From 9012c6fb7c040be92aa8f950bad4f49c5be264d8 Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Sun, 28 Dec 2025 09:23:05 +0100 Subject: feat! rename docs to doc. Signed-off-by: Amlal El Mahrouss --- docs/drawio/AHCI_DESIGN.drawio | 40 ---- docs/drawio/LAUNCH_DESIGN.drawio | 22 --- docs/drawio/MBCI_DESIGN.drawio | 70 ------- docs/drawio/SCHED_DESIGN.drawio | 34 ---- docs/drawio/SOFT_SCHED_DESIGN.drawio | 25 --- docs/drawio/SYSTEM_DESIGN.drawio | 46 ----- docs/drawio/TIMER_DESIGN.drawio | 49 ----- docs/drawio/ZXD_DESIGN.drawio | 31 --- docs/specs/SPECIFICATION_FWRK.md | 302 ----------------------------- docs/specs/SPECIFICATION_MBCI.md | 34 ---- docs/specs/SPECIFICATION_OS.md | 82 -------- docs/svg/OS_DESIGN.png | Bin 22504 -> 0 bytes docs/tex/NOTICE.md | 10 - docs/tex/binary_mutex.tex | 77 -------- docs/tex/mini_bus_controller_interface.tex | 117 ----------- docs/tex/nefs.tex | 125 ------------ docs/tex/nekernel_smp_subsystem.tex | 32 --- docs/tex/openhefs.tex | 174 ----------------- 18 files changed, 1270 deletions(-) delete mode 100644 docs/drawio/AHCI_DESIGN.drawio delete mode 100644 docs/drawio/LAUNCH_DESIGN.drawio delete mode 100644 docs/drawio/MBCI_DESIGN.drawio delete mode 100644 docs/drawio/SCHED_DESIGN.drawio delete mode 100644 docs/drawio/SOFT_SCHED_DESIGN.drawio delete mode 100644 docs/drawio/SYSTEM_DESIGN.drawio delete mode 100644 docs/drawio/TIMER_DESIGN.drawio delete mode 100644 docs/drawio/ZXD_DESIGN.drawio delete mode 100644 docs/specs/SPECIFICATION_FWRK.md delete mode 100644 docs/specs/SPECIFICATION_MBCI.md delete mode 100644 docs/specs/SPECIFICATION_OS.md delete mode 100644 docs/svg/OS_DESIGN.png delete mode 100644 docs/tex/NOTICE.md delete mode 100644 docs/tex/binary_mutex.tex delete mode 100644 docs/tex/mini_bus_controller_interface.tex delete mode 100644 docs/tex/nefs.tex delete mode 100644 docs/tex/nekernel_smp_subsystem.tex delete mode 100644 docs/tex/openhefs.tex (limited to 'docs') diff --git a/docs/drawio/AHCI_DESIGN.drawio b/docs/drawio/AHCI_DESIGN.drawio deleted file mode 100644 index 73029de7..00000000 --- a/docs/drawio/AHCI_DESIGN.drawio +++ /dev/null @@ -1,40 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/LAUNCH_DESIGN.drawio b/docs/drawio/LAUNCH_DESIGN.drawio deleted file mode 100644 index 32fe8eda..00000000 --- a/docs/drawio/LAUNCH_DESIGN.drawio +++ /dev/null @@ -1,22 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/MBCI_DESIGN.drawio b/docs/drawio/MBCI_DESIGN.drawio deleted file mode 100644 index 38aa8b92..00000000 --- a/docs/drawio/MBCI_DESIGN.drawio +++ /dev/null @@ -1,70 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/SCHED_DESIGN.drawio b/docs/drawio/SCHED_DESIGN.drawio deleted file mode 100644 index ab75d000..00000000 --- a/docs/drawio/SCHED_DESIGN.drawio +++ /dev/null @@ -1,34 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/drawio/SOFT_SCHED_DESIGN.drawio b/docs/drawio/SOFT_SCHED_DESIGN.drawio deleted file mode 100644 index 27d4e2b0..00000000 --- a/docs/drawio/SOFT_SCHED_DESIGN.drawio +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/SYSTEM_DESIGN.drawio b/docs/drawio/SYSTEM_DESIGN.drawio deleted file mode 100644 index ffc625d4..00000000 --- a/docs/drawio/SYSTEM_DESIGN.drawio +++ /dev/null @@ -1,46 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/TIMER_DESIGN.drawio b/docs/drawio/TIMER_DESIGN.drawio deleted file mode 100644 index ca081fd3..00000000 --- a/docs/drawio/TIMER_DESIGN.drawio +++ /dev/null @@ -1,49 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/drawio/ZXD_DESIGN.drawio b/docs/drawio/ZXD_DESIGN.drawio deleted file mode 100644 index 19fadabd..00000000 --- a/docs/drawio/ZXD_DESIGN.drawio +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/specs/SPECIFICATION_FWRK.md b/docs/specs/SPECIFICATION_FWRK.md deleted file mode 100644 index 8d95abc7..00000000 --- a/docs/specs/SPECIFICATION_FWRK.md +++ /dev/null @@ -1,302 +0,0 @@ -=================================== - -# 0: General Information - -=================================== - -- ABI and Format: PEF/PE32+. -- Target: NeKernel. - -=================================== - -# 1: The specification: - -=================================== - -The NeKernel framework system (`.fwrk`) provides a standardized structure for creating modular, reusable libraries and components. Frameworks are self-contained packages that include headers, source code, metadata, and configuration for compilation and deployment within the NeKernel ecosystem. - -================================== - -# 2: Framework Directory Structure: - -================================== - -Each framework follows the standardized directory layout below: - -``` -.fwrk/ -├── .json # Framework manifest and build configuration -├── headers/ # Public API headers -│ ├── *.h # Public header files (C++ headers) -│ └── ... -├── src/ # Implementation source files -│ ├── *.cc # C++ implementation files -│ ├── DylibMain.cc # Dynamic library entry point (optional) -│ └── ... -├── xml/ # Framework metadata and properties -│ └── app.xml # Framework property list -├── dist/ # Build output directory -│ └── lib.fwrk.dylib # Compiled dynamic library -└── .keep # Placeholder file -``` - -================================ - -# 3: Component Specifications - -================================ - -### 1. Framework Manifest (`.json`) - -The JSON manifest file defines the build configuration, compilation flags, and metadata for the framework. - -**Required Fields:** - -- **`compiler_path`** (string): Path to the C++ compiler executable - - Example: `"clang++"`, `"x86_64-w64-mingw32-g++"` - -- **`compiler_std`** (string): C++ standard version - - Example: `"c++20"`, `"c++17"` - -- **`headers_path`** (array): Array of header search paths (relative to framework) - - Include paths for finding dependencies and kernel interfaces - - Example: `["./", "../../../src/kernel", "../../../public/frameworks/", "../../../src/"]` - -- **`sources_path`** (array): Array of source file globs to compile - - Example: `["src/*.cc"]` - -- **`output_name`** (string): Path and filename for compiled library output - - Example: `"./dist/libCoreFoundation.fwrk.dylib"` - -**Optional Fields:** - -- **`compiler_flags`** (array): Custom compilation flags - - Example: `["-ffreestanding", "-shared", "-fno-rtti", "-fno-exceptions"]` - -- **`cpp_macros`** (array): C++ preprocessor macro definitions - - Example: `["kCFVersion=0x0100", "__NE_AMD64__", "__CF_64BIT__"]` - -**Example Manifest:** -```json -{ - "compiler_path": "x86_64-w64-mingw32-g++", - "compiler_std": "c++20", - "headers_path": ["../", "./", "../../../dev", "../../../src/kernel"], - "sources_path": ["src/*.cc"], - "output_name": "./dist/libCoreFoundation.fwrk.dylib", - "compiler_flags": [ - "-ffreestanding", - "-shared", - "-fno-rtti", - "-fno-exceptions", - "-Wl,--subsystem=17" - ], - "cpp_macros": [ - "kCFVersion=0x0100", - "kCFVersionHighest=0x0100", - "kCFVersionLowest=0x0100", - "__NE_AMD64__", - "__CF_64BIT__" - ] -} -``` - -### 2. Public Headers Directory (`headers/`) - -Contains all public-facing C++ header files that define the framework's API. - -**Conventions:** -- File extension: `.h` (not `.hpp`) -- Namespace: Typically matches framework name (e.g., `CF::` for CoreFoundation) -- Include guards: Use `#pragma once` for header protection -- Copyright headers: Include NeKernel copyright notice at the top - -**Typical Headers:** -- Main header providing overall framework interface -- Specialized headers for different components -- Type definitions and class declarations -- Exception/error definitions - -### 3. Source Implementation Directory (`src/`) - -Contains C++ implementation files for the framework. - -**Key Files:** - -- **`DylibMain.cc`** (Optional): - - Entry point for dynamic library initialization - - Contains `_DylibAttach(SInt32 argc, Char* argv[])` function - - Returns status code (0 for success, EXIT_FAILURE otherwise) - - **Example:** - ```cpp - #include - - SInt32 _DylibAttach(SInt32 argc, Char* argv[]) { - // Initialization code here - return EXIT_FAILURE; // Change based on initialization result - } - ``` - -- **Implementation Files** (`*.cc`): - - Correspond to public headers - - Contain class definitions and function implementations - - Include necessary system and framework headers - -### 4. Metadata Directory (`xml/`) - -Contains XML-based property list files for framework metadata. - -**`app.xml` Structure:** -- PropertyList format for framework configuration -- Typically includes: - - `LibraryName`: Framework name (string) - - `CacheLibs`: Whether to cache library (boolean) - - Other framework-specific properties - -**Example:** -```xml - - - -``` - -### 5. Build Output Directory (`dist/`) - -Auto-generated directory containing compiled framework binaries. - -- **Output file**: `lib.fwrk.dylib` -- Created during build process via `mk_fwrk.py` -- Not committed to version control - -## Built-in Frameworks - -The NeKernel project includes the following standard frameworks: - -### CoreFoundation.fwrk -**Purpose:** Core data structures and utilities foundation -**Provides:** -- Reference types (CFRef) -- String handling (CFString) -- Collections (Arrays, Dictionaries) -- Geometric types (CFPoint, CFRect, CFColor) -- Object system (CFObject, CFProperty) - -### DiskImage.fwrk -**Purpose:** Disk image management and handling - -### KernelTest.fwrk -**Purpose:** Testing framework for kernel components - -### LaunchHelpers.fwrk -**Purpose:** Helper functions for system launch and initialization - -## Framework Creation - -### Using mk_fwrk.py - -The `mk_fwrk.py` tool automates framework creation: - -```bash -python3 tools/mk_fwrk.py -``` - -This generates: -1. Complete directory structure -2. Template `.json` manifest -3. Skeleton `DylibMain.cc` entry point -4. Template `xml/app.xml` metadata - -**Generated Structure:** -``` -.fwrk/ -├── .json -├── headers/ -│ └── .keep -├── src/ -│ ├── .keep -│ └── DylibMain.cc -├── xml/ -│ └── app.xml -└── .keep -``` - -## Compilation and Linking - -### Build Process - -1. **Configuration Phase**: Read and parse `.json` -2. **Compilation Phase**: Compile source files with specified compiler and flags -3. **Linking Phase**: Link object files into dynamic library -4. **Output Phase**: Place compiled binary in `dist/` directory - -### Dependencies - -- Frameworks can depend on: - - System libraries (via SystemKit) - - Other frameworks (via headers_path) - - Kernel components (via kernel paths in headers_path) - -### Linking Order - -When building applications that use frameworks: -1. Frameworks are linked in dependency order -2. CoreFoundation is typically a base dependency -3. Framework paths and library names must match manifest output names - -## Naming Conventions - -- **Framework directories**: `.fwrk` (PascalCase + .fwrk suffix) -- **JSON manifest**: `.json` (matches framework directory name) -- **Output library**: `lib.fwrk.dylib` -- **Namespaces**: Two-letter abbreviations (e.g., `CF`, `DI`, `KT`, `LH`) -- **Macros**: `k` prefix (e.g., `kCFVersion`) - -## Version Specification - -Frameworks should include version information via preprocessor macros: - -- **`kVersion`**: Current framework version (e.g., `0x0100` for v1.0) -- **`kVersionHighest`**: Highest compatible version -- **`kVersionLowest`**: Lowest compatible version - -**Version Format**: Hexadecimal (e.g., `0x0100` = 1.0, `0x0201` = 2.1) - -## Architecture Support - -Frameworks can be compiled for multiple architectures: - -- **x86_64** (amd64): 64-bit x86/AMD64 architecture -- **ARM64**: 64-bit ARM architecture -- **RISC-V 64**: RISC-V 64-bit architecture -- **PowerPC 64**: PowerPC 64-bit architecture - -Architecture is typically controlled via: -- Compiler selection in manifest -- C++ macros (`__NE_AMD64__`, `__NE_ARM64__`, etc.) - -## Best Practices - -1. **Header Organization**: Keep headers minimal; place implementation in `.cc` files -2. **Namespace Usage**: Encapsulate all public APIs in framework namespace -3. **Dependencies**: Minimize external dependencies; prefer kernel APIs -4. **Configuration**: Use `.json` manifest for all build-time configuration -5. **Documentation**: Include copyright headers and documentation comments in code -6. **Error Handling**: Define framework-specific error codes and status returns -7. **Testing**: Provide test cases using KernelTest.fwrk when applicable - -## Integration with Applications - -Applications that use frameworks: - -1. **Include Headers**: `#include ` -2. **Link Framework**: Add framework library to linker flags -3. **Initialize**: Call framework initialization if provided -4. **Handle Errors**: Check return codes and handle framework exceptions - -## File Permissions - -- Framework files: Standard text (`.h`, `.cc`, `.json`, `.xml`) -- Build artifacts: Auto-generated and read-only during runtime -- Framework package: Should be distributable as single `.fwrk` directory - diff --git a/docs/specs/SPECIFICATION_MBCI.md b/docs/specs/SPECIFICATION_MBCI.md deleted file mode 100644 index 648529cf..00000000 --- a/docs/specs/SPECIFICATION_MBCI.md +++ /dev/null @@ -1,34 +0,0 @@ -=================================== - -# 0: General Information: - -=================================== - -- High Speed Bus Format. -- Designed for keyboards, mouses, interfaces. -- A open and cheap alternative to other HCIs. - -=================================== - -# 1: Concepts: - -=================================== - -- MBCI Host -- MBCI Authentication key (24-bit number) -- MBCI Host Kind and Flags. - -=================================== - -# 2: Pinout: - -=================================== - -- VCC (IN) (OUT for MCU) -- CLK (IN) (OUT for MCU) -- ACK (BI) (Contains an Acknowledge Packet Frame) -- D0- (IN) (Starts with the Host Interface Packet Frame) -- D1- (IN) (Starts with the Host Interface Packet Frame) -- D0+ (OUT) (Starts with the Host Interface Packet Frame) -- D1+ (OUT) (Starts with the Host Interface Packet Frame) -- GND (IN) (OUT for MCU) \ No newline at end of file diff --git a/docs/specs/SPECIFICATION_OS.md b/docs/specs/SPECIFICATION_OS.md deleted file mode 100644 index 08c2b326..00000000 --- a/docs/specs/SPECIFICATION_OS.md +++ /dev/null @@ -1,82 +0,0 @@ -=================================== - -# 0: General Information: - -=================================== - -- ABI and Format: PEF/PE32+. -- Kernel architecture: Portable hybrid Kernel. -- Used Languages: C++, and Assembly Assembly (AMD64, X64000, X86S, ARM64, POWER, RISCV) -- 32-bit is not supported as of 12/25/2025. - -=================================== - -# 1: The Kernel (NeKernel) - -=================================== - -- Drive/Device Abstraction. -- SMP, Preemptive Multi Threading. -- Separation of Files/Devices. -- Networking Support. -- Hardware Abstraction Layer. -- Native Filesystem support (NeFS, FAT32 and ffs2). -- Program Loaders interfaces. -- TLS (Thread Local Storage) support. -- BinaryMutex, Locks, Timers. -- Canary mechanisms. -- Dynamic Loader. -- Cross Platform. -- Permission Selectors. -- Modular and Security focused. - -=================================== - -# 2: The Filesystem (NeFS, or OpenHeFS) - -=================================== - -- Catalog object with associated forks. -- Large storage support. -- Long file names. -- UNIX path style. -- Can be formated under 8mb. - -================================== - -# 3: Common conventions: - -================================== - -- Kernel -> ke_init_x -- RunTime -> rt_copy_mem -- Hal -> hal_foo_bar -- Class methods -> Class::FooBar -- Internals function shall be formated as such: (hali, rtli, rti...) - -=================================== - -# 4: The Bootloader (BootZ) - -=================================== - -- Capable of booting from a network drive. -- Loads a PE file which is the Kernel, or any modules. -- Sanity checks, based on the number of sections. -- Handover compliant. -- Does check for a valid partition (useful in the case of recovering) -- Modular, and Security focused. - -=================================== - -# 5: The IFS - -================================== - -- Filesystem to mountpoint interface abstraction. -- VFS-like subsystem inspired by NT/OS2 IFS. -- Multi-drive support (A, B, C, D indices). -- Ext2 support via IFS layer. -- Packet-based I/O operations. -- Separation of read/write operations per drive. - diff --git a/docs/svg/OS_DESIGN.png b/docs/svg/OS_DESIGN.png deleted file mode 100644 index 05fbee16..00000000 Binary files a/docs/svg/OS_DESIGN.png and /dev/null differ diff --git a/docs/tex/NOTICE.md b/docs/tex/NOTICE.md deleted file mode 100644 index 23417d2a..00000000 --- a/docs/tex/NOTICE.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/docs/tex/binary_mutex.tex b/docs/tex/binary_mutex.tex deleted file mode 100644 index 548f440f..00000000 --- a/docs/tex/binary_mutex.tex +++ /dev/null @@ -1,77 +0,0 @@ -\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/docs/tex/mini_bus_controller_interface.tex b/docs/tex/mini_bus_controller_interface.tex deleted file mode 100644 index ba2381b7..00000000 --- a/docs/tex/mini_bus_controller_interface.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{\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/docs/tex/nefs.tex b/docs/tex/nefs.tex deleted file mode 100644 index 37e43d13..00000000 --- a/docs/tex/nefs.tex +++ /dev/null @@ -1,125 +0,0 @@ -\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/docs/tex/nekernel_smp_subsystem.tex b/docs/tex/nekernel_smp_subsystem.tex deleted file mode 100644 index cb30f3cb..00000000 --- a/docs/tex/nekernel_smp_subsystem.tex +++ /dev/null @@ -1,32 +0,0 @@ -\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/docs/tex/openhefs.tex b/docs/tex/openhefs.tex deleted file mode 100644 index 136d651c..00000000 --- a/docs/tex/openhefs.tex +++ /dev/null @@ -1,174 +0,0 @@ -\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} -- cgit v1.2.3