EriX Virtio Block Driver (drv-virtio-block)

drv-virtio-block is the raw block provider for one discovered QEMU virtio-blk PCI function. It receives a validated BAR-derived DEVICE_FRAME from deviced, maps its BAR and queue/data buffers through vspaced into a deterministic high runtime aperture, drives one polled virtqueue, and exposes synchronous block I/O to blockd through lib-block.

EriX is a clean-room, capability-based microkernel operating system written entirely in Rust.

Technical requirements are tracked in the EriX requirements, conventions, and project documentation.

See:

• docs for design documents, specifications, and development plans.
• Related architecture repositories for kernel, services, libraries, drivers, and integration tooling.

Purpose of This Repository

This repository implements the EriX virtio block driver service. Its purpose in EriX is to mediate virtio block hardware or protocol behavior under explicit deviced / procd ownership.

Functionally, it implements the driver startup, runtime, and validation contracts for virtio block. The repository keeps the implementation, interface contracts, tests, and documentation for that behavior in one reviewable ownership boundary.

The maintained responsibilities are:

• implement the virtio block driver logic behind explicit driver authority
• bind only to the startup-assigned device, service endpoint, root vspace, and exact memory-service peer capabilities
• serve canonical transport-sized driver operations without creating public service authority
• keep MMIO and DMA buffer mappings outside signed executable and dynamic-shared-object image ranges
• request exact DMA-frame rights and alignment from memd, use the kernel-reported physical range only for device descriptors, and map the already-backed frame capability through vspaced
• derive DMA data capacity from the smaller canonical read/write IPC fragment, advertise only the complete 512-byte blocks that fit, and encode no padded transfer tail
• retire and reject caller-supplied capabilities on startup, lifecycle, and provider calls because those protocols require no call-time authority
• negotiate only supported Virtio features, validate device-selected queue and notification geometry inside the assigned BAR, and validate used-ring completion metadata before trusting DMA output
• require the actual common, notification, and device subregions to fit rather than imposing a driver-local minimum BAR size
• represent device-reported zero-capacity media without inventing a minimum disk-size policy
• keep driver validation and failure behavior documented for integration tests

Clean-Room Policy

EriX follows a strict clean-room philosophy:

• No external source code may be copied.
• No external Rust crates are allowed.
• No code generation tools that embed third-party code.
• All code must be authored within the project.

Violations will result in rejection of the contribution.

License

All EriX repositories are licensed under the ISC License.

Development Model

EriX development is modular, deterministic, reproducible, authority-explicit, security-first, and self-hosting oriented.

This repository follows the project roadmap and the validation rules documented in its own roadmap.

Validation

• cargo fmt --all -- --check
• strict clippy with warnings as errors
• standalone crate CI through ../integration/scripts/setup-component-ci-overrides.sh so internal Git dependencies resolve from exact commit pins without cross-repo path deps
• local unit tests for virtqueue layout, request framing, and read-only flag propagation
• full VM integration through the storage scenarios
• Cargo.toml pins lib-block with a full 40-character commit rev; local validation preserves that Git object in generated Integration caches without branch-head or synthetic-commit substitution

Dynamic Boot Artifact Evidence

The image build packages drv-virtio-block as an ELF64 x86_64 ET_DYN executable with .erix_dynlink metadata in the signed dynlink-store and mirrors it under /lib/erix/dynlink with its required shared objects.

Startup remains deviced through procd dynamic driver creation with a role-derived executable identity; authority remains the transferred DEVICE_FRAME, instance service endpoint, and explicit memory peers. Dynamic packaging and filesystem mirror records are evidence and launch inputs only; they do not grant filesystem, loader, object-store, service-discovery, provider-bypass, block-device, or dynlinkd authority. drv-virtio-block receives only the documented startup endpoints, peers, and capabilities for its role.

Provider publication is a deviced lifecycle decision, not a driver-initiated registration. The authenticated successful DRIVER_START response proves that this physical instance initialized its MMIO and virtqueue state. Deviced then retains the already-assigned instance endpoint for cursor-based resolution by blockd. The driver receives no deviced registration peer and blocks on its provider endpoint instead of continuously polling an idle queue.

Required memd and vspaced calls use the same retained-completion contract. Only a successful memd allocation may return authority, and that reply must contain exactly the requested role-local frame receipt, frame type, rights, size, and alignment. Replies from vspaced may return no authority; any undeclared receipt is dropped and rejected.

The driver has no host-report authority. Startup outcomes travel through the typed driver-start reply, and block operations return typed transport or payload errors to their callers. Successful reads therefore add no serial-marker work or hidden diagnostic side channel.

After accepting a provider request, the driver retains the reply obligation through transient kernel BUSY/RETRY backpressure. It yields until delivery succeeds or the kernel returns a terminal result, without abandoning the authoritative reply after a service-local polling count.

Virtqueue completion polling checks the used index once and yields whenever it is unchanged so QEMU can run its device model under parallel VM load. A persistently unchanged index periodically repeats the queue notification for the same published chain without advancing the available index. Once a descriptor chain is submitted, the driver waits for exactly the next used-ring entry, validates its head identifier and minimum device-written length, and does not reuse device-owned DMA storage after a synthetic polling count. Future timeout recovery must reset or cancel the queue explicitly before releasing that storage.

The queue depth is the smallest power of two that holds the driver's one three-descriptor request. Queue memory is cleared before the queue is enabled, device reset completion is observed before negotiation continues, and the queue-selected notification register is computed with checked arithmetic and required to fit the mapped BAR. A zero notification multiplier is accepted as the Virtio-defined shared-notification-register encoding; non-zero values must be even powers of two for the feature set this driver negotiates.

Startup, lifecycle, and provider calls carry no call-time authority. Any unexpected complete receipt is retired before the call is rejected; malformed receipt state or failed cleanup terminates the process so residual authority cannot remain usable. The startup-assigned DEVICE_FRAME and allocated DMA frame capabilities are dropped immediately after their mappings are established, and any drop failure aborts initialization.

Governance Principles

drv-virtio-block governance is scoped to the virtio block driver role and its assigned hardware/provider authority.

The scoped governance rules are:

• It must be started and supervised through deviced and procd, not as an independently discovered public service.
• It uses only the device, service, root-vspace, and exact memory-peer capabilities explicitly installed at startup.
• It keeps hardware-specific behavior inside the driver while leaving device-matching policy to deviced.
• It rejects malformed device state and unexpected authority instead of broadening access.

Authority Boundaries

• drv-virtio-block does not receive named, filesystem-provider, or peer-driver authority.
• New hardware access requires explicit manifest, startup, and integration-test coverage.

Contact

Development occurs in EriX organization and discussions happen in issues and design documents.

No decisions are considered valid without documented rationale.

Maintainers can be reached via email: admin@erikinkinen.fi.