From eca076240835f1fd5e15b6234a9f705b333d6569 Mon Sep 17 00:00:00 2001 From: Yanbo Zhou Date: Wed, 13 Dec 2017 10:52:07 +0800 Subject: [PATCH] include/blob.h:add comments for public APIs Change-Id: If630b2f897daa799324840af431ba7e5c9b25c6b Signed-off-by: Yanbo Zhou Reviewed-on: https://review.gerrithub.io/391514 Reviewed-by: GangCao Reviewed-by: Shuhei Matsumoto Tested-by: SPDK Automated Test System Reviewed-by: Daniel Verkamp Reviewed-by: Changpeng Liu --- include/spdk/blob.h | 387 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 347 insertions(+), 40 deletions(-) diff --git a/include/spdk/blob.h b/include/spdk/blob.h index e791e1e2d..415a8381e 100644 --- a/include/spdk/blob.h +++ b/include/spdk/blob.h @@ -52,7 +52,7 @@ * functions that may be called from a thread other than the metadata * thread. * - * The blob store returns errors using negated POSIX errno values, either + * The blobstore returns errors using negated POSIX errno values, either * returned in the callback or as a return value. An errno value of 0 means * success. */ @@ -169,54 +169,142 @@ struct spdk_bs_opts { void *iter_cb_arg; }; -/* Initialize an spdk_bs_opts structure to the default blobstore option values. */ +/** + * Initialize a spdk_bs_opts structure to the default blobstore option values. + * + * \param opts The spdk_bs_opts structure to be initialized. + */ void spdk_bs_opts_init(struct spdk_bs_opts *opts); -/* Load a blob store from the given device. This will fail (return NULL) if no blob store is present. */ +/** + * Load a blobstore from the given device. + * + * \param dev Blobstore block device. + * \param opts The structure which contains the option values for the blobstore. + * \param cb_fn Called when the loading is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_load(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts, spdk_bs_op_with_handle_complete cb_fn, void *cb_arg); -/* Initialize a blob store on the given disk. Destroys all data present on the device. */ +/** + * Initialize a blobstore on the given device. + * + * \param dev Blobstore block device. + * \param opts The structure which contains the option values for the blobstore. + * \param cb_fn Called when the initialization is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_init(struct spdk_bs_dev *dev, struct spdk_bs_opts *opts, spdk_bs_op_with_handle_complete cb_fn, void *cb_arg); -/* Destroy a blob store by zeroing the metadata and freeing in-memory structures. +/** + * Destroy the blobstore. + * + * It will destroy the blobstore by zeroing the super block. + * + * \param bs blobstore to destroy. + * \param cb_fn Called when the destruction is complete. + * \param cb_arg Argument passed to function cb_fn. */ void spdk_bs_destroy(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg); -/* Flush all volatile data to disk and free in-memory structures. */ +/** + * Unload the blobstore. + * + * It will flush all volatile data to disk. + * + * \param bs blobstore to unload. + * \param cb_fn Called when the unloading is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_unload(struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg); -/* Set the given blob as the super blob. This will be retrievable immediately after an - * spdk_bs_load on the next initialization. +/** + * Set a super blob on the given blobstore. + * + * This will be retrievable immediately after spdk_bs_load() on the next initializaiton. + * + * \param bs blobstore. + * \param blobid The id of the blob which will be set as the super blob. + * \param cb_fn Called when the setting is complete. + * \param cb_arg Argument passed to function cb_fn. */ void spdk_bs_set_super(struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_bs_op_complete cb_fn, void *cb_arg); -/* Open the super blob. */ +/** + * Get the super blob. The obtained blob id will be passed to the callback function. + * + * \param bs blobstore. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_get_super(struct spdk_blob_store *bs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg); -/* Get the cluster size in bytes. Used in the extend operation. */ +/** + * Get the cluster size in bytes. + * + * \param bs blobstore to query. + * + * \return cluster size. + */ uint64_t spdk_bs_get_cluster_size(struct spdk_blob_store *bs); -/* Get the page size in bytes. This is the write and read granularity of blobs. */ +/** + * Get the page size in bytes. This is the write and read granularity of blobs. + * + * \param bs blobstore to query. + * + * \return page size. + */ uint64_t spdk_bs_get_page_size(struct spdk_blob_store *bs); -/* Get the number of free clusters. */ +/** + * Get the number of free clusters. + * + * \param bs blobstore to query. + * + * \return the number of free clusters. + */ uint64_t spdk_bs_free_cluster_count(struct spdk_blob_store *bs); -/* Get the total number of clusters accessible by user. */ +/** + * Get the total number of clusters accessible by user. + * + * \param bs blobstore to query. + * + * \return the total number of clusters accessible by user. + */ uint64_t spdk_bs_total_data_cluster_count(struct spdk_blob_store *bs); -/* Return the blobid */ +/** + * Get the blob id. + * + * \param blob Blob struct to query. + * + * \return blob id. + */ spdk_blob_id spdk_blob_get_id(struct spdk_blob *blob); -/* Return the number of pages allocated to the blob */ +/** + * Get the number of pages allocated to the blob. + * + * \param blob Blob struct to query. + * + * \return the number of pages. + */ uint64_t spdk_blob_get_num_pages(struct spdk_blob *blob); -/* Return the number of clusters allocated to the blob */ +/** + * Get the number of clusters allocated to the blob. + * + * \param blob Blob struct to query. + * + * \return the number of clusters. + */ uint64_t spdk_blob_get_num_clusters(struct spdk_blob *blob); struct spdk_blob_xattr_opts { @@ -237,77 +325,202 @@ struct spdk_blob_opts { struct spdk_blob_xattr_opts xattrs; }; -/* Initialize an spdk_blob_opts structure to the default blob option values. */ +/** + * Initialize a spdk_blob_opts structure to the default blob option values. + * + * \param opts spdk_blob_opts structure to initialize. + */ void spdk_blob_opts_init(struct spdk_blob_opts *opts); -/* Create a new blob with options. */ +/** + * Create a new blob with options on the given blobstore. The new blob id will + * be passed to the callback function. + * + * \param bs blobstore. + * \param opts The structure which contains the option values for the new blob. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to funcion cb_fn. + */ void spdk_bs_create_blob_ext(struct spdk_blob_store *bs, const struct spdk_blob_opts *opts, spdk_blob_op_with_id_complete cb_fn, void *cb_arg); -/* Create a new blob. */ +/** + * Create a new blob with default option values on the given blobstore. + * The new blob id will be passed to the callback function. + * + * \param bs blobstore. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_create_blob(struct spdk_blob_store *bs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg); -/* Delete an existing blob. */ +/** + * Delete an existing blob from the given blobstore. + * + * \param bs blobstore. + * \param blobid The id of the blob to delete. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_delete_blob(struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Open a blob */ +/** + * Open a blob from the given blobstore. + * + * \param bs blobstore. + * \param blobid The id of the blob to open. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_open_blob(struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); -/* Resize a blob to 'sz' clusters. +/** + * Resize a blob to 'sz' clusters. These changes are not persisted to disk until + * spdk_bs_md_sync_blob() is called. * - * These changes are not persisted to disk until - * spdk_blob_sync_md() is called. */ + * \param blob Blob to resize. + * \param sz The new number of clusters. + * + * \return 0 on success, negative errno on failure. + */ int spdk_blob_resize(struct spdk_blob *blob, size_t sz); -/* Set blob as read only. +/** + * Set blob as read only. * - * These changes do not take effect until - * spdk_blob_sync_md() is called. */ - + * These changes do not take effect until spdk_blob_sync_md() is called. + * + * \param blob Blob to set. + */ int spdk_blob_set_read_only(struct spdk_blob *blob); -/* Sync a blob */ -/* Make a blob persistent. This applies to resize, set xattr, - * and remove xattr. These operations will not be persistent until - * the blob has been synced. +/** + * Sync a blob. + * + * Make a blob persistent. This applies to open, resize, set xattr, and remove + * xattr. These operations will not be persistent until the blob has been synced. + * + * \param blob Blob to sync. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. */ void spdk_blob_sync_md(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Close a blob. This will automatically sync. */ +/** + * Close a blob. This will automatically sync. + * + * \param blob Blob to close. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_close(struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg); +/** + * Allocate an I/O channel for the given blobstore. + * + * \param bs blobstore. + * \return a pointer to the allocated I/O channel. + */ struct spdk_io_channel *spdk_bs_alloc_io_channel(struct spdk_blob_store *bs); +/** + * Free the I/O channel. + * + * \param channel I/O channel to free. + */ void spdk_bs_free_io_channel(struct spdk_io_channel *channel); -/* Write data to a blob. Offset is in pages from the beginning of the blob. */ +/** + * Write data to a blob. + * + * \param blob Blob to write. + * \param channel The I/O channel used to submit requests. + * \param payload The specified buffer which should contain the data to be written. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of data in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_write(struct spdk_blob *blob, struct spdk_io_channel *channel, void *payload, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Read data from a blob. Offset is in pages from the beginning of the blob. */ +/** + * Read data from a blob. + * + * \param blob Blob to read. + * \param channel The I/O channel used to submit requests. + * \param payload The specified buffer which will store the obtained data. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of data in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_read(struct spdk_blob *blob, struct spdk_io_channel *channel, void *payload, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Write data to a blob. Offset is in pages from the beginning of the blob. */ +/** + * Write the data described by 'iov' to 'length' pages beginning at 'offset' pages + * into the blob. + * + * \param blob Blob to write. + * \param channel I/O channel used to submit requests. + * \param iov The pointer points to an array of iovec structures. + * \param iovcnt The number of buffers. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of data in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_writev(struct spdk_blob *blob, struct spdk_io_channel *channel, struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Read data from a blob. Offset is in pages from the beginning of the blob. */ +/** + * Read 'length' pages starting at 'offset' pages into the blob into the memory + * described by 'iov'. + * + * \param blob Blob to read. + * \param channel I/O channel used to submit requests. + * \param iov The pointer points to an array of iovec structures. + * \param iovcnt The number of buffers. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of data in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_readv(struct spdk_blob *blob, struct spdk_io_channel *channel, struct iovec *iov, int iovcnt, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Unmap area of a blob. Offset is in pages from the beginning of the blob. */ +/** + * Unmap 'length' pages beginning at 'offset' pages on the blob as unused. Unmapped + * pages may allow the underlying storage media to behave more effciently. + * + * \param blob Blob to unmap. + * \param channel I/O channel used to submit requests. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of unmap area in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_unmap(struct spdk_blob *blob, struct spdk_io_channel *channel, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); -/* Write zeros into area of a blob. Offset is in pages from the beginning of the blob. */ +/** + * Write zeros into area of a blob. + * + * \param blob Blob to write. + * \param channel I/O channel used to submit requests. + * \param offset Offset is in pages from the beginning of the blob. + * \param length Size of data in pages. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_blob_io_write_zeroes(struct spdk_blob *blob, struct spdk_io_channel *channel, uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg); @@ -334,24 +547,118 @@ void spdk_bs_io_write_zeroes_blob(struct spdk_blob *blob, struct spdk_io_channel uint64_t offset, uint64_t length, spdk_blob_op_complete cb_fn, void *cb_arg) __attribute__((deprecated)); -/* Iterate through all blobs */ +/** + * Get the first blob of the blobstore. The obtained blob will be passed to + * the callback function. + * + * \param bs blobstore to traverse. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_iter_first(struct spdk_blob_store *bs, spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); + +/** + * Get the next blob by using the current blob. The obtained blob will be passed + * to the callback function. + * + * \param bs blobstore to traverse. + * \param blob The current blob. + * \param cb_fn Called when the operation is complete. + * \param cb_arg Argument passed to function cb_fn. + */ void spdk_bs_iter_next(struct spdk_blob_store *bs, struct spdk_blob *blob, spdk_blob_op_with_handle_complete cb_fn, void *cb_arg); +/** + * Set an extended attribute for the given blob. + * + * \param blob Blob to set attribute. + * \param name Name of the extended attribute. + * \param value Value of the extended attribute. + * \param value_len Length of the value. + * + * \return 0 on success, -1 on failure. + */ int spdk_blob_set_xattr(struct spdk_blob *blob, const char *name, const void *value, uint16_t value_len); + +/** + * Remove the extended attribute from the given blob. + * + * \param blob Blob to remove attribute. + * \param name Name of the extended attribute. + * + * \return 0 on success, negative errno on failure. + */ int spdk_blob_remove_xattr(struct spdk_blob *blob, const char *name); + +/** + * Get the value of the specified extended attribute. The obtained value and its + * size will be stored in value and value_len. + * + * \param blob Blob to query. + * \param name Name of the extended attribute. + * \param value Parameter as output. + * \param value_len Parameter as output. + * + * \return 0 on success, negative errno on failure. + */ int spdk_blob_get_xattr_value(struct spdk_blob *blob, const char *name, const void **value, size_t *value_len); + +/** + * Iterate through all extended attributes of the blob. Get the names of all extended + * attributes that will be stored in names. + * + * \param blob Blob to query. + * \param names Parameter as output. + * + * \return 0 on success, negative errno on failure. + */ int spdk_blob_get_xattr_names(struct spdk_blob *blob, struct spdk_xattr_names **names); +/** + * Get the number of extended attributes. + * + * \param names Names of total extended attributes of the blob. + * + * \return the number of extended attributes. + */ uint32_t spdk_xattr_names_get_count(struct spdk_xattr_names *names); + +/** + * Get the attribute name specified by the index. + * + * \param names Names of total extended attributes of the blob. + * \param index Index position of the specified attribute. + * + * \return attribute name. + */ const char *spdk_xattr_names_get_name(struct spdk_xattr_names *names, uint32_t index); + +/** + * Free the attribute names. + * + * \param names Names of total extended attributes of the blob. + */ void spdk_xattr_names_free(struct spdk_xattr_names *names); +/** + * Get blobstore type of the given device. + * + * \param bs blobstore to query. + * + * \return blobstore type. + */ struct spdk_bs_type spdk_bs_get_bstype(struct spdk_blob_store *bs); + +/** + * Set blobstore type to the given device. + * + * \param bs blobstore to set to. + * \param bstype Type label to set. + */ void spdk_bs_set_bstype(struct spdk_blob_store *bs, struct spdk_bs_type bstype); #ifdef __cplusplus