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 Specification

Copy this file to docs/devices/<device>.md, set the front matter (status, description, last_reviewed, topics), add the page to docs/SUMMARY.md, and fill in the three sections below. Document only the subset the driver actually implements; cite, do not transcribe, the full spec.

1. Spec basis

  • Device: name, PCI/MMIO class and IDs (vendor/device), instance shapes.
  • Authoritative spec(s): name, version, and source (URL or ref). For open vendor devices without a published register spec, cite the upstream open-source driver and any datasheet as the basis of record, and say so explicitly.
  • Reference driver(s) (optional): upstream implementations cross-checked for behavior.

2. Wire format (relevant subset)

  • Registers / BARs: BAR layout, register map offsets, doorbell offsets the driver reads or writes.
  • Queues / rings: queue kinds (admin/management vs I/O), ring layout, sizes.
  • Descriptor + completion formats: the descriptor and completion entry fields the driver encodes/decodes, including flags and status codes.
  • Admin / management commands: feature negotiation, identify/configure, and lifecycle commands the driver issues.

3. capOS mapping

  • Authority gate: how the device is enumerated, claimed, and bound through the reviewed userspace-driver hardware-authority gate and the device-manager ownership ledger.
  • DeviceMmio: which BAR ranges are mapped, with what page attributes (device-uncacheable, NX), and how register/doorbell writes are scoped.
  • Interrupt: MSI/MSI-X vector binding, completion-IRQ waiter model.
  • DMAPool: queue/buffer DMA allocation, the selected DMA backend (direct IOMMU vs labeled bounce buffer), quiesce/scrub-before-reuse rules, and the host-physical-address / IOVA non-exposure policy.
  • Fail-closed / validation rules: stale-generation rejection, BAR bounds, doorbell scoping, malformed-descriptor handling, release/reset/driver-death teardown.
  • QEMU-emulable vs hardware-only: which parts are end-to-end provable in QEMU (and the make run-* target) versus hardware-only (host-conformance gate now, deferred live proof when the hardware is provisioned).