Re: [PATCH 01/11] block: improve the kerneldoc comments for submit_bio and generic_make_request

[Ming Lei <ming.lei@redhat.com>]

On Sat, Apr 25, 2020 at 07:09:34PM +0200, Christoph Hellwig wrote:
> The current documentation is a little weird, as it doesn't clearly
> explain which function to use, and also has the guts of the information
> on generic_make_request, which is the internal interface for stacking
> drivers.
> 
> Fix this up by properly documenting submit_bio, and only documenting
> the differences and the use case for generic_make_request.
> 
> Signed-off-by: Christoph Hellwig <hch@lst.de>
> ---
>  block/blk-core.c | 35 ++++++++++++-----------------------
>  1 file changed, 12 insertions(+), 23 deletions(-)
> 
> diff --git a/block/blk-core.c b/block/blk-core.c
> index dffff21008886..68351ee94ad2e 100644
> --- a/block/blk-core.c
> +++ b/block/blk-core.c
> @@ -992,28 +992,13 @@ generic_make_request_checks(struct bio *bio)
>  }
>  
>  /**
> - * generic_make_request - hand a buffer to its device driver for I/O
> + * generic_make_request - re-submit a bio to the block device layer for I/O
>   * @bio:  The bio describing the location in memory and on the device.
>   *
> - * generic_make_request() is used to make I/O requests of block
> - * devices. It is passed a &struct bio, which describes the I/O that needs
> - * to be done.
> - *
> - * generic_make_request() does not return any status.  The
> - * success/failure status of the request, along with notification of
> - * completion, is delivered asynchronously through the bio->bi_end_io
> - * function described (one day) else where.
> - *
> - * The caller of generic_make_request must make sure that bi_io_vec
> - * are set to describe the memory buffer, and that bi_dev and bi_sector are
> - * set to describe the device address, and the
> - * bi_end_io and optionally bi_private are set to describe how
> - * completion notification should be signaled.
> - *
> - * generic_make_request and the drivers it calls may use bi_next if this
> - * bio happens to be merged with someone else, and may resubmit the bio to
> - * a lower device by calling into generic_make_request recursively, which
> - * means the bio should NOT be touched after the call to ->make_request_fn.
> + * This is a version of submit_bio() that shall only be used for I/O that is
> + * resubmitted to lower level drivers by stacking block drivers.  All file

No, generic_make_request() can be used by any block driver instead of
stacking drivers, see bio split, blk_throttle.c and bounce, maybe more.


Thanks, 
Ming