bdev.h File Reference

Block device abstraction layer. More...

Data Structures

struct  spdk_bdev_media_event
 Media management event details. More...
 
struct  spdk_bdev_io_stat
 
struct  spdk_bdev_opts
 
struct  spdk_bdev_io_wait_entry
 Structure to register a callback when an spdk_bdev_io becomes available. More...
 

Macros

#define SPDK_BDEV_SMALL_BUF_MAX_SIZE   8192
 
#define SPDK_BDEV_LARGE_BUF_MAX_SIZE   (64 * 1024)
 
#define SPDK_BDEV_BUF_SIZE_WITH_MD(x)   (((x) / 512) * (512 + 16))
 

Typedefs

typedef void(* spdk_bdev_remove_cb_t) (void *remove_ctx)
 Block device remove callback. More...
 
typedef void(* spdk_bdev_event_cb_t) (enum spdk_bdev_event_type type, struct spdk_bdev *bdev, void *event_ctx)
 Block device event callback. More...
 
typedef void(* spdk_bdev_io_completion_cb) (struct spdk_bdev_io *bdev_io, bool success, void *cb_arg)
 Block device completion callback. More...
 
typedef void(* spdk_bdev_init_cb) (void *cb_arg, int rc)
 Block device initialization callback. More...
 
typedef void(* spdk_bdev_fini_cb) (void *cb_arg)
 Block device finish callback. More...
 
typedef void(* spdk_bdev_get_device_stat_cb) (struct spdk_bdev *bdev, struct spdk_bdev_io_stat *stat, void *cb_arg, int rc)
 
typedef void(* spdk_bdev_io_timeout_cb) (void *cb_arg, struct spdk_bdev_io *bdev_io)
 Block device channel IO timeout callback. More...
 
typedef void(* spdk_bdev_io_wait_cb) (void *cb_arg)
 Block device I/O wait callback. More...
 
typedef void(* spdk_bdev_histogram_status_cb) (void *cb_arg, int status)
 
typedef void(* spdk_bdev_histogram_data_cb) (void *cb_arg, int status, struct spdk_histogram_data *histogram)
 

Enumerations

enum  spdk_bdev_event_type { SPDK_BDEV_EVENT_REMOVE, SPDK_BDEV_EVENT_RESIZE, SPDK_BDEV_EVENT_MEDIA_MANAGEMENT }
 Asynchronous event type.
 
enum  spdk_bdev_status { SPDK_BDEV_STATUS_INVALID, SPDK_BDEV_STATUS_READY, SPDK_BDEV_STATUS_REMOVING }
 bdev status
 
enum  spdk_bdev_io_type {
  SPDK_BDEV_IO_TYPE_INVALID = 0, SPDK_BDEV_IO_TYPE_READ, SPDK_BDEV_IO_TYPE_WRITE, SPDK_BDEV_IO_TYPE_UNMAP,
  SPDK_BDEV_IO_TYPE_FLUSH, SPDK_BDEV_IO_TYPE_RESET, SPDK_BDEV_IO_TYPE_NVME_ADMIN, SPDK_BDEV_IO_TYPE_NVME_IO,
  SPDK_BDEV_IO_TYPE_NVME_IO_MD, SPDK_BDEV_IO_TYPE_WRITE_ZEROES, SPDK_BDEV_IO_TYPE_ZCOPY, SPDK_BDEV_IO_TYPE_GET_ZONE_INFO,
  SPDK_BDEV_IO_TYPE_ZONE_MANAGEMENT, SPDK_BDEV_IO_TYPE_ZONE_APPEND, SPDK_BDEV_IO_TYPE_COMPARE, SPDK_BDEV_IO_TYPE_COMPARE_AND_WRITE,
  SPDK_BDEV_NUM_IO_TYPES
}
 bdev I/O type
 
enum  spdk_bdev_qos_rate_limit_type {
  SPDK_BDEV_QOS_RW_IOPS_RATE_LIMIT = 0, SPDK_BDEV_QOS_RW_BPS_RATE_LIMIT, SPDK_BDEV_QOS_R_BPS_RATE_LIMIT, SPDK_BDEV_QOS_W_BPS_RATE_LIMIT,
  SPDK_BDEV_QOS_NUM_RATE_LIMIT_TYPES
}
 bdev QoS rate limit type More...
 

Functions

void spdk_bdev_get_opts (struct spdk_bdev_opts *opts)
 
int spdk_bdev_set_opts (struct spdk_bdev_opts *opts)
 
void spdk_bdev_initialize (spdk_bdev_init_cb cb_fn, void *cb_arg)
 Initialize block device modules. More...
 
void spdk_bdev_finish (spdk_bdev_fini_cb cb_fn, void *cb_arg)
 Perform cleanup work to remove the registered block device modules. More...
 
void spdk_bdev_config_text (FILE *fp)
 Get the configuration options for the registered block device modules. More...
 
void spdk_bdev_subsystem_config_json (struct spdk_json_write_ctx *w)
 Get the full configuration options for the registered block device modules and created bdevs. More...
 
struct spdk_bdevspdk_bdev_get_by_name (const char *bdev_name)
 Get block device by the block device name. More...
 
struct spdk_bdevspdk_bdev_first (void)
 Get the first registered block device. More...
 
struct spdk_bdevspdk_bdev_next (struct spdk_bdev *prev)
 Get the next registered block device. More...
 
struct spdk_bdevspdk_bdev_first_leaf (void)
 Get the first block device without virtual block devices on top. More...
 
struct spdk_bdevspdk_bdev_next_leaf (struct spdk_bdev *prev)
 Get the next block device without virtual block devices on top. More...
 
int spdk_bdev_open (struct spdk_bdev *bdev, bool write, spdk_bdev_remove_cb_t remove_cb, void *remove_ctx, struct spdk_bdev_desc **desc)
 Open a block device for I/O operations (deprecated, please use spdk_bdev_open_ext). More...
 
int spdk_bdev_open_ext (const char *bdev_name, bool write, spdk_bdev_event_cb_t event_cb, void *event_ctx, struct spdk_bdev_desc **desc)
 Open a block device for I/O operations. More...
 
void spdk_bdev_close (struct spdk_bdev_desc *desc)
 Close a previously opened block device. More...
 
struct spdk_bdevspdk_bdev_desc_get_bdev (struct spdk_bdev_desc *desc)
 Get the bdev associated with a bdev descriptor. More...
 
int spdk_bdev_set_timeout (struct spdk_bdev_desc *desc, uint64_t timeout_in_sec, spdk_bdev_io_timeout_cb cb_fn, void *cb_arg)
 Set a time limit for the timeout IO of the bdev and timeout callback. More...
 
bool spdk_bdev_io_type_supported (struct spdk_bdev *bdev, enum spdk_bdev_io_type io_type)
 Check whether the block device supports the I/O type. More...
 
int spdk_bdev_dump_info_json (struct spdk_bdev *bdev, struct spdk_json_write_ctx *w)
 Output driver-specific information to a JSON stream. More...
 
const char * spdk_bdev_get_name (const struct spdk_bdev *bdev)
 Get block device name. More...
 
const char * spdk_bdev_get_product_name (const struct spdk_bdev *bdev)
 Get block device product name. More...
 
uint32_t spdk_bdev_get_block_size (const struct spdk_bdev *bdev)
 Get block device logical block size. More...
 
uint32_t spdk_bdev_get_write_unit_size (const struct spdk_bdev *bdev)
 Get the write unit size for this bdev. More...
 
uint64_t spdk_bdev_get_num_blocks (const struct spdk_bdev *bdev)
 Get size of block device in logical blocks. More...
 
const char * spdk_bdev_get_qos_rpc_type (enum spdk_bdev_qos_rate_limit_type type)
 Get the string of quality of service rate limit. More...
 
void spdk_bdev_get_qos_rate_limits (struct spdk_bdev *bdev, uint64_t *limits)
 Get the quality of service rate limits on a bdev. More...
 
void spdk_bdev_set_qos_rate_limits (struct spdk_bdev *bdev, uint64_t *limits, void(*cb_fn)(void *cb_arg, int status), void *cb_arg)
 Set the quality of service rate limits on a bdev. More...
 
size_t spdk_bdev_get_buf_align (const struct spdk_bdev *bdev)
 Get minimum I/O buffer address alignment for a bdev. More...
 
uint32_t spdk_bdev_get_optimal_io_boundary (const struct spdk_bdev *bdev)
 Get optimal I/O boundary for a bdev. More...
 
bool spdk_bdev_has_write_cache (const struct spdk_bdev *bdev)
 Query whether block device has an enabled write cache. More...
 
const struct spdk_uuidspdk_bdev_get_uuid (const struct spdk_bdev *bdev)
 Get a bdev's UUID. More...
 
uint16_t spdk_bdev_get_acwu (const struct spdk_bdev *bdev)
 Get block device atomic compare and write unit. More...
 
uint32_t spdk_bdev_get_md_size (const struct spdk_bdev *bdev)
 Get block device metadata size. More...
 
bool spdk_bdev_is_md_interleaved (const struct spdk_bdev *bdev)
 Query whether metadata is interleaved with block data or separated with block data. More...
 
bool spdk_bdev_is_md_separate (const struct spdk_bdev *bdev)
 Query whether metadata is interleaved with block data or separated from block data. More...
 
bool spdk_bdev_is_zoned (const struct spdk_bdev *bdev)
 Checks if bdev supports zoned namespace semantics. More...
 
uint32_t spdk_bdev_get_data_block_size (const struct spdk_bdev *bdev)
 Get block device data block size. More...
 
enum spdk_dif_type spdk_bdev_get_dif_type (const struct spdk_bdev *bdev)
 Get DIF type of the block device. More...
 
bool spdk_bdev_is_dif_head_of_md (const struct spdk_bdev *bdev)
 Check whether DIF is set in the first 8 bytes or the last 8 bytes of metadata. More...
 
bool spdk_bdev_is_dif_check_enabled (const struct spdk_bdev *bdev, enum spdk_dif_check_type check_type)
 Check whether the DIF check type is enabled. More...
 
uint64_t spdk_bdev_get_qd (const struct spdk_bdev *bdev)
 Get the most recently measured queue depth from a bdev. More...
 
uint64_t spdk_bdev_get_qd_sampling_period (const struct spdk_bdev *bdev)
 Get the queue depth polling period. More...
 
void spdk_bdev_set_qd_sampling_period (struct spdk_bdev *bdev, uint64_t period)
 Enable or disable queue depth sampling for this bdev. More...
 
uint64_t spdk_bdev_get_io_time (const struct spdk_bdev *bdev)
 Get the time spent processing IO for this device. More...
 
uint64_t spdk_bdev_get_weighted_io_time (const struct spdk_bdev *bdev)
 Get the weighted IO processing time for this bdev. More...
 
struct spdk_io_channelspdk_bdev_get_io_channel (struct spdk_bdev_desc *desc)
 Obtain an I/O channel for the block device opened by the specified descriptor. More...
 
int spdk_bdev_read (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t offset, uint64_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_read_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_read_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, void *md, int64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_readv (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t offset, uint64_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_readv_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_readv_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, void *md, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a read request to the bdev on the given channel. More...
 
int spdk_bdev_write (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t offset, uint64_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_write_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_write_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, void *md, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_writev (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t offset, uint64_t len, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_writev_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_writev_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, void *md, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write request to the bdev on the given channel. More...
 
int spdk_bdev_compare_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a compare request to the bdev on the given channel. More...
 
int spdk_bdev_compare_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, void *md, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a compare request to the bdev on the given channel. More...
 
int spdk_bdev_comparev_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a compare request to the bdev on the given channel. More...
 
int spdk_bdev_comparev_blocks_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, void *md, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a compare request to the bdev on the given channel. More...
 
int spdk_bdev_comparev_and_writev_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *compare_iov, int compare_iovcnt, struct iovec *write_iov, int write_iovcnt, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an atomic compare-and-write request to the bdev on the given channel. More...
 
int spdk_bdev_zcopy_start (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset_blocks, uint64_t num_blocks, bool populate, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a request to acquire a data buffer that represents the given range of blocks. More...
 
int spdk_bdev_zcopy_end (struct spdk_bdev_io *bdev_io, bool commit, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a request to release a data buffer representing a range of blocks. More...
 
int spdk_bdev_write_zeroes (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset, uint64_t len, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write zeroes request to the bdev on the given channel. More...
 
int spdk_bdev_write_zeroes_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a write zeroes request to the bdev on the given channel. More...
 
int spdk_bdev_unmap (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset, uint64_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an unmap request to the block device. More...
 
int spdk_bdev_unmap_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an unmap request to the block device. More...
 
int spdk_bdev_flush (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset, uint64_t length, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a flush request to the bdev on the given channel. More...
 
int spdk_bdev_flush_blocks (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t offset_blocks, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a flush request to the bdev on the given channel. More...
 
int spdk_bdev_reset (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a reset request to the bdev on the given channel. More...
 
int spdk_bdev_nvme_admin_passthru (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, const struct spdk_nvme_cmd *cmd, void *buf, size_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an NVMe Admin command to the bdev. More...
 
int spdk_bdev_nvme_io_passthru (struct spdk_bdev_desc *bdev_desc, struct spdk_io_channel *ch, const struct spdk_nvme_cmd *cmd, void *buf, size_t nbytes, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an NVMe I/O command to the bdev. More...
 
int spdk_bdev_nvme_io_passthru_md (struct spdk_bdev_desc *bdev_desc, struct spdk_io_channel *ch, const struct spdk_nvme_cmd *cmd, void *buf, size_t nbytes, void *md_buf, size_t md_len, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit an NVMe I/O command to the bdev. More...
 
void spdk_bdev_free_io (struct spdk_bdev_io *bdev_io)
 Free an I/O request. More...
 
int spdk_bdev_queue_io_wait (struct spdk_bdev *bdev, struct spdk_io_channel *ch, struct spdk_bdev_io_wait_entry *entry)
 Add an entry into the calling thread's queue to be notified when an spdk_bdev_io becomes available. More...
 
void spdk_bdev_get_io_stat (struct spdk_bdev *bdev, struct spdk_io_channel *ch, struct spdk_bdev_io_stat *stat)
 Return I/O statistics for this channel. More...
 
void spdk_bdev_get_device_stat (struct spdk_bdev *bdev, struct spdk_bdev_io_stat *stat, spdk_bdev_get_device_stat_cb cb, void *cb_arg)
 Return I/O statistics for this bdev. More...
 
void spdk_bdev_io_get_nvme_status (const struct spdk_bdev_io *bdev_io, uint32_t *cdw0, int *sct, int *sc)
 Get the status of bdev_io as an NVMe status code and command specific completion queue value. More...
 
void spdk_bdev_io_get_nvme_fused_status (const struct spdk_bdev_io *bdev_io, uint32_t *cdw0, int *first_sct, int *first_sc, int *second_sct, int *second_sc)
 Get the status of bdev_io as an NVMe status codes and command specific completion queue value for fused operations such as compare-and-write. More...
 
void spdk_bdev_io_get_scsi_status (const struct spdk_bdev_io *bdev_io, int *sc, int *sk, int *asc, int *ascq)
 Get the status of bdev_io as a SCSI status code. More...
 
void spdk_bdev_io_get_iovec (struct spdk_bdev_io *bdev_io, struct iovec **iovp, int *iovcntp)
 Get the iovec describing the data buffer of a bdev_io. More...
 
void * spdk_bdev_io_get_md_buf (struct spdk_bdev_io *bdev_io)
 Get metadata buffer. More...
 
void spdk_bdev_histogram_enable (struct spdk_bdev *bdev, spdk_bdev_histogram_status_cb cb_fn, void *cb_arg, bool enable)
 Enable or disable collecting histogram data on a bdev. More...
 
void spdk_bdev_histogram_get (struct spdk_bdev *bdev, struct spdk_histogram_data *histogram, spdk_bdev_histogram_data_cb cb_fn, void *cb_arg)
 Get aggregated histogram data from a bdev. More...
 
size_t spdk_bdev_get_media_events (struct spdk_bdev_desc *bdev_desc, struct spdk_bdev_media_event *events, size_t max_events)
 Retrieves media events. More...
 

Detailed Description

Block device abstraction layer.

Typedef Documentation

◆ spdk_bdev_event_cb_t

typedef void(* spdk_bdev_event_cb_t) (enum spdk_bdev_event_type type, struct spdk_bdev *bdev, void *event_ctx)

Block device event callback.

Parameters
eventEvent details.
bdevBlock device that triggered event.
event_ctxContext for the block device event.

◆ spdk_bdev_fini_cb

typedef void(* spdk_bdev_fini_cb) (void *cb_arg)

Block device finish callback.

Parameters
cb_argCallback argument.

◆ spdk_bdev_init_cb

typedef void(* spdk_bdev_init_cb) (void *cb_arg, int rc)

Block device initialization callback.

Parameters
cb_argCallback argument.
rc0 if block device initialized successfully or negative errno if it failed.

◆ spdk_bdev_io_completion_cb

typedef void(* spdk_bdev_io_completion_cb) (struct spdk_bdev_io *bdev_io, bool success, void *cb_arg)

Block device completion callback.

Parameters
bdev_ioBlock device I/O that has completed.
successTrue if I/O completed successfully or false if it failed; additional error information may be retrieved from bdev_io by calling spdk_bdev_io_get_nvme_status() or spdk_bdev_io_get_scsi_status().
cb_argCallback argument specified when bdev_io was submitted.

◆ spdk_bdev_io_timeout_cb

typedef void(* spdk_bdev_io_timeout_cb) (void *cb_arg, struct spdk_bdev_io *bdev_io)

Block device channel IO timeout callback.

Parameters
cb_argCallback argument
bdev_ioThe IO cause the timeout

◆ spdk_bdev_io_wait_cb

typedef void(* spdk_bdev_io_wait_cb) (void *cb_arg)

Block device I/O wait callback.

Callback function to notify when an spdk_bdev_io structure is available to satisfy a call to one of the bdev I/O Submit Functions.

◆ spdk_bdev_remove_cb_t

typedef void(* spdk_bdev_remove_cb_t) (void *remove_ctx)

Block device remove callback.

Parameters
remove_ctxContext for the removed block device.

Enumeration Type Documentation

◆ spdk_bdev_qos_rate_limit_type

bdev QoS rate limit type

Enumerator
SPDK_BDEV_QOS_RW_IOPS_RATE_LIMIT 

IOPS rate limit for both read and write.

SPDK_BDEV_QOS_RW_BPS_RATE_LIMIT 

Byte per second rate limit for both read and write.

SPDK_BDEV_QOS_R_BPS_RATE_LIMIT 

Byte per second rate limit for read only.

SPDK_BDEV_QOS_W_BPS_RATE_LIMIT 

Byte per second rate limit for write only.

SPDK_BDEV_QOS_NUM_RATE_LIMIT_TYPES 

Keep last.

Function Documentation

◆ spdk_bdev_close()

void spdk_bdev_close ( struct spdk_bdev_desc *  desc)

Close a previously opened block device.

Must be called on the same thread that the spdk_bdev_open() was performed on.

Parameters
descBlock device descriptor to close.

◆ spdk_bdev_config_text()

void spdk_bdev_config_text ( FILE *  fp)

Get the configuration options for the registered block device modules.

Parameters
fpThe pointer to a file that will be written to the configuration options.

◆ spdk_bdev_desc_get_bdev()

struct spdk_bdev* spdk_bdev_desc_get_bdev ( struct spdk_bdev_desc *  desc)

Get the bdev associated with a bdev descriptor.

Parameters
descOpen block device desciptor
Returns
bdev associated with the descriptor

◆ spdk_bdev_dump_info_json()

int spdk_bdev_dump_info_json ( struct spdk_bdev bdev,
struct spdk_json_write_ctx *  w 
)

Output driver-specific information to a JSON stream.

The JSON write context will be initialized with an open object, so the bdev driver should write a name(based on the driver name) followed by a JSON value (most likely another nested object).

Parameters
bdevBlock device to query.
wJSON write context. It will store the driver-specific configuration context.
Returns
0 on success, negated errno on failure.

◆ spdk_bdev_finish()

void spdk_bdev_finish ( spdk_bdev_fini_cb  cb_fn,
void *  cb_arg 
)

Perform cleanup work to remove the registered block device modules.

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

◆ spdk_bdev_first()

struct spdk_bdev* spdk_bdev_first ( void  )

Get the first registered block device.

Returns
The first registered block device.

◆ spdk_bdev_first_leaf()

struct spdk_bdev* spdk_bdev_first_leaf ( void  )

Get the first block device without virtual block devices on top.

This function only traverses over block devices which have no virtual block devices on top of them, then get the first one.

Returns
The first block device without virtual block devices on top.

◆ spdk_bdev_free_io()

void spdk_bdev_free_io ( struct spdk_bdev_io bdev_io)

Free an I/O request.

This should only be called after the completion callback for the I/O has been called and notifies the bdev layer that memory may now be released.

Parameters
bdev_ioI/O request.

◆ spdk_bdev_get_acwu()

uint16_t spdk_bdev_get_acwu ( const struct spdk_bdev bdev)

Get block device atomic compare and write unit.

Parameters
bdevBlock device to query.
Returns
Atomic compare and write unit for this bdev in blocks.

◆ spdk_bdev_get_block_size()

uint32_t spdk_bdev_get_block_size ( const struct spdk_bdev bdev)

Get block device logical block size.

Parameters
bdevBlock device to query.
Returns
Size of logical block for this bdev in bytes.

◆ spdk_bdev_get_buf_align()

size_t spdk_bdev_get_buf_align ( const struct spdk_bdev bdev)

Get minimum I/O buffer address alignment for a bdev.

Parameters
bdevBlock device to query.
Returns
Required alignment of I/O buffers in bytes.

◆ spdk_bdev_get_by_name()

struct spdk_bdev* spdk_bdev_get_by_name ( const char *  bdev_name)

Get block device by the block device name.

Parameters
bdev_nameThe name of the block device.
Returns
Block device associated with the name or NULL if no block device with bdev_name is currently registered.

◆ spdk_bdev_get_data_block_size()

uint32_t spdk_bdev_get_data_block_size ( const struct spdk_bdev bdev)

Get block device data block size.

Data block size is equal to block size if there is no metadata or metadata is separated with block data, or equal to block size minus metadata size if there is metadata and it is interleaved with block data.

Parameters
bdevBlock device to query.
Returns
Size of data block for this bdev in bytes.

◆ spdk_bdev_get_device_stat()

void spdk_bdev_get_device_stat ( struct spdk_bdev bdev,
struct spdk_bdev_io_stat stat,
spdk_bdev_get_device_stat_cb  cb,
void *  cb_arg 
)

Return I/O statistics for this bdev.

All the required information will be passed via the callback function.

Parameters
bdevBlock device to query.
statStructure for aggregating collected statistics. Passed as argument to cb.
cbCalled when this operation completes.
cb_argArgument passed to callback function.

◆ spdk_bdev_get_dif_type()

enum spdk_dif_type spdk_bdev_get_dif_type ( const struct spdk_bdev bdev)

Get DIF type of the block device.

Parameters
bdevBlock device to query.
Returns
DIF type of the block device.

◆ spdk_bdev_get_io_channel()

struct spdk_io_channel* spdk_bdev_get_io_channel ( struct spdk_bdev_desc *  desc)

Obtain an I/O channel for the block device opened by the specified descriptor.

I/O channels are bound to threads, so the resulting I/O channel may only be used from the thread it was originally obtained from.

Parameters
descBlock device descriptor.
Returns
A handle to the I/O channel or NULL on failure.

◆ spdk_bdev_get_io_stat()

void spdk_bdev_get_io_stat ( struct spdk_bdev bdev,
struct spdk_io_channel ch,
struct spdk_bdev_io_stat stat 
)

Return I/O statistics for this channel.

Parameters
bdevBlock device.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
statThe per-channel statistics.

◆ spdk_bdev_get_io_time()

uint64_t spdk_bdev_get_io_time ( const struct spdk_bdev bdev)

Get the time spent processing IO for this device.

This value is dependent upon the queue depth sampling period and is incremented at sampling time by the sampling period only if the measured queue depth is greater than 0.

The disk utilization can be calculated by the following formula: disk_util = (io_time_2 - io_time_1) / elapsed_time. The user is responsible for tracking the elapsed time between two measurements.

Parameters
bdevBlock device to query.
Returns
The io time for this device in microseconds.

◆ spdk_bdev_get_md_size()

uint32_t spdk_bdev_get_md_size ( const struct spdk_bdev bdev)

Get block device metadata size.

Parameters
bdevBlock device to query.
Returns
Size of metadata for this bdev in bytes.

◆ spdk_bdev_get_media_events()

size_t spdk_bdev_get_media_events ( struct spdk_bdev_desc *  bdev_desc,
struct spdk_bdev_media_event events,
size_t  max_events 
)

Retrieves media events.

Can only be called from the context of SPDK_BDEV_EVENT_MEDIA_MANAGEMENT event callback. These events are sent by devices exposing raw access to the physical medium (e.g. Open Channel SSD).

Parameters
bdev_descBlock device descriptor
eventsArray of media mangement event descriptors
max_eventsSize of the events array
Returns
number of events retrieved

◆ spdk_bdev_get_name()

const char* spdk_bdev_get_name ( const struct spdk_bdev bdev)

Get block device name.

Parameters
bdevBlock device to query.
Returns
Name of bdev as a null-terminated string.

◆ spdk_bdev_get_num_blocks()

uint64_t spdk_bdev_get_num_blocks ( const struct spdk_bdev bdev)

Get size of block device in logical blocks.

Parameters
bdevBlock device to query.
Returns
Size of bdev in logical blocks.

Logical blocks are numbered from 0 to spdk_bdev_get_num_blocks(bdev) - 1, inclusive.

◆ spdk_bdev_get_optimal_io_boundary()

uint32_t spdk_bdev_get_optimal_io_boundary ( const struct spdk_bdev bdev)

Get optimal I/O boundary for a bdev.

Parameters
bdevBlock device to query.
Returns
Optimal I/O boundary in blocks that should not be crossed for best performance, or 0 if no optimal boundary is reported.

◆ spdk_bdev_get_product_name()

const char* spdk_bdev_get_product_name ( const struct spdk_bdev bdev)

Get block device product name.

Parameters
bdevBlock device to query.
Returns
Product name of bdev as a null-terminated string.

◆ spdk_bdev_get_qd()

uint64_t spdk_bdev_get_qd ( const struct spdk_bdev bdev)

Get the most recently measured queue depth from a bdev.

The reported queue depth is the aggregate of outstanding I/O across all open channels associated with this bdev.

Parameters
bdevBlock device to query.
Returns
The most recent queue depth measurement for the bdev. If tracking is not enabled, the function will return UINT64_MAX It is also possible to receive UINT64_MAX after enabling tracking but before the first period has expired.

◆ spdk_bdev_get_qd_sampling_period()

uint64_t spdk_bdev_get_qd_sampling_period ( const struct spdk_bdev bdev)

Get the queue depth polling period.

The return value of this function is only valid if the bdev's queue depth tracking status is set to true.

Parameters
bdevBlock device to query.
Returns
The period at which this bdev's gueue depth is being refreshed.

◆ spdk_bdev_get_qos_rate_limits()

void spdk_bdev_get_qos_rate_limits ( struct spdk_bdev bdev,
uint64_t *  limits 
)

Get the quality of service rate limits on a bdev.

Parameters
bdevBlock device to query.
limitsPointer to the QoS rate limits array which holding the limits.

The limits are ordered based on the spdk_bdev_qos_rate_limit_type enum.

◆ spdk_bdev_get_qos_rpc_type()

const char* spdk_bdev_get_qos_rpc_type ( enum spdk_bdev_qos_rate_limit_type  type)

Get the string of quality of service rate limit.

Parameters
typeType of rate limit to query.
Returns
String of QoS type.

◆ spdk_bdev_get_uuid()

const struct spdk_uuid* spdk_bdev_get_uuid ( const struct spdk_bdev bdev)

Get a bdev's UUID.

Parameters
bdevBlock device to query.
Returns
Pointer to UUID.

All bdevs will have a UUID, but not all UUIDs will be persistent across application runs.

◆ spdk_bdev_get_weighted_io_time()

uint64_t spdk_bdev_get_weighted_io_time ( const struct spdk_bdev bdev)

Get the weighted IO processing time for this bdev.

This value is dependent upon the queue depth sampling period and is equal to the time spent reading from or writing to a device times the measured queue depth during each sampling period.

The average queue depth can be calculated by the following formula: queue_depth = (weighted_io_time_2 - weighted_io_time_1) / elapsed_time. The user is responsible for tracking the elapsed time between two measurements.

Parameters
bdevBlock device to query.
Returns
The weighted io time for this device in microseconds.

◆ spdk_bdev_get_write_unit_size()

uint32_t spdk_bdev_get_write_unit_size ( const struct spdk_bdev bdev)

Get the write unit size for this bdev.

Write unit size is required number of logical blocks to perform write operation on block device.

Unit of write unit size is logical block and the minimum of write unit size is one. Write operations must be multiple of write unit size.

Parameters
bdevBlock device to query.
Returns
The write unit size in logical blocks.

◆ spdk_bdev_has_write_cache()

bool spdk_bdev_has_write_cache ( const struct spdk_bdev bdev)

Query whether block device has an enabled write cache.

Parameters
bdevBlock device to query.
Returns
true if block device has a volatile write cache enabled.

If this function returns true, written data may not be persistent until a flush command is issued.

◆ spdk_bdev_histogram_enable()

void spdk_bdev_histogram_enable ( struct spdk_bdev bdev,
spdk_bdev_histogram_status_cb  cb_fn,
void *  cb_arg,
bool  enable 
)

Enable or disable collecting histogram data on a bdev.

Parameters
bdevBlock device.
cb_fnCallback function to be called when histograms are enabled.
cb_argArgument to pass to cb_fn.
enableEnable/disable flag

◆ spdk_bdev_histogram_get()

void spdk_bdev_histogram_get ( struct spdk_bdev bdev,
struct spdk_histogram_data histogram,
spdk_bdev_histogram_data_cb  cb_fn,
void *  cb_arg 
)

Get aggregated histogram data from a bdev.

Callback provides merged histogram for specified bdev.

Parameters
bdevBlock device.
histogramHistogram for aggregated data
cb_fnCallback function to be called with data collected on bdev.
cb_argArgument to pass to cb_fn.

◆ spdk_bdev_initialize()

void spdk_bdev_initialize ( spdk_bdev_init_cb  cb_fn,
void *  cb_arg 
)

Initialize block device modules.

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

◆ spdk_bdev_io_get_iovec()

void spdk_bdev_io_get_iovec ( struct spdk_bdev_io bdev_io,
struct iovec **  iovp,
int *  iovcntp 
)

Get the iovec describing the data buffer of a bdev_io.

Parameters
bdev_ioI/O to describe with iovec.
iovpPointer to be filled with iovec.
iovcntpPointer to be filled with number of iovec entries.

◆ spdk_bdev_io_get_md_buf()

void* spdk_bdev_io_get_md_buf ( struct spdk_bdev_io bdev_io)

Get metadata buffer.

Only makes sense if the IO uses separate buffer for metadata transfer.

Parameters
bdev_ioI/O to retrieve the buffer from.
Returns
Pointer to metadata buffer, NULL if the IO doesn't use separate buffer for metadata transfer.

◆ spdk_bdev_io_get_nvme_fused_status()

void spdk_bdev_io_get_nvme_fused_status ( const struct spdk_bdev_io bdev_io,
uint32_t *  cdw0,
int *  first_sct,
int *  first_sc,
int *  second_sct,
int *  second_sc 
)

Get the status of bdev_io as an NVMe status codes and command specific completion queue value for fused operations such as compare-and-write.

Parameters
bdev_ioI/O to get the status from.
cdw0Command specific completion queue value
first_sctStatus Code Type return value for the first operation, as defined by the NVMe specification.
first_scStatus Code return value for the first operation, as defined by the NVMe specification.
second_sctStatus Code Type return value for the second operation, as defined by the NVMe specification.
second_scStatus Code return value for the second operation, as defined by the NVMe specification.

◆ spdk_bdev_io_get_nvme_status()

void spdk_bdev_io_get_nvme_status ( const struct spdk_bdev_io bdev_io,
uint32_t *  cdw0,
int *  sct,
int *  sc 
)

Get the status of bdev_io as an NVMe status code and command specific completion queue value.

Parameters
bdev_ioI/O to get the status from.
cdw0Command specific completion queue value
sctStatus Code Type return value, as defined by the NVMe specification.
scStatus Code return value, as defined by the NVMe specification.

◆ spdk_bdev_io_get_scsi_status()

void spdk_bdev_io_get_scsi_status ( const struct spdk_bdev_io bdev_io,
int *  sc,
int *  sk,
int *  asc,
int *  ascq 
)

Get the status of bdev_io as a SCSI status code.

Parameters
bdev_ioI/O to get the status from.
scSCSI Status Code.
skSCSI Sense Key.
ascSCSI Additional Sense Code.
ascqSCSI Additional Sense Code Qualifier.

◆ spdk_bdev_io_type_supported()

bool spdk_bdev_io_type_supported ( struct spdk_bdev bdev,
enum spdk_bdev_io_type  io_type 
)

Check whether the block device supports the I/O type.

Parameters
bdevBlock device to check.
io_typeThe specific I/O type like read, write, flush, unmap.
Returns
true if support, false otherwise.

◆ spdk_bdev_is_dif_check_enabled()

bool spdk_bdev_is_dif_check_enabled ( const struct spdk_bdev bdev,
enum spdk_dif_check_type  check_type 
)

Check whether the DIF check type is enabled.

Parameters
bdevBlock device to query.
check_typeThe specific DIF check type.
Returns
true if enabled, false otherwise.

◆ spdk_bdev_is_dif_head_of_md()

bool spdk_bdev_is_dif_head_of_md ( const struct spdk_bdev bdev)

Check whether DIF is set in the first 8 bytes or the last 8 bytes of metadata.

Parameters
bdevBlock device to query.
Returns
true if DIF is set in the first 8 bytes of metadata, or false if DIF is set in the last 8 bytes of metadata.

Note that this function is valid only if DIF type is not SPDK_DIF_DISABLE.

◆ spdk_bdev_is_md_interleaved()

bool spdk_bdev_is_md_interleaved ( const struct spdk_bdev bdev)

Query whether metadata is interleaved with block data or separated with block data.

Parameters
bdevBlock device to query.
Returns
true if metadata is interleaved with block data or false if metadata is separated with block data.

Note this function is valid only if there is metadata.

◆ spdk_bdev_is_md_separate()

bool spdk_bdev_is_md_separate ( const struct spdk_bdev bdev)

Query whether metadata is interleaved with block data or separated from block data.

Parameters
bdevBlock device to query.
Returns
true if metadata is separated from block data, false otherwise.

Note this function is valid only if there is metadata.

◆ spdk_bdev_is_zoned()

bool spdk_bdev_is_zoned ( const struct spdk_bdev bdev)

Checks if bdev supports zoned namespace semantics.

Parameters
bdevBlock device to query.
Returns
true if device supports zoned namespace sementics.

◆ spdk_bdev_next()

struct spdk_bdev* spdk_bdev_next ( struct spdk_bdev prev)

Get the next registered block device.

Parameters
prevThe current block device.
Returns
The next registered block device.

◆ spdk_bdev_next_leaf()

struct spdk_bdev* spdk_bdev_next_leaf ( struct spdk_bdev prev)

Get the next block device without virtual block devices on top.

This function only traverses over block devices which have no virtual block devices on top of them, then get the next one.

Parameters
prevThe current block device.
Returns
The next block device without virtual block devices on top.

◆ spdk_bdev_open()

int spdk_bdev_open ( struct spdk_bdev bdev,
bool  write,
spdk_bdev_remove_cb_t  remove_cb,
void *  remove_ctx,
struct spdk_bdev_desc **  desc 
)

Open a block device for I/O operations (deprecated, please use spdk_bdev_open_ext).

Parameters
bdevBlock device to open.
writetrue is read/write access requested, false if read-only
remove_cbnotification callback to be called when the bdev gets hotremoved. This will always be called on the same thread that spdk_bdev_open() was called on. It can be NULL, in which case the upper layer won't be notified about the bdev hotremoval. The descriptor will have to be manually closed to make the bdev unregister proceed.
remove_ctxparam for remove_cb.
descoutput parameter for the descriptor when operation is successful
Returns
0 if operation is successful, suitable errno value otherwise

◆ spdk_bdev_open_ext()

int spdk_bdev_open_ext ( const char *  bdev_name,
bool  write,
spdk_bdev_event_cb_t  event_cb,
void *  event_ctx,
struct spdk_bdev_desc **  desc 
)

Open a block device for I/O operations.

Parameters
bdev_nameBlock device name to open.
writetrue is read/write access requested, false if read-only
event_cbnotification callback to be called when the bdev triggers asynchronous event such as bdev removal. This will always be called on the same thread that spdk_bdev_open() was called on. In case of removal event the descriptor will have to be manually closed to make the bdev unregister proceed.
event_ctxparam for event_cb.
descoutput parameter for the descriptor when operation is successful
Returns
0 if operation is successful, suitable errno value otherwise

◆ spdk_bdev_queue_io_wait()

int spdk_bdev_queue_io_wait ( struct spdk_bdev bdev,
struct spdk_io_channel ch,
struct spdk_bdev_io_wait_entry entry 
)

Add an entry into the calling thread's queue to be notified when an spdk_bdev_io becomes available.

When one of the bdev I/O Submit Functions returns -ENOMEM, it means the spdk_bdev_io buffer pool has no available buffers. This function may be called to register a callback to be notified when a buffer becomes available on the calling thread.

The callback function will always be called on the same thread as this function was called.

This function must only be called immediately after one of the bdev I/O Submit Functions returns -ENOMEM.

Parameters
bdevBlock device. The block device that the caller will submit an I/O to when the callback is invoked. Must match the bdev member in the entry parameter.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
entryData structure allocated by the caller specifying the callback function and argument.
Returns
0 on success. -EINVAL if bdev parameter does not match bdev member in entry -EINVAL if an spdk_bdev_io structure was available on this thread.

◆ spdk_bdev_set_qd_sampling_period()

void spdk_bdev_set_qd_sampling_period ( struct spdk_bdev bdev,
uint64_t  period 
)

Enable or disable queue depth sampling for this bdev.

Enables queue depth sampling when period is greater than 0. Disables it when the period is equal to zero. The resulting queue depth is stored in the spdk_bdev object as measured_queue_depth.

Parameters
bdevBlock device on which to enable queue depth tracking.
periodThe period at which to poll this bdev's queue depth. If this is set to zero, polling will be disabled.

◆ spdk_bdev_set_qos_rate_limits()

void spdk_bdev_set_qos_rate_limits ( struct spdk_bdev bdev,
uint64_t *  limits,
void(*)(void *cb_arg, int status)  cb_fn,
void *  cb_arg 
)

Set the quality of service rate limits on a bdev.

Parameters
bdevBlock device.
limitsPointer to the QoS rate limits array which holding the limits.
cb_fnCallback function to be called when the QoS limit has been updated.
cb_argArgument to pass to cb_fn.

The limits are ordered based on the spdk_bdev_qos_rate_limit_type enum.

◆ spdk_bdev_set_timeout()

int spdk_bdev_set_timeout ( struct spdk_bdev_desc *  desc,
uint64_t  timeout_in_sec,
spdk_bdev_io_timeout_cb  cb_fn,
void *  cb_arg 
)

Set a time limit for the timeout IO of the bdev and timeout callback.

We can use this function to enable/disable the timeout handler. If the timeout_in_sec > 0 then it means to enable the timeout IO handling or change the time limit. If the timeout_in_sec == 0 it means to disable the timeout IO handling. If you want to enable or change the timeout IO handle you need to specify the spdk_bdev_io_timeout_cb it means the upper user determines what to do if you meet the timeout IO, for example, you can reset the device or abort the IO. Note: This function must run in the desc's thread.

Parameters
descBlock device descriptor.
timeout_in_secTimeout value
cb_fnBdev IO timeout callback
cb_argCallback argument
Returns
0 on success, negated errno on failure.

◆ spdk_bdev_subsystem_config_json()

void spdk_bdev_subsystem_config_json ( struct spdk_json_write_ctx *  w)

Get the full configuration options for the registered block device modules and created bdevs.

Parameters
wpointer to a JSON write context where the configuration will be written.

◆ spdk_bdev_zcopy_end()

int spdk_bdev_zcopy_end ( struct spdk_bdev_io bdev_io,
bool  commit,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a request to release a data buffer representing a range of blocks.

Parameters
bdev_ioI/O request returned in the completion callback of spdk_bdev_zcopy_start().
commitWhether to commit the data in the buffers to the blocks before releasing. The data does not need to be committed if it was not modified.
cbCalled when the request is complete.
cb_argArgument passed to cb.
Returns
0 on success. On success, the callback will always be called (even if the request ultimately failed). Return negated errno on failure, in which case the callback will not be called.

◆ spdk_bdev_zcopy_start()

int spdk_bdev_zcopy_start ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
uint64_t  offset_blocks,
uint64_t  num_blocks,
bool  populate,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a request to acquire a data buffer that represents the given range of blocks.

The data buffer is placed in the spdk_bdev_io structure and can be obtained by calling spdk_bdev_io_get_iovec().

Parameters
descBlock device descriptor
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks.
populateWhether the data buffer should be populated with the data at the given blocks. Populating the data buffer can be skipped if the user writes new data to the entire buffer.
cbCalled when the request is complete.
cb_argArgument passed to cb.
Returns
0 on success. On success, the callback will always be called (even if the request ultimately failed). Return negated errno on failure, in which case the callback will not be called.