On 6/11/25 12:47, John Levon wrote:
Explicitly describe every parameter rather than summarizing.
Signed-off-by: John Levon <john.le...@nutanix.com>
Reviewed-by: Cédric Le Goater <c...@redhat.com>
Applied to vfio-next.
Thanks,
C.
---
include/hw/vfio/vfio-device.h | 52 +++++++++++++++++++++++++++++------
1 file changed, 43 insertions(+), 9 deletions(-)
diff --git a/include/hw/vfio/vfio-device.h b/include/hw/vfio/vfio-device.h
index f39259406b..d45e5a68a2 100644
--- a/include/hw/vfio/vfio-device.h
+++ b/include/hw/vfio/vfio-device.h
@@ -168,14 +168,25 @@ struct VFIODeviceIOOps {
* @device_feature
*
* Fill in feature info for the given device.
+ *
+ * @vdev: #VFIODevice to use
+ * @feat: feature information to fill in
+ *
+ * Returns 0 on success or -errno.
*/
- int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *);
+ int (*device_feature)(VFIODevice *vdev, struct vfio_device_feature *feat);
/**
* @get_region_info
*
- * Fill in @info (and optionally @fd) with information on the region given
- * by @info->index.
+ * Get the information for a given region on the device.
+ *
+ * @vdev: #VFIODevice to use
+ * @info: set @info->index to the region index to look up; the rest of the
+ * struct will be filled in on success
+ * @fd: pointer to the fd for the region; will be -1 if not found
+ *
+ * Returns 0 on success or -errno.
*/
int (*get_region_info)(VFIODevice *vdev,
struct vfio_region_info *info, int *fd);
@@ -183,22 +194,38 @@ struct VFIODeviceIOOps {
/**
* @get_irq_info
*
- * Fill in @irq with information on the IRQ given by @info->index.
+ * @vdev: #VFIODevice to use
+ * @irq: set @irq->index to the IRQ index to look up; the rest of the
struct
+ * will be filled in on success
+ *
+ * Returns 0 on success or -errno.
*/
int (*get_irq_info)(VFIODevice *vdev, struct vfio_irq_info *irq);
/**
* @set_irqs
*
- * Configure IRQs as defined by @irqs.
+ * Configure IRQs.
+ *
+ * @vdev: #VFIODevice to use
+ * @irqs: IRQ configuration as defined by VFIO docs.
+ *
+ * Returns 0 on success or -errno.
*/
int (*set_irqs)(VFIODevice *vdev, struct vfio_irq_set *irqs);
/**
* @region_read
*
- * Read @size bytes from the region @nr at offset @off into the buffer
- * @data.
+ * Read part of a region.
+ *
+ * @vdev: #VFIODevice to use
+ * @nr: region index
+ * @off: offset within the region
+ * @size: size in bytes to read
+ * @data: buffer to read into
+ *
+ * Returns number of bytes read on success or -errno.
*/
int (*region_read)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t size,
void *data);
@@ -206,8 +233,15 @@ struct VFIODeviceIOOps {
/**
* @region_write
*
- * Write @size bytes to the region @nr at offset @off from the buffer
- * @data; if @post, the write is posted.
+ * Write part of a region.
+ *
+ * @vdev: #VFIODevice to use
+ * @nr: region index
+ * @off: offset within the region
+ * @size: size in bytes to write
+ * @data: buffer to write from
+ *
+ * Returns number of bytes write on success or -errno.
*/
int (*region_write)(VFIODevice *vdev, uint8_t nr, off_t off, uint32_t
size,
void *data, bool post);
