> From: lkp <lkp@xxxxxxxxx> > Sent: Saturday, February 4, 2023 4:56 PM > > Hi Yi, > > Thank you for the patch! Perhaps something to improve: > > [auto build test WARNING on awilliam-vfio/for-linus] > [also build test WARNING on linus/master v6.2-rc6 next-20230203] > [cannot apply to awilliam-vfio/next] > [If your patch is applied to the wrong git tree, kindly drop us a note. > And when submitting patch, we suggest to use '--base' as documented in > https://git-scm.com/docs/git-format-patch#_base_tree_information] > > url: https://github.com/intel-lab-lkp/linux/commits/Yi-Liu/vfio-Update- > the-kdoc-for-vfio_device_ops/20230203-163612 > base: https://github.com/awilliam/linux-vfio.git for-linus > patch link: https://lore.kernel.org/r/20230203083345.711443-3- > yi.l.liu%40intel.com > patch subject: [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest > interfaces > reproduce: > # https://github.com/intel-lab- > lkp/linux/commit/8db2c0d3414387502a6c743d6fa383cec960e3ba > git remote add linux-review https://github.com/intel-lab-lkp/linux > git fetch --no-tags linux-review Yi-Liu/vfio-Update-the-kdoc-for- > vfio_device_ops/20230203-163612 > git checkout 8db2c0d3414387502a6c743d6fa383cec960e3ba > make menuconfig > # enable CONFIG_COMPILE_TEST, > CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS > make htmldocs > > If you fix the issue, kindly add following tag where applicable > | Reported-by: kernel test robot <lkp@xxxxxxxxx> > > All warnings (new ones prefixed by >>): > > >> Documentation/driver-api/vfio.rst:264: WARNING: Inline emphasis start- > string without end-string. > >> Documentation/driver-api/vfio.rst:296: WARNING: Literal block ends > without a blank line; unexpected unindent. > >> Documentation/driver-api/vfio.rst:305: WARNING: Unexpected > indentation. > >> Documentation/driver-api/vfio.rst:306: WARNING: Block quote ends > without a blank line; unexpected unindent. > Hi Alex, An updated version to address comments in this mail. >From 6d9c6f9b3d10da2923b28d8cfbf5fdd39e5fd8aa Mon Sep 17 00:00:00 2001 From: Yi Liu <yi.l.liu@xxxxxxxxx> Date: Tue, 31 Jan 2023 06:16:50 -0800 Subject: [PATCH] docs: vfio: Update vfio.rst per latest interfaces 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 | 79 ++++++++++++++++++++++--------- 1 file changed, 57 insertions(+), 22 deletions(-) diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst index c663b6f97825..0bfa7261f991 100644 --- a/Documentation/driver-api/vfio.rst +++ b/Documentation/driver-api/vfio.rst @@ -249,19 +249,21 @@ 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:: +Following interfaces are called when devices are bound to and +unbound from the driver:: - 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. +The driver should embed the vfio_device in its own structure and use +vfio_alloc_device() to allocate the structure, 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 +272,61 @@ 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 when vfio_device is initialized + and released. + + - The open/close_device callbacks are issued when a new file descriptor + is created for a device (e.g. via VFIO_GROUP_GET_DEVICE_FD). + + - 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 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 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. + - 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 iova unmap can implement this callback and must tolerate receiving + unmap notifications before the device is opened. PPC64 sPAPR implementation note ------------------------------- -- 2.34.1
