# <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).