# Virtio PCI common configuration contract (K1466–K1470)

This bounded prototype follows [Virtio 1.3, sections 4.1.3–4.1.4.3](https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html). The conventional PCI capability walker and memory BAR decoder must first validate the PCI function. This stage accepts only a memory BAR; an I/O BAR remains outside the AArch64 guest prototype.

## Discovery and ownership

- A common configuration candidate is a vendor capability (`0x09`) with type `VIRTIO_PCI_CAP_COMMON_CFG` (`1`) and at least the 16-byte capability header. Larger capability lengths are valid. A reserved BAR index is ignored. The caller supplies the validated BAR for the selected index.
- The common configuration offset is four-byte aligned. Its advertised length must cover the base fields through `queue_device` (0x38 bytes). Checked arithmetic proves that the advertised range lies within the BAR, while the model maps only the first 0x38 bytes. The caller establishes Device memory attributes before register access.
- One generation-tagged owner claims a PCI function and common configuration region. Duplicate functions and overlapping regions fail without changing existing claims. Reusing a function after release gives a new generation; stale handles cannot operate on it.

## Register and lifetime rules

- Common configuration fields use little-endian 8-, 16-, or 32-bit aligned accesses. The physical bridge never writes read-only fields (`device_feature`, `num_queues`, `config_generation`, `queue_notify_off`). Queue addresses are two independent 32-bit words at offsets 0x20, 0x28, and 0x30.
- The caller must observe `device_status == 0` and `queue_enable == 0` after device reset before publishing another queue or releasing its claim. A live queue or nonzero status keeps the claim owned. `queue_enable` is written only with `1` after queue fields and memory are ready; it is never cleared by a driver write.
- Feature selection, accepted bits, notification routing, and queue memory publication are later contracts. The local model records capability bounds and reset ownership; it does not claim physical MMIO or DMA evidence.

## Guest acceptance

K1470 requires an isolated guest to find a real modern Virtio PCI function, validate its common capability and memory BAR, read the common configuration fields through Device mapping, perform a disposable bounded queue setup, observe enable and DRIVER_OK, then reset, observe zero status and queue enable, release queue memory and ownership, and return. Direct and UEFI profiles at 256, 512, and 1024 MiB must pass. Product release acceptance remains separate.