Documentation/driver-api/vfio.rst

2 VFIO - "Virtual Function I/O" [1]_
5 Many modern system now provide DMA and interrupt remapping facilities
7 allotted.  This includes x86 hardware with AMD-Vi and Intel VT-d,
12 safe [2]_, non-privileged, userspace drivers.
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)
36 ---------------------------
40 and DMA.  Without going into the details of each of these, DMA is
42 as allowing a device read-write access to system memory imposes the
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
96 group available, but not that particular device).  TBD - interface
119 ------------------
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
203 	/* Allocate some space and setup a DMA mapping */
243 -------------------------------------------------------------------------------
248 -------------------------------------------------------------------------------
250 VFIO bus drivers, such as vfio-pci make use of only a few interfaces
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
307    to map/unmap pages for DMA, and it normally maps 1..32 pages per call and
309    things faster, the map/unmap handling has been implemented in real mode
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
324 		returns the size and the start of the DMA window on the PCI bus.
329 		the DMA window is and adjust rlimit before doing any real job.
355 	/* Allocate some space and setup a DMA mapping */
363 	/* Check here is .iova/.size are within DMA window from spapr_iommu_info */
396 	/* Inject EEH error, which is expected to be caused by 32-bits
455    PPC64 paravirtualized guests generate a lot of map/unmap requests,
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.
471    This separation helps in optimizing DMA for guests.
473 6) sPAPR specification allows guests to have an additional DMA window(s) on
477    the userspace. The existing hardware supports up to 2 DMA windows, one is
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.
482    VFIO_IOMMU_SPAPR_TCE_CREATE receives a page shift, a DMA window size and
487    space cannot choose the location of DMA windows.
492 -------------------------------------------------------------------------------
498 .. [2] "safe" also depends upon a device being "well behaved".  It's
499    possible for multi-function devices to have backdoors between
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