The virt machine now supports creating multiple SMMUv3 instances, each
associated with a separate PCIe root complex.
Update the documentation with an example.
Signed-off-by: Shameer Kolothum <skolothumtho@nvidia.com>
---
Addressed feedback from v1.(Thanks!).
https://lore.kernel.org/qemu-devel/20251006182900.100580-1-skolothumtho@nvidia.com/
---
docs/system/arm/virt.rst | 34 ++++++++++++++++++++++++++++++++--
1 file changed, 32 insertions(+), 2 deletions(-)
diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst
index 10cbffc8a7..339aa99ae1 100644
--- a/docs/system/arm/virt.rst
+++ b/docs/system/arm/virt.rst
@@ -37,7 +37,8 @@ The virt board supports:
- An RTC
- The fw_cfg device that allows a guest to obtain data from QEMU
- A PL061 GPIO controller
-- An optional SMMUv3 IOMMU
+- An optional machine-wide SMMUv3 IOMMU
+- User-creatable SMMUv3 devices (see below for example)
- hotpluggable DIMMs
- hotpluggable NVDIMMs
- An MSI controller (GICv2M or ITS). GICv2M is selected by default along
@@ -176,7 +177,7 @@ iommu
``none``
Don't create an IOMMU (the default)
``smmuv3``
- Create an SMMUv3
+ Create a machine-wide SMMUv3.
default-bus-bypass-iommu
Set ``on``/``off`` to enable/disable `bypass_iommu
@@ -219,6 +220,35 @@ x-oem-table-id
Set string (up to 8 bytes) to override the default value of field OEM Table ID
in ACPI table header.
+SMMU configuration
+""""""""""""""""""
+
+Machine-wide SMMUv3 IOMMU
+ See the machine-specific ``iommu`` option above. This allows specifying
+ a single, machine-wide SMMUv3 instance that applies to all devices in
+ the PCIe topology.
+
+ For information about selectively bypassing devices, refer to
+ ``docs/bypass-iommu.txt``.
+
+User-creatable SMMUv3 devices
+ Allows creating multiple user-defined SMMUv3 devices, each associated
+ with a separate PCIe root complex. This is only permitted if the
+ machine-wide SMMUv3 (``iommu=smmuv3``) option is not used.
+
+ This model is useful when you want to mirror a host configuration where
+ each NUMA node typically has its own SMMU, allowing the VM topology to
+ align more closely with the host’s hardware layout. Supporting multiple
+ SMMUv3 instances is also a prerequisite for future accelerated SMMUv3
+ support.
+
+ Example::
+
+ -device arm-smmuv3,primary-bus=pcie.0,id=smmuv3.0
+ ...
+ -device pxb-pcie,id=pcie.1,numa_node=1
+ -device arm-smmuv3,primary-bus=pcie.1,id=smmuv3.1
+
Linux guest kernel configuration
""""""""""""""""""""""""""""""""
--
2.43.0