Documentation/driver-api/vfio.rst

2 VFIO - "Virtual Function I/O" [1]_
7 allotted.  This includes x86 hardware with AMD-Vi and Intel VT-d,
10 agnostic framework for exposing direct device access to userspace, in
11 a secure, IOMMU protected environment.  In other words, this allows
12 safe [2]_, non-privileged, userspace drivers.
15 access ("device assignment") when configured for the highest possible
19 bare-metal device drivers [3]_.
22 field, also benefit from low-overhead, direct device access from
23 userspace.  Examples include network adapters (often non-TCP/IP based)
28 and requires root privileges to access things like PCI configuration
33 secure, more featureful userspace driver environment than UIO.
36 ---------------------------
39 create a programming interface made up of I/O access, interrupts,
41 by far the most critical aspect for maintaining a secure environment
42 as allowing a device read-write access to system memory imposes the
49 from each other and from arbitrary memory access, thus allowing
50 things like secure direct assignment of devices into virtual machines.
55 For instance, an individual device may be part of a larger multi-
59 could be anything from a multi-function PCI device with backdoors
60 between functions to a non-PCI-ACS (Access Control Services) capable
62 can also play a factor in terms of hiding devices.  A PCIe-to-PCI
74 ensure secure user access, it's not necessarily the preferred
96 group available, but not that particular device).  TBD - interface
109 ioctls become available, enabling access to the VFIO IOMMU interfaces.
119 ------------------
121 Assume user wants to access PCI device 0000:06:0d.0::
127 pci bus, therefore the user will make use of vfio-pci to manage the
130 	# modprobe vfio-pci
132 Binding this device to the vfio-pci driver creates the VFIO group
135 	$ lspci -n -s 0000:06:0d.0
138 	# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
143 	$ ls -l /sys/bus/pci/devices/0000:06:0d.0/iommu_group/devices
145 	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:00:1e.0 ->
147 	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.0 ->
149 	lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.1 ->
152 This device is behind a PCIe-to-PCI bridge [4]_, therefore we also
156 bind this device to the vfio-pci driver (vfio-pci does not currently
159 The final step is to provide the user with access to the group if
166 The user now has full access to all the devices and the iommu for this
167 group and can access them as follows::
219 		struct vfio_region_info reg = { .argsz = sizeof(reg) };
221 		reg.index = i;
223 		ioctl(device, VFIO_DEVICE_GET_REGION_INFO, &reg);
243 -------------------------------------------------------------------------------
248 -------------------------------------------------------------------------------
250 VFIO bus drivers, such as vfio-pci make use of only a few interfaces
284 interfaces implement the device region access defined by the device's
289 -------------------------------
302 2) The hardware supports so called DMA windows - the PCI address range
303    within which DMA transfer is allowed, any attempt to access address space
315    error recovery. A PE may be a single or multi-function IOA (IO Adapter), a
316    function of a multi-function IOA, or multiple IOAs (possibly including
396 	/* Inject EEH error, which is expected to be caused by 32-bits
460    - VFIO_IOMMU_SPAPR_REGISTER_MEMORY/VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY ioctls
467    - VFIO_IOMMU_MAP_DMA/VFIO_IOMMU_UNMAP_DMA ioctls only update the actual
469      address is from pre-registered range.
479    be as big as entire RAM, use different page size, it is optional - guests
480    create those in run-time if the guest driver supports 64bit DMA.
492 -------------------------------------------------------------------------------
499    possible for multi-function devices to have backdoors between
501    access to things like PCI config space through MMIO registers.  To
503    IOMMU driver to group multi-function PCI devices together
505    still provide isolation.  For PCI, SR-IOV Virtual Functions are the
509 .. [3] As always there are trade-offs to virtual machine device
512    these trade-offs.
517 	-[0000:00]-+-1e.0-[06]--+-0d.0
518 				\-0d.1