Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Device Driver Specifications

The pages under docs/devices/ are per-device driver references. Each one captures the authoritative hardware/protocol specification a capOS device driver is built from, the subset of that specification the driver actually implements, and how the device binds onto capOS’s reviewed userspace hardware-authority gate.

A device page is a navigational / provenance document, not a re-spec. It cites the spec (name, version, source), summarizes only the wire-format subset the driver actually implements, and points into the implementation with file + symbol references (the function, type, or constant name – not line numbers, which drift) so the doc maps to the code. Do not copy the full spec or dump exhaustive register tables: if something is in the spec and not specially handled by the driver, link to it rather than transcribing it.

Depth scales to maturity and risk. Transitional or stable in-kernel drivers get a concise provenance map – do not over-document stable code. Actively developed or higher-risk drivers (new DMA paths, cloud NICs/storage behind the userspace-authority gate) get fuller treatment.

These pages are the provenance map of record for device-driver work. Landing or modifying a device driver requires creating or updating the matching docs/devices/<device>.md page as part of the same change; it is part of that change’s acceptance, not an afterthought. Each page reads as a reader-facing capability map – the driver’s currently-implemented subset in present tense and what is future or not yet implemented – not a per-slice development log.

docs/devices/ is distinct from the other device-adjacent doc areas:

  • docs/research/ holds OS-design research deep-dives (capability models, IPC, scheduling, IOMMU prior art). It informs architecture; it does not specify a concrete device.
  • docs/*-design.md and docs/proposals/ describe capOS subsystem designs (the DMA isolation model, the device-manager refactor, the userspace-driver authority gate). They define the framework a driver binds into; a device page maps one device onto that framework.
  • docs/devices/<device>.md is the narrow, per-device contract: which external spec, which wire-format fields, and which capOS grants and fail-closed rules the driver depends on.

Three-part structure

Every device page follows the same three sections. See Device Spec Template for the blank form and virtio-net for a worked example.

  1. Spec basis – the authoritative specification(s) the driver is built from: name, version, and source (URL or ref). For open vendor devices without a freely published register spec (for example AWS ENA or Azure MANA), cite the upstream open-source driver and any published datasheet as the basis of record.
  2. Wire format (relevant subset) – the registers / BARs, queues / rings, descriptor and completion formats, and admin / management commands that the driver actually implements. Document the subset, not the whole spec.
  3. capOS mapping – how the device binds (note transitional in-kernel status and any pending userspace move where applicable); its DeviceMmio / Interrupt / DMAPool usage; the fail-closed and validation rules it relies on (stale-generation rejection, bounds checks, doorbell scoping); and what is QEMU-emulable versus hardware-only. The last point drives whether the driver carries a QEMU proof or a host-side conformance gate plus a deferred live proof.

Pages

  • Device Spec Template – the blank three-part form for a new device page.
  • virtio-net – the in-tree modern virtio-net PCI NIC: the worked first example, sourced from the kernel virtio transport and the public virtio specification.
  • NVMe – the queue-base/PRP register and descriptor subset the conditional kernel on-notify DMA validator scans on the NVMe doorbell path, plus the no-IOMMU brokered-DMA correction (validator mechanism + bounded hostile-scan proof + brokered controller bring-up).
  • AWS Nitro EBS (NVMe storage) – the AWS cloud-shape classification on top of the shared NVMe foundation: EBS exposed as NVMe namespaces, the Nitro IOMMU-availability DMA-backend policy, and the local make run-pci-nvme precursor proof.
  • Azure managed disk (NVMe storage) – the Azure cloud-shape classification on the same shared NVMe foundation: Azure Boost managed disks exposed as NVMe namespaces, the Azure IOMMU-availability DMA-backend policy, why the older-family Hyper-V/SCSI path is out of scope, and the local make run-pci-nvme precursor proof.
  • GCP Persistent Disk (storage) – the GCP cloud-shape classification on the same shared NVMe foundation: PD exposed as NVMe namespaces on current GCE generations, the GCE IOMMU-availability DMA-backend policy, why the older-family virtio-scsi PD path is out of scope, and the production storage-bind proof (cloud-prod-storage-bound-local-proof) that precedes a billable live-GCE storage driver bind.
  • GCE gVNIC – a grounding map for the Google Virtual NIC: spec basis from the public gVNIC docs and the GVE Linux driver, the wire-format subset (BARs, admin queue, MSI-X interrupt classes, GQI/DQO formats, QPL/RDA addressing, reset) a future reusable capOS driver would implement, and the DDF authority mapping. capOS has live-GCE inventory, admin-queue/register, bounded GQI/QPL raw-frame TX/RX, and typed Nic-adaptation proofs for the 1ae0:0042 PCI function, but no reusable gVNIC provider service, QEMU model, DQO/RDA path, or host conformance suite; it is a separate GCE portability lane, not a blocker for the virtio-net Web UI proof.