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`_. 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`_: 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 86riscv-iommu-sys device 87---------------------- 88 89This device implements the RISC-V IOMMU emulation as a platform bus device that 90RISC-V boards can use. 91 92For the 'virt' board the device is disabled by default. To enable it use the 93'iommu-sys' machine option: 94 95.. code-block:: bash 96 97 $ qemu-system-riscv64 -M virt,iommu-sys=on (...) 98 99There is no options to configure the capabilities of this device in the 'virt' 100board using the QEMU command line. The device is configured with the following 101riscv-iommu options: 102 103- "ioatc-limit": default value (2Mb) 104- "intremap": enabled 105- "ats": enabled 106- "off": on (DMA disabled) 107- "s-stage": enabled 108- "g-stage": enabled 109 110.. _iommu1.0: https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0/riscv-iommu.pdf 111 112.. _linux-v8: https://lore.kernel.org/linux-riscv/cover.1718388908.git.tjeznach@rivosinc.com/ 113 114.. _ventana-linux: https://github.com/ventanamicro/linux/tree/dev-upstream 115