AMD IOMMU: the engineering reference

Alignment: frames versus requests

The leaf size defines the frame boundary. A 2 MiB frame must begin at a multiple of 2 MiB; 4 KiB alignment alone is insufficient. Alignment is a minimum boundary requirement, not a maximum. A 1 GiB-aligned address also satisfies the smaller alignments.

Swipe or scroll horizontally to see every column.

Check base % pageSize == 0. Translation preserves address % pageSize and combines it with the mapped base. For example, a request at 0x1234 can address byte 0x234 in a 4 KiB page. Rejecting this request merely because it is not 4 KiB aligned would break ordinary byte-addressed DMA.

Page-table allocations in this teaching model are 4 KiB aligned and contain 512 eight-byte entries. A table pointer and a large data-frame pointer have different alignment rules. Entry addresses themselves advance by eight bytes. Hardware physical-address width, supported formats and permissions remain separate checks.

Swipe or scroll horizontally to see every column.

Mixed sizes: work through the offset twice

Choose a 4 KiB guest leaf at GPA 0x801000, a 2 MiB host frame at SPA 0x12000000, and guest offset 0xABC. The guest result is 0x801ABC. Its host page starts at 0x800000; the host offset is 0x1ABC. The final address is 0x12001ABC. Requiring the guest base itself to align to 2 MiB would incorrectly reject this valid mapping.

The lab allocates one host data leaf per context. When the host leaf is smaller than the guest leaf, only the host slice containing the configured guest address is mapped. A request outside that slice can fault even while remaining inside the guest page. When the host leaf is larger, its whole source interval must avoid the synthetic table allocations. These allocation limits belong to this example, not to AMD hardware.

Try the alignment controls. “Align entered bases” rounds down explicitly; Apply validates before replacing the active mapping.

Device, process and page entries

Swipe or scroll horizontally to see every column.

The raw DTE inspector and downloadable C++ expose the subset actually constructed by this lab. Host Mode 1–6 is configurable; real availability depends on the IOMMU capabilities, including supported host address-translation size. Guest Only selects host Mode 0 in this lesson. The model uses a four-level guest walk and caps physical addresses at 52 bits; neither value is a universal platform guarantee.

GLX and the device PASID capability are independent limits. This UI enforces the smaller capacity to prevent aliasing. A rejected UI configuration is a software guard, not a fabricated architectural event. DomainID identifies an IOMMU translation domain; DeviceID identifies a requester; PASID identifies a process address space. They are not interchangeable.

Read and write permissions are checked through the selected walks. Full execute/privilege semantics, accessed/dirty updates, atomic table changes, encrypted-memory ownership and every reserved-bit rule are outside the DMA lab’s model. The reference names them so a working demo is not mistaken for complete validation. dmakit, the executable AMD model behind the Linux DMA code lab, does update the host Accessed and Dirty bits and check each device access against the SEV-SNP RMP; it is not complete validation either.

Commands, events, PPR and GA are separate formats

Swipe or scroll horizontally to see every column.

Identical numeric codes in different record families have different meanings. Decode using the buffer type before interpreting the opcode. The event catalogue is the baseline set used in the companion lesson; the feature-dependent EVENT_COUNTER_ZERO, GUEST_EVENT_FAULT, VIOMMU_HARDWARE_ERROR, RMP_PAGE_FAULT and RMP_HARDWARE_ERROR records also appear in §2.5. Their fields and recovery paths must be interpreted using the corresponding feature definitions. They are not injected by this baseline lab.

Command sequencing and fault diagnosis have interactive examples. Selected memory-fault words and the GA codec are packed encodings; most displayed ring records remain semantic teaching records.

Safe mapping changes and PCIe requests

1. Gate affected DMA and retain ownership of the old backing memory while requests can still use it.
2. Publish valid new table/configuration contents with the platform’s required coherency and ordering operations.
3. Invalidate the appropriate IOMMU state. If the device holds ATS translations, invalidate its ATC as well and account for acknowledgments.
4. Observe command completion before reusing old memory or permitting a fresh translation and retry.

PCIe ATS obtains translation and permissions; PRI requests software service when necessary. Neither is a byte-copy operation. The NIC must advertise and enable the relevant features, and Bus Master Enable gates memory traffic. An untranslated rejected request, an unsuccessful ATS lookup and a page-service request have different reporting paths. Ordinary AT=10 traffic relies on a trusted device using its ATS result: §2.11 states that the IOMMU checks translated-request authorization but does not revalidate the SPA. Secure ATS instead returns a GPA and applies inline host translation. The mock’s provenance guard is a stricter teaching constraint.

The mock NIC is an intentionally small Ethernet descriptor model, not a vendor register set or a complete PCIe TLP engine. Splitting transfers at a mapped boundary, preventing bytes from the failing page, and preserving already completed bytes are the behaviours under test.

GA entries, control registers and recovery

“GA entry” is ambiguous. The interrupt-remapping table can contain a guest-capable IRTE; the guest APIC backing page stores pending interrupt state; the GA log contains notifications for software. These are three different structures. The lab’s basic interrupt remapper models a legacy entry, while the buffer page separately illustrates a guest virtual interrupt.

Swipe or scroll horizontally to see every column.

Example: DeviceID 0x0200, GATag 0x1234 → word 0x1000020000001234 → memory bytes 34 12 00 00 00 02 00 10. The vector is not encoded in this log entry. Revision 3.11 specifies one GA log opcode here; other opcode values must not be presented as invented GA types. Encode and decode a record.

The guest-capable IRTE includes controls such as GuestMode, IsRun and GALogIntr, as well as the guest APIC backing-page reference and tag. Guest-capable 128-bit IRTE formats differ from the legacy 32-bit format; select and validate them according to the enabled GA/GAM and other capabilities. With an eligible interrupt and a non-running guest, pending state is recorded in the backing page and enabled GA logging notifies the hypervisor. A running guest uses the applicable delivery path instead. Consuming a notification does not service the vector.

Swipe or scroll horizontally to see every column.

Length trap: GA has eight-byte records but GALogLen=8 still allocates 4 KiB: entries = 2^(Len+1). Do not reuse the command buffer’s entry-count formula for GA. The eight-slot illustrations are intentionally small and are not legal hardware allocations.

After overflow

Preserve available records and follow §2.7.4: wait for GALogRun=0; disable GALogEn; adjust the allocation and Head/Tail only while stopped; clear GALOverflow with W1C; then re-enable logging and configure GAIntEn. Reconcile pending guest interrupt state because lost notifications cannot be recovered by moving a pointer. Restarting the log neither replays lost entries nor completes guest EOI. The mini-lab stops at its capacity boundary instead of emulating all overflow races.

48882 coverage map and implementation boundary

Swipe or scroll horizontally to see every column.

Use the same test scenario vocabulary across implementations—requester, address space, input address, access, result and evidence—but keep architecture-specific encoders separate. A passing educational test proves its stated assertion; it does not establish whole-spec conformance.

Model and reusable C++ review · Detailed Arm comparison

Sources and revision

Reference baseline: the April 2026 rev 3.11 PDF; AMD IOMMU Specification 48882, revision 3.11, April 2026, especially §§2.4–2.7 and the MMIO register definitions. The link opens AMD's own PDF. All examples on this page are independently written.

Implementation cross-check: Linux AMD IOMMU types and driver sources. Driver implementations are useful evidence, but capability-dependent architectural rules come from the specification.