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, that QEMU
10 RISC-V boards can use.  The 'virt' RISC-V machine is compatible with this
13 riscv-iommu-pci reference device
14 --------------------------------
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`_: a PCI device with base
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
39 mirror.
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
86 .. _iommu1.0: https://github.com/riscv-non-isa/riscv-iommu/releases/download/v1.0/riscv-iommu.pdf
88 .. _linux-v8: https://lore.kernel.org/linux-riscv/cover.1718388908.git.tjeznach@rivosinc.com/
90 .. _ventana-linux: https://github.com/ventanamicro/linux/tree/dev-upstream