| Message ID | 20200425170944.968861-2-hch@lst.de (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [01/11] block: improve the kerneldoc comments for submit_bio and generic_make_request | expand |
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
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 + * systems and other upper level users of the block layer should use + * submit_bio() instead. */ blk_qc_t generic_make_request(struct bio *bio) { @@ -1152,10 +1137,14 @@ EXPORT_SYMBOL_GPL(direct_make_request); * submit_bio - submit a bio to the block device layer for I/O * @bio: The &struct bio which describes the I/O * - * submit_bio() is very similar in purpose to generic_make_request(), and - * uses that function to do most of the work. Both are fairly rough - * interfaces; @bio must be presetup and ready for I/O. + * submit_bio() is used to submit I/O requests to block devices. It is passed a + * fully set up &struct bio that describes the I/O that needs to be done. The + * bio will be send to the device described by the bi_disk and bi_partno fields. * + * The success/failure status of the request, along with notification of + * completion, is delivered asynchronously through the ->bi_end_io() callback + * in @bio. The bio must NOT be touched by thecaller until ->bi_end_io() has + * been called. */ blk_qc_t submit_bio(struct bio *bio) {
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(-)