blk-mq-dma: kernel-doc fixes
cover blk-mq-dma: kernel-doc fixes
Two comment-only fixes for block/blk-mq-dma.c. Neither changes the generated code.
Patch 1 removes a @state parameter description from blk_rq_integrity_dma_map_iter_next(), which has never taken that argument, and fixes the tab-after-"* " alignment checkpatch complains about in the two integrity summary lines.
Patch 2 fixes "ft" -> "if" in the return value description of blk_rq_dma_map_iter_start() and blk_rq_dma_map_iter_next().
Per Documentation/process/generated-content.rst, disclosure of the tooling used:
- The defects were found by running scripts/kernel-doc and scripts/checkpatch.pl over block/ and comparing the resulting warnings against the function prototypes.
- An AI coding assistant (Claude, claude-opus-5) was used across an interactive session to run those scripts, cross-check the signatures in include/linux/blk-integrity.h, identify the introducing commits for the Fixes: tags, and draft these changelogs. The code changes themselves are confined to comment text and whitespace.
- Verification: scripts/kernel-doc reports no warnings for block/blk-mq-dma.c after the series; scripts/checkpatch.pl reports no errors or warnings on either patch; both apply cleanly to for-next. The series has not been compile-tested, as it was prepared on a non-Linux host; it touches only comments.
Bryan Boquel (2):
blk-mq-dma: fix kernel-doc for integrity DMA iterators
blk-mq-dma: fix typo in DMA iterator kernel-doc
block/blk-mq-dma.c | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
Signature · 1 line
2.39.2 (Apple Git-143)
PATCH 1/2 blk-mq-dma: fix kernel-doc for integrity DMA iterators
blk_rq_integrity_dma_map_iter_next() documents a @state parameter it has never had. It takes (req, dma_dev, iter), as declared in include/linux/blk-integrity.h, so scripts/kernel-doc reports an "Excess function parameter 'state' description" warning at block/blk-mq-dma.c:379.
The wrapped summary lines of both integrity helpers also indent with tabs directly after "* ", which checkpatch flags as:
block/blk-mq-dma.c:320: WARNING: please, no space before tabs block/blk-mq-dma.c:361: WARNING: please, no space before tabs
Drop the stale parameter description and use spaces for the alignment; the rendered output is unchanged. No functional change.
Both issues were found by running scripts/kernel-doc and scripts/checkpatch.pl over block/, and verified against the prototype in include/linux/blk-integrity.h.
--- block/blk-mq-dma.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
block/blk-mq-dma.c +2 -3
@@ -317,7 +317,7 @@ EXPORT_SYMBOL(__blk_rq_map_sg);#ifdef CONFIG_BLK_DEV_INTEGRITY /** * blk_rq_integrity_dma_map_iter_start - map the first integrity DMA segment -* for a request +* for a request * @req: request to map * @dma_dev: device to map to * @state: DMA IOVA state
@@ -358,10 +358,9 @@ EXPORT_SYMBOL_GPL(blk_rq_integrity_dma_map_iter_start);/** * blk_rq_integrity_dma_map_iter_next - map the next integrity DMA segment for -* a request +* a request * @req: request to map * @dma_dev: device to map to -* @state: DMA IOVA state * @iter: block layer DMA iterator * * Iterate to the next integrity mapping after a previous call to
Signature · 1 line
2.39.2 (Apple Git-143)
Re: [PATCH 1/2] blk-mq-dma: fix kernel-doc for integrity DMA iterators
Looks good:
PATCH 2/2 blk-mq-dma: fix typo in DMA iterator kernel-doc
In reply to Bryan Boquelblk_rq_dma_map_iter_start() and blk_rq_dma_map_iter_next() both document their return value as "%true ft it did map a segment", where "ft" should read "if". The two integrity variants further down spell it correctly.
No functional change.
--- block/blk-mq-dma.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
block/blk-mq-dma.c +2 -2
@@ -213,7 +213,7 @@ static bool blk_dma_map_iter_start(struct request *req, struct device *dma_dev,* at unmap time, @iter is only needed at map time. * * Returns %false if there is no segment to map, including due to an error, or -* %true ft it did map a segment. +* %true if it did map a segment. * * If a segment was mapped, the DMA address for it is returned in @iter.addr and * the length in @iter.len. If no segment was mapped the status code is
@@ -243,7 +243,7 @@ EXPORT_SYMBOL_GPL(blk_rq_dma_map_iter_start);* arguments. * * Returns %false if there is no segment to map, including due to an error, or -* %true ft it did map a segment. +* %true if it did map a segment. * * If a segment was mapped, the DMA address for it is returned in @iter.addr and * the length in @iter.len. If no segment was mapped the status code is
Signature · 1 line
2.39.2 (Apple Git-143)
Re: [PATCH 2/2] blk-mq-dma: fix typo in DMA iterator kernel-doc
Looks good: