From: Nathan Chen <nathanc@nvidia.com>

Document arm-smmuv3 properties for setting HW-acceleration,
Range Invalidation, and Address Translation Services support, as
well as setting Output Address size and Substream ID size.

Signed-off-by: Nathan Chen <nathanc@nvidia.com>
---
 qemu-options.hx | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 890c4f1d23..836de4532c 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1274,13 +1274,40 @@ SRST
     ``aw-bits=val`` (val between 32 and 64, default depends on machine)
         This decides the address width of the IOVA address space.
 
-``-device arm-smmuv3,primary-bus=id``
+``-device arm-smmuv3,primary-bus=id[,option=...]``
     This is only supported by ``-machine virt`` (ARM).
 
     ``primary-bus=id``
         Accepts either the default root complex (pcie.0) or a
         pxb-pcie based root complex.
 
+    ``accel=on|off`` (default: off)
+        Enables guest to try to leverage host SMMUv3 features for acceleration.
+        By default, enabling accel configures the host SMMUv3 in nested mode to
+        support vfio-pci pass-through.
+
+    ``ril=on|off`` (default: on)
+        Support for Range Invalidation, which allows the SMMUv3 driver to
+        invalidate TLB entries for a range of IOVAs at once instead of issuing
+        separate commands to invalidate each page. Must match with host SMMUv3
+        Range Invalidation support.
+
+    ``ats=on|off`` (default: off)
+        Support for Address Translation Services, which enables PCIe devices to
+        cache address translations in their local TLB and reduce latency. Host
+        SMMUv3 must support ATS in order to enable this feature for the vIOMMU.
+
+    ``oas=val`` (supported values are 44 and 48. default: 44)
+        Sets the Output Address Size in bits. The value set here must be less
+        than or equal to the host SMMUv3's supported OAS, so that the
+        intermediate physical addresses (IPA) consumed by host SMMU for stage-2
+        translation do not exceed the host's max supported IPA size.
+
+    ``ssidsize=val`` (val between 0 and 20. default: 0)
+        Sets the Substream ID size in bits. When set to a non-zero value,
+        PASID capability is advertised to the vIOMMU and accelerated use cases
+        such as Shared Virtual Addressing (SVA) are supported.
+
 ``-device amd-iommu[,option=...]``
     Enables emulation of an AMD-Vi I/O Memory Management Unit (IOMMU).
     Only available with ``-machine q35``, it supports the following options:
-- 
2.43.0

> -----Original Message-----
> From: Nathan Chen <nathanc@nvidia.com>
> Sent: 12 March 2026 21:03
> To: qemu-devel@nongnu.org; qemu-arm@nongnu.org
> Cc: Eric Auger <eric.auger@redhat.com>; Peter Maydell
> <peter.maydell@linaro.org>; Michael S . Tsirkin <mst@redhat.com>; Igor
> Mammedov <imammedo@redhat.com>; Ani Sinha <anisinha@redhat.com>;
> Shannon Zhao <shannon.zhaosl@gmail.com>; Paolo Bonzini
> <pbonzini@redhat.com>; Daniel P . Berrangé <berrange@redhat.com>;
> Eduardo Habkost <eduardo@habkost.net>; Eric Blake <eblake@redhat.com>;
> Markus Armbruster <armbru@redhat.com>; Shameer Kolothum Thodi
> <skolothumtho@nvidia.com>; Nicolin Chen <nicolinc@nvidia.com>; Matt
> Ochs <mochs@nvidia.com>; Nathan Chen <nathanc@nvidia.com>
> Subject: [PATCH v2 8/8] qemu-options.hx: Document arm-smmuv3 device's
> accel properties
> 
> From: Nathan Chen <nathanc@nvidia.com>
> 
> Document arm-smmuv3 properties for setting HW-acceleration,
> Range Invalidation, and Address Translation Services support, as
> well as setting Output Address size and Substream ID size.
> 
> Signed-off-by: Nathan Chen <nathanc@nvidia.com>
> ---
>  qemu-options.hx | 29 ++++++++++++++++++++++++++++-
>  1 file changed, 28 insertions(+), 1 deletion(-)
> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 890c4f1d23..836de4532c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1274,13 +1274,40 @@ SRST
>      ``aw-bits=val`` (val between 32 and 64, default depends on machine)
>          This decides the address width of the IOVA address space.
> 
> -``-device arm-smmuv3,primary-bus=id``
> +``-device arm-smmuv3,primary-bus=id[,option=...]``
>      This is only supported by ``-machine virt`` (ARM).
> 
>      ``primary-bus=id``
>          Accepts either the default root complex (pcie.0) or a
>          pxb-pcie based root complex.
> 
> +    ``accel=on|off`` (default: off)
> +        Enables guest to try to leverage host SMMUv3 features for acceleration.
> +        By default, enabling accel configures the host SMMUv3 in nested mode
> to
> +        support vfio-pci pass-through.

It might be worth mentioning that the properties below are only
applicable when accel=on.

Also, should we explicitly mention that "auto" is currently not
supported?

Thanks,
Shameer

> +
> +    ``ril=on|off`` (default: on)
> +        Support for Range Invalidation, which allows the SMMUv3 driver to
> +        invalidate TLB entries for a range of IOVAs at once instead of issuing
> +        separate commands to invalidate each page. Must match with host
> SMMUv3
> +        Range Invalidation support.
> +
> +    ``ats=on|off`` (default: off)
> +        Support for Address Translation Services, which enables PCIe devices to
> +        cache address translations in their local TLB and reduce latency. Host
> +        SMMUv3 must support ATS in order to enable this feature for the
> vIOMMU.
> +
> +    ``oas=val`` (supported values are 44 and 48. default: 44)
> +        Sets the Output Address Size in bits. The value set here must be less
> +        than or equal to the host SMMUv3's supported OAS, so that the
> +        intermediate physical addresses (IPA) consumed by host SMMU for
> stage-2
> +        translation do not exceed the host's max supported IPA size.
> +
> +    ``ssidsize=val`` (val between 0 and 20. default: 0)
> +        Sets the Substream ID size in bits. When set to a non-zero value,
> +        PASID capability is advertised to the vIOMMU and accelerated use cases
> +        such as Shared Virtual Addressing (SVA) are supported.
> +
>  ``-device amd-iommu[,option=...]``
>      Enables emulation of an AMD-Vi I/O Memory Management Unit (IOMMU).
>      Only available with ``-machine q35``, it supports the following options:
> --
> 2.43.0

On 3/16/2026 1:27 AM, Shameer Kolothum Thodi wrote:
> 
>> -----Original Message-----
>> From: Nathan Chen<nathanc@nvidia.com>
>> Sent: 12 March 2026 21:03
>> To:qemu-devel@nongnu.org;qemu-arm@nongnu.org
>> Cc: Eric Auger<eric.auger@redhat.com>; Peter Maydell
>> <peter.maydell@linaro.org>; Michael S . Tsirkin<mst@redhat.com>; Igor
>> Mammedov<imammedo@redhat.com>; Ani Sinha<anisinha@redhat.com>;
>> Shannon Zhao<shannon.zhaosl@gmail.com>; Paolo Bonzini
>> <pbonzini@redhat.com>; Daniel P . Berrangé<berrange@redhat.com>;
>> Eduardo Habkost<eduardo@habkost.net>; Eric Blake<eblake@redhat.com>;
>> Markus Armbruster<armbru@redhat.com>; Shameer Kolothum Thodi
>> <skolothumtho@nvidia.com>; Nicolin Chen<nicolinc@nvidia.com>; Matt
>> Ochs<mochs@nvidia.com>; Nathan Chen<nathanc@nvidia.com>
>> Subject: [PATCH v2 8/8] qemu-options.hx: Document arm-smmuv3 device's
>> accel properties
>>
>> From: Nathan Chen<nathanc@nvidia.com>
>>
>> Document arm-smmuv3 properties for setting HW-acceleration,
>> Range Invalidation, and Address Translation Services support, as
>> well as setting Output Address size and Substream ID size.
>>
>> Signed-off-by: Nathan Chen<nathanc@nvidia.com>
>> ---
>>   qemu-options.hx | 29 ++++++++++++++++++++++++++++-
>>   1 file changed, 28 insertions(+), 1 deletion(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 890c4f1d23..836de4532c 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -1274,13 +1274,40 @@ SRST
>>       ``aw-bits=val`` (val between 32 and 64, default depends on machine)
>>           This decides the address width of the IOVA address space.
>>
>> -``-device arm-smmuv3,primary-bus=id``
>> +``-device arm-smmuv3,primary-bus=id[,option=...]``
>>       This is only supported by ``-machine virt`` (ARM).
>>
>>       ``primary-bus=id``
>>           Accepts either the default root complex (pcie.0) or a
>>           pxb-pcie based root complex.
>>
>> +    ``accel=on|off`` (default: off)
>> +        Enables guest to try to leverage host SMMUv3 features for acceleration.
>> +        By default, enabling accel configures the host SMMUv3 in nested mode
>> to
>> +        support vfio-pci pass-through.
> It might be worth mentioning that the properties below are only
> applicable when accel=on.
> 
> Also, should we explicitly mention that "auto" is currently not
> supported?

Yes, I will mention accel=on being a requirement and call out that 
"auto" is currently not supported.

Thanks,
Nathan

On 3/12/26 10:03 PM, Nathan Chen wrote:
> From: Nathan Chen <nathanc@nvidia.com>
>
> Document arm-smmuv3 properties for setting HW-acceleration,
> Range Invalidation, and Address Translation Services support, as
> well as setting Output Address size and Substream ID size.
>
> Signed-off-by: Nathan Chen <nathanc@nvidia.com>
> ---
>  qemu-options.hx | 29 ++++++++++++++++++++++++++++-
>  1 file changed, 28 insertions(+), 1 deletion(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 890c4f1d23..836de4532c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1274,13 +1274,40 @@ SRST
>      ``aw-bits=val`` (val between 32 and 64, default depends on machine)
>          This decides the address width of the IOVA address space.
>  
> -``-device arm-smmuv3,primary-bus=id``
> +``-device arm-smmuv3,primary-bus=id[,option=...]``
>      This is only supported by ``-machine virt`` (ARM).
>  
>      ``primary-bus=id``
>          Accepts either the default root complex (pcie.0) or a
>          pxb-pcie based root complex.
>  
> +    ``accel=on|off`` (default: off)
> +        Enables guest to try to leverage host SMMUv3 features for acceleration.
Enables guest to leverage
> +        By default, enabling accel configures the host SMMUv3 in nested mode to
I would remove "By default, "
> +        support vfio-pci pass-through.
passthrough
> +
> +    ``ril=on|off`` (default: on)
> +        Support for Range Invalidation, which allows the SMMUv3 driver to
> +        invalidate TLB entries for a range of IOVAs at once instead of issuing
> +        separate commands to invalidate each page. Must match with host SMMUv3
> +        Range Invalidation support.
> +
> +    ``ats=on|off`` (default: off)
> +        Support for Address Translation Services, which enables PCIe devices to
> +        cache address translations in their local TLB and reduce latency. Host
> +        SMMUv3 must support ATS in order to enable this feature for the vIOMMU.
> +
> +    ``oas=val`` (supported values are 44 and 48. default: 44)
> +        Sets the Output Address Size in bits. The value set here must be less
> +        than or equal to the host SMMUv3's supported OAS, so that the
> +        intermediate physical addresses (IPA) consumed by host SMMU for stage-2
> +        translation do not exceed the host's max supported IPA size.
> +
> +    ``ssidsize=val`` (val between 0 and 20. default: 0)
> +        Sets the Substream ID size in bits. When set to a non-zero value,
> +        PASID capability is advertised to the vIOMMU and accelerated use cases
> +        such as Shared Virtual Addressing (SVA) are supported.
> +
>  ``-device amd-iommu[,option=...]``
>      Enables emulation of an AMD-Vi I/O Memory Management Unit (IOMMU).
>      Only available with ``-machine q35``, it supports the following options:
Besides,

Reviewed-by: Eric Auger <eric.auger@redhat.com>


Eric