bdev I/O Submit Functions

These functions submit a new I/O request to a bdev. More...

Functions

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_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...
 
int spdk_bdev_get_zone_info (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t zone_id, size_t num_zones, struct spdk_bdev_zone_info *info, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a get_zone_info request to the bdev. More...
 
int spdk_bdev_zone_management (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, uint64_t zone_id, enum spdk_bdev_zone_action action, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a zone_management request to the bdev. More...
 
int spdk_bdev_zone_append (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, uint64_t zone_id, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a zone_append request to the bdev. More...
 
int spdk_bdev_zone_appendv (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, uint64_t zone_id, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a zone_append request to the bdev. More...
 
int spdk_bdev_zone_append_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, void *buf, void *md, uint64_t zone_id, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a zone_append request with metadata to the bdev. More...
 
int spdk_bdev_zone_appendv_with_md (struct spdk_bdev_desc *desc, struct spdk_io_channel *ch, struct iovec *iov, int iovcnt, void *md, uint64_t zone_id, uint64_t num_blocks, spdk_bdev_io_completion_cb cb, void *cb_arg)
 Submit a zone_append request with metadata to the bdev. More...
 

Detailed Description

These functions submit a new I/O request to a bdev.

The I/O request will be represented by an spdk_bdev_io structure allocated from a global pool. These functions will return -ENOMEM if the spdk_bdev_io pool is empty.

Function Documentation

◆ spdk_bdev_compare_blocks()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to compare to.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to compare. buf must be greater than or equal to this size.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_compare_blocks_with_md()

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.

This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to compare to.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to compare. buf must be greater than or equal to this size.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_comparev_and_writev_blocks()

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.

For bdevs that do not natively support atomic compare-and-write, the bdev layer will quiesce I/O to the specified LBA range, before performing the read, compare and write operations.

Currently this supports compare-and-write of only one block.

The data buffers for both the compare and write operations are described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer out of the buffers provided. In this case, the request may fail.

spdk_bdev_io_get_nvme_fused_status() function should be called in callback function to get status for the individual operation.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
compare_iovA scatter gather list of buffers to be compared.
compare_iovcntThe number of elements in compare_iov.
write_iovA scatter gather list of buffers to be written if the compare is successful.
write_iovcntThe number of elements in write_iov.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to compare-and-write.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_comparev_blocks()

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.

This differs from spdk_bdev_compare by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer out of the buffers provided. In this case, the request may fail.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be compared to.
iovcntThe number of elements in iov.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to compare.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_comparev_blocks_with_md()

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.

This differs from spdk_bdev_compare by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data or metadata and may not be able to directly transfer out of the buffers provided. In this case, the request may fail. This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be compared to.
iovcntThe number of elements in iov.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to compare.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_flush()

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.

For devices with volatile caches, data is not guaranteed to be persistent until the completion of a flush request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
offsetThe offset, in bytes, from the start of the block device.
lengthThe number of bytes.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_flush_blocks()

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.

For devices with volatile caches, data is not guaranteed to be persistent until the completion of a flush request. Call spdk_bdev_has_write_cache() to check if the bdev has a volatile cache.

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.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_get_zone_info()

int spdk_bdev_get_zone_info ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
uint64_t  zone_id,
size_t  num_zones,
struct spdk_bdev_zone_info info,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a get_zone_info request to the bdev.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
zone_idFirst logical block of a zone.
num_zonesNumber of consecutive zones info to retrieve.
infoPointer to array capable of storing num_zones elements.
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_nvme_admin_passthru()

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.

This passes directly through the block layer to the device. Support for NVMe passthru is optional, indicated by calling spdk_bdev_io_type_supported().

The SGL/PRP will be automated generated based on the given buffer, so that portion of the command may be left empty.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
cmdThe raw NVMe command. Must be an admin command.
bufData buffer to written from.
nbytesThe number of bytes to transfer. buf must be greater than or equal to this size.
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.
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_nvme_io_passthru()

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.

This passes directly through the block layer to the device. Support for NVMe passthru is optional, indicated by calling spdk_bdev_io_type_supported().

The SGL/PRP will be automated generated based on the given buffer, so that portion of the command may be left empty. Also, the namespace id (nsid) will be populated automatically.

Parameters
bdev_descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
cmdThe raw NVMe command. Must be in the NVM command set.
bufData buffer to written from.
nbytesThe number of bytes to transfer. buf must be greater than or equal to this size.
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.
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_nvme_io_passthru_md()

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.

This passes directly through the block layer to the device. Support for NVMe passthru is optional, indicated by calling spdk_bdev_io_type_supported().

The SGL/PRP will be automated generated based on the given buffer, so that portion of the command may be left empty. Also, the namespace id (nsid) will be populated automatically.

Parameters
bdev_descBlock device descriptor
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
cmdThe raw NVMe command. Must be in the NVM command set.
bufData buffer to written from.
nbytesThe number of bytes to transfer. buf must be greater than or equal to this size.
md_bufMeta data buffer to written from.
md_lenmd_buf size to transfer. md_buf must be greater than or equal to this size.
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.
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_read()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to read into.
offsetThe offset, in bytes, from the start of the block device.
nbytesThe number of bytes to read.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_read_blocks()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to read into.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to read.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_read_blocks_with_md()

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.

This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to read into.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to read.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_readv()

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.

This differs from spdk_bdev_read by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer into the buffers provided. In this case, the request may fail.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be read into.
iovcntThe number of elements in iov.
offsetThe offset, in bytes, from the start of the block device.
nbytesThe number of bytes to read.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_readv_blocks()

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.

This differs from spdk_bdev_read by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer into the buffers provided. In this case, the request may fail.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be read into.
iovcntThe number of elements in iov.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to read.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_readv_blocks_with_md()

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.

This differs from spdk_bdev_read by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data or metadata and may not be able to directly transfer into the buffers provided. In this case, the request may fail. This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be read into.
iovcntThe number of elements in iov.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to read.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated

◆ spdk_bdev_reset()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
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_unmap()

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.

Unmap is sometimes also called trim or deallocate. This notifies the device that the data in the blocks described is no longer valid. Reading blocks that have been unmapped results in indeterminate data.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
offsetThe offset, in bytes, from the start of the block device.
nbytesThe number of bytes to unmap. Must be a multiple of the block size.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_unmap_blocks()

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.

Unmap is sometimes also called trim or deallocate. This notifies the device that the data in the blocks described is no longer valid. Reading blocks that have been unmapped results in indeterminate data.

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 to unmap.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_write()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to written from.
offsetThe offset, in bytes, from the start of the block device.
nbytesThe number of bytes to write. buf must be greater than or equal to this size.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_write_blocks()

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.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to written from.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_write_blocks_with_md()

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.

This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to written from.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_write_zeroes()

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.

This command ensures that all bytes in the specified range are set to 00h

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
offsetThe offset, in bytes, from the start of the block device.
lenThe size of data to zero.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_write_zeroes_blocks()

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.

This command ensures that all bytes in the specified range are set to 00h

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 to zero.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_writev()

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.

This differs from spdk_bdev_write by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer out of the buffers provided. In this case, the request may fail.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
offsetThe offset, in bytes, from the start of the block device.
lenThe size of data to write.
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.
  • -EINVAL - offset and/or nbytes are not aligned or out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_writev_blocks()

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.

This differs from spdk_bdev_write by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data and may not be able to directly transfer out of the buffers provided. In this case, the request may fail.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to write.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_writev_blocks_with_md()

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.

This differs from spdk_bdev_write by allowing the data buffer to be described in a scatter gather list. Some physical devices place memory alignment requirements on data or metadata and may not be able to directly transfer out of the buffers provided. In this case, the request may fail. This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
mdMetadata buffer.
offset_blocksThe offset, in blocks, from the start of the block device.
num_blocksThe number of blocks to write.
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.
  • -EINVAL - offset_blocks and/or num_blocks are out of range or separate metadata is not supported
  • -ENOMEM - spdk_bdev_io buffer cannot be allocated
  • -EBADF - desc not open for writing

◆ spdk_bdev_zone_append()

int spdk_bdev_zone_append ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
void *  buf,
uint64_t  zone_id,
uint64_t  num_blocks,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a zone_append request to the bdev.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to written from.
zone_idFirst logical block of a zone.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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). Appended logical block address can be obtained with spdk_bdev_io_get_append_location(). Return negated errno on failure, in which case the callback will not be called.

◆ spdk_bdev_zone_append_with_md()

int spdk_bdev_zone_append_with_md ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
void *  buf,
void *  md,
uint64_t  zone_id,
uint64_t  num_blocks,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a zone_append request with metadata to the bdev.

This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
bufData buffer to written from.
mdMetadata buffer.
zone_idFirst logical block of a zone.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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). Appended logical block address can be obtained with spdk_bdev_io_get_append_location(). Return negated errno on failure, in which case the callback will not be called.

◆ spdk_bdev_zone_appendv()

int spdk_bdev_zone_appendv ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
struct iovec *  iov,
int  iovcnt,
uint64_t  zone_id,
uint64_t  num_blocks,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a zone_append request to the bdev.

This differs from spdk_bdev_zone_append by allowing the data buffer to be described in a scatter gather list.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
zone_idFirst logical block of a zone.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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). Appended logical block address can be obtained with spdk_bdev_io_get_append_location(). Return negated errno on failure, in which case the callback will not be called.

◆ spdk_bdev_zone_appendv_with_md()

int spdk_bdev_zone_appendv_with_md ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
struct iovec *  iov,
int  iovcnt,
void *  md,
uint64_t  zone_id,
uint64_t  num_blocks,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a zone_append request with metadata to the bdev.

This differs from spdk_bdev_zone_append by allowing the data buffer to be described in a scatter gather list.

This function uses separate buffer for metadata transfer (valid only if bdev supports this mode).

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
iovA scatter gather list of buffers to be written from.
iovcntThe number of elements in iov.
mdMetadata buffer.
zone_idFirst logical block of a zone.
num_blocksThe number of blocks to write. buf must be greater than or equal to this size.
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). Appended logical block address can be obtained with spdk_bdev_io_get_append_location(). Return negated errno on failure, in which case the callback will not be called.

◆ spdk_bdev_zone_management()

int spdk_bdev_zone_management ( struct spdk_bdev_desc *  desc,
struct spdk_io_channel ch,
uint64_t  zone_id,
enum spdk_bdev_zone_action  action,
spdk_bdev_io_completion_cb  cb,
void *  cb_arg 
)

Submit a zone_management request to the bdev.

Parameters
descBlock device descriptor.
chI/O channel. Obtained by calling spdk_bdev_get_io_channel().
zone_idFirst logical block of a zone.
actionAction to perform on a zone (open, close, reset, finish).
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.