# K1421–K1425 PCI ECAM address contract

An ECAM window is a caller-owned physical MMIO resource described by an aligned
base, whole-MiB size, and inclusive first/last bus numbers. Construction checks
that the bus span fits the resource and that `base + size` does not overflow.
It does not map the resource. The caller must verify the DTB host node and keep
the mapping alive while reading configuration space.

For bus `b`, device `d`, function `f`, and DWORD register `r`, the physical
address is `base + ((b - first_bus) << 20) + (d << 15) + (f << 12) + r`.
The request is valid only when `first_bus <= b <= last_bus`, `d < 32`, `f < 8`,
`r < 4096`, and `r` is DWORD aligned. All arithmetic and the four-byte access
must stay inside the declared window. Validation completes before a logical
claim is published.

The logical claim table owns at most one claim per configuration DWORD. A
successful claim adds exactly one entry; release removes exactly that entry.
Duplicate, full-table, out-of-range, and overflow errors leave all entries and
the count unchanged. A rejected request never authorizes a volatile MMIO read.

The positive example uses the QEMU `pci-host-ecam-generic` resource at
`0x40_1000_0000`, 256 MiB, buses 0–255. Bus 0, device 1, function 0,
register 0 resolves to `0x40_1000_8000`. The negative example uses an
explicit one-bus fixture at the same base with buses 0–0 and 1 MiB: bus 255
returns `BusOutOfRange`, preserves the existing bus 0 claim, and performs no
physical read. QEMU's ordinary DTB declares buses 0–255, so bus 255 is not an
out-of-range input for that unmodified resource.

The local model and unit tests establish address and logical ownership rules.
They do not establish physical MMIO mapping, guest observation, or product
Image integration. K1425 requires those measurements in an isolated guest
candidate before development guest acceptance can be recorded.