feat! rename docs to doc.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

6 files changed, 535 insertions, 0 deletions

diff --git a/doc/tex/NOTICE.md b/doc/tex/NOTICE.md
new file mode 100644
index 00000000..23417d2a
--- /dev/null
+++ b/doc/tex/NOTICE.md
@@ -0,0 +1,10 @@
+# Notice: NeKernel specifications.
+
+## Notice: CoreProcessScheduler paper.
+
+The CPS has been moved to WG02,for more information, clone the following repository: [https://github.com/nekernel-org/draft](https://github.com/nekernel-org/draft).
+
+## Recommended:
+
+- `pdflatex` is recommended for this matter.
+- You can use `overleaf` to edit the LaTeX files too.
diff --git a/doc/tex/binary_mutex.tex b/doc/tex/binary_mutex.tex
new file mode 100644
index 00000000..548f440f
--- /dev/null
+++ b/doc/tex/binary_mutex.tex
@@ -0,0 +1,77 @@
+\documentclass{article}
+\usepackage{graphicx}
+\usepackage{hyperref}
+
+\title{BinaryMutex: Technical Documentation}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Abstract}
+
+{The BinaryMutex is a core component of NeKernel (NeKernel/Legacy 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{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;
+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;
+while (mux.WaitForProcess(kSecondsMax));
+
+// finally do our task now.
+
+process.DoFoo();
+\end{verbatim}
+
+\section{Implementation}
+
+The source implementation consists of this simple C++ class:
+
+\begin{verbatim}
+class BinaryMutex final {
+ public:
+  explicit BinaryMutex() = default;
+  ~BinaryMutex()         = default;
+
+ public:
+  bool IsLocked() const;
+  bool Unlock();
+
+ public:
+  BOOL WaitForProcess(const UInt32& sec);
+
+ public:
+  bool Lock(UserProcess* process);
+  bool LockAndWait(UserProcess* process, ITimer* timer);
+
+ public:
+  NE_COPY_DEFAULT(BinaryMutex)
+
+ private:
+  UserProcess* fLockingProcess;
+};
+\end{verbatim}
+
+\section{Conclusion}
+
+{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 Legacy VMKernel and NeKernel.}
+
+\section{References}
+
+{NeKernel}: \href{https://github.com/nekernel-org/nekernel}{NeKernel}
+
+{Legacy VMKernel}: \href{https://snu.systems/specs/vmkernel}{Legacy VMKernel}
+
+{BinaryMutex}: \href{https://github.com/nekernel-org/nekernel/blob/src/src/kernel/KernelKit/BinaryMutex.h}{BinaryMutex}
+
+\end{document}
diff --git a/doc/tex/mini_bus_controller_interface.tex b/doc/tex/mini_bus_controller_interface.tex
new file mode 100644
index 00000000..ba2381b7
--- /dev/null
+++ b/doc/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{\today}
+
+\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/doc/tex/nefs.tex b/doc/tex/nefs.tex
new file mode 100644
index 00000000..37e43d13
--- /dev/null
+++ b/doc/tex/nefs.tex
@@ -0,0 +1,125 @@
+\documentclass{article}
+\usepackage[a4paper,margin=1in]{geometry}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage{amsmath}
+\usepackage{hyperref}
+\usepackage{longtable}
+\usepackage{titlesec}
+\usepackage{fancyhdr}
+\usepackage{caption}
+\usepackage{graphicx}
+
+\definecolor{codegray}{gray}{0.95}
+\lstset{
+  backgroundcolor=\color{codegray},
+  basicstyle=\ttfamily\small,
+  breaklines=true,
+  frame=single,
+  tabsize=4,
+  language=C++,
+  showstringspaces=false
+}
+
+\title{NeFS: New Extended File System Specification}
+\author{Amlal El Mahrouss}
+\date{2025}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+NeFS (New Extended File System) is am embedded file system designed to operate over low-level block storage (AHCI/ATA) with a modular architecture. It supports catalogs (like files or directories), forks (similar to macOS data/resource forks), and a formatting mechanism using EPM (Extended Partition Map).
+
+\section{Key Components}
+
+\subsection*{Mountpoint and Drive Access}
+\begin{itemize}
+  \item `kMountpoint`: Global mountpoint interface to access drives.
+  \item `DriveTrait`: Interface used to abstract block-level access.
+\end{itemize}
+
+\subsection*{Core Structures}
+\begin{longtable}{|l|p{11cm}|}
+\hline
+\textbf{Structure} & \textbf{Purpose} \\
+\hline
+NEFS\_FORK\_STRUCT & Represents a data fork (stream of bytes attached to a catalog). \\
+\hline
+NEFS\_CATALOG\_STRUCT & Represents metadata of a file or directory, including fork pointers. \\
+\hline
+NEFS\_ROOT\_PARTITION\_BLOCK & Metadata describing a NeFS partition. \\
+\hline
+EPM\_PART\_BLOCK & EPM descriptor for bootable partition support. \\
+\hline
+\end{longtable}
+
+\subsection*{Key Functions}
+
+\begin{itemize}
+  \item \texttt{CreateCatalog()} — Creates a file or directory catalog.
+  \item \texttt{CreateFork()} — Adds a fork to a catalog, with LBA linking.
+  \item \texttt{FindCatalog()} — Finds a catalog by traversing sibling links.
+  \item \texttt{FindFork()} — Locates a fork by name under a catalog.
+  \item \texttt{WriteCatalog()} — Writes a fork's data to the correct offset.
+  \item \texttt{Format()} — Initializes a NeFS + EPM partition on a drive.
+  \item \texttt{ReadCatalog()} — Reads back a fork's data.
+  \item \texttt{RemoveCatalog()} — Marks a catalog as deleted and updates partition metadata.
+\end{itemize}
+
+\section{Design Overview}
+
+\subsection*{Fork Management}
+Forks are chained using `NextSibling` pointers and are scanned linearly to find unallocated entries. Forks contain:
+\begin{itemize}
+  \item Fork name
+  \item Catalog name
+  \item Flags (e.g., created/deleted)
+  \item Data size and offset
+  \item Sibling pointers (Next, Previous)
+\end{itemize}
+
+\subsection*{Catalog Management}
+Catalogs act like files or directories. Each has:
+\begin{itemize}
+  \item Name and type (file/dir)
+  \item Data and resource forks
+  \item Status flags
+  \item Chaining via sibling pointers
+\end{itemize}
+Catalog creation attempts to find a parent first, then finds a free block to allocate the new catalog structure.
+
+\subsection*{Partition Formatting}
+The `Format()` function sets up the NeFS partition and optionally writes an EPM descriptor if bootable. It:
+\begin{enumerate}
+  \item Verifies the drive
+  \item Initializes partition metadata (sector size, catalog start, etc.)
+  \item Writes the root directory
+\end{enumerate}
+
+\section{Error Handling}
+Errors are written to a global error register using `err\_global\_get()`. Common codes include:
+\begin{itemize}
+  \item \texttt{kErrorDiskIsCorrupted}
+  \item \texttt{kErrorFileExists}
+  \item \texttt{kErrorFileNotFound}
+  \item \texttt{kErrorUnimplemented}
+\end{itemize}
+
+\section{Limitations and Notes}
+\begin{itemize}
+  \item No read/write locking or access concurrency.
+  \item Assumes in-memory buffers for fork writing.
+  \item Seek/Tell operations are not implemented — only bulk read/write.
+  \item Supports one mountpoint at a time.
+\end{itemize}
+
+\section{Future Work}
+\begin{itemize}
+  \item Implement streaming I/O with Seek/Tell.
+  \item Support multiple mountpoints or drives.
+  \item Improve metadata journaling and recovery features.
+\end{itemize}
+
+\end{document}
diff --git a/doc/tex/nekernel_smp_subsystem.tex b/doc/tex/nekernel_smp_subsystem.tex
new file mode 100644
index 00000000..cb30f3cb
--- /dev/null
+++ b/doc/tex/nekernel_smp_subsystem.tex
@@ -0,0 +1,32 @@
+\documentclass{article}
+\usepackage{graphicx}
+
+\title{NeKernel: The SMP Subsystem}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+    \maketitle
+
+    \section{Abstract}
+
+    {NeKernel is a hybrid based operating system kernel written in modern C++ (C++17/C++20). It features a bootloader, kernel, tools, libraries, and frameworks. This document is about the SMP subsystem of the kernel.}
+
+    \section{Design Overview}
+
+    {NeKernel is designed with SMP by default. Although it may fallback under classic preemptive round-robin scheduling when unavailable - NeKernel runs best on a SMP based machine. The subsystem goes from the HardwareThreadScheduler to the Hardware Abstraction Layer's Application Processor API.}
+
+    \section{The SMP Subsystem}
+
+    {The SMP subsystem consist of the HTS (HardwareThreadScheduler) and AP (Application Processor) APIs. Those systems are made to handle SMP tasks inside NeKernel.}
+
+    \subsection{Higher Level: HardwareThreadScheduler (HTS)}
+
+    {HTS's main purpose is to make cores all busy with a StackFrame object. That object contains program registers such as the stack pointer and instruction pointer. Each task is fairly assigned to then be run by the AP's mp\_register\_task function.}
+
+    \subsection{Lower Level: Application Processor (AP) API}
+
+    {Application Processors (now referred as AP) is the API taking care of multi-core scheduling, very platform dependent (thus its presence on the HAL) it is designed to run tasks passed from the HTS.}
+
+\end{document}
diff --git a/doc/tex/openhefs.tex b/doc/tex/openhefs.tex
new file mode 100644
index 00000000..136d651c
--- /dev/null
+++ b/doc/tex/openhefs.tex
@@ -0,0 +1,174 @@
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+\usepackage{geometry}
+\usepackage{longtable}
+\usepackage{listings}
+\geometry{margin=1in}
+\title{OpenHeFS: Hight-throughput extended File System}
+\author{Amlal El Mahrouss}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\section{Overview}
+The High-throughput Extended File System (OpenHeFS) is a custom filesystem tailored for performance, structure, and compact representation. It uses red-black trees for directory indexing, sparse block slicing for file layout, and fixed-size metadata structures optimized for 512-byte sector alignment.
+
+\section{Constants and Macros}
+\begin{longtable}{|l|l|}
+\hline
+\textbf{Name} & \textbf{Value / Description} \\
+\hline
+\texttt{kOpenHeFSVersion} & 0x0103 \\
+\texttt{kOpenHeFSMagic} & "OpenHeFS" (9-byte magic identifier) \\
+\texttt{kOpenHeFSMagicLen} & 9 \\
+\texttt{kOpenHeFSBlockLen} & 512 bytes \\
+\texttt{kOpenHeFSFileNameLen} & 256 characters \\
+\texttt{kOpenHeFSPartNameLen} & 128 characters \\
+\texttt{kOpenHeFSMinimumDiskSize} & 128 GiB \\
+\texttt{kOpenHeFSDefaultVolumeName} & "OpenHeFS Volume" \\
+\texttt{kOpenHeFSINDStartOffset} & Offset after boot node \\
+\texttt{kOpenHeFSSearchAllStr} & "*" (wildcard string) \\
+\hline
+\end{longtable}
+
+\section{Disk and File Metadata Enums}\label{sec:disk-and-file-metadata-enums}
+
+\subsection{Drive Kind (\texttt{UInt8})}\label{subsec:drive-kind-(texttt{uint8})}
+\begin{itemize}
+\item 0xC0: Hard Drive
+\item 0xC1: Solid State Drive
+\item 0x0C: Optical Drive
+\item 0xCC: USB Mass Storage
+\item 0xC4: SCSI Drive
+\item 0xC6: Flash Drive
+\item 0xFF: Unknown
+\end{itemize}
+
+\subsection{Disk Status (\texttt{UInt8})}\label{subsec:disk-status-(texttt{uint8})}
+\begin{itemize}
+\item 0x18: Unlocked
+\item 0x19: Locked
+\item 0x1A: Error
+\item 0x1B: Invalid
+\end{itemize}
+
+\subsection{Encoding Flags (\texttt{UInt16})}\label{subsec:encoding-flags-(texttt{uint16})}
+\begin{itemize}
+\item UTF-8
+\item UTF-16
+\item UTF-32
+\item UTF-16BE
+\item UTF-16LE
+\item UTF-32BE
+\item UTF-32LE
+\item UTF-8BE
+\item UTF-8LE
+\item Binary
+\end{itemize}
+
+\subsection{File Kinds (\texttt{UInt16})}\label{subsec:file-kinds-(texttt{uint16})}
+\begin{itemize}
+\item 0x00: Regular File
+\item 0x01: Directory
+\item 0x02: Block Device
+\item 0x03: Character Device
+\item 0x04: FIFO
+\item 0x05: Socket
+\item 0x06: Symbolic Link
+\item 0x07: Unknown
+\end{itemize}
+
+\subsection{File Flags (\texttt{UInt32})}\label{subsec:file-flags-(texttt{uint32})}
+\begin{itemize}
+\item 0x000: None
+\item 0x100: ReadOnly
+\item 0x101: Hidden
+\item 0x102: System
+\item 0x103: Archive
+\item 0x104: Device
+\end{itemize}
+
+\section{Structures}\label{sec:structures}
+
+\subsection{HEFS\_BOOT\_NODE}\label{subsec:hefs_boot_node}
+Acts as the superblock of the filesystem, provides necessary information about the disk and the filesystem itself.
+
+\begin{itemize}
+  \item \texttt{fMagic}, \texttt{fVolName}, \texttt{fVersion}, \texttt{fChecksum}
+  \item Sector and disk geometry: \texttt{fSectorCount}, \texttt{fSectorSize}, \texttt{fBadSectors}
+  \item Drive info: \texttt{fDiskKind}, \texttt{fEncoding}, \texttt{fDiskStatus}, \texttt{fDiskFlags}, \texttt{fVID}
+  \item Tree layout: \texttt{fStartIND}, \texttt{fEndIND}, \texttt{fINDCount}
+  \item Reserved: \texttt{fStartIN}, \texttt{fEndIN}, \texttt{fStartBlock}, \texttt{fEndBlock}
+\end{itemize}
+
+\subsection{HEFS\_INDEX\_NODE}\label{subsec:hefs_index_node}
+Contains file metadata and block layout.
+
+\begin{itemize}
+  \item \texttt{fHashPath}, \texttt{fFlags}, \texttt{fKind}, \texttt{fSize}, \texttt{fChecksum}
+  \item \texttt{fSymLink} - if set, \texttt{fHashPath} represents the symlink target
+  \item Time: \texttt{fCreated}, \texttt{fAccessed}, \texttt{fModified}, \texttt{fDeleted}
+  \item Ownership: \texttt{fUID}, \texttt{fGID}, \texttt{fMode}
+  \item Block data: \texttt{fOffsetSliceLow}, \texttt{fOffsetSliceHigh}
+\end{itemize}
+
+\subsection{HEFS\_INDEX\_NODE\_DIRECTORY}\label{subsec:hefs_index_node_directory}
+Red-black tree based directory node.
+
+\begin{itemize}
+  \item \texttt{fHashPath}, \texttt{fFlags}, \texttt{fKind}, \texttt{fEntryCount}, \texttt{fChecksum}
+  \item Time and ownership same as inode
+  \item \texttt{fINSlices[kOpenHeFSSliceCount]} for storing child inode links
+\item RB-Tree Fields:
+\begin{itemize}
+  \item \texttt{fColor}: Red or Black
+  \item \texttt{fNext}/\texttt{fPrev}: Sibling pointers
+  \item \texttt{fChild}: Left or right child (implementation-defined)
+  \item \texttt{fParent}: Parent node
+\end{itemize}
+
+\end{itemize}
+
+\section{Timestamp Layout (ATime)}\label{sec:timestamp-layout-(atime)}
+
+\texttt{ATime} is a 64-bit timestamp and allocation status tracker with the following structure:
+
+\begin{itemize}
+  \item Bits 63-32: Year
+  \item Bits 31-24: Month
+  \item Bits 23-16: Day
+  \item Bits 15-8: Hour
+  \item Bits 7-0: Minute
+\end{itemize}
+
+Constants:
+\begin{itemize}
+  \item \texttt{kOpenHeFSTimeInvalid = 0x0}
+  \item \texttt{kOpenHeFSTimeMax = 0xFFFFFFFFFFFFFFFF - 1}
+\end{itemize}
+
+\section{Filesystem API}\label{sec:filesystem-api}
+
+Provided by \texttt{Kernel::OpenHeFS::HeFileSystemParser}.
+
+\begin{itemize}
+  \item \texttt{Format(drive, flags, name)} - Format drive with OpenHeFS
+  \item \texttt{CreateINodeDirectory(drive, flags, dir)}
+  \item \texttt{RemoveINodeDirectory(drive, flags, dir)}
+  \item \texttt{CreateINode(drive, flags, dir, name, kind)}
+  \item \texttt{DeleteINode(drive, flags, dir, name, kind)}
+  \item \texttt{INodeManip(drive, block, size, dir, kind, name, in)}
+\end{itemize}
+
+Internal helpers:
+\begin{itemize}
+  \item \texttt{INodeCtlManip}, \texttt{INodeDirectoryCtlManip}
+\end{itemize}
+
+\section{Conclusion}
+OpenHeFS provides a modern and compact approach to high-performance file storage.
+Its use of red-black trees, fixed-size metadata, slice-based sparse files, and minimal overhead makes it a strong candidate for performance-sensitive use cases.
+
+\end{document}