# `mkfs.hefs` – OpenHeFS 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 (OpenHeFS)** used by NeKernel. This tool initializes a OpenHeFS 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 OpenHeFS 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 [OpenHeFS 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 – Licensed under the Apache 2.0 license.