# 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
[`_template.md`](_template.md) for the blank form and
[`virtio-net.md`](virtio-net.md) 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](_template.md) -- the blank three-part form for a new
  device page.
- [virtio-net](virtio-net.md) -- the in-tree modern virtio-net PCI NIC: the
  worked first example, sourced from the kernel virtio transport and the
  public virtio specification.
- [NVMe](nvme.md) -- 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)](aws-nvme.md) -- 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)](azure-disk.md) -- 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)](gcp-storage.md) -- 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](gvnic.md) -- 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.