blobfs.h File Reference

SPDK Filesystem. More...

Data Structures

struct  spdk_blobfs_opts
 
struct  spdk_file_stat
 

Macros

#define SPDK_FILE_NAME_MAX   255
 
#define SPDK_BLOBFS_OPEN_CREATE   (1ULL << 0)
 
#define spdk_fs_iter_get_file(iter)   ((struct spdk_file *)(iter))
 
#define SPDK_FILE_PRIORITY_LOW   0 /* default */
 
#define SPDK_FILE_PRIORITY_HIGH   1
 

Typedefs

typedef struct spdk_file * spdk_fs_iter
 
typedef void(* spdk_fs_op_with_handle_complete) (void *ctx, struct spdk_filesystem *fs, int fserrno)
 Filesystem operation completion callback with handle. More...
 
typedef void(* spdk_file_op_with_handle_complete) (void *ctx, struct spdk_file *f, int fserrno)
 File operation completion callback with handle. More...
 
typedef spdk_bs_op_complete spdk_fs_op_complete
 
typedef void(* spdk_file_op_complete) (void *ctx, int fserrno)
 File operation completion callback. More...
 
typedef void(* spdk_file_stat_op_complete) (void *ctx, struct spdk_file_stat *stat, int fserrno)
 File stat operation completion callback. More...
 
typedef void(* fs_request_fn) (void *arg)
 Function for a request of file system. More...
 
typedef void(* fs_send_request_fn) (fs_request_fn fn, void *arg)
 Function for sending request. More...
 

Functions

void spdk_fs_opts_init (struct spdk_blobfs_opts *opts)
 Initialize a spdk_blobfs_opts structure to the default option values. More...
 
void spdk_fs_init (struct spdk_bs_dev *dev, struct spdk_blobfs_opts *opt, fs_send_request_fn send_request_fn, spdk_fs_op_with_handle_complete cb_fn, void *cb_arg)
 Initialize blobstore filesystem. More...
 
void spdk_fs_load (struct spdk_bs_dev *dev, fs_send_request_fn send_request_fn, spdk_fs_op_with_handle_complete cb_fn, void *cb_arg)
 Load blobstore filesystem from the given blobstore block device. More...
 
void spdk_fs_unload (struct spdk_filesystem *fs, spdk_fs_op_complete cb_fn, void *cb_arg)
 Unload blobstore filesystem. More...
 
struct spdk_io_channel * spdk_fs_alloc_io_channel (struct spdk_filesystem *fs)
 Allocate an I/O channel for asynchronous operations. More...
 
void spdk_fs_free_io_channel (struct spdk_io_channel *channel)
 Free I/O channel. More...
 
struct spdk_fs_thread_ctx * spdk_fs_alloc_thread_ctx (struct spdk_filesystem *fs)
 Allocate a context for synchronous operations. More...
 
void spdk_fs_free_thread_ctx (struct spdk_fs_thread_ctx *ctx)
 Free thread context. More...
 
int spdk_fs_file_stat (struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, const char *name, struct spdk_file_stat *stat)
 Get statistics about the file including the underlying blob id and the file size. More...
 
int spdk_fs_create_file (struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, const char *name)
 Create a new file on the given blobstore filesystem. More...
 
int spdk_fs_open_file (struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, const char *name, uint32_t flags, struct spdk_file **file)
 Open the file. More...
 
int spdk_file_close (struct spdk_file *file, struct spdk_fs_thread_ctx *ctx)
 Close the file. More...
 
int spdk_fs_rename_file (struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, const char *old_name, const char *new_name)
 Change the file name. More...
 
int spdk_fs_delete_file (struct spdk_filesystem *fs, struct spdk_fs_thread_ctx *ctx, const char *name)
 Delete the file. More...
 
spdk_fs_iter spdk_fs_iter_first (struct spdk_filesystem *fs)
 Get the first file in the blobstore filesystem. More...
 
spdk_fs_iter spdk_fs_iter_next (spdk_fs_iter iter)
 Get the next file in the blobstore filesystem by using the input iterator. More...
 
int spdk_file_truncate (struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, uint64_t length)
 Truncate the file. More...
 
const char * spdk_file_get_name (struct spdk_file *file)
 Get file name. More...
 
uint64_t spdk_file_get_length (struct spdk_file *file)
 Obtain the size of the file. More...
 
int spdk_file_write (struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, void *payload, uint64_t offset, uint64_t length)
 Write data to the given file. More...
 
int64_t spdk_file_read (struct spdk_file *file, struct spdk_fs_thread_ctx *ctx, void *payload, uint64_t offset, uint64_t length)
 Read data to user buffer from the given file. More...
 
int spdk_fs_set_cache_size (uint64_t size_in_mb)
 Set cache size for the blobstore filesystem. More...
 
uint64_t spdk_fs_get_cache_size (void)
 Obtain the cache size. More...
 
void spdk_file_set_priority (struct spdk_file *file, uint32_t priority)
 Set priority for the file. More...
 
int spdk_file_sync (struct spdk_file *file, struct spdk_fs_thread_ctx *ctx)
 Synchronize the data from the cache to the disk. More...
 
int spdk_file_get_id (struct spdk_file *file, void *id, size_t size)
 Get the unique ID for the file. More...
 
void spdk_file_readv_async (struct spdk_file *file, struct spdk_io_channel *channel, struct iovec *iovs, uint32_t iovcnt, uint64_t offset, uint64_t length, spdk_file_op_complete cb_fn, void *cb_arg)
 Read data to user buffer from the given file. More...
 
void spdk_file_writev_async (struct spdk_file *file, struct spdk_io_channel *channel, struct iovec *iovs, uint32_t iovcnt, uint64_t offset, uint64_t length, spdk_file_op_complete cb_fn, void *cb_arg)
 Write data to the given file. More...
 
void spdk_fs_file_stat_async (struct spdk_filesystem *fs, const char *name, spdk_file_stat_op_complete cb_fn, void *cb_arg)
 Get statistics about the file including the underlying blob id and the file size. More...
 
void spdk_fs_create_file_async (struct spdk_filesystem *fs, const char *name, spdk_file_op_complete cb_fn, void *cb_arg)
 Create a new file on the given blobstore filesystem. More...
 
void spdk_fs_open_file_async (struct spdk_filesystem *fs, const char *name, uint32_t flags, spdk_file_op_with_handle_complete cb_fn, void *cb_arg)
 Open the file. More...
 
void spdk_file_close_async (struct spdk_file *file, spdk_file_op_complete cb_fn, void *cb_arg)
 Close the file. More...
 
void spdk_fs_rename_file_async (struct spdk_filesystem *fs, const char *old_name, const char *new_name, spdk_fs_op_complete cb_fn, void *cb_arg)
 Change the file name. More...
 
void spdk_fs_delete_file_async (struct spdk_filesystem *fs, const char *name, spdk_file_op_complete cb_fn, void *cb_arg)
 Delete the file. More...
 
void spdk_file_truncate_async (struct spdk_file *file, uint64_t length, spdk_file_op_complete cb_fn, void *cb_arg)
 Truncate the file. More...
 
void spdk_file_write_async (struct spdk_file *file, struct spdk_io_channel *channel, void *payload, uint64_t offset, uint64_t length, spdk_file_op_complete cb_fn, void *cb_arg)
 Write data to the given file. More...
 
void spdk_file_read_async (struct spdk_file *file, struct spdk_io_channel *channel, void *payload, uint64_t offset, uint64_t length, spdk_file_op_complete cb_fn, void *cb_arg)
 Read data to user buffer from the given file. More...
 
void spdk_file_sync_async (struct spdk_file *file, struct spdk_io_channel *channel, spdk_file_op_complete cb_fn, void *cb_arg)
 Sync all dirty cache buffers to the backing block device. More...
 

Detailed Description

SPDK Filesystem.

Typedef Documentation

◆ fs_request_fn

typedef void(* fs_request_fn) (void *arg)

Function for a request of file system.

Parameters
argArgument to the request function.

◆ fs_send_request_fn

typedef void(* fs_send_request_fn) (fs_request_fn fn, void *arg)

Function for sending request.

This function will be invoked any time when the filesystem wants to pass a message to the main dispatch thread.

Parameters
fnA pointer to the request function.
argArgument to the request function.

◆ spdk_file_op_complete

typedef void(* spdk_file_op_complete) (void *ctx, int fserrno)

File operation completion callback.

Parameters
ctxContext for the operation.
fserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_file_op_with_handle_complete

typedef void(* spdk_file_op_with_handle_complete) (void *ctx, struct spdk_file *f, int fserrno)

File operation completion callback with handle.

Parameters
ctxContext for the operation.
fHandle to a file.
fserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_file_stat_op_complete

typedef void(* spdk_file_stat_op_complete) (void *ctx, struct spdk_file_stat *stat, int fserrno)

File stat operation completion callback.

Parameters
ctxContext for the operation.
statHandle to the stat about the file.
fserrno0 if it completed successfully, or negative errno if it failed.

◆ spdk_fs_op_with_handle_complete

typedef void(* spdk_fs_op_with_handle_complete) (void *ctx, struct spdk_filesystem *fs, int fserrno)

Filesystem operation completion callback with handle.

Parameters
ctxContext for the operation.
fsHandle to a blobfs.
fserrno0 if it completed successfully, or negative errno if it failed.

Function Documentation

◆ spdk_file_close()

int spdk_file_close ( struct spdk_file *  file,
struct spdk_fs_thread_ctx *  ctx 
)

Close the file.

Parameters
fileFile to close.
ctxThe thread context for this operation
Returns
0 on success, negative errno on failure.

◆ spdk_file_close_async()

void spdk_file_close_async ( struct spdk_file *  file,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Close the file.

Parameters
fileFile to close.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_get_id()

int spdk_file_get_id ( struct spdk_file *  file,
void *  id,
size_t  size 
)

Get the unique ID for the file.

Parameters
fileFile to get the ID.
idID buffer.
sizeSize of the ID buffer.
Returns
the length of ID on success.

◆ spdk_file_get_length()

uint64_t spdk_file_get_length ( struct spdk_file *  file)

Obtain the size of the file.

Parameters
fileFile to query.
Returns
the size in bytes of the file.

◆ spdk_file_get_name()

const char* spdk_file_get_name ( struct spdk_file *  file)

Get file name.

Parameters
fileFile to query.
Returns
the name of the file.

◆ spdk_file_read()

int64_t spdk_file_read ( struct spdk_file *  file,
struct spdk_fs_thread_ctx *  ctx,
void *  payload,
uint64_t  offset,
uint64_t  length 
)

Read data to user buffer from the given file.

Parameters
fileFile to read.
ctxThe thread context for this operation
payloadThe specified buffer which will store the obtained data.
offsetThe beginning position to read.
lengthThe size in bytes of data to read.
Returns
the end position of this read operation on success, negated errno on failure.

◆ spdk_file_read_async()

void spdk_file_read_async ( struct spdk_file *  file,
struct spdk_io_channel *  channel,
void *  payload,
uint64_t  offset,
uint64_t  length,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Read data to user buffer from the given file.

Parameters
fileFile to write.
channelI/O channel for asynchronous operations.
payloadThe specified buffer which will store the obtained data.
offsetThe beginning position to read.
lengthThe size in bytes of data to read.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_readv_async()

void spdk_file_readv_async ( struct spdk_file *  file,
struct spdk_io_channel *  channel,
struct iovec *  iovs,
uint32_t  iovcnt,
uint64_t  offset,
uint64_t  length,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Read data to user buffer from the given file.

Parameters
fileFile to read.
channelI/O channel for asynchronous operations.
iovsA scatter gather list of buffers to be read into.
iovcntThe number of elements in iov.
offsetThe beginning position to read.
lengthThe size in bytes of data to read.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_set_priority()

void spdk_file_set_priority ( struct spdk_file *  file,
uint32_t  priority 
)

Set priority for the file.

Parameters
fileFile to set priority.
priorityPriority level (SPDK_FILE_PRIORITY_LOW or SPDK_FILE_PRIORITY_HIGH).

◆ spdk_file_sync()

int spdk_file_sync ( struct spdk_file *  file,
struct spdk_fs_thread_ctx *  ctx 
)

Synchronize the data from the cache to the disk.

Parameters
fileFile to sync.
ctxThe thread context for this operation
Returns
0 on success.

◆ spdk_file_sync_async()

void spdk_file_sync_async ( struct spdk_file *  file,
struct spdk_io_channel *  channel,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Sync all dirty cache buffers to the backing block device.

For async usage models, completion of the sync indicates only that data written when the sync command was issued have been flushed to disk - it does not guarantee any writes submitted after the sync have been flushed, even if those writes are completed before the sync.

Parameters
fileFile to write.
channelI/O channel for asynchronous operations.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_truncate()

int spdk_file_truncate ( struct spdk_file *  file,
struct spdk_fs_thread_ctx *  ctx,
uint64_t  length 
)

Truncate the file.

Parameters
fileFile to truncate.
ctxThe thread context for this operation
lengthNew size in bytes of the file.
Returns
0 on success, negative errno on failure.

◆ spdk_file_truncate_async()

void spdk_file_truncate_async ( struct spdk_file *  file,
uint64_t  length,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Truncate the file.

Parameters
fileFile to truncate.
lengthNew size in bytes of the file.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_write()

int spdk_file_write ( struct spdk_file *  file,
struct spdk_fs_thread_ctx *  ctx,
void *  payload,
uint64_t  offset,
uint64_t  length 
)

Write data to the given file.

Parameters
fileFile to write.
ctxThe thread context for this operation
payloadThe specified buffer which should contain the data to be transmitted.
offsetThe beginning position to write data.
lengthThe size in bytes of data to write.
Returns
0 on success, negative errno on failure.

◆ spdk_file_write_async()

void spdk_file_write_async ( struct spdk_file *  file,
struct spdk_io_channel *  channel,
void *  payload,
uint64_t  offset,
uint64_t  length,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Write data to the given file.

Parameters
fileFile to write.
channelI/O channel for asynchronous operations.
payloadThe specified buffer which should contain the data to be transmitted.
offsetThe beginning position to write data.
lengthThe size in bytes of data to write.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_file_writev_async()

void spdk_file_writev_async ( struct spdk_file *  file,
struct spdk_io_channel *  channel,
struct iovec *  iovs,
uint32_t  iovcnt,
uint64_t  offset,
uint64_t  length,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Write data to the given file.

Parameters
fileFile to write.
channelI/O channel for asynchronous operations.
iovsA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
offsetThe beginning position to write.
lengthThe size in bytes of data to write.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_alloc_io_channel()

struct spdk_io_channel* spdk_fs_alloc_io_channel ( struct spdk_filesystem *  fs)

Allocate an I/O channel for asynchronous operations.

Parameters
fsBlobstore filesystem to allocate I/O channel.
Returns
a pointer to the I/O channel on success or NULL otherwise.

◆ spdk_fs_alloc_thread_ctx()

struct spdk_fs_thread_ctx* spdk_fs_alloc_thread_ctx ( struct spdk_filesystem *  fs)

Allocate a context for synchronous operations.

Parameters
fsBlobstore filesystem for this context.
Returns
a pointer to the context on success or NULL otherwise.

◆ spdk_fs_create_file()

int spdk_fs_create_file ( struct spdk_filesystem *  fs,
struct spdk_fs_thread_ctx *  ctx,
const char *  name 
)

Create a new file on the given blobstore filesystem.

Parameters
fsBlobstore filesystem.
ctxThe thread context for this operation
nameThe file name for this new file.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_create_file_async()

void spdk_fs_create_file_async ( struct spdk_filesystem *  fs,
const char *  name,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Create a new file on the given blobstore filesystem.

Parameters
fsBlobstore filesystem.
nameThe file name for this new file.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_delete_file()

int spdk_fs_delete_file ( struct spdk_filesystem *  fs,
struct spdk_fs_thread_ctx *  ctx,
const char *  name 
)

Delete the file.

Parameters
fsBlobstore filesystem.
ctxThe thread context for this operation
nameThe name of the file to be deleted.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_delete_file_async()

void spdk_fs_delete_file_async ( struct spdk_filesystem *  fs,
const char *  name,
spdk_file_op_complete  cb_fn,
void *  cb_arg 
)

Delete the file.

Parameters
fsBlobstore filesystem.
nameThe name of the file to be deleted.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_file_stat()

int spdk_fs_file_stat ( struct spdk_filesystem *  fs,
struct spdk_fs_thread_ctx *  ctx,
const char *  name,
struct spdk_file_stat stat 
)

Get statistics about the file including the underlying blob id and the file size.

Parameters
fsBlobstore filesystem.
ctxThe thread context for this operation
nameThe file name used to look up the matched file in the blobstore filesystem.
statCaller allocated structure to store the obtained information about this file.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_file_stat_async()

void spdk_fs_file_stat_async ( struct spdk_filesystem *  fs,
const char *  name,
spdk_file_stat_op_complete  cb_fn,
void *  cb_arg 
)

Get statistics about the file including the underlying blob id and the file size.

Parameters
fsBlobstore filesystem.
nameThe file name used to look up the matched file in the blobstore filesystem.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_free_io_channel()

void spdk_fs_free_io_channel ( struct spdk_io_channel *  channel)

Free I/O channel.

This function will decrease the references of this I/O channel. If the reference is reduced to 0, the I/O channel will be freed.

Parameters
channelI/O channel to free.

◆ spdk_fs_free_thread_ctx()

void spdk_fs_free_thread_ctx ( struct spdk_fs_thread_ctx *  ctx)

Free thread context.

Parameters
ctxThread context to free.

◆ spdk_fs_get_cache_size()

uint64_t spdk_fs_get_cache_size ( void  )

Obtain the cache size.

Returns
cache size in megabytes.

◆ spdk_fs_init()

void spdk_fs_init ( struct spdk_bs_dev dev,
struct spdk_blobfs_opts opt,
fs_send_request_fn  send_request_fn,
spdk_fs_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Initialize blobstore filesystem.

Initialize the blobstore filesystem on the blobstore block device which has been created by the function spdk_bdev_create_bs_dev() in the blob_bdev.h. The obtained blobstore filesystem will be passed to the callback function.

Parameters
devBlobstore block device used by this blobstore filesystem.
optInitialization options used for this blobstore filesystem.
send_request_fnThe function for sending request. This function will be invoked any time when the blobstore filesystem wants to pass a message to the main dispatch thread.
cb_fnCalled when the initialization is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_fs_iter_first()

spdk_fs_iter spdk_fs_iter_first ( struct spdk_filesystem *  fs)

Get the first file in the blobstore filesystem.

Parameters
fsBlobstore filesystem to traverse.
Returns
an iterator which points to the first file in the blobstore filesystem.

◆ spdk_fs_iter_next()

spdk_fs_iter spdk_fs_iter_next ( spdk_fs_iter  iter)

Get the next file in the blobstore filesystem by using the input iterator.

Parameters
iterThe iterator which points to the current file struct.
Returns
an iterator which points to the next file in the blobstore filesystem.

◆ spdk_fs_load()

void spdk_fs_load ( struct spdk_bs_dev dev,
fs_send_request_fn  send_request_fn,
spdk_fs_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Load blobstore filesystem from the given blobstore block device.

The obtained blobstore filesystem will be passed to the callback function.

Parameters
devBlobstore block device used by this blobstore filesystem.
send_request_fnThe function for sending request. This function will be invoked any time when the blobstore filesystem wants to pass a message to the main dispatch thread.
cb_fnCalled when the loading is complete.
cb_argArgument passed to function cb_fn.

◆ spdk_fs_open_file()

int spdk_fs_open_file ( struct spdk_filesystem *  fs,
struct spdk_fs_thread_ctx *  ctx,
const char *  name,
uint32_t  flags,
struct spdk_file **  file 
)

Open the file.

Parameters
fsBlobstore filesystem.
ctxThe thread context for this operation
nameThe file name used to look up the matched file in the blobstore filesystem.
flagsThis flags will be used to control the open mode.
fileIt will point to the open file if successful or NULL otherwise.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_open_file_async()

void spdk_fs_open_file_async ( struct spdk_filesystem *  fs,
const char *  name,
uint32_t  flags,
spdk_file_op_with_handle_complete  cb_fn,
void *  cb_arg 
)

Open the file.

Parameters
fsBlobstore filesystem.
nameThe file name used to look up the matched file in the blobstore filesystem.
flagsThis flags will be used to control the open mode.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_opts_init()

void spdk_fs_opts_init ( struct spdk_blobfs_opts opts)

Initialize a spdk_blobfs_opts structure to the default option values.

Parameters
optsspdk_blobf_opts structure to initialize.

◆ spdk_fs_rename_file()

int spdk_fs_rename_file ( struct spdk_filesystem *  fs,
struct spdk_fs_thread_ctx *  ctx,
const char *  old_name,
const char *  new_name 
)

Change the file name.

This operation will overwrite an existing file if there is a file with the same name.

Parameters
fsBlobstore filesystem.
ctxThe thread context for this operation
old_nameOld name of the file.
new_nameNew name of the file.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_rename_file_async()

void spdk_fs_rename_file_async ( struct spdk_filesystem *  fs,
const char *  old_name,
const char *  new_name,
spdk_fs_op_complete  cb_fn,
void *  cb_arg 
)

Change the file name.

This operation will overwrite an existing file if there is a file with the same name.

Parameters
fsBlobstore filesystem.
old_nameOld name of the file.
new_nameNew name of the file.
cb_fnCalled when the request is complete.
cb_argArgument passed to cb_fn.

◆ spdk_fs_set_cache_size()

int spdk_fs_set_cache_size ( uint64_t  size_in_mb)

Set cache size for the blobstore filesystem.

Parameters
size_in_mbCache size in megabytes.
Returns
0 on success, negative errno on failure.

◆ spdk_fs_unload()

void spdk_fs_unload ( struct spdk_filesystem *  fs,
spdk_fs_op_complete  cb_fn,
void *  cb_arg 
)

Unload blobstore filesystem.

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