From cad626fa9792abb74b861c6d0c1444d58188c002 Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Fri, 1 Aug 2025 10:34:07 +0100 Subject: feat: tex: add binary_mutex document. Signed-off-by: Amlal El Mahrouss --- docs/tex/binary_mutex.tex | 65 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/tex/binary_mutex.tex (limited to 'docs') diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex new file mode 100644 index 00000000..5902cefc --- /dev/null +++ b/docs/tex/binary_mutex.tex @@ -0,0 +1,65 @@ +\documentclass{article} +\usepackage{graphicx} % Required for inserting images + +\title{The BinaryMutex Pattern} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Context} + +The BinaryMutex is a core component of NeKernel (NeKernel/VMKernel) based systems. + +The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold. + +Thus the acquiree is the USER\_PROCESS itself + +\section{Use Cases} + +\begin{verbatim} +BinaryMutex mux; +mux.Lock(process); + +// Say we want to interact with the process itself on this thread, +we can then make sure that no race condition happens by using: +constexpr auto kSecondsMax = 5; +mux.WaitForProcess(kSecondsMax); +\end{verbatim} + +\section{Implementation} + +The source implementation consists of: + +\begin{verbatim} +class BinaryMutex final { + public: + explicit BinaryMutex() = default; + ~BinaryMutex() = default; + + public: + bool IsLocked() const; + bool Unlock() noexcept; + + public: + BOOL WaitForProcess(const UInt32& sec) noexcept; + + public: + bool Lock(USER_PROCESS* process); + bool LockOrWait(USER_PROCESS* process, TimerInterface* timer); + + public: + NE_COPY_DEFAULT(BinaryMutex) + + private: + USER_PROCESS* fLockingProcess; +}; +\end{verbatim} + +\section{Conclusion} + +This pattern is useful for systems that need to make sure that a process isn't tampered by concurrent usages. Thus its existence in VMKernel and NeKernel. + +\end{document} -- cgit v1.2.3 From 01a31ff876b0b33eec412a2cc5778aad7af7c334 Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Sat, 2 Aug 2025 08:43:04 +0100 Subject: feat: add more documentation (CPS architecture) Signed-off-by: Amlal El Mahrouss --- docs/tex/cps_arch.tex | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/tex/cps_arch.tex (limited to 'docs') diff --git a/docs/tex/cps_arch.tex b/docs/tex/cps_arch.tex new file mode 100644 index 00000000..328a0f1b --- /dev/null +++ b/docs/tex/cps_arch.tex @@ -0,0 +1,81 @@ +\documentclass{article} +\usepackage{graphicx} % Required for inserting images +\usepackage{hyperref} + +\title{The CoreProcessScheduler (CPS) architecture} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Introduction} + +{The CoreProcessScheduler is a concept of NeKernel based systems governs how the scheduling backend, and policy of the kernel works, it is the common gateway for schedulers inside NeKernel.} + +\section{Overview} + +{The CoreProcessScheduler (now referred as CPS) serves as the intermediate foundal between the scheduler backend and kernel.} {It takes care of process life-cycle management, team-based process grouping, and affinity-based CPU based allocation to mention the least.} + +\section{The Affinity System} + +{Processes are given CPU time affinity hints using an affinity kind type, these hints help the scheduler run or adjust the current process.} + +\subsection{Sample Code} + +{The following sample is C++ code.} {The smaller the value, the more critical the process.} + +\begin{verbatim} +enum class AffinityKind : Int32 { + kRealTime = 100, + kVeryHigh = 150, + kHigh = 200, + kStandard = 1000, + kLowUsage = 1500, + kVeryLowUsage = 2000, +}; +\end{verbatim} + +\section{The Team System} + +{The team container has process metadata for the backend to run on. It holds methods and fields for backend specific operations.} {One implementation of such team is the UserProcessTeam object inside NeKernel.} + +\subsection{Sample Code} + +{The following sample is C++ code.} {This is the UserProcessTeam from NeKernel} + +\begin{verbatim} +class UserProcessTeam final { + public: + explicit UserProcessTeam(); + ~UserProcessTeam() = default; + + NE_COPY_DEFAULT(UserProcessTeam) + + Array& AsArray(); + Ref& AsRef(); + ProcessID& Id() noexcept; + + public: + USER_PROCESS_ARRAY mProcessList; + USER_PROCESS_REF mCurrentProcess; + ProcessID mTeamId{0}; + ProcessID mProcessCur{0}; +}; + +\end{verbatim} + +\section{Conclusion} + +{Meanwhile the scheduler backend (such as the UserProcessScheduler) takes care of user process scheduling and fairness, the CPS architecture itself is the foundation for those systems (such as KernelTaskScheduler, or HardwareThreadScheduler)} + +\section{Links} + +{NeKernel.org}: \href{https://nekernel.org}{NeKernel.org} +\newline +{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} +\newline +{SNU Systems}: \href{https://snu.systems}{SNU.Systems} + +\end{document} -- cgit v1.2.3 From 9c07b4640a226f8070d4de0f8cd8f119d7754aa8 Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Sun, 3 Aug 2025 10:03:55 +0100 Subject: feat: update papers. Signed-off-by: Amlal El Mahrouss --- docs/tex/binary_mutex.tex | 16 ++--- docs/tex/coreprocessscheduler.tex | 139 ++++++++++++++++++++++++++++++++++++++ docs/tex/cps_arch.tex | 81 ---------------------- 3 files changed, 146 insertions(+), 90 deletions(-) create mode 100644 docs/tex/coreprocessscheduler.tex delete mode 100644 docs/tex/cps_arch.tex (limited to 'docs') diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex index 5902cefc..4e61eb65 100644 --- a/docs/tex/binary_mutex.tex +++ b/docs/tex/binary_mutex.tex @@ -1,7 +1,7 @@ \documentclass{article} \usepackage{graphicx} % Required for inserting images -\title{The BinaryMutex Pattern} +\title{BinaryMutex} \author{Amlal El Mahrouss} \date{\today} @@ -9,15 +9,11 @@ \maketitle -\section{Context} +\section{Abstract} -The BinaryMutex is a core component of NeKernel (NeKernel/VMKernel) based systems. +{The BinaryMutex is a core component of NeKernel (NeKernel/VMKernel) based systems. The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold. Thus the acquiree is the USER\_PROCESS itself} -The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold. - -Thus the acquiree is the USER\_PROCESS itself - -\section{Use Cases} +\section{Use Case \#1: Process lock for atomic data retrival} \begin{verbatim} BinaryMutex mux; @@ -26,7 +22,9 @@ mux.Lock(process); // Say we want to interact with the process itself on this thread, we can then make sure that no race condition happens by using: constexpr auto kSecondsMax = 5; -mux.WaitForProcess(kSecondsMax); +mux.WaitForProcess(kSecondsMax); + +process.DoFoo(); \end{verbatim} \section{Implementation} diff --git a/docs/tex/coreprocessscheduler.tex b/docs/tex/coreprocessscheduler.tex new file mode 100644 index 00000000..60f2b8cd --- /dev/null +++ b/docs/tex/coreprocessscheduler.tex @@ -0,0 +1,139 @@ +\documentclass{article} +\usepackage{graphicx} % Required for inserting images +\usepackage{hyperref} + +\title{CoreProcessScheduler} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Abstract} + +{The CoreProcessScheduler governs how the scheduling backend and policy of the kernel works, It is the common gateway for schedulers inside NeKernel based systems.} + +\section{Overview} + +{The CoreProcessScheduler (now referred as CPS) serves as the intermediate foundal between the scheduler backend and kernel.} {It takes care of process life-cycle management, team-based process grouping, and affinity-based CPU based allocation to mention the least.} + +\section{The Affinity System} + +{Processes are given CPU time affinity hints using an affinity kind type, these hints help the scheduler run or adjust the current process.} + +\subsection{Sample Code \#1} + +{The following sample is C++ code.} {The smaller the value, the more critical the process.} + +\begin{verbatim} +enum class AffinityKind : Int32 { + kRealTime = 100, + kVeryHigh = 150, + kHigh = 200, + kStandard = 1000, + kLowUsage = 1500, + kVeryLowUsage = 2000, +}; +\end{verbatim} + +\section{The Team System} + +{The team system holds process metadata for the backend scheduler to run on. It holds methods and fields for backend specific operations.} {One implementation of such team is the UserProcessTeam object inside NeKernel.} + +\subsection{Sample Code \#2} + +{The following sample is used to hold team metadata.} {This is part of the NeKernel source tree.} + +\begin{verbatim} +class UserProcessTeam final { + public: + explicit UserProcessTeam(); + ~UserProcessTeam() = default; + + NE_COPY_DEFAULT(UserProcessTeam) + + Array& AsArray(); + Ref& AsRef(); + ProcessID& Id() noexcept; + + public: + USER_PROCESS_ARRAY mProcessList; + USER_PROCESS_REF mCurrentProcess; + ProcessID mTeamId{0}; + ProcessID mProcessCur{0}; +}; + +\end{verbatim} + +\section{The Process Image System} + +{The process image container is a design pattern made to contain process data and metadata, its purpose comes from the lack of mainstream operating systems of such ability to hold metadata.} + +\newline{} + +{This approach helps separate concerns and give modularity to the system, as the image and process structure are not mixed together.} + +\subsection{Sample Code \#3} + +{The following sample is a C++ container used to hold process data and metadata.} {This is part of the NeKernel source tree.} + +\begin{verbatim} +struct PROCESS_IMAGE final { + explicit PROCESS_IMAGE() = default; + + private: + friend USER_PROCESS; + friend KERNEL_TASK; + + friend class UserProcessScheduler; + + ImagePtr fCode; + ImagePtr fBlob; + + public: + Bool HasCode() const { return this->fCode != nullptr; } + + Bool HasImage() const { return this->fBlob != nullptr; } + + ErrorOr LeakImage() { + if (this->fCode) { + return ErrorOr{this->fCode}; + } + + return ErrorOr{kErrorInvalidData}; + } + + ErrorOr LeakBlob() { + if (this->fBlob) { + return ErrorOr{this->fBlob}; + } + + return ErrorOr{kErrorInvalidData}; + } +}; + +\end{verbatim} + +\section{Conclusion} + +{The CoreProcessScheduler is a piece of systems design with robust design and useful cases, although useful in desktop/server cases, It may not be suited for every other tasks.} + +{And while one scheduler backend (such as the UserProcessScheduler) takes care of user process scheduling and fairness, the CoreProcessScheduler takes care of the foundation for those systems.} + +\section{References} + +{Here are the reference material on this paper:} + +{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} + +{CoreProcessScheduler}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/CoreProcessScheduler.h}{CoreProcessScheduler} + +\section{Hyperlinks} + +{NeKernel.org}: \href{https://nekernel.org}{NeKernel.org} +\newline +\newline +{SNU Systems}: \href{https://snu.systems}{SNU.Systems} + +\end{document} diff --git a/docs/tex/cps_arch.tex b/docs/tex/cps_arch.tex deleted file mode 100644 index 328a0f1b..00000000 --- a/docs/tex/cps_arch.tex +++ /dev/null @@ -1,81 +0,0 @@ -\documentclass{article} -\usepackage{graphicx} % Required for inserting images -\usepackage{hyperref} - -\title{The CoreProcessScheduler (CPS) architecture} -\author{Amlal El Mahrouss} -\date{\today} - -\begin{document} - -\maketitle - -\section{Introduction} - -{The CoreProcessScheduler is a concept of NeKernel based systems governs how the scheduling backend, and policy of the kernel works, it is the common gateway for schedulers inside NeKernel.} - -\section{Overview} - -{The CoreProcessScheduler (now referred as CPS) serves as the intermediate foundal between the scheduler backend and kernel.} {It takes care of process life-cycle management, team-based process grouping, and affinity-based CPU based allocation to mention the least.} - -\section{The Affinity System} - -{Processes are given CPU time affinity hints using an affinity kind type, these hints help the scheduler run or adjust the current process.} - -\subsection{Sample Code} - -{The following sample is C++ code.} {The smaller the value, the more critical the process.} - -\begin{verbatim} -enum class AffinityKind : Int32 { - kRealTime = 100, - kVeryHigh = 150, - kHigh = 200, - kStandard = 1000, - kLowUsage = 1500, - kVeryLowUsage = 2000, -}; -\end{verbatim} - -\section{The Team System} - -{The team container has process metadata for the backend to run on. It holds methods and fields for backend specific operations.} {One implementation of such team is the UserProcessTeam object inside NeKernel.} - -\subsection{Sample Code} - -{The following sample is C++ code.} {This is the UserProcessTeam from NeKernel} - -\begin{verbatim} -class UserProcessTeam final { - public: - explicit UserProcessTeam(); - ~UserProcessTeam() = default; - - NE_COPY_DEFAULT(UserProcessTeam) - - Array& AsArray(); - Ref& AsRef(); - ProcessID& Id() noexcept; - - public: - USER_PROCESS_ARRAY mProcessList; - USER_PROCESS_REF mCurrentProcess; - ProcessID mTeamId{0}; - ProcessID mProcessCur{0}; -}; - -\end{verbatim} - -\section{Conclusion} - -{Meanwhile the scheduler backend (such as the UserProcessScheduler) takes care of user process scheduling and fairness, the CPS architecture itself is the foundation for those systems (such as KernelTaskScheduler, or HardwareThreadScheduler)} - -\section{Links} - -{NeKernel.org}: \href{https://nekernel.org}{NeKernel.org} -\newline -{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} -\newline -{SNU Systems}: \href{https://snu.systems}{SNU.Systems} - -\end{document} -- cgit v1.2.3 From 34758487e7630244dcec71ebf3995675ac2d1c27 Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Sun, 3 Aug 2025 13:27:49 +0100 Subject: feat: LaTeX: update technical papers. feat: CPS: Assign image to nullptr in PROCESS_IMAGE container. Signed-off-by: Amlal El Mahrouss --- dev/kernel/KernelKit/CoreProcessScheduler.h | 11 ++++++----- docs/tex/NOTICE.md | 5 +++++ docs/tex/binary_mutex.tex | 2 +- docs/tex/coreprocessscheduler.tex | 13 +++---------- 4 files changed, 15 insertions(+), 16 deletions(-) create mode 100644 docs/tex/NOTICE.md (limited to 'docs') diff --git a/dev/kernel/KernelKit/CoreProcessScheduler.h b/dev/kernel/KernelKit/CoreProcessScheduler.h index 170244eb..b92d7393 100644 --- a/dev/kernel/KernelKit/CoreProcessScheduler.h +++ b/dev/kernel/KernelKit/CoreProcessScheduler.h @@ -90,6 +90,7 @@ struct PROCESS_FILE_TREE { struct PROCESS_FILE_TREE* Parent { nullptr }; + struct PROCESS_FILE_TREE* Child { nullptr }; @@ -97,6 +98,7 @@ struct PROCESS_FILE_TREE { struct PROCESS_FILE_TREE* Prev { nullptr }; + struct PROCESS_FILE_TREE* Next { nullptr }; @@ -115,8 +117,6 @@ enum class ProcessSubsystem : Int32 { kProcessSubsystemCount = 4, }; -typedef UInt64 PTime; - /***********************************************************************************/ //! @brief Local Process identifier. /***********************************************************************************/ @@ -179,7 +179,8 @@ inline bool operator>=(AffinityKind lhs, AffinityKind rhs) { return lhs_int >= rhs_int; } -using ProcessTime = UInt64; +using PTime = UInt64; +using ProcessTime = PTime; using PID = Int64; /***********************************************************************************/ @@ -209,8 +210,8 @@ struct PROCESS_IMAGE final { friend class UserProcessScheduler; - ImagePtr fCode; - ImagePtr fBlob; + ImagePtr fCode{}; + ImagePtr fBlob{}; public: Bool HasCode() const { return this->fCode != nullptr; } diff --git a/docs/tex/NOTICE.md b/docs/tex/NOTICE.md new file mode 100644 index 00000000..5d6eb03f --- /dev/null +++ b/docs/tex/NOTICE.md @@ -0,0 +1,5 @@ +# Notice for LaTeX documents. + +## Recommended Tool + +`pdflatex` is recommended for this matter, although you are free to use other tools. diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex index 4e61eb65..cc5a7d3c 100644 --- a/docs/tex/binary_mutex.tex +++ b/docs/tex/binary_mutex.tex @@ -1,7 +1,7 @@ \documentclass{article} \usepackage{graphicx} % Required for inserting images -\title{BinaryMutex} +\title{BinaryMutex: Technical Documentation} \author{Amlal El Mahrouss} \date{\today} diff --git a/docs/tex/coreprocessscheduler.tex b/docs/tex/coreprocessscheduler.tex index 60f2b8cd..dd3594b1 100644 --- a/docs/tex/coreprocessscheduler.tex +++ b/docs/tex/coreprocessscheduler.tex @@ -2,7 +2,7 @@ \usepackage{graphicx} % Required for inserting images \usepackage{hyperref} -\title{CoreProcessScheduler} +\title{CoreProcessScheduler: Technical Documentation} \author{Amlal El Mahrouss} \date{\today} @@ -70,7 +70,7 @@ class UserProcessTeam final { {The process image container is a design pattern made to contain process data and metadata, its purpose comes from the lack of mainstream operating systems of such ability to hold metadata.} -\newline{} +\newline {This approach helps separate concerns and give modularity to the system, as the image and process structure are not mixed together.} @@ -123,17 +123,10 @@ struct PROCESS_IMAGE final { \section{References} -{Here are the reference material on this paper:} +{Here are the reference mentioned on this paper:} {NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} {CoreProcessScheduler}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/CoreProcessScheduler.h}{CoreProcessScheduler} -\section{Hyperlinks} - -{NeKernel.org}: \href{https://nekernel.org}{NeKernel.org} -\newline -\newline -{SNU Systems}: \href{https://snu.systems}{SNU.Systems} - \end{document} -- cgit v1.2.3 From e29425af3c9ac47242856783f1c5e2fbaebc8de3 Mon Sep 17 00:00:00 2001 From: Amlal Date: Wed, 13 Aug 2025 03:22:05 +0200 Subject: feat: tex: new revision of tex specs. Signed-off-by: Amlal --- docs/tex/binary_mutex.tex | 21 ++++- docs/tex/core_process_scheduler.tex | 130 ++++++++++++++++++++++++++++ docs/tex/coreprocessscheduler.tex | 132 ----------------------------- docs/tex/mbci.tex | 117 ------------------------- docs/tex/mini_bus_controller_interface.tex | 117 +++++++++++++++++++++++++ 5 files changed, 264 insertions(+), 253 deletions(-) create mode 100644 docs/tex/core_process_scheduler.tex delete mode 100644 docs/tex/coreprocessscheduler.tex delete mode 100644 docs/tex/mbci.tex create mode 100644 docs/tex/mini_bus_controller_interface.tex (limited to 'docs') diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex index cc5a7d3c..564d322a 100644 --- a/docs/tex/binary_mutex.tex +++ b/docs/tex/binary_mutex.tex @@ -13,7 +13,9 @@ {The BinaryMutex is a core component of NeKernel (NeKernel/VMKernel) based systems. The pattern excludes other acquirers to own the USER\_PROCESS that is currently being hold. Thus the acquiree is the USER\_PROCESS itself} -\section{Use Case \#1: Process lock for atomic data retrival} +\section{Overview} + +{The BinaryMutex comes from the need to make sure that no race conditions occurs in kernel code. Most of those race conditions happens in process handling code. Thus the design of the BinaryMutex (which holds a process handle to it)} \begin{verbatim} BinaryMutex mux; @@ -22,14 +24,16 @@ mux.Lock(process); // Say we want to interact with the process itself on this thread, we can then make sure that no race condition happens by using: constexpr auto kSecondsMax = 5; -mux.WaitForProcess(kSecondsMax); +while (mux.WaitForProcess(kSecondsMax)); + +// finally do our task now. process.DoFoo(); \end{verbatim} \section{Implementation} -The source implementation consists of: +The source implementation consists of this simple C++ class: \begin{verbatim} class BinaryMutex final { @@ -58,6 +62,15 @@ class BinaryMutex final { \section{Conclusion} -This pattern is useful for systems that need to make sure that a process isn't tampered by concurrent usages. Thus its existence in VMKernel and NeKernel. +{This design pattern is useful for systems that need to make sure that a process isn't tampered by concurrent usages. +Thus its existence in VMKernel and NeKernel.} + +\section{References} + +{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} + +{VMKernel}: \href{https://snu.systems/specs/vmkernel}{VMKernel} + +{BinaryMutex}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/BinaryMutex.h}{BinaryMutex} \end{document} diff --git a/docs/tex/core_process_scheduler.tex b/docs/tex/core_process_scheduler.tex new file mode 100644 index 00000000..b99232bb --- /dev/null +++ b/docs/tex/core_process_scheduler.tex @@ -0,0 +1,130 @@ +\documentclass{article} +\usepackage{graphicx} +\usepackage{hyperref} + +\title{CoreProcessScheduler: Technical Documentation} +\author{Amlal El Mahrouss} +\date{\today} + +\begin{document} + +\maketitle + +\section{Abstract} + +{The CoreProcessScheduler governs how the scheduling backend and policy of the kernel works, It is the common gateway for schedulers inside NeKernel based systems.} + +\section{Overview} + +{The CoreProcessScheduler (now referred as CPS) serves as the intermediate foundal between the scheduler backend and kernel.} {It takes care of process life-cycle management, team-based process grouping, and affinity-based CPU based allocation to mention the least.} + +\section{The Affinity System} + +{Processes are given CPU time affinity hints using an affinity kind type, these hints help the scheduler run or adjust the current process.} + +\subsection{Sample Code \#1} + +{The following sample is C++ code.} {The smaller the value, the more critical the process.} + +\begin{verbatim} +enum class AffinityKind : Int32 { + kRealTime = 100, + kVeryHigh = 150, + kHigh = 200, + kStandard = 1000, + kLowUsage = 1500, + kVeryLowUsage = 2000, +}; +\end{verbatim} + +\section{The Team System} + +{The team system holds process metadata for the backend scheduler to run on. It holds methods and fields for backend specific operations.} {One implementation of such team is the UserProcessTeam object inside NeKernel.} + +\subsection{Sample Code \#2} + +{The following sample is used to hold team metadata.} {This is part of the NeKernel source tree.} + +\begin{verbatim} +class UserProcessTeam final { + public: + explicit UserProcessTeam(); + ~UserProcessTeam() = default; + + NE_COPY_DEFAULT(UserProcessTeam) + + Array& AsArray(); + Ref& AsRef(); + ProcessID& Id() noexcept; + + public: + USER_PROCESS_ARRAY mProcessList; + USER_PROCESS_REF mCurrentProcess; + ProcessID mTeamId{0}; + ProcessID mProcessCur{0}; +}; + +\end{verbatim} + +\section{The Process Image System} + +{The process image container is a design pattern made to contain process data and metadata, its purpose comes from the lack of mainstream operating systems of such ability to hold metadata.} + +{This approach helps separate concerns and give modularity to the system, as the image and process structure are not mixed together.} + +\subsection{Sample Code \#3} + +{The following sample is a C++ container used to hold process data and metadata.} {This is part of the NeKernel source tree.} + +\begin{verbatim} +struct PROCESS_IMAGE final { + explicit PROCESS_IMAGE() = default; + + private: + friend USER_PROCESS; + friend KERNEL_TASK; + + friend class UserProcessScheduler; + + ImagePtr fCode; + ImagePtr fBlob; + + public: + Bool HasCode() const { return this->fCode != nullptr; } + + Bool HasImage() const { return this->fBlob != nullptr; } + + ErrorOr LeakImage() { + if (this->fCode) { + return ErrorOr{this->fCode}; + } + + return ErrorOr{kErrorInvalidData}; + } + + ErrorOr LeakBlob() { + if (this->fBlob) { + return ErrorOr{this->fBlob}; + } + + return ErrorOr{kErrorInvalidData}; + } +}; + +\end{verbatim} + +\section{Conclusion} + +{The CoreProcessScheduler is a piece of systems design with robust design and useful cases, although useful in desktop/server cases, It may not be suited for every other tasks.} + +{And while one scheduler backend (such as the UserProcessScheduler) takes care of user process scheduling and fairness, the CoreProcessScheduler takes care of the foundation for those systems.} + +\section{References} + +{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} + +{VMKernel}: \href{https://snu.systems/specs/vmkernel}{VMKernel} + +{CoreProcessScheduler C++ Header}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/CoreProcessScheduler.h}{CoreProcessScheduler} + +\end{document} diff --git a/docs/tex/coreprocessscheduler.tex b/docs/tex/coreprocessscheduler.tex deleted file mode 100644 index dd3594b1..00000000 --- a/docs/tex/coreprocessscheduler.tex +++ /dev/null @@ -1,132 +0,0 @@ -\documentclass{article} -\usepackage{graphicx} % Required for inserting images -\usepackage{hyperref} - -\title{CoreProcessScheduler: Technical Documentation} -\author{Amlal El Mahrouss} -\date{\today} - -\begin{document} - -\maketitle - -\section{Abstract} - -{The CoreProcessScheduler governs how the scheduling backend and policy of the kernel works, It is the common gateway for schedulers inside NeKernel based systems.} - -\section{Overview} - -{The CoreProcessScheduler (now referred as CPS) serves as the intermediate foundal between the scheduler backend and kernel.} {It takes care of process life-cycle management, team-based process grouping, and affinity-based CPU based allocation to mention the least.} - -\section{The Affinity System} - -{Processes are given CPU time affinity hints using an affinity kind type, these hints help the scheduler run or adjust the current process.} - -\subsection{Sample Code \#1} - -{The following sample is C++ code.} {The smaller the value, the more critical the process.} - -\begin{verbatim} -enum class AffinityKind : Int32 { - kRealTime = 100, - kVeryHigh = 150, - kHigh = 200, - kStandard = 1000, - kLowUsage = 1500, - kVeryLowUsage = 2000, -}; -\end{verbatim} - -\section{The Team System} - -{The team system holds process metadata for the backend scheduler to run on. It holds methods and fields for backend specific operations.} {One implementation of such team is the UserProcessTeam object inside NeKernel.} - -\subsection{Sample Code \#2} - -{The following sample is used to hold team metadata.} {This is part of the NeKernel source tree.} - -\begin{verbatim} -class UserProcessTeam final { - public: - explicit UserProcessTeam(); - ~UserProcessTeam() = default; - - NE_COPY_DEFAULT(UserProcessTeam) - - Array& AsArray(); - Ref& AsRef(); - ProcessID& Id() noexcept; - - public: - USER_PROCESS_ARRAY mProcessList; - USER_PROCESS_REF mCurrentProcess; - ProcessID mTeamId{0}; - ProcessID mProcessCur{0}; -}; - -\end{verbatim} - -\section{The Process Image System} - -{The process image container is a design pattern made to contain process data and metadata, its purpose comes from the lack of mainstream operating systems of such ability to hold metadata.} - -\newline - -{This approach helps separate concerns and give modularity to the system, as the image and process structure are not mixed together.} - -\subsection{Sample Code \#3} - -{The following sample is a C++ container used to hold process data and metadata.} {This is part of the NeKernel source tree.} - -\begin{verbatim} -struct PROCESS_IMAGE final { - explicit PROCESS_IMAGE() = default; - - private: - friend USER_PROCESS; - friend KERNEL_TASK; - - friend class UserProcessScheduler; - - ImagePtr fCode; - ImagePtr fBlob; - - public: - Bool HasCode() const { return this->fCode != nullptr; } - - Bool HasImage() const { return this->fBlob != nullptr; } - - ErrorOr LeakImage() { - if (this->fCode) { - return ErrorOr{this->fCode}; - } - - return ErrorOr{kErrorInvalidData}; - } - - ErrorOr LeakBlob() { - if (this->fBlob) { - return ErrorOr{this->fBlob}; - } - - return ErrorOr{kErrorInvalidData}; - } -}; - -\end{verbatim} - -\section{Conclusion} - -{The CoreProcessScheduler is a piece of systems design with robust design and useful cases, although useful in desktop/server cases, It may not be suited for every other tasks.} - -{And while one scheduler backend (such as the UserProcessScheduler) takes care of user process scheduling and fairness, the CoreProcessScheduler takes care of the foundation for those systems.} - -\section{References} - -{Here are the reference mentioned on this paper:} - -{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel} - -{CoreProcessScheduler}: \href{https://github.com/nekernel-org/nekernel/blob/dev/dev/kernel/KernelKit/CoreProcessScheduler.h}{CoreProcessScheduler} - -\end{document} diff --git a/docs/tex/mbci.tex b/docs/tex/mbci.tex deleted file mode 100644 index 71907376..00000000 --- a/docs/tex/mbci.tex +++ /dev/null @@ -1,117 +0,0 @@ - -\documentclass{article} -\usepackage{geometry} -\usepackage{longtable} -\usepackage{listings} -\usepackage{xcolor} -\geometry{margin=1in} -\title{MBCI: Mini Bus Controller Interface Specification} -\author{Amlal El Mahrouss} -\date{2025} - -\begin{document} - -\maketitle - -\section{Overview} -The Mini Bus Controller Interface (MBCI) is a standardized memory-mapped I/O bus specification designed for use in embedded systems and operating system kernels. It provides an extensible framework for managing hardware devices via a shared bus using memory-mapped registers. It is designed to remain abstract and platform-agnostic, leaving platform-specific interrupt and address logic to the HAL. - -\section{Signal Lines} -The MBCI bus interface includes the following signal lines: - -\begin{itemize} - \item \textbf{VCC} (IN) – Power supply (OUT for MCU) - \item \textbf{CLK} (IN) – Clock line (OUT for MCU) - \item \textbf{ACK} (BI) – Acknowledge line containing packet frame - \item \textbf{D0-, D1-} (IN) – Host interface packet input - \item \textbf{D0+, D1+} (OUT) – Host interface packet output - \item \textbf{GND} (IN) – Ground line (OUT for MCU) -\end{itemize} - -\section{Host Structure} - -\subsection*{IMBCIHost Structure} - -\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] -volatile struct IMBCIHost { - UInt32 Magic; - UInt32 HostId; - UInt16 VendorId; - UInt16 DeviceId; - UInt8 MemoryType; - UInt16 HostType; - UInt16 HostFlags; - UInt8 Error; - UInt32 MMIOTest; - UInt16 State; - UInt8 Status; - UInt8 InterruptEnable; - UInt64 BaseAddressRegister; - UInt64 BaseAddressRegisterSize; - UInt32 CommandIssue; - UInt8 Esb[64]; // Extended Signature Block - UInt8 Zero[8]; -}; -\end{lstlisting} - -\section{Enumerations} - -\subsection*{Device Speeds} -\begin{itemize} - \item \texttt{kMBCISpeedDeviceInvalid} - \item \texttt{kMBCILowSpeedDevice} - \item \texttt{kMBCIHighSpeedDevice} -\end{itemize} - -\subsection*{Host Flags} -\begin{itemize} - \item \texttt{kMBCIHostFlagsSupportsNothing} - \item \texttt{kMBCIHostFlagsSupportsAPM} - \item \texttt{kMBCIHostFlagsSupportsDaisyChain} - \item \texttt{kMBCIHostFlagsSupportsHWInterrupts} - \item \texttt{kMBCIHostFlagsSupportsDMA} - \item \texttt{kMBCIHostFlagsExtended} -\end{itemize} - -\subsection*{Host Types} -\begin{itemize} - \item \texttt{kMBCIHostKindHardDisk} - \item \texttt{kMBCIHostKindOpticalDisk} - \item \texttt{kMBCIHostKindKeyboardLow} - \item \texttt{kMBCIHostKindMouseLow} - \item \texttt{kMBCIHostKindMouseHigh} - \item \texttt{kMBCIHostKindKeyboardHigh} - \item \texttt{kMBCIHostKindNetworkInterface} - \item \texttt{kMBCIHostKindDaisyChain} - \item \texttt{kMBCIHostKindStartExtended} -\end{itemize} - -\subsection*{Host State} -\begin{itemize} - \item \texttt{kMBCIHostStateInvalid} - \item \texttt{kMBCIHostStateReset} - \item \texttt{kMBCIHostStateSuccess} - \item \texttt{kMBCIHostStateReady} - \item \texttt{kMBCIHostStateDmaStart} - \item \texttt{kMBCIHostStateDmaEnd} - \item \texttt{kMBCIHostStateFail} - \item \texttt{kMBCIHostStateCount} -\end{itemize} - -\section{Functions} - -\subsection*{MMIO Test} -Tests if MMIO is accessible by writing and checking a challenge value. Times out if the bus does not respond. - -\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] -inline BOOL busi_test_mmio(struct IMBCIHost* host, const UInt32 test); -\end{lstlisting} - -\subsection*{Auth Key Reader} -Reads the 24-bit auth key encoded in the last three bytes of the Extended Signature Block after verifying MMIO test success: - -\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] -inline MBCIAuthKeyType mbci_read_auth_key(struct IMBCIHost* host); -\end{lstlisting} - -\end{document} diff --git a/docs/tex/mini_bus_controller_interface.tex b/docs/tex/mini_bus_controller_interface.tex new file mode 100644 index 00000000..71907376 --- /dev/null +++ b/docs/tex/mini_bus_controller_interface.tex @@ -0,0 +1,117 @@ + +\documentclass{article} +\usepackage{geometry} +\usepackage{longtable} +\usepackage{listings} +\usepackage{xcolor} +\geometry{margin=1in} +\title{MBCI: Mini Bus Controller Interface Specification} +\author{Amlal El Mahrouss} +\date{2025} + +\begin{document} + +\maketitle + +\section{Overview} +The Mini Bus Controller Interface (MBCI) is a standardized memory-mapped I/O bus specification designed for use in embedded systems and operating system kernels. It provides an extensible framework for managing hardware devices via a shared bus using memory-mapped registers. It is designed to remain abstract and platform-agnostic, leaving platform-specific interrupt and address logic to the HAL. + +\section{Signal Lines} +The MBCI bus interface includes the following signal lines: + +\begin{itemize} + \item \textbf{VCC} (IN) – Power supply (OUT for MCU) + \item \textbf{CLK} (IN) – Clock line (OUT for MCU) + \item \textbf{ACK} (BI) – Acknowledge line containing packet frame + \item \textbf{D0-, D1-} (IN) – Host interface packet input + \item \textbf{D0+, D1+} (OUT) – Host interface packet output + \item \textbf{GND} (IN) – Ground line (OUT for MCU) +\end{itemize} + +\section{Host Structure} + +\subsection*{IMBCIHost Structure} + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +volatile struct IMBCIHost { + UInt32 Magic; + UInt32 HostId; + UInt16 VendorId; + UInt16 DeviceId; + UInt8 MemoryType; + UInt16 HostType; + UInt16 HostFlags; + UInt8 Error; + UInt32 MMIOTest; + UInt16 State; + UInt8 Status; + UInt8 InterruptEnable; + UInt64 BaseAddressRegister; + UInt64 BaseAddressRegisterSize; + UInt32 CommandIssue; + UInt8 Esb[64]; // Extended Signature Block + UInt8 Zero[8]; +}; +\end{lstlisting} + +\section{Enumerations} + +\subsection*{Device Speeds} +\begin{itemize} + \item \texttt{kMBCISpeedDeviceInvalid} + \item \texttt{kMBCILowSpeedDevice} + \item \texttt{kMBCIHighSpeedDevice} +\end{itemize} + +\subsection*{Host Flags} +\begin{itemize} + \item \texttt{kMBCIHostFlagsSupportsNothing} + \item \texttt{kMBCIHostFlagsSupportsAPM} + \item \texttt{kMBCIHostFlagsSupportsDaisyChain} + \item \texttt{kMBCIHostFlagsSupportsHWInterrupts} + \item \texttt{kMBCIHostFlagsSupportsDMA} + \item \texttt{kMBCIHostFlagsExtended} +\end{itemize} + +\subsection*{Host Types} +\begin{itemize} + \item \texttt{kMBCIHostKindHardDisk} + \item \texttt{kMBCIHostKindOpticalDisk} + \item \texttt{kMBCIHostKindKeyboardLow} + \item \texttt{kMBCIHostKindMouseLow} + \item \texttt{kMBCIHostKindMouseHigh} + \item \texttt{kMBCIHostKindKeyboardHigh} + \item \texttt{kMBCIHostKindNetworkInterface} + \item \texttt{kMBCIHostKindDaisyChain} + \item \texttt{kMBCIHostKindStartExtended} +\end{itemize} + +\subsection*{Host State} +\begin{itemize} + \item \texttt{kMBCIHostStateInvalid} + \item \texttt{kMBCIHostStateReset} + \item \texttt{kMBCIHostStateSuccess} + \item \texttt{kMBCIHostStateReady} + \item \texttt{kMBCIHostStateDmaStart} + \item \texttt{kMBCIHostStateDmaEnd} + \item \texttt{kMBCIHostStateFail} + \item \texttt{kMBCIHostStateCount} +\end{itemize} + +\section{Functions} + +\subsection*{MMIO Test} +Tests if MMIO is accessible by writing and checking a challenge value. Times out if the bus does not respond. + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +inline BOOL busi_test_mmio(struct IMBCIHost* host, const UInt32 test); +\end{lstlisting} + +\subsection*{Auth Key Reader} +Reads the 24-bit auth key encoded in the last three bytes of the Extended Signature Block after verifying MMIO test success: + +\begin{lstlisting}[language=C++,basicstyle=\ttfamily\footnotesize] +inline MBCIAuthKeyType mbci_read_auth_key(struct IMBCIHost* host); +\end{lstlisting} + +\end{document} -- cgit v1.2.3 From 0de2622525d0044a955d040147ae64a928f029c1 Mon Sep 17 00:00:00 2001 From: Amlal Date: Wed, 13 Aug 2025 03:26:52 +0200 Subject: fix: tex: fix binary_mutex imports. Signed-off-by: Amlal --- docs/tex/binary_mutex.tex | 3 ++- docs/tex/hefs.tex | 4 ++-- docs/tex/mini_bus_controller_interface.tex | 2 +- docs/tex/nefs.tex | 4 ++-- 4 files changed, 7 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex index 564d322a..9b8a1c40 100644 --- a/docs/tex/binary_mutex.tex +++ b/docs/tex/binary_mutex.tex @@ -1,5 +1,6 @@ \documentclass{article} -\usepackage{graphicx} % Required for inserting images +\usepackage{graphicx} +\usepackage{hyperref} \title{BinaryMutex: Technical Documentation} \author{Amlal El Mahrouss} diff --git a/docs/tex/hefs.tex b/docs/tex/hefs.tex index c947710f..1656e5a9 100644 --- a/docs/tex/hefs.tex +++ b/docs/tex/hefs.tex @@ -4,9 +4,9 @@ \usepackage{longtable} \usepackage{listings} \geometry{margin=1in} -\title{HeFS Filesystem Specification (v1.3)} +\title{HeFS: Hight-throughput extended File System} \author{Amlal El Mahrouss} -\date{2025} +\date{\today} \begin{document} diff --git a/docs/tex/mini_bus_controller_interface.tex b/docs/tex/mini_bus_controller_interface.tex index 71907376..ba2381b7 100644 --- a/docs/tex/mini_bus_controller_interface.tex +++ b/docs/tex/mini_bus_controller_interface.tex @@ -7,7 +7,7 @@ \geometry{margin=1in} \title{MBCI: Mini Bus Controller Interface Specification} \author{Amlal El Mahrouss} -\date{2025} +\date{\today} \begin{document} diff --git a/docs/tex/nefs.tex b/docs/tex/nefs.tex index 37e43d13..7f2fdd84 100644 --- a/docs/tex/nefs.tex +++ b/docs/tex/nefs.tex @@ -21,9 +21,9 @@ showstringspaces=false } -\title{NeFS: New Extended File System Specification} +\title{NeFS: New Extended File System} \author{Amlal El Mahrouss} -\date{2025} +\date{\today} \begin{document} -- cgit v1.2.3