tacit/minix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
acfb8ad154
minix/docs/doxygen_html/html/graph_legend.html
google-labs-jules[bot] acfb8ad154 feat: Dev tools, advanced spinlocks, IPC KASSERTs, docs & quality 
This commit delivers a comprehensive set of updates including development
environment setup, advanced spinlock features, initial IPC robustness
KASSERTs, extensive Doxygen commenting, code formatting, and Doxygen setup.

Key Changes:

Part 0: Development Environment Setup
- Created `setup.sh` to automate installation of `doxygen`, `graphviz`,
  `clang-format`, and `cppcheck`. (Tools were installed in the environment).

Part 1: Advanced Spinlock Features
- Enhanced `simple_spin_lock()` in `kernel/k_spinlock.h` with:
    - Adaptive spinning: `MAX_SPIN_THRESHOLD` and a stubbed `kernel_yield()`
      (calling `arch_pause()`).
    - Contention statistics: `acquisitions` and `contentions` counters
      added to `simple_spinlock_t` and integrated into lock functions.
- Added extensive Doxygen and inline comments for all spinlock code.
- Updated `docs/Signal_Refactoring_Verification.md` with these features.

Part 2: Initial IPC Robustness Analysis & KASSERTs
- Implemented an initial set of KASSERTs in `kernel/system.c` (in
  `kernel_call`, `kernel_call_dispatch`, `kernel_call_finish`) for
  validating IPC message parameters, call numbers, privileges, and
  internal states.
- Added Doxygen/inline comments to these IPC functions.
- Created `docs/IPC_Robustness_Analysis.md` documenting these KASSERTs
  and areas for further IPC validation.

Part 3: Code Formatting, Doxygen Setup & Review
- Code Formatting: Applied `clang-format --style=Google` to all C/H
  files modified in recent KASSERT and spinlock work.
- Static Analysis: Ran `cppcheck`; no critical issues found in recent
  changes requiring immediate code modification.
- Doxygen Setup: Created `docs/Doxyfile.kernel` with a comprehensive,
  C23-aware configuration based on your feedback. This file enables
  generation of extensive kernel documentation.
- `docs/Lock_Ordering.md`: Reviewed; no updates needed in this pass.

This work significantly improves kernel robustness, developer tooling,
code quality, and documentation infrastructure.
2025-06-08 00:40:50 +00:00

142 lines
7.1 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MINIX Kernel Documentation: Graph Legend</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">MINIX Kernel Documentation
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">Graph Legend</div></div>
</div><!--header-->
<div class="contents">
<p>This page explains how to interpret the graphs that are generated by doxygen.</p>
<p>Consider the following example: </p><div class="fragment"><div class="line"><span class="comment">/*! Invisible class because of truncation */</span></div>
<div class="line"><span class="keyword">class </span>Invisible { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Truncated class, inheritance relation is hidden */</span></div>
<div class="line"><span class="keyword">class </span>Truncated : <span class="keyword">public</span> Invisible { };</div>
<div class="line"> </div>
<div class="line"><span class="comment">/* Class not documented with doxygen comments */</span></div>
<div class="line"><span class="keyword">class </span>Undocumented { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Class that is inherited using public inheritance */</span></div>
<div class="line"><span class="keyword">class </span>PublicBase : <span class="keyword">public</span> Truncated { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! A template class */</span></div>
<div class="line"><span class="keyword">template</span>&lt;<span class="keyword">class</span> T&gt; <span class="keyword">class </span>Templ { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Class that is inherited using protected inheritance */</span></div>
<div class="line"><span class="keyword">class </span>ProtectedBase { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Class that is inherited using private inheritance */</span></div>
<div class="line"><span class="keyword">class </span>PrivateBase { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Class that is used by the Inherited class */</span></div>
<div class="line"><span class="keyword">class </span>Used { };</div>
<div class="line"><span class="comment"></span> </div>
<div class="line"><span class="comment">/*! Super class that inherits a number of other classes */</span></div>
<div class="line"><span class="keyword">class </span>Inherited : <span class="keyword">public</span> PublicBase,</div>
<div class="line"> <span class="keyword">protected</span> ProtectedBase,</div>
<div class="line"> <span class="keyword">private</span> PrivateBase,</div>
<div class="line"> <span class="keyword">public</span> Undocumented,</div>
<div class="line"> <span class="keyword">public</span> Templ&lt;int&gt;</div>
<div class="line">{</div>
<div class="line"> <span class="keyword">private</span>:</div>
<div class="line"> Used *m_usedClass;</div>
<div class="line">};</div>
</div><!-- fragment --><p> This will result in the following graph:</p>
<center><img src="graph_legend.png" alt="" class="inline"/></center><p>The boxes in the above graph have the following meaning: </p>
<ul>
<li>
A filled gray box represents the struct or class for which the graph is generated. </li>
<li>
A box with a black border denotes a documented struct or class. </li>
<li>
A box with a gray border denotes an undocumented struct or class. </li>
<li>
A box with a red border denotes a documented struct or class forwhich not all inheritance/containment relations are shown. A graph is truncated if it does not fit within the specified boundaries. </li>
</ul>
<p>The arrows have the following meaning: </p>
<ul>
<li>
A blue arrow is used to visualize a public inheritance relation between two classes. </li>
<li>
A dark green arrow is used for protected inheritance. </li>
<li>
A dark red arrow is used for private inheritance. </li>
<li>
A purple dashed arrow is used if a class is contained or used by another class. The arrow is labelled with the variable(s) through which the pointed class or struct is accessible. </li>
<li>
A yellow dashed arrow denotes a relation between a template instance and the template class it was instantiated from. The arrow is labelled with the template parameters of the instance. </li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink