2.6 KiB

Raw Permalink Blame History

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.

2.6 KiB Raw Permalink Blame History