| 1 | .. _riscv-iommu: |
| 2 | |
| 3 | RISC-V IOMMU support for RISC-V machines |
| 4 | ======================================== |
| 5 | |
| 6 | QEMU implements a RISC-V IOMMU emulation based on the RISC-V IOMMU spec |
| 7 | version 1.0 `iommu1.0.0`_. |
| 8 | |
| 9 | The emulation includes a PCI reference device (riscv-iommu-pci) and a platform |
| 10 | bus device (riscv-iommu-sys) that QEMU RISC-V boards can use. The 'virt' |
| 11 | RISC-V machine is compatible with both devices. |
| 12 | |
| 13 | riscv-iommu-pci reference device |
| 14 | -------------------------------- |
| 15 | |
| 16 | This 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 |
| 18 | class 08h, sub-class 06h and programming interface 00h. |
| 19 | |
| 20 | As a reference device it doesn't implement anything outside of the specification, |
| 21 | so it uses a generic default PCI ID given by QEMU: 1b36:0014. |
| 22 | |
| 23 | To 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 | |
| 29 | This will add a RISC-V IOMMU PCI device in the board following any additional |
| 30 | PCI parameters (like PCI bus address). The behavior of the RISC-V IOMMU is |
| 31 | defined by the spec but its operation is OS dependent. |
| 32 | |
| 33 | Linux kernel iommu support was merged in v6.13. QEMU IOMMU emulation can be |
| 34 | used with mainline kernels for simple IOMMU PCIe support. |
| 35 | |
| 36 | As of v6.17, it does not have support for features like VFIO passthrough. |
| 37 | There is a `VFIO`_ RFC series that is not yet merged. The public Ventana Micro |
| 38 | Systems kernel repository in `ventana-linux`_ can be used for testing the VFIO |
| 39 | functions. |
| 40 | |
| 41 | The v6.13+ Linux kernel support uses the IOMMU device to create IOMMU groups |
| 42 | with any eligible cards available in the system, regardless of factors such as the |
| 43 | order in which the devices are added in the command line. |
| 44 | |
| 45 | This means that these command lines are equivalent as far as the current |
| 46 | IOMMU 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 \ |
| 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=3.0 \ |
| 62 | (...) |
| 63 | |
| 64 | Both will create iommu groups for the two e1000e cards. |
| 65 | |
| 66 | Several options are available to control the capabilities of the device, namely: |
| 67 | |
| 68 | - "bus": the bus that the IOMMU device uses |
| 69 | - "ioatc-limit": size of the Address Translation Cache (default to 2Mb) |
| 70 | - "intremap": enable/disable MSI support |
| 71 | - "ats": enable ATS support |
| 72 | - "off" (Out-of-reset translation mode: 'on' for DMA disabled, 'off' for 'BARE' (passthrough)) |
| 73 | - "s-stage": enable s-stage support |
| 74 | - "g-stage": enable g-stage support |
| 75 | - "hpm-counters": number of hardware performance counters available. Maximum value is 31. |
| 76 | Default value is 31. Use 0 (zero) to disable HPM support |
| 77 | - "vendor-id"/"device-id": pci device ID. Defaults to 1b36:0014 (Redhat) |
| 78 | |
| 79 | riscv-iommu-sys device |
| 80 | ---------------------- |
| 81 | |
| 82 | This device implements the RISC-V IOMMU emulation as a platform bus device that |
| 83 | RISC-V boards can use. |
| 84 | |
| 85 | For the 'virt' board the device is disabled by default. To enable it use the |
| 86 | 'iommu-sys' machine option: |
| 87 | |
| 88 | .. code-block:: bash |
| 89 | |
| 90 | $ qemu-system-riscv64 -M virt,iommu-sys=on (...) |
| 91 | |
| 92 | There is no options to configure the capabilities of this device in the 'virt' |
| 93 | board using the QEMU command line. The device is configured with the following |
| 94 | riscv-iommu options: |
| 95 | |
| 96 | - "ioatc-limit": default value (2Mb) |
| 97 | - "intremap": enabled |
| 98 | - "ats": enabled |
| 99 | - "off": on (DMA disabled) |
| 100 | - "s-stage": enabled |
| 101 | - "g-stage": enabled |
| 102 | |
| 103 | .. _iommu1.0.0: https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0.0/riscv-iommu.pdf |
| 104 | |
| 105 | .. _VFIO: https://lore.kernel.org/linux-riscv/20241114161845.502027-17-ajones@ventanamicro.com/ |
| 106 | |
| 107 | .. _ventana-linux: https://github.com/ventanamicro/linux/tree/dev-upstream |