Commit eca07624 authored by Yanbo Zhou's avatar Yanbo Zhou Committed by Changpeng Liu
Browse files

include/blob.h:add comments for public APIs 



Change-Id: If630b2f897daa799324840af431ba7e5c9b25c6b
Signed-off-by: default avatarYanbo Zhou <yanbo.zhou@intel.com>
Reviewed-on: https://review.gerrithub.io/391514


Reviewed-by: default avatarGangCao <gang.cao@intel.com>
Reviewed-by: default avatarShuhei Matsumoto <shuhei.matsumoto.xt@hitachi.com>
Tested-by: default avatarSPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: default avatarDaniel Verkamp <daniel.verkamp@intel.com>
Reviewed-by: default avatarChangpeng Liu <changpeng.liu@intel.com>
parent d076dcfb

include/spdk/blob.h

+347 −40
Original line number Diff line number Diff line
@@ -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.

 *

 * \param blob Blob to resize.

 * \param sz The new number of clusters.

 *

 * These changes are not persisted to disk until

 * spdk_blob_sync_md() is called. */

 * \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