* [PATCH vhost 1/3] vdpa: address kdoc warnings
2023-03-31 8:56 [PATCH vhost 0/3] vhost: minor kdoc fixes and MAINTAINERS update Simon Horman
@ 2023-03-31 8:56 ` Simon Horman
2023-03-31 9:17 ` Jason Wang
2023-03-31 8:56 ` [PATCH vhost 2/3] vringh: " Simon Horman
2023-03-31 8:56 ` [PATCH vhost 3/3] MAINTAINERS: add vringh.h to Virtio Core and Net Drivers Simon Horman
2 siblings, 1 reply; 6+ messages in thread
From: Simon Horman @ 2023-03-31 8:56 UTC (permalink / raw)
To: Michael S. Tsirkin, Jason Wang
Cc: Eli Cohen, Si-Wei Liu, Xie Yongji, Parav Pandit, kvm,
virtualization, netdev
This patch addresses the following minor kdoc problems.
* Incorrect spelling of 'callback' and 'notification'
* Unrecognised kdoc format for 'struct vdpa_map_file'
* Missing documentation of 'get_vendor_vq_stats' member of
'struct vdpa_config_ops'
* Missing documentation of 'max_supported_vqs' and 'supported_features'
members of 'struct vdpa_mgmt_dev'
Most of these problems were flagged by:
$ ./scripts/kernel-doc -Werror -none include/linux/vdpa.h
include/linux/vdpa.h:20: warning: expecting prototype for struct vdpa_calllback. Prototype was for struct vdpa_callback instead
include/linux/vdpa.h:117: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
* Corresponding file area for device memory mapping
include/linux/vdpa.h:357: warning: Function parameter or member 'get_vendor_vq_stats' not described in 'vdpa_config_ops'
include/linux/vdpa.h:518: warning: Function parameter or member 'supported_features' not described in 'vdpa_mgmt_dev'
include/linux/vdpa.h:518: warning: Function parameter or member 'max_supported_vqs' not described in 'vdpa_mgmt_dev'
The misspelling of 'notification' was flagged by:
$ ./scripts/checkpatch.pl --codespell --showfile --strict -f include/linux/vdpa.h
include/linux/vdpa.h:171: CHECK: 'notifcation' may be misspelled - perhaps 'notification'?
...
Signed-off-by: Simon Horman <horms@kernel.org>
---
include/linux/vdpa.h | 14 +++++++++++---
1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/include/linux/vdpa.h b/include/linux/vdpa.h
index 43f59ef10cc9..010321945997 100644
--- a/include/linux/vdpa.h
+++ b/include/linux/vdpa.h
@@ -10,7 +10,7 @@
#include <linux/if_ether.h>
/**
- * struct vdpa_calllback - vDPA callback definition.
+ * struct vdpa_callback - vDPA callback definition.
* @callback: interrupt callback function
* @private: the data passed to the callback function
*/
@@ -114,7 +114,7 @@ struct vdpa_dev_set_config {
};
/**
- * Corresponding file area for device memory mapping
+ * struct vdpa_map_file - file area for device memory mapping
* @file: vma->vm_file for the mapping
* @offset: mapping offset in the vm_file
*/
@@ -165,10 +165,16 @@ struct vdpa_map_file {
* @vdev: vdpa device
* @idx: virtqueue index
* @state: pointer to returned state (last_avail_idx)
+ * @get_vendor_vq_stats: Get the vendor statistics of a device.
+ * @vdev: vdpa device
+ * @idx: virtqueue index
+ * @msg: socket buffer holding stats message
+ * @extack: extack for reporting error messages
+ * Returns integer: success (0) or error (< 0)
* @get_vq_notification: Get the notification area for a virtqueue (optional)
* @vdev: vdpa device
* @idx: virtqueue index
- * Returns the notifcation area
+ * Returns the notification area
* @get_vq_irq: Get the irq number of a virtqueue (optional,
* but must implemented if require vq irq offloading)
* @vdev: vdpa device
@@ -506,6 +512,8 @@ struct vdpa_mgmtdev_ops {
* @config_attr_mask: bit mask of attributes of type enum vdpa_attr that
* management device support during dev_add callback
* @list: list entry
+ * @supported_features: features supported by device
+ * @max_supported_vqs: maximum number of virtqueues supported by device
*/
struct vdpa_mgmt_dev {
struct device *device;
--
2.30.2
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH vhost 1/3] vdpa: address kdoc warnings
2023-03-31 8:56 ` [PATCH vhost 1/3] vdpa: address kdoc warnings Simon Horman
@ 2023-03-31 9:17 ` Jason Wang
0 siblings, 0 replies; 6+ messages in thread
From: Jason Wang @ 2023-03-31 9:17 UTC (permalink / raw)
To: Simon Horman
Cc: Michael S. Tsirkin, Eli Cohen, Si-Wei Liu, Xie Yongji,
Parav Pandit, kvm, virtualization, netdev
On Fri, Mar 31, 2023 at 4:58 PM Simon Horman <horms@kernel.org> wrote:
>
> This patch addresses the following minor kdoc problems.
>
> * Incorrect spelling of 'callback' and 'notification'
> * Unrecognised kdoc format for 'struct vdpa_map_file'
> * Missing documentation of 'get_vendor_vq_stats' member of
> 'struct vdpa_config_ops'
> * Missing documentation of 'max_supported_vqs' and 'supported_features'
> members of 'struct vdpa_mgmt_dev'
>
> Most of these problems were flagged by:
>
> $ ./scripts/kernel-doc -Werror -none include/linux/vdpa.h
> include/linux/vdpa.h:20: warning: expecting prototype for struct vdpa_calllback. Prototype was for struct vdpa_callback instead
> include/linux/vdpa.h:117: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> * Corresponding file area for device memory mapping
> include/linux/vdpa.h:357: warning: Function parameter or member 'get_vendor_vq_stats' not described in 'vdpa_config_ops'
> include/linux/vdpa.h:518: warning: Function parameter or member 'supported_features' not described in 'vdpa_mgmt_dev'
> include/linux/vdpa.h:518: warning: Function parameter or member 'max_supported_vqs' not described in 'vdpa_mgmt_dev'
>
> The misspelling of 'notification' was flagged by:
> $ ./scripts/checkpatch.pl --codespell --showfile --strict -f include/linux/vdpa.h
> include/linux/vdpa.h:171: CHECK: 'notifcation' may be misspelled - perhaps 'notification'?
> ...
>
> Signed-off-by: Simon Horman <horms@kernel.org>
Acked-by: Jason Wang <jasowang@redhat.com>
Thanks
> ---
> include/linux/vdpa.h | 14 +++++++++++---
> 1 file changed, 11 insertions(+), 3 deletions(-)
>
> diff --git a/include/linux/vdpa.h b/include/linux/vdpa.h
> index 43f59ef10cc9..010321945997 100644
> --- a/include/linux/vdpa.h
> +++ b/include/linux/vdpa.h
> @@ -10,7 +10,7 @@
> #include <linux/if_ether.h>
>
> /**
> - * struct vdpa_calllback - vDPA callback definition.
> + * struct vdpa_callback - vDPA callback definition.
> * @callback: interrupt callback function
> * @private: the data passed to the callback function
> */
> @@ -114,7 +114,7 @@ struct vdpa_dev_set_config {
> };
>
> /**
> - * Corresponding file area for device memory mapping
> + * struct vdpa_map_file - file area for device memory mapping
> * @file: vma->vm_file for the mapping
> * @offset: mapping offset in the vm_file
> */
> @@ -165,10 +165,16 @@ struct vdpa_map_file {
> * @vdev: vdpa device
> * @idx: virtqueue index
> * @state: pointer to returned state (last_avail_idx)
> + * @get_vendor_vq_stats: Get the vendor statistics of a device.
> + * @vdev: vdpa device
> + * @idx: virtqueue index
> + * @msg: socket buffer holding stats message
> + * @extack: extack for reporting error messages
> + * Returns integer: success (0) or error (< 0)
> * @get_vq_notification: Get the notification area for a virtqueue (optional)
> * @vdev: vdpa device
> * @idx: virtqueue index
> - * Returns the notifcation area
> + * Returns the notification area
> * @get_vq_irq: Get the irq number of a virtqueue (optional,
> * but must implemented if require vq irq offloading)
> * @vdev: vdpa device
> @@ -506,6 +512,8 @@ struct vdpa_mgmtdev_ops {
> * @config_attr_mask: bit mask of attributes of type enum vdpa_attr that
> * management device support during dev_add callback
> * @list: list entry
> + * @supported_features: features supported by device
> + * @max_supported_vqs: maximum number of virtqueues supported by device
> */
> struct vdpa_mgmt_dev {
> struct device *device;
>
> --
> 2.30.2
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH vhost 2/3] vringh: address kdoc warnings
2023-03-31 8:56 [PATCH vhost 0/3] vhost: minor kdoc fixes and MAINTAINERS update Simon Horman
2023-03-31 8:56 ` [PATCH vhost 1/3] vdpa: address kdoc warnings Simon Horman
@ 2023-03-31 8:56 ` Simon Horman
2023-03-31 8:56 ` [PATCH vhost 3/3] MAINTAINERS: add vringh.h to Virtio Core and Net Drivers Simon Horman
2 siblings, 0 replies; 6+ messages in thread
From: Simon Horman @ 2023-03-31 8:56 UTC (permalink / raw)
To: Michael S. Tsirkin, Jason Wang
Cc: Eli Cohen, Si-Wei Liu, Xie Yongji, Parav Pandit, kvm,
virtualization, netdev
Address some minor kdoc warnings in vring.h.
* Place kdoc for 'struct vringh_config_ops' immediately before the structure
* Add missing documentation of members of 'vringh_iov' and 'vringh_kiov'
Warnings flagged by:
$ ./scripts/kernel-doc -none include/linux/vringh.h
include/linux/vringh.h:68: error: Cannot parse struct or union!
include/linux/vringh.h:92: warning: Function parameter or member 'iov' not described in 'vringh_iov'
include/linux/vringh.h:92: warning: Function parameter or member 'consumed' not described in 'vringh_iov'
include/linux/vringh.h:92: warning: Function parameter or member 'i' not described in 'vringh_iov'
include/linux/vringh.h:92: warning: Function parameter or member 'used' not described in 'vringh_iov'
include/linux/vringh.h:92: warning: Function parameter or member 'max_num' not described in 'vringh_iov'
include/linux/vringh.h:104: warning: Function parameter or member 'iov' not described in 'vringh_kiov'
include/linux/vringh.h:104: warning: Function parameter or member 'consumed' not described in 'vringh_kiov'
include/linux/vringh.h:104: warning: Function parameter or member 'i' not described in 'vringh_kiov'
include/linux/vringh.h:104: warning: Function parameter or member 'used' not described in 'vringh_kiov'
include/linux/vringh.h:104: warning: Function parameter or member 'max_num' not described in 'vringh_kiov'
Signed-off-by: Simon Horman <horms@kernel.org>
---
include/linux/vringh.h | 17 +++++++++++++++--
1 file changed, 15 insertions(+), 2 deletions(-)
diff --git a/include/linux/vringh.h b/include/linux/vringh.h
index 1991a02c6431..9f3e7012a255 100644
--- a/include/linux/vringh.h
+++ b/include/linux/vringh.h
@@ -54,6 +54,9 @@ struct vringh {
void (*notify)(struct vringh *);
};
+struct virtio_device;
+typedef void vrh_callback_t(struct virtio_device *, struct vringh *);
+
/**
* struct vringh_config_ops - ops for creating a host vring from a virtio driver
* @find_vrhs: find the host vrings and instantiate them
@@ -65,8 +68,6 @@ struct vringh {
* Returns 0 on success or error status
* @del_vrhs: free the host vrings found by find_vrhs().
*/
-struct virtio_device;
-typedef void vrh_callback_t(struct virtio_device *, struct vringh *);
struct vringh_config_ops {
int (*find_vrhs)(struct virtio_device *vdev, unsigned nhvrs,
struct vringh *vrhs[], vrh_callback_t *callbacks[]);
@@ -81,6 +82,12 @@ struct vringh_range {
/**
* struct vringh_iov - iovec mangler.
+ * @iov: array of iovecs to operate on
+ * @consumed: number of bytes consumed within iov[i]
+ * @i: index of current iovec
+ * @used: number of iovecs present in @iov
+ * @max_num: maximum number of iovecs.
+ * corresponds to allocated memory of @iov
*
* Mangles iovec in place, and restores it.
* Remaining data is iov + i, of used - i elements.
@@ -93,6 +100,12 @@ struct vringh_iov {
/**
* struct vringh_kiov - kvec mangler.
+ * @iov: array of iovecs to operate on
+ * @consumed: number of bytes consumed within iov[i]
+ * @i: index of current iovec
+ * @used: number of iovecs present in @iov
+ * @max_num: maximum number of iovecs.
+ * corresponds to allocated memory of @iov
*
* Mangles kvec in place, and restores it.
* Remaining data is iov + i, of used - i elements.
--
2.30.2
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH vhost 3/3] MAINTAINERS: add vringh.h to Virtio Core and Net Drivers
2023-03-31 8:56 [PATCH vhost 0/3] vhost: minor kdoc fixes and MAINTAINERS update Simon Horman
2023-03-31 8:56 ` [PATCH vhost 1/3] vdpa: address kdoc warnings Simon Horman
2023-03-31 8:56 ` [PATCH vhost 2/3] vringh: " Simon Horman
@ 2023-03-31 8:56 ` Simon Horman
2023-03-31 9:18 ` Jason Wang
2 siblings, 1 reply; 6+ messages in thread
From: Simon Horman @ 2023-03-31 8:56 UTC (permalink / raw)
To: Michael S. Tsirkin, Jason Wang
Cc: Eli Cohen, Si-Wei Liu, Xie Yongji, Parav Pandit, kvm,
virtualization, netdev
vringh.h doesn't seem to belong to any section in MAINTAINERS.
Add it to Virtio Core and Net Drivers, which seems to be the most
appropriate section to me.
Signed-off-by: Simon Horman <horms@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 91201c2b8190..7cf548302c56 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -22095,6 +22095,7 @@ F: drivers/vdpa/
F: drivers/virtio/
F: include/linux/vdpa.h
F: include/linux/virtio*.h
+F: include/linux/vringh.h
F: include/uapi/linux/virtio_*.h
F: tools/virtio/
--
2.30.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH vhost 3/3] MAINTAINERS: add vringh.h to Virtio Core and Net Drivers
2023-03-31 8:56 ` [PATCH vhost 3/3] MAINTAINERS: add vringh.h to Virtio Core and Net Drivers Simon Horman
@ 2023-03-31 9:18 ` Jason Wang
0 siblings, 0 replies; 6+ messages in thread
From: Jason Wang @ 2023-03-31 9:18 UTC (permalink / raw)
To: Simon Horman
Cc: Michael S. Tsirkin, Eli Cohen, Si-Wei Liu, Xie Yongji,
Parav Pandit, kvm, virtualization, netdev
On Fri, Mar 31, 2023 at 4:59 PM Simon Horman <horms@kernel.org> wrote:
>
> vringh.h doesn't seem to belong to any section in MAINTAINERS.
> Add it to Virtio Core and Net Drivers, which seems to be the most
> appropriate section to me.
>
> Signed-off-by: Simon Horman <horms@kernel.org>
Acked-by: Jason Wang <jasowang@redhat.com>
Thanks
> ---
> MAINTAINERS | 1 +
> 1 file changed, 1 insertion(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 91201c2b8190..7cf548302c56 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -22095,6 +22095,7 @@ F: drivers/vdpa/
> F: drivers/virtio/
> F: include/linux/vdpa.h
> F: include/linux/virtio*.h
> +F: include/linux/vringh.h
> F: include/uapi/linux/virtio_*.h
> F: tools/virtio/
>
>
> --
> 2.30.2
>
^ permalink raw reply [flat|nested] 6+ messages in thread