@@ -242,26 +242,28 @@ group and can access them as follows::
242242VFIO User API
243243-------------------------------------------------------------------------------
244244
245- Please see include/linux/vfio.h for complete API documentation.
245+ Please see include/uapi/ linux/vfio.h for complete API documentation.
246246
247247VFIO bus driver API
248248-------------------------------------------------------------------------------
249249
250250VFIO bus drivers, such as vfio-pci make use of only a few interfaces
251251into VFIO core. When devices are bound and unbound to the driver,
252- the driver should call vfio_register_group_dev() and
253- vfio_unregister_group_dev() respectively ::
252+ Following interfaces are called when devices are bound to and
253+ unbound from the driver ::
254254
255- void vfio_init_group_dev(struct vfio_device *device,
256- struct device *dev,
257- const struct vfio_device_ops *ops);
258- void vfio_uninit_group_dev(struct vfio_device *device);
259255 int vfio_register_group_dev(struct vfio_device *device);
256+ int vfio_register_emulated_iommu_dev(struct vfio_device *device);
260257 void vfio_unregister_group_dev(struct vfio_device *device);
261258
262- The driver should embed the vfio_device in its own structure and call
263- vfio_init_group_dev() to pre-configure it before going to registration
264- and call vfio_uninit_group_dev() after completing the un-registration.
259+ The driver should embed the vfio_device in its own structure and use
260+ vfio_alloc_device() to allocate the structure, and can register
261+ @init/@release callbacks to manage any private state wrapping the
262+ vfio_device::
263+
264+ vfio_alloc_device(dev_struct, member, dev, ops);
265+ void vfio_put_device(struct vfio_device *device);
266+
265267vfio_register_group_dev() indicates to the core to begin tracking the
266268iommu_group of the specified dev and register the dev as owned by a VFIO bus
267269driver. Once vfio_register_group_dev() returns it is possible for userspace to
@@ -270,28 +272,64 @@ ready before calling it. The driver provides an ops structure for callbacks
270272similar to a file operations structure::
271273
272274 struct vfio_device_ops {
273- int (*open)(struct vfio_device *vdev);
275+ char *name;
276+ int (*init)(struct vfio_device *vdev);
274277 void (*release)(struct vfio_device *vdev);
278+ int (*bind_iommufd)(struct vfio_device *vdev,
279+ struct iommufd_ctx *ictx, u32 *out_device_id);
280+ void (*unbind_iommufd)(struct vfio_device *vdev);
281+ int (*attach_ioas)(struct vfio_device *vdev, u32 *pt_id);
282+ int (*open_device)(struct vfio_device *vdev);
283+ void (*close_device)(struct vfio_device *vdev);
275284 ssize_t (*read)(struct vfio_device *vdev, char __user *buf,
276285 size_t count, loff_t *ppos);
277- ssize_t (*write)(struct vfio_device *vdev,
278- const char __user *buf,
279- size_t size, loff_t *ppos);
286+ ssize_t (*write)(struct vfio_device *vdev, const char __user *buf,
287+ size_t count, loff_t *size);
280288 long (*ioctl)(struct vfio_device *vdev, unsigned int cmd,
281289 unsigned long arg);
282- int (*mmap)(struct vfio_device *vdev,
283- struct vm_area_struct *vma);
290+ int (*mmap)(struct vfio_device *vdev, struct vm_area_struct *vma);
291+ void (*request)(struct vfio_device *vdev, unsigned int count);
292+ int (*match)(struct vfio_device *vdev, char *buf);
293+ void (*dma_unmap)(struct vfio_device *vdev, u64 iova, u64 length);
294+ int (*device_feature)(struct vfio_device *device, u32 flags,
295+ void __user *arg, size_t argsz);
284296 };
285297
286298Each function is passed the vdev that was originally registered
287- in the vfio_register_group_dev() call above. This allows the bus driver
288- to obtain its private data using container_of(). The open/release
289- callbacks are issued when a new file descriptor is created for a
290- device (via VFIO_GROUP_GET_DEVICE_FD). The ioctl interface provides
291- a direct pass through for VFIO_DEVICE_* ioctls. The read/write/mmap
292- interfaces implement the device region access defined by the device's
293- own VFIO_DEVICE_GET_REGION_INFO ioctl.
299+ in the vfio_register_group_dev() or vfio_register_emulated_iommu_dev()
300+ call above. This allows the bus driver to obtain its private data using
301+ container_of().
302+
303+ ::
304+
305+ - The init/release callbacks are issued when vfio_device is initialized
306+ and released.
307+
308+ - The open/close device callbacks are issued when the first
309+ instance of a file descriptor for the device is created (eg.
310+ via VFIO_GROUP_GET_DEVICE_FD) for a user session.
311+
312+ - The ioctl callback provides a direct pass through for some VFIO_DEVICE_*
313+ ioctls.
314+
315+ - The [un]bind_iommufd callbacks are issued when the device is bound to
316+ and unbound from iommufd.
317+
318+ - The attach_ioas callback is issued when the device is attached to an
319+ IOAS managed by the bound iommufd. The attached IOAS is automatically
320+ detached when the device is unbound from iommufd.
321+
322+ - The read/write/mmap callbacks implement the device region access defined
323+ by the device's own VFIO_DEVICE_GET_REGION_INFO ioctl.
324+
325+ - The request callback is issued when device is going to be unregistered,
326+ such as when trying to unbind the device from the vfio bus driver.
294327
328+ - The dma_unmap callback is issued when a range of iovas are unmapped
329+ in the container or IOAS attached by the device. Drivers which make
330+ use of the vfio page pinning interface must implement this callback in
331+ order to unpin pages within the dma_unmap range. Drivers must tolerate
332+ this callback even before calls to open_device().
295333
296334PPC64 sPAPR implementation note
297335-------------------------------
0 commit comments