blob.h File Reference

Blob Storage System. More...

Data Structures

struct  spdk_bs_dev_cb_args
 
struct  spdk_blob_ext_io_opts
 Structure with optional IO request parameters The content of this structure must be valid until the IO request is completed. More...
 
struct  spdk_bs_dev
 
struct  spdk_bs_type
 
struct  spdk_bs_opts
 
struct  spdk_blob_xattr_opts
 
struct  spdk_blob_opts
 
struct  spdk_blob_open_opts
 

Macros

#define SPDK_BLOBID_INVALID   (uint64_t)-1
 
#define SPDK_BLOBID_EXTERNAL_SNAPSHOT   (uint64_t)-2
 
#define SPDK_BLOBSTORE_TYPE_LENGTH   16
 

Typedefs

typedef uint64_t spdk_blob_id
 
typedef void(* spdk_bs_op_complete) (void *cb_arg, int bserrno)
 Blobstore operation completion callback. More...
 
typedef void(* spdk_bs_op_with_handle_complete) (void *cb_arg, struct spdk_blob_store *bs, int bserrno)
 Blobstore operation completion callback with handle. More...
 
typedef void(* spdk_blob_op_complete) (void *cb_arg, int bserrno)
 Blob operation completion callback. More...
 
typedef void(* spdk_blob_op_with_id_complete) (void *cb_arg, spdk_blob_id blobid, int bserrno)
 Blob operation completion callback with blob ID. More...
 
typedef void(* spdk_blob_op_with_handle_complete) (void *cb_arg, struct spdk_blob *blb, int bserrno)
 Blob operation completion callback with handle. More...
 
typedef void(* spdk_bs_dev_cpl) (struct spdk_io_channel *channel, void *cb_arg, int bserrno)
 Blobstore device completion callback. More...
 
typedef void(* spdk_blob_op_with_bs_dev) (void *cb_arg, struct spdk_bs_dev *bs_dev, int bserrno)
 Blob device open completion callback with blobstore device. More...
 
typedef int(* spdk_bs_esnap_dev_create) (void *bs_ctx, void *blob_ctx, struct spdk_blob *blob, const void *esnap_id, uint32_t id_size, struct spdk_bs_dev **bs_dev)
 External snapshot device open callback. More...
 
typedef void(* spdk_bs_dump_print_xattr) (FILE *fp, const char *bstype, const char *name, const void *value, size_t value_length)
 

Enumerations

enum  blob_clear_method { BLOB_CLEAR_WITH_DEFAULT , BLOB_CLEAR_WITH_NONE , BLOB_CLEAR_WITH_UNMAP , BLOB_CLEAR_WITH_WRITE_ZEROES }
 
enum  bs_clear_method { BS_CLEAR_WITH_UNMAP , BS_CLEAR_WITH_WRITE_ZEROES , BS_CLEAR_WITH_NONE }
 

Functions

 SPDK_STATIC_ASSERT (sizeof(struct spdk_blob_ext_io_opts)==32, "Incorrect size")
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_bs_opts)==88, "Incorrect size")
 
void spdk_bs_opts_init (struct spdk_bs_opts *opts, size_t opts_size)
 Initialize a spdk_bs_opts structure to the default blobstore option values. More...
 
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)
 Load a blobstore from the given device. More...
 
void spdk_bs_grow (struct spdk_bs_dev *dev, struct spdk_bs_opts *opts, spdk_bs_op_with_handle_complete cb_fn, void *cb_arg)
 Grow a blobstore to fill the underlying device Cannot be used on loaded blobstore. More...
 
void spdk_bs_grow_live (struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg)
 Grow a blobstore to fill the underlying device. More...
 
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)
 Initialize a blobstore on the given device. More...
 
void spdk_bs_dump (struct spdk_bs_dev *dev, FILE *fp, spdk_bs_dump_print_xattr print_xattr_fn, spdk_bs_op_complete cb_fn, void *cb_arg)
 Dump a blobstore's metadata to a given FILE in human-readable format. More...
 
void spdk_bs_destroy (struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg)
 Destroy the blobstore. More...
 
void spdk_bs_unload (struct spdk_blob_store *bs, spdk_bs_op_complete cb_fn, void *cb_arg)
 Unload the blobstore. More...
 
void spdk_bs_set_super (struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_bs_op_complete cb_fn, void *cb_arg)
 Set a super blob on the given blobstore. More...
 
void spdk_bs_get_super (struct spdk_blob_store *bs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg)
 Get the super blob. More...
 
uint64_t spdk_bs_get_cluster_size (struct spdk_blob_store *bs)
 Get the cluster size in bytes. More...
 
uint64_t spdk_bs_get_page_size (struct spdk_blob_store *bs)
 Get the page size in bytes. More...
 
uint64_t spdk_bs_get_io_unit_size (struct spdk_blob_store *bs)
 Get the io unit size in bytes. More...
 
uint64_t spdk_bs_free_cluster_count (struct spdk_blob_store *bs)
 Get the number of free clusters. More...
 
uint64_t spdk_bs_total_data_cluster_count (struct spdk_blob_store *bs)
 Get the total number of clusters accessible by user. More...
 
spdk_blob_id spdk_blob_get_id (struct spdk_blob *blob)
 Get the blob id. More...
 
uint64_t spdk_blob_get_num_pages (struct spdk_blob *blob)
 Get the number of pages allocated to the blob. More...
 
uint64_t spdk_blob_get_num_io_units (struct spdk_blob *blob)
 Get the number of io_units allocated to the blob. More...
 
uint64_t spdk_blob_get_num_clusters (struct spdk_blob *blob)
 Get the number of clusters allocated to the blob. More...
 
uint64_t spdk_blob_get_next_allocated_io_unit (struct spdk_blob *blob, uint64_t offset)
 Get next allocated io_unit. More...
 
uint64_t spdk_blob_get_next_unallocated_io_unit (struct spdk_blob *blob, uint64_t offset)
 Get next unallocated io_unit. More...
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_blob_opts)==80, "Incorrect size")
 
void spdk_blob_opts_init (struct spdk_blob_opts *opts, size_t opts_size)
 Initialize a spdk_blob_opts structure to the default blob option values. More...
 
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 with options on the given blobstore. More...
 
void spdk_bs_create_blob (struct spdk_blob_store *bs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg)
 Create a new blob with default option values on the given blobstore. More...
 
void spdk_bs_create_snapshot (struct spdk_blob_store *bs, spdk_blob_id blobid, const struct spdk_blob_xattr_opts *snapshot_xattrs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg)
 Create a read-only snapshot of specified blob with provided options. More...
 
void spdk_bs_create_clone (struct spdk_blob_store *bs, spdk_blob_id blobid, const struct spdk_blob_xattr_opts *clone_xattrs, spdk_blob_op_with_id_complete cb_fn, void *cb_arg)
 Create a clone of specified read-only blob. More...
 
int spdk_blob_get_clones (struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_id *ids, size_t *count)
 Provide table with blob id's of clones are dependent on specified snapshot. More...
 
spdk_blob_id spdk_blob_get_parent_snapshot (struct spdk_blob_store *bs, spdk_blob_id blobid)
 Get the blob id for the parent snapshot of this blob. More...
 
int spdk_blob_get_esnap_id (struct spdk_blob *blob, const void **id, size_t *len)
 Get the id used to access the esnap clone's parent. More...
 
bool spdk_blob_is_read_only (struct spdk_blob *blob)
 Check if blob is read only. More...
 
bool spdk_blob_is_snapshot (struct spdk_blob *blob)
 Check if blob is a snapshot. More...
 
bool spdk_blob_is_clone (struct spdk_blob *blob)
 Check if blob is a clone of a blob. More...
 
bool spdk_blob_is_thin_provisioned (struct spdk_blob *blob)
 Check if blob is thin-provisioned. More...
 
bool spdk_blob_is_esnap_clone (const struct spdk_blob *blob)
 Check if blob is a clone of an external snapshot. More...
 
void spdk_bs_delete_blob (struct spdk_blob_store *bs, spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg)
 Delete an existing blob from the given blobstore. More...
 
void spdk_bs_inflate_blob (struct spdk_blob_store *bs, struct spdk_io_channel *channel, spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg)
 Allocate all clusters in this blob. More...
 
void spdk_bs_blob_decouple_parent (struct spdk_blob_store *bs, struct spdk_io_channel *channel, spdk_blob_id blobid, spdk_blob_op_complete cb_fn, void *cb_arg)
 Remove dependency on parent blob. More...
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_blob_open_opts)==24, "Incorrect size")
 
void spdk_blob_open_opts_init (struct spdk_blob_open_opts *opts, size_t opts_size)
 Initialize a spdk_blob_open_opts structure to the default blob option values. More...
 
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)
 Open a blob from the given blobstore. More...
 
void spdk_bs_open_blob_ext (struct spdk_blob_store *bs, spdk_blob_id blobid, struct spdk_blob_open_opts *opts, spdk_blob_op_with_handle_complete cb_fn, void *cb_arg)
 Open a blob from the given blobstore with additional options. More...
 
void spdk_blob_resize (struct spdk_blob *blob, uint64_t sz, spdk_blob_op_complete cb_fn, void *cb_arg)
 Resize a blob to 'sz' clusters. More...
 
int spdk_blob_set_read_only (struct spdk_blob *blob)
 Set blob as read only. More...
 
void spdk_blob_sync_md (struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg)
 Sync a blob. More...
 
void spdk_blob_close (struct spdk_blob *blob, spdk_blob_op_complete cb_fn, void *cb_arg)
 Close a blob. More...
 
struct spdk_io_channel * spdk_bs_alloc_io_channel (struct spdk_blob_store *bs)
 Allocate an I/O channel for the given blobstore. More...
 
void spdk_bs_free_io_channel (struct spdk_io_channel *channel)
 Free the I/O channel. More...
 
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)
 Write data to a blob. More...
 
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)
 Read data from a blob. More...
 
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)
 Write the data described by 'iov' to 'length' io_units beginning at 'offset' io_units into the blob. More...
 
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)
 Read 'length' io_units starting at 'offset' io_units into the blob into the memory described by 'iov'. More...
 
void spdk_blob_io_writev_ext (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, struct spdk_blob_ext_io_opts *io_opts)
 Write the data described by 'iov' to 'length' io_units beginning at 'offset' io_units into the blob. More...
 
void spdk_blob_io_readv_ext (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, struct spdk_blob_ext_io_opts *io_opts)
 Read 'length' io_units starting at 'offset' io_units into the blob into the memory described by 'iov'. More...
 
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)
 Unmap 'length' io_units beginning at 'offset' io_units on the blob as unused. More...
 
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)
 Write zeros into area of a blob. More...
 
void spdk_bs_iter_first (struct spdk_blob_store *bs, spdk_blob_op_with_handle_complete cb_fn, void *cb_arg)
 Get the first blob of the blobstore. More...
 
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)
 Get the next blob by using the current blob. More...
 
int spdk_blob_set_xattr (struct spdk_blob *blob, const char *name, const void *value, uint16_t value_len)
 Set an extended attribute for the given blob. More...
 
int spdk_blob_remove_xattr (struct spdk_blob *blob, const char *name)
 Remove the extended attribute from the given blob. More...
 
int spdk_blob_get_xattr_value (struct spdk_blob *blob, const char *name, const void **value, size_t *value_len)
 Get the value of the specified extended attribute. More...
 
int spdk_blob_get_xattr_names (struct spdk_blob *blob, struct spdk_xattr_names **names)
 Iterate through all extended attributes of the blob. More...
 
uint32_t spdk_xattr_names_get_count (struct spdk_xattr_names *names)
 Get the number of extended attributes. More...
 
const char * spdk_xattr_names_get_name (struct spdk_xattr_names *names, uint32_t index)
 Get the attribute name specified by the index. More...
 
void spdk_xattr_names_free (struct spdk_xattr_names *names)
 Free the attribute names. More...
 
struct spdk_bs_type spdk_bs_get_bstype (struct spdk_blob_store *bs)
 Get blobstore type of the given device. More...
 
void spdk_bs_set_bstype (struct spdk_blob_store *bs, struct spdk_bs_type bstype)
 Set blobstore type to the given device. More...
 
void spdk_blob_set_esnap_bs_dev (struct spdk_blob *blob, struct spdk_bs_dev *back_bs_dev, spdk_blob_op_complete cb_fn, void *cb_arg)
 Replace the existing external snapshot device. More...
 
struct spdk_bs_devspdk_blob_get_esnap_bs_dev (const struct spdk_blob *blob)
 Get the existing external snapshot device. More...
 
bool spdk_blob_is_degraded (const struct spdk_blob *blob)
 Determine if the blob is degraded. More...
 

Detailed Description

Blob Storage System.

The blob storage system, or the blobstore for short, is a low level library for placing opaque blobs of data onto a storage device such that scattered physical blocks on the storage device appear as a single, contiguous storage region. These blobs are also persistent, which means they are rediscoverable after reboot or power loss.

The blobstore is designed to be very high performance, and thus has a few general rules regarding thread safety to avoid taking locks in the I/O path. This is primarily done by only allowing most functions to be called on the metadata thread. The metadata thread is the thread which called spdk_bs_init() or spdk_bs_load().

Functions starting with the prefix "spdk_blob_io" are passed a channel as an argument, and channels may only be used from the thread they were created on. See spdk_bs_alloc_io_channel. These are the only functions that may be called from a thread other than the metadata thread.

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.

Typedef Documentation

◆ spdk_blob_op_complete

typedef void(* spdk_blob_op_complete) (void *cb_arg, int bserrno)

Blob operation completion callback.

Parameters
cb_argCallback argument.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_blob_op_with_bs_dev

typedef void(* spdk_blob_op_with_bs_dev) (void *cb_arg, struct spdk_bs_dev *bs_dev, int bserrno)

Blob device open completion callback with blobstore device.

Parameters
cb_argCallback argument.
bs_devBlobstore device.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_blob_op_with_handle_complete

typedef void(* spdk_blob_op_with_handle_complete) (void *cb_arg, struct spdk_blob *blb, int bserrno)

Blob operation completion callback with handle.

Parameters
cb_argCallback argument.
blbHandle to a blob.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_blob_op_with_id_complete

typedef void(* spdk_blob_op_with_id_complete) (void *cb_arg, spdk_blob_id blobid, int bserrno)

Blob operation completion callback with blob ID.

Parameters
cb_argCallback argument.
blobidBlob ID.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_bs_dev_cpl

typedef void(* spdk_bs_dev_cpl) (struct spdk_io_channel *channel, void *cb_arg, int bserrno)

Blobstore device completion callback.

Parameters
channelI/O channel the operation was initiated on.
cb_argCallback argument.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_bs_esnap_dev_create

typedef int(* spdk_bs_esnap_dev_create) (void *bs_ctx, void *blob_ctx, struct spdk_blob *blob, const void *esnap_id, uint32_t id_size, struct spdk_bs_dev **bs_dev)

External snapshot device open callback.

As an esnap clone blob is loading, it uses this callback registered with the blobstore to create the external snapshot device. The blobstore consumer must set this while loading the blobstore if it intends to support external snapshots.

If the blobstore consumer does not wish to load an external snapshot, it should set *bs_dev to NULL and return 0.

Parameters
bs_ctxContext provided by the blobstore consumer via esnap_ctx member of struct spdk_bs_opts.
blob_ctxContext provided to spdk_bs_open_ext() via esnap_ctx member of struct spdk_bs_open_opts.
blobThe blob that needs its external snapshot device.
esnap_idA copy of the esnap_id passed via blob_opts when creating the esnap clone.
id_sizeThe size in bytes of the data referenced by esnap_id.
bs_devWhen 0 is returned, the newly created blobstore device is returned by reference.
Returns
0 on success, else a negative errno.

◆ spdk_bs_op_complete

typedef void(* spdk_bs_op_complete) (void *cb_arg, int bserrno)

Blobstore operation completion callback.

Parameters
cb_argCallback argument.
bserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_bs_op_with_handle_complete

typedef void(* spdk_bs_op_with_handle_complete) (void *cb_arg, struct spdk_blob_store *bs, int bserrno)

Blobstore operation completion callback with handle.

Parameters
cb_argCallback argument.
bsHandle to a blobstore.
bserrno0 if it completed successfully, or negative errno if it failed.

Function Documentation

◆ spdk_blob_close()

void spdk_blob_close ( struct spdk_blob *  blob,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Close a blob.

This will automatically sync.

Parameters
blobBlob to close.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_get_clones()

int spdk_blob_get_clones ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
spdk_blob_id *  ids,
size_t *  count 
)

Provide table with blob id's of clones are dependent on specified snapshot.

Ids array should be allocated and the count parameter set to the number of id's it can store, before calling this function.

If ids is NULL or count parameter is not sufficient to handle ids of all clones, -ENOMEM error is returned and count parameter is updated to the total number of clones.

Parameters
bsblobstore.
blobidSnapshots blob id.
idsArray of the clone ids or NULL to get required size in count.
countSize of ids. After call it is updated to the number of clones.
Returns
-ENOMEM if count is not sufficient to store all clones.

◆ spdk_blob_get_esnap_bs_dev()

struct spdk_bs_dev* spdk_blob_get_esnap_bs_dev ( const struct spdk_blob *  blob)

Get the existing external snapshot device.

Parameters
blobA blob that is an esnap clone
Returns
NULL if the blob is not an esnap clone, else the current external snapshot device.

◆ spdk_blob_get_esnap_id()

int spdk_blob_get_esnap_id ( struct spdk_blob *  blob,
const void **  id,
size_t *  len 
)

Get the id used to access the esnap clone's parent.

Parameters
blobThe clone's blob.
idOn successful return, *id will reference memory that has the same life as blob.
lenOn successful return *len will be the size of id in bytes.
Returns
0 on success
-EINVAL if blob is not an esnap clone.

◆ spdk_blob_get_id()

spdk_blob_id spdk_blob_get_id ( struct spdk_blob *  blob)

Get the blob id.

Parameters
blobBlob struct to query.
Returns
blob id.

◆ spdk_blob_get_next_allocated_io_unit()

uint64_t spdk_blob_get_next_allocated_io_unit ( struct spdk_blob *  blob,
uint64_t  offset 
)

Get next allocated io_unit.

Starting at 'offset' io_units into the blob, returns the offset of the first allocated io unit found. If 'offset' points to an allocated io_unit, same offset is returned.

Parameters
blobBlob struct to query.
offsetOffset is in io units from the beginning of the blob.
Returns
offset in io_units or UINT64_MAX if no allocated io_unit found

◆ spdk_blob_get_next_unallocated_io_unit()

uint64_t spdk_blob_get_next_unallocated_io_unit ( struct spdk_blob *  blob,
uint64_t  offset 
)

Get next unallocated io_unit.

Starting at 'offset' io_units into the blob, returns the offset of the first unallocated io unit found. If 'offset' points to an unallocated io_unit, same offset is returned.

Parameters
blobBlob struct to query.
offsetOffset is in io units from the beginning of the blob.
Returns
offset in io_units or UINT64_MAX if only allocated io_unit found

◆ spdk_blob_get_num_clusters()

uint64_t spdk_blob_get_num_clusters ( struct spdk_blob *  blob)

Get the number of clusters allocated to the blob.

Parameters
blobBlob struct to query.
Returns
the number of clusters.

◆ spdk_blob_get_num_io_units()

uint64_t spdk_blob_get_num_io_units ( struct spdk_blob *  blob)

Get the number of io_units allocated to the blob.

Parameters
blobBlob struct to query.
Returns
the number of io_units.

◆ spdk_blob_get_num_pages()

uint64_t spdk_blob_get_num_pages ( struct spdk_blob *  blob)

Get the number of pages allocated to the blob.

Parameters
blobBlob struct to query.
Returns
the number of pages.

◆ spdk_blob_get_parent_snapshot()

spdk_blob_id spdk_blob_get_parent_snapshot ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid 
)

Get the blob id for the parent snapshot of this blob.

Parameters
bsblobstore.
blobidBlob id.
Returns
blob id of parent blob or SPDK_BLOBID_INVALID if have no parent

◆ spdk_blob_get_xattr_names()

int spdk_blob_get_xattr_names ( struct spdk_blob *  blob,
struct spdk_xattr_names **  names 
)

Iterate through all extended attributes of the blob.

Get the names of all extended attributes that will be stored in names.

Parameters
blobBlob to query.
namesParameter as output.
Returns
0 on success, negative errno on failure.

◆ spdk_blob_get_xattr_value()

int spdk_blob_get_xattr_value ( struct spdk_blob *  blob,
const char *  name,
const void **  value,
size_t *  value_len 
)

Get the value of the specified extended attribute.

The obtained value and its size will be stored in value and value_len.

Parameters
blobBlob to query.
nameName of the extended attribute.
valueParameter as output.
value_lenParameter as output.
Returns
0 on success, negative errno on failure.

◆ spdk_blob_io_read()

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 
)

Read data from a blob.

Parameters
blobBlob to read.
channelThe I/O channel used to submit requests.
payloadThe specified buffer which will store the obtained data.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_readv()

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 
)

Read 'length' io_units starting at 'offset' io_units into the blob into the memory described by 'iov'.

Parameters
blobBlob to read.
channelI/O channel used to submit requests.
iovThe pointer points to an array of iovec structures.
iovcntThe number of buffers.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_readv_ext()

void spdk_blob_io_readv_ext ( 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,
struct spdk_blob_ext_io_opts io_opts 
)

Read 'length' io_units starting at 'offset' io_units into the blob into the memory described by 'iov'.

Accepts extended IO request options

Parameters
blobBlob to read.
channelI/O channel used to submit requests.
iovThe pointer points to an array of iovec structures.
iovcntThe number of buffers.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.
io_optsOptional extended IO request options

◆ spdk_blob_io_unmap()

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 
)

Unmap 'length' io_units beginning at 'offset' io_units on the blob as unused.

Unmapped io_units may allow the underlying storage media to behave more efficiently.

Parameters
blobBlob to unmap.
channelI/O channel used to submit requests.
offsetOffset is in io units from the beginning of the blob.
lengthSize of unmap area in io_units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_write()

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 
)

Write data to a blob.

Parameters
blobBlob to write.
channelThe I/O channel used to submit requests.
payloadThe specified buffer which should contain the data to be written.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_write_zeroes()

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 
)

Write zeros into area of a blob.

Parameters
blobBlob to write.
channelI/O channel used to submit requests.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_writev()

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 
)

Write the data described by 'iov' to 'length' io_units beginning at 'offset' io_units into the blob.

Parameters
blobBlob to write.
channelI/O channel used to submit requests.
iovThe pointer points to an array of iovec structures.
iovcntThe number of buffers.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_io_writev_ext()

void spdk_blob_io_writev_ext ( 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,
struct spdk_blob_ext_io_opts io_opts 
)

Write the data described by 'iov' to 'length' io_units beginning at 'offset' io_units into the blob.

Accepts extended IO request options

Parameters
blobBlob to write.
channelI/O channel used to submit requests.
iovThe pointer points to an array of iovec structures.
iovcntThe number of buffers.
offsetOffset is in io units from the beginning of the blob.
lengthSize of data in io units.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.
io_optsOptional extended IO request options

◆ spdk_blob_is_clone()

bool spdk_blob_is_clone ( struct spdk_blob *  blob)

Check if blob is a clone of a blob.

Clones of external snapshots will return false. See spdk_blob_is_esnap_clone.

Parameters
blobBlob.
Returns
true if blob is a clone of a blob.

◆ spdk_blob_is_degraded()

bool spdk_blob_is_degraded ( const struct spdk_blob *  blob)

Determine if the blob is degraded.

A degraded blob cannot perform IO.

Parameters
blobA blob
Returns
true if the blob or any snapshots upon which it depends are degraded, else false.

◆ spdk_blob_is_esnap_clone()

bool spdk_blob_is_esnap_clone ( const struct spdk_blob *  blob)

Check if blob is a clone of an external snapshot.

Parameters
blobBlob.
Returns
true if blob is a clone of an external bdev.

◆ spdk_blob_is_read_only()

bool spdk_blob_is_read_only ( struct spdk_blob *  blob)

Check if blob is read only.

Parameters
blobBlob.
Returns
true if blob is read only.

◆ spdk_blob_is_snapshot()

bool spdk_blob_is_snapshot ( struct spdk_blob *  blob)

Check if blob is a snapshot.

Parameters
blobBlob.
Returns
true if blob is a snapshot.

◆ spdk_blob_is_thin_provisioned()

bool spdk_blob_is_thin_provisioned ( struct spdk_blob *  blob)

Check if blob is thin-provisioned.

Parameters
blobBlob.
Returns
true if blob is thin-provisioned.

◆ spdk_blob_open_opts_init()

void spdk_blob_open_opts_init ( struct spdk_blob_open_opts opts,
size_t  opts_size 
)

Initialize a spdk_blob_open_opts structure to the default blob option values.

Parameters
optsspdk_blob_open_opts structure to initialize.
opts_sizeIt mus be the size of struct spdk_blob_open_opts.

◆ spdk_blob_opts_init()

void spdk_blob_opts_init ( struct spdk_blob_opts opts,
size_t  opts_size 
)

Initialize a spdk_blob_opts structure to the default blob option values.

Parameters
optsspdk_blob_opts structure to initialize.
opts_sizeIt must be the size of spdk_blob_opts structure.

◆ spdk_blob_remove_xattr()

int spdk_blob_remove_xattr ( struct spdk_blob *  blob,
const char *  name 
)

Remove the extended attribute from the given blob.

Parameters
blobBlob to remove attribute.
nameName of the extended attribute.
Returns
0 on success, negative errno on failure.

◆ spdk_blob_resize()

void spdk_blob_resize ( struct spdk_blob *  blob,
uint64_t  sz,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Resize a blob to 'sz' clusters.

These changes are not persisted to disk until spdk_bs_md_sync_blob() is called. If called before previous resize finish, it will fail with errno -EBUSY

Parameters
blobBlob to resize.
szThe new number of clusters.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_blob_set_esnap_bs_dev()

void spdk_blob_set_esnap_bs_dev ( struct spdk_blob *  blob,
struct spdk_bs_dev back_bs_dev,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Replace the existing external snapshot device.

Parameters
blobThe blob that is getting a new external snapshot device.
back_bs_devThe new blobstore device to use as an external snapshot.
cb_fnCallback to be called when complete.
cb_argCallback argument used with cb_fn.

◆ spdk_blob_set_read_only()

int spdk_blob_set_read_only ( struct spdk_blob *  blob)

Set blob as read only.

These changes do not take effect until spdk_blob_sync_md() is called.

Parameters
blobBlob to set.

◆ spdk_blob_set_xattr()

int spdk_blob_set_xattr ( struct spdk_blob *  blob,
const char *  name,
const void *  value,
uint16_t  value_len 
)

Set an extended attribute for the given blob.

Parameters
blobBlob to set attribute.
nameName of the extended attribute.
valueValue of the extended attribute.
value_lenLength of the value.
Returns
0 on success, -1 on failure.

◆ spdk_blob_sync_md()

void spdk_blob_sync_md ( struct spdk_blob *  blob,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

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.

Parameters
blobBlob to sync.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_alloc_io_channel()

struct spdk_io_channel* spdk_bs_alloc_io_channel ( struct spdk_blob_store *  bs)

Allocate an I/O channel for the given blobstore.

Parameters
bsblobstore.
Returns
a pointer to the allocated I/O channel.

◆ spdk_bs_blob_decouple_parent()

void spdk_bs_blob_decouple_parent ( struct spdk_blob_store *  bs,
struct spdk_io_channel *  channel,
spdk_blob_id  blobid,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Remove dependency on parent blob.

This call allocates and copies data for any clusters that are allocated in the parent blob, and decouples parent updating dependencies of blob to its ancestor.

If blob have no parent -EINVAL error is reported.

Parameters
bsblobstore.
channelIO channel used to inflate blob.
blobidThe id of the blob.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_create_blob()

void spdk_bs_create_blob ( struct spdk_blob_store *  bs,
spdk_blob_op_with_id_complete  cb_fn,
void *  cb_arg 
)

Create a new blob with default option values on the given blobstore.

The new blob id will be passed to the callback function.

Parameters
bsblobstore.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_create_blob_ext()

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 with options on the given blobstore.

The new blob id will be passed to the callback function.

Parameters
bsblobstore.
optsThe structure which contains the option values for the new blob.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_create_clone()

void spdk_bs_create_clone ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
const struct spdk_blob_xattr_opts clone_xattrs,
spdk_blob_op_with_id_complete  cb_fn,
void *  cb_arg 
)

Create a clone of specified read-only blob.

Structure clone_xattrs as well as anything it references (like e.g. names array) must be valid until the completion is called.

Parameters
bsblobstore.
blobidId of the read only blob used as a snapshot for new clone.
clone_xattrsxattrs specified for clone.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_create_snapshot()

void spdk_bs_create_snapshot ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
const struct spdk_blob_xattr_opts snapshot_xattrs,
spdk_blob_op_with_id_complete  cb_fn,
void *  cb_arg 
)

Create a read-only snapshot of specified blob with provided options.

This will automatically sync specified blob.

When operation is done, original blob is converted to the thin-provisioned blob with a newly created read-only snapshot set as a backing blob. Structure snapshot_xattrs as well as anything it references (like e.g. names array) must be valid until the completion is called.

Parameters
bsblobstore.
blobidId of the source blob used to create a snapshot.
snapshot_xattrsxattrs specified for snapshot.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_delete_blob()

void spdk_bs_delete_blob ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Delete an existing blob from the given blobstore.

Parameters
bsblobstore.
blobidThe id of the blob to delete.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_destroy()

void spdk_bs_destroy ( struct spdk_blob_store *  bs,
spdk_bs_op_complete  cb_fn,
void *  cb_arg 
)

Destroy the blobstore.

It will destroy the blobstore by zeroing the super block.

Parameters
bsblobstore to destroy.
cb_fnCalled when the destruction is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_dump()

void spdk_bs_dump ( struct spdk_bs_dev dev,
FILE *  fp,
spdk_bs_dump_print_xattr  print_xattr_fn,
spdk_bs_op_complete  cb_fn,
void *  cb_arg 
)

Dump a blobstore's metadata to a given FILE in human-readable format.

Parameters
devBlobstore block device.
fpFILE pointer to dump the metadata contents.
print_xattr_fnCallback function to interpret external xattrs.
cb_fnCalled when the dump is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_free_cluster_count()

uint64_t spdk_bs_free_cluster_count ( struct spdk_blob_store *  bs)

Get the number of free clusters.

Parameters
bsblobstore to query.
Returns
the number of free clusters.

◆ spdk_bs_free_io_channel()

void spdk_bs_free_io_channel ( struct spdk_io_channel *  channel)

Free the I/O channel.

Parameters
channelI/O channel to free.

◆ spdk_bs_get_bstype()

struct spdk_bs_type spdk_bs_get_bstype ( struct spdk_blob_store *  bs)

Get blobstore type of the given device.

Parameters
bsblobstore to query.
Returns
blobstore type.

◆ spdk_bs_get_cluster_size()

uint64_t spdk_bs_get_cluster_size ( struct spdk_blob_store *  bs)

Get the cluster size in bytes.

Parameters
bsblobstore to query.
Returns
cluster size.

◆ spdk_bs_get_io_unit_size()

uint64_t spdk_bs_get_io_unit_size ( struct spdk_blob_store *  bs)

Get the io unit size in bytes.

Parameters
bsblobstore to query.
Returns
io unit size.

◆ spdk_bs_get_page_size()

uint64_t spdk_bs_get_page_size ( struct spdk_blob_store *  bs)

Get the page size in bytes.

This is the write and read granularity of blobs.

Parameters
bsblobstore to query.
Returns
page size.

◆ spdk_bs_get_super()

void spdk_bs_get_super ( struct spdk_blob_store *  bs,
spdk_blob_op_with_id_complete  cb_fn,
void *  cb_arg 
)

Get the super blob.

The obtained blob id will be passed to the callback function.

Parameters
bsblobstore.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_grow()

void spdk_bs_grow ( struct spdk_bs_dev dev,
struct spdk_bs_opts opts,
spdk_bs_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Grow a blobstore to fill the underlying device Cannot be used on loaded blobstore.

Parameters
devBlobstore block device.
optsThe structure which contains the option values for the blobstore.
cb_fnCalled when the loading is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_grow_live()

void spdk_bs_grow_live ( struct spdk_blob_store *  bs,
spdk_bs_op_complete  cb_fn,
void *  cb_arg 
)

Grow a blobstore to fill the underlying device.

Can be used on loaded blobstore, even with opened blobs.

Parameters
bsblobstore to grow.
cb_fnCalled when the growing is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_inflate_blob()

void spdk_bs_inflate_blob ( struct spdk_blob_store *  bs,
struct spdk_io_channel *  channel,
spdk_blob_id  blobid,
spdk_blob_op_complete  cb_fn,
void *  cb_arg 
)

Allocate all clusters in this blob.

Data for allocated clusters is copied from backing blob(s) if they exist.

This call removes all dependencies on any backing blobs.

Parameters
bsblobstore.
channelIO channel used to inflate blob.
blobidThe id of the blob to inflate.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_init()

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 
)

Initialize a blobstore on the given device.

Parameters
devBlobstore block device.
optsThe structure which contains the option values for the blobstore.
cb_fnCalled when the initialization is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_iter_first()

void spdk_bs_iter_first ( struct spdk_blob_store *  bs,
spdk_blob_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Get the first blob of the blobstore.

The obtained blob will be passed to the callback function.

The user's cb_fn will be called with rc == -ENOENT when the iteration is complete.

When the user's cb_fn is called with rc == 0, the associated blob is open. This means that the cb_fn may not attempt to unload the blobstore. It must complete the iteration before attempting to unload.

Parameters
bsblobstore to traverse.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_iter_next()

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 
)

Get the next blob by using the current blob.

The obtained blob will be passed to the callback function.

The user's cb_fn will be called with rc == -ENOENT when the iteration is complete.

When the user's cb_fn is called with rc == 0, the associated blob is open. This means that the cb_fn may not attempt to unload the blobstore. It must complete the iteration before attempting to unload.

Parameters
bsblobstore to traverse.
blobThe current blob.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_load()

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 
)

Load a blobstore from the given device.

Parameters
devBlobstore block device.
optsThe structure which contains the option values for the blobstore.
cb_fnCalled when the loading is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_open_blob()

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 
)

Open a blob from the given blobstore.

Parameters
bsblobstore.
blobidThe id of the blob to open.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_open_blob_ext()

void spdk_bs_open_blob_ext ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
struct spdk_blob_open_opts opts,
spdk_blob_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Open a blob from the given blobstore with additional options.

Parameters
bsblobstore.
blobidThe id of the blob to open.
optsThe structure which contains the option values for the blob.
cb_fnCalled when the operation is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_opts_init()

void spdk_bs_opts_init ( struct spdk_bs_opts opts,
size_t  opts_size 
)

Initialize a spdk_bs_opts structure to the default blobstore option values.

Parameters
optsThe spdk_bs_opts structure to be initialized.
opts_sizeThe opts_size must be the size of spdk_bs_opts structure.

◆ spdk_bs_set_bstype()

void spdk_bs_set_bstype ( struct spdk_blob_store *  bs,
struct spdk_bs_type  bstype 
)

Set blobstore type to the given device.

Parameters
bsblobstore to set to.
bstypeType label to set.

◆ spdk_bs_set_super()

void spdk_bs_set_super ( struct spdk_blob_store *  bs,
spdk_blob_id  blobid,
spdk_bs_op_complete  cb_fn,
void *  cb_arg 
)

Set a super blob on the given blobstore.

This will be retrievable immediately after spdk_bs_load() on the next initialization.

Parameters
bsblobstore.
blobidThe id of the blob which will be set as the super blob.
cb_fnCalled when the setting is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_bs_total_data_cluster_count()

uint64_t spdk_bs_total_data_cluster_count ( struct spdk_blob_store *  bs)

Get the total number of clusters accessible by user.

Parameters
bsblobstore to query.
Returns
the total number of clusters accessible by user.

◆ spdk_bs_unload()

void spdk_bs_unload ( struct spdk_blob_store *  bs,
spdk_bs_op_complete  cb_fn,
void *  cb_arg 
)

Unload the blobstore.

It will flush all volatile data to disk.

Parameters
bsblobstore to unload.
cb_fnCalled when the unloading is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_xattr_names_free()

void spdk_xattr_names_free ( struct spdk_xattr_names *  names)

Free the attribute names.

Parameters
namesNames of total extended attributes of the blob.

◆ spdk_xattr_names_get_count()

uint32_t spdk_xattr_names_get_count ( struct spdk_xattr_names *  names)

Get the number of extended attributes.

Parameters
namesNames of total extended attributes of the blob.
Returns
the number of extended attributes.

◆ spdk_xattr_names_get_name()

const char* spdk_xattr_names_get_name ( struct spdk_xattr_names *  names,
uint32_t  index 
)

Get the attribute name specified by the index.

Parameters
namesNames of total extended attributes of the blob.
indexIndex position of the specified attribute.
Returns
attribute name.