tests/qtest: Add Intel IOMMU bare-metal test using iommu-testdev

[PATCH RFC v1 1/2] tests/qtest/libqos: Add Intel IOMMU helper library

Posted by Fengyuan Yu 3 days, 2 hours ago

Introduce a libqos helper module for Intel IOMMU (VT-d) testing with
iommu-testdev. The helper provides routines to:

- Build Root Entry Tables, Context Entry Tables, and 4-level page tables
  for 48-bit address translation
- Program VT-d registers (Root Table Pointer, Global Command Register)
  following the Intel VT-d specification
- Execute DMA translations and verify results

The current implementation supports Legacy mode with both pass-through and
translated (4-level paging) modes. Support for Scalable mode (PASID-based)
can be added in future patches.

Signed-off-by: Fengyuan Yu <15fengyuan@gmail.com>

---
 MAINTAINERS                          |   1 +
 tests/qtest/libqos/meson.build       |   3 +
 tests/qtest/libqos/qos-intel-iommu.c | 566 +++++++++++++++++++++++++++
 tests/qtest/libqos/qos-intel-iommu.h | 299 ++++++++++++++
 4 files changed, 869 insertions(+)
 create mode 100644 tests/qtest/libqos/qos-intel-iommu.c
 create mode 100644 tests/qtest/libqos/qos-intel-iommu.h

diff --git a/MAINTAINERS b/MAINTAINERS
index 9b7ed4fccb..1cd2a4f474 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3585,6 +3585,7 @@ M: Tao Tang <tangtao1634@phytium.com.cn>
 S: Maintained
 F: tests/qtest/libqos/qos-iommu*
 F: tests/qtest/libqos/qos-smmuv3*
+F: tests/qtest/libqos/qos-intel-iommu*
 
 Device Fuzzing
 M: Alexander Bulekov <alxndr@bu.edu>
diff --git a/tests/qtest/libqos/meson.build b/tests/qtest/libqos/meson.build
index 8d6758ec2b..7f7c4f9c6f 100644
--- a/tests/qtest/libqos/meson.build
+++ b/tests/qtest/libqos/meson.build
@@ -72,6 +72,9 @@ endif
 if config_all_devices.has_key('CONFIG_RISCV_IOMMU')
   libqos_srcs += files('riscv-iommu.c')
 endif
+if config_all_devices.has_key('CONFIG_VTD')
+  libqos_srcs += files('qos-intel-iommu.c')
+endif
 if config_all_devices.has_key('CONFIG_TPCI200')
   libqos_srcs += files('tpci200.c')
 endif
diff --git a/tests/qtest/libqos/qos-intel-iommu.c b/tests/qtest/libqos/qos-intel-iommu.c
new file mode 100644
index 0000000000..d6a733de7e
--- /dev/null
+++ b/tests/qtest/libqos/qos-intel-iommu.c
@@ -0,0 +1,566 @@
+/*
+ * QOS Intel IOMMU (VT-d) Module Implementation
+ *
+ * This module provides Intel IOMMU-specific helper functions for libqos tests.
+ *
+ * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#include "qemu/osdep.h"
+#include "../libqtest.h"
+#include "pci.h"
+#include "qos-intel-iommu.h"
+
+#define QVTD_POLL_DELAY_US        1000
+#define QVTD_POLL_MAX_RETRIES     1000
+#define QVTD_AW_48BIT_ENCODING    2
+
+/*
+ * iommu-testdev DMA attribute layout for Intel VT-d traffic.
+ *
+ * Bits [2:0] keep using the generic iommu-testdev encoding
+ * (secure + ArmSecuritySpace). Bits [23:8] carry the PCI Requester ID in the
+ * format defined in the Intel VT-d spec (Figure 3-2 in
+ * spec/Intel-iommu-spec.txt), and bits [31:24] contain the PASID that tags
+ * scalable-mode transactions. Bit 4 distinguishes between pure legacy RID
+ * requests and scalable-mode PASID-tagged requests. The PASID field is
+ * limited to 8 bits because MemTxAttrs::pid only carries 8 bits today (see
+ * include/exec/memattrs.h and the VTD_ECAP_PSS limit in
+ * hw/i386/intel_iommu_internal.h).
+ */
+#define QVTD_DMA_ATTR_MODE_SHIFT      4
+#define QVTD_DMA_ATTR_MODE_MASK       0x1
+#define QVTD_DMA_ATTR_MODE_LEGACY     0
+#define QVTD_DMA_ATTR_MODE_SCALABLE   1
+#define QVTD_DMA_ATTR_RID_SHIFT       8
+#define QVTD_DMA_ATTR_RID_MASK        0xffffu
+#define QVTD_DMA_ATTR_PASID_BITS      8
+#define QVTD_DMA_ATTR_PASID_SHIFT     24
+#define QVTD_DMA_ATTR_PASID_MASK      ((1u << QVTD_DMA_ATTR_PASID_BITS) - 1)
+
+#define QVTD_PCI_FUNCS_PER_DEVICE     8
+#define QVTD_PCI_DEVS_PER_BUS         32
+
+static void qvtd_wait_for_bitsl(QTestState *qts, uint64_t addr,
+                                uint32_t mask, bool expect_set)
+{
+    uint32_t val = 0;
+
+    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
+        val = qtest_readl(qts, addr);
+        if (!!(val & mask) == expect_set) {
+            return;
+        }
+        g_usleep(QVTD_POLL_DELAY_US);
+    }
+
+    g_error("Timeout waiting for bits 0x%x (%s) at 0x%llx, last=0x%x",
+            mask, expect_set ? "set" : "clear",
+            (unsigned long long)addr, val);
+}
+
+static void qvtd_wait_for_bitsq(QTestState *qts, uint64_t addr,
+                                uint64_t mask, bool expect_set)
+{
+    uint64_t val = 0;
+
+    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
+        val = qtest_readq(qts, addr);
+        if (!!(val & mask) == expect_set) {
+            return;
+        }
+        g_usleep(QVTD_POLL_DELAY_US);
+    }
+
+    g_error("Timeout waiting for bits 0x%llx (%s) at 0x%llx, last=0x%llx",
+            (unsigned long long)mask, expect_set ? "set" : "clear",
+            (unsigned long long)addr, (unsigned long long)val);
+}
+
+static uint16_t qvtd_calc_sid(const QPCIDevice *dev)
+{
+    uint16_t devfn = dev->devfn & 0xff;
+    uint16_t bus = (dev->devfn >> 8) & 0xff;
+    uint8_t device = (devfn >> 3) & 0x1f;
+    uint8_t function = devfn & 0x7;
+
+    /* Validate BDF components. */
+    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
+        g_error("Invalid BDF: bus=%u device=%u function=%u", bus, device, function);
+    }
+
+    return (bus << 8) | devfn;
+}
+
+static bool qvtd_validate_dma_memory(QVTDTestContext *ctx)
+{
+    uint32_t len = ctx->config.dma_len;
+    g_autofree uint8_t *buf = NULL;
+
+    if (!len) {
+        return true;
+    }
+
+    buf = g_malloc(len);
+    qtest_memread(ctx->qts, ctx->config.dma_pa, buf, len);
+
+    for (uint32_t i = 0; i < len; i++) {
+        uint8_t expected = (ITD_DMA_WRITE_VAL >> ((i % 4) * 8)) & 0xff;
+        if (buf[i] != expected) {
+            g_test_message("Memory mismatch at PA=0x%llx offset=%u "
+                           "expected=0x%02x actual=0x%02x",
+                           (unsigned long long)ctx->config.dma_pa, i,
+                           expected, buf[i]);
+            return false;
+        }
+    }
+
+    return true;
+}
+
+uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx)
+{
+    return ctx->config.expected_result;
+}
+
+uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid)
+{
+    uint32_t attrs = 0;
+    uint8_t bus = (bdf >> 8) & 0xff;
+    uint8_t devfn = bdf & 0xff;
+    uint8_t device = devfn >> 3;
+    uint8_t function = devfn & 0x7;
+    bool scalable_mode = pasid != 0;
+
+    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
+        g_error("Invalid requester-id 0x%04x (bus=%u device=%u function=%u)",
+                bdf, bus, device, function);
+    }
+
+    attrs = ITD_ATTRS_SET_SECURE(attrs, 0);
+    attrs = ITD_ATTRS_SET_SPACE(attrs, 0);
+    attrs |= ((uint32_t)bdf & QVTD_DMA_ATTR_RID_MASK) << QVTD_DMA_ATTR_RID_SHIFT;
+
+    if (scalable_mode) {
+        if (pasid > QVTD_DMA_ATTR_PASID_MASK) {
+            g_error("PASID 0x%x exceeds %u-bit limit imposed by MemTxAttrs",
+                    pasid, QVTD_DMA_ATTR_PASID_BITS);
+        }
+
+        attrs |= (QVTD_DMA_ATTR_MODE_SCALABLE << QVTD_DMA_ATTR_MODE_SHIFT);
+        attrs |= ((pasid & QVTD_DMA_ATTR_PASID_MASK) << QVTD_DMA_ATTR_PASID_SHIFT);
+    } else {
+        attrs |= (QVTD_DMA_ATTR_MODE_LEGACY << QVTD_DMA_ATTR_MODE_SHIFT);
+    }
+
+    return attrs;
+}
+
+static void qvtd_build_root_entry(QTestState *qts, uint8_t bus,
+                                  uint64_t context_table_ptr)
+{
+    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
+    uint64_t lo, hi;
+
+    /* Root Entry Low: Context Table Pointer + Present bit (VT-d spec Section 9.1). */
+    lo = (context_table_ptr & VTD_CONTEXT_ENTRY_SLPTPTR) | VTD_CONTEXT_ENTRY_P;
+    hi = 0;  /* Reserved. */
+
+    qtest_writeq(qts, root_entry_addr, lo);
+    qtest_writeq(qts, root_entry_addr + 8, hi);
+}
+
+static void qvtd_build_context_entry(QTestState *qts, uint16_t sid,
+                                     QVTDTransMode mode, uint16_t domain_id,
+                                     uint64_t slptptr)
+{
+    uint8_t devfn = sid & 0xff;
+    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
+    uint64_t lo, hi;
+
+    if (mode == QVTD_TM_LEGACY_PT) {
+        /* Pass-through mode (VT-d spec Section 3.9, Section 9.3). */
+        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_PASS_THROUGH;
+        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
+    } else {
+        /* Translated mode: 4-level paging (AW=2 for 48-bit, VT-d spec Section 9.3). */
+        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_MULTI_LEVEL |
+             (slptptr & VTD_CONTEXT_ENTRY_SLPTPTR);
+        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
+    }
+
+    qtest_writeq(qts, context_entry_addr, lo);
+    qtest_writeq(qts, context_entry_addr + 8, hi);
+}
+
+void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
+                                   uint64_t pa, QVTDTransMode mode)
+{
+    uint64_t pml4_entry, pdpt_entry, pd_entry, pt_entry;
+    uint64_t pml4_addr, pdpt_addr, pd_addr, pt_addr;
+    uint32_t pml4_idx, pdpt_idx, pd_idx, pt_idx;
+    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
+                           "Pass-Through" : "Translated";
+
+    g_test_message("Begin of page table construction: IOVA=0x%llx PA=0x%llx mode=%s",
+                   (unsigned long long)iova, (unsigned long long)pa, mode_str);
+
+    /* Pass-through mode doesn't need page tables */
+    if (mode == QVTD_TM_LEGACY_PT) {
+        g_test_message("Pass-through mode: skipping page table setup");
+        return;
+    }
+
+    /* Extract indices from IOVA
+     * 4-level paging for 48-bit virtual address space:
+     * - PML4 index: bits [47:39] (9 bits = 512 entries)
+     * - PDPT index:  bits [38:30] (9 bits = 512 entries)
+     * - PD index:    bits [29:21] (9 bits = 512 entries)
+     * - PT index:    bits [20:12] (9 bits = 512 entries)
+     * - Page offset: bits [11:0]  (12 bits = 4KB pages)
+     */
+    pml4_idx = (iova >> 39) & 0x1ff;  /* Bits [47:39] */
+    pdpt_idx = (iova >> 30) & 0x1ff;  /* Bits [38:30] */
+    pd_idx = (iova >> 21) & 0x1ff;    /* Bits [29:21] */
+    pt_idx = (iova >> 12) & 0x1ff;    /* Bits [20:12] */
+
+    /*
+     * Build 4-level page table hierarchy (VT-d spec Section 9.3, Table 9-3).
+     * Non-leaf entries: both R+W set for full access (spec allows R or W individually).
+     * Per VT-d spec Section 9.8: "If either the R or W field of a non-leaf
+     * paging-structure entry is 1", indicating that setting one or both is valid.
+     * We set both R+W for non-leaf entries as standard practice.
+     */
+
+    /* PML4 Entry: points to PDPT. */
+    pml4_addr = QVTD_PT_L4_BASE + (pml4_idx * 8);
+    pml4_entry = QVTD_PT_L3_BASE | VTD_SL_R | VTD_SL_W;
+    qtest_writeq(qts, pml4_addr, pml4_entry);
+
+    /* PDPT Entry: points to PD. */
+    pdpt_addr = QVTD_PT_L3_BASE + (pdpt_idx * 8);
+    pdpt_entry = QVTD_PT_L2_BASE | VTD_SL_R | VTD_SL_W;
+    qtest_writeq(qts, pdpt_addr, pdpt_entry);
+
+    /* PD Entry: points to PT. */
+    pd_addr = QVTD_PT_L2_BASE + (pd_idx * 8);
+    pd_entry = QVTD_PT_L1_BASE | VTD_SL_R | VTD_SL_W;
+    qtest_writeq(qts, pd_addr, pd_entry);
+
+    /* PT Entry: points to physical page (leaf). */
+    pt_addr = QVTD_PT_L1_BASE + (pt_idx * 8);
+    pt_entry = (pa & VTD_PAGE_MASK_4K) | VTD_SL_R | VTD_SL_W;
+    qtest_writeq(qts, pt_addr, pt_entry);
+
+    g_test_message("End of page table construction: mapped IOVA=0x%llx -> PA=0x%llx",
+                   (unsigned long long)iova, (unsigned long long)pa);
+}
+
+static void qvtd_invalidate_context_cache(QTestState *qts,
+                                          uint64_t iommu_base)
+{
+    uint64_t ccmd_val;
+
+    /* Context Command Register: Global invalidation (VT-d spec Section 6.5.1.1). */
+    ccmd_val = VTD_CCMD_ICC | VTD_CCMD_GLOBAL_INVL;
+    qtest_writeq(qts, iommu_base + DMAR_CCMD_REG, ccmd_val);
+
+    /* Wait for ICC bit to clear. */
+    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_CCMD_REG,
+                        VTD_CCMD_ICC, false);
+}
+
+static void qvtd_invalidate_iotlb(QTestState *qts, uint64_t iommu_base)
+{
+    uint64_t iotlb_val;
+
+    /* IOTLB Invalidate Register: Global flush (VT-d spec Section 6.5.1.2). */
+    iotlb_val = VTD_TLB_IVT | VTD_TLB_GLOBAL_FLUSH;
+    qtest_writeq(qts, iommu_base + DMAR_IOTLB_REG, iotlb_val);
+
+    /* Wait for IVT bit to clear. */
+    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_IOTLB_REG,
+                        VTD_TLB_IVT, false);
+}
+
+static void qvtd_clear_memory_regions(QTestState *qts)
+{
+    /* Clear root table. */
+    qtest_memset(qts, QVTD_ROOT_TABLE_BASE, 0, 4096);
+
+    /* Clear context table. */
+    qtest_memset(qts, QVTD_CONTEXT_TABLE_BASE, 0, 4096);
+
+    /* Clear all page table levels (4 levels * 4KB each = 16KB). */
+    qtest_memset(qts, QVTD_PT_L4_BASE, 0, 16384);
+}
+
+void qvtd_program_regs(QTestState *qts, uint64_t iommu_base)
+{
+    uint32_t gcmd;
+
+    /* 1. Disable translation (VT-d spec Section 11.4.4). */
+    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
+    gcmd &= ~VTD_GCMD_TE;
+    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
+
+    /* Wait for TES to clear. */
+    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
+                        VTD_GSTS_TES, false);
+
+    /* 2. Program root table address (VT-d spec Section 11.4.5). */
+    qtest_writeq(qts, iommu_base + DMAR_RTADDR_REG, QVTD_ROOT_TABLE_BASE);
+
+    /* 3. Set root table pointer (VT-d spec Section 6.6). */
+    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
+    gcmd |= VTD_GCMD_SRTP;
+    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
+
+    /* Wait for RTPS. */
+    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
+                        VTD_GSTS_RTPS, true);
+
+    /* Invalidate context cache after setting root table pointer. */
+    qvtd_invalidate_context_cache(qts, iommu_base);
+
+    /* 4. Unmask fault event interrupt to avoid warning messages. */
+    qtest_writel(qts, iommu_base + DMAR_FECTL_REG, 0);
+
+    /* NOTE: Translation is NOT enabled here - caller must enable after building structures. */
+}
+
+uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
+                                uint16_t sid, uint16_t domain_id,
+                                uint64_t iova, uint64_t pa)
+{
+    uint8_t bus = (sid >> 8) & 0xff;
+    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
+                           "Pass-Through" : "Translated";
+
+    g_test_message("Begin of construction: IOVA=0x%llx PA=0x%llx "
+                   "mode=%s domain_id=%u ===",
+                   (unsigned long long)iova, (unsigned long long)pa,
+                   mode_str, domain_id);
+
+    /* Build root entry */
+    qvtd_build_root_entry(qts, bus, QVTD_CONTEXT_TABLE_BASE);
+
+    /* Build context entry */
+    if (mode == QVTD_TM_LEGACY_PT) {
+        /* Pass-through mode: no page tables needed */
+        qvtd_build_context_entry(qts, sid, mode, domain_id, 0);
+        g_test_message("End of construction: identity mapping to PA=0x%llx ===",
+                       (unsigned long long)pa);
+    } else {
+        /* Translated mode: build 4-level page tables */
+        qvtd_setup_translation_tables(qts, iova, pa, QVTD_TM_LEGACY_TRANS);
+        qvtd_build_context_entry(qts, sid, mode, domain_id, QVTD_PT_L4_BASE);
+        g_test_message("End of construction: mapped IOVA=0x%llx -> PA=0x%llx ===",
+                       (unsigned long long)iova, (unsigned long long)pa);
+    }
+
+    return 0;
+}
+
+uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx)
+{
+    uint32_t gcmd;
+
+    /* Clear memory regions once during setup */
+    qvtd_clear_memory_regions(ctx->qts);
+
+    /* Program IOMMU registers (sets up root table pointer) */
+    qvtd_program_regs(ctx->qts, ctx->iommu_base);
+
+    /* Build translation structures AFTER clearing memory */
+    ctx->trans_status = qvtd_build_translation(ctx->qts, ctx->config.trans_mode,
+                                               ctx->sid, ctx->config.domain_id,
+                                               ctx->config.dma_iova,
+                                               ctx->config.dma_pa);
+    if (ctx->trans_status != 0) {
+        return ctx->trans_status;
+    }
+
+    /* Invalidate caches using register-based invalidation */
+    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
+    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
+
+    /* Enable translation AFTER building structures and invalidating caches */
+    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
+    gcmd |= VTD_GCMD_TE;
+    qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
+
+    /* Wait for TES */
+    qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
+                        VTD_GSTS_TES, true);
+
+    return 0;
+}
+
+uint32_t qvtd_trigger_dma(QVTDTestContext *ctx)
+{
+    uint64_t iova = ctx->config.dma_iova;
+    uint32_t len = ctx->config.dma_len;
+    uint32_t result, attrs_val;
+    const char *mode_str = (ctx->config.trans_mode == QVTD_TM_LEGACY_PT) ?
+                           "Pass-Through" : "Translated";
+
+    /* Write IOVA low 32 bits */
+    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_LO, (uint32_t)iova);
+
+    /* Write IOVA high 32 bits */
+    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_HI, (uint32_t)(iova >> 32));
+
+    /* Write DMA length */
+    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_LEN, len);
+
+    /* Build and write DMA attributes with BDF (PASID=0 for Legacy mode) */
+    attrs_val = qvtd_build_dma_attrs(ctx->sid, 0);
+    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_ATTRS, attrs_val);
+
+    /* Arm DMA by writing 1 to doorbell */
+    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_DBELL, ITD_DMA_DBELL_ARM);
+
+    /* Trigger DMA by reading from triggering register */
+    qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_TRIGGERING);
+
+    /* Poll for completion */
+    ctx->dma_result = ITD_DMA_RESULT_BUSY;
+    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
+        result = qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_RESULT);
+        if (result != ITD_DMA_RESULT_BUSY) {
+            ctx->dma_result = result;
+            break;
+        }
+        g_usleep(QVTD_POLL_DELAY_US);
+    }
+
+    if (ctx->dma_result == ITD_DMA_RESULT_BUSY) {
+        ctx->dma_result = ITD_DMA_ERR_TX_FAIL;
+        g_test_message("-> DMA timeout detected, forcing failure");
+    }
+
+    if (ctx->dma_result == 0) {
+        g_test_message("-> DMA succeeded: mode=%s", mode_str);
+    } else {
+        g_test_message("-> DMA failed: mode=%s result=0x%x",
+                       mode_str, ctx->dma_result);
+    }
+
+    return ctx->dma_result;
+}
+
+void qvtd_cleanup_translation(QVTDTestContext *ctx)
+{
+    uint8_t bus = (ctx->sid >> 8) & 0xff;
+    uint8_t devfn = ctx->sid & 0xff;
+    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
+    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
+    uint32_t gcmd;
+
+    /* Disable translation before tearing down the structures */
+    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
+    if (gcmd & VTD_GCMD_TE) {
+        gcmd &= ~VTD_GCMD_TE;
+        qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
+        qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
+                            VTD_GSTS_TES, false);
+    }
+
+    /* Clear context entry */
+    qtest_writeq(ctx->qts, context_entry_addr, 0);
+    qtest_writeq(ctx->qts, context_entry_addr + 8, 0);
+
+    /* Clear root entry */
+    qtest_writeq(ctx->qts, root_entry_addr, 0);
+    qtest_writeq(ctx->qts, root_entry_addr + 8, 0);
+
+    /* Invalidate caches using register-based invalidation */
+    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
+    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
+}
+
+bool qvtd_validate_test_result(QVTDTestContext *ctx)
+{
+    uint32_t expected = qvtd_expected_dma_result(ctx);
+    bool passed = (ctx->dma_result == expected);
+    bool mem_ok = true;
+
+    g_test_message("-> Validating result: expected=0x%x actual=0x%x",
+                   expected, ctx->dma_result);
+
+    if (passed && expected == 0) {
+        mem_ok = qvtd_validate_dma_memory(ctx);
+        g_test_message("-> Memory validation %s at PA=0x%llx",
+                       mem_ok ? "passed" : "failed",
+                       (unsigned long long)ctx->config.dma_pa);
+        passed = mem_ok;
+    }
+
+    return passed;
+}
+
+void qvtd_single_translation(QVTDTestContext *ctx)
+{
+    uint32_t config_result;
+    bool test_passed;
+
+    /* Configure Intel IOMMU translation */
+    config_result = qvtd_setup_and_enable_translation(ctx);
+    if (config_result != 0) {
+        g_test_message("Configuration failed: mode=%u status=0x%x",
+                       ctx->config.trans_mode, config_result);
+    }
+    g_assert_cmpint(config_result, ==, 0);
+
+    /* Trigger DMA operation */
+    qvtd_trigger_dma(ctx);
+
+    /* Validate test result */
+    test_passed = qvtd_validate_test_result(ctx);
+    g_assert_true(test_passed);
+
+    /* Clean up translation state to prepare for the next test */
+    qvtd_cleanup_translation(ctx);
+}
+
+void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
+                               QPCIBar bar, uint64_t iommu_base,
+                               const QVTDTestConfig *cfg)
+{
+    /* Initialize test memory */
+    qtest_memset(qts, cfg->dma_pa, 0x00, cfg->dma_len);
+
+    /* Create test context on stack */
+    QVTDTestContext ctx = {
+        .qts = qts,
+        .dev = dev,
+        .bar = bar,
+        .iommu_base = iommu_base,
+        .config = *cfg,
+        .trans_status = 0,
+        .dma_result = 0,
+        .sid = qvtd_calc_sid(dev),
+    };
+
+    /* Execute the test using existing single_translation logic */
+    qvtd_single_translation(&ctx);
+
+    /* Report results */
+    g_test_message("--> Test completed: mode=%u domain_id=%u "
+                   "status=0x%x result=0x%x",
+                   cfg->trans_mode, cfg->domain_id,
+                   ctx.trans_status, ctx.dma_result);
+}
+
+void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
+                            QTestState *qts, QPCIDevice *dev,
+                            QPCIBar bar, uint64_t iommu_base)
+{
+    for (size_t i = 0; i < count; i++) {
+        g_test_message("=== Running test %zu/%zu ===", i + 1, count);
+        qvtd_run_translation_case(qts, dev, bar, iommu_base, &configs[i]);
+    }
+}
diff --git a/tests/qtest/libqos/qos-intel-iommu.h b/tests/qtest/libqos/qos-intel-iommu.h
new file mode 100644
index 0000000000..dab5d4df63
--- /dev/null
+++ b/tests/qtest/libqos/qos-intel-iommu.h
@@ -0,0 +1,299 @@
+/*
+ * QOS Intel IOMMU (VT-d) Module
+ *
+ * This module provides Intel IOMMU-specific helper functions for libqos tests,
+ * encapsulating VT-d setup, assertion, and cleanup operations.
+ *
+ * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#ifndef QTEST_LIBQOS_INTEL_IOMMU_H
+#define QTEST_LIBQOS_INTEL_IOMMU_H
+
+#include "hw/misc/iommu-testdev.h"
+#include "hw/i386/intel_iommu_internal.h"
+
+/*
+ * Intel IOMMU MMIO register base. This is the standard Q35 IOMMU address.
+ */
+#define Q35_IOMMU_BASE            0xfed90000ULL
+
+/*
+ * Guest memory layout for IOMMU structures.
+ * All structures are placed in guest physical memory inside the 512MB RAM.
+ * Using 256MB mark (0x10000000) as base to ensure all structures fit in RAM.
+ */
+#define QVTD_MEM_BASE             0x10000000ULL
+
+/* Root Entry Table: 256 entries * 16 bytes = 4KB */
+#define QVTD_ROOT_TABLE_BASE      (QVTD_MEM_BASE + 0x00000000)
+
+/* Context Entry Table: 256 entries * 16 bytes = 4KB per bus */
+#define QVTD_CONTEXT_TABLE_BASE   (QVTD_MEM_BASE + 0x00001000)
+
+/* Page Tables: 4-level hierarchy for 48-bit address translation */
+#define QVTD_PT_L4_BASE           (QVTD_MEM_BASE + 0x00010000)  /* PML4 */
+#define QVTD_PT_L3_BASE           (QVTD_MEM_BASE + 0x00011000)  /* PDPT */
+#define QVTD_PT_L2_BASE           (QVTD_MEM_BASE + 0x00012000)  /* PD */
+#define QVTD_PT_L1_BASE           (QVTD_MEM_BASE + 0x00013000)  /* PT */
+
+/* Invalidation Queue: 256 entries * 16 bytes = 4KB */
+#define QVTD_INV_QUEUE_BASE       (QVTD_MEM_BASE + 0x00020000)
+
+/* Test IOVA and target physical address */
+#define QVTD_TEST_IOVA            0x0000008080604000ULL
+#define QVTD_TEST_PA              (QVTD_MEM_BASE + 0x00100000)
+
+/*
+ * Translation modes supported by Intel IOMMU
+ */
+typedef enum QVTDTransMode {
+    QVTD_TM_LEGACY_PT,      /* Legacy pass-through mode */
+    QVTD_TM_LEGACY_TRANS,   /* Legacy translated mode (4-level paging) */
+} QVTDTransMode;
+
+/*
+ * Test configuration structure
+ */
+typedef struct QVTDTestConfig {
+    QVTDTransMode trans_mode;     /* Translation mode */
+    uint64_t dma_iova;            /* DMA IOVA address for testing */
+    uint64_t dma_pa;              /* Target physical address */
+    uint32_t dma_len;             /* DMA length for testing */
+    uint32_t expected_result;     /* Expected DMA result */
+    uint16_t domain_id;           /* Domain ID for this test */
+} QVTDTestConfig;
+
+/*
+ * Test context structure
+ */
+typedef struct QVTDTestContext {
+    QTestState *qts;              /* QTest state handle */
+    QPCIDevice *dev;              /* PCI device handle */
+    QPCIBar bar;                  /* PCI BAR for MMIO access */
+    QVTDTestConfig config;        /* Test configuration */
+    uint64_t iommu_base;          /* Intel IOMMU base address */
+    uint32_t trans_status;        /* Translation configuration status */
+    uint32_t dma_result;          /* DMA operation result */
+    uint16_t sid;                 /* Source ID (bus:devfn) */
+} QVTDTestContext;
+
+/*
+ * qvtd_setup_and_enable_translation - Complete translation setup and enable
+ *
+ * @ctx: Test context containing configuration and device handles
+ *
+ * Returns: Translation status (0 = success, non-zero = error)
+ *
+ * This function performs the complete translation setup sequence:
+ * 1. Builds all required VT-d structures (root entry, context entry, page tables)
+ * 2. Programs IOMMU registers
+ * 3. Invalidates caches
+ * 4. Enables translation
+ */
+uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx);
+
+/*
+ * qvtd_build_translation - Build Intel IOMMU translation structures
+ *
+ * @qts: QTest state handle
+ * @mode: Translation mode (pass-through or translated)
+ * @sid: Source ID (bus:devfn)
+ * @domain_id: Domain ID
+ * @iova: IOVA address for logging purposes
+ * @pa: Physical address backed by the mapping
+ *
+ * Returns: Build status (0 = success, non-zero = error)
+ *
+ * Constructs all necessary VT-d translation structures in guest memory:
+ * - Root Entry for the device's bus
+ * - Context Entry for the device
+ * - Complete 4-level page table hierarchy (if translated mode)
+ */
+uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
+                                uint16_t sid, uint16_t domain_id,
+                                uint64_t iova, uint64_t pa);
+
+/*
+ * qvtd_program_regs - Program Intel IOMMU registers
+ *
+ * @qts: QTest state handle
+ * @iommu_base: IOMMU base address
+ *
+ * Programs IOMMU registers with the following sequence:
+ * 1. Disable translation
+ * 2. Program root table address
+ * 3. Set root table pointer
+ * 4. Unmask fault event interrupt
+ *
+ * Note: This function does NOT clear memory regions or enable translation.
+ * Memory clearing should be done once during test setup via qvtd_clear_memory_regions().
+ * Translation is enabled separately after building all structures.
+ */
+void qvtd_program_regs(QTestState *qts, uint64_t iommu_base);
+
+/*
+ * qvtd_trigger_dma - Trigger DMA operation via iommu-testdev
+ *
+ * @ctx: Test context
+ *
+ * Returns: DMA result code
+ *
+ * Programs iommu-testdev BAR0 registers to trigger a DMA operation:
+ * 1. Write IOVA address (GVA_LO/HI)
+ * 2. Write DMA length
+ * 3. Arm DMA (write to DBELL)
+ * 4. Trigger DMA (read from TRIGGERING)
+ * 5. Poll for completion (read DMA_RESULT)
+ */
+uint32_t qvtd_trigger_dma(QVTDTestContext *ctx);
+
+/*
+ * qvtd_cleanup_translation - Clean up translation configuration
+ *
+ * @ctx: Test context containing configuration and device handles
+ *
+ * Clears all translation structures and invalidates IOMMU caches.
+ */
+void qvtd_cleanup_translation(QVTDTestContext *ctx);
+
+/*
+ * qvtd_validate_test_result - Validate actual vs expected test result
+ *
+ * @ctx: Test context containing actual and expected results
+ *
+ * Returns: true if test passed (actual == expected), false otherwise
+ *
+ * Compares the actual DMA result with the expected result and logs
+ * the comparison for debugging purposes.
+ */
+bool qvtd_validate_test_result(QVTDTestContext *ctx);
+
+/*
+ * qvtd_setup_translation_tables - Setup complete VT-d page table hierarchy
+ *
+ * @qts: QTest state handle
+ * @iova: Input Virtual Address to translate
+ * @pa: Physical address to map to
+ * @mode: Translation mode
+ *
+ * This function builds the complete 4-level page table structure for translating
+ * the given IOVA to PA through Intel VT-d. The structure is:
+ * - PML4 (Level 4): IOVA bits [47:39]
+ * - PDPT (Level 3): IOVA bits [38:30]
+ * - PD (Level 2): IOVA bits [29:21]
+ * - PT (Level 1): IOVA bits [20:12]
+ * - Page offset: IOVA bits [11:0]
+ *
+ * The function writes all necessary Page Table Entries (PTEs) to guest
+ * memory using qtest_writeq(), setting up the complete translation path
+ * that the VT-d hardware will traverse during DMA operations.
+ */
+void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
+                                   uint64_t pa, QVTDTransMode mode);
+
+/*
+ * qvtd_expected_dma_result - Calculate expected DMA result
+ *
+ * @ctx: Test context containing configuration
+ *
+ * Returns: Expected DMA result code
+ *
+ * This function acts as a test oracle, calculating the expected DMA result
+ * based on the test configuration. It centralizes validation logic for
+ * different scenarios (pass-through vs. translated, fault conditions).
+ */
+uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx);
+
+/*
+ * qvtd_build_dma_attrs - Build DMA attributes for an Intel VT-d DMA request
+ *
+ * @bdf: PCI requester ID encoded as Bus[15:8]/Device[7:3]/Function[2:0]
+ * @pasid: PASID tag (0 for legacy requests, non-zero for scalable mode)
+ *
+ * Returns: Value to program into iommu-testdev's DMA_ATTRS register
+ *
+ * The iommu-testdev attribute register mirrors Intel VT-d request metadata:
+ *   - bits[2:0] keep the generic iommu-testdev fields (secure + space)
+ *   - bit[4] selects legacy (0) vs. scalable (1) transactions
+ *   - bits[23:8] carry the requester ID as defined in the VT-d spec
+ *   - bits[31:24] carry the PASID (limited to 8 bits in QEMU, matching
+ *     the MemTxAttrs::pid width and ECAP.PSS advertisement)
+ *
+ * The helper validates the BDF layout (bus <= 255, device <= 31, function <= 7)
+ * and makes sure PASID fits in the supported width before returning the value.
+ */
+uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid);
+
+/*
+ * High-level test execution functions
+ */
+
+/*
+ * qvtd_single_translation - Execute single translation test
+ *
+ * @ctx: Test context
+ *
+ * Performs a complete test cycle:
+ * 1. Setup translation structures
+ * 2. Trigger DMA operation
+ * 3. Validate results
+ * 4. Cleanup
+ */
+void qvtd_single_translation(QVTDTestContext *ctx);
+
+/*
+ * qvtd_run_translation_case - Execute a single Intel VT-d translation test
+ *
+ * @qts: QTestState for the test
+ * @dev: PCI device (iommu-testdev)
+ * @bar: BAR0 of iommu-testdev
+ * @iommu_base: Base address of Intel IOMMU MMIO registers
+ * @cfg: Test configuration
+ *
+ * High-level wrapper that creates test context internally and executes
+ * a single translation test case. This provides a simpler API compared
+ * to qvtd_single_translation() which requires manual context initialization.
+ *
+ * This function is analogous to qriommu_run_translation_case() in the
+ * RISC-V IOMMU test framework, providing a consistent API across different
+ * IOMMU architectures.
+ *
+ * Example usage:
+ *   QVTDTestConfig cfg = {
+ *       .trans_mode = QVTD_TM_LEGACY_PT,
+ *       .domain_id = 1,
+ *       .dma_iova = 0x40100000,
+ *       .dma_pa = 0x40100000,
+ *       .dma_len = 4,
+ *   };
+ *   qvtd_run_translation_case(qts, dev, bar, iommu_base, &cfg);
+ */
+void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
+                               QPCIBar bar, uint64_t iommu_base,
+                               const QVTDTestConfig *cfg);
+
+/*
+ * qvtd_translation_batch - Execute batch of translation tests
+ *
+ * @configs: Array of test configurations
+ * @count: Number of configurations
+ * @qts: QTest state handle
+ * @dev: PCI device handle
+ * @bar: PCI BAR for MMIO access
+ * @iommu_base: IOMMU base address
+ *
+ * Executes multiple translation tests in sequence, each with its own
+ * configuration. Useful for testing different translation modes and
+ * scenarios in a single test run.
+ *
+ * This function now uses qvtd_run_translation_case() internally to
+ * reduce code duplication.
+ */
+void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
+                            QTestState *qts, QPCIDevice *dev,
+                            QPCIBar bar, uint64_t iommu_base);
+
+#endif /* QTEST_LIBQOS_INTEL_IOMMU_H */
-- 
2.39.5

Re: [PATCH RFC v1 1/2] tests/qtest/libqos: Add Intel IOMMU helper library

Posted by Chao Liu 2 days, 22 hours ago

Hi Fengyuan,

Thanks for working on Intel IOMMU bare-metal testing support. I have some
comments below.

On Wed, Feb 04, 2026 at 11:06:19AM +0800, Fengyuan Yu wrote:
> Introduce a libqos helper module for Intel IOMMU (VT-d) testing with
> iommu-testdev. The helper provides routines to:
> 
> - Build Root Entry Tables, Context Entry Tables, and 4-level page tables
>   for 48-bit address translation
> - Program VT-d registers (Root Table Pointer, Global Command Register)
>   following the Intel VT-d specification
> - Execute DMA translations and verify results
> 
> The current implementation supports Legacy mode with both pass-through and
> translated (4-level paging) modes. Support for Scalable mode (PASID-based)
> can be added in future patches.
> 
The commit message looks good.

> Signed-off-by: Fengyuan Yu <15fengyuan@gmail.com>
> 
> ---
>  MAINTAINERS                          |   1 +
>  tests/qtest/libqos/meson.build       |   3 +
>  tests/qtest/libqos/qos-intel-iommu.c | 566 +++++++++++++++++++++++++++
>  tests/qtest/libqos/qos-intel-iommu.h | 299 ++++++++++++++
>  4 files changed, 869 insertions(+)
>  create mode 100644 tests/qtest/libqos/qos-intel-iommu.c
>  create mode 100644 tests/qtest/libqos/qos-intel-iommu.h
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9b7ed4fccb..1cd2a4f474 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -3585,6 +3585,7 @@ M: Tao Tang <tangtao1634@phytium.com.cn>
>  S: Maintained
>  F: tests/qtest/libqos/qos-iommu*
>  F: tests/qtest/libqos/qos-smmuv3*
> +F: tests/qtest/libqos/qos-intel-iommu*
>  
>  Device Fuzzing
>  M: Alexander Bulekov <alxndr@bu.edu>
> diff --git a/tests/qtest/libqos/meson.build b/tests/qtest/libqos/meson.build
> index 8d6758ec2b..7f7c4f9c6f 100644
> --- a/tests/qtest/libqos/meson.build
> +++ b/tests/qtest/libqos/meson.build
> @@ -72,6 +72,9 @@ endif
>  if config_all_devices.has_key('CONFIG_RISCV_IOMMU')
>    libqos_srcs += files('riscv-iommu.c')
>  endif
> +if config_all_devices.has_key('CONFIG_VTD')
> +  libqos_srcs += files('qos-intel-iommu.c')
> +endif
>  if config_all_devices.has_key('CONFIG_TPCI200')
>    libqos_srcs += files('tpci200.c')
>  endif
> diff --git a/tests/qtest/libqos/qos-intel-iommu.c b/tests/qtest/libqos/qos-intel-iommu.c
> new file mode 100644
> index 0000000000..d6a733de7e
> --- /dev/null
> +++ b/tests/qtest/libqos/qos-intel-iommu.c
> @@ -0,0 +1,566 @@
> +/*
> + * QOS Intel IOMMU (VT-d) Module Implementation
> + *
> + * This module provides Intel IOMMU-specific helper functions for libqos tests.
> + *
> + * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
> + *
> + * SPDX-License-Identifier: GPL-2.0-or-later
> + */
> +
> +#include "qemu/osdep.h"
> +#include "../libqtest.h"
> +#include "pci.h"
> +#include "qos-intel-iommu.h"
> +
You should also include "qos-iommu-testdev.h" here, as the SMMUv3 helper
does. This would allow reusing the common DMA trigger infrastructure.

> +#define QVTD_POLL_DELAY_US        1000
> +#define QVTD_POLL_MAX_RETRIES     1000
> +#define QVTD_AW_48BIT_ENCODING    2
> +
> +/*
> + * iommu-testdev DMA attribute layout for Intel VT-d traffic.
> + *
> + * Bits [2:0] keep using the generic iommu-testdev encoding
> + * (secure + ArmSecuritySpace). Bits [23:8] carry the PCI Requester ID in the
> + * format defined in the Intel VT-d spec (Figure 3-2 in
> + * spec/Intel-iommu-spec.txt), and bits [31:24] contain the PASID that tags
> + * scalable-mode transactions. Bit 4 distinguishes between pure legacy RID
> + * requests and scalable-mode PASID-tagged requests. The PASID field is
> + * limited to 8 bits because MemTxAttrs::pid only carries 8 bits today (see
> + * include/exec/memattrs.h and the VTD_ECAP_PSS limit in
> + * hw/i386/intel_iommu_internal.h).
> + */
> +#define QVTD_DMA_ATTR_MODE_SHIFT      4
> +#define QVTD_DMA_ATTR_MODE_MASK       0x1
> +#define QVTD_DMA_ATTR_MODE_LEGACY     0
> +#define QVTD_DMA_ATTR_MODE_SCALABLE   1
> +#define QVTD_DMA_ATTR_RID_SHIFT       8
> +#define QVTD_DMA_ATTR_RID_MASK        0xffffu
> +#define QVTD_DMA_ATTR_PASID_BITS      8
> +#define QVTD_DMA_ATTR_PASID_SHIFT     24
> +#define QVTD_DMA_ATTR_PASID_MASK      ((1u << QVTD_DMA_ATTR_PASID_BITS) - 1)
> +
> +#define QVTD_PCI_FUNCS_PER_DEVICE     8
> +#define QVTD_PCI_DEVS_PER_BUS         32
> +
> +static void qvtd_wait_for_bitsl(QTestState *qts, uint64_t addr,
> +                                uint32_t mask, bool expect_set)
> +{
> +    uint32_t val = 0;
> +
> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
> +        val = qtest_readl(qts, addr);
> +        if (!!(val & mask) == expect_set) {
> +            return;
> +        }
> +        g_usleep(QVTD_POLL_DELAY_US);
> +    }
> +
> +    g_error("Timeout waiting for bits 0x%x (%s) at 0x%llx, last=0x%x",
Please use PRIx64 instead of %llx with (unsigned long long) cast.
This applies to all similar occurrences in this file.

> +            mask, expect_set ? "set" : "clear",
> +            (unsigned long long)addr, val);
> +}
> +
> +static void qvtd_wait_for_bitsq(QTestState *qts, uint64_t addr,
> +                                uint64_t mask, bool expect_set)
> +{
> +    uint64_t val = 0;
> +
> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
> +        val = qtest_readq(qts, addr);
> +        if (!!(val & mask) == expect_set) {
> +            return;
> +        }
> +        g_usleep(QVTD_POLL_DELAY_US);
> +    }
> +
> +    g_error("Timeout waiting for bits 0x%llx (%s) at 0x%llx, last=0x%llx",
> +            (unsigned long long)mask, expect_set ? "set" : "clear",
> +            (unsigned long long)addr, (unsigned long long)val);
> +}
> +
> +static uint16_t qvtd_calc_sid(const QPCIDevice *dev)
> +{
> +    uint16_t devfn = dev->devfn & 0xff;
> +    uint16_t bus = (dev->devfn >> 8) & 0xff;
> +    uint8_t device = (devfn >> 3) & 0x1f;
> +    uint8_t function = devfn & 0x7;
> +
> +    /* Validate BDF components. */
> +    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
> +        g_error("Invalid BDF: bus=%u device=%u function=%u", bus, device, function);
> +    }
> +
> +    return (bus << 8) | devfn;
> +}
> +
> +static bool qvtd_validate_dma_memory(QVTDTestContext *ctx)
> +{
> +    uint32_t len = ctx->config.dma_len;
> +    g_autofree uint8_t *buf = NULL;
> +
> +    if (!len) {
> +        return true;
> +    }
> +
> +    buf = g_malloc(len);
> +    qtest_memread(ctx->qts, ctx->config.dma_pa, buf, len);
> +
> +    for (uint32_t i = 0; i < len; i++) {
> +        uint8_t expected = (ITD_DMA_WRITE_VAL >> ((i % 4) * 8)) & 0xff;
> +        if (buf[i] != expected) {
> +            g_test_message("Memory mismatch at PA=0x%llx offset=%u "
> +                           "expected=0x%02x actual=0x%02x",
> +                           (unsigned long long)ctx->config.dma_pa, i,
> +                           expected, buf[i]);
> +            return false;
> +        }
> +    }
> +
> +    return true;
> +}
> +
> +uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx)
> +{
> +    return ctx->config.expected_result;
> +}
> +
> +uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid)
> +{
> +    uint32_t attrs = 0;
> +    uint8_t bus = (bdf >> 8) & 0xff;
> +    uint8_t devfn = bdf & 0xff;
> +    uint8_t device = devfn >> 3;
> +    uint8_t function = devfn & 0x7;
> +    bool scalable_mode = pasid != 0;
> +
> +    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
> +        g_error("Invalid requester-id 0x%04x (bus=%u device=%u function=%u)",
> +                bdf, bus, device, function);
> +    }
> +
> +    attrs = ITD_ATTRS_SET_SECURE(attrs, 0);
> +    attrs = ITD_ATTRS_SET_SPACE(attrs, 0);
> +    attrs |= ((uint32_t)bdf & QVTD_DMA_ATTR_RID_MASK) << QVTD_DMA_ATTR_RID_SHIFT;
> +
> +    if (scalable_mode) {
> +        if (pasid > QVTD_DMA_ATTR_PASID_MASK) {
> +            g_error("PASID 0x%x exceeds %u-bit limit imposed by MemTxAttrs",
> +                    pasid, QVTD_DMA_ATTR_PASID_BITS);
> +        }
> +
> +        attrs |= (QVTD_DMA_ATTR_MODE_SCALABLE << QVTD_DMA_ATTR_MODE_SHIFT);
> +        attrs |= ((pasid & QVTD_DMA_ATTR_PASID_MASK) << QVTD_DMA_ATTR_PASID_SHIFT);
> +    } else {
> +        attrs |= (QVTD_DMA_ATTR_MODE_LEGACY << QVTD_DMA_ATTR_MODE_SHIFT);
> +    }
> +
> +    return attrs;
> +}
> +
> +static void qvtd_build_root_entry(QTestState *qts, uint8_t bus,
> +                                  uint64_t context_table_ptr)
> +{
> +    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
> +    uint64_t lo, hi;
> +
> +    /* Root Entry Low: Context Table Pointer + Present bit (VT-d spec Section 9.1). */
> +    lo = (context_table_ptr & VTD_CONTEXT_ENTRY_SLPTPTR) | VTD_CONTEXT_ENTRY_P;
> +    hi = 0;  /* Reserved. */
> +
> +    qtest_writeq(qts, root_entry_addr, lo);
> +    qtest_writeq(qts, root_entry_addr + 8, hi);
> +}
> +
> +static void qvtd_build_context_entry(QTestState *qts, uint16_t sid,
> +                                     QVTDTransMode mode, uint16_t domain_id,
> +                                     uint64_t slptptr)
> +{
> +    uint8_t devfn = sid & 0xff;
> +    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
> +    uint64_t lo, hi;
> +
> +    if (mode == QVTD_TM_LEGACY_PT) {
> +        /* Pass-through mode (VT-d spec Section 3.9, Section 9.3). */
> +        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_PASS_THROUGH;
> +        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
> +    } else {
> +        /* Translated mode: 4-level paging (AW=2 for 48-bit, VT-d spec Section 9.3). */
> +        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_MULTI_LEVEL |
> +             (slptptr & VTD_CONTEXT_ENTRY_SLPTPTR);
> +        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
> +    }
> +
> +    qtest_writeq(qts, context_entry_addr, lo);
> +    qtest_writeq(qts, context_entry_addr + 8, hi);
> +}
> +
> +void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
> +                                   uint64_t pa, QVTDTransMode mode)
> +{
> +    uint64_t pml4_entry, pdpt_entry, pd_entry, pt_entry;
> +    uint64_t pml4_addr, pdpt_addr, pd_addr, pt_addr;
> +    uint32_t pml4_idx, pdpt_idx, pd_idx, pt_idx;
> +    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
> +                           "Pass-Through" : "Translated";
> +
> +    g_test_message("Begin of page table construction: IOVA=0x%llx PA=0x%llx mode=%s",
> +                   (unsigned long long)iova, (unsigned long long)pa, mode_str);
> +
> +    /* Pass-through mode doesn't need page tables */
> +    if (mode == QVTD_TM_LEGACY_PT) {
> +        g_test_message("Pass-through mode: skipping page table setup");
> +        return;
> +    }
> +
> +    /* Extract indices from IOVA
> +     * 4-level paging for 48-bit virtual address space:
> +     * - PML4 index: bits [47:39] (9 bits = 512 entries)
> +     * - PDPT index:  bits [38:30] (9 bits = 512 entries)
> +     * - PD index:    bits [29:21] (9 bits = 512 entries)
> +     * - PT index:    bits [20:12] (9 bits = 512 entries)
> +     * - Page offset: bits [11:0]  (12 bits = 4KB pages)
> +     */
> +    pml4_idx = (iova >> 39) & 0x1ff;  /* Bits [47:39] */
> +    pdpt_idx = (iova >> 30) & 0x1ff;  /* Bits [38:30] */
> +    pd_idx = (iova >> 21) & 0x1ff;    /* Bits [29:21] */
> +    pt_idx = (iova >> 12) & 0x1ff;    /* Bits [20:12] */
> +
> +    /*
> +     * Build 4-level page table hierarchy (VT-d spec Section 9.3, Table 9-3).
> +     * Non-leaf entries: both R+W set for full access (spec allows R or W individually).
> +     * Per VT-d spec Section 9.8: "If either the R or W field of a non-leaf
> +     * paging-structure entry is 1", indicating that setting one or both is valid.
> +     * We set both R+W for non-leaf entries as standard practice.
> +     */
> +
> +    /* PML4 Entry: points to PDPT. */
> +    pml4_addr = QVTD_PT_L4_BASE + (pml4_idx * 8);
> +    pml4_entry = QVTD_PT_L3_BASE | VTD_SL_R | VTD_SL_W;
> +    qtest_writeq(qts, pml4_addr, pml4_entry);
> +
> +    /* PDPT Entry: points to PD. */
> +    pdpt_addr = QVTD_PT_L3_BASE + (pdpt_idx * 8);
> +    pdpt_entry = QVTD_PT_L2_BASE | VTD_SL_R | VTD_SL_W;
> +    qtest_writeq(qts, pdpt_addr, pdpt_entry);
> +
> +    /* PD Entry: points to PT. */
> +    pd_addr = QVTD_PT_L2_BASE + (pd_idx * 8);
> +    pd_entry = QVTD_PT_L1_BASE | VTD_SL_R | VTD_SL_W;
> +    qtest_writeq(qts, pd_addr, pd_entry);
> +
> +    /* PT Entry: points to physical page (leaf). */
> +    pt_addr = QVTD_PT_L1_BASE + (pt_idx * 8);
> +    pt_entry = (pa & VTD_PAGE_MASK_4K) | VTD_SL_R | VTD_SL_W;
> +    qtest_writeq(qts, pt_addr, pt_entry);
> +
> +    g_test_message("End of page table construction: mapped IOVA=0x%llx -> PA=0x%llx",
> +                   (unsigned long long)iova, (unsigned long long)pa);
> +}
> +
> +static void qvtd_invalidate_context_cache(QTestState *qts,
> +                                          uint64_t iommu_base)
> +{
> +    uint64_t ccmd_val;
> +
> +    /* Context Command Register: Global invalidation (VT-d spec Section 6.5.1.1). */
> +    ccmd_val = VTD_CCMD_ICC | VTD_CCMD_GLOBAL_INVL;
> +    qtest_writeq(qts, iommu_base + DMAR_CCMD_REG, ccmd_val);
> +
> +    /* Wait for ICC bit to clear. */
> +    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_CCMD_REG,
> +                        VTD_CCMD_ICC, false);
> +}
> +
> +static void qvtd_invalidate_iotlb(QTestState *qts, uint64_t iommu_base)
> +{
> +    uint64_t iotlb_val;
> +
> +    /* IOTLB Invalidate Register: Global flush (VT-d spec Section 6.5.1.2). */
> +    iotlb_val = VTD_TLB_IVT | VTD_TLB_GLOBAL_FLUSH;
> +    qtest_writeq(qts, iommu_base + DMAR_IOTLB_REG, iotlb_val);
> +
> +    /* Wait for IVT bit to clear. */
> +    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_IOTLB_REG,
> +                        VTD_TLB_IVT, false);
> +}
> +
> +static void qvtd_clear_memory_regions(QTestState *qts)
> +{
> +    /* Clear root table. */
> +    qtest_memset(qts, QVTD_ROOT_TABLE_BASE, 0, 4096);
> +
> +    /* Clear context table. */
> +    qtest_memset(qts, QVTD_CONTEXT_TABLE_BASE, 0, 4096);
> +
> +    /* Clear all page table levels (4 levels * 4KB each = 16KB). */
> +    qtest_memset(qts, QVTD_PT_L4_BASE, 0, 16384);
> +}
> +
> +void qvtd_program_regs(QTestState *qts, uint64_t iommu_base)
> +{
> +    uint32_t gcmd;
> +
> +    /* 1. Disable translation (VT-d spec Section 11.4.4). */
> +    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
> +    gcmd &= ~VTD_GCMD_TE;
> +    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
> +
> +    /* Wait for TES to clear. */
> +    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
> +                        VTD_GSTS_TES, false);
> +
> +    /* 2. Program root table address (VT-d spec Section 11.4.5). */
> +    qtest_writeq(qts, iommu_base + DMAR_RTADDR_REG, QVTD_ROOT_TABLE_BASE);
> +
> +    /* 3. Set root table pointer (VT-d spec Section 6.6). */
> +    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
> +    gcmd |= VTD_GCMD_SRTP;
> +    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
> +
> +    /* Wait for RTPS. */
> +    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
> +                        VTD_GSTS_RTPS, true);
> +
> +    /* Invalidate context cache after setting root table pointer. */
> +    qvtd_invalidate_context_cache(qts, iommu_base);
> +
> +    /* 4. Unmask fault event interrupt to avoid warning messages. */
> +    qtest_writel(qts, iommu_base + DMAR_FECTL_REG, 0);
> +
> +    /* NOTE: Translation is NOT enabled here - caller must enable after building structures. */
> +}
> +
> +uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
> +                                uint16_t sid, uint16_t domain_id,
> +                                uint64_t iova, uint64_t pa)
> +{
> +    uint8_t bus = (sid >> 8) & 0xff;
> +    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
> +                           "Pass-Through" : "Translated";
> +
> +    g_test_message("Begin of construction: IOVA=0x%llx PA=0x%llx "
> +                   "mode=%s domain_id=%u ===",
> +                   (unsigned long long)iova, (unsigned long long)pa,
> +                   mode_str, domain_id);
> +
> +    /* Build root entry */
> +    qvtd_build_root_entry(qts, bus, QVTD_CONTEXT_TABLE_BASE);
> +
> +    /* Build context entry */
> +    if (mode == QVTD_TM_LEGACY_PT) {
> +        /* Pass-through mode: no page tables needed */
> +        qvtd_build_context_entry(qts, sid, mode, domain_id, 0);
> +        g_test_message("End of construction: identity mapping to PA=0x%llx ===",
> +                       (unsigned long long)pa);
> +    } else {
> +        /* Translated mode: build 4-level page tables */
> +        qvtd_setup_translation_tables(qts, iova, pa, QVTD_TM_LEGACY_TRANS);
> +        qvtd_build_context_entry(qts, sid, mode, domain_id, QVTD_PT_L4_BASE);
> +        g_test_message("End of construction: mapped IOVA=0x%llx -> PA=0x%llx ===",
> +                       (unsigned long long)iova, (unsigned long long)pa);
> +    }
> +
> +    return 0;
> +}
> +
> +uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx)
> +{
> +    uint32_t gcmd;
> +
> +    /* Clear memory regions once during setup */
> +    qvtd_clear_memory_regions(ctx->qts);
> +
> +    /* Program IOMMU registers (sets up root table pointer) */
> +    qvtd_program_regs(ctx->qts, ctx->iommu_base);
> +
> +    /* Build translation structures AFTER clearing memory */
> +    ctx->trans_status = qvtd_build_translation(ctx->qts, ctx->config.trans_mode,
> +                                               ctx->sid, ctx->config.domain_id,
> +                                               ctx->config.dma_iova,
> +                                               ctx->config.dma_pa);
> +    if (ctx->trans_status != 0) {
> +        return ctx->trans_status;
> +    }
> +
> +    /* Invalidate caches using register-based invalidation */
> +    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
> +    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
> +
> +    /* Enable translation AFTER building structures and invalidating caches */
> +    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
> +    gcmd |= VTD_GCMD_TE;
> +    qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
> +
> +    /* Wait for TES */
> +    qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
> +                        VTD_GSTS_TES, true);
> +
> +    return 0;
> +}
> +
> +uint32_t qvtd_trigger_dma(QVTDTestContext *ctx)
This function duplicates the logic in qos_iommu_testdev_trigger_dma().
The SMMUv3 helper uses the common qos-iommu-testdev infrastructure with
callback functions (setup_fn, attrs_fn, validate_fn, report_fn).

I'd suggest refactoring to use qos_iommu_testdev_single_translation()
instead, similar to how qsmmu_run_translation_case() does it in
qos-smmuv3.c

Thanks,
Chao
> +{
> +    uint64_t iova = ctx->config.dma_iova;
> +    uint32_t len = ctx->config.dma_len;
> +    uint32_t result, attrs_val;
> +    const char *mode_str = (ctx->config.trans_mode == QVTD_TM_LEGACY_PT) ?
> +                           "Pass-Through" : "Translated";
> +
> +    /* Write IOVA low 32 bits */
> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_LO, (uint32_t)iova);
> +
> +    /* Write IOVA high 32 bits */
> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_HI, (uint32_t)(iova >> 32));
> +
> +    /* Write DMA length */
> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_LEN, len);
> +
> +    /* Build and write DMA attributes with BDF (PASID=0 for Legacy mode) */
> +    attrs_val = qvtd_build_dma_attrs(ctx->sid, 0);
> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_ATTRS, attrs_val);
> +
> +    /* Arm DMA by writing 1 to doorbell */
> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_DBELL, ITD_DMA_DBELL_ARM);
> +
> +    /* Trigger DMA by reading from triggering register */
> +    qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_TRIGGERING);
> +
> +    /* Poll for completion */
> +    ctx->dma_result = ITD_DMA_RESULT_BUSY;
> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
> +        result = qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_RESULT);
> +        if (result != ITD_DMA_RESULT_BUSY) {
> +            ctx->dma_result = result;
> +            break;
> +        }
> +        g_usleep(QVTD_POLL_DELAY_US);
> +    }
> +
> +    if (ctx->dma_result == ITD_DMA_RESULT_BUSY) {
> +        ctx->dma_result = ITD_DMA_ERR_TX_FAIL;
> +        g_test_message("-> DMA timeout detected, forcing failure");
> +    }
> +
> +    if (ctx->dma_result == 0) {
> +        g_test_message("-> DMA succeeded: mode=%s", mode_str);
> +    } else {
> +        g_test_message("-> DMA failed: mode=%s result=0x%x",
> +                       mode_str, ctx->dma_result);
> +    }
> +
> +    return ctx->dma_result;
> +}
> +
> +void qvtd_cleanup_translation(QVTDTestContext *ctx)
> +{
> +    uint8_t bus = (ctx->sid >> 8) & 0xff;
> +    uint8_t devfn = ctx->sid & 0xff;
> +    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
> +    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
> +    uint32_t gcmd;
> +
> +    /* Disable translation before tearing down the structures */
> +    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
> +    if (gcmd & VTD_GCMD_TE) {
> +        gcmd &= ~VTD_GCMD_TE;
> +        qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
> +        qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
> +                            VTD_GSTS_TES, false);
> +    }
> +
> +    /* Clear context entry */
> +    qtest_writeq(ctx->qts, context_entry_addr, 0);
> +    qtest_writeq(ctx->qts, context_entry_addr + 8, 0);
> +
> +    /* Clear root entry */
> +    qtest_writeq(ctx->qts, root_entry_addr, 0);
> +    qtest_writeq(ctx->qts, root_entry_addr + 8, 0);
> +
> +    /* Invalidate caches using register-based invalidation */
> +    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
> +    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
> +}
> +
> +bool qvtd_validate_test_result(QVTDTestContext *ctx)
> +{
> +    uint32_t expected = qvtd_expected_dma_result(ctx);
> +    bool passed = (ctx->dma_result == expected);
> +    bool mem_ok = true;
> +
> +    g_test_message("-> Validating result: expected=0x%x actual=0x%x",
> +                   expected, ctx->dma_result);
> +
> +    if (passed && expected == 0) {
> +        mem_ok = qvtd_validate_dma_memory(ctx);
> +        g_test_message("-> Memory validation %s at PA=0x%llx",
> +                       mem_ok ? "passed" : "failed",
> +                       (unsigned long long)ctx->config.dma_pa);
> +        passed = mem_ok;
> +    }
> +
> +    return passed;
> +}
> +
> +void qvtd_single_translation(QVTDTestContext *ctx)
> +{
> +    uint32_t config_result;
> +    bool test_passed;
> +
> +    /* Configure Intel IOMMU translation */
> +    config_result = qvtd_setup_and_enable_translation(ctx);
> +    if (config_result != 0) {
> +        g_test_message("Configuration failed: mode=%u status=0x%x",
> +                       ctx->config.trans_mode, config_result);
> +    }
> +    g_assert_cmpint(config_result, ==, 0);
> +
> +    /* Trigger DMA operation */
> +    qvtd_trigger_dma(ctx);
> +
> +    /* Validate test result */
> +    test_passed = qvtd_validate_test_result(ctx);
> +    g_assert_true(test_passed);
> +
> +    /* Clean up translation state to prepare for the next test */
> +    qvtd_cleanup_translation(ctx);
> +}
> +
> +void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
> +                               QPCIBar bar, uint64_t iommu_base,
> +                               const QVTDTestConfig *cfg)
> +{
> +    /* Initialize test memory */
> +    qtest_memset(qts, cfg->dma_pa, 0x00, cfg->dma_len);
> +
> +    /* Create test context on stack */
> +    QVTDTestContext ctx = {
> +        .qts = qts,
> +        .dev = dev,
> +        .bar = bar,
> +        .iommu_base = iommu_base,
> +        .config = *cfg,
> +        .trans_status = 0,
> +        .dma_result = 0,
> +        .sid = qvtd_calc_sid(dev),
> +    };
> +
> +    /* Execute the test using existing single_translation logic */
> +    qvtd_single_translation(&ctx);
> +
> +    /* Report results */
> +    g_test_message("--> Test completed: mode=%u domain_id=%u "
> +                   "status=0x%x result=0x%x",
> +                   cfg->trans_mode, cfg->domain_id,
> +                   ctx.trans_status, ctx.dma_result);
> +}
> +
> +void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
> +                            QTestState *qts, QPCIDevice *dev,
> +                            QPCIBar bar, uint64_t iommu_base)
> +{
> +    for (size_t i = 0; i < count; i++) {
> +        g_test_message("=== Running test %zu/%zu ===", i + 1, count);
> +        qvtd_run_translation_case(qts, dev, bar, iommu_base, &configs[i]);
> +    }
> +}
> diff --git a/tests/qtest/libqos/qos-intel-iommu.h b/tests/qtest/libqos/qos-intel-iommu.h
> new file mode 100644
> index 0000000000..dab5d4df63
> --- /dev/null
> +++ b/tests/qtest/libqos/qos-intel-iommu.h
> @@ -0,0 +1,299 @@
> +/*
> + * QOS Intel IOMMU (VT-d) Module
> + *
> + * This module provides Intel IOMMU-specific helper functions for libqos tests,
> + * encapsulating VT-d setup, assertion, and cleanup operations.
> + *
> + * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
> + *
> + * SPDX-License-Identifier: GPL-2.0-or-later
> + */
> +
> +#ifndef QTEST_LIBQOS_INTEL_IOMMU_H
> +#define QTEST_LIBQOS_INTEL_IOMMU_H
> +
> +#include "hw/misc/iommu-testdev.h"
> +#include "hw/i386/intel_iommu_internal.h"
> +
> +/*
> + * Intel IOMMU MMIO register base. This is the standard Q35 IOMMU address.
> + */
> +#define Q35_IOMMU_BASE            0xfed90000ULL
> +
> +/*
> + * Guest memory layout for IOMMU structures.
> + * All structures are placed in guest physical memory inside the 512MB RAM.
> + * Using 256MB mark (0x10000000) as base to ensure all structures fit in RAM.
> + */
> +#define QVTD_MEM_BASE             0x10000000ULL
> +
> +/* Root Entry Table: 256 entries * 16 bytes = 4KB */
> +#define QVTD_ROOT_TABLE_BASE      (QVTD_MEM_BASE + 0x00000000)
> +
> +/* Context Entry Table: 256 entries * 16 bytes = 4KB per bus */
> +#define QVTD_CONTEXT_TABLE_BASE   (QVTD_MEM_BASE + 0x00001000)
> +
> +/* Page Tables: 4-level hierarchy for 48-bit address translation */
> +#define QVTD_PT_L4_BASE           (QVTD_MEM_BASE + 0x00010000)  /* PML4 */
> +#define QVTD_PT_L3_BASE           (QVTD_MEM_BASE + 0x00011000)  /* PDPT */
> +#define QVTD_PT_L2_BASE           (QVTD_MEM_BASE + 0x00012000)  /* PD */
> +#define QVTD_PT_L1_BASE           (QVTD_MEM_BASE + 0x00013000)  /* PT */
> +
> +/* Invalidation Queue: 256 entries * 16 bytes = 4KB */
> +#define QVTD_INV_QUEUE_BASE       (QVTD_MEM_BASE + 0x00020000)
> +
> +/* Test IOVA and target physical address */
> +#define QVTD_TEST_IOVA            0x0000008080604000ULL
> +#define QVTD_TEST_PA              (QVTD_MEM_BASE + 0x00100000)
> +
> +/*
> + * Translation modes supported by Intel IOMMU
> + */
> +typedef enum QVTDTransMode {
> +    QVTD_TM_LEGACY_PT,      /* Legacy pass-through mode */
> +    QVTD_TM_LEGACY_TRANS,   /* Legacy translated mode (4-level paging) */
> +} QVTDTransMode;
> +
> +/*
> + * Test configuration structure
> + */
> +typedef struct QVTDTestConfig {
> +    QVTDTransMode trans_mode;     /* Translation mode */
> +    uint64_t dma_iova;            /* DMA IOVA address for testing */
> +    uint64_t dma_pa;              /* Target physical address */
> +    uint32_t dma_len;             /* DMA length for testing */
> +    uint32_t expected_result;     /* Expected DMA result */
> +    uint16_t domain_id;           /* Domain ID for this test */
> +} QVTDTestConfig;
> +
> +/*
> + * Test context structure
> + */
> +typedef struct QVTDTestContext {
> +    QTestState *qts;              /* QTest state handle */
> +    QPCIDevice *dev;              /* PCI device handle */
> +    QPCIBar bar;                  /* PCI BAR for MMIO access */
> +    QVTDTestConfig config;        /* Test configuration */
> +    uint64_t iommu_base;          /* Intel IOMMU base address */
> +    uint32_t trans_status;        /* Translation configuration status */
> +    uint32_t dma_result;          /* DMA operation result */
> +    uint16_t sid;                 /* Source ID (bus:devfn) */
> +} QVTDTestContext;
> +
> +/*
> + * qvtd_setup_and_enable_translation - Complete translation setup and enable
> + *
> + * @ctx: Test context containing configuration and device handles
> + *
> + * Returns: Translation status (0 = success, non-zero = error)
> + *
> + * This function performs the complete translation setup sequence:
> + * 1. Builds all required VT-d structures (root entry, context entry, page tables)
> + * 2. Programs IOMMU registers
> + * 3. Invalidates caches
> + * 4. Enables translation
> + */
> +uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_build_translation - Build Intel IOMMU translation structures
> + *
> + * @qts: QTest state handle
> + * @mode: Translation mode (pass-through or translated)
> + * @sid: Source ID (bus:devfn)
> + * @domain_id: Domain ID
> + * @iova: IOVA address for logging purposes
> + * @pa: Physical address backed by the mapping
> + *
> + * Returns: Build status (0 = success, non-zero = error)
> + *
> + * Constructs all necessary VT-d translation structures in guest memory:
> + * - Root Entry for the device's bus
> + * - Context Entry for the device
> + * - Complete 4-level page table hierarchy (if translated mode)
> + */
> +uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
> +                                uint16_t sid, uint16_t domain_id,
> +                                uint64_t iova, uint64_t pa);
> +
> +/*
> + * qvtd_program_regs - Program Intel IOMMU registers
> + *
> + * @qts: QTest state handle
> + * @iommu_base: IOMMU base address
> + *
> + * Programs IOMMU registers with the following sequence:
> + * 1. Disable translation
> + * 2. Program root table address
> + * 3. Set root table pointer
> + * 4. Unmask fault event interrupt
> + *
> + * Note: This function does NOT clear memory regions or enable translation.
> + * Memory clearing should be done once during test setup via qvtd_clear_memory_regions().
> + * Translation is enabled separately after building all structures.
> + */
> +void qvtd_program_regs(QTestState *qts, uint64_t iommu_base);
> +
> +/*
> + * qvtd_trigger_dma - Trigger DMA operation via iommu-testdev
> + *
> + * @ctx: Test context
> + *
> + * Returns: DMA result code
> + *
> + * Programs iommu-testdev BAR0 registers to trigger a DMA operation:
> + * 1. Write IOVA address (GVA_LO/HI)
> + * 2. Write DMA length
> + * 3. Arm DMA (write to DBELL)
> + * 4. Trigger DMA (read from TRIGGERING)
> + * 5. Poll for completion (read DMA_RESULT)
> + */
> +uint32_t qvtd_trigger_dma(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_cleanup_translation - Clean up translation configuration
> + *
> + * @ctx: Test context containing configuration and device handles
> + *
> + * Clears all translation structures and invalidates IOMMU caches.
> + */
> +void qvtd_cleanup_translation(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_validate_test_result - Validate actual vs expected test result
> + *
> + * @ctx: Test context containing actual and expected results
> + *
> + * Returns: true if test passed (actual == expected), false otherwise
> + *
> + * Compares the actual DMA result with the expected result and logs
> + * the comparison for debugging purposes.
> + */
> +bool qvtd_validate_test_result(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_setup_translation_tables - Setup complete VT-d page table hierarchy
> + *
> + * @qts: QTest state handle
> + * @iova: Input Virtual Address to translate
> + * @pa: Physical address to map to
> + * @mode: Translation mode
> + *
> + * This function builds the complete 4-level page table structure for translating
> + * the given IOVA to PA through Intel VT-d. The structure is:
> + * - PML4 (Level 4): IOVA bits [47:39]
> + * - PDPT (Level 3): IOVA bits [38:30]
> + * - PD (Level 2): IOVA bits [29:21]
> + * - PT (Level 1): IOVA bits [20:12]
> + * - Page offset: IOVA bits [11:0]
> + *
> + * The function writes all necessary Page Table Entries (PTEs) to guest
> + * memory using qtest_writeq(), setting up the complete translation path
> + * that the VT-d hardware will traverse during DMA operations.
> + */
> +void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
> +                                   uint64_t pa, QVTDTransMode mode);
> +
> +/*
> + * qvtd_expected_dma_result - Calculate expected DMA result
> + *
> + * @ctx: Test context containing configuration
> + *
> + * Returns: Expected DMA result code
> + *
> + * This function acts as a test oracle, calculating the expected DMA result
> + * based on the test configuration. It centralizes validation logic for
> + * different scenarios (pass-through vs. translated, fault conditions).
> + */
> +uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_build_dma_attrs - Build DMA attributes for an Intel VT-d DMA request
> + *
> + * @bdf: PCI requester ID encoded as Bus[15:8]/Device[7:3]/Function[2:0]
> + * @pasid: PASID tag (0 for legacy requests, non-zero for scalable mode)
> + *
> + * Returns: Value to program into iommu-testdev's DMA_ATTRS register
> + *
> + * The iommu-testdev attribute register mirrors Intel VT-d request metadata:
> + *   - bits[2:0] keep the generic iommu-testdev fields (secure + space)
> + *   - bit[4] selects legacy (0) vs. scalable (1) transactions
> + *   - bits[23:8] carry the requester ID as defined in the VT-d spec
> + *   - bits[31:24] carry the PASID (limited to 8 bits in QEMU, matching
> + *     the MemTxAttrs::pid width and ECAP.PSS advertisement)
> + *
> + * The helper validates the BDF layout (bus <= 255, device <= 31, function <= 7)
> + * and makes sure PASID fits in the supported width before returning the value.
> + */
> +uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid);
> +
> +/*
> + * High-level test execution functions
> + */
> +
> +/*
> + * qvtd_single_translation - Execute single translation test
> + *
> + * @ctx: Test context
> + *
> + * Performs a complete test cycle:
> + * 1. Setup translation structures
> + * 2. Trigger DMA operation
> + * 3. Validate results
> + * 4. Cleanup
> + */
> +void qvtd_single_translation(QVTDTestContext *ctx);
> +
> +/*
> + * qvtd_run_translation_case - Execute a single Intel VT-d translation test
> + *
> + * @qts: QTestState for the test
> + * @dev: PCI device (iommu-testdev)
> + * @bar: BAR0 of iommu-testdev
> + * @iommu_base: Base address of Intel IOMMU MMIO registers
> + * @cfg: Test configuration
> + *
> + * High-level wrapper that creates test context internally and executes
> + * a single translation test case. This provides a simpler API compared
> + * to qvtd_single_translation() which requires manual context initialization.
> + *
> + * This function is analogous to qriommu_run_translation_case() in the
> + * RISC-V IOMMU test framework, providing a consistent API across different
> + * IOMMU architectures.
> + *
> + * Example usage:
> + *   QVTDTestConfig cfg = {
> + *       .trans_mode = QVTD_TM_LEGACY_PT,
> + *       .domain_id = 1,
> + *       .dma_iova = 0x40100000,
> + *       .dma_pa = 0x40100000,
> + *       .dma_len = 4,
> + *   };
> + *   qvtd_run_translation_case(qts, dev, bar, iommu_base, &cfg);
> + */
> +void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
> +                               QPCIBar bar, uint64_t iommu_base,
> +                               const QVTDTestConfig *cfg);
> +
> +/*
> + * qvtd_translation_batch - Execute batch of translation tests
> + *
> + * @configs: Array of test configurations
> + * @count: Number of configurations
> + * @qts: QTest state handle
> + * @dev: PCI device handle
> + * @bar: PCI BAR for MMIO access
> + * @iommu_base: IOMMU base address
> + *
> + * Executes multiple translation tests in sequence, each with its own
> + * configuration. Useful for testing different translation modes and
> + * scenarios in a single test run.
> + *
> + * This function now uses qvtd_run_translation_case() internally to
> + * reduce code duplication.
> + */
> +void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
> +                            QTestState *qts, QPCIDevice *dev,
> +                            QPCIBar bar, uint64_t iommu_base);
> +
> +#endif /* QTEST_LIBQOS_INTEL_IOMMU_H */
> -- 
> 2.39.5
>

Re: [PATCH RFC v1 1/2] tests/qtest/libqos: Add Intel IOMMU helper library

Posted by Fengyuan 1 day, 20 hours ago

Hi Chao,

Thanks for the review!

On 2/4/2026 3:31 PM, Chao Liu wrote:
> Hi Fengyuan,
> 
> Thanks for working on Intel IOMMU bare-metal testing support. I have some
> comments below.
> 
> On Wed, Feb 04, 2026 at 11:06:19AM +0800, Fengyuan Yu wrote:
>> Introduce a libqos helper module for Intel IOMMU (VT-d) testing with
>> iommu-testdev. The helper provides routines to:
>>
>> - Build Root Entry Tables, Context Entry Tables, and 4-level page tables
>>    for 48-bit address translation
>> - Program VT-d registers (Root Table Pointer, Global Command Register)
>>    following the Intel VT-d specification
>> - Execute DMA translations and verify results
>>
>> The current implementation supports Legacy mode with both pass-through and
>> translated (4-level paging) modes. Support for Scalable mode (PASID-based)
>> can be added in future patches.
>>
> The commit message looks good.
> 
>> Signed-off-by: Fengyuan Yu <15fengyuan@gmail.com>
>>
>> ---
>>   MAINTAINERS                          |   1 +
>>   tests/qtest/libqos/meson.build       |   3 +
>>   tests/qtest/libqos/qos-intel-iommu.c | 566 +++++++++++++++++++++++++++
>>   tests/qtest/libqos/qos-intel-iommu.h | 299 ++++++++++++++
>>   4 files changed, 869 insertions(+)
>>   create mode 100644 tests/qtest/libqos/qos-intel-iommu.c
>>   create mode 100644 tests/qtest/libqos/qos-intel-iommu.h
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 9b7ed4fccb..1cd2a4f474 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -3585,6 +3585,7 @@ M: Tao Tang <tangtao1634@phytium.com.cn>
>>   S: Maintained
>>   F: tests/qtest/libqos/qos-iommu*
>>   F: tests/qtest/libqos/qos-smmuv3*
>> +F: tests/qtest/libqos/qos-intel-iommu*
>>   
>>   Device Fuzzing
>>   M: Alexander Bulekov <alxndr@bu.edu>
>> diff --git a/tests/qtest/libqos/meson.build b/tests/qtest/libqos/meson.build
>> index 8d6758ec2b..7f7c4f9c6f 100644
>> --- a/tests/qtest/libqos/meson.build
>> +++ b/tests/qtest/libqos/meson.build
>> @@ -72,6 +72,9 @@ endif
>>   if config_all_devices.has_key('CONFIG_RISCV_IOMMU')
>>     libqos_srcs += files('riscv-iommu.c')
>>   endif
>> +if config_all_devices.has_key('CONFIG_VTD')
>> +  libqos_srcs += files('qos-intel-iommu.c')
>> +endif
>>   if config_all_devices.has_key('CONFIG_TPCI200')
>>     libqos_srcs += files('tpci200.c')
>>   endif
>> diff --git a/tests/qtest/libqos/qos-intel-iommu.c b/tests/qtest/libqos/qos-intel-iommu.c
>> new file mode 100644
>> index 0000000000..d6a733de7e
>> --- /dev/null
>> +++ b/tests/qtest/libqos/qos-intel-iommu.c
>> @@ -0,0 +1,566 @@
>> +/*
>> + * QOS Intel IOMMU (VT-d) Module Implementation
>> + *
>> + * This module provides Intel IOMMU-specific helper functions for libqos tests.
>> + *
>> + * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
>> + *
>> + * SPDX-License-Identifier: GPL-2.0-or-later
>> + */
>> +
>> +#include "qemu/osdep.h"
>> +#include "../libqtest.h"
>> +#include "pci.h"
>> +#include "qos-intel-iommu.h"
>> +
> You should also include "qos-iommu-testdev.h" here, as the SMMUv3 helper
> does. This would allow reusing the common DMA trigger infrastructure.
> 
Thanks for the review. After developing based on an earlier version of 
iommu-testdev, I had overlooked its interface updates. I have now pulled the 
latest changes and adapted the unified interface for Intel IOMMU functionality. 
I will include this update in v2.

>> +#define QVTD_POLL_DELAY_US        1000
>> +#define QVTD_POLL_MAX_RETRIES     1000
>> +#define QVTD_AW_48BIT_ENCODING    2
>> +
>> +/*
>> + * iommu-testdev DMA attribute layout for Intel VT-d traffic.
>> + *
>> + * Bits [2:0] keep using the generic iommu-testdev encoding
>> + * (secure + ArmSecuritySpace). Bits [23:8] carry the PCI Requester ID in the
>> + * format defined in the Intel VT-d spec (Figure 3-2 in
>> + * spec/Intel-iommu-spec.txt), and bits [31:24] contain the PASID that tags
>> + * scalable-mode transactions. Bit 4 distinguishes between pure legacy RID
>> + * requests and scalable-mode PASID-tagged requests. The PASID field is
>> + * limited to 8 bits because MemTxAttrs::pid only carries 8 bits today (see
>> + * include/exec/memattrs.h and the VTD_ECAP_PSS limit in
>> + * hw/i386/intel_iommu_internal.h).
>> + */
>> +#define QVTD_DMA_ATTR_MODE_SHIFT      4
>> +#define QVTD_DMA_ATTR_MODE_MASK       0x1
>> +#define QVTD_DMA_ATTR_MODE_LEGACY     0
>> +#define QVTD_DMA_ATTR_MODE_SCALABLE   1
>> +#define QVTD_DMA_ATTR_RID_SHIFT       8
>> +#define QVTD_DMA_ATTR_RID_MASK        0xffffu
>> +#define QVTD_DMA_ATTR_PASID_BITS      8
>> +#define QVTD_DMA_ATTR_PASID_SHIFT     24
>> +#define QVTD_DMA_ATTR_PASID_MASK      ((1u << QVTD_DMA_ATTR_PASID_BITS) - 1)
>> +
>> +#define QVTD_PCI_FUNCS_PER_DEVICE     8
>> +#define QVTD_PCI_DEVS_PER_BUS         32
>> +
>> +static void qvtd_wait_for_bitsl(QTestState *qts, uint64_t addr,
>> +                                uint32_t mask, bool expect_set)
>> +{
>> +    uint32_t val = 0;
>> +
>> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
>> +        val = qtest_readl(qts, addr);
>> +        if (!!(val & mask) == expect_set) {
>> +            return;
>> +        }
>> +        g_usleep(QVTD_POLL_DELAY_US);
>> +    }
>> +
>> +    g_error("Timeout waiting for bits 0x%x (%s) at 0x%llx, last=0x%x",
> Please use PRIx64 instead of %llx with (unsigned long long) cast.
> This applies to all similar occurrences in this file.
> 
Thanks for the review. I'ill fix this in v2.

>> +            mask, expect_set ? "set" : "clear",
>> +            (unsigned long long)addr, val);
>> +}
>> +
>> +static void qvtd_wait_for_bitsq(QTestState *qts, uint64_t addr,
>> +                                uint64_t mask, bool expect_set)
>> +{
>> +    uint64_t val = 0;
>> +
>> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
>> +        val = qtest_readq(qts, addr);
>> +        if (!!(val & mask) == expect_set) {
>> +            return;
>> +        }
>> +        g_usleep(QVTD_POLL_DELAY_US);
>> +    }
>> +
>> +    g_error("Timeout waiting for bits 0x%llx (%s) at 0x%llx, last=0x%llx",
>> +            (unsigned long long)mask, expect_set ? "set" : "clear",
>> +            (unsigned long long)addr, (unsigned long long)val);
>> +}
>> +
>> +static uint16_t qvtd_calc_sid(const QPCIDevice *dev)
>> +{
>> +    uint16_t devfn = dev->devfn & 0xff;
>> +    uint16_t bus = (dev->devfn >> 8) & 0xff;
>> +    uint8_t device = (devfn >> 3) & 0x1f;
>> +    uint8_t function = devfn & 0x7;
>> +
>> +    /* Validate BDF components. */
>> +    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
>> +        g_error("Invalid BDF: bus=%u device=%u function=%u", bus, device, function);
>> +    }
>> +
>> +    return (bus << 8) | devfn;
>> +}
>> +
>> +static bool qvtd_validate_dma_memory(QVTDTestContext *ctx)
>> +{
>> +    uint32_t len = ctx->config.dma_len;
>> +    g_autofree uint8_t *buf = NULL;
>> +
>> +    if (!len) {
>> +        return true;
>> +    }
>> +
>> +    buf = g_malloc(len);
>> +    qtest_memread(ctx->qts, ctx->config.dma_pa, buf, len);
>> +
>> +    for (uint32_t i = 0; i < len; i++) {
>> +        uint8_t expected = (ITD_DMA_WRITE_VAL >> ((i % 4) * 8)) & 0xff;
>> +        if (buf[i] != expected) {
>> +            g_test_message("Memory mismatch at PA=0x%llx offset=%u "
>> +                           "expected=0x%02x actual=0x%02x",
>> +                           (unsigned long long)ctx->config.dma_pa, i,
>> +                           expected, buf[i]);
>> +            return false;
>> +        }
>> +    }
>> +
>> +    return true;
>> +}
>> +
>> +uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx)
>> +{
>> +    return ctx->config.expected_result;
>> +}
>> +
>> +uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid)
>> +{
>> +    uint32_t attrs = 0;
>> +    uint8_t bus = (bdf >> 8) & 0xff;
>> +    uint8_t devfn = bdf & 0xff;
>> +    uint8_t device = devfn >> 3;
>> +    uint8_t function = devfn & 0x7;
>> +    bool scalable_mode = pasid != 0;
>> +
>> +    if (device >= QVTD_PCI_DEVS_PER_BUS || function >= QVTD_PCI_FUNCS_PER_DEVICE) {
>> +        g_error("Invalid requester-id 0x%04x (bus=%u device=%u function=%u)",
>> +                bdf, bus, device, function);
>> +    }
>> +
>> +    attrs = ITD_ATTRS_SET_SECURE(attrs, 0);
>> +    attrs = ITD_ATTRS_SET_SPACE(attrs, 0);
>> +    attrs |= ((uint32_t)bdf & QVTD_DMA_ATTR_RID_MASK) << QVTD_DMA_ATTR_RID_SHIFT;
>> +
>> +    if (scalable_mode) {
>> +        if (pasid > QVTD_DMA_ATTR_PASID_MASK) {
>> +            g_error("PASID 0x%x exceeds %u-bit limit imposed by MemTxAttrs",
>> +                    pasid, QVTD_DMA_ATTR_PASID_BITS);
>> +        }
>> +
>> +        attrs |= (QVTD_DMA_ATTR_MODE_SCALABLE << QVTD_DMA_ATTR_MODE_SHIFT);
>> +        attrs |= ((pasid & QVTD_DMA_ATTR_PASID_MASK) << QVTD_DMA_ATTR_PASID_SHIFT);
>> +    } else {
>> +        attrs |= (QVTD_DMA_ATTR_MODE_LEGACY << QVTD_DMA_ATTR_MODE_SHIFT);
>> +    }
>> +
>> +    return attrs;
>> +}
>> +
>> +static void qvtd_build_root_entry(QTestState *qts, uint8_t bus,
>> +                                  uint64_t context_table_ptr)
>> +{
>> +    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
>> +    uint64_t lo, hi;
>> +
>> +    /* Root Entry Low: Context Table Pointer + Present bit (VT-d spec Section 9.1). */
>> +    lo = (context_table_ptr & VTD_CONTEXT_ENTRY_SLPTPTR) | VTD_CONTEXT_ENTRY_P;
>> +    hi = 0;  /* Reserved. */
>> +
>> +    qtest_writeq(qts, root_entry_addr, lo);
>> +    qtest_writeq(qts, root_entry_addr + 8, hi);
>> +}
>> +
>> +static void qvtd_build_context_entry(QTestState *qts, uint16_t sid,
>> +                                     QVTDTransMode mode, uint16_t domain_id,
>> +                                     uint64_t slptptr)
>> +{
>> +    uint8_t devfn = sid & 0xff;
>> +    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
>> +    uint64_t lo, hi;
>> +
>> +    if (mode == QVTD_TM_LEGACY_PT) {
>> +        /* Pass-through mode (VT-d spec Section 3.9, Section 9.3). */
>> +        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_PASS_THROUGH;
>> +        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
>> +    } else {
>> +        /* Translated mode: 4-level paging (AW=2 for 48-bit, VT-d spec Section 9.3). */
>> +        lo = VTD_CONTEXT_ENTRY_P | VTD_CONTEXT_TT_MULTI_LEVEL |
>> +             (slptptr & VTD_CONTEXT_ENTRY_SLPTPTR);
>> +        hi = ((uint64_t)domain_id << 8) | QVTD_AW_48BIT_ENCODING;
>> +    }
>> +
>> +    qtest_writeq(qts, context_entry_addr, lo);
>> +    qtest_writeq(qts, context_entry_addr + 8, hi);
>> +}
>> +
>> +void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
>> +                                   uint64_t pa, QVTDTransMode mode)
>> +{
>> +    uint64_t pml4_entry, pdpt_entry, pd_entry, pt_entry;
>> +    uint64_t pml4_addr, pdpt_addr, pd_addr, pt_addr;
>> +    uint32_t pml4_idx, pdpt_idx, pd_idx, pt_idx;
>> +    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
>> +                           "Pass-Through" : "Translated";
>> +
>> +    g_test_message("Begin of page table construction: IOVA=0x%llx PA=0x%llx mode=%s",
>> +                   (unsigned long long)iova, (unsigned long long)pa, mode_str);
>> +
>> +    /* Pass-through mode doesn't need page tables */
>> +    if (mode == QVTD_TM_LEGACY_PT) {
>> +        g_test_message("Pass-through mode: skipping page table setup");
>> +        return;
>> +    }
>> +
>> +    /* Extract indices from IOVA
>> +     * 4-level paging for 48-bit virtual address space:
>> +     * - PML4 index: bits [47:39] (9 bits = 512 entries)
>> +     * - PDPT index:  bits [38:30] (9 bits = 512 entries)
>> +     * - PD index:    bits [29:21] (9 bits = 512 entries)
>> +     * - PT index:    bits [20:12] (9 bits = 512 entries)
>> +     * - Page offset: bits [11:0]  (12 bits = 4KB pages)
>> +     */
>> +    pml4_idx = (iova >> 39) & 0x1ff;  /* Bits [47:39] */
>> +    pdpt_idx = (iova >> 30) & 0x1ff;  /* Bits [38:30] */
>> +    pd_idx = (iova >> 21) & 0x1ff;    /* Bits [29:21] */
>> +    pt_idx = (iova >> 12) & 0x1ff;    /* Bits [20:12] */
>> +
>> +    /*
>> +     * Build 4-level page table hierarchy (VT-d spec Section 9.3, Table 9-3).
>> +     * Non-leaf entries: both R+W set for full access (spec allows R or W individually).
>> +     * Per VT-d spec Section 9.8: "If either the R or W field of a non-leaf
>> +     * paging-structure entry is 1", indicating that setting one or both is valid.
>> +     * We set both R+W for non-leaf entries as standard practice.
>> +     */
>> +
>> +    /* PML4 Entry: points to PDPT. */
>> +    pml4_addr = QVTD_PT_L4_BASE + (pml4_idx * 8);
>> +    pml4_entry = QVTD_PT_L3_BASE | VTD_SL_R | VTD_SL_W;
>> +    qtest_writeq(qts, pml4_addr, pml4_entry);
>> +
>> +    /* PDPT Entry: points to PD. */
>> +    pdpt_addr = QVTD_PT_L3_BASE + (pdpt_idx * 8);
>> +    pdpt_entry = QVTD_PT_L2_BASE | VTD_SL_R | VTD_SL_W;
>> +    qtest_writeq(qts, pdpt_addr, pdpt_entry);
>> +
>> +    /* PD Entry: points to PT. */
>> +    pd_addr = QVTD_PT_L2_BASE + (pd_idx * 8);
>> +    pd_entry = QVTD_PT_L1_BASE | VTD_SL_R | VTD_SL_W;
>> +    qtest_writeq(qts, pd_addr, pd_entry);
>> +
>> +    /* PT Entry: points to physical page (leaf). */
>> +    pt_addr = QVTD_PT_L1_BASE + (pt_idx * 8);
>> +    pt_entry = (pa & VTD_PAGE_MASK_4K) | VTD_SL_R | VTD_SL_W;
>> +    qtest_writeq(qts, pt_addr, pt_entry);
>> +
>> +    g_test_message("End of page table construction: mapped IOVA=0x%llx -> PA=0x%llx",
>> +                   (unsigned long long)iova, (unsigned long long)pa);
>> +}
>> +
>> +static void qvtd_invalidate_context_cache(QTestState *qts,
>> +                                          uint64_t iommu_base)
>> +{
>> +    uint64_t ccmd_val;
>> +
>> +    /* Context Command Register: Global invalidation (VT-d spec Section 6.5.1.1). */
>> +    ccmd_val = VTD_CCMD_ICC | VTD_CCMD_GLOBAL_INVL;
>> +    qtest_writeq(qts, iommu_base + DMAR_CCMD_REG, ccmd_val);
>> +
>> +    /* Wait for ICC bit to clear. */
>> +    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_CCMD_REG,
>> +                        VTD_CCMD_ICC, false);
>> +}
>> +
>> +static void qvtd_invalidate_iotlb(QTestState *qts, uint64_t iommu_base)
>> +{
>> +    uint64_t iotlb_val;
>> +
>> +    /* IOTLB Invalidate Register: Global flush (VT-d spec Section 6.5.1.2). */
>> +    iotlb_val = VTD_TLB_IVT | VTD_TLB_GLOBAL_FLUSH;
>> +    qtest_writeq(qts, iommu_base + DMAR_IOTLB_REG, iotlb_val);
>> +
>> +    /* Wait for IVT bit to clear. */
>> +    qvtd_wait_for_bitsq(qts, iommu_base + DMAR_IOTLB_REG,
>> +                        VTD_TLB_IVT, false);
>> +}
>> +
>> +static void qvtd_clear_memory_regions(QTestState *qts)
>> +{
>> +    /* Clear root table. */
>> +    qtest_memset(qts, QVTD_ROOT_TABLE_BASE, 0, 4096);
>> +
>> +    /* Clear context table. */
>> +    qtest_memset(qts, QVTD_CONTEXT_TABLE_BASE, 0, 4096);
>> +
>> +    /* Clear all page table levels (4 levels * 4KB each = 16KB). */
>> +    qtest_memset(qts, QVTD_PT_L4_BASE, 0, 16384);
>> +}
>> +
>> +void qvtd_program_regs(QTestState *qts, uint64_t iommu_base)
>> +{
>> +    uint32_t gcmd;
>> +
>> +    /* 1. Disable translation (VT-d spec Section 11.4.4). */
>> +    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
>> +    gcmd &= ~VTD_GCMD_TE;
>> +    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
>> +
>> +    /* Wait for TES to clear. */
>> +    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
>> +                        VTD_GSTS_TES, false);
>> +
>> +    /* 2. Program root table address (VT-d spec Section 11.4.5). */
>> +    qtest_writeq(qts, iommu_base + DMAR_RTADDR_REG, QVTD_ROOT_TABLE_BASE);
>> +
>> +    /* 3. Set root table pointer (VT-d spec Section 6.6). */
>> +    gcmd = qtest_readl(qts, iommu_base + DMAR_GCMD_REG);
>> +    gcmd |= VTD_GCMD_SRTP;
>> +    qtest_writel(qts, iommu_base + DMAR_GCMD_REG, gcmd);
>> +
>> +    /* Wait for RTPS. */
>> +    qvtd_wait_for_bitsl(qts, iommu_base + DMAR_GSTS_REG,
>> +                        VTD_GSTS_RTPS, true);
>> +
>> +    /* Invalidate context cache after setting root table pointer. */
>> +    qvtd_invalidate_context_cache(qts, iommu_base);
>> +
>> +    /* 4. Unmask fault event interrupt to avoid warning messages. */
>> +    qtest_writel(qts, iommu_base + DMAR_FECTL_REG, 0);
>> +
>> +    /* NOTE: Translation is NOT enabled here - caller must enable after building structures. */
>> +}
>> +
>> +uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
>> +                                uint16_t sid, uint16_t domain_id,
>> +                                uint64_t iova, uint64_t pa)
>> +{
>> +    uint8_t bus = (sid >> 8) & 0xff;
>> +    const char *mode_str = (mode == QVTD_TM_LEGACY_PT) ?
>> +                           "Pass-Through" : "Translated";
>> +
>> +    g_test_message("Begin of construction: IOVA=0x%llx PA=0x%llx "
>> +                   "mode=%s domain_id=%u ===",
>> +                   (unsigned long long)iova, (unsigned long long)pa,
>> +                   mode_str, domain_id);
>> +
>> +    /* Build root entry */
>> +    qvtd_build_root_entry(qts, bus, QVTD_CONTEXT_TABLE_BASE);
>> +
>> +    /* Build context entry */
>> +    if (mode == QVTD_TM_LEGACY_PT) {
>> +        /* Pass-through mode: no page tables needed */
>> +        qvtd_build_context_entry(qts, sid, mode, domain_id, 0);
>> +        g_test_message("End of construction: identity mapping to PA=0x%llx ===",
>> +                       (unsigned long long)pa);
>> +    } else {
>> +        /* Translated mode: build 4-level page tables */
>> +        qvtd_setup_translation_tables(qts, iova, pa, QVTD_TM_LEGACY_TRANS);
>> +        qvtd_build_context_entry(qts, sid, mode, domain_id, QVTD_PT_L4_BASE);
>> +        g_test_message("End of construction: mapped IOVA=0x%llx -> PA=0x%llx ===",
>> +                       (unsigned long long)iova, (unsigned long long)pa);
>> +    }
>> +
>> +    return 0;
>> +}
>> +
>> +uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx)
>> +{
>> +    uint32_t gcmd;
>> +
>> +    /* Clear memory regions once during setup */
>> +    qvtd_clear_memory_regions(ctx->qts);
>> +
>> +    /* Program IOMMU registers (sets up root table pointer) */
>> +    qvtd_program_regs(ctx->qts, ctx->iommu_base);
>> +
>> +    /* Build translation structures AFTER clearing memory */
>> +    ctx->trans_status = qvtd_build_translation(ctx->qts, ctx->config.trans_mode,
>> +                                               ctx->sid, ctx->config.domain_id,
>> +                                               ctx->config.dma_iova,
>> +                                               ctx->config.dma_pa);
>> +    if (ctx->trans_status != 0) {
>> +        return ctx->trans_status;
>> +    }
>> +
>> +    /* Invalidate caches using register-based invalidation */
>> +    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
>> +    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
>> +
>> +    /* Enable translation AFTER building structures and invalidating caches */
>> +    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
>> +    gcmd |= VTD_GCMD_TE;
>> +    qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
>> +
>> +    /* Wait for TES */
>> +    qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
>> +                        VTD_GSTS_TES, true);
>> +
>> +    return 0;
>> +}
>> +
>> +uint32_t qvtd_trigger_dma(QVTDTestContext *ctx)
> This function duplicates the logic in qos_iommu_testdev_trigger_dma().
> The SMMUv3 helper uses the common qos-iommu-testdev infrastructure with
> callback functions (setup_fn, attrs_fn, validate_fn, report_fn).
> 
> I'd suggest refactoring to use qos_iommu_testdev_single_translation()
> instead, similar to how qsmmu_run_translation_case() does it in
> qos-smmuv3.c
> 
> Thanks,
> Chao
Thank you. The root cause of this issue is the same as the first review.
I will port my functionality following the coding style of the latest 
iommu-testdev version in v2.

Thanks,
Fengyuan

>> +{
>> +    uint64_t iova = ctx->config.dma_iova;
>> +    uint32_t len = ctx->config.dma_len;
>> +    uint32_t result, attrs_val;
>> +    const char *mode_str = (ctx->config.trans_mode == QVTD_TM_LEGACY_PT) ?
>> +                           "Pass-Through" : "Translated";
>> +
>> +    /* Write IOVA low 32 bits */
>> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_LO, (uint32_t)iova);
>> +
>> +    /* Write IOVA high 32 bits */
>> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_GVA_HI, (uint32_t)(iova >> 32));
>> +
>> +    /* Write DMA length */
>> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_LEN, len);
>> +
>> +    /* Build and write DMA attributes with BDF (PASID=0 for Legacy mode) */
>> +    attrs_val = qvtd_build_dma_attrs(ctx->sid, 0);
>> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_ATTRS, attrs_val);
>> +
>> +    /* Arm DMA by writing 1 to doorbell */
>> +    qpci_io_writel(ctx->dev, ctx->bar, ITD_REG_DMA_DBELL, ITD_DMA_DBELL_ARM);
>> +
>> +    /* Trigger DMA by reading from triggering register */
>> +    qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_TRIGGERING);
>> +
>> +    /* Poll for completion */
>> +    ctx->dma_result = ITD_DMA_RESULT_BUSY;
>> +    for (int attempt = 0; attempt < QVTD_POLL_MAX_RETRIES; attempt++) {
>> +        result = qpci_io_readl(ctx->dev, ctx->bar, ITD_REG_DMA_RESULT);
>> +        if (result != ITD_DMA_RESULT_BUSY) {
>> +            ctx->dma_result = result;
>> +            break;
>> +        }
>> +        g_usleep(QVTD_POLL_DELAY_US);
>> +    }
>> +
>> +    if (ctx->dma_result == ITD_DMA_RESULT_BUSY) {
>> +        ctx->dma_result = ITD_DMA_ERR_TX_FAIL;
>> +        g_test_message("-> DMA timeout detected, forcing failure");
>> +    }
>> +
>> +    if (ctx->dma_result == 0) {
>> +        g_test_message("-> DMA succeeded: mode=%s", mode_str);
>> +    } else {
>> +        g_test_message("-> DMA failed: mode=%s result=0x%x",
>> +                       mode_str, ctx->dma_result);
>> +    }
>> +
>> +    return ctx->dma_result;
>> +}
>> +
>> +void qvtd_cleanup_translation(QVTDTestContext *ctx)
>> +{
>> +    uint8_t bus = (ctx->sid >> 8) & 0xff;
>> +    uint8_t devfn = ctx->sid & 0xff;
>> +    uint64_t root_entry_addr = QVTD_ROOT_TABLE_BASE + (bus * 16);
>> +    uint64_t context_entry_addr = QVTD_CONTEXT_TABLE_BASE + (devfn * 16);
>> +    uint32_t gcmd;
>> +
>> +    /* Disable translation before tearing down the structures */
>> +    gcmd = qtest_readl(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG);
>> +    if (gcmd & VTD_GCMD_TE) {
>> +        gcmd &= ~VTD_GCMD_TE;
>> +        qtest_writel(ctx->qts, ctx->iommu_base + DMAR_GCMD_REG, gcmd);
>> +        qvtd_wait_for_bitsl(ctx->qts, ctx->iommu_base + DMAR_GSTS_REG,
>> +                            VTD_GSTS_TES, false);
>> +    }
>> +
>> +    /* Clear context entry */
>> +    qtest_writeq(ctx->qts, context_entry_addr, 0);
>> +    qtest_writeq(ctx->qts, context_entry_addr + 8, 0);
>> +
>> +    /* Clear root entry */
>> +    qtest_writeq(ctx->qts, root_entry_addr, 0);
>> +    qtest_writeq(ctx->qts, root_entry_addr + 8, 0);
>> +
>> +    /* Invalidate caches using register-based invalidation */
>> +    qvtd_invalidate_context_cache(ctx->qts, ctx->iommu_base);
>> +    qvtd_invalidate_iotlb(ctx->qts, ctx->iommu_base);
>> +}
>> +
>> +bool qvtd_validate_test_result(QVTDTestContext *ctx)
>> +{
>> +    uint32_t expected = qvtd_expected_dma_result(ctx);
>> +    bool passed = (ctx->dma_result == expected);
>> +    bool mem_ok = true;
>> +
>> +    g_test_message("-> Validating result: expected=0x%x actual=0x%x",
>> +                   expected, ctx->dma_result);
>> +
>> +    if (passed && expected == 0) {
>> +        mem_ok = qvtd_validate_dma_memory(ctx);
>> +        g_test_message("-> Memory validation %s at PA=0x%llx",
>> +                       mem_ok ? "passed" : "failed",
>> +                       (unsigned long long)ctx->config.dma_pa);
>> +        passed = mem_ok;
>> +    }
>> +
>> +    return passed;
>> +}
>> +
>> +void qvtd_single_translation(QVTDTestContext *ctx)
>> +{
>> +    uint32_t config_result;
>> +    bool test_passed;
>> +
>> +    /* Configure Intel IOMMU translation */
>> +    config_result = qvtd_setup_and_enable_translation(ctx);
>> +    if (config_result != 0) {
>> +        g_test_message("Configuration failed: mode=%u status=0x%x",
>> +                       ctx->config.trans_mode, config_result);
>> +    }
>> +    g_assert_cmpint(config_result, ==, 0);
>> +
>> +    /* Trigger DMA operation */
>> +    qvtd_trigger_dma(ctx);
>> +
>> +    /* Validate test result */
>> +    test_passed = qvtd_validate_test_result(ctx);
>> +    g_assert_true(test_passed);
>> +
>> +    /* Clean up translation state to prepare for the next test */
>> +    qvtd_cleanup_translation(ctx);
>> +}
>> +
>> +void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
>> +                               QPCIBar bar, uint64_t iommu_base,
>> +                               const QVTDTestConfig *cfg)
>> +{
>> +    /* Initialize test memory */
>> +    qtest_memset(qts, cfg->dma_pa, 0x00, cfg->dma_len);
>> +
>> +    /* Create test context on stack */
>> +    QVTDTestContext ctx = {
>> +        .qts = qts,
>> +        .dev = dev,
>> +        .bar = bar,
>> +        .iommu_base = iommu_base,
>> +        .config = *cfg,
>> +        .trans_status = 0,
>> +        .dma_result = 0,
>> +        .sid = qvtd_calc_sid(dev),
>> +    };
>> +
>> +    /* Execute the test using existing single_translation logic */
>> +    qvtd_single_translation(&ctx);
>> +
>> +    /* Report results */
>> +    g_test_message("--> Test completed: mode=%u domain_id=%u "
>> +                   "status=0x%x result=0x%x",
>> +                   cfg->trans_mode, cfg->domain_id,
>> +                   ctx.trans_status, ctx.dma_result);
>> +}
>> +
>> +void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
>> +                            QTestState *qts, QPCIDevice *dev,
>> +                            QPCIBar bar, uint64_t iommu_base)
>> +{
>> +    for (size_t i = 0; i < count; i++) {
>> +        g_test_message("=== Running test %zu/%zu ===", i + 1, count);
>> +        qvtd_run_translation_case(qts, dev, bar, iommu_base, &configs[i]);
>> +    }
>> +}
>> diff --git a/tests/qtest/libqos/qos-intel-iommu.h b/tests/qtest/libqos/qos-intel-iommu.h
>> new file mode 100644
>> index 0000000000..dab5d4df63
>> --- /dev/null
>> +++ b/tests/qtest/libqos/qos-intel-iommu.h
>> @@ -0,0 +1,299 @@
>> +/*
>> + * QOS Intel IOMMU (VT-d) Module
>> + *
>> + * This module provides Intel IOMMU-specific helper functions for libqos tests,
>> + * encapsulating VT-d setup, assertion, and cleanup operations.
>> + *
>> + * Copyright (c) 2026 Fengyuan Yu <15fengyuan@gmail.com>
>> + *
>> + * SPDX-License-Identifier: GPL-2.0-or-later
>> + */
>> +
>> +#ifndef QTEST_LIBQOS_INTEL_IOMMU_H
>> +#define QTEST_LIBQOS_INTEL_IOMMU_H
>> +
>> +#include "hw/misc/iommu-testdev.h"
>> +#include "hw/i386/intel_iommu_internal.h"
>> +
>> +/*
>> + * Intel IOMMU MMIO register base. This is the standard Q35 IOMMU address.
>> + */
>> +#define Q35_IOMMU_BASE            0xfed90000ULL
>> +
>> +/*
>> + * Guest memory layout for IOMMU structures.
>> + * All structures are placed in guest physical memory inside the 512MB RAM.
>> + * Using 256MB mark (0x10000000) as base to ensure all structures fit in RAM.
>> + */
>> +#define QVTD_MEM_BASE             0x10000000ULL
>> +
>> +/* Root Entry Table: 256 entries * 16 bytes = 4KB */
>> +#define QVTD_ROOT_TABLE_BASE      (QVTD_MEM_BASE + 0x00000000)
>> +
>> +/* Context Entry Table: 256 entries * 16 bytes = 4KB per bus */
>> +#define QVTD_CONTEXT_TABLE_BASE   (QVTD_MEM_BASE + 0x00001000)
>> +
>> +/* Page Tables: 4-level hierarchy for 48-bit address translation */
>> +#define QVTD_PT_L4_BASE           (QVTD_MEM_BASE + 0x00010000)  /* PML4 */
>> +#define QVTD_PT_L3_BASE           (QVTD_MEM_BASE + 0x00011000)  /* PDPT */
>> +#define QVTD_PT_L2_BASE           (QVTD_MEM_BASE + 0x00012000)  /* PD */
>> +#define QVTD_PT_L1_BASE           (QVTD_MEM_BASE + 0x00013000)  /* PT */
>> +
>> +/* Invalidation Queue: 256 entries * 16 bytes = 4KB */
>> +#define QVTD_INV_QUEUE_BASE       (QVTD_MEM_BASE + 0x00020000)
>> +
>> +/* Test IOVA and target physical address */
>> +#define QVTD_TEST_IOVA            0x0000008080604000ULL
>> +#define QVTD_TEST_PA              (QVTD_MEM_BASE + 0x00100000)
>> +
>> +/*
>> + * Translation modes supported by Intel IOMMU
>> + */
>> +typedef enum QVTDTransMode {
>> +    QVTD_TM_LEGACY_PT,      /* Legacy pass-through mode */
>> +    QVTD_TM_LEGACY_TRANS,   /* Legacy translated mode (4-level paging) */
>> +} QVTDTransMode;
>> +
>> +/*
>> + * Test configuration structure
>> + */
>> +typedef struct QVTDTestConfig {
>> +    QVTDTransMode trans_mode;     /* Translation mode */
>> +    uint64_t dma_iova;            /* DMA IOVA address for testing */
>> +    uint64_t dma_pa;              /* Target physical address */
>> +    uint32_t dma_len;             /* DMA length for testing */
>> +    uint32_t expected_result;     /* Expected DMA result */
>> +    uint16_t domain_id;           /* Domain ID for this test */
>> +} QVTDTestConfig;
>> +
>> +/*
>> + * Test context structure
>> + */
>> +typedef struct QVTDTestContext {
>> +    QTestState *qts;              /* QTest state handle */
>> +    QPCIDevice *dev;              /* PCI device handle */
>> +    QPCIBar bar;                  /* PCI BAR for MMIO access */
>> +    QVTDTestConfig config;        /* Test configuration */
>> +    uint64_t iommu_base;          /* Intel IOMMU base address */
>> +    uint32_t trans_status;        /* Translation configuration status */
>> +    uint32_t dma_result;          /* DMA operation result */
>> +    uint16_t sid;                 /* Source ID (bus:devfn) */
>> +} QVTDTestContext;
>> +
>> +/*
>> + * qvtd_setup_and_enable_translation - Complete translation setup and enable
>> + *
>> + * @ctx: Test context containing configuration and device handles
>> + *
>> + * Returns: Translation status (0 = success, non-zero = error)
>> + *
>> + * This function performs the complete translation setup sequence:
>> + * 1. Builds all required VT-d structures (root entry, context entry, page tables)
>> + * 2. Programs IOMMU registers
>> + * 3. Invalidates caches
>> + * 4. Enables translation
>> + */
>> +uint32_t qvtd_setup_and_enable_translation(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_build_translation - Build Intel IOMMU translation structures
>> + *
>> + * @qts: QTest state handle
>> + * @mode: Translation mode (pass-through or translated)
>> + * @sid: Source ID (bus:devfn)
>> + * @domain_id: Domain ID
>> + * @iova: IOVA address for logging purposes
>> + * @pa: Physical address backed by the mapping
>> + *
>> + * Returns: Build status (0 = success, non-zero = error)
>> + *
>> + * Constructs all necessary VT-d translation structures in guest memory:
>> + * - Root Entry for the device's bus
>> + * - Context Entry for the device
>> + * - Complete 4-level page table hierarchy (if translated mode)
>> + */
>> +uint32_t qvtd_build_translation(QTestState *qts, QVTDTransMode mode,
>> +                                uint16_t sid, uint16_t domain_id,
>> +                                uint64_t iova, uint64_t pa);
>> +
>> +/*
>> + * qvtd_program_regs - Program Intel IOMMU registers
>> + *
>> + * @qts: QTest state handle
>> + * @iommu_base: IOMMU base address
>> + *
>> + * Programs IOMMU registers with the following sequence:
>> + * 1. Disable translation
>> + * 2. Program root table address
>> + * 3. Set root table pointer
>> + * 4. Unmask fault event interrupt
>> + *
>> + * Note: This function does NOT clear memory regions or enable translation.
>> + * Memory clearing should be done once during test setup via qvtd_clear_memory_regions().
>> + * Translation is enabled separately after building all structures.
>> + */
>> +void qvtd_program_regs(QTestState *qts, uint64_t iommu_base);
>> +
>> +/*
>> + * qvtd_trigger_dma - Trigger DMA operation via iommu-testdev
>> + *
>> + * @ctx: Test context
>> + *
>> + * Returns: DMA result code
>> + *
>> + * Programs iommu-testdev BAR0 registers to trigger a DMA operation:
>> + * 1. Write IOVA address (GVA_LO/HI)
>> + * 2. Write DMA length
>> + * 3. Arm DMA (write to DBELL)
>> + * 4. Trigger DMA (read from TRIGGERING)
>> + * 5. Poll for completion (read DMA_RESULT)
>> + */
>> +uint32_t qvtd_trigger_dma(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_cleanup_translation - Clean up translation configuration
>> + *
>> + * @ctx: Test context containing configuration and device handles
>> + *
>> + * Clears all translation structures and invalidates IOMMU caches.
>> + */
>> +void qvtd_cleanup_translation(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_validate_test_result - Validate actual vs expected test result
>> + *
>> + * @ctx: Test context containing actual and expected results
>> + *
>> + * Returns: true if test passed (actual == expected), false otherwise
>> + *
>> + * Compares the actual DMA result with the expected result and logs
>> + * the comparison for debugging purposes.
>> + */
>> +bool qvtd_validate_test_result(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_setup_translation_tables - Setup complete VT-d page table hierarchy
>> + *
>> + * @qts: QTest state handle
>> + * @iova: Input Virtual Address to translate
>> + * @pa: Physical address to map to
>> + * @mode: Translation mode
>> + *
>> + * This function builds the complete 4-level page table structure for translating
>> + * the given IOVA to PA through Intel VT-d. The structure is:
>> + * - PML4 (Level 4): IOVA bits [47:39]
>> + * - PDPT (Level 3): IOVA bits [38:30]
>> + * - PD (Level 2): IOVA bits [29:21]
>> + * - PT (Level 1): IOVA bits [20:12]
>> + * - Page offset: IOVA bits [11:0]
>> + *
>> + * The function writes all necessary Page Table Entries (PTEs) to guest
>> + * memory using qtest_writeq(), setting up the complete translation path
>> + * that the VT-d hardware will traverse during DMA operations.
>> + */
>> +void qvtd_setup_translation_tables(QTestState *qts, uint64_t iova,
>> +                                   uint64_t pa, QVTDTransMode mode);
>> +
>> +/*
>> + * qvtd_expected_dma_result - Calculate expected DMA result
>> + *
>> + * @ctx: Test context containing configuration
>> + *
>> + * Returns: Expected DMA result code
>> + *
>> + * This function acts as a test oracle, calculating the expected DMA result
>> + * based on the test configuration. It centralizes validation logic for
>> + * different scenarios (pass-through vs. translated, fault conditions).
>> + */
>> +uint32_t qvtd_expected_dma_result(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_build_dma_attrs - Build DMA attributes for an Intel VT-d DMA request
>> + *
>> + * @bdf: PCI requester ID encoded as Bus[15:8]/Device[7:3]/Function[2:0]
>> + * @pasid: PASID tag (0 for legacy requests, non-zero for scalable mode)
>> + *
>> + * Returns: Value to program into iommu-testdev's DMA_ATTRS register
>> + *
>> + * The iommu-testdev attribute register mirrors Intel VT-d request metadata:
>> + *   - bits[2:0] keep the generic iommu-testdev fields (secure + space)
>> + *   - bit[4] selects legacy (0) vs. scalable (1) transactions
>> + *   - bits[23:8] carry the requester ID as defined in the VT-d spec
>> + *   - bits[31:24] carry the PASID (limited to 8 bits in QEMU, matching
>> + *     the MemTxAttrs::pid width and ECAP.PSS advertisement)
>> + *
>> + * The helper validates the BDF layout (bus <= 255, device <= 31, function <= 7)
>> + * and makes sure PASID fits in the supported width before returning the value.
>> + */
>> +uint32_t qvtd_build_dma_attrs(uint16_t bdf, uint32_t pasid);
>> +
>> +/*
>> + * High-level test execution functions
>> + */
>> +
>> +/*
>> + * qvtd_single_translation - Execute single translation test
>> + *
>> + * @ctx: Test context
>> + *
>> + * Performs a complete test cycle:
>> + * 1. Setup translation structures
>> + * 2. Trigger DMA operation
>> + * 3. Validate results
>> + * 4. Cleanup
>> + */
>> +void qvtd_single_translation(QVTDTestContext *ctx);
>> +
>> +/*
>> + * qvtd_run_translation_case - Execute a single Intel VT-d translation test
>> + *
>> + * @qts: QTestState for the test
>> + * @dev: PCI device (iommu-testdev)
>> + * @bar: BAR0 of iommu-testdev
>> + * @iommu_base: Base address of Intel IOMMU MMIO registers
>> + * @cfg: Test configuration
>> + *
>> + * High-level wrapper that creates test context internally and executes
>> + * a single translation test case. This provides a simpler API compared
>> + * to qvtd_single_translation() which requires manual context initialization.
>> + *
>> + * This function is analogous to qriommu_run_translation_case() in the
>> + * RISC-V IOMMU test framework, providing a consistent API across different
>> + * IOMMU architectures.
>> + *
>> + * Example usage:
>> + *   QVTDTestConfig cfg = {
>> + *       .trans_mode = QVTD_TM_LEGACY_PT,
>> + *       .domain_id = 1,
>> + *       .dma_iova = 0x40100000,
>> + *       .dma_pa = 0x40100000,
>> + *       .dma_len = 4,
>> + *   };
>> + *   qvtd_run_translation_case(qts, dev, bar, iommu_base, &cfg);
>> + */
>> +void qvtd_run_translation_case(QTestState *qts, QPCIDevice *dev,
>> +                               QPCIBar bar, uint64_t iommu_base,
>> +                               const QVTDTestConfig *cfg);
>> +
>> +/*
>> + * qvtd_translation_batch - Execute batch of translation tests
>> + *
>> + * @configs: Array of test configurations
>> + * @count: Number of configurations
>> + * @qts: QTest state handle
>> + * @dev: PCI device handle
>> + * @bar: PCI BAR for MMIO access
>> + * @iommu_base: IOMMU base address
>> + *
>> + * Executes multiple translation tests in sequence, each with its own
>> + * configuration. Useful for testing different translation modes and
>> + * scenarios in a single test run.
>> + *
>> + * This function now uses qvtd_run_translation_case() internally to
>> + * reduce code duplication.
>> + */
>> +void qvtd_translation_batch(const QVTDTestConfig *configs, size_t count,
>> +                            QTestState *qts, QPCIDevice *dev,
>> +                            QPCIBar bar, uint64_t iommu_base);
>> +
>> +#endif /* QTEST_LIBQOS_INTEL_IOMMU_H */
>> -- 
>> 2.39.5
>>

[PATCH RFC v1 1/2] tests/qtest/libqos: Add Intel IOMMU helper library
[PATCH RFC v1 2/2] tests/qtest: Add Intel IOMMU bare-metal test