docs/specs/riscv-iommu.rst

1 .. _riscv-iommu:
3 RISC-V IOMMU support for RISC-V machines
6 QEMU implements a RISC-V IOMMU emulation based on the RISC-V IOMMU spec
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.
13 riscv-iommu-pci reference device
14 --------------------------------
16 This device implements the RISC-V IOMMU emulation as recommended by the section
18 class 08h, sub-class 06h and programming interface 00h.
25 .. code-block:: bash
27   $ qemu-system-riscv64 -M virt -device riscv-iommu-pci,[optional_pci_opts] (...)
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
33 As of this writing the existing Linux kernel support `linux-v8`_, not yet merged,
36 `ventana-linux`_.  This kernel is based on `linux-v8`_ with additional patches that
37 enable features like KVM VFIO passthrough with irqbypass.  Until the kernel support
48 .. code-block:: bash
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 \
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 \
66 Another thing to notice on `linux-v8`_ and `ventana-linux`_ is that the kernel driver
68 use the riscv-iommu-pci device with the existing kernel support we need to emulate
69 a Rivos PCI IOMMU by setting 'vendor-id' and 'device-id':
71 .. code-block:: bash
73   $ qemu-system-riscv64 -M virt	\
74      -device riscv-iommu-pci,vendor-id=0x1efd,device-id=0xedf1 (...)
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
88 riscv-iommu-sys device
89 ----------------------
91 This device implements the RISC-V IOMMU emulation as a platform bus device that
92 RISC-V boards can use.
95 'iommu-sys' machine option:
97 .. code-block:: bash
99   $ qemu-system-riscv64 -M virt,iommu-sys=on (...)
103 riscv-iommu options:
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
112 .. _iommu1.0.0: https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0.0/riscv-iommu.p…
114 .. _linux-v8: https://lore.kernel.org/linux-riscv/cover.1718388908.git.tjeznach@rivosinc.com/
116 .. _ventana-linux: https://github.com/ventanamicro/linux/tree/dev-upstream