1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
9  * it under the terms of the GNU General Public License version 2 as
30  * capability is subject to change as groups are added or removed.
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
54  * devices, so this capability is subject to change as groups are added or
61  * structure length (argsz) and flags into structures passed between
64  * As structure fields are added, argsz will increase to match and flag
78  * This field is only valid when the corresponding bit in the flags
80  * INFO buffer, as is the next field within each capability header.
100 /* -------- IOCTLs for VFIO file descriptor (/dev/vfio/vfio) -------- */
103  * VFIO_GET_API_VERSION - _IO(VFIO_TYPE, VFIO_BASE + 0)
114  * VFIO_CHECK_EXTENSION - _IOW(VFIO_TYPE, VFIO_BASE + 1, __u32)
123  * VFIO_SET_IOMMU - _IOW(VFIO_TYPE, VFIO_BASE + 2, __s32)
126  * iommu driver as verified by calling CHECK_EXTENSION using the same
130  * Return: 0 on success, -errno on failure
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.
148 	__u32	flags;  member
155  * VFIO_GROUP_SET_CONTAINER - _IOW(VFIO_TYPE, VFIO_BASE + 4, __s32)
163  * Return: 0 on success, -errno on failure.
169  * VFIO_GROUP_UNSET_CONTAINER - _IO(VFIO_TYPE, VFIO_BASE + 5)
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.
207 	__u32	flags;  member
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 */
227  * of the following corresponding to device flags in vfio_device_info structure.
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
247  * completion to the root bus with supported widths provided via flags.
252 	__u32 flags;  member
260  * VFIO_DEVICE_GET_REGION_INFO - _IOWR(VFIO_TYPE, VFIO_BASE + 8,
266  * intended to describe MMIO, I/O port, as well as bus specific
269  * Return: 0 on success, -errno on failure.
273 	__u32	flags;  member
289  * areas specified may fail (such as the range covering a PCI MSI-X table) or
312  * on the device, without needing to resort to static indexes, as done by
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.
322  * for VGA, but there are other upcoming use cases, such as opregions for Intel
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.
380  * The EDID blob has monitor information such as brand, name, serial
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 */
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
513  * The MASKABLE flags indicates the index supports MASK and UNMASK
522  * are setup as a set and new subindexes cannot be enabled without first
524  * and MSI-X where the driver may only use a subset of the available
526  * upfront.  In the case of MSI-X, where the user can enable MSI-X and
529  * down setup and incrementally increase the vectors as each is enabled.
536 	__u32	flags;  member
547  * VFIO_DEVICE_SET_IRQS - _IOW(VFIO_TYPE, VFIO_BASE + 10, struct vfio_irq_set)
553  * The DATA flags specify the type of data provided.  If DATA_NONE, the
556  * flags = (DATA_NONE|ACTION_UNMASK), index = 0, start = 0, count = 1.
560  * flags = (DATA_BOOL|ACTION_MASK), index = 0, start = 1, count = 3,
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
567  * flags = (DATA_EVENTFD|ACTION_TRIGGER), index = 0, start = 0, count = 3,
568  * data = {fd1, -1, fd2}
578  * can be disabled using the -1 value for DATA_EVENTFD or the index can be
579  * disabled as a whole with: flags = (DATA_NONE|ACTION_TRIGGER), count = 0.
581  * Note that ACTION_[UN]MASK specify user->kernel signaling (irqfds) while
582  * ACTION_TRIGGER specifies kernel->user signaling.
586 	__u32	flags;  member
607  * VFIO_DEVICE_RESET - _IO(VFIO_TYPE, VFIO_BASE + 11)
614  * The VFIO-PCI bus driver makes use of the following fixed region and
619 enum {
631 	 * as well as the MMIO range 0xa0000 to 0xbffff.  Each implemented
641 enum {
651  * The vfio-ccw bus driver makes use of the following fixed region and
656 enum {
661 enum {
669  * The vfio-ap bus driver makes use of the following IRQ index mapping.
672 enum {
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
694  *	- If the calling device is opened as a cdev, devid is reported.
701  *	     the cdev calling conventions do not support a proof-of-ownership
702  *	     model as provided in the legacy group interface.  In this case
706  *	     device, but belongs to the same IOMMU group as the calling device
716  *	  of VFIO_DEVICE_PCI_HOT_RESET ioctl outside of the proof-of-ownership
723  *	  length fd array on the calling device as the ownership is validated
726  * Return: 0 on success, -errno on failure:
727  *	-enospc = insufficient buffer, -enodev = unsupported for device.
734 #define VFIO_PCI_DEVID_NOT_OWNED	-1
743 	__u32	flags;  member
753  * VFIO_DEVICE_PCI_HOT_RESET - _IOW(VFIO_TYPE, VFIO_BASE + 13,
758  * ownership of the full set of affected devices as determined by the
766  * When called on a direct cdev opened vfio device, the flags field of
774  * Return: 0 on success, -errno on failure.
778 	__u32	flags;  member
786  * VFIO_DEVICE_QUERY_GFX_PLANE - _IOW(VFIO_TYPE, VFIO_BASE + 14,
789  * Set the drm_plane_type and flags, then retrieve the gfx plane info.
791  * flags supported:
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.
812 	__u32 flags;  member
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
843  * DEVICE_QUERY_GFX_PLANE as a token of the exposed guest framebuffer.
849  * VFIO_DEVICE_IOEVENTFD - _IOW(VFIO_TYPE, VFIO_BASE + 16,
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.
862 	__u32	flags;  member
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,
881  * using the FEATURE_MASK portion of the flags field.  Support for a feature
890  * Return 0 on success, -errno on failure.
894 	__u32	flags;  member
895 #define VFIO_DEVICE_FEATURE_MASK	(0xffff) /* 16-bit feature index */
905  * VFIO_DEVICE_BIND_IOMMUFD - _IOR(VFIO_TYPE, VFIO_BASE + 18,
908  * @flags:	 Must be 0.
920  * Return: 0 on success, -errno on failure.
924 	__u32		flags;  member
932  * VFIO_DEVICE_ATTACH_IOMMUFD_PT - _IOW(VFIO_TYPE, VFIO_BASE + 19,
935  * @flags:	Flags for attach.
942  *		VFIO_DEVICE_ATTACH_PASID is set in @flags
951  * This action, also known as a hw_pagetable replacement, will replace the
955  * Return: 0 on success, -errno on failure.
959 	__u32	flags;  member
968  * VFIO_DEVICE_DETACH_IOMMUFD_PT - _IOW(VFIO_TYPE, VFIO_BASE + 20,
971  * @flags:	Flags for detach.
973  *		VFIO_DEVICE_DETACH_PASID is set in @flags
979  * Return: 0 on success, -errno on failure.
983 	__u32	flags;  member
991  * Provide support for setting a PCI VF Token, which is used as a shared
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
1003  * indicated via the flags field; at least VFIO_MIGRATION_STOP_COPY must be
1019  * Other combinations of flags have behavior to be defined in the future.
1022 	__aligned_u64 flags;  member
1031  * device. The new state is supplied in device_state, see enum
1039  * ioctl as described above.
1045  * such as RUNNING or STOP.
1055  * device, data_fd will be -1.
1058 	__u32 device_state; /* From enum vfio_device_mig_state */
1064  * The device migration Finite State Machine is described by the enum
1067  * flow over the FD using read() and write() as discussed below.
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.
1099  * RESUMING -> STOP
1107  *   optionally go to the ERROR state as described below.
1109  *   While in STOP the device has the same behavior as other STOP states
1114  * PRE_COPY -> RUNNING
1115  * RUNNING_P2P -> RUNNING
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
1139  *   new data_fd. The migration driver may perform actions such as enabling
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
1156  *   While in the STOP_COPY state the device has the same behavior as STOP
1165  * STOP -> RESUMING
1173  * STOP_COPY -> PRE_COPY
1174  * STOP_COPY -> PRE_COPY_P2P
1180  * any -> ERROR
1181  *   ERROR cannot be specified as a device state, however any transition request
1190  * user context where peer-to-peer DMA between devices may be active. The
1196  * behave as though the device was fully running if not supported. Like while in
1200  * The remaining possible transitions are interpreted as combinations of the
1201  * above FSM arcs. As there are multiple paths through the FSM arcs the path
1203  *   - Select the shortest path.
1204  *   - The path cannot have saving group states as interior arcs, only
1223 enum vfio_device_mig_state {
1236  * VFIO_MIG_GET_PRECOPY_INFO - _IO(VFIO_TYPE, VFIO_BASE + 21)
1244  * return -EINVAL from any other migration state.
1252  * data available from the device. This field should have a non-zero initial
1253  * value and decrease as migration data is read from the device.
1258  * previously retrieved.  This field starts at zero and may increase as
1259  * the internal device state is modified or decrease as that modified
1263  * potential data size available during the PRE_COPY phases, as well as
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.
1288 	__u32 flags;  member
1297  * state with the platform-based power management.  Device use of lower power
1305  * state as necessary prior to the access.  Once the access is completed, the
1306  * device may re-enter the low power state.  For single shot low power support
1307  * with wake-up notification, see
1315  * This device feature has the same behavior as
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
1330  * state, as managed through the runtime power management core, will not
1343  * Upon VFIO_DEVICE_FEATURE_SET, disallow use of device low power states as
1377  * up if the above can't be achieved as of some driver limitations.
1411  *  bitmap[(addr - iova)/page_size] & (1ULL << (addr % 64))
1455  * but the in-band device interface lacks the support. Consequently, it is not
1456  * applicable to PCI devices, as bus master control for PCI devices is managed
1457  * in-band through the configuration space. At present, this feature is supported
1459  * When the device's BUS MASTER setting is configured as CLEAR, it will result in
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)
1483 	__u32	flags;  member
1493  * excluding any non-relaxable reserved regions exposed by
1531 	__u32	flags;  member
1554  * VFIO_IOMMU_MAP_DMA - _IOW(VFIO_TYPE, VFIO_BASE + 13, struct vfio_dma_map)
1559  * If flags & VFIO_DMA_MAP_FLAG_VADDR, update the base vaddr for iova. The vaddr
1562  * must address the same memory object as originally mapped.  Failure to do so
1565  * changed, and the READ & WRITE flags must be 0.
1569 	__u32	flags;  member
1587  * VFIO_IOMMU_UNMAP_DMA - _IOWR(VFIO_TYPE, VFIO_BASE + 14,
1598  * provide a struct vfio_bitmap in data[]. User must provide zero-allocated
1603  * pages in the range of unmapped size is returned in the user-provided
1606  * If flags & VFIO_DMA_UNMAP_FLAG_ALL, unmap all addresses.  iova and size
1607  * must be 0.  This cannot be combined with the get-dirty-bitmap flag.
1609  * If flags & VFIO_DMA_UNMAP_FLAG_VADDR, do not unmap, but invalidate host
1610  * virtual addresses in the iova range.  DMA to already-mapped pages continues.
1612  * This cannot be combined with the get-dirty-bitmap flag.
1616 	__u32	flags;  member
1635  * VFIO_IOMMU_DIRTY_PAGES - _IOWR(VFIO_TYPE, VFIO_BASE + 17,
1638  * Caller should set flag depending on which operation to perform, details as
1665  * Only one of the flags _START, _STOP and _GET may be specified at a time.
1670 	__u32        flags;  member
1685 /* -------- Additional API for SPAPR TCE (Server POWERPC) IOMMU -------- */
1694  * @levels tells the maximum number of levels in multi-level IOMMU tables;
1711  * addresses too so the window works as a filter rather than an offset
1714  * Flags supported:
1715  * - VFIO_IOMMU_SPAPR_INFO_DDW: informs the userspace that dynamic DMA windows
1720 	__u32 flags;  member
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.
1747 	__u32 flags;  member
1773 …* VFIO_IOMMU_SPAPR_REGISTER_MEMORY - _IOW(VFIO_TYPE, VFIO_BASE + 17, struct vfio_iommu_spapr_regis…
1782 	__u32	flags;  member
1789 …* VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY - _IOW(VFIO_TYPE, VFIO_BASE + 18, struct vfio_iommu_spapr_reg…
1798 …* VFIO_IOMMU_SPAPR_TCE_CREATE - _IOWR(VFIO_TYPE, VFIO_BASE + 19, struct vfio_iommu_spapr_tce_creat…
1808 	__u32 flags;  member
1821  * VFIO_IOMMU_SPAPR_TCE_REMOVE - _IOW(VFIO_TYPE, VFIO_BASE + 20, struct vfio_iommu_spapr_tce_remove)
1824  * It receives a PCI bus offset as a window id.
1828 	__u32 flags;  member