Add a qtest for AMD IOMMU command buffer head pointer wraparound.
The test programs a command buffer, fills it with COMPLETION_WAIT commands,
advances the tail to consume all but the final entry, then wraps the tail
to zero to force the final command to advance CmdHeadPtr past the end of
the buffer. The guest-visible CmdHeadPtr register must then wrap back to zero.

This covers the case fixed by an earlier CmdHeadPtr wraparound patch.

The Linux kernel AMD IOMMU driver is not affected by this bug because it
uses COMPLETION_WAIT with a memory store doorbell to detect command progress.

Signed-off-by: Costas Argyris <costas.argyris@amd.com>
---
Changes since v1:
 - Drop the amd_iommu.c fix.
 - Reframe as a test-only patch.
 - Derive CMDBUF_ENTRIES from CMDBUF_LEN_FIELD.
 - Skip the test when the q35 machine is not built.

 MAINTAINERS                  |  1 +
 tests/qtest/amd-iommu-test.c | 76 ++++++++++++++++++++++++++++++++++++
 tests/qtest/meson.build      |  1 +
 3 files changed, 78 insertions(+)
 create mode 100644 tests/qtest/amd-iommu-test.c

diff --git a/MAINTAINERS b/MAINTAINERS
index 80d28e618d..750d415389 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4052,6 +4052,7 @@ M: Alejandro Jimenez <alejandro.j.jimenez@oracle.com>
 R: Sairaj Kodilkar <sarunkod@amd.com>
 S: Supported
 F: hw/i386/amd_iommu*
+F: tests/qtest/amd-iommu-test.c
 
 OpenSBI Firmware
 L: qemu-riscv@nongnu.org
diff --git a/tests/qtest/amd-iommu-test.c b/tests/qtest/amd-iommu-test.c
new file mode 100644
index 0000000000..fb28511588
--- /dev/null
+++ b/tests/qtest/amd-iommu-test.c
@@ -0,0 +1,76 @@
+/*
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ */
+
+#include "qemu/osdep.h"
+#include "libqtest.h"
+#include "hw/i386/amd_iommu.h"
+
+#define CMDBUF_ADDR       0x200000
+#define CMDBUF_LEN_FIELD  8
+#define CMDBUF_ENTRIES    (1U << CMDBUF_LEN_FIELD)
+
+static inline uint64_t amdvi_reg_readq(QTestState *s, uint64_t offset)
+{
+    return qtest_readq(s, AMDVI_BASE_ADDR + offset);
+}
+
+static inline void amdvi_reg_writeq(QTestState *s, uint64_t offset,
+                                    uint64_t val)
+{
+    qtest_writeq(s, AMDVI_BASE_ADDR + offset, val);
+}
+
+static void test_cmdbuf_head_wrap(void)
+{
+    QTestState *s;
+    uint64_t head;
+    int i;
+    /* 16 bytes per command */
+    struct {
+        uint64_t qw0;
+        uint64_t qw1;
+    } cmdbuf[CMDBUF_ENTRIES];
+
+    if (!qtest_has_machine("q35")) {
+        g_test_skip("q35 machine not available");
+        return;
+    }
+
+    s = qtest_init("-M q35 -device amd-iommu");
+
+    /* fill the command buffer with COMPLETION_WAIT (no-op) commands */
+    for (i = 0; i < CMDBUF_ENTRIES; i++) {
+        cmdbuf[i].qw0 = (uint64_t)AMDVI_CMD_COMPLETION_WAIT << 60;
+        cmdbuf[i].qw1 = 0;
+    }
+    qtest_memwrite(s, CMDBUF_ADDR, cmdbuf, sizeof(cmdbuf));
+
+    /* point the IOMMU at the command buffer and set its length */
+    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_BASE,
+                     CMDBUF_ADDR | ((uint64_t)CMDBUF_LEN_FIELD << 56));
+
+    /* enable the IOMMU and its command buffer processor */
+    amdvi_reg_writeq(s, AMDVI_MMIO_CONTROL,
+                     AMDVI_MMIO_CONTROL_AMDVIEN | AMDVI_MMIO_CONTROL_CMDBUFLEN);
+
+    /* advance tail to the last entry, consuming all but the final entry */
+    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_TAIL,
+                     (CMDBUF_ENTRIES - 1) * AMDVI_COMMAND_SIZE);
+
+    /* wrap tail to 0, consuming the final entry and completing the buffer */
+    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_TAIL, 0);
+
+    /* after consuming all entries the IOMMU must wrap CmdHeadPtr to 0 */
+    head = amdvi_reg_readq(s, AMDVI_MMIO_COMMAND_HEAD);
+    g_assert((head & AMDVI_MMIO_CMDBUF_HEAD_MASK) == 0);
+
+    qtest_quit(s);
+}
+
+int main(int argc, char **argv)
+{
+    g_test_init(&argc, &argv, NULL);
+    qtest_add_func("/q35/amd-iommu/cmdbuf-head-wrap", test_cmdbuf_head_wrap);
+    return g_test_run();
+}
diff --git a/tests/qtest/meson.build b/tests/qtest/meson.build
index 728dde54b3..67eea5c71a 100644
--- a/tests/qtest/meson.build
+++ b/tests/qtest/meson.build
@@ -95,6 +95,7 @@ qtests_i386 = \
   (config_all_devices.has_key('CONFIG_SB16') ? ['fuzz-sb16-test'] : []) +                   \
   (config_all_devices.has_key('CONFIG_SDHCI_PCI') ? ['fuzz-sdcard-test'] : []) +            \
   (config_all_devices.has_key('CONFIG_ESP_PCI') ? ['am53c974-test'] : []) +                 \
+  (config_all_devices.has_key('CONFIG_AMD_IOMMU') ? ['amd-iommu-test'] : []) +             \
   (config_all_devices.has_key('CONFIG_VTD') ? ['intel-iommu-test'] : []) +                 \
   (config_all_devices.has_key('CONFIG_VTD') and
    config_all_devices.has_key('CONFIG_IOMMU_TESTDEV') ? ['iommu-intel-test'] : []) +      \
-- 
2.43.0

On 5/30/26 2:34 PM, Costas Argyris wrote:
> Add a qtest for AMD IOMMU command buffer head pointer wraparound.
> The test programs a command buffer, fills it with COMPLETION_WAIT commands,
> advances the tail to consume all but the final entry, then wraps the tail
> to zero to force the final command to advance CmdHeadPtr past the end of
> the buffer. The guest-visible CmdHeadPtr register must then wrap back to zero.
> 
> This covers the case fixed by an earlier CmdHeadPtr wraparound patch.
> 
> The Linux kernel AMD IOMMU driver is not affected by this bug because it
> uses COMPLETION_WAIT with a memory store doorbell to detect command progress.
> 
> Signed-off-by: Costas Argyris <costas.argyris@amd.com>

Hi Costas,

Quick note on good practices: it is preferred that you send a v2 as a new
thread (with an optional link to v1) rather than in reply to the initial
thread. Not an issue in this instance since I am aware of what is
happening, but it could make it harder/confusing for other reviewers to see
the follow up if it is buried in the original thread.

I'm offline this week, but wanted to at least ACK your reply. Will review
again and apply to my tree once I am back (and it will also leave time for
others to review).

Thank you,
Alejandro

> ---
> Changes since v1:
>  - Drop the amd_iommu.c fix.
>  - Reframe as a test-only patch.
>  - Derive CMDBUF_ENTRIES from CMDBUF_LEN_FIELD.
>  - Skip the test when the q35 machine is not built.
> 
>  MAINTAINERS                  |  1 +
>  tests/qtest/amd-iommu-test.c | 76 ++++++++++++++++++++++++++++++++++++
>  tests/qtest/meson.build      |  1 +
>  3 files changed, 78 insertions(+)
>  create mode 100644 tests/qtest/amd-iommu-test.c
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 80d28e618d..750d415389 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -4052,6 +4052,7 @@ M: Alejandro Jimenez <alejandro.j.jimenez@oracle.com>
>  R: Sairaj Kodilkar <sarunkod@amd.com>
>  S: Supported
>  F: hw/i386/amd_iommu*
> +F: tests/qtest/amd-iommu-test.c
>  
>  OpenSBI Firmware
>  L: qemu-riscv@nongnu.org
> diff --git a/tests/qtest/amd-iommu-test.c b/tests/qtest/amd-iommu-test.c
> new file mode 100644
> index 0000000000..fb28511588
> --- /dev/null
> +++ b/tests/qtest/amd-iommu-test.c
> @@ -0,0 +1,76 @@
> +/*
> + * SPDX-License-Identifier: GPL-2.0-or-later
> + */
> +
> +#include "qemu/osdep.h"
> +#include "libqtest.h"
> +#include "hw/i386/amd_iommu.h"
> +
> +#define CMDBUF_ADDR       0x200000
> +#define CMDBUF_LEN_FIELD  8
> +#define CMDBUF_ENTRIES    (1U << CMDBUF_LEN_FIELD)
> +
> +static inline uint64_t amdvi_reg_readq(QTestState *s, uint64_t offset)
> +{
> +    return qtest_readq(s, AMDVI_BASE_ADDR + offset);
> +}
> +
> +static inline void amdvi_reg_writeq(QTestState *s, uint64_t offset,
> +                                    uint64_t val)
> +{
> +    qtest_writeq(s, AMDVI_BASE_ADDR + offset, val);
> +}
> +
> +static void test_cmdbuf_head_wrap(void)
> +{
> +    QTestState *s;
> +    uint64_t head;
> +    int i;
> +    /* 16 bytes per command */
> +    struct {
> +        uint64_t qw0;
> +        uint64_t qw1;
> +    } cmdbuf[CMDBUF_ENTRIES];
> +
> +    if (!qtest_has_machine("q35")) {
> +        g_test_skip("q35 machine not available");
> +        return;
> +    }
> +
> +    s = qtest_init("-M q35 -device amd-iommu");
> +
> +    /* fill the command buffer with COMPLETION_WAIT (no-op) commands */
> +    for (i = 0; i < CMDBUF_ENTRIES; i++) {
> +        cmdbuf[i].qw0 = (uint64_t)AMDVI_CMD_COMPLETION_WAIT << 60;
> +        cmdbuf[i].qw1 = 0;
> +    }
> +    qtest_memwrite(s, CMDBUF_ADDR, cmdbuf, sizeof(cmdbuf));
> +
> +    /* point the IOMMU at the command buffer and set its length */
> +    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_BASE,
> +                     CMDBUF_ADDR | ((uint64_t)CMDBUF_LEN_FIELD << 56));
> +
> +    /* enable the IOMMU and its command buffer processor */
> +    amdvi_reg_writeq(s, AMDVI_MMIO_CONTROL,
> +                     AMDVI_MMIO_CONTROL_AMDVIEN | AMDVI_MMIO_CONTROL_CMDBUFLEN);
> +
> +    /* advance tail to the last entry, consuming all but the final entry */
> +    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_TAIL,
> +                     (CMDBUF_ENTRIES - 1) * AMDVI_COMMAND_SIZE);
> +
> +    /* wrap tail to 0, consuming the final entry and completing the buffer */
> +    amdvi_reg_writeq(s, AMDVI_MMIO_COMMAND_TAIL, 0);
> +
> +    /* after consuming all entries the IOMMU must wrap CmdHeadPtr to 0 */
> +    head = amdvi_reg_readq(s, AMDVI_MMIO_COMMAND_HEAD);
> +    g_assert((head & AMDVI_MMIO_CMDBUF_HEAD_MASK) == 0);
> +
> +    qtest_quit(s);
> +}
> +
> +int main(int argc, char **argv)
> +{
> +    g_test_init(&argc, &argv, NULL);
> +    qtest_add_func("/q35/amd-iommu/cmdbuf-head-wrap", test_cmdbuf_head_wrap);
> +    return g_test_run();
> +}
> diff --git a/tests/qtest/meson.build b/tests/qtest/meson.build
> index 728dde54b3..67eea5c71a 100644
> --- a/tests/qtest/meson.build
> +++ b/tests/qtest/meson.build
> @@ -95,6 +95,7 @@ qtests_i386 = \
>    (config_all_devices.has_key('CONFIG_SB16') ? ['fuzz-sb16-test'] : []) +                   \
>    (config_all_devices.has_key('CONFIG_SDHCI_PCI') ? ['fuzz-sdcard-test'] : []) +            \
>    (config_all_devices.has_key('CONFIG_ESP_PCI') ? ['am53c974-test'] : []) +                 \
> +  (config_all_devices.has_key('CONFIG_AMD_IOMMU') ? ['amd-iommu-test'] : []) +             \
>    (config_all_devices.has_key('CONFIG_VTD') ? ['intel-iommu-test'] : []) +                 \
>    (config_all_devices.has_key('CONFIG_VTD') and
>     config_all_devices.has_key('CONFIG_IOMMU_TESTDEV') ? ['iommu-intel-test'] : []) +      \