diff options
Diffstat (limited to 'dev/boot/src/docs')
| -rw-r--r-- | dev/boot/src/docs/KERN_VER.md | 18 | ||||
| -rw-r--r-- | dev/boot/src/docs/MKFS_HEFS.md | 106 |
2 files changed, 121 insertions, 3 deletions
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 |