[PATCH] blk-mq: Fix more tag iteration function documentation

[PATCH] blk-mq: Fix more tag iteration function documentation

[Bart Van Assche]

Commit 8ab30a331946 ("blk-mq: Drop busy_iter_fn blk_mq_hw_ctx argument")
removed the hctx argument from the callback functions called by
bt_for_each() and blk_mq_queue_tag_busy_iter(). Commit 2dd6532e9591
("blk-mq: Drop 'reserved' arg of busy_tag_iter_fn") removed the
'reserved' argument of the busy_tag_iter_fn function pointer type. Bring
the documentation of the tag iteration functions in sync with these
changes.

Cc: John Garry <john.g.garry@oracle.com>
Cc: Ming Lei <ming.lei@redhat.com>
Cc: Christoph Hellwig <hch@infradead.org>
Signed-off-by: Bart Van Assche <bvanassche@acm.org>
---
 block/blk-mq-tag.c | 32 +++++++++++++++-----------------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/block/blk-mq-tag.c b/block/blk-mq-tag.c
index 0602ca7f1e37..271fa005c51e 100644
--- a/block/blk-mq-tag.c
+++ b/block/blk-mq-tag.c
@@ -297,15 +297,15 @@ static bool bt_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data)
 /**
  * bt_for_each - iterate over the requests associated with a hardware queue
  * @hctx:	Hardware queue to examine.
- * @q:		Request queue to examine.
+ * @q:		Request queue @hctx is associated with (@hctx->queue).
  * @bt:		sbitmap to examine. This is either the breserved_tags member
  *		or the bitmap_tags member of struct blk_mq_tags.
  * @fn:		Pointer to the function that will be called for each request
  *		associated with @hctx that has been assigned a driver tag.
- *		@fn will be called as follows: @fn(@hctx, rq, @data, @reserved)
- *		where rq is a pointer to a request. Return true to continue
- *		iterating tags, false to stop.
- * @data:	Will be passed as third argument to @fn.
+ *		@fn will be called as follows: @fn(rq, @data) where rq is a
+ *		pointer to a request. Return %true to continue iterating tags;
+ *		%false to stop.
+ * @data:	Will be passed as second argument to @fn.
  * @reserved:	Indicates whether @bt is the breserved_tags member or the
  *		bitmap_tags member of struct blk_mq_tags.
  */
@@ -371,9 +371,9 @@ static bool bt_tags_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data)
  * @bt:		sbitmap to examine. This is either the breserved_tags member
  *		or the bitmap_tags member of struct blk_mq_tags.
  * @fn:		Pointer to the function that will be called for each started
- *		request. @fn will be called as follows: @fn(rq, @data,
- *		@reserved) where rq is a pointer to a request. Return true
- *		to continue iterating tags, false to stop.
+ *		request. @fn will be called as follows: @fn(rq, @data) where rq
+ *		is a pointer to a request. Return %true to continue iterating
+ *		tags; %false to stop.
  * @data:	Will be passed as second argument to @fn.
  * @flags:	BT_TAG_ITER_*
  */
@@ -406,10 +406,9 @@ static void __blk_mq_all_tag_iter(struct blk_mq_tags *tags,
  * blk_mq_all_tag_iter - iterate over all requests in a tag map
  * @tags:	Tag map to iterate over.
  * @fn:		Pointer to the function that will be called for each
- *		request. @fn will be called as follows: @fn(rq, @priv,
- *		reserved) where rq is a pointer to a request. 'reserved'
- *		indicates whether or not @rq is a reserved request. Return
- *		true to continue iterating tags, false to stop.
+ *		request. @fn will be called as follows: @fn(rq, @priv) where rq
+ *		is a pointer to a request. Return %true to continue iterating
+ *		tags; %false to stop.
  * @priv:	Will be passed as second argument to @fn.
  *
  * Caller has to pass the tag map from which requests are allocated.
@@ -485,11 +484,10 @@ EXPORT_SYMBOL(blk_mq_tagset_wait_completed_request);
  * blk_mq_queue_tag_busy_iter - iterate over all requests with a driver tag
  * @q:		Request queue to examine.
  * @fn:		Pointer to the function that will be called for each request
- *		on @q. @fn will be called as follows: @fn(hctx, rq, @priv,
- *		reserved) where rq is a pointer to a request and hctx points
- *		to the hardware queue associated with the request. 'reserved'
- *		indicates whether or not @rq is a reserved request.
- * @priv:	Will be passed as third argument to @fn.
+ *		on @q. @fn will be called as follows: @fn(rq, @priv) where rq
+ *		is a pointer to a request and hctx points to the hardware queue
+ *		associated with the request.
+ * @priv:	Will be passed as second argument to @fn.
  *
  * Note: if @q->tag_set is shared with other request queues then @fn will be
  * called for all requests on all queues that share that tag set and not only

Re: [PATCH] blk-mq: Fix more tag iteration function documentation

[Jens Axboe]

On Mon, 22 Sep 2025 13:13:24 -0700, Bart Van Assche wrote:
> Commit 8ab30a331946 ("blk-mq: Drop busy_iter_fn blk_mq_hw_ctx argument")
> removed the hctx argument from the callback functions called by
> bt_for_each() and blk_mq_queue_tag_busy_iter(). Commit 2dd6532e9591
> ("blk-mq: Drop 'reserved' arg of busy_tag_iter_fn") removed the
> 'reserved' argument of the busy_tag_iter_fn function pointer type. Bring
> the documentation of the tag iteration functions in sync with these
> changes.
> 
> [...]

Applied, thanks!

[1/1] blk-mq: Fix more tag iteration function documentation
      (no commit info)

Best regards,
-- 
Jens Axboe

Re: [PATCH] blk-mq: Fix more tag iteration function documentation

[John Garry]

On 22/09/2025 21:13, Bart Van Assche wrote:
> Commit 8ab30a331946 ("blk-mq: Drop busy_iter_fn blk_mq_hw_ctx argument")
> removed the hctx argument from the callback functions called by
> bt_for_each() and blk_mq_queue_tag_busy_iter(). Commit 2dd6532e9591
> ("blk-mq: Drop 'reserved' arg of busy_tag_iter_fn") removed the
> 'reserved' argument of the busy_tag_iter_fn function pointer type. Bring
> the documentation of the tag iteration functions in sync with these
> changes.
> 
> Cc: John Garry <john.g.garry@oracle.com>
> Cc: Ming Lei <ming.lei@redhat.com>
> Cc: Christoph Hellwig <hch@infradead.org>
> Signed-off-by: Bart Van Assche <bvanassche@acm.org>

Reviewed-by: John Garry <john.g.garry@oracle.com>

> ---
>   block/blk-mq-tag.c | 32 +++++++++++++++-----------------
>   1 file changed, 15 insertions(+), 17 deletions(-)
> 
> diff --git a/block/blk-mq-tag.c b/block/blk-mq-tag.c
> index 0602ca7f1e37..271fa005c51e 100644
> --- a/block/blk-mq-tag.c
> +++ b/block/blk-mq-tag.c
> @@ -297,15 +297,15 @@ static bool bt_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data)
>   /**
>    * bt_for_each - iterate over the requests associated with a hardware queue
>    * @hctx:	Hardware queue to examine.
> - * @q:		Request queue to examine.
> + * @q:		Request queue @hctx is associated with (@hctx->queue).

eh, sometimes hctx is NULL, so it is odd to be saying that it is the q 
is associated with that (being NULL)

Re: [PATCH] blk-mq: Fix more tag iteration function documentation

[Bart Van Assche]

On 9/23/25 12:51 AM, John Garry wrote:
> On 22/09/2025 21:13, Bart Van Assche wrote:
>> diff --git a/block/blk-mq-tag.c b/block/blk-mq-tag.c
>> index 0602ca7f1e37..271fa005c51e 100644
>> --- a/block/blk-mq-tag.c
>> +++ b/block/blk-mq-tag.c
>> @@ -297,15 +297,15 @@ static bool bt_iter(struct sbitmap *bitmap, 
>> unsigned int bitnr, void *data)
>>   /**
>>    * bt_for_each - iterate over the requests associated with a 
>> hardware queue
>>    * @hctx:    Hardware queue to examine.
>> - * @q:        Request queue to examine.
>> + * @q:        Request queue @hctx is associated with (@hctx->queue).
> 
> eh, sometimes hctx is NULL, so it is odd to be saying that it is the q 
> is associated with that (being NULL)

Thanks for the feedback John.

Jens, please let me know whether you want me to address this feedback in
a follow-up patch or by posting a second version of this patch.

Thank you,

Bart.

Re: [PATCH] blk-mq: Fix more tag iteration function documentation

[Jens Axboe]

On 9/23/25 9:59 AM, Bart Van Assche wrote:
> On 9/23/25 12:51 AM, John Garry wrote:
>> On 22/09/2025 21:13, Bart Van Assche wrote:
>>> diff --git a/block/blk-mq-tag.c b/block/blk-mq-tag.c
>>> index 0602ca7f1e37..271fa005c51e 100644
>>> --- a/block/blk-mq-tag.c
>>> +++ b/block/blk-mq-tag.c
>>> @@ -297,15 +297,15 @@ static bool bt_iter(struct sbitmap *bitmap, unsigned int bitnr, void *data)
>>>   /**
>>>    * bt_for_each - iterate over the requests associated with a hardware queue
>>>    * @hctx:    Hardware queue to examine.
>>> - * @q:        Request queue to examine.
>>> + * @q:        Request queue @hctx is associated with (@hctx->queue).
>>
>> eh, sometimes hctx is NULL, so it is odd to be saying that it is the q is associated with that (being NULL)
> 
> Thanks for the feedback John.
> 
> Jens, please let me know whether you want me to address this feedback in
> a follow-up patch or by posting a second version of this patch.

As per my applied email, it's already applied. And it's sitting a few
patches down at this point. I don't think there's a rush in fixing a
comment, so perhaps just do it next time you're touching that area
anyway.

-- 
Jens Axboe