Documentation/driver-api/vfio.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/vfio.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/vfio.rst
Extension
.rst
Size
29342 bytes
Lines
708
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct vfio_device_ops {
		char	*name;
		int	(*init)(struct vfio_device *vdev);
		void	(*release)(struct vfio_device *vdev);
		int	(*bind_iommufd)(struct vfio_device *vdev,
					struct iommufd_ctx *ictx, u32 *out_device_id);
		void	(*unbind_iommufd)(struct vfio_device *vdev);
		int	(*attach_ioas)(struct vfio_device *vdev, u32 *pt_id);
		void	(*detach_ioas)(struct vfio_device *vdev);
		int	(*open_device)(struct vfio_device *vdev);
		void	(*close_device)(struct vfio_device *vdev);
		ssize_t	(*read)(struct vfio_device *vdev, char __user *buf,
				size_t count, loff_t *ppos);
		ssize_t	(*write)(struct vfio_device *vdev, const char __user *buf,
			 size_t count, loff_t *size);
		long	(*ioctl)(struct vfio_device *vdev, unsigned int cmd,
				 unsigned long arg);
		int	(*mmap)(struct vfio_device *vdev, struct vm_area_struct *vma);
		void	(*request)(struct vfio_device *vdev, unsigned int count);
		int	(*match)(struct vfio_device *vdev, char *buf);
		void	(*dma_unmap)(struct vfio_device *vdev, u64 iova, u64 length);
		int	(*device_feature)(struct vfio_device *device, u32 flags,
					  void __user *arg, size_t argsz);
	};

Each function is passed the vdev that was originally registered
in the vfio_register_group_dev() or vfio_register_emulated_iommu_dev()
call above. This allows the bus driver to obtain its private data using
container_of().

::

	- The init/release callbacks are issued when vfio_device is initialized
	  and released.

	- The open/close device callbacks are issued when the first
	  instance of a file descriptor for the device is created (eg.
	  via VFIO_GROUP_GET_DEVICE_FD) for a user session.

	- The ioctl callback provides a direct pass through for some VFIO_DEVICE_*
	  ioctls.

	- The [un]bind_iommufd callbacks are issued when the device is bound to
	  and unbound from iommufd.

	- The [de]attach_ioas callback is issued when the device is attached to
	  and detached from an IOAS managed by the bound iommufd. However, the
	  attached IOAS can also be automatically detached when the device is
	  unbound from iommufd.

	- The read/write/mmap callbacks implement the device region access defined
	  by the device's own VFIO_DEVICE_GET_REGION_INFO ioctl.

	- The request callback is issued when device is going to be unregistered,
	  such as when trying to unbind the device from the vfio bus driver.

	- The dma_unmap callback is issued when a range of iovas are unmapped
	  in the container or IOAS attached by the device. Drivers which make
	  use of the vfio page pinning interface must implement this callback in
	  order to unpin pages within the dma_unmap range. Drivers must tolerate
	  this callback even before calls to open_device().

PPC64 sPAPR implementation note
-------------------------------

This implementation has some specifics:

1) On older systems (POWER7 with P5IOC2/IODA1) only one IOMMU group per
   container is supported as an IOMMU table is allocated at the boot time,
   one table per a IOMMU group which is a Partitionable Endpoint (PE)

Annotation

Implementation Notes