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

include/lvol.h: add comments for public APIs

Browse Source 
Change-Id: I1f3947a4d666c0b96a60a3014ac1bfb9f77ce813
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/411217
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>
This commit is contained in:
Yanbo Zhou 2018-05-15 14:36:11 +08:00 committed by Jim Harris
parent 3d22c5088e
commit b31330acaa
1 changed files with 94 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
include/spdk/lvol.h
View File

@ -61,13 +61,15 @@ struct spdk_lvs_opts {
}; };
/** /**
* \brief Initialize an spdk_lvs_opts structure to the defaults. * Initialize an spdk_lvs_opts structure to the defaults.
* \param opts *
* \param opts Pointer to the spdk_lvs_opts structure to initialize.
*/ */
void spdk_lvs_opts_init(struct spdk_lvs_opts *opts); void spdk_lvs_opts_init(struct spdk_lvs_opts *opts);
/** /**
* \brief Callback definition for lvolstore operations, including handle to lvs * Callback definition for lvolstore operations, including handle to lvs.
*
* \param cb_arg Custom arguments * \param cb_arg Custom arguments
* \param lvol_store Handle to lvol_store or NULL when lvserrno is set * \param lvol_store Handle to lvol_store or NULL when lvserrno is set
* \param lvserrno Error * \param lvserrno Error
@ -76,7 +78,8 @@ typedef void (*spdk_lvs_op_with_handle_complete)(void *cb_arg, struct spdk_lvol_
int lvserrno); int lvserrno);
/** /**
* \brief Callback definition for lvolstore operations without handle * Callback definition for lvolstore operations without handle.
*
* \param cb_arg Custom arguments * \param cb_arg Custom arguments
* \param lvserrno Error * \param lvserrno Error
*/ */
@ -84,7 +87,8 @@ typedef void (*spdk_lvs_op_complete)(void *cb_arg, int lvserrno);
/** /**
* \brief Callback definition for lvol operations with handle to lvol * Callback definition for lvol operations with handle to lvol.
*
* \param cb_arg Custom arguments * \param cb_arg Custom arguments
* \param lvol Handle to lvol or NULL when lvserrno is set * \param lvol Handle to lvol or NULL when lvserrno is set
* \param lvolerrno Error * \param lvolerrno Error
@ -93,131 +97,158 @@ typedef void (*spdk_lvol_op_with_handle_complete)(void *cb_arg, struct spdk_lvol
int lvolerrno); int lvolerrno);
/** /**
* \brief Callback definition for lvol operations without handle to lvol * Callback definition for lvol operations without handle to lvol.
*
* \param cb_arg Custom arguments * \param cb_arg Custom arguments
* \param lvolerrno Error * \param lvolerrno Error
*/ */
typedef void (*spdk_lvol_op_complete)(void *cb_arg, int lvolerrno); typedef void (*spdk_lvol_op_complete)(void *cb_arg, int lvolerrno);
/** /**
* \brief Initialize lvolstore on given bs_bdev. * Initialize lvolstore on given bs_bdev.
* *
* bs_dev can be created on bdev by using spdk_bdev_create_bs_dev() * \param bs_dev This is created on the given bdev by using spdk_bdev_create_bs_dev()
* Refer to blobstore documention for more details. * beforehand.
* \param o Options for lvolstore.
* \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
* *
* \param o Options for lvolstore * \return 0 on success, negative errno on failure.
* \param cb_fn Completion callback
* \param cb_arg Completion callback custom arguments
* \return error
*/ */
int spdk_lvs_init(struct spdk_bs_dev *bs_dev, struct spdk_lvs_opts *o, int spdk_lvs_init(struct spdk_bs_dev *bs_dev, struct spdk_lvs_opts *o,
spdk_lvs_op_with_handle_complete cb_fn, void *cb_arg); spdk_lvs_op_with_handle_complete cb_fn, void *cb_arg);
/** /**
* \brief Renames given lvolstore. * Rename the given lvolstore.
* *
* \param lvs Pointer to lvolstore * \param lvs Pointer to lvolstore.
* \param new_name New name of lvs * \param new_name New name of lvs.
* \param cb_fn Completion callback * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments * \param cb_arg Completion callback custom arguments.
*/ */
void spdk_lvs_rename(struct spdk_lvol_store *lvs, const char *new_name, void spdk_lvs_rename(struct spdk_lvol_store *lvs, const char *new_name,
spdk_lvs_op_complete cb_fn, void *cb_arg); spdk_lvs_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Unloads lvolstore * Unload lvolstore.
* *
* All lvols have to be closed beforehand, when doing unload. * All lvols have to be closed beforehand, when doing unload.
* *
* \param lvol_store Handle to lvolstore * \param lvol_store Handle to lvolstore.
* \param cb_fn Completion callback * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments * \param cb_arg Completion callback custom arguments.
* \return error *
* \return 0 on success, negative errno on failure.
*/ */
int spdk_lvs_unload(struct spdk_lvol_store *lvol_store, int spdk_lvs_unload(struct spdk_lvol_store *lvol_store,
spdk_lvs_op_complete cb_fn, void *cb_arg); spdk_lvs_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Destroy lvolstore * Destroy lvolstore.
* *
* All lvols have to be closed beforehand, when doing destroy. * All lvols have to be closed beforehand, when doing destroy.
* *
* \param lvol_store Handle to lvolstore * \param lvol_store Handle to lvolstore.
* \param cb_fn Completion callback * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments * \param cb_arg Completion callback custom arguments.
* \return error *
* \return 0 on success, negative errno on failure.
*/ */
int spdk_lvs_destroy(struct spdk_lvol_store *lvol_store, int spdk_lvs_destroy(struct spdk_lvol_store *lvol_store,
spdk_lvs_op_complete cb_fn, void *cb_arg); spdk_lvs_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Create lvol on given lvolstore with specified size * Create lvol on given lvolstore with specified size.
* \param lvs Handle to lvolstore *
* \param name Name of lvol * \param lvs Handle to lvolstore.
* \param sz size of lvol in bytes * \param name Name of lvol.
* \param thin_provisioned Enables thin provisioning * \param sz size of lvol in bytes.
* \param cb_fn Completion callback * \param thin_provisioned Enables thin provisioning.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \return error * \param cb_arg Completion callback custom arguments.
*
* \return 0 on success, negative errno on failure.
*/ */
int spdk_lvol_create(struct spdk_lvol_store *lvs, const char *name, uint64_t sz, int spdk_lvol_create(struct spdk_lvol_store *lvs, const char *name, uint64_t sz,
bool thin_provisioned, spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); bool thin_provisioned, spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg);
/** /**
* \brief Create snapshot of given lvol * Create snapshot of given lvol.
* \param lvol Handle to lvol *
* \param snapshot_name Name of created snapshot * \param lvol Handle to lvol.
* \param cb_fn Completion callback * \param snapshot_name Name of created snapshot.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/ */
void spdk_lvol_create_snapshot(struct spdk_lvol *lvol, const char *snapshot_name, void spdk_lvol_create_snapshot(struct spdk_lvol *lvol, const char *snapshot_name,
spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg);
/** /**
* \brief Create clone of given snapshot * Create clone of given snapshot.
* \param lvol Handle to lvol snapshot *
* \param clone_name Name of created clone * \param lvol Handle to lvol snapshot.
* \param cb_fn Completion callback * \param clone_name Name of created clone.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/ */
void spdk_lvol_create_clone(struct spdk_lvol *lvol, const char *clone_name, void spdk_lvol_create_clone(struct spdk_lvol *lvol, const char *clone_name,
spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg);
/** /**
* \brief Renames lvol with new_name. * Rename lvol with new_name.
* \param lvol Handle to lvol *
* \param new_name new name for lvol * \param lvol Handle to lvol.
* \param cb_fn Completion callback * \param new_name new name for lvol.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/ */
void void
spdk_lvol_rename(struct spdk_lvol *lvol, const char *new_name, spdk_lvol_rename(struct spdk_lvol *lvol, const char *new_name,
spdk_lvol_op_complete cb_fn, void *cb_arg); spdk_lvol_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Closes lvol and removes information about lvol from its lvolstore. * Close lvol and remove information about lvol from its lvolstore.
* \param lvol Handle to lvol *
* \param cb_fn Completion callback * \param lvol Handle to lvol.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/ */
void spdk_lvol_destroy(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); void spdk_lvol_destroy(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Closes lvol, but information is kept on lvolstore. * Close lvol, but information is kept on lvolstore.
* \param lvol Handle to lvol *
* \param cb_fn Completion callback * \param lvol Handle to lvol.
* \param cb_arg Completion callback custom arguments * \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/ */
void spdk_lvol_close(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg); void spdk_lvol_close(struct spdk_lvol *lvol, spdk_lvol_op_complete cb_fn, void *cb_arg);
/** /**
* \brief Return IO channel of bdev associated with specified lvol. * Get I/O channel of bdev associated with specified lvol.
* \param lvol Handle to lvol *
* \return IO channel * \param lvol Handle to lvol.
*
* \return a pointer to the I/O channel.
*/ */
struct spdk_io_channel *spdk_lvol_get_io_channel(struct spdk_lvol *lvol); struct spdk_io_channel *spdk_lvol_get_io_channel(struct spdk_lvol *lvol);
/**
* Load lvolstore from the given blobstore device.
*
* \param bs_dev Pointer to the blobstore device.
* \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/
void spdk_lvs_load(struct spdk_bs_dev *bs_dev, spdk_lvs_op_with_handle_complete cb_fn, void spdk_lvs_load(struct spdk_bs_dev *bs_dev, spdk_lvs_op_with_handle_complete cb_fn,
void *cb_arg); void *cb_arg);
/**
* Open a lvol.
*
* \param lvol Handle to lvol.
* \param cb_fn Completion callback.
* \param cb_arg Completion callback custom arguments.
*/
void spdk_lvol_open(struct spdk_lvol *lvol, spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg); void spdk_lvol_open(struct spdk_lvol *lvol, spdk_lvol_op_with_handle_complete cb_fn, void *cb_arg);
#ifdef __cplusplus #ifdef __cplusplus