Skip to contentSkip to conversation

Improve block layer function documentation

PATCH In review Bart Van Assche 4 participants 19 messages May 31, 2019

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 6db573f33219..fe5d970e2e60 100644
@@ -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
Reviewed-by on v1 1/8
#2 lore raw

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.

---
  block/partitions/ldm.c | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
block/partitions/ldm.c +1 -1
index 6db573f33219..fe5d970e2e60 100644
@@ -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
#3 lore raw

PATCH 2/8 block: Convert blk_invalidate_devt() header into a non-kernel-doc header

In reply to Bart Van Assche

This 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
index ad6826628e79..24654e1d83e6 100644
@@ -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
Reviewed-by on v1 2/8
#4 lore raw

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.

---
  block/genhd.c | 4 ++--
  1 file changed, 2 insertions(+), 2 deletions(-)
block/genhd.c +2 -2
index ad6826628e79..24654e1d83e6 100644
@@ -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)
  {
#5 lore raw

PATCH 3/8 block: Fix throtl_pending_timer_fn() kernel-doc header

In reply to Bart Van Assche

Commit e99e88a9d2b0 renamed 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.
---
 block/blk-throttle.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
block/blk-throttle.c +1 -1
index 1b97a73d2fb1..9ea7c0ecad10 100644
@@ -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
Reviewed-by on v1 3/8
#6 lore raw

Re: [PATCH 3/8] block: Fix throtl_pending_timer_fn() kernel-doc header

Looks good.

Quoted 24 lines · Bart Van Assche

Commit e99e88a9d2b0 renamed 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.
---
  block/blk-throttle.c | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
block/blk-throttle.c +1 -1
index 1b97a73d2fb1..9ea7c0ecad10 100644
@@ -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
Reviewed-by on v1 3/8
#7 lore raw

Re: [PATCH 3/8] block: Fix throtl_pending_timer_fn() kernel-doc header

In reply to Bart Van Assche
Quoted 6 lines · Bart Van Assche

Commit e99e88a9d2b0 renamed 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.

-Kees

Quoted 20 lines
---
 block/blk-throttle.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
block/blk-throttle.c +1 -1
index 1b97a73d2fb1..9ea7c0ecad10 100644
@@ -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
#8 lore raw

PATCH 4/8 block: Fix blk_mq_*_map_queues() kernel-doc headers

In reply to 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.
---
 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
index ad4545a2a98b..b595a94c4d16 100644
@@ -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
index cc921e6ba709..14f968e58b8f 100644
@@ -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
index 75a52c18a8f6..488341628256 100644
@@ -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
Reviewed-by on v1 4/8
#9 lore raw

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.
---
  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
index ad4545a2a98b..b595a94c4d16 100644
@@ -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
index cc921e6ba709..14f968e58b8f 100644
@@ -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
index 75a52c18a8f6..488341628256 100644
@@ -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
#10 lore raw

PATCH 5/8 block: Fix rq_qos_wait() kernel-doc header

In reply to 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.
---
 block/blk-rq-qos.c | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
block/blk-rq-qos.c +4 -3
index 3f55b56f24bc..659ccb8b693f 100644
@@ -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
Reviewed-by on v1 5/8
#11 lore raw

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.
---
  block/blk-rq-qos.c | 7 ++++---
  1 file changed, 4 insertions(+), 3 deletions(-)
block/blk-rq-qos.c +4 -3
index 3f55b56f24bc..659ccb8b693f 100644
@@ -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
#12 lore raw

PATCH 6/8 block: Fix bsg_setup_queue() kernel-doc header

In reply to Bart Van Assche

Document all bsg_setup_queue() arguments as required.

Fixes aae3b069d5ce ("bsg: pass in desired timeout handler") # v5.0.
---
 block/bsg-lib.c | 1 +
 1 file changed, 1 insertion(+)
block/bsg-lib.c +1 -0
index b898a1cdf872..785dd58947f1 100644
@@ -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
Reviewed-by on v1 6/8
#13 lore raw

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.
---
  block/bsg-lib.c | 1 +
  1 file changed, 1 insertion(+)
block/bsg-lib.c +1 -0
index b898a1cdf872..785dd58947f1 100644
@@ -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,
#14 lore raw

PATCH 7/8 blk-mq: Fix spelling in a source code comment

In reply to 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.
---
 block/blk-mq-cpumap.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
block/blk-mq-cpumap.c +2 -2
index 48bebf00a5f3..0afa4dc48365 100644
@@ -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
Reviewed-by on v1 7/8
#15 lore raw

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.
---
  block/blk-mq-cpumap.c | 4 ++--
  1 file changed, 2 insertions(+), 2 deletions(-)
block/blk-mq-cpumap.c +2 -2
index 48bebf00a5f3..0afa4dc48365 100644
@@ -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);
#16 lore raw

PATCH 8/8 blk-mq: Document the blk_mq_hw_queue_to_node() arguments

In reply to Bart Van Assche

Document 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
index 0afa4dc48365..f945621a0e8f 100644
@@ -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
Reviewed-by on v1 8/8
#17 lore raw

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.

---
  block/blk-mq-cpumap.c | 6 +++++-
  1 file changed, 5 insertions(+), 1 deletion(-)
block/blk-mq-cpumap.c +5 -1
index 0afa4dc48365..f945621a0e8f 100644
@@ -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.
   */
maintainer
#18 lore raw
In reply to Bart Van Assche
Quoted 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