.. SPDX-License-Identifier: GPL-2.0-or-later

iommu-testdev — IOMMU test device for bare-metal testing
========================================================

Overview
--------
``iommu-testdev`` is a minimal, test-only PCI device designed to exercise
IOMMU translation (such as ARM SMMUv3) without requiring firmware or a guest
OS. Tests can populate IOMMU translation tables with known values and trigger
DMA operations that flow through the IOMMU translation path. It is **not** a
faithful PCIe endpoint and must be considered a QEMU-internal test vehicle.

Key Features
------------
* **Bare-metal IOMMU testing**: No guest kernel or firmware required
* **Configurable DMA attributes**: Supports address space configuration via
  MMIO registers
* **Deterministic verification**: Write-then-read DMA pattern with automatic
  result checking

Status
------
* Location: ``hw/misc/iommu-testdev.c``
* Header: ``include/hw/misc/iommu-testdev.h``
* Build guard: ``CONFIG_IOMMU_TESTDEV``

Device Interface
----------------
The device exposes a single PCI BAR0 with 32-bit MMIO registers:

* ``ITD_REG_DMA_TRIGGERING`` (0x00): Read triggers DMA and consumes
  the armed request
* ``ITD_REG_DMA_GVA_LO`` (0x04): DMA IOVA bits [31:0]
* ``ITD_REG_DMA_GVA_HI`` (0x08): DMA IOVA bits [63:32]
* ``ITD_REG_DMA_GPA_LO`` (0x1C): DMA GPA bits [31:0] for readback validation
* ``ITD_REG_DMA_GPA_HI`` (0x20): DMA GPA bits [63:32] for readback validation
* ``ITD_REG_DMA_LEN`` (0x0C): DMA transfer length
* ``ITD_REG_DMA_RESULT`` (0x10): DMA result
  (0=success, 0xffffffff=idle, 0xfffffffe=armed)
* ``ITD_REG_DMA_DBELL`` (0x14): Write 1 to arm DMA, write 0 to disarm.
  Arming only marks the request and sets BUSY (no latch/check), but it
  provides an explicit gate for qtests and leaves room for async/latching.
* ``ITD_REG_DMA_ATTRS`` (0x18): DMA attributes which shadow some fields in
  MemTxAttrs:

  - bit[0]: secure (1=Secure, 0=Non-Secure)
  - bits[2:1]: ArmSecuritySpace (0=Secure, 1=Non-Secure)
  - bit[3]: space_valid (1=space is valid, 0=ignore space and default to Non-Secure)
    ``space`` field in MemTxAttrs is consumed only when ``space_valid`` is set.
    For Secure/Non-Secure, ``secure`` and ``space`` must match; mismatches
    return ``ITD_DMA_ERR_BAD_ATTRS``. Other bits are reserved but can be wired
    up easily if future tests need to pass extra attributes.

Translation Setup Workflow
--------------------------
``iommu-testdev`` never builds SMMU/AMD-Vi/RISC-V IOMMU structures on its own.
Architecture-specific construction lives entirely in qtest/libqos helpers.
Those helpers populate guest memory with page tables/architecture-specific
structures and program the emulated IOMMU registers directly. See the
``qsmmu_setup_and_enable_translation()`` function in
``tests/qtest/libqos/qos-smmuv3.c`` for an example of how SMMUv3 translation
is set up for this device.

DMA Operation Flow
------------------
Arming semantics:

* Writing ``DMA_DBELL`` with bit0=1 marks the request armed and sets
  ``DMA_RESULT`` to BUSY. It does not latch GVA/LEN/ATTRS; values are sampled
  when ``DMA_TRIGGERING`` is read.
* Writing ``DMA_DBELL`` with bit0=0 disarms the request and sets
  ``DMA_RESULT`` to IDLE.
* Reading ``DMA_TRIGGERING`` consumes the armed request and clears the armed
  state, even on error.

The flow would be split into these steps, mainly for timing control and
debuggability: qtests can easily exercise and assert distinct paths
(NOT_ARMED, BAD_LEN, TX/RD failures, mismatch) instead of having all side
effects hidden behind a single step:
1. Test programs IOMMU translation tables
2. Test configures DMA IOVA (GVA_LO/HI), GPA for readback, length, and attributes
3. Test writes 1 to DMA_DBELL to arm the operation
4. Test reads DMA_TRIGGERING to execute DMA
5. Test polls DMA_RESULT:

   - 0x00000000: Success
   - 0xFFFFFFFE: Armed (waiting for trigger). DMA runs synchronously, so
     BUSY is not observed once the trigger read completes.
   - 0xDEAD0006: Bad attrs (secure/space mismatch for S/NS)
   - 0xDEAD000X: Various error codes

The device performs a write-then-read sequence using a known pattern
(0x12345678) and verifies data integrity automatically.

Running the qtest
-----------------
The SMMUv3 test suite uses this device and covers multiple translation modes::

    cd build
    QTEST_QEMU_BINARY=./qemu-system-aarch64 \\
        ./tests/qtest/iommu-smmuv3-test --tap -k

This test suite exercises:

* Stage 1 only translation
* Stage 2 only translation
* Nested (Stage 1 + Stage 2) translation

Instantiation
-------------
The device is not wired into any board by default. Tests instantiate it
via QEMU command line::

    -device iommu-testdev

For ARM platforms with SMMUv3::

    -M virt,iommu=smmuv3 -device iommu-testdev

When the IOMMU sits on the same PCI root complex (``pci.0``), the device is
placed behind it automatically. For other PCI topologies, specify the bus
explicitly.

Limitations
-----------
* No realistic PCIe enumeration, MSI/MSI-X, or interrupt handling
* No ATS/PRI support
* No actual device functionality beyond DMA test pattern
* Test-only; not suitable for production or machine realism
* Address space support (Secure/Root/Realm) is architecture-dependent and
  gated by ``space_valid``
* Readback uses the programmed GPA and reads via system memory, avoiding a
  second IOMMU access for the readback step

See also
--------
* ``tests/qtest/iommu-smmuv3-test.c`` — SMMUv3 test suite
* ``tests/qtest/libqos/qos-smmuv3.{c,h}`` — SMMUv3 test library
* SMMUv3 emulation: ``hw/arm/smmu*``