docs/devel/vfio-iommufd.rst

9 for assigned devices. While the legacy kernel interface is group-centric,
10 the new iommufd interface is device-centric, relying on device fd and iommufd.
12 To support both interfaces in the QEMU VFIO device, introduce a base container
18 specific to either legacy or iommufd. Each container has its own way to setup
25       +-------+  +----------+  +-----+  +-----+
27       +---+---+  +----+-----+  +--+--+  +--+--+     +----------------------+
29           |           |           |        |        +------------+---------+
30       +---V-----------V-----------V--------V----+               /
31       |           VFIOAddressSpace              | <------------+
34       +-------+----------------------------+----+
37       +-------V------+            +--------V----------+
40       +-------+------+            +--------+----------+
47               +---------------+            | group/container fd
51               |       +-------V------------V-----------------+
53   (map/unmap  |       +---------+--------------------+-------+
56        +------V------+    +-----V------+      +------V--------+
58        +-------------+    +------------+      +---------------+
60 * Secure Context setup
62   - iommufd BE: uses device fd and iommufd to setup secure context
64   - vfio legacy BE: uses group fd and container fd to setup secure context
69   - iommufd BE: device fd is opened through ``/dev/vfio/devices/vfioX``
70   - vfio legacy BE: device fd is retrieved from group fd ioctl
83 ---------------------------------
87 Step 2: configure QEMU
88 ----------------------
93 Any QEMU device (e.g. VFIO device) wishing to use ``/dev/iommu`` must
95 named iommufd which allows to pass an iommufd object. Take ``vfio-pci``
98 .. code-block:: bash
100     -object iommufd,id=iommufd0
101     -device vfio-pci,host=0000:02:00.0,iommufd=iommufd0
107 .. code-block:: bash
109     -object iommufd,id=iommufd0,fd=22
110     -device vfio-pci,iommufd=iommufd0,fd=23
112 If the ``fd`` property is not passed, the fd is opened by QEMU.
114 If no ``iommufd`` object is passed to the ``vfio-pci`` device, iommufd
118 .. code-block:: bash
120     -device vfio-pci,host=0000:02:00.0
131 ---------------
137 .. code-block:: bash
139     -object iommufd,id=iommufd0
140     -device vfio-pci,host=0000:02:00.0,iommufd=iommufd0,enable-migration=on
143 -------
148 .. code-block:: none
150     qemu-system-x86_64: warning: IOMMU_IOAS_MAP failed: Bad address, PCI BAR?
151 …qemu-system-x86_64: vfio_container_dma_map(0x560cb6cb1620, 0xe000000021000, 0x3000, 0x7f32ed55c000…
154 --------------------
156 ``vfio-pci`` device checks sysfsdev property to decide if backend is a mdev.
161 .. code-block:: none
163 …qemu-system-x86_64: -device vfio-pci,iommufd=iommufd0,x-balloon-allowed=on,fd=9: vfio VFIO_FD9: x-…
165 ``vfio-ap`` and ``vfio-ccw`` devices don't have same issue as their backend