Improve block layer function documentation
Subsystems (3)
cover Improve block layer function documentation
Hi Jens,
This is a series with eight patches that address source code comments. Most patches suppress kernel-doc warnings that appear when building with W=1. Please consider these patches.
Thanks,
Bart.
Bart Van Assche (8):
block/partitions/ldm: Convert a kernel-doc header into a
non-kernel-doc header
block: Convert blk_invalidate_devt() header into a non-kernel-doc
header
block: Fix throtl_pending_timer_fn() kernel-doc header
block: Fix blk_mq_*_map_queues() kernel-doc headers
block: Fix rq_qos_wait() kernel-doc header
block: Fix bsg_setup_queue() kernel-doc header
blk-mq: Fix spelling in a source code comment
blk-mq: Document the blk_mq_hw_queue_to_node() arguments
block/blk-mq-cpumap.c | 10 +++++++--- block/blk-mq-pci.c | 2 +- block/blk-mq-rdma.c | 4 ++-- block/blk-mq-virtio.c | 4 ++-- block/blk-rq-qos.c | 7 ++++--- block/blk-throttle.c | 2 +- block/bsg-lib.c | 1 + block/genhd.c | 4 ++-- block/partitions/ldm.c | 2 +- 9 files changed, 21 insertions(+), 15 deletions(-)
Signature · 1 line
2.22.0.rc1
PATCH 1/8 block/partitions/ldm: Convert a kernel-doc header into a non-kernel-doc header
This patch avoids that the kernel-doc tool warns about this function header when building with W=1.
--- block/partitions/ldm.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
block/partitions/ldm.c +1 -1
@@ -19,7 +19,7 @@#include "check.h" #include "msdos.h" -/** +/* * ldm_debug/info/error/crit - Output an error message * @f: A printf format string containing the message * @...: Variables to substitute into @f
Signature · 1 line
2.22.0.rc1
Re: [PATCH 1/8] block/partitions/ldm: Convert a kernel-doc header into a non-kernel-doc header
Looks good.
Quoted 22 lines · Bart Van Assche
This patch avoids that the kernel-doc tool warns about this function header when building with W=1.
Signed-off-by Bart Van Assche <[email protected]>--- block/partitions/ldm.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)block/partitions/ldm.c +1
-1@@ -19,7 +19,7 @@#include "check.h" #include "msdos.h" -/** +/* * ldm_debug/info/error/crit - Output an error message * @f: A printf format string containing the message * @...: Variables to substitute into @f
PATCH 2/8 block: Convert blk_invalidate_devt() header into a non-kernel-doc header
In reply to Bart Van AsscheThis patch avoids that the kernel-doc tool warns about this function header when building with W=1.
--- block/genhd.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
block/genhd.c +2 -2
@@ -532,8 +532,8 @@ void blk_free_devt(dev_t devt) } } -/** -* We invalidate devt by assigning NULL pointer for devt in idr. +/* +* We invalidate devt by assigning NULL pointer for devt in idr. */ void blk_invalidate_devt (dev_t devt) {
Signature · 1 line
2.22.0.rc1
Re: [PATCH 2/8] block: Convert blk_invalidate_devt() header into a non-kernel-doc header
Looks good.
Quoted 24 lines · Bart Van Assche
This patch avoids that the kernel-doc tool warns about this function header when building with W=1.
Signed-off-by Bart Van Assche <[email protected]>--- block/genhd.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)block/genhd.c +2
-2@@ -532,8 +532,8 @@ void blk_free_devt(dev_t devt) } } -/** -* We invalidate devt by assigning NULL pointer for devt in idr. +/* +* We invalidate devt by assigning NULL pointer for devt in idr. */ void blk_invalidate_devt (dev_t devt) {
PATCH 3/8 block: Fix throtl_pending_timer_fn() kernel-doc header
In reply to Bart Van AsscheCommit e99e88a9d2b0 renamed a function argument without updating the corresponding kernel-doc header. Update the kernel-doc header.
--- block/blk-throttle.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
block/blk-throttle.c +1 -1
@@ -1220,7 +1220,7 @@ static bool throtl_can_upgrade(struct throtl_data *td, struct throtl_grp *this_tg);/** * throtl_pending_timer_fn - timer function for service_queue->pending_timer -* @arg: the throtl_service_queue being serviced +* @t: the pending_timer member of the throtl_service_queue being serviced * * This timer is armed when a child throtl_grp with active bio's become * pending and queued on the service_queue's pending_tree and expires when
Signature · 1 line
2.22.0.rc1
Re: [PATCH 3/8] block: Fix throtl_pending_timer_fn() kernel-doc header
Looks good.
Quoted 24 lines · Bart Van Assche
Commit
e99e88a9d2b0renamed a function argument without updating the corresponding kernel-doc header. Update the kernel-doc header.Cc Kees Cook <[email protected]>Fixes e99e88a9d2b0 ("treewide: setup_timer() -> timer_setup()") # v4.15.Signed-off-by Bart Van Assche <[email protected]>--- block/blk-throttle.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)block/blk-throttle.c +1
-1@@ -1220,7 +1220,7 @@ static bool throtl_can_upgrade(struct throtl_data *td, struct throtl_grp *this_tg);/** * throtl_pending_timer_fn - timer function for service_queue->pending_timer -* @arg: the throtl_service_queue being serviced +* @t: the pending_timer member of the throtl_service_queue being serviced * * This timer is armed when a child throtl_grp with active bio's become * pending and queued on the service_queue's pending_tree and expires when
Re: [PATCH 3/8] block: Fix throtl_pending_timer_fn() kernel-doc header
In reply to Bart Van AsscheQuoted 6 lines · Bart Van Assche
Commit
e99e88a9d2b0renamed a function argument without updating the corresponding kernel-doc header. Update the kernel-doc header.Cc Kees Cook <[email protected]>Fixes e99e88a9d2b0 ("treewide: setup_timer() -> timer_setup()") # v4.15.Signed-off-by Bart Van Assche <[email protected]>
-Kees
Quoted 20 lines
--- block/blk-throttle.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)block/blk-throttle.c +1
-1@@ -1220,7 +1220,7 @@ static bool throtl_can_upgrade(struct throtl_data *td, struct throtl_grp *this_tg);/** * throtl_pending_timer_fn - timer function for service_queue->pending_timer -* @arg: the throtl_service_queue being serviced +* @t: the pending_timer member of the throtl_service_queue being serviced * * This timer is armed when a child throtl_grp with active bio's become * pending and queued on the service_queue's pending_tree and expires when Signature · 1 line
2.22.0.rc1
Signature · 1 line
Kees Cook
PATCH 4/8 block: Fix blk_mq_*_map_queues() kernel-doc headers
In reply to Bart Van AsscheThis patch avoids that the kernel-doc script complains about these function headers when building with W=1.
--- block/blk-mq-pci.c | 2 +- block/blk-mq-rdma.c | 4 ++-- block/blk-mq-virtio.c | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-)
block/blk-mq-pci.c +1 -1
@@ -13,7 +13,7 @@/** * blk_mq_pci_map_queues - provide a default queue mapping for PCI device -* @set: tagset to provide the mapping for +* @qmap: CPU to hardware queue map. * @pdev: PCI device associated with @set. * @offset: Offset to use for the pci irq vector *
block/blk-mq-rdma.c +2 -2
@@ -8,8 +8,8 @@/** * blk_mq_rdma_map_queues - provide a default queue mapping for rdma device -* @set: tagset to provide the mapping for -* @dev: rdma device associated with @set. +* @map: CPU to hardware queue map. +* @dev: rdma device to provide a mapping for. * @first_vec: first interrupt vectors to use for queues (usually 0) * * This function assumes the rdma device @dev has at least as many available
block/blk-mq-virtio.c +2 -2
@@ -11,8 +11,8 @@/** * blk_mq_virtio_map_queues - provide a default queue mapping for virtio device -* @set: tagset to provide the mapping for -* @vdev: virtio device associated with @set. +* @qmap: CPU to hardware queue map. +* @vdev: virtio device to provide a mapping for. * @first_vec: first interrupt vectors to use for queues (usually 0) * * This function assumes the virtio device @vdev has at least as many available
Signature · 1 line
2.22.0.rc1
Re: [PATCH 4/8] block: Fix blk_mq_*_map_queues() kernel-doc headers
Looks good.
Quoted 58 lines · Bart Van Assche
This patch avoids that the kernel-doc script complains about these function headers when building with W=1.
Cc Hannes Reinecke <[email protected]>Cc Keith Busch <[email protected]>Fixes ed76e329d74a ("blk-mq: abstract out queue map") # v5.0.Fixes e42b3867de4b ("blk-mq-rdma: pass in queue map to blk_mq_rdma_map_queues") # v5.0.Signed-off-by Bart Van Assche <[email protected]>--- block/blk-mq-pci.c | 2 +- block/blk-mq-rdma.c | 4 ++-- block/blk-mq-virtio.c | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-)block/blk-mq-pci.c +1
-1@@ -13,7 +13,7 @@/** * blk_mq_pci_map_queues - provide a default queue mapping for PCI device -* @set: tagset to provide the mapping for +* @qmap: CPU to hardware queue map. * @pdev: PCI device associated with @set. * @offset: Offset to use for the pci irq vector * block/blk-mq-rdma.c +2
-2@@ -8,8 +8,8 @@/** * blk_mq_rdma_map_queues - provide a default queue mapping for rdma device -* @set: tagset to provide the mapping for -* @dev: rdma device associated with @set. +* @map: CPU to hardware queue map. +* @dev: rdma device to provide a mapping for. * @first_vec: first interrupt vectors to use for queues (usually 0) * * This function assumes the rdma device @dev has at least as many available block/blk-mq-virtio.c +2
-2@@ -11,8 +11,8 @@/** * blk_mq_virtio_map_queues - provide a default queue mapping for virtio device -* @set: tagset to provide the mapping for -* @vdev: virtio device associated with @set. +* @qmap: CPU to hardware queue map. +* @vdev: virtio device to provide a mapping for. * @first_vec: first interrupt vectors to use for queues (usually 0) * * This function assumes the virtio device @vdev has at least as many available
PATCH 5/8 block: Fix rq_qos_wait() kernel-doc header
In reply to Bart Van AsscheAdd documentation for the @rqw argument and change " - " into ": ".
--- block/blk-rq-qos.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
block/blk-rq-qos.c +4 -3
@@ -209,9 +209,10 @@ static int rq_qos_wake_function(struct wait_queue_entry *curr,/** * rq_qos_wait - throttle on a rqw if we need to -* @private_data - caller provided specific data -* @acquire_inflight_cb - inc the rqw->inflight counter if we can -* @cleanup_cb - the callback to cleanup in case we race with a waker +* @rqw: rqw to throttle on +* @private_data: caller provided specific data +* @acquire_inflight_cb: inc the rqw->inflight counter if we can +* @cleanup_cb: the callback to cleanup in case we race with a waker * * This provides a uniform place for the rq_qos users to do their throttling. * Since you can end up with a lot of things sleeping at once, this manages the
Signature · 1 line
2.22.0.rc1
Re: [PATCH 5/8] block: Fix rq_qos_wait() kernel-doc header
Looks good.
Quoted 27 lines · Bart Van Assche
Add documentation for the @rqw argument and change " - " into ": ".
Fixes 84f603246db9 ("block: add rq_qos_wait to rq_qos") # v5.0-rc1~52^2~140.Signed-off-by Bart Van Assche <[email protected]>--- block/blk-rq-qos.c | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)block/blk-rq-qos.c +4
-3@@ -209,9 +209,10 @@ static int rq_qos_wake_function(struct wait_queue_entry *curr,/** * rq_qos_wait - throttle on a rqw if we need to -* @private_data - caller provided specific data -* @acquire_inflight_cb - inc the rqw->inflight counter if we can -* @cleanup_cb - the callback to cleanup in case we race with a waker +* @rqw: rqw to throttle on +* @private_data: caller provided specific data +* @acquire_inflight_cb: inc the rqw->inflight counter if we can +* @cleanup_cb: the callback to cleanup in case we race with a waker * * This provides a uniform place for the rq_qos users to do their throttling. * Since you can end up with a lot of things sleeping at once, this manages the
PATCH 6/8 block: Fix bsg_setup_queue() kernel-doc header
In reply to Bart Van AsscheDocument all bsg_setup_queue() arguments as required.
--- block/bsg-lib.c | 1 + 1 file changed, 1 insertion(+)
block/bsg-lib.c +1 -0
@@ -354,6 +354,7 @@ static const struct blk_mq_ops bsg_mq_ops = {* @dev: device to attach bsg device to * @name: device to give bsg device * @job_fn: bsg job handler +* @timeout: timeout handler function pointer * @dd_job_size: size of LLD data needed for each job */ struct request_queue *bsg_setup_queue(struct device *dev, const char *name,
Signature · 1 line
2.22.0.rc1
Re: [PATCH 6/8] block: Fix bsg_setup_queue() kernel-doc header
Looks good.
Quoted 21 lines · Bart Van Assche
Document all
bsg_setup_queue()arguments as required.Fixes aae3b069d5ce ("bsg: pass in desired timeout handler") # v5.0.Signed-off-by Bart Van Assche <[email protected]>--- block/bsg-lib.c | 1 + 1 file changed, 1 insertion(+)block/bsg-lib.c +1
-0@@ -354,6 +354,7 @@ static const struct blk_mq_ops bsg_mq_ops = {* @dev: device to attach bsg device to * @name: device to give bsg device * @job_fn: bsg job handler +* @timeout: timeout handler function pointer * @dd_job_size: size of LLD data needed for each job */ struct request_queue *bsg_setup_queue(struct device *dev, const char *name,
PATCH 7/8 blk-mq: Fix spelling in a source code comment
In reply to Bart Van AsscheChange one occurrence of 'performace' into 'performance'.
--- block/blk-mq-cpumap.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
block/blk-mq-cpumap.c +2 -2
@@ -42,8 +42,8 @@ int blk_mq_map_queues(struct blk_mq_queue_map *qmap)/* * First do sequential mapping between CPUs and queues. * In case we still have CPUs to map, and we have some number of -* threads per cores then map sibling threads to the same queue for -* performace optimizations. +* threads per cores then map sibling threads to the same queue +* for performance optimizations. */ if (cpu < nr_queues) { map[cpu] =cpu_to_queue_index (qmap, nr_queues, cpu);
Signature · 1 line
2.22.0.rc1
Re: [PATCH 7/8] blk-mq: Fix spelling in a source code comment
Looks good.
Quoted 25 lines · Bart Van Assche
Change one occurrence of 'performace' into 'performance'.
Cc Max Gurtovoy <[email protected]>Fixes fe631457ff3e ("blk-mq: map all HWQ also in hyperthreaded system") # v4.13.Signed-off-by Bart Van Assche <[email protected]>--- block/blk-mq-cpumap.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)block/blk-mq-cpumap.c +2
-2@@ -42,8 +42,8 @@ int blk_mq_map_queues(struct blk_mq_queue_map *qmap)/* * First do sequential mapping between CPUs and queues. * In case we still have CPUs to map, and we have some number of -* threads per cores then map sibling threads to the same queue for -* performace optimizations. +* threads per cores then map sibling threads to the same queue +* for performance optimizations. */ if (cpu < nr_queues) { map[cpu] =cpu_to_queue_index (qmap, nr_queues, cpu);
PATCH 8/8 blk-mq: Document the blk_mq_hw_queue_to_node() arguments
In reply to Bart Van AsscheDocument the meaning of the blk_mq_hw_queue_to_node() arguments.
--- block/blk-mq-cpumap.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
block/blk-mq-cpumap.c +5 -1
@@ -60,7 +60,11 @@ int blk_mq_map_queues(struct blk_mq_queue_map *qmap) }EXPORT_SYMBOL_GPL (blk_mq_map_queues); -/* +/** +* blk_mq_hw_queue_to_node - Look up the memory node for a hardware queue index +* @qmap: CPU to hardware queue map. +* @index: hardware queue index. +* * We have no quick way of doing reverse lookups. This is only used at * queue init time, so runtime isn't important. */
Signature · 1 line
2.22.0.rc1
Re: [PATCH 8/8] blk-mq: Document the blk_mq_hw_queue_to_node() arguments
Looks good.
Quoted 25 lines · Bart Van Assche
Document the meaning of the
blk_mq_hw_queue_to_node()arguments.Signed-off-by Bart Van Assche <[email protected]>--- block/blk-mq-cpumap.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)block/blk-mq-cpumap.c +5
-1@@ -60,7 +60,11 @@ int blk_mq_map_queues(struct blk_mq_queue_map *qmap) }EXPORT_SYMBOL_GPL (blk_mq_map_queues); -/* +/** +* blk_mq_hw_queue_to_node - Look up the memory node for a hardware queue index +* @qmap: CPU to hardware queue map. +* @index: hardware queue index. +* * We have no quick way of doing reverse lookups. This is only used at * queue init time, so runtime isn't important. */
Jens Axboe
maintainerQuoted 5 lines · Bart Van Assche
Hi Jens,
This is a series with eight patches that address source code comments. Most patches suppress kernel-doc warnings that appear when building with W=1. Please consider these patches.
Thanks Bart, applied.
Signature · 1 line
Jens Axboe