bdev: add doc comments for functions in bdev_module.h

Change-Id: I429b1b7e553870844e3efa02188c5dd5a75531fc
Signed-off-by: Seth Howell <seth.howell@intel.com>
Reviewed-on: https://review.gerrithub.io/416250
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>
This commit is contained in:
Seth Howell 2018-06-20 13:41:24 -07:00 committed by Ben Walker
parent a648660be5
commit 4393ae23b0

View File

@ -429,17 +429,103 @@ struct spdk_bdev_io {
/* No members may be added after driver_ctx! */
};
/**
* Register a new bdev.
*
* \param bdev Block device to register.
*
* \return 0 on success.
* \return -EINVAL if the bdev name is NULL.
* \return -EEXIST if a bdev or bdev alias with the same name already exists.
*/
int spdk_bdev_register(struct spdk_bdev *bdev);
/**
* Unregister a bdev
*
* \param bdev Block device to unregister.
* \param cb_fn Callback function to be called when the unregister is complete.
* \param cb_arg Argument to be supplied to cb_fn
*/
void spdk_bdev_unregister(struct spdk_bdev *bdev, spdk_bdev_unregister_cb cb_fn, void *cb_arg);
/**
* Invokes the unregister callback of a bdev backing a virtual bdev.
*
* A Bdev with an asynchronous destruct path should return 1 from its
* destruct function and call this function at the conclusion of that path.
* Bdevs with synchronous destruct paths should return 0 from their destruct
* path.
*
* \param bdev Block device that was destroyed.
* \param bdeverrno Error code returned from bdev's destruct callback.
*/
void spdk_bdev_destruct_done(struct spdk_bdev *bdev, int bdeverrno);
/**
* Register a virtual bdev.
*
* \param vbdev Virtual bdev to register.
* \param base_bdevs Array of bdevs upon which this vbdev is based.
* \param base_bdev_count Number of bdevs in base_bdevs.
*
* \return 0 on success
* \return -EINVAL if the bdev name is NULL.
* \return -EEXIST if the bdev already exists.
* \return -ENOMEM if allocation of the base_bdevs array or the base bdevs vbdevs array fails.
*/
int spdk_vbdev_register(struct spdk_bdev *vbdev, struct spdk_bdev **base_bdevs,
int base_bdev_count);
/**
* Indicate to the bdev layer that the module is done examining a bdev.
*
* To be called synchronously or asynchronously in response to the
* module's examine function being called.
*
* \param module Pointer to the module completing the examination.
*/
void spdk_bdev_module_examine_done(struct spdk_bdev_module *module);
/**
* Indicate to the bdev layer that the module is done initializing.
*
* To be called synchronously or asynchronously in response to the
* module_init function being called.
*
* \param module Pointer to the module completing the initialization.
*/
void spdk_bdev_module_init_done(struct spdk_bdev_module *module);
/**
* Indicate to the bdev layer that the module is done cleaning up.
*
* To be called either synchronously or asynchronously
* in response to the module_fini function being called.
*
*/
void spdk_bdev_module_finish_done(void);
/**
* Called by a bdev module to lay exclusive write claim to a bdev.
*
* Also upgrades that bdev's descriptor to have write access.
*
* \param bdev Block device to be claimed.
* \param desc Descriptor for the above block device.
* \param module Bdev module attempting to claim bdev.
*
* \return 0 on success
* \return -EPERM if the bdev is already claimed by another module.
*/
int spdk_bdev_module_claim_bdev(struct spdk_bdev *bdev, struct spdk_bdev_desc *desc,
struct spdk_bdev_module *module);
/**
* Called to release a write claim on a block device.
*
* \param bdev Block device to be released.
*/
void spdk_bdev_module_release_bdev(struct spdk_bdev *bdev);
/**
@ -449,7 +535,6 @@ void spdk_bdev_module_release_bdev(struct spdk_bdev *bdev);
* \param bdev Block device to query.
* \param alias Alias to be added to list.
*
* Return codes
* \return 0 on success
* \return -EEXIST if alias already exists as name or alias on any bdev
* \return -ENOMEM if memory cannot be allocated to store alias
@ -491,6 +576,12 @@ const struct spdk_bdev_aliases_list *spdk_bdev_get_aliases(const struct spdk_bde
*/
void spdk_bdev_io_get_buf(struct spdk_bdev_io *bdev_io, spdk_bdev_io_get_buf_cb cb, uint64_t len);
/**
* Complete a bdev_io
*
* \param bdev_io I/O to complete.
* \param status The I/O completion status.
*/
void spdk_bdev_io_complete(struct spdk_bdev_io *bdev_io,
enum spdk_bdev_io_status status);