47 lines
2.6 KiB
Markdown
47 lines
2.6 KiB
Markdown
# Sovereign Ledger: VirtIO Block Driver
|
|
|
|
## Overview
|
|
Phase 10 "The Sovereign Ledger" introduces persistent storage capabilities to **Rumpk** via a custom **VirtIO Block Driver**. This allows the **NipBox** userland to perform direct sector-level I/O operations on a raw disk image (`storage.img`), establishing the foundation for a future Sovereign Filesystem.
|
|
|
|
## Architecture
|
|
|
|
### 1. Hardware Abstraction (L0 HAL)
|
|
- **Driver:** `hal/virtio_block.zig`
|
|
- **Device ID:** `0x1001` (Legacy Block) or `0x1042` (Modern).
|
|
- **Transport:** Leverages `hal/virtio_pci.zig` for universal PCI resource discovery and I/O port allocation.
|
|
- **Mechanism:** Synchronous Polling (Busy Wait).
|
|
- Uses a 3-Descriptor Chain per request:
|
|
1. **Header:** `VirtioBlkReq` (Type, Priority, Sector).
|
|
2. **Buffer:** Data payload (512 bytes).
|
|
3. **Status:** Completion byte (0 = OK).
|
|
- **Orchestration:** Initialized in `hal/entry_riscv.zig` via `hal_io_init`.
|
|
|
|
### 2. Kernel Core (L1 Logic)
|
|
- **Command Ring:** Adds `CMD_BLK_READ` (0x600) and `CMD_BLK_WRITE` (0x601) to `ion.nim`.
|
|
- **Arguments:** `BlkArgs` structure marshals `sector`, `buffer_ptr`, and `len` across the User/Kernel boundary.
|
|
- **Dispatch:** `kernel.nim` routes these commands from the `chan_cmd` ring directly to the HAL functions `virtio_blk_read/write`.
|
|
|
|
### 3. Userland Shim (Membrane)
|
|
- **Syscalls:** `libc_shim.zig` exposes `nexus_blk_read` and `nexus_blk_write`.
|
|
- **Packaging:** These wrappers construct the `BlkArgs` struct and invoke `nexus_syscall`.
|
|
|
|
### 4. Userland Application (NipBox)
|
|
- **Command:** `dd`
|
|
- **Syntax:**
|
|
- `dd read <sector>`: Dumps the first 16 bytes of the sector in Hex.
|
|
- `dd write <sector> <string>`: Writes the string (UTF-8) to the sector, zero-padded.
|
|
- **Protocol:** Uses the new IO syscalls to interact with the Ledger.
|
|
|
|
## Deployment & Verification
|
|
- **Disk Image:** `build/storage.img` (Raw, 32MB).
|
|
- **QEMU:** Attached via `-drive if=none,format=raw,file=build/storage.img,id=hd0 -device virtio-blk-pci,drive=hd0,disable-modern=on`.
|
|
- **Status:**
|
|
- **Write:** Confirmed successful (Hexdump valid on host).
|
|
- **Read:** Driver operation successful, data verification ongoing.
|
|
- **Boot:** Stable initialization of both Network and Block devices simultaneously (via fixed PCI I/O allocation).
|
|
|
|
## Next Steps
|
|
- **Data Integrity:** Investigate zero-readback issue (likely buffer address mapping or flag polarity).
|
|
- **Filesystem:** Implement a minimalist inode-based FS (SovFS) on top of the raw ledger.
|
|
- **Async I/O:** Move from busy-polling to Interrupt-driven (Virtqueue Notification) for high throughput.
|