From 54a0f4c49d9bfb955174c87dae2f442d7f5a8b25 Mon Sep 17 00:00:00 2001
From: Amlal El Mahrouss <amlal@nekernel.org>
Date: Fri, 23 May 2025 11:12:31 +0200
Subject: feat!(Kernel): Improvements on the BitMapMgr, HTS, and UPS.

other:

 - Add ZXD header file.
 - Reworking AMD64 interrupts.
 - Improved HTS's design implementation.
 - Improved UPS's balancing implementation.

breaking changes:

 - Rename MemoryMgr to HeapMgr.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>
---
 dev/boot/src/docs/KERN_VER.md  |  18 +++++--
 dev/boot/src/docs/MKFS_HEFS.md | 106 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+), 3 deletions(-)
 create mode 100644 dev/boot/src/docs/MKFS_HEFS.md

(limited to 'dev/boot/src/docs')

diff --git a/dev/boot/src/docs/KERN_VER.md b/dev/boot/src/docs/KERN_VER.md
index cabdb1d2..0659431b 100644
--- a/dev/boot/src/docs/KERN_VER.md
+++ b/dev/boot/src/docs/KERN_VER.md
@@ -1,6 +1,18 @@
-# The `/props/kern_ver` NVRAM variable
+# `/props/kern_ver` — NVRAM EFI Variable
 
 The `/props/kern_ver` variable is used to track NeKernel's current version in a BCD format.
 
-- Use it to track the current's NeKernel version, in order to adapt your drivers to it.
-- It is also useful to keep track of it, for other purposes (bug tracking, development of new features)
\ No newline at end of file
+## 🛠 Reason
+
+- It is also used for:
+    - Bug tracking and system patching.
+    - Version and compatibility checking.
+
+## 🧪 Usage
+
+N/A
+
+## © License
+
+    Copyright (C) 2025,
+    Amlal El Mahrouss – All rights reserved.
\ No newline at end of file
diff --git a/dev/boot/src/docs/MKFS_HEFS.md b/dev/boot/src/docs/MKFS_HEFS.md
new file mode 100644
index 00000000..c9aa0628
--- /dev/null
+++ b/dev/boot/src/docs/MKFS_HEFS.md
@@ -0,0 +1,106 @@
+# `mkfs.hefs` – HeFS Filesystem Formatter
+
+`mkfs.hefs` is a command-line utility used to format a block device or disk image with the **High-throughput Extended File System (HeFS)** used by NeKernel. This tool initializes a HeFS volume by writing a boot node and configuring directory and inode index regions, block ranges, and volume metadata.
+
+---
+
+## 🛠 Features
+
+- Writes a valid `BootNode` to the specified output device or file.
+- Sets disk size, sector size, and volume label.
+- Supports user-defined ranges for:
+  - Index Node Directory (IND)
+  - Inodes (IN)
+  - Data blocks
+- UTF-8 encoded volume label support.
+- Fully compatible with NeKernel's VFS subsystem.
+
+---
+
+## 🧪 Usage
+
+    mkfs.hefs -L <label> -s <sector_size> \
+              -b <ind_start> -e <ind_end> \
+              -bs <block_start> -be <block_end> \
+              -is <in_start> -ie <in_end> \
+              -S <disk_size> -o <output_device>
+
+---
+
+## 🧾 Arguments
+
+| Option        | Description                                                             |
+|---------------|-------------------------------------------------------------------------|
+| `-L`          | Volume label (UTF-8, internally stored as UTF-16)                       |
+| `-s`          | Sector size (e.g., 512)                                                 |
+| `-b` `-e`     | Start and end addresses for the **Index Node Directory (IND)** region   |
+| `-bs` `-be`   | Start and end addresses for the **Block** data region                   |
+| `-is` `-ie`   | Start and end addresses for the **Inode** region                        |
+| `-S`          | Disk size in **gigabytes**                                              |
+| `-o`          | Path to the output device or image file                                 |
+
+> All address-based inputs (`-b`, `-e`, etc.) must be specified in **hexadecimal** format.
+
+---
+
+## 🧷 Notes
+
+- Default sector size is `512` bytes.
+- Default volume name is `"HeFS_VOLUME"`, defined as `kHeFSDefaultVolumeName`.
+- The tool writes a `BootNode` at the beginning of the index node range.
+- A CRC-safe magic signature is embedded for boot and integrity validation.
+- After writing the metadata, the tool flushes and closes the file stream.
+
+---
+
+## 💻 Example
+
+    mkfs.hefs -L "MyHeFS" -s 512 \
+              -b 0x1000 -e 0x8000 \
+              -bs 0x8000 -be 0x800000 \
+              -is 0x800000 -ie 0xA00000 \
+              -S 128 -o hefs.img
+
+This will create a 128 GiB formatted HeFS image named `hefs.img` with specified region boundaries.
+
+---
+
+## 📁 BootNode Structure
+
+The `BootNode` stores key filesystem metadata:
+
+    struct BootNode {
+      char     magic[8];
+      char16_t volumeName[64];
+      uint16_t version;
+      uint16_t diskKind;
+      uint16_t encoding;
+      uint64_t diskSize;
+      uint32_t sectorSize;
+      uint64_t startIND, endIND;
+      uint64_t startIN, endIN;
+      uint64_t startBlock, endBlock;
+      uint64_t indCount;
+      uint16_t diskStatus;
+    };
+
+---
+
+## ⚠️ Error Handling
+
+- Prints usage and exits on invalid/missing arguments.
+- Exits with error if the output device cannot be opened or written to.
+- Checks for zero sector size or disk size to prevent invalid formatting.
+
+---
+
+## 📚 Source Location
+
+Part of the [HeFS Tooling module](https://github.com/nekernel-org/nekernel) and used during system setup or disk preparation for NeKernel.
+
+---
+
+## © License
+
+    Copyright (C) 2025,
+    Amlal El Mahrouss – All rights reserved.
\ No newline at end of file
-- 
cgit v1.2.3