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.
140 lines
9.9 KiB
TeX
140 lines
9.9 KiB
TeX
\doxysection{minix/kernel/k\+\_\+spinlock.h File Reference}
|
|
\hypertarget{k__spinlock_8h}{}\label{k__spinlock_8h}\index{minix/kernel/k\_spinlock.h@{minix/kernel/k\_spinlock.h}}
|
|
|
|
|
|
Defines a simple, non-\/recursive spinlock using GCC atomic builtins.
|
|
|
|
|
|
{\ttfamily \#include $<$minix/sys\+\_\+config.\+h$>$}\newline
|
|
Include dependency graph for k\+\_\+spinlock.\+h\+:
|
|
\nopagebreak
|
|
\begin{figure}[H]
|
|
\begin{center}
|
|
\leavevmode
|
|
\includegraphics[width=221pt]{k__spinlock_8h__incl}
|
|
\end{center}
|
|
\end{figure}
|
|
\doxysubsubsection*{Classes}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
struct \mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}}
|
|
\begin{DoxyCompactList}\small\item\em Structure representing a simple spinlock. \end{DoxyCompactList}\end{DoxyCompactItemize}
|
|
\doxysubsubsection*{Macros}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
\#define \mbox{\hyperlink{k__spinlock_8h_ab64669b95d563f14428a1f073106ef04}{MAX\+\_\+\+SPIN\+\_\+\+THRESHOLD}}~100000
|
|
\begin{DoxyCompactList}\small\item\em Maximum number of spin iterations before attempting to yield. \end{DoxyCompactList}\item
|
|
\#define \mbox{\hyperlink{k__spinlock_8h_ab7e692108b27a8b15089a297b451f293}{KERNEL\+\_\+\+YIELD\+\_\+\+DEFINED}}
|
|
\end{DoxyCompactItemize}
|
|
\doxysubsubsection*{Functions}
|
|
\begin{DoxyCompactItemize}
|
|
\item
|
|
static void \mbox{\hyperlink{k__spinlock_8h_a79887c626e823a36834e349fb75c539c}{arch\+\_\+pause}} (void)
|
|
\begin{DoxyCompactList}\small\item\em Placeholder for arch\+\_\+pause on non-\/x86 architectures. \end{DoxyCompactList}\item
|
|
static void \mbox{\hyperlink{k__spinlock_8h_a3b96827abeb83529b5d946e2654231ed}{kernel\+\_\+yield}} (void)
|
|
\begin{DoxyCompactList}\small\item\em Yields the CPU, typically to the scheduler. (Stub Implementation) \end{DoxyCompactList}\item
|
|
static void \mbox{\hyperlink{k__spinlock_8h_a614711109a66b779e92036c573e57002}{simple\+\_\+spin\+\_\+init}} (\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}lock)
|
|
\begin{DoxyCompactList}\small\item\em Initializes a spinlock to the unlocked state and resets statistics. \end{DoxyCompactList}\item
|
|
static void \mbox{\hyperlink{k__spinlock_8h_a8e8fd03b0cdf6f309bde43577c3dd548}{simple\+\_\+spin\+\_\+lock}} (\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}lock)
|
|
\begin{DoxyCompactList}\small\item\em Acquires a spinlock, busy-\/waiting if necessary. \end{DoxyCompactList}\item
|
|
static void \mbox{\hyperlink{k__spinlock_8h_ad62d430c4e62aaa0d945088f5e1adc32}{simple\+\_\+spin\+\_\+unlock}} (\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}lock)
|
|
\begin{DoxyCompactList}\small\item\em Releases a previously acquired spinlock. \end{DoxyCompactList}\end{DoxyCompactItemize}
|
|
|
|
|
|
\doxysubsection{Detailed Description}
|
|
Defines a simple, non-\/recursive spinlock using GCC atomic builtins.
|
|
|
|
This header provides a basic spinlock implementation suitable for short critical sections, particularly in contexts where sleeping is not permissible (e.\+g., some interrupt handlers or core kernel code before schedulers are fully active). It is designed with SMP considerations, relying on GCC\textquotesingle{}s atomic builtins which typically ensure full memory barriers for sequential consistency. Includes adaptive spinning using {\ttfamily \doxylink{k__spinlock_8h_a79887c626e823a36834e349fb75c539c}{arch\+\_\+pause()}} for supported architectures.
|
|
|
|
\doxysubsection{Macro Definition Documentation}
|
|
\Hypertarget{k__spinlock_8h_ab7e692108b27a8b15089a297b451f293}\label{k__spinlock_8h_ab7e692108b27a8b15089a297b451f293}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!KERNEL\_YIELD\_DEFINED@{KERNEL\_YIELD\_DEFINED}}
|
|
\index{KERNEL\_YIELD\_DEFINED@{KERNEL\_YIELD\_DEFINED}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{KERNEL\_YIELD\_DEFINED}{KERNEL\_YIELD\_DEFINED}}
|
|
{\footnotesize\ttfamily \#define KERNEL\+\_\+\+YIELD\+\_\+\+DEFINED}
|
|
|
|
\Hypertarget{k__spinlock_8h_ab64669b95d563f14428a1f073106ef04}\label{k__spinlock_8h_ab64669b95d563f14428a1f073106ef04}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!MAX\_SPIN\_THRESHOLD@{MAX\_SPIN\_THRESHOLD}}
|
|
\index{MAX\_SPIN\_THRESHOLD@{MAX\_SPIN\_THRESHOLD}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{MAX\_SPIN\_THRESHOLD}{MAX\_SPIN\_THRESHOLD}}
|
|
{\footnotesize\ttfamily \#define MAX\+\_\+\+SPIN\+\_\+\+THRESHOLD~100000}
|
|
|
|
|
|
|
|
Maximum number of spin iterations before attempting to yield.
|
|
|
|
This threshold is used in {\ttfamily simple\+\_\+spin\+\_\+lock} to prevent a CPU from monopolizing resources by spinning indefinitely on a highly contended lock. After this many spins in the inner loop, {\ttfamily \doxylink{k__spinlock_8h_a3b96827abeb83529b5d946e2654231ed}{kernel\+\_\+yield()}} is called. The value should be tuned based on system characteristics and expected contention levels.
|
|
|
|
\doxysubsection{Function Documentation}
|
|
\Hypertarget{k__spinlock_8h_a79887c626e823a36834e349fb75c539c}\label{k__spinlock_8h_a79887c626e823a36834e349fb75c539c}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!arch\_pause@{arch\_pause}}
|
|
\index{arch\_pause@{arch\_pause}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{arch\_pause()}{arch\_pause()}}
|
|
{\footnotesize\ttfamily static void arch\+\_\+pause (\begin{DoxyParamCaption}\item[{void}]{ }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}
|
|
|
|
|
|
|
|
Placeholder for arch\+\_\+pause on non-\/x86 architectures.
|
|
|
|
For architectures other than i386/x86\+\_\+64, this function currently acts as a no-\/op. It can be defined with architecture-\/specific pause/yield instructions if available to improve spin-\/wait loop performance. \Hypertarget{k__spinlock_8h_a3b96827abeb83529b5d946e2654231ed}\label{k__spinlock_8h_a3b96827abeb83529b5d946e2654231ed}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!kernel\_yield@{kernel\_yield}}
|
|
\index{kernel\_yield@{kernel\_yield}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{kernel\_yield()}{kernel\_yield()}}
|
|
{\footnotesize\ttfamily static void kernel\+\_\+yield (\begin{DoxyParamCaption}\item[{void}]{ }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}
|
|
|
|
|
|
|
|
Yields the CPU, typically to the scheduler. (Stub Implementation)
|
|
|
|
This function is called when a spinlock has been spinning for too long (exceeding MAX\+\_\+\+SPIN\+\_\+\+THRESHOLD), as a mechanism to prevent CPU monopolization and allow other threads/processes to run.
|
|
|
|
\begin{DoxyNote}{Note}
|
|
This is a stub implementation. A full implementation would typically involve interacting with the system scheduler to relinquish the CPU. For now, it at least performs an {\ttfamily \doxylink{k__spinlock_8h_a79887c626e823a36834e349fb75c539c}{arch\+\_\+pause()}} to reduce contention. A real implementation might call something like {\ttfamily sched\+\_\+yield()} or {\ttfamily yield()}.
|
|
\end{DoxyNote}
|
|
\Hypertarget{k__spinlock_8h_a614711109a66b779e92036c573e57002}\label{k__spinlock_8h_a614711109a66b779e92036c573e57002}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!simple\_spin\_init@{simple\_spin\_init}}
|
|
\index{simple\_spin\_init@{simple\_spin\_init}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{simple\_spin\_init()}{simple\_spin\_init()}}
|
|
{\footnotesize\ttfamily static void simple\+\_\+spin\+\_\+init (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}}]{lock }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}
|
|
|
|
|
|
|
|
Initializes a spinlock to the unlocked state and resets statistics.
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em lock} & Pointer to the \doxylink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t} to initialize.\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
This function must be called before the spinlock is used for the first time. It sets the lock state to 0 (unlocked) and initializes statistics counters to zero. \Hypertarget{k__spinlock_8h_a8e8fd03b0cdf6f309bde43577c3dd548}\label{k__spinlock_8h_a8e8fd03b0cdf6f309bde43577c3dd548}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!simple\_spin\_lock@{simple\_spin\_lock}}
|
|
\index{simple\_spin\_lock@{simple\_spin\_lock}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{simple\_spin\_lock()}{simple\_spin\_lock()}}
|
|
{\footnotesize\ttfamily static void simple\+\_\+spin\+\_\+lock (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}}]{lock }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}
|
|
|
|
|
|
|
|
Acquires a spinlock, busy-\/waiting if necessary.
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em lock} & Pointer to the \doxylink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t} to acquire.\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
This function attempts to acquire the lock. If the lock is already held, it will spin (busy-\/wait) until the lock becomes available. This function is non-\/recursive; a thread attempting to acquire a lock it already holds will deadlock. Includes a spin counter and calls {\ttfamily \doxylink{k__spinlock_8h_a3b96827abeb83529b5d946e2654231ed}{kernel\+\_\+yield()}} if spinning excessively. Also updates lock acquisition and contention statistics. \Hypertarget{k__spinlock_8h_ad62d430c4e62aaa0d945088f5e1adc32}\label{k__spinlock_8h_ad62d430c4e62aaa0d945088f5e1adc32}
|
|
\index{k\_spinlock.h@{k\_spinlock.h}!simple\_spin\_unlock@{simple\_spin\_unlock}}
|
|
\index{simple\_spin\_unlock@{simple\_spin\_unlock}!k\_spinlock.h@{k\_spinlock.h}}
|
|
\doxysubsubsection{\texorpdfstring{simple\_spin\_unlock()}{simple\_spin\_unlock()}}
|
|
{\footnotesize\ttfamily static void simple\+\_\+spin\+\_\+unlock (\begin{DoxyParamCaption}\item[{\mbox{\hyperlink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t}} \texorpdfstring{$\ast$}{*}}]{lock }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}, {\ttfamily [static]}}
|
|
|
|
|
|
|
|
Releases a previously acquired spinlock.
|
|
|
|
|
|
\begin{DoxyParams}{Parameters}
|
|
{\em lock} & Pointer to the \doxylink{structsimple__spinlock__t}{simple\+\_\+spinlock\+\_\+t} to release.\\
|
|
\hline
|
|
\end{DoxyParams}
|
|
This function releases the lock, allowing another thread to acquire it. It must only be called by the thread that currently holds the lock.
|