ivampiresp/Spdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bdev: add Doxgyen group tags to mark bdev_io_submit functions

Browse Source 
This will be useful for some upcoming patches that refer to
functions that can submit an spdk_bdev_io.

Signed-off-by: Jim Harris <james.r.harris@intel.com>
Change-Id: If9b97d53e32d3198f3ef4f2d69f9fafea7a16bf2

Reviewed-on: https://review.gerrithub.io/415033
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
This commit is contained in:
Jim Harris 2018-06-12 09:28:42 -07:00
parent 58528ca799
commit b10f6b1c8c
1 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
include/spdk/bdev.h
View File

@ -400,9 +400,19 @@ const struct spdk_uuid *spdk_bdev_get_uuid(const struct spdk_bdev *bdev);
*/ */
struct spdk_io_channel *spdk_bdev_get_io_channel(struct spdk_bdev_desc *desc); struct spdk_io_channel *spdk_bdev_get_io_channel(struct spdk_bdev_desc *desc);
/**
* \defgroup bdev_io_submit_functions bdev I/O Submit Functions
*
* These functions submit a new I/O request to a bdev. The I/O request will
* be represented by an spdk_bdev_io structure allocated from a global pool.
* These functions will return -ENOMEM if the spdk_bdev_io pool is empty.
*/
/** /**
* Submit a read request to the bdev on the given channel. * Submit a read request to the bdev on the given channel.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param buf Data buffer to read into. * \param buf Data buffer to read into.
@ -424,6 +434,8 @@ int spdk_bdev_read(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
/** /**
* Submit a read request to the bdev on the given channel. * Submit a read request to the bdev on the given channel.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param buf Data buffer to read into. * \param buf Data buffer to read into.
@ -449,6 +461,8 @@ int spdk_bdev_read_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel *c
* data and may not be able to directly transfer into the buffers provided. In * data and may not be able to directly transfer into the buffers provided. In
* this case, the request may fail. * this case, the request may fail.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param iov A scatter gather list of buffers to be read into. * \param iov A scatter gather list of buffers to be read into.
@ -476,6 +490,8 @@ int spdk_bdev_readv(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
* data and may not be able to directly transfer into the buffers provided. In * data and may not be able to directly transfer into the buffers provided. In
* this case, the request may fail. * this case, the request may fail.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param iov A scatter gather list of buffers to be read into. * \param iov A scatter gather list of buffers to be read into.
@ -499,6 +515,8 @@ int spdk_bdev_readv_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel *
/** /**
* Submit a write request to the bdev on the given channel. * Submit a write request to the bdev on the given channel.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param buf Data buffer to written from. * \param buf Data buffer to written from.
@ -521,6 +539,8 @@ int spdk_bdev_write(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
/** /**
* Submit a write request to the bdev on the given channel. * Submit a write request to the bdev on the given channel.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param buf Data buffer to written from. * \param buf Data buffer to written from.
@ -547,6 +567,8 @@ int spdk_bdev_write_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel *
* data and may not be able to directly transfer out of the buffers provided. In * data and may not be able to directly transfer out of the buffers provided. In
* this case, the request may fail. * this case, the request may fail.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param iov A scatter gather list of buffers to be written from. * \param iov A scatter gather list of buffers to be written from.
@ -575,6 +597,8 @@ int spdk_bdev_writev(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
* data and may not be able to directly transfer out of the buffers provided. In * data and may not be able to directly transfer out of the buffers provided. In
* this case, the request may fail. * this case, the request may fail.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param iov A scatter gather list of buffers to be written from. * \param iov A scatter gather list of buffers to be written from.
@ -600,6 +624,8 @@ int spdk_bdev_writev_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel
* Submit a write zeroes request to the bdev on the given channel. This command * Submit a write zeroes request to the bdev on the given channel. This command
* ensures that all bytes in the specified range are set to 00h * ensures that all bytes in the specified range are set to 00h
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset The offset, in bytes, from the start of the block device. * \param offset The offset, in bytes, from the start of the block device.
@ -622,6 +648,8 @@ int spdk_bdev_write_zeroes(struct spdk_bdev_desc *desc, struct spdk_io_channel *
* Submit a write zeroes request to the bdev on the given channel. This command * Submit a write zeroes request to the bdev on the given channel. This command
* ensures that all bytes in the specified range are set to 00h * ensures that all bytes in the specified range are set to 00h
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset_blocks The offset, in blocks, from the start of the block device. * \param offset_blocks The offset, in blocks, from the start of the block device.
@ -645,6 +673,8 @@ int spdk_bdev_write_zeroes_blocks(struct spdk_bdev_desc *desc, struct spdk_io_ch
* deallocate. This notifies the device that the data in the blocks described is no * deallocate. This notifies the device that the data in the blocks described is no
* longer valid. Reading blocks that have been unmapped results in indeterminate data. * longer valid. Reading blocks that have been unmapped results in indeterminate data.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset The offset, in bytes, from the start of the block device. * \param offset The offset, in bytes, from the start of the block device.
@ -668,6 +698,8 @@ int spdk_bdev_unmap(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
* deallocate. This notifies the device that the data in the blocks described is no * deallocate. This notifies the device that the data in the blocks described is no
* longer valid. Reading blocks that have been unmapped results in indeterminate data. * longer valid. Reading blocks that have been unmapped results in indeterminate data.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset_blocks The offset, in blocks, from the start of the block device. * \param offset_blocks The offset, in blocks, from the start of the block device.
@ -691,6 +723,8 @@ int spdk_bdev_unmap_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel *
* caches, data is not guaranteed to be persistent until the completion of a flush * caches, data is not guaranteed to be persistent until the completion of a flush
* request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache. * request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset The offset, in bytes, from the start of the block device. * \param offset The offset, in bytes, from the start of the block device.
@ -714,6 +748,8 @@ int spdk_bdev_flush(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
* caches, data is not guaranteed to be persistent until the completion of a flush * caches, data is not guaranteed to be persistent until the completion of a flush
* request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache. * request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param offset_blocks The offset, in blocks, from the start of the block device. * \param offset_blocks The offset, in blocks, from the start of the block device.
@ -735,6 +771,8 @@ int spdk_bdev_flush_blocks(struct spdk_bdev_desc *desc, struct spdk_io_channel *
/** /**
* Submit a reset request to the bdev on the given channel. * Submit a reset request to the bdev on the given channel.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param cb Called when the request is complete. * \param cb Called when the request is complete.
@ -756,6 +794,8 @@ int spdk_bdev_reset(struct spdk_bdev_desc *desc, struct spdk_io_channel *ch,
* The SGL/PRP will be automated generated based on the given buffer, * The SGL/PRP will be automated generated based on the given buffer,
* so that portion of the command may be left empty. * so that portion of the command may be left empty.
* *
* \ingroup bdev_io_submit_functions
*
* \param desc Block device descriptor. * \param desc Block device descriptor.
* \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel(). * \param ch I/O channel. Obtained by calling spdk_bdev_get_io_channel().
* \param cmd The raw NVMe command. Must be an admin command. * \param cmd The raw NVMe command. Must be an admin command.
@ -781,6 +821,8 @@ int spdk_bdev_nvme_admin_passthru(struct spdk_bdev_desc *desc,
* the block layer to the device. Support for NVMe passthru is optional, * the block layer to the device. Support for NVMe passthru is optional,
* indicated by calling spdk_bdev_io_type_supported(). * indicated by calling spdk_bdev_io_type_supported().
* *
* \ingroup bdev_io_submit_functions
*
* The SGL/PRP will be automated generated based on the given buffer, * The SGL/PRP will be automated generated based on the given buffer,
* so that portion of the command may be left empty. Also, the namespace * so that portion of the command may be left empty. Also, the namespace
* id (nsid) will be populated automatically. * id (nsid) will be populated automatically.
@ -810,6 +852,8 @@ int spdk_bdev_nvme_io_passthru(struct spdk_bdev_desc *bdev_desc,
* the block layer to the device. Support for NVMe passthru is optional, * the block layer to the device. Support for NVMe passthru is optional,
* indicated by calling spdk_bdev_io_type_supported(). * indicated by calling spdk_bdev_io_type_supported().
* *
* \ingroup bdev_io_submit_functions
*
* The SGL/PRP will be automated generated based on the given buffer, * The SGL/PRP will be automated generated based on the given buffer,
* so that portion of the command may be left empty. Also, the namespace * so that portion of the command may be left empty. Also, the namespace
* id (nsid) will be populated automatically. * id (nsid) will be populated automatically.