Commit 7cc2623d authored by Bart Van Assche's avatar Bart Van Assche Committed by Jens Axboe
Browse files

block: Update blk_update_request() documentation 



Although the original intent was to use blk_update_request() in stacking
block drivers only, it is used much more widely today. Reflect this in the
documentation block above this function. See also:
* commit 32fab448 ("block: add request update interface").
* commit 2e60e022 ("block: clean up request completion API").
* commit ed6565e7 ("block: handle partial completions for special
  payload requests").

Cc: Christoph Hellwig <hch@lst.de>
Cc: Ming Lei <ming.lei@redhat.com>
Cc: Hannes Reinecke <hare@suse.de>
Signed-off-by: default avatarBart Van Assche <bvanassche@acm.org>
Link: https://lore.kernel.org/r/20210519175226.8853-1-bvanassche@acm.org


Signed-off-by: default avatarJens Axboe <axboe@kernel.dk>
parent 61347154

block/blk-core.c

+4 −8
Original line number Diff line number Diff line
@@ -1384,26 +1384,22 @@ void blk_steal_bios(struct bio_list *list, struct request *rq) 
EXPORT_SYMBOL_GPL(blk_steal_bios);



/**

 * blk_update_request - Special helper function for request stacking drivers

 * blk_update_request - Complete multiple bytes without completing the request

 * @req:      the request being processed

 * @error:    block status code

 * @nr_bytes: number of bytes to complete @req

 * @nr_bytes: number of bytes to complete for @req

 *

 * Description:

 *     Ends I/O on a number of bytes attached to @req, but doesn't complete

 *     the request structure even if @req doesn't have leftover.

 *     If @req has leftover, sets it up for the next range of segments.

 *

 *     This special helper function is only for request stacking drivers

 *     (e.g. request-based dm) so that they can handle partial completion.

 *     Actual device drivers should use blk_mq_end_request instead.

 *

 *     Passing the result of blk_rq_bytes() as @nr_bytes guarantees

 *     %false return from this function.

 *

 * Note:

 *	The RQF_SPECIAL_PAYLOAD flag is ignored on purpose in both

 *	blk_rq_bytes() and in blk_update_request().

 *	The RQF_SPECIAL_PAYLOAD flag is ignored on purpose in this function

 *      except in the consistency check at the end of this function.

 *

 * Return:

 *     %false - this request doesn't have any more data