1.. _riscv-iommu: 2 3RISC-V IOMMU support for RISC-V machines 4======================================== 5 6QEMU implements a RISC-V IOMMU emulation based on the RISC-V IOMMU spec 7version 1.0 `iommu1.0.0`_. 8 9The emulation includes a PCI reference device (riscv-iommu-pci) and a platform 10bus device (riscv-iommu-sys) that QEMU RISC-V boards can use. The 'virt' 11RISC-V machine is compatible with both devices. 12 13riscv-iommu-pci reference device 14-------------------------------- 15 16This device implements the RISC-V IOMMU emulation as recommended by the section 17"Integrating an IOMMU as a PCIe device" of `iommu1.0.0`_: a PCI device with base 18class 08h, sub-class 06h and programming interface 00h. 19 20As a reference device it doesn't implement anything outside of the specification, 21so it uses a generic default PCI ID given by QEMU: 1b36:0014. 22 23To include the device in the 'virt' machine: 24 25.. code-block:: bash 26 27 $ qemu-system-riscv64 -M virt -device riscv-iommu-pci,[optional_pci_opts] (...) 28 29This will add a RISC-V IOMMU PCI device in the board following any additional 30PCI parameters (like PCI bus address). The behavior of the RISC-V IOMMU is 31defined by the spec but its operation is OS dependent. 32 33As of this writing the existing Linux kernel support `linux-v8`_, not yet merged, 34does not have support for features like VFIO passthrough. The IOMMU emulation 35was tested using a public Ventana Micro Systems kernel repository in 36`ventana-linux`_. This kernel is based on `linux-v8`_ with additional patches that 37enable features like KVM VFIO passthrough with irqbypass. Until the kernel support 38is feature complete feel free to use the kernel available in the Ventana Micro Systems 39mirror. 40 41The current Linux kernel support will use the IOMMU device to create IOMMU groups 42with any eligible cards available in the system, regardless of factors such as the 43order in which the devices are added in the command line. 44 45This means that these command lines are equivalent as far as the current 46IOMMU kernel driver behaves: 47 48.. code-block:: bash 49 50 $ qemu-system-riscv64 \ 51 -M virt,aia=aplic-imsic,aia-guests=5 \ 52 -device riscv-iommu-pci,addr=1.0,vendor-id=0x1efd,device-id=0xedf1 \ 53 -device e1000e,netdev=net1 -netdev user,id=net1,net=192.168.0.0/24 \ 54 -device e1000e,netdev=net2 -netdev user,id=net2,net=192.168.200.0/24 \ 55 (...) 56 57 $ qemu-system-riscv64 \ 58 -M virt,aia=aplic-imsic,aia-guests=5 \ 59 -device e1000e,netdev=net1 -netdev user,id=net1,net=192.168.0.0/24 \ 60 -device e1000e,netdev=net2 -netdev user,id=net2,net=192.168.200.0/24 \ 61 -device riscv-iommu-pci,addr=1.0,vendor-id=0x1efd,device-id=0xedf1 \ 62 (...) 63 64Both will create iommu groups for the two e1000e cards. 65 66Another thing to notice on `linux-v8`_ and `ventana-linux`_ is that the kernel driver 67considers an IOMMU identified as a Rivos device, i.e. it uses Rivos vendor ID. To 68use the riscv-iommu-pci device with the existing kernel support we need to emulate 69a Rivos PCI IOMMU by setting 'vendor-id' and 'device-id': 70 71.. code-block:: bash 72 73 $ qemu-system-riscv64 -M virt \ 74 -device riscv-iommu-pci,vendor-id=0x1efd,device-id=0xedf1 (...) 75 76Several options are available to control the capabilities of the device, namely: 77 78- "bus": the bus that the IOMMU device uses 79- "ioatc-limit": size of the Address Translation Cache (default to 2Mb) 80- "intremap": enable/disable MSI support 81- "ats": enable ATS support 82- "off" (Out-of-reset translation mode: 'on' for DMA disabled, 'off' for 'BARE' (passthrough)) 83- "s-stage": enable s-stage support 84- "g-stage": enable g-stage support 85- "hpm-counters": number of hardware performance counters available. Maximum value is 31. 86 Default value is 31. Use 0 (zero) to disable HPM support 87 88riscv-iommu-sys device 89---------------------- 90 91This device implements the RISC-V IOMMU emulation as a platform bus device that 92RISC-V boards can use. 93 94For the 'virt' board the device is disabled by default. To enable it use the 95'iommu-sys' machine option: 96 97.. code-block:: bash 98 99 $ qemu-system-riscv64 -M virt,iommu-sys=on (...) 100 101There is no options to configure the capabilities of this device in the 'virt' 102board using the QEMU command line. The device is configured with the following 103riscv-iommu options: 104 105- "ioatc-limit": default value (2Mb) 106- "intremap": enabled 107- "ats": enabled 108- "off": on (DMA disabled) 109- "s-stage": enabled 110- "g-stage": enabled 111 112.. _iommu1.0.0: https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0.0/riscv-iommu.pdf 113 114.. _linux-v8: https://lore.kernel.org/linux-riscv/cover.1718388908.git.tjeznach@rivosinc.com/ 115 116.. _ventana-linux: https://github.com/ventanamicro/linux/tree/dev-upstream 117