IOMMU / INTERACTIVE WORKING MODEL

IOMMU translation & DMA validation.

Trace a device request from its address space to memory—or to a fault.

AMD-style semantic model · up to four guest levels · configurable host levels · 4 KiB / 2 MiB / 1 GiB leaves · a synthetic Ethernet NIC and selected raw entry encodings.

Start with the translation path New to this? Follow one prepared request first →

What claims does this page make? 3 points

Spec rule: Device Table Entry fields, Host Mode 0 to 6, GLX and PASID widths, AT encodings, 16-byte IO_PAGE_FAULT records and the command and PPR queues follow AMD IOMMU spec 48882 rev 3.11 (Tables 7, 11, 15 and 57, section 2.2.6.3).
Platform assumption: PASID width is also limited by the device, the IOMMU's GLXSup and the kernel driver, and these presets assume the needed features are present and enabled.
Teaching model: addresses, tables, the NIC, ring sizes, 256-byte chunks and the ATS cache are synthetic fixtures, not a conformance test or silicon behaviour.

New to IOMMU? Start here

An IOMMU controls which memory a device may access. Begin with the default mapping, select Translate, then step through DMA. Compare the two fault examples to see why an invalid page copies no bytes.

DMA: Direct Memory Access: a device reads or writes system memory.
PASID: Process Address Space ID: selects an address space for a device request; it is not itself a memory address or a VM identifier.
GVA / GPA / SPA: Guest Virtual / Guest Physical / System Physical Address. Guest Only ends at GPA = SPA; nested translation adds a host mapping.
DTE / GCR3: The Device Table Entry holds translation controls. The GCR3 tables select a guest page-table root using the PASID.
Leaf / offset: A leaf entry names the final page. The offset selects a byte within that page. Larger pages end the walk earlier.
ATS / IRTE: Address Translation Services queries a translation. An Interrupt Remapping Table Entry routes a device interrupt; it does not translate data addresses.

START HERE

01 / Choose the translation path

A device sends a memory address. The IOMMU checks a device entry (DTE), follows a set of lookup tables, and either finds an allowed memory location or stops the request. A page is a mapped block of 4 KiB, 2 MiB or 1 GiB; a page entry is an 8-byte record pointing to another table or the final block.

Translation path

Which path would I use?

Host only

Give a device its own DMA address space. Host tables map a device GPA / IOVA to RAM and enforce isolation. No PASID guest lookup is needed.

V=1 · TV=1 · GV=0 · Mode=1–6

Guest only

Use a PASID-selected address space without a second physical remap. Guest tables map GVA to GPA, and GPA already is SPA.

V=1 · TV=1 · GV=1 · Mode=0

Guest + host

Give a process inside a VM a virtual address space, while the host controls which RAM the VM may use. Guest-table memory also needs host translation.

V=1 · TV=1 · GV=1 · Mode=1–6

These presets assume the required hardware features and global enables. “Guest” names the first translation stage; it does not mean a VM is required for every use. Effective PASID width is the smallest of the PCIe device capability, the IOMMU’s PASmax and its GCR3 capacity. The device capability is separate from the DTE.

02 / Build a mapping

Runs locally in your browser

Choose up to eight PASID contexts. Each maps the chosen device virtual page to a separate GPA and system physical page, illustrating separate address spaces. With mixed page sizes, only the region covered by both stages is accessible. This demonstration is not a hardware isolation test or proof.

Mapped frame bases must align to their leaf size. A DMA address may include any byte offset within that mapping; it does not need to be page aligned. Table pages in this model remain 4 KiB aligned.

Alignment and AMD 48882 details · Compare Arm SMMUv3

Guest virtual address to mapGuest physical page baseSystem Physical Address (SPA) · page baseC++ / CPU linear page base (optional)Guest data page sizeHost Mode / root levelGuest Only uses Mode 0 (identity). Mode 7 is reserved. Real hardware must advertise the selected depth through HATS.Skip host levels (optional)NextLevel jumps over these directory levels. Their address bits must be zero.Host data page sizeGCR3 depthPCIe device PASID capabilityMock NIC capability; independent of GLX.IOMMU GCR3 capacityGLX 1 · 18 bitsDemo PASID range16 bits · 65,536 PASIDs · IDs 0–65,535PASIDs with mappings (decimal or 0x)

Skipped levels retain the original address bit positions; they are not shifted or packed together. A data leaf cannot be skipped. Nested Mode 1 is not offered by this lab because its guest tables are allocated above 2 MiB; the architecture itself permits Mode 1.

How mixed page sizes are mapped

Each PASID has one guest data leaf and one host data leaf. If the host page is smaller, only the host-sized region containing the configured guest address is mapped. Page-table storage always uses 4 KiB blocks. Guest Only bypasses the host stage; Host Only bypasses the guest stage.

How the device and IOMMU limits combine

The PCIe PASID capability describes the device’s maximum PASID width. GLX selects the IOMMU’s GCR3 table capacity. This demo uses the smaller range as a software guard against aliases. With a 16-bit NIC and GLX=1, the effective capacity is 65,536 PASIDs (IDs 0–65,535), even though the two-level GCR3 structure can represent more.

GLX capacity: 0 → 9 bits; 1 → 18 bits; 2 → 20 bits. The demo assumes the IOMMU hardware supports the selected GLX and a 20-bit PASID ceiling. A platform may impose further limits. AMD 48882 §2.2.6.3 specifies that GLX=0 ignores PASID bits above bit 8, and GLX=1 ignores bits above bit 17. Software must choose enough levels for the PASIDs it uses. This demo rejects such aliases before issuing a request; that rejection is not an emulated hardware IO_PAGE_FAULT. These mock capabilities do not read your hardware.

Linux PCIe PASID capability handling · AMD GCR3 table capacity

In this example, the System Physical Address (SPA) of the backing memory is given, and the addresses are synthetic. The C++ linear address is a separate CPU-side buffer association, not a pointer cast or a CPU page-table walk. Values are synthetic; no buffer is allocated at these addresses.

03 / Configure the PCIe device

Mock configuration space

Capabilities describe what the NIC supports; control registers enable those features. “+” means a bit is set and “−” means it is clear, as in lspci output. These controls apply immediately; the device width above changes when you apply the mapping.

DMA and PASID controls Command: Bus Master Enable PASIDCtl: Enable PASIDCap: Execute Permission Supported PASIDCap: Privileged Mode Supported PASIDCtl: Execute Permission Enable PASIDCtl: Privileged Mode Enable

Enabling these permissions does not turn this demo’s user-mode data transfers into instruction fetches or privileged requests.

Address Translation Services ATSCtl: Enable IOMMU DTE.I: Allow ATS responses ATSCap: Page Aligned RequestInvalidate queue depth (1–32)

STU=0 selects a 4 KiB minimum translation unit for ATS. Data-page leaves may still be larger; STU does not set their size. Queue depth 32 uses encoded value 0. Queue processing and cache invalidation are not simulated.

Offsets are relative to each extended capability: PASID ID 0x001B and ATS ID 0x000F. The Command register is at configuration-space offset 0x04. Unused bits are zero in this selected-field example.

Linux PCIe register definitions · Linux PASID/ATS enablement · pciutils decoding

Ask for a translation with ATS

This query uses the current request below and returns a translation with read/write permissions. It copies no packet bytes and does not add an IO_PAGE_FAULT entry for a failed page lookup. This is a standalone probe; it does not warm the DMA cache. Choose ATS / pretranslated DMA in section 05 to observe the full query, cache and transfer sequence.

A selected DTE with V=1 and TV=0 is not a page-table lookup failure. AMD 48882 rev 3.11 Table 64 classifies that ATS request as INVALID_DEVICE_REQUEST with TR=1; this model stops without a response or event. AMD IOMMU Table 64.

Enable ATSCtl and DTE.I, then issue a query.

Guest walk: PML4 / 48-bit teaching profile · independent of host Mode

04 / Send a DMA request

Input addressPASID sent by this requestPick one configured above, or enter an unmapped ID to test a fault.AccessInject a fault

05 / Observe the DMA transfer

Mock vDMA · browser memory only

A receive operation (RX) writes packet bytes from the NIC into RAM. A transmit operation (TX) reads RAM into the NIC. Both use the request address, PASID, access and fault settings above.

Choose how the NIC addresses memory

DMA address protocol Missing-page recoveryAvailable in ATS mode. One outstanding page-request group.

Untranslated, translated and pretranslated: what changes?

Operation	AT[1:0]	Address and effect
Untranslated memory DMA	`00`	NIC sends the original GVA or GPA/IOVA. The IOMMU translates it and checks access before memory is touched.
ATS translation request	`01`	NIC asks the translation agent for an address and permissions. This query copies no payload bytes.
Translated / pretranslated memory DMA	`10`	NIC sends an SPA obtained through ATS and enforces the cached permissions. The IOMMU does not repeat the page-table walk for this permitted device.
Reserved	`11`	Not selectable in this demonstration.

AT is a two-bit field. AT[1]=1 in the translated encoding 10; the value 01 means a translation request. AMD calls the device-translated address “pretranslated”—it is not a fourth kind of memory DMA. An address calculated by software is not automatically an ATS translation.

Untranslated DMA and ATS can use the same guest and host tables. What changes is when translation occurs: during the memory request, or earlier so the NIC can cache the result. Cache entries must be invalidated when mappings or permissions change. This demo starts with an empty cache on each prepare/configuration change.

AMD PCIe AT encodings · AMD 48882: pretranslated address, Definitions and §1.1

DMA directionRead sourceDMA length (1–65,536 bytes)NIC payload byte pattern (hex)Up to 32 bytes, repeated to fill the transfer. For reads choose “Repeat my pattern” to prepare the mock RAM source.

Byte preview: first 64 bytes (offsets 0–63). The counter covers the full descriptor. Each page needs a valid translation and permission before its bytes move. ATS mode uses the NIC’s cached translation for AT=10 requests. A failed page copies zero bytes; earlier completed pages are not rolled back.

NIC packet buffer

RAM · before transfer

RAM · at this event

Hex bytes correspond to consecutive request offsets. “—” means no backing address has been resolved for that byte. RAM starts with byte[offset] = offset mod 256, or your repeating pattern when patterned reads are selected. Highlighted cells were written or read. Each run starts from the same mock memory. Other PASID buffers are separate allocations.

Scenario presets and predicted outcome +

Compare two fault cases

These examples select untranslated DMA (AT=00), enable the NIC and choose a mapped PASID. Your page sizes and read/write choice stay selected. Use the ATS examples above to compare recovery.

Start on an invalid page

The first page fails its presence check. 0 of 16 bytes copied.

Valid page → invalid page

Start 8 bytes before a valid page ends. Copy those 8 bytes, then reject the next page. 8 of 16 bytes copied; 0 from the invalid page.

Predicted outcome · before playback

The breakdown predicts the configured descriptor. The progress bar and byte display below show only the events reached during playback. An earlier successful page is not rolled back when the next page faults.

IOMMU event buffer

Logging enabled · DTE SA=0 / SE=0 · memory requests, not ATS queries. The eight slots are a compact visual teaching buffer, not a hardware-valid event-buffer size. A page fault appends a 16-byte IO_PAGE_FAULT record. This is the IOMMU’s event log, separate from the NIC’s interrupt-remapping table. Successful DMA does not create a fault event.

Teaching model: one descriptor, chunks of at most 256 bytes that never cross a 4 KiB boundary or a mapping, and no real packets or hardware. Earlier successful chunks remain copied if a later chunk faults; this is not a model of PCIe timing, descriptor rings or a particular NIC.

06 / Inspect the device and roots

Device Table Entry · 256 bits / 32 bytes

The Requester ID chooses this record. It supplies the roots and permissions; it does not contain the page mapping itself.

Expand DTE fields and bit positions

Find the page tables for this PASID

A PASID identifies an address space. The GCR3 tables act like a directory: the PASID selects a guest page-table root. They do not translate the data address yet.

DTE GCR3 root 0x180000 SPA

↓ selected GCR3 depth

↓ selected entry contains a GPA (equals SPA in Guest Only)

Guest page-table root PML4 → PDPT → PD → PT

Host root

DTE Host Root Pointer 0x100000 SPA

↓ Mode=6

PDE · level 6
PDE · level 5
PDE · level 4
PDE · level 3
PDE · level 2
PTE · level 1 → SPA frame

The selected Host Mode chooses the root level. NextLevel points to the next directory or leaf, allowing the configured zero-index levels to be skipped. A 4 KiB data leaf is at level 1; 2 MiB and 1 GiB leaves end at levels 2 and 3. In Guest + Host, guest-table storage uses separate 4 KiB host mappings.

FOLLOW THE POINTERS

07 / See the address map

You do not need to memorize the hexadecimal numbers. Follow the named tables, select a card, and see which slot points to the next table or data frame. These cards use the same walk as the detailed trace below.

08 / Walk the tables

Choose a step to inspect its entries, or step through the request. In Guest + Host, guest and subordinate GCR3 table fetches also need host translation. In Guest Only, GPA already equals SPA. Expand any entry to inspect its bits and mocked memory.

All table accesses in this walk

09 / Investigate faults

A page fault means the lookup or permission check could not complete. It does not automatically mean the hardware is broken. The failing entry tells software what is missing or disallowed.

Missing mapping

The next 4 KiB page has no entry. The original page remains accessible.

Read-only page

A read succeeds; a write is rejected. Present and writable are different checks.

A table is missing

In a nested walk, the host must map the guest table itself before its entry can even be read.

Examples reset to a known mapping so their outcomes are reproducible.

Real software may install a mapping, adjust authorized permissions, invalidate cached translations and retry through an appropriate protocol. The address walk shows a teaching diagnosis. Running DMA also encodes the selected IO_PAGE_FAULT record; neither action models automatic hardware recovery.

10 / Follow the interrupt path

An IRTE belongs to an interrupt-remapping table. It does not translate the DMA address and is not another guest or host page-table level. This simplified legacy-style table uses 4-byte entries. The independent probe below previews routing; the DMA demonstration delivers a completion interrupt only after a successful transfer. Its generated C++ packs and decodes the selected IRTE fields.

Synthetic NIC MSIDTE interrupt-table root
0x1C0000 SPAIRTE[index]Vector + APIC destination

IRTE index (3 and 7 present)Vector (decimal)APIC destinationRemapping

Disabled or absent entries stop this educational interrupt path. Other delivery modes, guest virtual interrupts, interrupt-fault event records and real MSI message decoding are outside this model.

Model boundaries and public references

Validity of this model: this is an executable teaching model of selected AMD IOMMU behaviours, not a device emulator or conformance test. The generated C++ and browser walker are compared for translation paths, page sizes, permission faults, skipped levels and ATS/PRI scenarios. Agreement between two implementations is useful regression evidence; it does not prove agreement with silicon. To program an emulated one by hand, open the QEMU labs: QEMU's AMD, Arm and RISC-V IOMMUs in your browser.

The C++ rejects inconsistent packed/decoded fields, misaligned supported leaves and a guest walk without a leaf. Host entries are limited to read-enabled pages; raw entry editing is not a complete architectural parser. Command execution is serial, PRI handles one group, and timing, coherency, A/D updates and feature-dependent errors are outside its scope. Read the validation scope and reuse guide.

The guest uses canonical 48-bit virtual addresses and four 9-bit indices (PML4E, PDPE, PDE, PTE). Host Mode selects 1–6 levels; their shifts are 12, 21, 30, 39, 48 and 57; only seven top-index bits are available in a 64-bit input. The mapping builder limits physical page bases to 52 bits.

The GCR3 root is an SPA in this model; a valid Level 1 GCR3 entry holds the GPA of the guest PML4. Subordinate GCR3 pointers are GPAs; the example identity-maps their backing pages when host translation is active. GLX=0/1/2 selects one/two/three GCR3 levels. Index slices are PASID[8:0], [17:9], and [19:18]. This demo combines the PCIe device’s configured PASID width with the GLX capacity and uses the smaller range as a software guard against aliases. A 16-bit PASID fits in two levels; GLX=2 can still be used with a 16-bit width, with a zero top index. Only explicitly mapped PASIDs have valid leaves. Guest table fetches pass through host translation in the nested path; Guest Only uses GPA = SPA. ATS mode uses a small semantic IOMMU translation cache for permission responses; microarchitectural TLB behaviour is not modelled. ATS mode adds a small NIC address translation cache (ATC).

All pointers, BDFs, domains and tables are synthetic. Raw words encode a selected page-entry subset of AMD 48882 rev 3.11. Host IR/IW/PR/NextLevel and guest P/RW/US use different bit positions. Guest A/D are pre-set, host HAD is zero, and unmodelled optional features remain off. PCIe and ATS controls shown on this page are configurable. The walker uses decoded teaching fields alongside the displayed packed words; it does not parse arbitrary hardware memory. This is not a complete hardware implementation. The address walker uses teaching diagnostics; mock DMA adds the selected IO_PAGE_FAULT encoding. The model omits other architectural events, access/dirty updates, privileged access details, nonstandard page sizes, real PCIe invalidation packet timing and memory coherency protocols. The mock verifies ATC provenance before translated DMA; this is a teaching safeguard, not ordinary AMD hardware revalidation of an SPA (§2.11). ATS mode models a per-descriptor 4 KiB ATC and semantic PRI/PPR page-in handshake; packed command/PPR words, real PRI registers, timeouts, concurrent requests and secure ATS are omitted. Command and PPR rings model ownership, fetch, completion and wraparound. A per-session IOMMU cache is also invalidated; invalidation scope is conservatively the whole mock session. Mapping changes discard the mock cache. Control/DTE protocol errors are stopped by this teaching model; their full architectural event handling is not emulated. The address inspector validates one address. The mock DMA demo splits a 1–65,536 byte transfer at the active guest/host page boundaries, in requests of at most 256 bytes, and checks each chunk; it is not a hardware protocol implementation. Arm SMMU uses different structures and is not represented by these AMD-specific names.

AMD IOMMU specification 48882 rev 3.11 (publisher PDF): Tables 7–8, 15, 17–18, 20, 26–29 and 57; §2.2.7.1. Bit displays below are independently constructed examples, not reproduced specification figures.
Linux AMD IOMMU definitions: DTE, host modes, GCR3 and interrupt-remapping fields
Linux AMD IOMMU implementation: GCR3 tables and domain setup
Linux DMA mapping guide: CPU, DMA and physical addresses

11 / Run the matching C++ example

Generated from the applied mappings, GCR3 tables, request, faults, NIC, DMA length/payload and interrupt settings. Run it to reproduce the complete mock transfer from its initial memory state. Edit manually to explore further, or regenerate to return to the playground state.

Edit the source, then run the tests. Compilation provided by Compiler Explorer. Clicking Run sends the code to that external service. Use only public, non-confidential code.

Keep C++ synced with playground

Editable source · selected file

#line 1 "types.hpp"
#include <algorithm>
#include <array>
#include <cstdint>
#include <iomanip>
#include <iostream>
#include <map>
#include <optional>
#include <stdexcept>
#include <string_view>
#include <vector>

namespace iommu_demo {
// 1. Address values: numeric addresses never become native pointers.
// Entry contains both a packed word and its decoded teaching fields.
// Host: PR bit 0, NextLevel bits 11:9, IR bit 61, IW bit 62.
// Guest: P bit 0, R/W bit 1, U/S bit 2, address bits 51:12.
// All guest A bits and leaf D bits are preset; this example omits A/D updates.
using Address = std::uint64_t;

struct Entry {
    Address target;
    Address raw;
    bool present;
    bool write;
    Address page_size;   // Zero means another table; otherwise 4 KiB / 2 MiB / 1 GiB.
    unsigned next_level; // Host directory NextLevel; zero for a leaf.
};

// Keep fault classification separate from human-readable diagnostics.
// PR describes presence; PE describes a permission failure on a present page.
struct PageFault : std::runtime_error {
    bool present;
    bool permission;

PageFault(const char* message, bool is_present, bool is_permission)
        : std::runtime_error(message), present(is_present), permission(is_permission)
    {
    }
};

constexpr std::size_t kPageSize = 4096;
constexpr std::size_t kEntryBytes = 8;
using RamPage = std::array<std::uint8_t, kPageSize>;
using EventRecord = std::array<std::uint32_t, 4>;
using Memory = std::map<Address, std::map<unsigned, Entry>>;

struct AtcEntry {
    Address input_page;
    Address spa_page;
    bool read;
    bool write;
};

struct PprRecord {
    unsigned group;
    Address page;
    bool write;
    const char* response;
};

} // namespace iommu_demo

#line 1 "scenario.hpp"

// CURRENT playground snapshot. Compatible with C++17/20/23 and draft C++26.
// Synthetic RAM only: no MMIO, hardware access or pointer dereferences.
// Selected AMD 48882 rev 3.11 encodings; guest A/D preset.
// Guest leaf: 4096 bytes; host leaf: 4096 bytes.
// One leaf per context per stage; a smaller host leaf maps only the selected guest region.
// Translation path: Guest + host: GVA -> GPA -> SPA.

namespace iommu_demo {
// 2. Applied UI configuration: roots, request identity and permissions.
constexpr unsigned host_mode = 6;
constexpr Address host_root = 0x100000ULL;
constexpr Address gcr3_root = 0x180000ULL;
constexpr Address device_table = 0x4000000ULL;
constexpr Address interrupt_table = 0x1C0000ULL;
constexpr unsigned requester_id = 512;
constexpr unsigned pasid = 42;
constexpr unsigned glx = 1;
// Device capability and GLX capacity are separate limits. Their minimum is a
// software range guard against aliases; it is not the hardware PASmax check.
constexpr unsigned pcie_pasid_width = 16;
constexpr unsigned iommu_glx_width = 18;
constexpr unsigned effective_pasid_width = std::min(pcie_pasid_width, iommu_glx_width);
constexpr unsigned pasid_capacity = 1U << effective_pasid_width;
constexpr unsigned max_pasid = 65535;
static_assert(max_pasid == pasid_capacity - 1);
constexpr Address input_address = 0x123456789ABCULL;
constexpr std::optional<Address> cpu_linear_page = std::nullopt;
constexpr bool write_access = false;
constexpr bool translation_valid = true;
constexpr bool guest_stage = true;
constexpr bool host_stage = true;
constexpr Address dte_words[]{0x6180000000100C03ULL, 0x300007ULL, 0x20000000001C000FULL, 0x0ULL};

// PCIe capability registers describe support; controls enable use of that support.
// Offsets +4/+6 are relative to their own PASID or ATS extended capability.
constexpr std::uint16_t pci_command = 4;
constexpr std::uint16_t pasid_cap = 4102, pasid_ctl = 1;
constexpr std::uint16_t ats_cap = 0, ats_ctl = 0;
// DTE.I is the IOMMU-side ATS gate (Q1 bit 32), separate from ATSCtl.Enable.
// AT is TWO bits: 00=untranslated memory, 01=translation query,
// 10=translated (AMD: pretranslated) memory, 11=reserved.
constexpr bool use_ats = false;
constexpr bool use_pri = false;
constexpr std::uint16_t pri_ctl = use_pri ? 1 : 0; // PCI_PRI_CTRL_ENABLE.
// PRI recipe assumes EPHSup, global PPREn/PPRLogEn, and one allocated request.
static_assert(!use_pri || ((dte_words[0] & (1ULL << 52)) && (pri_ctl & 1)));
// Command/PPR rings below use semantic records, not packed hardware encodings.
// The mock host accepts one group and restores only an injected missing leaf.

// 3. Sparse table memory. Each outer map key is a backing SPA.
// Missing slots contain zero. Guest and subordinate GCR3 targets are GPAs.
// GCR3 subordinate pages use identity host mappings in this example.
inline Memory host_tables{
    {0x100000ULL,
     {
         {0, {0x101000ULL, 0x6000000000101A01ULL, true, true, 0x0ULL, 5}},
     }},
    {0x101000ULL,
     {
         {0, {0x102000ULL, 0x6000000000102801ULL, true, true, 0x0ULL, 4}},
     }},
    {0x102000ULL,
     {
         {0, {0x103000ULL, 0x6000000000103601ULL, true, true, 0x0ULL, 3}},
     }},
    {0x103000ULL,
     {
         {0, {0x104000ULL, 0x6000000000104401ULL, true, true, 0x0ULL, 2}},
     }},
    {0x104000ULL,
     {
         {2, {0x105000ULL, 0x6000000000105201ULL, true, true, 0x0ULL, 1}},
         {4, {0x106000ULL, 0x6000000000106201ULL, true, true, 0x0ULL, 1}},
         {0, {0x107000ULL, 0x6000000000107201ULL, true, true, 0x0ULL, 1}},
     }},
    {0x105000ULL,
     {
         {0, {0x2000000ULL, 0x6000000002000001ULL, true, true, 0x1000ULL, 0}},
         {1, {0x2001000ULL, 0x6000000002001001ULL, true, true, 0x1000ULL, 0}},
         {2, {0x2002000ULL, 0x6000000002002001ULL, true, true, 0x1000ULL, 0}},
         {3, {0x2003000ULL, 0x6000000002003001ULL, true, true, 0x1000ULL, 0}},
         {16, {0x2010000ULL, 0x6000000002010001ULL, true, true, 0x1000ULL, 0}},
         {17, {0x2011000ULL, 0x6000000002011001ULL, true, true, 0x1000ULL, 0}},
         {18, {0x2012000ULL, 0x6000000002012001ULL, true, true, 0x1000ULL, 0}},
         {19, {0x2013000ULL, 0x6000000002013001ULL, true, true, 0x1000ULL, 0}},
     }},
    {0x106000ULL,
     {
         {0, {0x12000000ULL, 0x6000000012000001ULL, true, true, 0x1000ULL, 0}},
         {256, {0x13000000ULL, 0x6000000013000001ULL, true, true, 0x1000ULL, 0}},
     }},
    {0x107000ULL,
     {
         {385, {0x181000ULL, 0x6000000000181001ULL, true, true, 0x1000ULL, 0}},
         {386, {0x182000ULL, 0x6000000000182001ULL, true, true, 0x1000ULL, 0}},
     }},
};
inline Memory gcr3_tables{
    {0x180000ULL,
     {
         {0, {0x181000ULL, 0x181001ULL, true, true, 0x0ULL, 1}},
         {127, {0x182000ULL, 0x182001ULL, true, true, 0x0ULL, 1}},
     }},
    {0x181000ULL,
     {
         {42, {0x400000ULL, 0x400001ULL, true, true, 0x0ULL, 0}},
     }},
    {0x182000ULL,
     {
         {511, {0x410000ULL, 0x410001ULL, true, true, 0x0ULL, 0}},
     }},
};
inline Memory guest_tables_in_spa{
    {0x2000000ULL,
     {
         {36, {0x401000ULL, 0x401027ULL, true, true, 0x0ULL, 3}},
     }},
    {0x2001000ULL,
     {
         {209, {0x402000ULL, 0x402027ULL, true, true, 0x0ULL, 2}},
     }},
    {0x2002000ULL,
     {
         {179, {0x403000ULL, 0x403027ULL, true, true, 0x0ULL, 1}},
     }},
    {0x2003000ULL,
     {
         {393, {0x800000ULL, 0x800067ULL, true, true, 0x1000ULL, 0}},
     }},
    {0x2010000ULL,
     {
         {36, {0x411000ULL, 0x411027ULL, true, true, 0x0ULL, 3}},
     }},
    {0x2011000ULL,
     {
         {209, {0x412000ULL, 0x412027ULL, true, true, 0x0ULL, 2}},
     }},
    {0x2012000ULL,
     {
         {179, {0x413000ULL, 0x413027ULL, true, true, 0x0ULL, 1}},
     }},
    {0x2013000ULL,
     {
         {393, {0x900000ULL, 0x900067ULL, true, true, 0x1000ULL, 0}},
     }},
};

// Independent mocked CPU allocations for table pages, indexed by backing SPA.
inline const std::map<Address, Address> table_cpu_linear{
    {0x100000ULL, 0xFFFF900000000000ULL},  {0x101000ULL, 0xFFFF900000001000ULL},
    {0x102000ULL, 0xFFFF900000002000ULL},  {0x103000ULL, 0xFFFF900000003000ULL},
    {0x104000ULL, 0xFFFF900000004000ULL},  {0x105000ULL, 0xFFFF900000005000ULL},
    {0x106000ULL, 0xFFFF900000006000ULL},  {0x107000ULL, 0xFFFF900000007000ULL},
    {0x180000ULL, 0xFFFF900000008000ULL},  {0x181000ULL, 0xFFFF900000009000ULL},
    {0x182000ULL, 0xFFFF90000000A000ULL},  {0x2000000ULL, 0xFFFF90000000B000ULL},
    {0x2001000ULL, 0xFFFF90000000C000ULL}, {0x2002000ULL, 0xFFFF90000000D000ULL},
    {0x2003000ULL, 0xFFFF90000000E000ULL}, {0x2010000ULL, 0xFFFF90000000F000ULL},
    {0x2011000ULL, 0xFFFF900000010000ULL}, {0x2012000ULL, 0xFFFF900000011000ULL},
    {0x2013000ULL, 0xFFFF900000012000ULL},
};

struct Buffer {
    std::optional<Address> linear;
    Address gpa;
    Address spa;
    Address span;
};

inline const std::map<unsigned, Buffer> buffers{
    {42, {std::nullopt, 0x800000ULL, 0x12000000ULL, 0x1000ULL}},
    {65535, {std::nullopt, 0x900000ULL, 0x13000000ULL, 0x1000ULL}},
};

constexpr std::size_t transfer_size = 16;
constexpr bool read_pattern = false;
constexpr std::array<std::uint8_t, 8> pattern{0xde, 0xad, 0xbe, 0xef, 0x1, 0x23, 0x45, 0x67};
constexpr unsigned irq_index = 3;
constexpr bool irq_enabled = true;
constexpr unsigned irq_vector = 81, irq_destination = 2;

// Scenario-specific recovery: restore only a deliberately absent owned leaf.
inline bool restore_missing_leaf(Address address)
{
    if (!false || (address & ~0xFFFULL) != 0x123456789000ULL) {
        return false;
    }

return true;
}

} // namespace iommu_demo
#line 1 "page_tables.hpp"

namespace iommu_demo {
// 4. Fetch an entry, print its storage and encoding, then check presence.
// A fault occurs before any packet bytes are copied.
inline Entry fetch(const Memory& memory, Address table_spa, unsigned index, const char* label,
                   unsigned level)
{
    Entry e{};
    const auto t = memory.find(table_spa);
    if (t != memory.end()) {
        const auto it = t->second.find(index);
        if (it != t->second.end()) {
            e = it->second;
        }
    }
    const Address offset = index * 8;
    std::cout << label << " index " << index << " raw " << e.raw << " -> next table / frame "
              << e.target << '\n';
    std::cout << "  backing table page SPA " << table_spa << ", entry SPA " << table_spa + offset
              << '\n';
    const auto linear = table_cpu_linear.find(table_spa);
    if (linear != table_cpu_linear.end()) {
        std::cout << "  mock table CPU linear page " << linear->second << ", entry linear "
                  << linear->second + offset << '\n';
    }
    std::cout << "  mocked RAM bytes (little endian): ";
    for (unsigned byte = 0; byte < 8; ++byte) {
        std::cout << std::noshowbase << std::setw(2) << std::setfill('0')
                  << ((e.raw >> (byte * 8)) & 255) << ' ';
    }
    std::cout << std::showbase << std::setfill(' ') << '\n';
    // The snapshot stores a packed word beside decoded fields for readability.
    // Reject inconsistent manual edits rather than silently executing a different entry.
    const bool is_host = std::string_view(label) == "Host";
    const bool is_guest = std::string_view(label) == "Guest";
    const bool raw_write = is_host ? bool(e.raw & (1ULL << 62)) : bool(e.raw & 2);
    if (e.present != bool(e.raw & 1) || e.target != (e.raw & 0x000ffffffffff000ULL) ||
        ((is_host || is_guest) && e.write != raw_write)) {
        throw std::runtime_error(
            "Packed entry and decoded fields disagree; regenerate or edit both");
    }
    if (e.present && is_host && e.next_level != ((e.raw >> 9) & 7)) {
        throw std::runtime_error("Packed NextLevel and decoded next_level disagree");
    }
    if (e.present && e.page_size) {
        if (level > 3 || e.page_size != (Address{1} << (12 + 9 * (level - 1))) ||
            e.target % e.page_size) {
            throw PageFault("Unsupported or misaligned page leaf", true, false);
        }
        if (is_host && e.next_level != 0) {
            throw PageFault("This model uses NextLevel=0 for standard host leaves", true, false);
        }
        if (is_guest && level > 1 && !(e.raw & 128)) {
            throw std::runtime_error("Large guest leaf requires PS=1 in the packed word");
        }
    }
    if (e.present && is_host && !(e.raw & (1ULL << 61))) {
        throw std::runtime_error("IR=0 host entries are outside this read-enabled teaching subset");
    }
    if (!e.present) {
        throw PageFault("Entry is not present", false, false);
    }
    return e;
}

// 5. Host translation: each index consumes nine address bits.
// The six-level top index uses only seven bits of a 64-bit input.
inline Address last_host_size = 4096;
inline Address translation_remaining = 4096;

inline Address host_walk(Address gpa, bool write)
{
    Address table = host_root;
    // Bits above the root width, or in skipped levels, must be zero.
    if constexpr (host_mode > 0 && host_mode < 6) {
        if (gpa >> (12 + 9 * host_mode)) {
            throw PageFault("GPA above Host Mode width", true, false);
        }
    }
    unsigned level = host_mode;
    while (level) {
        const unsigned index = (gpa >> (12 + 9 * (level - 1))) & 511;
        std::cout << "Host level " << level << '\n';
        const auto e = fetch(host_tables, table, index, "Host", level);
        if (write && !e.write) {
            throw PageFault("Host write denied", true, true);
        }
        if (e.page_size) {
            last_host_size = e.page_size;
            return e.target | (gpa & (e.page_size - 1));
        }
        if (e.next_level == 0 || e.next_level >= level) {
            throw PageFault("Invalid Host NextLevel", true, false);
        }
        const Address skipped_mask =
            (Address{1} << (12 + 9 * (level - 1))) - (Address{1} << (12 + 9 * e.next_level));
        if (gpa & skipped_mask) {
            throw PageFault("Nonzero skipped host bits", true, false);
        }
        table = e.target;
        level = e.next_level;
    }
    throw PageFault("Host walk has no leaf", false, false);
}

// 6. Device lookup, PASID directory lookup, then guest and/or host walk.
// Guest Only preserves the guest result because GPA = SPA (host Mode=0).
inline Address translate(Address address, bool access_write = write_access)
{
    std::cout << "DTE SPA " << device_table + requester_id * 32 << '\n';
    for (unsigned i = 0; i < 4; ++i) {
        std::cout << "  DTE Q" << i << " = " << dte_words[i] << '\n';
    }
    if (!translation_valid) {
        throw PageFault("DTE V=1, TV=0: table walk unavailable", true, false);
    }
    Address gpa = address, guest_size = 0;
    if (guest_stage) {
        const Address high = address >> 48;
        if (high != ((address >> 47 & 1) ? 65535ULL : 0ULL)) {
            throw PageFault("Non-canonical guest address", true, false);
        }
        if (pasid > max_pasid) {
            throw std::runtime_error("PASID outside demo range; software rejects GLX aliases");
        }
        Address table = gcr3_root; // global GCR3TRPMode=0: top pointer is SPA
        // PASID selects a root; it is not part of the data virtual address.
        for (unsigned level = glx + 1; level; --level) {
            if (level != glx + 1 && host_stage) {
                table = host_walk(table, false);
            }
            const unsigned index = (pasid >> (9 * (level - 1))) & 511;
            const auto e = fetch(gcr3_tables, table, index, "GCR3", level);
            table = e.target;
        }
        // Guest tables contain GPAs; nested mode translates their memory too.
        for (unsigned level = 4; level; --level) {
            const unsigned index = (address >> (12 + 9 * (level - 1))) & 511;
            const Address entry_gpa = table + index * 8;
            const Address entry_spa = host_stage ? host_walk(entry_gpa, false) : entry_gpa;
            std::cout << "Guest level " << level << " table GPA " << table << '\n';
            const auto e = fetch(guest_tables_in_spa, entry_spa & ~4095ULL, (entry_spa & 4095) / 8,
                                 "Guest", level);
            if (access_write && !e.write) {
                throw PageFault("Guest write denied", true, true);
            }
            table = e.target;
            if (e.page_size) {
                guest_size = e.page_size;
                break;
            }
        }
        if (!guest_size) {
            throw PageFault("Guest walk has no supported leaf", false, false);
        }
        gpa = table | (address & (guest_size - 1));
        std::cout << "GPA " << gpa << '\n';
    }
    const Address spa = host_stage ? host_walk(gpa, access_write) : gpa;
    translation_remaining = guest_stage ? guest_size - address % guest_size : ~Address{0};
    if (host_stage) {
        translation_remaining =
            std::min(translation_remaining, last_host_size - gpa % last_host_size);
    }
    return spa;
}

} // namespace iommu_demo

#line 1 "log_buffers.hpp"

namespace iommu_demo {
// A bounded ring with one reserved slot. Pointer offsets advance by 16 bytes;
// eight slots demonstrate wraparound and are not a hardware-valid allocation.
template <class T, std::size_t Slots = 8>
class Ring {
    static_assert(Slots >= 2, "A ring needs one usable slot and one reserved slot");
    std::array<std::optional<T>, Slots> entries_{};
    std::size_t head_ = 0, tail_ = 0;

public:
    bool empty() const
    {
        return head_ == tail_;
    }

void push(const T& value)
    {
        const auto next = (tail_ + 1) % Slots;
        if (next == head_) {
            throw std::runtime_error("Teaching ring is full");
        }
        entries_[tail_] = value;
        tail_ = next;
    }

T pop()
    {
        if (empty()) {
            throw std::runtime_error("Teaching ring is empty");
        }
        const auto value = *entries_[head_];
        entries_[head_].reset();
        head_ = (head_ + 1) % Slots;
        return value;
    }

void print(const char* name) const
    {
        std::cout << name << " Head=" << head_ * 16 << " Tail=" << tail_ * 16 << '\n';
    }
};

// 7. Event logging: AMD 48882 rev 3.11, Table 57, 16 bytes per record.
// Logging is enabled and SA/SE are zero. This is ordinary DMA (TR=0, I=0),
// not an ATS query. D/P contains PASID low bits when GN=1, otherwise DomainID.
inline EventRecord make_page_fault(Address address, const PageFault& fault)
{
    const std::uint32_t first = requester_id | (guest_stage ? (pasid >> 16) << 16 : 0);
    const std::uint32_t flags =
        (2U << 28) | (fault.present ? 1U << 20 : 0) | (fault.permission ? 1U << 22 : 0) |
        (fault.present && write_access ? 1U << 21 : 0) |
        (guest_stage ? (1U << 18) | (1U << 17) | (1U << 16) | (pasid & 0xffffU) : 7U);
    return {first, flags, static_cast<std::uint32_t>(address),
            static_cast<std::uint32_t>(address >> 32)};
}

} // namespace iommu_demo

#line 1 "ats_commands.hpp"

namespace iommu_demo {
// ATS/PRI service is separate from ordinary memory-request fault reporting.
// The ATC entry is scoped to this descriptor's Requester ID and PASID. Each
// new run starts empty, so a mapping edit cannot accidentally reuse stale data.

inline std::optional<AtcEntry> atc;

inline std::vector<PprRecord> ppr_log; // Software work-item history, separate from the ring.

inline Ring<PprRecord> ppr_ring;
inline std::map<Address, AtcEntry> iommu_cache;
enum class Command { InvalidateIommu, InvalidateDevice, CompletionWait, CompletePpr };

struct CommandRecord {
    Command operation;
    unsigned group = 0;
    bool success = false;
};

inline Ring<CommandRecord> command_ring;
inline bool iommu_invalidated = false, device_invalidated = false;
inline bool completion_observed = false;
inline unsigned completion_token = 0;

// Real hardware can overlap command execution. This teaching processor fetches
// FIFO and completes serially, making the required dependency easy to inspect.
inline void process_commands()
{
    std::vector<CommandRecord> inflight;
    while (!command_ring.empty()) {
        inflight.push_back(command_ring.pop());
        command_ring.print("Command fetched, not completed:");
    }
    for (const auto& command : inflight) {
        switch (command.operation) {
        case Command::InvalidateIommu:
            iommu_cache.clear();
            iommu_invalidated = true;
            std::cout << "INVALIDATE_IOMMU_PAGES completed\n";
            break;
        case Command::InvalidateDevice:
            if (!iommu_invalidated) {
                throw std::runtime_error("IOMMU invalidation still pending");
            }
            atc.reset();
            device_invalidated = true;
            std::cout << "INVALIDATE_IOTLB_PAGES: NIC acknowledgment received\n";
            break;
        case Command::CompletionWait:
            // Serial execution has completed older queued commands. A wait itself
            // cannot compensate for an invalidate that software never issued.
            completion_observed = iommu_invalidated && device_invalidated;
            std::cout << "COMPLETION_WAIT observed token=" << ++completion_token << '\n';
            break;
        case Command::CompletePpr:
            if (command.success &&
                (!completion_observed || !iommu_invalidated || !device_invalidated)) {
                throw std::runtime_error("Cannot respond Success before invalidation completes");
            }
            if (ppr_log.empty() || ppr_log.back().group != command.group) {
                throw std::runtime_error("PPR group mismatch");
            }
            ppr_log.back().response = command.success ? "Success" : "Failure";
            std::cout << "COMPLETE_PPR_REQUEST group=" << command.group
                      << " response=" << ppr_log.back().response << '\n';
            break;
        }
    }
}

inline void invalidate_before_dma()
{
    completion_observed = iommu_invalidated = device_invalidated = false;
    command_ring.push({Command::InvalidateIommu});
    command_ring.push({Command::InvalidateDevice});
    command_ring.push({Command::CompletionWait});
    command_ring.print("Software publishes command Tail:");
    process_commands();
}

inline void complete_page_request(unsigned group, bool success)
{
    // One descriptor: Requester ID and PASID are the constants above. The group
    // is copied from the consumed request, not allocated again for the response.
    command_ring.push({Command::CompletePpr, group, success});
    process_commands();
}

inline AtcEntry ats_query(Address page)
{
    std::cout << "ATS query AT=01 page=" << page << "; no payload copy\n";
    if (const auto it = iommu_cache.find(page); it != iommu_cache.end()) {
        return it->second;
    }
    AtcEntry entry{page, 0, false, false};
    // The model independently computes R and W. Architectural A/D updates
    // and packed ATS completions are intentionally outside this teaching code.
    try {
        entry.spa_page = translate(page, false) & ~Address{4095};
        entry.read = true;
    }
    catch (const PageFault&) {
    }
    try {
        entry.spa_page = translate(page, true) & ~Address{4095};
        entry.write = true;
    }
    catch (const PageFault&) {
    }
    std::cout << "ATS response R=" << entry.read << " W=" << entry.write << '\n';
    iommu_cache[page] = entry;
    return entry;
}

inline bool mock_page_in(Address address)
{
    // The original allocation already exists. Restore presence only, retaining
    // its frame and permissions. Do not map arbitrary pages or grant writes.
    if (!restore_missing_leaf(address)) {
        return false;
    }
    completion_observed = false;
    std::cout << "Mock OS page-in: set P/PR=1; caches need invalidation\n";
    return true;
}

inline Address resolve_ats(Address address)
{
    if (!completion_observed || !iommu_invalidated || !device_invalidated) {
        throw std::runtime_error("DMA blocked: required invalidations/completion missing");
    }
    const Address page = address & ~Address{4095};
    if (!atc || atc->input_page != page) {
        auto entry = ats_query(page);
        auto allowed = [&] {
            return write_access ? entry.write : entry.read;
        };
        if (!allowed() && use_pri) {
            ppr_ring.push(
                {static_cast<unsigned>(ppr_log.size() + 1), page, write_access, "Pending"});
            ppr_ring.print("IOMMU logs PAGE_SERVICE_REQUEST, pending=1:");
            const auto work = ppr_ring.pop();
            ppr_log.push_back(work);
            ppr_ring.print("Software consumes PPR, pending=0 (response still pending):");
            std::cout << "PRI group " << work.group << " -> PPR log, Requester=" << requester_id
                      << " PASID=" << (guest_stage ? pasid : 0) << "; DMA waits\n";
            if (mock_page_in(address)) {
                invalidate_before_dma();
                complete_page_request(work.group, true);
                std::cout << "Page response Success; retry ATS before memory DMA\n";
                entry = ats_query(page);
            }
            else {
                complete_page_request(work.group, false);
                std::cout << "Page response Failure; no new mapping or permission upgrade\n";
            }
        }
        if (!allowed()) {
            throw PageFault("ATS did not grant this access", entry.read, entry.read);
        }
        atc = entry;
        std::cout << "NIC caches 4 KiB translation\n";
    }
    else {
        std::cout << "ATC hit; no page-table walk\n";
    }
    if (!(write_access ? atc->write : atc->read)) {
        throw PageFault("ATC permission denied", true, true);
    }
    translation_remaining = 4096 - (address & 4095);
    const Address spa = atc->spa_page + (address & 4095);
    std::cout << "Pretranslated DMA AT=10 SPA=" << spa << '\n';
    return spa;
}

} // namespace iommu_demo
#line 1 "dma_engine.hpp"

namespace iommu_demo {
inline void print_bytes(const char* label, const std::vector<std::uint8_t>& bytes)
{
    std::cout << label;
    for (std::size_t i = 0; i < std::min<std::size_t>(bytes.size(), 64); ++i) {
        const auto byte = bytes[i];
        std::cout << std::hex << std::noshowbase << std::setw(2) << std::setfill('0')
                  << static_cast<unsigned>(byte) << ' ';
    }
    std::cout << std::showbase << std::setfill(' ') << '\n';
}

// 8. Mock one Ethernet NIC descriptor. RX writes NIC bytes into RAM;
// TX reads RAM into the NIC. Splitting at page boundaries is essential:
// translating only the first byte cannot authorize a whole DMA buffer.
inline int run_dma()
{
    // No transaction is issued when the NIC is disabled. This is not an
    // IOMMU translation failure and must not append an IO_PAGE_FAULT record.
    if (!(pci_command & 0x4) || (guest_stage && !(pasid_ctl & 0x1))) {
        std::cout << "NIC request not issued: enable Bus Master and, for guest DMA, PASID.\n";
        return 2;
    }
    if (use_ats && (!(ats_ctl & 0x8000) || !(dte_words[1] & (1ULL << 32)))) {
        std::cout << "ATS DMA blocked: enable ATSCtl and DTE.I.\n";
        return 2;
    }
    static_assert(transfer_size > 0 && transfer_size <= 65536,
                  "Teaching descriptor is 1..65536 bytes");
    static_assert(pattern.size() > 0 && pattern.size() <= 32, "Payload pattern is 1..32 bytes");
    if (input_address > ~Address{0} - (transfer_size - 1)) {
        std::cout << "Descriptor wraps the 64-bit address space; no request issued\n";
        return 4;
    }
    // fragile: AMD 48882 rev 3.11 Table 64; changed rules make TV=0 classification stale.
    // Stops before invalidate_before_dma() and ats_query(): there is no response to show.
    if (use_ats && !translation_valid) {
        std::cout << "ATS stopped by teaching-model guard: DTE V=1, TV=0 "
                     "(INVALID_DEVICE_REQUEST, TR=1, Type=000b; AMD 48882 rev 3.11 Table 64). "
                     "No response or event is modelled.\n";
        std::cout << std::dec << "DMA copied 0/" << transfer_size
                  << " bytes; remaining bytes blocked\n"
                  << std::hex;
        return 3;
    }
    std::map<Address, RamPage> ram;
    for (const auto& [id, buffer] : buffers) {
        (void)id;
        auto& page = ram[buffer.spa];
        for (std::size_t i = 0; i < page.size(); ++i) {
            page[i] = static_cast<std::uint8_t>(i & 255);
        }
    }
    std::vector<std::uint8_t> packet(transfer_size);
    if (write_access) {
        for (std::size_t i = 0; i < packet.size(); ++i) {
            packet[i] = pattern[i % pattern.size()];
        }
    }
    Ring<EventRecord> event_buffer; // One reserved slot; one fault at most in this descriptor.
    std::size_t completed = 0;
    // The initial table image may already have P/PR=0 to model page-out.
    // Invalidate before querying it; page-in repeats this synchronization.
    if (use_ats) {
        invalidate_before_dma();
    }
    while (completed < transfer_size) {
        const Address address = input_address + completed;

try {
            // Translation and permissions must succeed before either endpoint changes.
            const Address spa = use_ats ? resolve_ats(address) : translate(address);
            // Validate both translation stages BEFORE reading or writing any byte
            // of this leaf-sized segment. A rejected segment copies zero bytes.
            const auto count = std::min(
                {transfer_size - completed, static_cast<std::size_t>(translation_remaining),
                 std::size_t{256}, kPageSize - static_cast<std::size_t>(address % kPageSize)});
            std::cout << (host_stage ? "SPA " : "GPA = SPA ") << spa << '\n';
            // CPU linear aliases are independent metadata given by the scenario.
            for (const auto& [id, buffer] : buffers) {
                if (buffer.linear && spa >= buffer.spa && spa < buffer.spa + buffer.span) {
                    std::cout << "Data CPU linear address " << *buffer.linear + (spa - buffer.spa)
                              << " for PASID " << id << '\n';
                }
            }

// Reject unsupported edited mappings before touching RAM. The NIC
            // uses 256-byte requests, bounded by a 4 KiB PCIe address boundary.
            const bool backed = std::any_of(buffers.begin(), buffers.end(), [&](const auto& item) {
                const auto& b = item.second;
                return spa >= b.spa && spa - b.spa < b.span && count <= b.span - (spa - b.spa);
            });
            if (!backed) {
                throw std::runtime_error("Translated segment has no mock RAM allocation");
            }
            std::vector<std::uint8_t> before, after;
            for (std::size_t i = 0; i < count; ++i) {
                // Allocate only touched 4 KiB backing blocks, even with 1 GiB leaves.
                const Address byte_spa = spa + i;
                const auto [it, inserted] = ram.try_emplace(byte_spa & ~Address{kPageSize - 1});
                auto& page = it->second;
                if (inserted) {
                    for (std::size_t j = 0; j < page.size(); ++j) {
                        page[j] = static_cast<std::uint8_t>(j & 255);
                    }
                }
                const auto offset = static_cast<std::size_t>(byte_spa & (kPageSize - 1));
                // Optional RAM fixture preparation, not a device write.
                if (!write_access && read_pattern) {
                    page[offset] = pattern[(completed + i) % pattern.size()];
                }
                before.push_back(page[offset]);
                if (write_access) {
                    page[offset] = packet[completed + i];
                }
                else {
                    packet[completed + i] = page[offset];
                }
                after.push_back(page[offset]);
            }
            print_bytes("RAM before: ", before);
            print_bytes("RAM after:  ", after);
            completed += count;
        }
        catch (const PageFault& fault) {
            if (use_ats) {
                // An ATS permission/missing-page response did not issue a
                // memory request: no ordinary DMA IO_PAGE_FAULT is appended.
                std::cout
                    << "ATS stopped: no AT=10 request for this page; event buffer pending=0\n";
                std::cout << std::dec << "DMA copied " << completed << '/' << transfer_size
                          << " bytes; remaining bytes blocked\n"
                          << std::hex;
                return 3;
            }
            // Earlier chunks stay copied; the rejected chunk has no side effects.
            const auto record = make_page_fault(address, fault);
            event_buffer.push(record);
            std::cout << "TRANSLATION FAULT: " << fault.what() << '\n';
            std::cout << "IO_PAGE_FAULT code=2 address=" << address << '\n';
            for (const auto value : record) {
                std::cout << value << ' ';
            }
            std::cout << "\nEvent buffer head=0x00 tail=0x10 pending=1\n";
            std::cout << std::dec << "DMA copied " << completed << '/' << transfer_size
                      << " bytes; remaining bytes blocked\n"
                      << std::hex;
            print_bytes("NIC packet: ", packet);
            return 1;
        }
    }
    print_bytes("NIC packet: ", packet);
    std::cout << std::dec << "DMA copied " << completed << '/' << transfer_size
              << " bytes; event buffer pending=0\n"
              << std::hex;
    return 0;
}

} // namespace iommu_demo

#line 1 "interrupts.hpp"

namespace iommu_demo {
// 9. Independent synthetic interrupt memory and APIC queue.
// Legacy remapping uses a 4-byte IRTE: RemapEn[0], IntType[4:2],
// Destination[15:8], Vector[23:16]. Fixed delivery uses IntType=0.
// No physical MSI write, MMIO access or CPU interrupt is executed here.
inline void deliver_completion_interrupt()
{
    constexpr std::uint32_t irte = 1U | (irq_destination << 8) | (irq_vector << 16);
    const std::map<unsigned, std::uint32_t> interrupt_memory{{3, irte}, {7, irte}};
    std::vector<unsigned> apic_pending;
    std::cout << "IRTE SPA " << interrupt_table + irq_index * 4 << '\n';
    const auto it = interrupt_memory.find(irq_index);
    if (!irq_enabled || it == interrupt_memory.end() || !(it->second & 1)) {
        std::cout << "Interrupt stopped: blocked or absent IRTE\n";
        return;
    }
    const auto word = it->second;
    const unsigned decoded_vector = (word >> 16) & 255;
    const unsigned decoded_destination = (word >> 8) & 255;
    apic_pending.push_back(decoded_vector);
    std::cout << "IRTE raw " << word << " Interrupt vector " << decoded_vector << " -> APIC "
              << decoded_destination << '\n';
    // Mock ISR acknowledges the queued vector after reading NIC completion.
    apic_pending.erase(apic_pending.begin());
    std::cout << "Mock ISR: completion acknowledged; APIC pending=" << apic_pending.size() << '\n';
}

} // namespace iommu_demo

#line 1 "main.cpp"
// Start here: one descriptor, then an interrupt only on success.

using namespace iommu_demo;

inline int run_example()
{
    std::cout << std::hex << std::showbase;
    if (cpu_linear_page) {
        std::cout << "Optional data CPU linear base " << *cpu_linear_page << '\n';
    }
    std::cout << "PCI Command " << pci_command << " PASIDCap " << pasid_cap << " PASIDCtl "
              << pasid_ctl << " ATSCap " << ats_cap << " ATSCtl " << ats_ctl << '\n';
    // The optional CPU address is metadata, never needed by the DMA walk.
    const int status = run_dma();
    // A NIC completion interrupt follows successful DMA only. An IOMMU event
    // is a separate mechanism; a failed descriptor must not claim completion.
    if (status == 0) {
        deliver_completion_interrupt();
    }
    else {
        std::cout << "No successful NIC completion interrupt.\n";
    }
    return status;
}

int main()
{
    try {
        return run_example();
    }
    catch (const std::exception& error) {
        std::cerr << "Model stopped: " << error.what() << '\n';
        return 4; // Invalid edited snapshot or unsupported model state.
    }
}

Download combined .cpp

Ready. No code has been sent.

Compiler & test output

Run the example to see actual output here.

If the external service is unavailable, copy the source and open Compiler Explorer, or compile locally with g++ -std=c++23 example.cpp -o example and run ./example.

Theme and appearance

IOMMU translation & DMA validation.

01 / Choose the translation path

Host only

Guest only

Guest + host

02 / Build a mapping

03 / Configure the PCIe device

Ask for a translation with ATS

04 / Send a DMA request

05 / Observe the DMA transfer

Choose how the NIC addresses memory

NIC packet buffer

RAM · before transfer

RAM · at this event

Compare two fault cases

Start on an invalid page

Valid page → invalid page

Predicted outcome · before playback

ATS cache and page-request service · at this event

NIC address translation cache (ATC)

PRI → AMD PPR log

PPR log · IOMMU produces, software consumes

Command buffer · software produces, IOMMU consumes

IOMMU event buffer

06 / Inspect the device and roots

Device Table Entry · 256 bits / 32 bytes

Find the page tables for this PASID

Host root

07 / See the address map

08 / Walk the tables

09 / Investigate faults

Missing mapping

Read-only page

A table is missing

10 / Follow the interrupt path

11 / Run the matching C++ example

Compiler & test output