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>
---
 docs/system/arm/virt.rst | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst
index 10cbffc8a7..2e0e8196be 100644
--- a/docs/system/arm/virt.rst
+++ b/docs/system/arm/virt.rst
@@ -37,7 +37,19 @@ 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
+
+  Allows instantiating multiple SMMUv3 devices, each associated with
+  a separate PCIe root complex. This is only allowed if the machine-wide
+  SMMUv3(``iommu=smmuv3``) is not used.
+
+  Example::
+
+      -device arm-smmuv3,primary-bus=pcie.0,id=smmuv3.0
+      ...
+      -device pxb-pcie,id=pcie.1
+      -device arm-smmuv3,primary-bus=pcie.1,id=smmuv3.1
 - hotpluggable DIMMs
 - hotpluggable NVDIMMs
 - An MSI controller (GICv2M or ITS). GICv2M is selected by default along
@@ -176,7 +188,8 @@ iommu
   ``none``
     Don't create an IOMMU (the default)
   ``smmuv3``
-    Create an SMMUv3
+    Create a machine-wide SMMUv3. Alternatively, SMMUv3 devices can be
+    instantiated directly using the ``-device`` option (see example above).
 
 default-bus-bypass-iommu
   Set ``on``/``off`` to enable/disable `bypass_iommu
-- 
2.43.0

On Mon, 6 Oct 2025 at 19:31, Shameer Kolothum <skolothumtho@nvidia.com> wrote:
>
> 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>
> ---
>  docs/system/arm/virt.rst | 17 +++++++++++++++--
>  1 file changed, 15 insertions(+), 2 deletions(-)
>
> diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst
> index 10cbffc8a7..2e0e8196be 100644
> --- a/docs/system/arm/virt.rst
> +++ b/docs/system/arm/virt.rst
> @@ -37,7 +37,19 @@ 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
> +
> +  Allows instantiating multiple SMMUv3 devices, each associated with
> +  a separate PCIe root complex. This is only allowed if the machine-wide
> +  SMMUv3(``iommu=smmuv3``) is not used.
> +
> +  Example::
> +
> +      -device arm-smmuv3,primary-bus=pcie.0,id=smmuv3.0
> +      ...
> +      -device pxb-pcie,id=pcie.1
> +      -device arm-smmuv3,primary-bus=pcie.1,id=smmuv3.1
>  - hotpluggable DIMMs
>  - hotpluggable NVDIMMs
>  - An MSI controller (GICv2M or ITS). GICv2M is selected by default along

This bulleted list is intended to be a summary list of the features the
virt board supports; if we put more detailed information and usage
examples in here then it gets a bit odd as the list is interrupted
by a multi-line detailed explanation of a single feature.

Instead I think we should have the list entry be a short one
that refers the user to elsewhere in the document for the
more detailed information, like:

 - User-creatable SMMUv3 devices (see below for example)

Then you can have a new subsection

SMMU configuration
""""""""""""""""""

(which I think I would put just above the "Linux guest
kernel configuration" subsection), which can describe
both the "machine-wide SMMU" and "multiple SMMU" options,
maybe say when you might pick one or the other, and have
your command line example there.

This gives us as much space as we like to document the SMMU
stuff, and a place in future where info about accelerated SMMUv3
will naturally sit.

thanks
-- PMM

On 10/6/25 2:29 PM, Shameer Kolothum wrote:
> 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>
> ---
>   docs/system/arm/virt.rst | 17 +++++++++++++++--
>   1 file changed, 15 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/system/arm/virt.rst b/docs/system/arm/virt.rst
> index 10cbffc8a7..2e0e8196be 100644
> --- a/docs/system/arm/virt.rst
> +++ b/docs/system/arm/virt.rst
> @@ -37,7 +37,19 @@ 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
I suggest a '(see example below)' at the end of the above line.

> +- User-creatable SMMUv3 devices
> +
> +  Allows instantiating multiple SMMUv3 devices, each associated with
> +  a separate PCIe root complex. This is only allowed if the machine-wide
> +  SMMUv3(``iommu=smmuv3``) is not used.
> +
> +  Example::
> +
> +      -device arm-smmuv3,primary-bus=pcie.0,id=smmuv3.0
> +      ...
> +      -device pxb-pcie,id=pcie.1
> +      -device arm-smmuv3,primary-bus=pcie.1,id=smmuv3.1
I like the detail; and wish it was done for many more of the -<option> above it,
e.g., PCIe, MSI, etc.

>   - hotpluggable DIMMs
>   - hotpluggable NVDIMMs
>   - An MSI controller (GICv2M or ITS). GICv2M is selected by default along
> @@ -176,7 +188,8 @@ iommu
>     ``none``
>       Don't create an IOMMU (the default)
>     ``smmuv3``
> -    Create an SMMUv3
> +    Create a machine-wide SMMUv3. Alternatively, SMMUv3 devices can be
s/Alternatively, SMMUv3/Alternatively, non-machine-wide SMMUv3/
Add:
'Note: user-creatable SMMUv3 devices cannot be instantiated if a machine-wide SMMUv3 is instantiated.'

Or should this section be moved up and after the updated 'optional machine-wide SMMUv3 IOMMU' above?
So all-things SMMUv3 are in the same doc area, and not split up as they are now, and not worsen over time as
more things (accelerated SMMUv3 documentation) is added


> +    instantiated directly using the ``-device`` option (see example above).
>   
>   default-bus-bypass-iommu
>     Set ``on``/``off`` to enable/disable `bypass_iommu

Thanks for the added documentation; more is better!
- Don