d/numam-spdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

include/blob.h:add comments for public APIs

Browse Source 
Change-Id: If630b2f897daa799324840af431ba7e5c9b25c6b
Signed-off-by: Yanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/391514
Reviewed-by: GangCao <gang.cao@intel.com>
Reviewed-by: Shuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Tested-by: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: Daniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: Changpeng Liu <changpeng.liu@intel.com>
This commit is contained in:
Yanbo Zhou 2017-12-13 10:52:07 +08:00 committed by Changpeng Liu
parent d076dcfb44
commit eca0762408
1 changed files with 347 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

387
include/spdk/blob.h
View File

@ -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