* [PATCH v2 0/2] Update VFIO doc
@ 2023-02-03 8:33 Yi Liu
2023-02-03 8:33 ` [PATCH v2 1/2] vfio: Update the kdoc for vfio_device_ops Yi Liu
2023-02-03 8:33 ` [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces Yi Liu
0 siblings, 2 replies; 7+ messages in thread
From: Yi Liu @ 2023-02-03 8:33 UTC (permalink / raw)
To: alex.williamson, jgg
Cc: kevin.tian, chao.p.peng, eric.auger, yi.l.liu, yi.y.sun, kvm
Two updates for VFIO doc.
v2:
- Add Kevin's r-b for patch 0001
- Address comments from Alex and Kevin on the statements in patch 0002
v1: https://lore.kernel.org/kvm/20230202080201.338571-1-yi.l.liu@intel.com/
Regards,
Yi Liu
Yi Liu (2):
vfio: Update the kdoc for vfio_device_ops
docs: vfio: Update vfio.rst per latest interfaces
Documentation/driver-api/vfio.rst | 70 +++++++++++++++++++++----------
include/linux/vfio.h | 4 ++
2 files changed, 51 insertions(+), 23 deletions(-)
--
2.34.1
^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH v2 1/2] vfio: Update the kdoc for vfio_device_ops
2023-02-03 8:33 [PATCH v2 0/2] Update VFIO doc Yi Liu
@ 2023-02-03 8:33 ` Yi Liu
2023-02-03 8:33 ` [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces Yi Liu
1 sibling, 0 replies; 7+ messages in thread
From: Yi Liu @ 2023-02-03 8:33 UTC (permalink / raw)
To: alex.williamson, jgg
Cc: kevin.tian, chao.p.peng, eric.auger, yi.l.liu, yi.y.sun, kvm
this is missed when adding bind_iommufd/unbind_iommufd and attach_ioas.
Signed-off-by: Yi Liu <yi.l.liu@intel.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
---
include/linux/vfio.h | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/include/linux/vfio.h b/include/linux/vfio.h
index 35be78e9ae57..cc7685386b53 100644
--- a/include/linux/vfio.h
+++ b/include/linux/vfio.h
@@ -70,6 +70,10 @@ struct vfio_device {
*
* @init: initialize private fields in device structure
* @release: Reclaim private fields in device structure
+ * @bind_iommufd: Called when binding the device to an iommufd
+ * @unbind_iommufd: Opposite of bind_iommufd
+ * @attach_ioas: Called when attaching device to an IOAS/HWPT managed by the
+ * bound iommufd. Undo in unbind_iommufd.
* @open_device: Called when the first file descriptor is opened for this device
* @close_device: Opposite of open_device
* @read: Perform read(2) on device file descriptor
--
2.34.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces
2023-02-03 8:33 [PATCH v2 0/2] Update VFIO doc Yi Liu
2023-02-03 8:33 ` [PATCH v2 1/2] vfio: Update the kdoc for vfio_device_ops Yi Liu
@ 2023-02-03 8:33 ` Yi Liu
2023-02-04 8:56 ` kernel test robot
1 sibling, 1 reply; 7+ messages in thread
From: Yi Liu @ 2023-02-03 8:33 UTC (permalink / raw)
To: alex.williamson, jgg
Cc: kevin.tian, chao.p.peng, eric.auger, yi.l.liu, yi.y.sun, kvm
this imports the latest vfio_device_ops definition to vfio.rst.
Signed-off-by: Yi Liu <yi.l.liu@intel.com>
---
Documentation/driver-api/vfio.rst | 70 +++++++++++++++++++++----------
1 file changed, 47 insertions(+), 23 deletions(-)
diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst
index c663b6f97825..f38ab4ae1244 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.
+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,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 when vfio_device is initialized
+- and released.
+- 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
+- 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 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
-------------------------------
--
2.34.1
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces
2023-02-03 8:33 ` [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces Yi Liu
@ 2023-02-04 8:56 ` kernel test robot
2023-02-04 13:09 ` Liu, Yi L
0 siblings, 1 reply; 7+ messages in thread
From: kernel test robot @ 2023-02-04 8:56 UTC (permalink / raw)
To: Yi Liu, alex.williamson, jgg
Cc: oe-kbuild-all, kevin.tian, chao.p.peng, eric.auger, yi.l.liu,
yi.y.sun, kvm
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@intel.com>
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.
vim +264 Documentation/driver-api/vfio.rst
263
> 264 vfio_alloc_device(dev_struct, member, dev, ops);
265 void vfio_put_device(struct vfio_device *device);
266
267 vfio_register_group_dev() indicates to the core to begin tracking the
268 iommu_group of the specified dev and register the dev as owned by a VFIO bus
269 driver. Once vfio_register_group_dev() returns it is possible for userspace to
270 start accessing the driver, thus the driver should ensure it is completely
271 ready before calling it. The driver provides an ops structure for callbacks
272 similar to a file operations structure::
273
274 struct vfio_device_ops {
275 char *name;
276 int (*init)(struct vfio_device *vdev);
277 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);
284 ssize_t (*read)(struct vfio_device *vdev, char __user *buf,
285 size_t count, loff_t *ppos);
286 ssize_t (*write)(struct vfio_device *vdev, const char __user *buf,
287 size_t count, loff_t *size);
288 long (*ioctl)(struct vfio_device *vdev, unsigned int cmd,
289 unsigned long arg);
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);
> 296 };
297
298 Each function is passed the vdev that was originally registered
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 - The init/release callbacks are issued when vfio_device is initialized
303 - and released.
304 - The open/close_device callbacks are issued when a new file descriptor is
> 305 created for a device (via VFIO_GROUP_GET_DEVICE_FD).
> 306 - The ioctl interface provides a direct pass through for VFIO_DEVICE_* ioctls.
307 - The [un]bind_iommufd callbacks are issued when the device is bound to
308 - and unbound from iommufd.
309 - The attach_ioas callback is issued when the device is attached to an IOAS
310 managed by the bound iommufd. The attached IOAS is automatically detached
311 when the device is unbound from the iommufd.
312 - The read/write/mmap interfaces implement the device region access defined by
313 the device's own VFIO_DEVICE_GET_REGION_INFO ioctl.
314 - The request callback is issued when device is going to be unregistered.
315 - The dma_unmap callback is issued when a range of iova's are unmapped in
316 the container or IOAS attached by the device. Drivers which care about
317 DMA unmap can implement this callback and must tolerate receiving unmap
318 notifications before the device is opened.
319
--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests
^ permalink raw reply [flat|nested] 7+ messages in thread
* RE: [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces
2023-02-04 8:56 ` kernel test robot
@ 2023-02-04 13:09 ` Liu, Yi L
2023-02-04 14:26 ` Alex Williamson
0 siblings, 1 reply; 7+ messages in thread
From: Liu, Yi L @ 2023-02-04 13:09 UTC (permalink / raw)
To: lkp, alex.williamson, jgg
Cc: oe-kbuild-all, Tian, Kevin, chao.p.peng, eric.auger, yi.y.sun, kvm
> From: lkp <lkp@intel.com>
> 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@intel.com>
>
> 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@intel.com>
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@intel.com>
---
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces
2023-02-04 13:09 ` Liu, Yi L
@ 2023-02-04 14:26 ` Alex Williamson
2023-02-04 14:42 ` Liu, Yi L
0 siblings, 1 reply; 7+ messages in thread
From: Alex Williamson @ 2023-02-04 14:26 UTC (permalink / raw)
To: Liu, Yi L
Cc: lkp, jgg, oe-kbuild-all, Tian, Kevin, chao.p.peng, eric.auger,
yi.y.sun, kvm
On Sat, 4 Feb 2023 13:09:25 +0000
"Liu, Yi L" <yi.l.liu@intel.com> wrote:
> > From: lkp <lkp@intel.com>
> > 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@intel.com>
> >
> > 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.
Please send a v3 series. Thanks,
Alex
> From 6d9c6f9b3d10da2923b28d8cfbf5fdd39e5fd8aa Mon Sep 17 00:00:00 2001
> From: Yi Liu <yi.l.liu@intel.com>
> 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@intel.com>
> ---
> 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
> -------------------------------
^ permalink raw reply [flat|nested] 7+ messages in thread
* RE: [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces
2023-02-04 14:26 ` Alex Williamson
@ 2023-02-04 14:42 ` Liu, Yi L
0 siblings, 0 replies; 7+ messages in thread
From: Liu, Yi L @ 2023-02-04 14:42 UTC (permalink / raw)
To: Alex Williamson
Cc: lkp, jgg, oe-kbuild-all, Tian, Kevin, chao.p.peng, eric.auger,
yi.y.sun, kvm
> From: Alex Williamson <alex.williamson@redhat.com>
> Sent: Saturday, February 4, 2023 10:27 PM
>
> On Sat, 4 Feb 2023 13:09:25 +0000
> "Liu, Yi L" <yi.l.liu@intel.com> wrote:
>
> > > From: lkp <lkp@intel.com>
> > > 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@intel.com>
> > >
> > > 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.
>
> Please send a v3 series. Thanks,
done. 😊
Regards,
Yi Liu
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-02-04 14:43 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-03 8:33 [PATCH v2 0/2] Update VFIO doc Yi Liu
2023-02-03 8:33 ` [PATCH v2 1/2] vfio: Update the kdoc for vfio_device_ops Yi Liu
2023-02-03 8:33 ` [PATCH v2 2/2] docs: vfio: Update vfio.rst per latest interfaces Yi Liu
2023-02-04 8:56 ` kernel test robot
2023-02-04 13:09 ` Liu, Yi L
2023-02-04 14:26 ` Alex Williamson
2023-02-04 14:42 ` Liu, Yi L
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.