block: improve the submit_bio and generic_make_request documentation (3fdd4086) · Commits · 戴 / test

block/blk-core.c

+12 −23

Original line number	Diff line number	Diff line
		@@ -992,28 +992,13 @@ end_io:
		}

		/**
		* 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)
		{

Admin message