Who writes the next entry?

Queue up to seven entries, then fetch to free slots. Consuming slots does not finish the commands. This teaching processor enforces its chosen safe invalidation order. COMPLETION_WAIT can finish without the needed invalidations, but the separate DMA safety gate stays closed. Reset restores a known starting state.

• INVALIDATE_IOMMU_PAGES targets the IOMMU’s cached address-translation state.
• INVALIDATE_IOTLB_PAGES requests invalidation in the peripheral’s translation cache. Device acknowledgment matters.
• COMPLETION_WAIT gives software a synchronization point after earlier commands. An empty command ring alone is insufficient.
• INVALIDATE_DEVTAB_ENTRY applies when cached device-table information changes. This lab keeps the DTE fixed.
• INVALIDATE_INTERRUPT_TABLE applies to cached interrupt-remapping information after its table changes. It is separate from data-page invalidation.

This model invalidates the entire small session cache. Real commands select scopes such as domain, device, PASID and address range. Submission may be FIFO while execution overlaps; here completion is serial so dependencies remain visible.

Do not put COMPLETION_WAIT between every command. Queue the ordered invalidate sequence, then place a wait where software needs a synchronization boundary. Software must observe the requested completion value or notification; command Head reaching Tail is not proof of completion. A wait does not fix an omitted invalidation.

This fixture withholds the acknowledgment and declares no InvTimeOut timer. If a device does not acknowledge invalidation, keep affected DMA/page reuse blocked. A software polling deadline must report failure rather than assume success. Command hardware errors and illegal commands stop command processing; clearing EventLogInt alone does not restart it.

Preserve the offending event and command context. Wait for the command engine to stop, disable CmdBufEn, repair the cause and buffer configuration while stopped, then re-enable according to §2.4. Hardware may have fetched beyond the bad command, so do not infer the culprit solely from the current Head.

Log overflow is different from a malformed record. Preserve unread information, drain or resize as appropriate, observe the log’s stopped state, configure while disabled, clear its overflow W1C flag and re-enable logging. Event, PPR and GA restart rules differ; a generic “clear everything” write is not a recovery procedure.

1. Discover and check: obtain the IOMMU MMIO window and supported features. Keep the CPU mapping of that window separate from the physical address of a buffer in RAM.
2. Allocate backing: use the platform’s DMA/coherent allocation mechanisms to obtain stable, contiguous physical backing with the required alignment and address width. A C++ pointer alone is not a hardware buffer address. Keep the allocation alive while hardware can reference it.
3. Stop before reprogramming: quiesce affected activity and follow the buffer-specific disable/Run=0 procedure. Do not change a running log’s base, length or hardware-owned Tail.
4. Initialize: initialize the storage and Head/Tail; program its SPA and length, not its CPU linear address. The command buffer uses 4 KiB alignment and ComLen=8 for 256 × 16-byte entries. The eight-slot illustrations below are intentionally smaller teaching views.
5. Enable: configure IommuEn, CmdBufEn and the logs in use. PPR additionally needs PPREn, PPRLogEn and enabled device facilities. Configure interrupt enables if interrupts are used; polling remains a distinct notification strategy.
6. Publish a command: reserve a free slot, write its complete 16 bytes, use the platform’s required memory/DMA ordering, then publish the new Tail. Hardware must never see Tail pointing past a partially written record.
7. Fetch and complete: hardware fetches at Head and advances Head. Execution can overlap; use a completion token or interrupt when software needs proof that older work finished.
8. Drain a log: observe Tail with the required ordering, copy/read complete records up to Tail and publish the consumed Head. Recheck for arrivals. Acknowledging status does not consume unread records.

Head and Tail are byte offsets within the buffer. Entry address = buffer SPA + offset. For 16-byte records, the next offset is (offset + 16) mod buffer_bytes; the GA log uses 8-byte records. For a 4 KiB command ring, offset 0xFF0 advances to 0x000. Keep one slot free to distinguish full from empty.

The CPU can write through a mapped linear pointer while the IOMMU reads the same backing through its SPA. The links between allocations and registers are separate from the actual DMA data mappings. The GA tail-address register at MMIO +0x00E8 points to a memory location for a hardware-written tail copy; it is not the tail offset itself.

MMIO +0x0018 is the Control register; +0x0030 reports Extended Features; +0x2020 is Status. Run bits are read-only state. Notification and overflow bits include write-one-to-clear (W1C) fields: EventLogInt bit 1, ComWaitInt bit 2, PprInt bit 6 and GAInt bit 10.

Write a deliberate mask of the W1C bits you intend to acknowledge. Writing zero does not clear them; blindly writing back an entire status value can acknowledge unrelated conditions. Draining entries, clearing notification status, clearing overflow, restarting logging and sending APIC EOI are separate operations. Use a drain/ack/recheck loop so racing arrivals are not missed.