On Thu, 2 Feb 2023 00:02:01 -0800
Yi Liu <yi.l.liu@xxxxxxxxx> wrote:
> this imports the latest vfio_device_ops definition to vfio.rst.
>
> Signed-off-by: Yi Liu <yi.l.liu@xxxxxxxxx>
> ---
> Documentation/driver-api/vfio.rst | 71 +++++++++++++++++++++----------
> 1 file changed, 48 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst
> index c663b6f97825..10d84f01fda1 100644
> --- a/Documentation/driver-api/vfio.rst
> +++ b/Documentation/driver-api/vfio.rst
> @@ -249,19 +249,22 @@ VFIO bus driver API
>
> VFIO bus drivers, such as vfio-pci make use of only a few interfaces
> into VFIO core. When devices are bound and unbound to the driver,
> -the driver should call vfio_register_group_dev() and
> -vfio_unregister_group_dev() respectively::
> +the driver should call vfio_register_group_dev() or
> +vfio_register_emulated_iommu_dev() and vfio_unregister_group_dev()
> +respectively::
>
> - void vfio_init_group_dev(struct vfio_device *device,
> - struct device *dev,
> - const struct vfio_device_ops *ops);
> - void vfio_uninit_group_dev(struct vfio_device *device);
> int vfio_register_group_dev(struct vfio_device *device);
> + int vfio_register_emulated_iommu_dev(struct vfio_device *device);
> void vfio_unregister_group_dev(struct vfio_device *device);
>
> The driver should embed the vfio_device in its own structure and call
> -vfio_init_group_dev() to pre-configure it before going to registration
> -and call vfio_uninit_group_dev() after completing the un-registration.
> +vfio_alloc_device() or _vfio_alloc_device() to allocate the structure,
AIUI, _vfio_alloc_device() is only exported because it's used by
vfio_alloc_device() which is a macro. I don't think we want to list
_vfio_alloc_device() as an equal alternative, if anything we should
discourage any direct use.
> +and can register @init/@release callbacks to manage any private state
> +wrapping the vfio_device.
> +
> + vfio_alloc_device(dev_struct, member, dev, ops);
> + void vfio_put_device(struct vfio_device *device);
> +
> vfio_register_group_dev() indicates to the core to begin tracking the
> iommu_group of the specified dev and register the dev as owned by a VFIO bus
> driver. Once vfio_register_group_dev() returns it is possible for userspace to
> @@ -270,28 +273,50 @@ ready before calling it. The driver provides an ops structure for callbacks
> similar to a file operations structure::
>
> struct vfio_device_ops {
> - int (*open)(struct vfio_device *vdev);
> + 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);
> + 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 size, 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);
> - };
> + 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() call above. This allows the bus driver
> -to obtain its private data using container_of(). The open/release
> -callbacks are issued when a new file descriptor is created for a
> -device (via VFIO_GROUP_GET_DEVICE_FD). The ioctl interface provides
> -a direct pass through for VFIO_DEVICE_* ioctls. The read/write/mmap
> -interfaces implement the device region access defined by the device's
> -own VFIO_DEVICE_GET_REGION_INFO ioctl.
> -
> +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 in the drivers's structure allocation
drivers' is the possessive of plural drivers. Thanks,
Alex
> + and put.
> +- The open/close_device callbacks are issued when a new file descriptor is
> + created for a device (via VFIO_GROUP_GET_DEVICE_FD).
> +- The ioctl interface provides a direct pass through for VFIO_DEVICE_* ioctls.
> +- The [un]bind_iommufd callbacks are issued when the device is bound to iommufd.
> + 'unbound' is implied if iommufd is being used.
> +- The attach_ioas callback is issued when the device is attached to an IOAS
> + managed by the bound iommufd. The attached IOAS is automatically detached
> + when the device is unbound from the iommufd.
> +- The read/write/mmap interfaces 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.
> +- The dma_unmap callback is issued when a range of iova's are unmapped in
> + the container or IOAS attached by the device. Drivers which care about
> + DMA unmap can implement this callback and must tolerate receiving unmap
> + notifications before the device is opened.
>
> PPC64 sPAPR implementation note
> -------------------------------
