virtio htmldoc comment fixes
Michael S. Tsirkin
maintainercover virtio htmldoc comment fixes
This fixes warnings reported by htmldoc as well as a couple of others I found while reading the code.
Jason, I found a bunch more issues with the map ops patches, like weird
/*
* XXX
*
*/
multiline comments, weirdly formatted return, inconsistent use of "the" for some parameters but not others.
Pls take a look and address.
Michael S. Tsirkin (8):
virtio: fix typo in virtio_device_ready() comment
virtio: fix whitespace in virtio_config_ops
virtio: fix grammar in virtio_queue_info docs
virtio: fix grammar in virtio_map_ops docs
virtio: standardize Returns documentation style
virtio: fix virtqueue_set_affinity() docs
virtio_ring: fix htmldoc warnings
virtio: fix map ops comment
drivers/virtio/virtio_ring.c | 3 ++- include/linux/virtio_config.h | 22 +++++++++++----------- 2 files changed, 13 insertions(+), 12 deletions(-)
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 1/8 virtio: fix typo in virtio_device_ready() comment
"coherenct" -> "coherent"
--- include/linux/virtio_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/virtio_config.h +1 -1
@@ -362,7 +362,7 @@ void virtio_device_ready(struct virtio_device *dev)* specific set_status() method. * * A well behaved device will only notify a virtqueue after -* DRIVER_OK, this means the device should "see" the coherenct +* DRIVER_OK, this means the device should "see" the coherent * memory write that set vq->broken as false which is done by * the driver when it sees DRIVER_OK, then the following * driver's vring_interrupt() will see vq->broken as false so
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 2/8 virtio: fix whitespace in virtio_config_ops
In reply to Michael S. TsirkinThe finalize_features documentation uses a tab between words. Use space instead.
--- include/linux/virtio_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/virtio_config.h +1 -1
@@ -86,7 +86,7 @@ struct virtqueue_info {* vdev: the virtio_device * This sends the driver feature bits to the device: it can change * the dev->feature bits if it wants. -* Note that despite the name this can be called any number of +* Note that despite the name this can be called any number of * times. * Returns 0 on success or error status * @bus_name: return the bus name associated with the device (optional)
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 3/8 virtio: fix grammar in virtio_queue_info docs
In reply to Michael S. TsirkinFix grammar in the description of @ctx
--- include/linux/virtio_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/virtio_config.h +1 -1
@@ -24,7 +24,7 @@ typedef void vq_callback_t(struct virtqueue *);* a virtqueue unused by the driver. * @callback: A callback to invoke on a used buffer notification. * NULL for a virtqueue that does not need a callback. -* @ctx: A flag to indicate to maintain an extra context per virtqueue. +* @ctx: whether to maintain an extra context per virtqueue. */ struct virtqueue_info {const char *name;
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 4/8 virtio: fix grammar in virtio_map_ops docs
In reply to Michael S. TsirkinFix grammar issues in the virtio_map_ops docs:
- missing article before "transport"
- "implements" -> "implement" to match subject
--- include/linux/virtio_config.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
include/linux/virtio_config.h +2 -2
@@ -141,8 +141,8 @@ struct virtio_config_ops {/** * struct virtio_map_ops - operations for mapping buffer for a virtio device -* Note: For transport that has its own mapping logic it must -* implements all of the operations +* Note: For a transport that has its own mapping logic it must +* implement all of the operations * @map_page: map a buffer to the device * map: metadata for performing mapping * page: the page that will be mapped by the device
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 5/8 virtio: standardize Returns documentation style
In reply to Michael S. TsirkinRemove colons after "Returns" in virtio_map_ops function documentation - both to avoid triggering an htmldoc warning and for consistency with virtio_config_ops.
This affects map_page, alloc, need_sync, and max_mapping_size.
--- include/linux/virtio_config.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
include/linux/virtio_config.h +4 -4
@@ -150,7 +150,7 @@ struct virtio_config_ops {* size: the buffer size * dir: mapping direction * attrs: mapping attributes -* Returns: the mapped address +* Returns the mapped address * @unmap_page: unmap a buffer from the device * map: device specific mapping map * map_handle: the mapped address
@@ -172,7 +172,7 @@ struct virtio_config_ops {* size: the size of the buffer * map_handle: the mapping address to sync * gfp: allocation flag (GFP_XXX) -* Returns: virtual address of the allocated buffer +* Returns virtual address of the allocated buffer * @free: free a coherent buffer mapping * map: metadata for performing mapping * size: the size of the buffer
@@ -182,13 +182,13 @@ struct virtio_config_ops {* @need_sync: if the buffer needs synchronization * map: metadata for performing mapping * map_handle: the mapped address -* Returns: whether the buffer needs synchronization +* Returns whether the buffer needs synchronization * @mapping_error: if the mapping address is error * map: metadata for performing mapping * map_handle: the mapped address * @max_mapping_size: get the maximum buffer size that can be mapped * map: metadata for performing mapping -* Returns: the maximum buffer size that can be mapped +* Returns the maximum buffer size that can be mapped */ struct virtio_map_ops { dma_addr_t (*map_page)(union virtio_map map, struct page *page,
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 6/8 virtio: fix virtqueue_set_affinity() docs
In reply to Michael S. TsirkinRewrite the comment for better grammar and clarity.
--- include/linux/virtio_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/virtio_config.h +1 -1
@@ -384,7 +384,7 @@ const char *virtio_bus_name(struct virtio_device *vdev)* @vq: the virtqueue * @cpu_mask: the cpu mask * -* Pay attention the function are best-effort: the affinity hint may not be set +* Note that this function is best-effort: the affinity hint may not be set * due to config support, irq type and sharing. * */
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 7/8 virtio_ring: fix htmldoc warnings
In reply to Michael S. TsirkinWe get:
drivers/virtio/virtio_ring.c:3174 - Missing parameter description for vaddr in virtqueue_map_free_coherent() drivers/virtio/virtio_ring.c:3308 - Documentation mismatch: expecting prototype for virtqueue_mapping_error() but the actual
Fix these.
--- drivers/virtio/virtio_ring.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
drivers/virtio/virtio_ring.c +2 -1
@@ -3166,6 +3166,7 @@ EXPORT_SYMBOL_GPL(virtqueue_map_alloc_coherent);* @vdev: the virtio device we are talking to * @map: metadata for performing mapping * @size: the size of the buffer +* @vaddr: virtual address of the buffer * @map_handle: the mapped address that needs to be freed * */
@@ -3299,7 +3300,7 @@ void virtqueue_unmap_single_attrs(const struct virtqueue *_vq,EXPORT_SYMBOL_GPL (virtqueue_unmap_single_attrs);/** -* virtqueue_mapping_error - check dma address +* virtqueue_map_mapping_error - check dma address * @_vq: the struct virtqueue we're talking about. * @addr: DMA address *
Signature · 1 line
MST
Michael S. Tsirkin
maintainerPATCH 8/8 virtio: fix map ops comment
In reply to Michael S. Tsirkin@free will free the map handle not sync it. Fix the doc to match.
--- include/linux/virtio_config.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/virtio_config.h +1 -1
@@ -177,7 +177,7 @@ struct virtio_config_ops {* map: metadata for performing mapping * size: the size of the buffer * vaddr: virtual address of the buffer -* map_handle: the mapping address to sync +* map_handle: the mapping address that needs to be freed * attrs: unmapping attributes * @need_sync: if the buffer needs synchronization * map: metadata for performing mapping
Signature · 1 line
MST
Quoted 5 lines · Michael S. Tsirkin
This fixes warnings reported by htmldoc as well as a couple of others I found while reading the code.
Jason, I found a bunch more issues with the map ops patches, like weird
Thanks.
Quoted 10 lines
/*
* XXX
*
*/multiline comments, weirdly formatted return, inconsistent use of "the" for some parameters but not others.
Pls take a look and address.
Quoted 18 lines
Michael S. Tsirkin (8):
virtio: fix typo invirtio_device_ready()comment
virtio: fix whitespace invirtio_config_ops
virtio: fix grammar invirtio_queue_infodocs
virtio: fix grammar invirtio_map_opsdocs
virtio: standardize Returns documentation style
virtio: fixvirtqueue_set_affinity()docs
virtio_ring: fix htmldoc warnings
virtio: fix map ops commentdrivers/virtio/virtio_ring.c | 3 ++- include/linux/virtio_config.h | 22 +++++++++++----------- 2 files changed, 13 insertions(+), 12 deletions(-)--
MST