acfb8ad154
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.
159 lines
7.9 KiB
HTML
159 lines
7.9 KiB
HTML
<!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: simple_spinlock_t Struct Reference</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&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&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
<!-- 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><!-- top -->
|
|
<div class="header">
|
|
<div class="summary">
|
|
<a href="#pub-attribs">Public Attributes</a> |
|
|
<a href="structsimple__spinlock__t-members.html">List of all members</a> </div>
|
|
<div class="headertitle"><div class="title">simple_spinlock_t Struct Reference</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
|
|
<p>Structure representing a simple spinlock.
|
|
<a href="structsimple__spinlock__t.html#details">More...</a></p>
|
|
|
|
<p><code>#include <<a class="el" href="k__spinlock_8h_source.html">k_spinlock.h</a>></code></p>
|
|
<table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-attribs" name="pub-attribs"></a>
|
|
Public Attributes</h2></td></tr>
|
|
<tr class="memitem:ae8d529ab0ac1b69010d98ef8336e9172" id="r_ae8d529ab0ac1b69010d98ef8336e9172"><td class="memItemLeft" align="right" valign="top">volatile int </td><td class="memItemRight" valign="bottom"><a class="el" href="structsimple__spinlock__t.html#ae8d529ab0ac1b69010d98ef8336e9172">locked</a></td></tr>
|
|
<tr class="memdesc:ae8d529ab0ac1b69010d98ef8336e9172"><td class="mdescLeft"> </td><td class="mdescRight">The lock state. 0 for unlocked, 1 for locked. <br /></td></tr>
|
|
<tr class="separator:ae8d529ab0ac1b69010d98ef8336e9172"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a849f8cded125ee7192052ca71e67f390" id="r_a849f8cded125ee7192052ca71e67f390"><td class="memItemLeft" align="right" valign="top">unsigned long </td><td class="memItemRight" valign="bottom"><a class="el" href="structsimple__spinlock__t.html#a849f8cded125ee7192052ca71e67f390">acquisitions</a></td></tr>
|
|
<tr class="memdesc:a849f8cded125ee7192052ca71e67f390"><td class="mdescLeft"> </td><td class="mdescRight">Number of times the lock was successfully acquired. <br /></td></tr>
|
|
<tr class="separator:a849f8cded125ee7192052ca71e67f390"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a7c66988c5d374d8eaf3b522a1ed7d041" id="r_a7c66988c5d374d8eaf3b522a1ed7d041"><td class="memItemLeft" align="right" valign="top">unsigned long </td><td class="memItemRight" valign="bottom"><a class="el" href="structsimple__spinlock__t.html#a7c66988c5d374d8eaf3b522a1ed7d041">contentions</a></td></tr>
|
|
<tr class="memdesc:a7c66988c5d374d8eaf3b522a1ed7d041"><td class="mdescLeft"> </td><td class="mdescRight">Number of times a thread tried to acquire the lock but found it already held, thus entering a spin-wait loop. This indicates contention. <br /></td></tr>
|
|
<tr class="separator:a7c66988c5d374d8eaf3b522a1ed7d041"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<div class="textblock"><p>Structure representing a simple spinlock. </p>
|
|
<p>The spinlock's state is determined by the <code>locked</code> member. It also includes basic statistics for acquisitions and contentions. It is crucial that operations on this structure use the provided <code>simple_spin_*</code> functions to ensure atomicity and correct memory ordering. </p>
|
|
</div><h2 class="groupheader">Member Data Documentation</h2>
|
|
<a id="a849f8cded125ee7192052ca71e67f390" name="a849f8cded125ee7192052ca71e67f390"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a849f8cded125ee7192052ca71e67f390">◆ </a></span>acquisitions</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">unsigned long simple_spinlock_t::acquisitions</td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Number of times the lock was successfully acquired. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="a7c66988c5d374d8eaf3b522a1ed7d041" name="a7c66988c5d374d8eaf3b522a1ed7d041"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#a7c66988c5d374d8eaf3b522a1ed7d041">◆ </a></span>contentions</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">unsigned long simple_spinlock_t::contentions</td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Number of times a thread tried to acquire the lock but found it already held, thus entering a spin-wait loop. This indicates contention. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ae8d529ab0ac1b69010d98ef8336e9172" name="ae8d529ab0ac1b69010d98ef8336e9172"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ae8d529ab0ac1b69010d98ef8336e9172">◆ </a></span>locked</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">volatile int simple_spinlock_t::locked</td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>The lock state. 0 for unlocked, 1 for locked. </p>
|
|
<p><code>volatile</code> ensures that the compiler does not optimize away reads of this variable, as its value can change unexpectedly due to actions from other CPUs or threads. The atomicity of lock operations is guaranteed by GCC's <code>__sync_*</code> builtins, not by <code>volatile</code> itself. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<hr/>The documentation for this struct was generated from the following file:<ul>
|
|
<li>minix/kernel/<a class="el" href="k__spinlock_8h_source.html">k_spinlock.h</a></li>
|
|
</ul>
|
|
</div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <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>
|