docs: Add '-device intel-iommu' entry
PATCH v2 1/1 docs: Add '-device intel-iommu' entry
The parameters of intel-iommu device are non-trivial to understand. Add an entry for it so that people can reference to it when using.
There're actually a few more options there, but I hide them explicitly because they shouldn't be used by normal QEMU users.
---
v2:
- Drop "in the guest" in intremap entry [Jason]
- Explain how the default value of intremap is chosen [Eric]
- Add r-bs for Jason and Yi
--- qemu-options.hx | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+)
qemu-options.hx +33 -0
@@ -926,6 +926,39 @@ SRST ``-device pci-ipmi-bt,bmc=id`` Like the KCS interface, but defines a BT interface on the PCI bus. + +``-device intel-iommu[,option=...]`` + This is only supported by ``-machine q35``, which will enable Intel VT-d + emulation within the guest. It supports below options: + + ``intremap=on|off`` (default: auto) + This enables interrupt remapping feature. It's required to enable + complete x2apic. Currently it only supports kvm kernel-irqchip modes + ``off`` or ``split``, while full kernel-irqchip is not yet supported. + The default value is "auto", which will be decided by the mode of + kernel-irqchip. + + ``caching-mode=on|off`` (default: off) + This enables caching mode for the VT-d emulated device. When + caching-mode is enabled, each guest DMA buffer mapping will generate an + IOTLB invalidation from the guest IOMMU driver to the vIOMMU device in + a synchronous way. It is required for ``-device vfio-pci`` to work + with the VT-d device, because host assigned devices requires to setup + the DMA mapping on the host before guest DMA starts. + + ``device-iotlb=on|off`` (default: off) + This enables device-iotlb capability for the emulated VT-d device. So + far virtio/vhost should be the only real user for this parameter, + paired with ats=on configured for the device. + + ``aw-bits=39|48`` (default: 39) + This decides the address width of IOVA address space. The address + space has 39 bits width for 3-level IOMMU page tables, and 48 bits for + 4-level IOMMU page tables. + + Please also refer to the wiki page for general scenarios of VT-d + emulation in QEMU: https://wiki.qemu.org/Features/VT-d. + ERST DEF("name", HAS_ARG, QEMU_OPTION_name,
Signature · 1 line
2.31.1
Quoted 59 lines · Peter Xu
The parameters of intel-iommu device are non-trivial to understand. Add an entry for it so that people can reference to it when using.
There're actually a few more options there, but I hide them explicitly because they shouldn't be used by normal QEMU users.
Cc Chao Yang <[email protected]>Cc Lei Yang <[email protected]>Cc Jing Zhao <[email protected]>Cc Jason Wang <[email protected]>Cc Michael S. Tsirkin <[email protected]>Cc Alex Williamson <[email protected]>Reviewed-by Jason Wang <[email protected]>Reviewed-by Yi Liu <[email protected]>Signed-off-by Peter Xu <[email protected]>---
v2:
- Drop "in the guest" in intremap entry [Jason]
- Explain how the default value of intremap is chosen [Eric]
- Add r-bs for Jason and YiSigned-off-by Peter Xu <[email protected]>--- qemu-options.hx | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+)qemu-options.hx +26
-0@@ -926,6 +926,39 @@ SRST ``-device pci-ipmi-bt,bmc=id`` Like the KCS interface, but defines a BT interface on the PCI bus. + +``-device intel-iommu[,option=...]`` + This is only supported by ``-machine q35``, which will enable Intel VT-d + emulation within the guest. It supports below options: + + ``intremap=on|off`` (default: auto) + This enables interrupt remapping feature. It's required to enable + complete x2apic. Currently it only supports kvm kernel-irqchip modes + ``off`` or ``split``, while full kernel-irqchip is not yet supported. + The default value is "auto", which will be decided by the mode of + kernel-irqchip. + + ``caching-mode=on|off`` (default: off) + This enables caching mode for the VT-d emulated device. When + caching-mode is enabled, each guest DMA buffer mapping will generate an + IOTLB invalidation from the guest IOMMU driver to the vIOMMU device in + a synchronous way. It is required for ``-device vfio-pci`` to work + with the VT-d device, because host assigned devices requires to setup + the DMA mapping on the host before guest DMA starts. + + ``device-iotlb=on|off`` (default: off) + This enables device-iotlb capability for the emulated VT-d device. So + far virtio/vhost should be the only real user for this parameter, + paired with ats=on configured for the device. + + ``aw-bits=39|48`` (default: 39)
qemu-options.hx SRST · line 964
Quoted 10 lines
qemu-options.hx +7
-0+ This decides the address width of IOVA address space. The address + space has 39 bits width for 3-level IOMMU page tables, and 48 bits for + 4-level IOMMU page tables. + + Please also refer to the wiki page for general scenarios of VT-d + emulation in QEMU: https://wiki.qemu.org/Features/VT-d. + ERST DEF("name", HAS_ARG, QEMU_OPTION_name,
As far as I know this looks very good.
Thanks for doing this!
Best regards,
Maxim Levitsky
Quoted 4 lines · Maxim Levitsky
As far as I know this looks very good.
Thanks for doing this!Reviewed-by Maxim Levitsky <[email protected]>
Thanks!
Michael - I just saw a pull req sent, so I wanted to double check: should this patch go through your tree at last? Thanks,
Signature · 1 line
Peter Xu
Quoted 10 lines · Peter Xu
Quoted 4 lines · Maxim Levitsky
As far as I know this looks very good.
Thanks for doing this!Reviewed-by Maxim Levitsky <[email protected]>Thanks!
Michael - I just saw a pull req sent, so I wanted to double check: should this patch go through your tree at last? Thanks,
Sure. Will be in the next one.
Quoted 2 lines
Signature · 1 line
Peter Xu
Hi Peter,
Quoted 6 lines · Peter Xu
The parameters of intel-iommu device are non-trivial to understand. Add an entry for it so that people can reference to it when using.
There're actually a few more options there, but I hide them explicitly because they shouldn't be used by normal QEMU users.
Quoted 9 lines
Cc Chao Yang <[email protected]>Cc Lei Yang <[email protected]>Cc Jing Zhao <[email protected]>Cc Jason Wang <[email protected]>Cc Michael S. Tsirkin <[email protected]>Cc Alex Williamson <[email protected]>Reviewed-by Jason Wang <[email protected]>Reviewed-by Yi Liu <[email protected]>Signed-off-by Peter Xu <[email protected]>
Thanks
Eric
Quoted 55 lines
---
v2:
- Drop "in the guest" in intremap entry [Jason]
- Explain how the default value of intremap is chosen [Eric]
- Add r-bs for Jason and YiSigned-off-by Peter Xu <[email protected]>--- qemu-options.hx | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+)qemu-options.hx +33
-0@@ -926,6 +926,39 @@ SRST ``-device pci-ipmi-bt,bmc=id`` Like the KCS interface, but defines a BT interface on the PCI bus. + +``-device intel-iommu[,option=...]`` + This is only supported by ``-machine q35``, which will enable Intel VT-d + emulation within the guest. It supports below options: + + ``intremap=on|off`` (default: auto) + This enables interrupt remapping feature. It's required to enable + complete x2apic. Currently it only supports kvm kernel-irqchip modes + ``off`` or ``split``, while full kernel-irqchip is not yet supported. + The default value is "auto", which will be decided by the mode of + kernel-irqchip. + + ``caching-mode=on|off`` (default: off) + This enables caching mode for the VT-d emulated device. When + caching-mode is enabled, each guest DMA buffer mapping will generate an + IOTLB invalidation from the guest IOMMU driver to the vIOMMU device in + a synchronous way. It is required for ``-device vfio-pci`` to work + with the VT-d device, because host assigned devices requires to setup + the DMA mapping on the host before guest DMA starts. + + ``device-iotlb=on|off`` (default: off) + This enables device-iotlb capability for the emulated VT-d device. So + far virtio/vhost should be the only real user for this parameter, + paired with ats=on configured for the device. + + ``aw-bits=39|48`` (default: 39) + This decides the address width of IOVA address space. The address + space has 39 bits width for 3-level IOMMU page tables, and 48 bits for + 4-level IOMMU page tables. + + Please also refer to the wiki page for general scenarios of VT-d + emulation in QEMU: https://wiki.qemu.org/Features/VT-d. + ERST DEF("name", HAS_ARG, QEMU_OPTION_name,