linux-headers/linux/vfio.h

1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
3  * VFIO API definition
21 /* Kernel & User level defines for VFIO IOCTLs. */
37 /* Two-stage IOMMU */
43  * The No-IOMMU IOMMU offers no translation or isolation for devices and
44  * supports no ioctls outside of VFIO_CHECK_EXTENSION.  Use of VFIO's No-IOMMU
74  * For extension of INFO ioctls, VFIO makes use of a capability chain
100 /* -------- IOCTLs for VFIO file descriptor (/dev/vfio/vfio) -------- */
103  * VFIO_GET_API_VERSION - _IO(VFIO_TYPE, VFIO_BASE + 0)
105  * Report the version of the VFIO API.  This allows us to bump the entire
114  * VFIO_CHECK_EXTENSION - _IOW(VFIO_TYPE, VFIO_BASE + 1, __u32)
123  * VFIO_SET_IOMMU - _IOW(VFIO_TYPE, VFIO_BASE + 2, __s32)
130  * Return: 0 on success, -errno on failure
131  * Availability: When VFIO group attached
135 /* -------- IOCTLs for GROUP file descriptors (/dev/vfio/$GROUP) -------- */
138  * VFIO_GROUP_GET_STATUS - _IOR(VFIO_TYPE, VFIO_BASE + 3,
143  * Return: 0 on succes, -errno on failure.
155  * VFIO_GROUP_SET_CONTAINER - _IOW(VFIO_TYPE, VFIO_BASE + 4, __s32)
157  * Set the container for the VFIO group to the open VFIO file
161  * of the VFIO file descriptor and the VFIO group file descriptor
162  * available to the user.
163  * Return: 0 on success, -errno on failure.
169  * VFIO_GROUP_UNSET_CONTAINER - _IO(VFIO_TYPE, VFIO_BASE + 5)
176  * effectively also returning the VFIO file descriptor to an initial
178  * Return: 0 on success, -errno on failure.
184  * VFIO_GROUP_GET_DEVICE_FD - _IOW(VFIO_TYPE, VFIO_BASE + 6, char)
190  * Return: new file descriptor on success, -errno on failure.
195 /* --------------- IOCTLs for DEVICE file descriptors --------------- */
198  * VFIO_DEVICE_GET_INFO - _IOR(VFIO_TYPE, VFIO_BASE + 7,
203  * Return: 0 on success, -errno on failure.
209 #define VFIO_DEVICE_FLAGS_PCI	(1 << 1)	/* vfio-pci device */
210 #define VFIO_DEVICE_FLAGS_PLATFORM (1 << 2)	/* vfio-platform device */
211 #define VFIO_DEVICE_FLAGS_AMBA  (1 << 3)	/* vfio-amba device */
212 #define VFIO_DEVICE_FLAGS_CCW	(1 << 4)	/* vfio-ccw device */
213 #define VFIO_DEVICE_FLAGS_AP	(1 << 5)	/* vfio-ap device */
214 #define VFIO_DEVICE_FLAGS_FSL_MC (1 << 6)	/* vfio-fsl-mc device */
216 #define VFIO_DEVICE_FLAGS_CDX	(1 << 8)	/* vfio-cdx device */
230 #define VFIO_DEVICE_API_PCI_STRING		"vfio-pci"
231 #define VFIO_DEVICE_API_PLATFORM_STRING		"vfio-platform"
232 #define VFIO_DEVICE_API_AMBA_STRING		"vfio-amba"
233 #define VFIO_DEVICE_API_CCW_STRING		"vfio-ccw"
234 #define VFIO_DEVICE_API_AP_STRING		"vfio-ap"
238  * are further-defined in vfio_zdev.h
260  * VFIO_DEVICE_GET_REGION_INFO - _IOWR(VFIO_TYPE, VFIO_BASE + 8,
269  * Return: 0 on success, -errno on failure.
287  * within a region with mmap support.  When specified, the user should only
289  * areas specified may fail (such as the range covering a PCI MSI-X table) or
311  * vfio bus drivers of defining which region indexes correspond to which region
313  * vfio-pci.  For instance, if we were to go back in time, we might remove
314  * VFIO_PCI_VGA_REGION_INDEX and let vfio-pci simply define that all indexes
317  * means that non-VGA devices wouldn't need to waste this index, and thus the
319  * descriptor offsets in vfio-pci.
321  * The current implementation is now part of the user ABI, so we can't use this
348 /* sub-types for VFIO_REGION_TYPE_PCI_* */
350 /* 8086 vendor PCI sub-types */
355 /* 10de vendor PCI sub-types */
363 /* 1014 vendor PCI sub-types */
372 /* sub-types for VFIO_REGION_TYPE_GFX */
376  * struct vfio_region_gfx_edid - EDID region layout.
393  * You can use the edid-decode ulility (comes with xorg-x11-utils) to
407  *   (1) set link-state to down.
409  *   (3) set link-state to up.
422 /* sub-types for VFIO_REGION_TYPE_CCW */
427 /* sub-types for VFIO_REGION_TYPE_MIGRATION */
431 	__u32 device_state;         /* VFIO device state */
460  * which allows direct access to non-MSIX registers which happened to be within
469  * Capability with compressed real address (aka SSA - small system address)
484  * the NVlink2 bridge driver from the bridge's "ibm,nvlink-speed"
500  * VFIO_DEVICE_GET_IRQ_INFO - _IOWR(VFIO_TYPE, VFIO_BASE + 9,
506  * using multiple IRQs are primarily intended to support MSI-like
517  * automatically masked by VFIO and the user needs to unmask the line
524  * and MSI-X where the driver may only use a subset of the available
525  * indexes, but VFIO needs to enable a specific number of vectors
526  * upfront.  In the case of MSI-X, where the user can enable MSI-X and
547  * VFIO_DEVICE_SET_IRQS - _IOW(VFIO_TYPE, VFIO_BASE + 10, struct vfio_irq_set)
564  * A value of -1 can be used to either de-assign interrupts if already
565  * assigned or skip un-assigned interrupts.  For example, to set an eventfd
568  * data = {fd1, -1, fd2}
578  * can be disabled using the -1 value for DATA_EVENTFD or the index can be
581  * Note that ACTION_[UN]MASK specify user->kernel signaling (irqfds) while
582  * ACTION_TRIGGER specifies kernel->user signaling.
607  * VFIO_DEVICE_RESET - _IO(VFIO_TYPE, VFIO_BASE + 11)
614  * The VFIO-PCI bus driver makes use of the following fixed region and
637 	VFIO_PCI_NUM_REGIONS = 9 /* Fixed user ABI, region indexes >=9 use */
651  * The vfio-ccw bus driver makes use of the following fixed region and
669  * The vfio-ap bus driver makes use of the following IRQ index mapping.
679  * VFIO_DEVICE_GET_PCI_HOT_RESET_INFO - _IOWR(VFIO_TYPE, VFIO_BASE + 12,
689  *	- If the calling device is opened via the traditional group/container
690  *	  API, group_id is reported.  User should check if it has owned all
694  *	- If the calling device is opened as a cdev, devid is reported.
697  *	  the dev_set, ex. bound to a vfio driver, and also be owned by
701  *	     the cdev calling conventions do not support a proof-of-ownership
716  *	  of VFIO_DEVICE_PCI_HOT_RESET ioctl outside of the proof-of-ownership
720  *	  the user.  This flag is available only when
722  *	  When set, user could invoke VFIO_DEVICE_PCI_HOT_RESET with a zero
726  * Return: 0 on success, -errno on failure:
727  *	-enospc = insufficient buffer, -enodev = unsupported for device.
734 #define VFIO_PCI_DEVID_NOT_OWNED	-1
753  * VFIO_DEVICE_PCI_HOT_RESET - _IOW(VFIO_TYPE, VFIO_BASE + 13,
757  * other devices sharing the bus/slot.  The calling user must have
761  * When called on a device file descriptor acquired through the vfio
762  * group interface, the user is required to provide proof of ownership
766  * When called on a direct cdev opened vfio device, the flags field of
774  * Return: 0 on success, -errno on failure.
786  * VFIO_DEVICE_QUERY_GFX_PLANE - _IOW(VFIO_TYPE, VFIO_BASE + 14,
792  * - VFIO_GFX_PLANE_TYPE_PROBE and VFIO_GFX_PLANE_TYPE_DMABUF are set
793  *   to ask if the mdev supports dma-buf. 0 on support, -EINVAL on no
794  *   support for dma-buf.
795  * - VFIO_GFX_PLANE_TYPE_PROBE and VFIO_GFX_PLANE_TYPE_REGION are set
796  *   to ask if the mdev supports region. 0 on support, -EINVAL on no
798  * - VFIO_GFX_PLANE_TYPE_DMABUF or VFIO_GFX_PLANE_TYPE_REGION is set
800  * - Others are invalid and return -EINVAL.
804  *    returned with zero-initialized drm_format, size, width and height
808  * Return: 0 on success, -errno on other failure.
831 		__u32 dmabuf_id;	/* dma-buf id */
839  * VFIO_DEVICE_GET_GFX_DMABUF - _IOW(VFIO_TYPE, VFIO_BASE + 15, __u32)
841  * Return a new dma-buf file descriptor for an exposed guest framebuffer
849  * VFIO_DEVICE_IOEVENTFD - _IOW(VFIO_TYPE, VFIO_BASE + 16,
854  * vfio bus drivers may not support this for all regions, for all widths,
855  * or at all.  vfio-pci currently only enables support for BAR regions,
856  * excluding the MSI-X vector table.
858  * Return: 0 on success, -errno on failure.
863 #define VFIO_DEVICE_IOEVENTFD_8		(1 << 0) /* 1-byte write */
864 #define VFIO_DEVICE_IOEVENTFD_16	(1 << 1) /* 2-byte write */
865 #define VFIO_DEVICE_IOEVENTFD_32	(1 << 2) /* 4-byte write */
866 #define VFIO_DEVICE_IOEVENTFD_64	(1 << 3) /* 8-byte write */
870 	__s32	fd;			/* -1 for de-assignment */
877  * VFIO_DEVICE_FEATURE - _IOWR(VFIO_TYPE, VFIO_BASE + 17,
890  * Return 0 on success, -errno on failure.
895 #define VFIO_DEVICE_FEATURE_MASK	(0xffff) /* 16-bit feature index */
905  * VFIO_DEVICE_BIND_IOMMUFD - _IOR(VFIO_TYPE, VFIO_BASE + 18,
907  * @argsz:	 User filled size of this data.
915  * User is restricted from accessing the device before the binding operation
920  * Return: 0 on success, -errno on failure.
932  * VFIO_DEVICE_ATTACH_IOMMUFD_PT - _IOW(VFIO_TYPE, VFIO_BASE + 19,
934  * @argsz:	User filled size of this data.
948  * If a vfio device or a pasid of this device is currently attached to a valid
955  * Return: 0 on success, -errno on failure.
968  * VFIO_DEVICE_DETACH_IOMMUFD_PT - _IOW(VFIO_TYPE, VFIO_BASE + 20,
970  * @argsz:	User filled size of this data.
979  * Return: 0 on success, -errno on failure.
993  * PCI SR-IOV PF when SR-IOV is enabled on the PF and there are no existing
994  * open VFs.  Data provided when setting this feature is a 16-byte array
1030  * Upon VFIO_DEVICE_FEATURE_SET, execute a migration state change on the VFIO
1035  * value before the operation returns to the user.
1038  * transitions outside of manipulation by the user or the VFIO_DEVICE_RESET
1043  * The user can then decide if it should execute a VFIO_DEVICE_RESET, attempt
1048  * with that session is returned in data_fd. The user is responsible to close
1049  * this FD when it is finished. The user must consider the migration data stream
1051  * stream. The user is not required to preserve buffer segmentation when writing
1054  * Upon VFIO_DEVICE_FEATURE_GET, get the current migration state of the VFIO
1055  * device, data_fd will be -1.
1070  *  RUNNING - The device is running normally
1071  *  STOP - The device does not change the internal or external state
1072  *  STOP_COPY - The device internal state can be read out
1073  *  RESUMING - The device is stopped and is loading a new internal state
1074  *  ERROR - The device has failed and must be reset
1077  *  RUNNING_P2P - RUNNING, except the device cannot do peer to peer DMA
1079  *  PRE_COPY - The device is running normally but tracking internal state
1082  *  PRE_COPY_P2P - PRE_COPY, except the device cannot do peer to peer DMA
1087  * RUNNING_P2P -> STOP
1088  * STOP_COPY -> STOP
1093  *   subsystems in the STOP state, for example PCI MSI-X and PCI config space.
1094  *   Failure by the user to restrict device access while in STOP must not result
1095  *   in error conditions outside the user context (ex. host system faults).
1099  * RESUMING -> STOP
1105  *   user provided data is found to be incomplete, inconsistent, or otherwise
1114  * PRE_COPY -> RUNNING
1115  * RUNNING_P2P -> RUNNING
1117  *   interrupts, DMA, respond to MMIO, all vfio device regions are functional,
1122  * PRE_COPY_P2P -> RUNNING_P2P
1123  * RUNNING -> RUNNING_P2P
1124  * STOP -> RUNNING_P2P
1130  * RUNNING -> PRE_COPY
1131  * RUNNING_P2P -> PRE_COPY_P2P
1132  * STOP -> STOP_COPY
1144  *   in PRE_COPY_P2P -> STOP_COPY.
1146  * PRE_COPY -> PRE_COPY_P2P
1151  * PRE_COPY_P2P -> PRE_COPY
1155  * PRE_COPY_P2P -> STOP_COPY
1161  *   The user should take steps to restrict access to vfio device regions while
1165  * STOP -> RESUMING
1173  * STOP_COPY -> PRE_COPY
1174  * STOP_COPY -> PRE_COPY_P2P
1180  * any -> ERROR
1190  * user context where peer-to-peer DMA between devices may be active. The
1197  * STOP or STOP_COPY the user must not touch the device, otherwise the state
1203  *   - Select the shortest path.
1204  *   - The path cannot have saving group states as interior arcs, only
1209  * transition is invisible to the user. When working with combination arcs the
1210  * user may see any step along the path in the device_state if SET_STATE
1216  * support them. The user can discover if these states are supported by using
1217  * VFIO_DEVICE_FEATURE_MIGRATION. By using combination transitions the user can
1236  * VFIO_MIG_GET_PRECOPY_INFO - _IO(VFIO_TYPE, VFIO_BASE + 21)
1240  * remaining to be transferred. It allows the user to judge when it is
1244  * return -EINVAL from any other migration state.
1252  * data available from the device. This field should have a non-zero initial
1271  * During pre-copy the migration data FD has a temporary "end of stream" that is
1284  * Return: 0 on success, -1 and errno set on failure.
1297  * state with the platform-based power management.  Device use of lower power
1303  * (either from the host or through the vfio uAPI) when the device is in the
1306  * device may re-enter the low power state.  For single shot low power support
1307  * with wake-up notification, see
1316  * VFIO_DEVICE_FEATURE_LOW_POWER_ENTRY with the exception that the user
1317  * provides an eventfd for wake-up notification.  When the device moves out of
1318  * the low power state for the wake-up, the host will not allow the device to
1319  * re-enter a low power state without a subsequent user call to one of the low
1323  * or through any other access (where the wake-up notification has been
1357  * initiating and report them back to userspace. It is part of the VFIO
1376  * into a single kernel page. User space can try higher values but should give
1411  *  bitmap[(addr - iova)/page_size] & (1ULL << (addr % 64))
1419  * perform any initialization of the user provided bitmap.
1455  * but the in-band device interface lacks the support. Consequently, it is not
1457  * in-band through the configuration space. At present, this feature is supported
1461  * the device's BUS MASTER setting as SET (enable) will grant the device the
1471 /* -------- API for Type1 VFIO IOMMU -------- */
1474  * VFIO_IOMMU_GET_INFO - _IOR(VFIO_TYPE, VFIO_BASE + 12, struct vfio_iommu_info)
1493  * excluding any non-relaxable reserved regions exposed by
1524  * size in bytes that can be used by user applications when getting the dirty
1554  * VFIO_IOMMU_MAP_DMA - _IOW(VFIO_TYPE, VFIO_BASE + 13, struct vfio_dma_map)
1561  * maintain memory consistency within the user application, the updated vaddr
1563  * will result in user memory corruption and/or device misbehavior.  iova and
1587  * VFIO_IOMMU_UNMAP_DMA - _IOWR(VFIO_TYPE, VFIO_BASE + 14,
1592  * field.  No guarantee is made to the user that arbitrary unmaps of iova
1597  * before unmapping IO virtual addresses. When this flag is set, the user must
1598  * provide a struct vfio_bitmap in data[]. User must provide zero-allocated
1600  * A bit in the bitmap represents one page, of user provided page size in
1603  * pages in the range of unmapped size is returned in the user-provided
1607  * must be 0.  This cannot be combined with the get-dirty-bitmap flag.
1610  * virtual addresses in the iova range.  DMA to already-mapped pages continues.
1612  * This cannot be combined with the get-dirty-bitmap flag.
1628  * IOCTLs to enable/disable IOMMU container usage.
1635  * VFIO_IOMMU_DIRTY_PAGES - _IOWR(VFIO_TYPE, VFIO_BASE + 17,
1644  * are logged until logging is disabled by user application by calling the IOCTL
1652  * The user must specify the IOVA range and the pgsize through the structure
1656  * user must provide a zeroed memory area for the bitmap memory and specify its
1658  * starting from iova offset. The user should provide page size in bitmap.pgsize
1685 /* -------- Additional API for SPAPR TCE (Server POWERPC) IOMMU -------- */
1694  * @levels tells the maximum number of levels in multi-level IOMMU tables;
1715  * - VFIO_IOMMU_SPAPR_INFO_DDW: informs the userspace that dynamic DMA windows
1731  * - enable/disable EEH functionality;
1732  * - unfreeze IO/DMA for frozen PE;
1733  * - read PE state;
1734  * - reset PE;
1735  * - configure PE;
1736  * - inject EEH error.
1755 #define VFIO_EEH_PE_ENABLE		1	/* Enable EEH functionality  */
1756 #define VFIO_EEH_PE_UNFREEZE_IO		2	/* Enable IO for frozen PE   */
1757 #define VFIO_EEH_PE_UNFREEZE_DMA	3	/* Enable DMA for frozen PE  */
1773 …* VFIO_IOMMU_SPAPR_REGISTER_MEMORY - _IOW(VFIO_TYPE, VFIO_BASE + 17, struct vfio_iommu_spapr_regis…
1775  * Registers user space memory where DMA is allowed. It pins
1776  * user pages and does the locked memory accounting so
1789 …* VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY - _IOW(VFIO_TYPE, VFIO_BASE + 18, struct vfio_iommu_spapr_reg…
1791  * Unregisters user space memory registered with
1798 …* VFIO_IOMMU_SPAPR_TCE_CREATE - _IOWR(VFIO_TYPE, VFIO_BASE + 19, struct vfio_iommu_spapr_tce_creat…
1821  * VFIO_IOMMU_SPAPR_TCE_REMOVE - _IOW(VFIO_TYPE, VFIO_BASE + 20, struct vfio_iommu_spapr_tce_remove)