NVMe driver public API. More...

Data Structures

struct  spdk_nvme_ctrlr_opts
 NVMe controller initialization options. More...
 
struct  spdk_nvme_transport_id
 NVMe transport identifier. More...
 
struct  spdk_nvme_host_id
 NVMe host identifier. More...
 
struct  spdk_nvme_io_qpair_opts
 NVMe I/O queue pair initialization options. More...
 

Macros

#define SPDK_NVME_DEFAULT_RETRY_COUNT   (4)
 

Typedefs

typedef enum spdk_nvme_transport_type spdk_nvme_transport_type_t
 
typedef bool(* spdk_nvme_probe_cb) (void *cb_ctx, const struct spdk_nvme_transport_id *trid, struct spdk_nvme_ctrlr_opts *opts)
 Callback for spdk_nvme_probe() enumeration. More...
 
typedef void(* spdk_nvme_attach_cb) (void *cb_ctx, const struct spdk_nvme_transport_id *trid, struct spdk_nvme_ctrlr *ctrlr, const struct spdk_nvme_ctrlr_opts *opts)
 Callback for spdk_nvme_attach() to report a device that has been attached to the userspace NVMe driver. More...
 
typedef void(* spdk_nvme_remove_cb) (void *cb_ctx, struct spdk_nvme_ctrlr *ctrlr)
 Callback for spdk_nvme_remove() to report that a device attached to the userspace NVMe driver has been removed from the system. More...
 
typedef void(* spdk_nvme_cmd_cb) (void *, const struct spdk_nvme_cpl *)
 Signature for callback function invoked when a command is completed. More...
 
typedef void(* spdk_nvme_aer_cb) (void *aer_cb_arg, const struct spdk_nvme_cpl *)
 Signature for callback function invoked when an asynchronous error request command is completed. More...
 
typedef void(* spdk_nvme_timeout_cb) (void *cb_arg, struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, uint16_t cid)
 Signature for the callback function invoked when a timeout is detected on a request. More...
 
typedef void(* spdk_nvme_req_reset_sgl_cb) (void *cb_arg, uint32_t offset)
 Restart the SGL walk to the specified offset when the command has scattered payloads. More...
 
typedef int(* spdk_nvme_req_next_sge_cb) (void *cb_arg, void **address, uint32_t *length)
 Fill out *address and *length with the current SGL entry and advance to the next entry for the next time the callback is invoked. More...
 

Enumerations

enum  spdk_nvme_transport_type { SPDK_NVME_TRANSPORT_PCIE = 256, SPDK_NVME_TRANSPORT_RDMA = SPDK_NVMF_TRTYPE_RDMA, SPDK_NVME_TRANSPORT_FC = SPDK_NVMF_TRTYPE_FC, SPDK_NVME_TRANSPORT_TCP = SPDK_NVMF_TRTYPE_TCP }
 NVMe library transports. More...
 
enum  spdk_nvme_ctrlr_flags { SPDK_NVME_CTRLR_SGL_SUPPORTED = 0x1, SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED = 0x2 }
 
enum  spdk_nvme_ns_flags {
  SPDK_NVME_NS_DEALLOCATE_SUPPORTED = 0x1, SPDK_NVME_NS_FLUSH_SUPPORTED = 0x2, SPDK_NVME_NS_RESERVATION_SUPPORTED = 0x4, SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED = 0x8,
  SPDK_NVME_NS_DPS_PI_SUPPORTED = 0x10, SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED = 0x20
}
 Namespace command support flags. More...
 

Functions

bool spdk_nvme_ctrlr_is_discovery (struct spdk_nvme_ctrlr *ctrlr)
 Indicate whether a ctrlr handle is associated with a Discovery controller. More...
 
void spdk_nvme_ctrlr_get_default_ctrlr_opts (struct spdk_nvme_ctrlr_opts *opts, size_t opts_size)
 Get the default options for the creation of a specific NVMe controller. More...
 
int spdk_nvme_transport_id_parse (struct spdk_nvme_transport_id *trid, const char *str)
 Parse the string representation of a transport ID. More...
 
int spdk_nvme_host_id_parse (struct spdk_nvme_host_id *hostid, const char *str)
 Parse the string representation of a host ID. More...
 
int spdk_nvme_transport_id_parse_trtype (enum spdk_nvme_transport_type *trtype, const char *str)
 Parse the string representation of a transport ID tranport type. More...
 
const char * spdk_nvme_transport_id_trtype_str (enum spdk_nvme_transport_type trtype)
 Look up the string representation of a transport ID transport type. More...
 
const char * spdk_nvme_transport_id_adrfam_str (enum spdk_nvmf_adrfam adrfam)
 Look up the string representation of a transport ID address family. More...
 
int spdk_nvme_transport_id_parse_adrfam (enum spdk_nvmf_adrfam *adrfam, const char *str)
 Parse the string representation of a tranport ID address family. More...
 
int spdk_nvme_transport_id_compare (const struct spdk_nvme_transport_id *trid1, const struct spdk_nvme_transport_id *trid2)
 Compare two transport IDs. More...
 
int spdk_nvme_prchk_flags_parse (uint32_t *prchk_flags, const char *str)
 Parse the string representation of PI check settings (prchk:guard|reftag) More...
 
const char * spdk_nvme_prchk_flags_str (uint32_t prchk_flags)
 Look up the string representation of PI check settings (prchk:guard|reftag) More...
 
bool spdk_nvme_transport_available (enum spdk_nvme_transport_type trtype)
 Determine whether the NVMe library can handle a specific NVMe over Fabrics transport type. More...
 
int spdk_nvme_probe (const struct spdk_nvme_transport_id *trid, void *cb_ctx, spdk_nvme_probe_cb probe_cb, spdk_nvme_attach_cb attach_cb, spdk_nvme_remove_cb remove_cb)
 Enumerate the bus indicated by the transport ID and attach the userspace NVMe driver to each device found if desired. More...
 
struct spdk_nvme_ctrlr * spdk_nvme_connect (const struct spdk_nvme_transport_id *trid, const struct spdk_nvme_ctrlr_opts *opts, size_t opts_size)
 Connect the NVMe driver to the device located at the given transport ID. More...
 
struct spdk_nvme_probe_ctx * spdk_nvme_connect_async (const struct spdk_nvme_transport_id *trid, const struct spdk_nvme_ctrlr_opts *opts, spdk_nvme_attach_cb attach_cb)
 Connect the NVMe driver to the device located at the given transport ID. More...
 
struct spdk_nvme_probe_ctx * spdk_nvme_probe_async (const struct spdk_nvme_transport_id *trid, void *cb_ctx, spdk_nvme_probe_cb probe_cb, spdk_nvme_attach_cb attach_cb, spdk_nvme_remove_cb remove_cb)
 Probe and add controllers to the probe context list. More...
 
int spdk_nvme_probe_poll_async (struct spdk_nvme_probe_ctx *probe_ctx)
 Start controllers in the context list. More...
 
int spdk_nvme_detach (struct spdk_nvme_ctrlr *ctrlr)
 Detach specified device returned by spdk_nvme_probe()'s attach_cb from the NVMe driver. More...
 
int spdk_nvme_ctrlr_reset (struct spdk_nvme_ctrlr *ctrlr)
 Perform a full hardware reset of the NVMe controller. More...
 
const struct spdk_nvme_ctrlr_dataspdk_nvme_ctrlr_get_data (struct spdk_nvme_ctrlr *ctrlr)
 Get the identify controller data as defined by the NVMe specification. More...
 
union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller CSTS (Status) register. More...
 
union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller CAP (Capabilities) register. More...
 
union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller VS (Version) register. More...
 
union spdk_nvme_cmbsz_register spdk_nvme_ctrlr_get_regs_cmbsz (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller CMBSZ (Controller Memory Buffer Size) register. More...
 
uint32_t spdk_nvme_ctrlr_get_num_ns (struct spdk_nvme_ctrlr *ctrlr)
 Get the number of namespaces for the given NVMe controller. More...
 
struct spdk_pci_devicespdk_nvme_ctrlr_get_pci_device (struct spdk_nvme_ctrlr *ctrlr)
 Get the PCI device of a given NVMe controller. More...
 
uint32_t spdk_nvme_ctrlr_get_max_xfer_size (const struct spdk_nvme_ctrlr *ctrlr)
 Get the maximum data transfer size of a given NVMe controller. More...
 
bool spdk_nvme_ctrlr_is_active_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid)
 Check whether the nsid is an active nv for the given NVMe controller. More...
 
uint32_t spdk_nvme_ctrlr_get_first_active_ns (struct spdk_nvme_ctrlr *ctrlr)
 Get the nsid of the first active namespace. More...
 
uint32_t spdk_nvme_ctrlr_get_next_active_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t prev_nsid)
 Get next active namespace given the previous nsid. More...
 
bool spdk_nvme_ctrlr_is_log_page_supported (struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page)
 Determine if a particular log page is supported by the given NVMe controller. More...
 
bool spdk_nvme_ctrlr_is_feature_supported (struct spdk_nvme_ctrlr *ctrlr, uint8_t feature_code)
 Determine if a particular feature is supported by the given NVMe controller. More...
 
void spdk_nvme_ctrlr_register_aer_callback (struct spdk_nvme_ctrlr *ctrlr, spdk_nvme_aer_cb aer_cb_fn, void *aer_cb_arg)
 Register callback function invoked when an AER command is completed for the given NVMe controller. More...
 
void spdk_nvme_ctrlr_register_timeout_callback (struct spdk_nvme_ctrlr *ctrlr, uint64_t timeout_us, spdk_nvme_timeout_cb cb_fn, void *cb_arg)
 Register for timeout callback on a controller. More...
 
void spdk_nvme_ctrlr_get_default_io_qpair_opts (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_io_qpair_opts *opts, size_t opts_size)
 Get the default options for I/O qpair creation for a specific NVMe controller. More...
 
struct spdk_nvme_qpair * spdk_nvme_ctrlr_alloc_io_qpair (struct spdk_nvme_ctrlr *ctrlr, const struct spdk_nvme_io_qpair_opts *opts, size_t opts_size)
 Allocate an I/O queue pair (submission and completion queue). More...
 
int spdk_nvme_ctrlr_free_io_qpair (struct spdk_nvme_qpair *qpair)
 Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair(). More...
 
int spdk_nvme_ctrlr_io_cmd_raw_no_payload_build (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, struct spdk_nvme_cmd *cmd, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send the given NVM I/O command, I/O buffers, lists and all to the NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_io_raw (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, struct spdk_nvme_cmd *cmd, void *buf, uint32_t len, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send the given NVM I/O command to the NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_io_raw_with_md (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, struct spdk_nvme_cmd *cmd, void *buf, uint32_t len, void *md_buf, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send the given NVM I/O command with metadata to the NVMe controller. More...
 
int32_t spdk_nvme_qpair_process_completions (struct spdk_nvme_qpair *qpair, uint32_t max_completions)
 Process any outstanding completions for I/O submitted on a queue pair. More...
 
int spdk_nvme_ctrlr_cmd_admin_raw (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_cmd *cmd, void *buf, uint32_t len, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send the given admin command to the NVMe controller. More...
 
int32_t spdk_nvme_ctrlr_process_admin_completions (struct spdk_nvme_ctrlr *ctrlr)
 Process any outstanding completions for admin commands. More...
 
struct spdk_nvme_ns * spdk_nvme_ctrlr_get_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t ns_id)
 Get a handle to a namespace for the given controller. More...
 
int spdk_nvme_ctrlr_cmd_get_log_page (struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page, uint32_t nsid, void *payload, uint32_t payload_size, uint64_t offset, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Get a specific log page from the NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_abort (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, uint16_t cid, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Abort a specific previously-submitted NVMe command. More...
 
int spdk_nvme_ctrlr_cmd_set_feature (struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, uint32_t cdw11, uint32_t cdw12, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Set specific feature for the given NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_get_feature (struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, uint32_t cdw11, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Get specific feature from given NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_get_feature_ns (struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, uint32_t cdw11, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id)
 Get specific feature from given NVMe controller. More...
 
int spdk_nvme_ctrlr_cmd_set_feature_ns (struct spdk_nvme_ctrlr *ctrlr, uint8_t feature, uint32_t cdw11, uint32_t cdw12, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t ns_id)
 Set specific feature for the given NVMe controller and namespace ID. More...
 
int spdk_nvme_ctrlr_security_receive (struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, uint8_t nssf, void *payload, size_t size)
 Receive security protocol data from controller. More...
 
int spdk_nvme_ctrlr_security_send (struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, uint8_t nssf, void *payload, size_t size)
 Send security protocol data to controller. More...
 
uint64_t spdk_nvme_ctrlr_get_flags (struct spdk_nvme_ctrlr *ctrlr)
 Get supported flags of the controller. More...
 
int spdk_nvme_ctrlr_attach_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, struct spdk_nvme_ctrlr_list *payload)
 Attach the specified namespace to controllers. More...
 
int spdk_nvme_ctrlr_detach_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, struct spdk_nvme_ctrlr_list *payload)
 Detach the specified namespace from controllers. More...
 
uint32_t spdk_nvme_ctrlr_create_ns (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_ns_data *payload)
 Create a namespace. More...
 
int spdk_nvme_ctrlr_delete_ns (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid)
 Delete a namespace. More...
 
int spdk_nvme_ctrlr_format (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, struct spdk_nvme_format *format)
 Format NVM. More...
 
int spdk_nvme_ctrlr_update_firmware (struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size, int slot, enum spdk_nvme_fw_commit_action commit_action, struct spdk_nvme_status *completion_status)
 Download a new firmware image. More...
 
volatile struct spdk_nvme_registersspdk_nvme_ctrlr_get_registers (struct spdk_nvme_ctrlr *ctrlr)
 Return virtual address of PCIe NVM I/O registers. More...
 
void * spdk_nvme_ctrlr_alloc_cmb_io_buffer (struct spdk_nvme_ctrlr *ctrlr, size_t size)
 Allocate an I/O buffer from the controller memory buffer (Experimental). More...
 
void spdk_nvme_ctrlr_free_cmb_io_buffer (struct spdk_nvme_ctrlr *ctrlr, void *buf, size_t size)
 Free a controller memory I/O buffer (Experimental). More...
 
const struct spdk_nvme_transport_idspdk_nvme_ctrlr_get_transport_id (struct spdk_nvme_ctrlr *ctrlr)
 Get the transport ID for a given NVMe controller. More...
 
const struct spdk_nvme_ns_dataspdk_nvme_ns_get_data (struct spdk_nvme_ns *ns)
 Get the identify namespace data as defined by the NVMe specification. More...
 
uint32_t spdk_nvme_ns_get_id (struct spdk_nvme_ns *ns)
 Get the namespace id (index number) from the given namespace handle. More...
 
struct spdk_nvme_ctrlr * spdk_nvme_ns_get_ctrlr (struct spdk_nvme_ns *ns)
 Get the controller with which this namespace is associated. More...
 
bool spdk_nvme_ns_is_active (struct spdk_nvme_ns *ns)
 Determine whether a namespace is active. More...
 
uint32_t spdk_nvme_ns_get_max_io_xfer_size (struct spdk_nvme_ns *ns)
 Get the maximum transfer size, in bytes, for an I/O sent to the given namespace. More...
 
uint32_t spdk_nvme_ns_get_sector_size (struct spdk_nvme_ns *ns)
 Get the sector size, in bytes, of the given namespace. More...
 
uint32_t spdk_nvme_ns_get_extended_sector_size (struct spdk_nvme_ns *ns)
 Get the extended sector size, in bytes, of the given namespace. More...
 
uint64_t spdk_nvme_ns_get_num_sectors (struct spdk_nvme_ns *ns)
 Get the number of sectors for the given namespace. More...
 
uint64_t spdk_nvme_ns_get_size (struct spdk_nvme_ns *ns)
 Get the size, in bytes, of the given namespace. More...
 
enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type (struct spdk_nvme_ns *ns)
 Get the end-to-end data protection information type of the given namespace. More...
 
uint32_t spdk_nvme_ns_get_md_size (struct spdk_nvme_ns *ns)
 Get the metadata size, in bytes, of the given namespace. More...
 
bool spdk_nvme_ns_supports_extended_lba (struct spdk_nvme_ns *ns)
 Check whether if the namespace can support extended LBA when end-to-end data protection enabled. More...
 
enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value (struct spdk_nvme_ns *ns)
 Determine the value returned when reading deallocated blocks. More...
 
uint32_t spdk_nvme_ns_get_optimal_io_boundary (struct spdk_nvme_ns *ns)
 Get the optimal I/O boundary, in blocks, for the given namespace. More...
 
const struct spdk_uuidspdk_nvme_ns_get_uuid (const struct spdk_nvme_ns *ns)
 Get the UUID for the given namespace. More...
 
uint32_t spdk_nvme_ns_get_flags (struct spdk_nvme_ns *ns)
 Get the flags for the given namespace. More...
 
int spdk_nvme_ns_cmd_write (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags)
 Submit a write I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_writev (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn)
 Submit a write I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_writev_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, uint16_t apptag_mask, uint16_t apptag)
 Submit a write I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_write_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, void *metadata, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, uint16_t apptag_mask, uint16_t apptag)
 Submit a write I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_write_zeroes (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags)
 Submit a write zeroes I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_read (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags)
 Submits a read I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_readv (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn)
 Submit a read I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_readv_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn, void *metadata, uint16_t apptag_mask, uint16_t apptag)
 Submit a read I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_read_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, void *metadata, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, uint16_t apptag_mask, uint16_t apptag)
 Submits a read I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_dataset_management (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint32_t type, const struct spdk_nvme_dsm_range *ranges, uint16_t num_ranges, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a data set management request to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_flush (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a flush request to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_reservation_register (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, struct spdk_nvme_reservation_register_data *payload, bool ignore_key, enum spdk_nvme_reservation_register_action action, enum spdk_nvme_reservation_register_cptpl cptpl, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a reservation register to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_reservation_release (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, struct spdk_nvme_reservation_key_data *payload, bool ignore_key, enum spdk_nvme_reservation_release_action action, enum spdk_nvme_reservation_type type, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submits a reservation release to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_reservation_acquire (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, struct spdk_nvme_reservation_acquire_data *payload, bool ignore_key, enum spdk_nvme_reservation_acquire_action action, enum spdk_nvme_reservation_type type, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submits a reservation acquire to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_reservation_report (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint32_t len, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a reservation report to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_compare (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags)
 Submit a compare I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_comparev (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn)
 Submit a compare I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_compare_with_md (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, void *metadata, uint64_t lba, uint32_t lba_count, spdk_nvme_cmd_cb cb_fn, void *cb_arg, uint32_t io_flags, uint16_t apptag_mask, uint16_t apptag)
 Submit a compare I/O to the specified NVMe namespace. More...
 
int spdk_nvme_qpair_add_cmd_error_injection (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, uint8_t opc, bool do_not_submit, uint64_t timeout_in_us, uint32_t err_count, uint8_t sct, uint8_t sc)
 Inject an error for the next request with a given opcode. More...
 
void spdk_nvme_qpair_remove_cmd_error_injection (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, uint8_t opc)
 Clear the specified NVMe command with error status. More...
 

Variables

int32_t spdk_nvme_retry_count
 

Detailed Description

NVMe driver public API.

Typedef Documentation

◆ spdk_nvme_aer_cb

typedef void(* spdk_nvme_aer_cb) (void *aer_cb_arg, const struct spdk_nvme_cpl *)

Signature for callback function invoked when an asynchronous error request command is completed.

Parameters
ctrlrOpaque handle to NVMe controller.
aer_cb_argContext specified by spdk_nvme_register_aer_callback().
spdk_nvme_cplCompletion queue entry that contains the completion status of the asynchronous event request that was completed.

◆ spdk_nvme_attach_cb

typedef void(* spdk_nvme_attach_cb) (void *cb_ctx, const struct spdk_nvme_transport_id *trid, struct spdk_nvme_ctrlr *ctrlr, const struct spdk_nvme_ctrlr_opts *opts)

Callback for spdk_nvme_attach() to report a device that has been attached to the userspace NVMe driver.

Parameters
cb_ctxOpaque value passed to spdk_nvme_attach_cb().
tridNVMe transport identifier.
ctrlrOpaque handle to NVMe controller.
optsNVMe controller initialization options that were actually used. Options may differ from the requested options from the attach call depending on what the controller supports.

◆ spdk_nvme_cmd_cb

typedef void(* spdk_nvme_cmd_cb) (void *, const struct spdk_nvme_cpl *)

Signature for callback function invoked when a command is completed.

Parameters
spdk_nvme_cplCompletion queue entry that coontains the completion status.

◆ spdk_nvme_probe_cb

typedef bool(* spdk_nvme_probe_cb) (void *cb_ctx, const struct spdk_nvme_transport_id *trid, struct spdk_nvme_ctrlr_opts *opts)

Callback for spdk_nvme_probe() enumeration.

Parameters
cb_ctxOpaque value passed to spdk_nvme_probe().
tridNVMe transport identifier.
optsNVMe controller initialization options. This structure will be populated with the default values on entry, and the user callback may update any options to request a different value. The controller may not support all requested parameters, so the final values will be provided during the attach callback.
Returns
true to attach to this device.

◆ spdk_nvme_remove_cb

typedef void(* spdk_nvme_remove_cb) (void *cb_ctx, struct spdk_nvme_ctrlr *ctrlr)

Callback for spdk_nvme_remove() to report that a device attached to the userspace NVMe driver has been removed from the system.

The controller will remain in a failed state (any new I/O submitted will fail).

The controller must be detached from the userspace driver by calling spdk_nvme_detach() once the controller is no longer in use. It is up to the library user to ensure that no other threads are using the controller before calling spdk_nvme_detach().

Parameters
cb_ctxOpaque value passed to spdk_nvme_remove_cb().
ctrlrNVMe controller instance that was removed.

◆ spdk_nvme_req_next_sge_cb

typedef int(* spdk_nvme_req_next_sge_cb) (void *cb_arg, void **address, uint32_t *length)

Fill out *address and *length with the current SGL entry and advance to the next entry for the next time the callback is invoked.

The described segment must be physically contiguous.

Parameters
cb_argArgument passed to readv/writev.
addressVirtual address of this segment.
lengthLength of this physical segment.

◆ spdk_nvme_req_reset_sgl_cb

typedef void(* spdk_nvme_req_reset_sgl_cb) (void *cb_arg, uint32_t offset)

Restart the SGL walk to the specified offset when the command has scattered payloads.

Parameters
cb_argArgument passed to readv/writev.
offsetOffset for SGL.

◆ spdk_nvme_timeout_cb

typedef void(* spdk_nvme_timeout_cb) (void *cb_arg, struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, uint16_t cid)

Signature for the callback function invoked when a timeout is detected on a request.

For timeouts detected on the admin queue pair, the qpair returned here will be NULL. If the controller has a serious error condition and is unable to communicate with driver via completion queue, the controller can set Controller Fatal Status field to 1, then reset is required to recover from such error. Users may detect Controller Fatal Status when timeout happens.

Parameters
cb_argArgument passed to callback funciton.
ctrlrOpaque handle to NVMe controller.
qpairOpaque handle to a queue pair.
cidCommand ID.

Enumeration Type Documentation

◆ spdk_nvme_ctrlr_flags

Enumerator
SPDK_NVME_CTRLR_SGL_SUPPORTED 

The SGL is supported.

SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED 

security send/receive is supported

◆ spdk_nvme_ns_flags

Namespace command support flags.

Enumerator
SPDK_NVME_NS_DEALLOCATE_SUPPORTED 

The deallocate command is supported.

SPDK_NVME_NS_FLUSH_SUPPORTED 

The flush command is supported.

SPDK_NVME_NS_RESERVATION_SUPPORTED 

The reservation command is supported.

SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED 

The write zeroes command is supported.

SPDK_NVME_NS_DPS_PI_SUPPORTED 

The end-to-end data protection is supported.

SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED 

The extended lba format is supported, metadata is transferred as a contiguous part of the logical block that it is associated with.

◆ spdk_nvme_transport_type

NVMe library transports.

NOTE: These are mapped directly to the NVMe over Fabrics TRTYPE values, except for PCIe, which is a special case since NVMe over Fabrics does not define a TRTYPE for local PCIe.

Currently, this uses 256 for PCIe which is intentionally outside of the 8-bit range of TRTYPE. If the NVMe-oF specification ever defines a PCIe TRTYPE, this should be updated.

Enumerator
SPDK_NVME_TRANSPORT_PCIE 

PCIe Transport (locally attached devices)

SPDK_NVME_TRANSPORT_RDMA 

RDMA Transport (RoCE, iWARP, etc.)

SPDK_NVME_TRANSPORT_FC 

Fibre Channel (FC) Transport.

SPDK_NVME_TRANSPORT_TCP 

TCP Transport.

Function Documentation

◆ spdk_nvme_connect()

struct spdk_nvme_ctrlr* spdk_nvme_connect ( const struct spdk_nvme_transport_id trid,
const struct spdk_nvme_ctrlr_opts opts,
size_t  opts_size 
)

Connect the NVMe driver to the device located at the given transport ID.

This function is not thread safe and should only be called from one thread at a time while no other threads are actively using this NVMe device.

If called from a secondary process, only the device that has been attached to the userspace driver in the primary process will be connected.

If connecting to multiple controllers, it is suggested to use spdk_nvme_probe() and filter the requested controllers with the probe callback. For PCIe controllers, spdk_nvme_probe() will be more efficient since the controller resets will happen in parallel.

To stop using the the controller and release its associated resources, call spdk_nvme_detach() with the spdk_nvme_ctrlr instance returned by this function.

Parameters
tridThe transport ID indicating which device to connect. If the trtype is PCIe, this will connect the local PCIe bus. If the trtype is RDMA, the traddr and trsvcid must point at the location of an NVMe-oF service.
optsNVMe controller initialization options. Default values will be used if the user does not specify the options. The controller may not support all requested parameters.
opts_sizeMust be set to sizeof(struct spdk_nvme_ctrlr_opts), or 0 if opts is NULL.
Returns
pointer to the connected NVMe controller or NULL if there is any failure.

◆ spdk_nvme_connect_async()

struct spdk_nvme_probe_ctx* spdk_nvme_connect_async ( const struct spdk_nvme_transport_id trid,
const struct spdk_nvme_ctrlr_opts opts,
spdk_nvme_attach_cb  attach_cb 
)

Connect the NVMe driver to the device located at the given transport ID.

The function will return a probe context on success, controller associates with the context is not ready for use, user must call spdk_nvme_probe_poll_async() until spdk_nvme_probe_poll_async() returns 0.

Parameters
tridThe transport ID indicating which device to connect. If the trtype is PCIe, this will connect the local PCIe bus. If the trtype is RDMA, the traddr and trsvcid must point at the location of an NVMe-oF service.
optsNVMe controller initialization options. Default values will be used if the user does not specify the options. The controller may not support all requested parameters.
attach_cbwill be called once the NVMe controller has been attached to the userspace driver.
Returns
probe context on success, NULL on failure.

◆ spdk_nvme_ctrlr_alloc_cmb_io_buffer()

void* spdk_nvme_ctrlr_alloc_cmb_io_buffer ( struct spdk_nvme_ctrlr *  ctrlr,
size_t  size 
)

Allocate an I/O buffer from the controller memory buffer (Experimental).

This function allocates registered memory which belongs to the Controller Memory Buffer (CMB) of the specified NVMe controller. Note that the CMB has to support the WDS and RDS capabilities for the allocation to be successful. Also, due to vtophys contraints the CMB must be at least 4MiB in size. Free memory allocated with this function using spdk_nvme_ctrlr_free_cmb_io_buffer().

Parameters
ctrlrController from which to allocate memory buffer.
sizeSize of buffer to allocate in bytes.
Returns
Pointer to controller memory buffer allocation, or NULL if allocation was not possible.

◆ spdk_nvme_ctrlr_alloc_io_qpair()

struct spdk_nvme_qpair* spdk_nvme_ctrlr_alloc_io_qpair ( struct spdk_nvme_ctrlr *  ctrlr,
const struct spdk_nvme_io_qpair_opts opts,
size_t  opts_size 
)

Allocate an I/O queue pair (submission and completion queue).

Each queue pair should only be used from a single thread at a time (mutual exclusion must be enforced by the user).

Parameters
ctrlrNVMe controller for which to allocate the I/O queue pair.
optsI/O qpair creation options, or NULL to use the defaults as returned by spdk_nvme_ctrlr_alloc_io_qpair().
opts_sizeMust be set to sizeof(struct spdk_nvme_io_qpair_opts), or 0 if opts is NULL.
Returns
a pointer to the allocated I/O queue pair.

◆ spdk_nvme_ctrlr_attach_ns()

int spdk_nvme_ctrlr_attach_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
struct spdk_nvme_ctrlr_list payload 
)

Attach the specified namespace to controllers.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrNVMe controller to use for command submission.
nsidNamespace identifier for namespace to attach.
payloadThe pointer to the controller list.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_cmd_abort()

int spdk_nvme_ctrlr_cmd_abort ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
uint16_t  cid,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Abort a specific previously-submitted NVMe command.

See also
spdk_nvme_ctrlr_register_timeout_callback()
Parameters
ctrlrNVMe controller to which the command was submitted.
qpairNVMe queue pair to which the command was submitted. For admin commands, pass NULL for the qpair.
cidCommand ID of the command to abort.
cb_fnCallback function to invoke when the abort has completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno value otherwise.

◆ spdk_nvme_ctrlr_cmd_admin_raw()

int spdk_nvme_ctrlr_cmd_admin_raw ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_cmd cmd,
void *  buf,
uint32_t  len,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send the given admin command to the NVMe controller.

This is a low level interface for submitting admin commands directly. Prefer the spdk_nvme_ctrlr_cmd_* functions instead. The validity of the command will not be checked!

When constructing the nvme_command it is not necessary to fill out the PRP list/SGL or the CID. The driver will handle both of those for you.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrOpaque handle to NVMe controller.
cmdNVM admin command to submit.
bufVirtual memory address of a single physically contiguous buffer.
lenSize of buffer.
cb_fnCallback function invoked when the admin command completes.
cb_argArgument passed to callback function.
Returns
0 on success, negated errno on failure.

◆ spdk_nvme_ctrlr_cmd_get_feature()

int spdk_nvme_ctrlr_cmd_get_feature ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  feature,
uint32_t  cdw11,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Get specific feature from given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

See also
spdk_nvme_ctrlr_cmd_set_feature()
Parameters
ctrlrNVMe controller to query.
featureThe feature identifier.
cdw11as defined by the specification for this command.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the feature has been retrieved.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_cmd_get_feature_ns()

int spdk_nvme_ctrlr_cmd_get_feature_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  feature,
uint32_t  cdw11,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  ns_id 
)

Get specific feature from given NVMe controller.

Parameters
ctrlrNVMe controller to query.
featureThe feature identifier.
cdw11as defined by the specification for this command.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the feature has been retrieved.
cb_argArgument to pass to the callback function.
ns_idThe namespace identifier.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

See also
spdk_nvme_ctrlr_cmd_set_feature_ns()

◆ spdk_nvme_ctrlr_cmd_get_log_page()

int spdk_nvme_ctrlr_cmd_get_log_page ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  log_page,
uint32_t  nsid,
void *  payload,
uint32_t  payload_size,
uint64_t  offset,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Get a specific log page from the NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

See also
spdk_nvme_ctrlr_is_log_page_supported()
Parameters
ctrlrOpaque handle to NVMe controller.
log_pageThe log page identifier.
nsidDepending on the log page, this may be 0, a namespace identifier, or SPDK_NVME_GLOBAL_NS_TAG.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
offsetOffset in bytes within the log page to start retrieving log page data. May only be non-zero if the controller supports extended data for Get Log Page as reported in the controller data log page attributes.
cb_fnCallback function to invoke when the log page has been retrieved.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_cmd_io_raw()

int spdk_nvme_ctrlr_cmd_io_raw ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cmd cmd,
void *  buf,
uint32_t  len,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send the given NVM I/O command to the NVMe controller.

This is a low level interface for submitting I/O commands directly. Prefer the spdk_nvme_ns_cmd_* functions instead. The validity of the command will not be checked!

When constructing the nvme_command it is not necessary to fill out the PRP list/SGL or the CID. The driver will handle both of those for you.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
ctrlrOpaque handle to NVMe controller.
qpairI/O qpair to submit command.
cmdNVM I/O command to submit.
bufVirtual memory address of a single physically contiguous buffer.
lenSize of buffer.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success, negated errno on failure.

◆ spdk_nvme_ctrlr_cmd_io_raw_with_md()

int spdk_nvme_ctrlr_cmd_io_raw_with_md ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cmd cmd,
void *  buf,
uint32_t  len,
void *  md_buf,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send the given NVM I/O command with metadata to the NVMe controller.

This is a low level interface for submitting I/O commands directly. Prefer the spdk_nvme_ns_cmd_* functions instead. The validity of the command will not be checked!

When constructing the nvme_command it is not necessary to fill out the PRP list/SGL or the CID. The driver will handle both of those for you.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
ctrlrOpaque handle to NVMe controller.
qpairI/O qpair to submit command.
cmdNVM I/O command to submit.
bufVirtual memory address of a single physically contiguous buffer.
lenSize of buffer.
md_bufVirtual memory address of a single physically contiguous metadata buffer.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success, negated errno on failure.

◆ spdk_nvme_ctrlr_cmd_set_feature()

int spdk_nvme_ctrlr_cmd_set_feature ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  feature,
uint32_t  cdw11,
uint32_t  cdw12,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Set specific feature for the given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

See also
spdk_nvme_ctrlr_cmd_get_feature().
Parameters
ctrlrNVMe controller to manipulate.
featureThe feature identifier.
cdw11as defined by the specification for this command.
cdw12as defined by the specification for this command.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the feature has been set.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_cmd_set_feature_ns()

int spdk_nvme_ctrlr_cmd_set_feature_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  feature,
uint32_t  cdw11,
uint32_t  cdw12,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  ns_id 
)

Set specific feature for the given NVMe controller and namespace ID.

Parameters
ctrlrNVMe controller to manipulate.
featureThe feature identifier.
cdw11as defined by the specification for this command.
cdw12as defined by the specification for this command.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the feature has been set.
cb_argArgument to pass to the callback function.
ns_idThe namespace identifier.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

See also
spdk_nvme_ctrlr_cmd_get_feature_ns()

◆ spdk_nvme_ctrlr_create_ns()

uint32_t spdk_nvme_ctrlr_create_ns ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_ns_data payload 
)

Create a namespace.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Parameters
ctrlrNVMe controller to create namespace on.
payloadThe pointer to the NVMe namespace data.
Returns
Namespace ID (>= 1) if successfully created, or 0 if the request failed.

◆ spdk_nvme_ctrlr_delete_ns()

int spdk_nvme_ctrlr_delete_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid 
)

Delete a namespace.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrNVMe controller to delete namespace from.
nsidThe namespace identifier.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request

◆ spdk_nvme_ctrlr_detach_ns()

int spdk_nvme_ctrlr_detach_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
struct spdk_nvme_ctrlr_list payload 
)

Detach the specified namespace from controllers.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrNVMe controller to use for command submission.
nsidNamespace ID to detach.
payloadThe pointer to the controller list.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request

◆ spdk_nvme_ctrlr_format()

int spdk_nvme_ctrlr_format ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
struct spdk_nvme_format format 
)

Format NVM.

This function requests a low-level format of the media.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Parameters
ctrlrNVMe controller to format.
nsidThe namespace identifier. May be SPDK_NVME_GLOBAL_NS_TAG to format all namespaces.
formatThe format information for the command.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request

◆ spdk_nvme_ctrlr_free_cmb_io_buffer()

void spdk_nvme_ctrlr_free_cmb_io_buffer ( struct spdk_nvme_ctrlr *  ctrlr,
void *  buf,
size_t  size 
)

Free a controller memory I/O buffer (Experimental).

Note this function is currently a NOP which is one reason why this and spdk_nvme_ctrlr_alloc_cmb_io_buffer() are currently marked as experimental.

Parameters
ctrlrController from which the buffer was allocated.
bufBuffer previously allocated by spdk_nvme_ctrlr_alloc_cmb_io_buffer().
sizeSize of buf in bytes.

◆ spdk_nvme_ctrlr_free_io_qpair()

int spdk_nvme_ctrlr_free_io_qpair ( struct spdk_nvme_qpair *  qpair)

Free an I/O queue pair that was allocated by spdk_nvme_ctrlr_alloc_io_qpair().

Parameters
qpairI/O queue pair to free.
Returns
0 on success, -1 on failure.

◆ spdk_nvme_ctrlr_get_data()

const struct spdk_nvme_ctrlr_data* spdk_nvme_ctrlr_get_data ( struct spdk_nvme_ctrlr *  ctrlr)

Get the identify controller data as defined by the NVMe specification.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
pointer to the identify controller data.

◆ spdk_nvme_ctrlr_get_default_ctrlr_opts()

void spdk_nvme_ctrlr_get_default_ctrlr_opts ( struct spdk_nvme_ctrlr_opts opts,
size_t  opts_size 
)

Get the default options for the creation of a specific NVMe controller.

Parameters
[out]optsWill be filled with the default option.
opts_sizeMust be set to sizeof(struct spdk_nvme_ctrlr_opts).

◆ spdk_nvme_ctrlr_get_default_io_qpair_opts()

void spdk_nvme_ctrlr_get_default_io_qpair_opts ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_io_qpair_opts opts,
size_t  opts_size 
)

Get the default options for I/O qpair creation for a specific NVMe controller.

Parameters
ctrlrNVMe controller to retrieve the defaults from.
[out]optsWill be filled with the default options for spdk_nvme_ctrlr_alloc_io_qpair().
opts_sizeMust be set to sizeof(struct spdk_nvme_io_qpair_opts).

◆ spdk_nvme_ctrlr_get_first_active_ns()

uint32_t spdk_nvme_ctrlr_get_first_active_ns ( struct spdk_nvme_ctrlr *  ctrlr)

Get the nsid of the first active namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the nsid of the first active namespace, 0 if there are no active namespaces.

◆ spdk_nvme_ctrlr_get_flags()

uint64_t spdk_nvme_ctrlr_get_flags ( struct spdk_nvme_ctrlr *  ctrlr)

Get supported flags of the controller.

Parameters
ctrlrNVMe controller to get flags.
Returns
supported flags of this controller.

◆ spdk_nvme_ctrlr_get_max_xfer_size()

uint32_t spdk_nvme_ctrlr_get_max_xfer_size ( const struct spdk_nvme_ctrlr *  ctrlr)

Get the maximum data transfer size of a given NVMe controller.

Returns
Maximum data transfer size of the NVMe controller in bytes.

The I/O command helper functions, such as spdk_nvme_ns_cmd_read(), will split large I/Os automatically; however, it is up to the user to obey this limit for commands submitted with the raw command functions, such as spdk_nvme_ctrlr_cmd_io_raw().

◆ spdk_nvme_ctrlr_get_next_active_ns()

uint32_t spdk_nvme_ctrlr_get_next_active_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  prev_nsid 
)

Get next active namespace given the previous nsid.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
prev_nsidNamespace id.
Returns
a next active namespace given the previous nsid, 0 when there are no more active namespaces.

◆ spdk_nvme_ctrlr_get_ns()

struct spdk_nvme_ns* spdk_nvme_ctrlr_get_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  ns_id 
)

Get a handle to a namespace for the given controller.

Namespaces are numbered from 1 to the total number of namespaces. There will never be any gaps in the numbering. The number of namespaces is obtained by calling spdk_nvme_ctrlr_get_num_ns().

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
ns_idNamespace id.
Returns
a pointer to the namespace.

◆ spdk_nvme_ctrlr_get_num_ns()

uint32_t spdk_nvme_ctrlr_get_num_ns ( struct spdk_nvme_ctrlr *  ctrlr)

Get the number of namespaces for the given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

This is equivalent to calling spdk_nvme_ctrlr_get_data() to get the spdk_nvme_ctrlr_data and then reading the nn field.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the number of namespaces.

◆ spdk_nvme_ctrlr_get_pci_device()

struct spdk_pci_device* spdk_nvme_ctrlr_get_pci_device ( struct spdk_nvme_ctrlr *  ctrlr)

Get the PCI device of a given NVMe controller.

This only works for local (PCIe-attached) NVMe controllers; other transports will return NULL.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
PCI device of the NVMe controller, or NULL if not available.

◆ spdk_nvme_ctrlr_get_registers()

volatile struct spdk_nvme_registers* spdk_nvme_ctrlr_get_registers ( struct spdk_nvme_ctrlr *  ctrlr)

Return virtual address of PCIe NVM I/O registers.

This function returns a pointer to the PCIe I/O registers for a controller or NULL if unsupported for this transport.

Parameters
ctrlrController whose registers are to be accessed.
Returns
Pointer to virtual address of register bank, or NULL.

◆ spdk_nvme_ctrlr_get_regs_cap()

union spdk_nvme_cap_register spdk_nvme_ctrlr_get_regs_cap ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller CAP (Capabilities) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller CAP (Capabilities) register.

◆ spdk_nvme_ctrlr_get_regs_cmbsz()

union spdk_nvme_cmbsz_register spdk_nvme_ctrlr_get_regs_cmbsz ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller CMBSZ (Controller Memory Buffer Size) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller CMBSZ (Controller Memory Buffer Size) register.

◆ spdk_nvme_ctrlr_get_regs_csts()

union spdk_nvme_csts_register spdk_nvme_ctrlr_get_regs_csts ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller CSTS (Status) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller CSTS (Status) register.

◆ spdk_nvme_ctrlr_get_regs_vs()

union spdk_nvme_vs_register spdk_nvme_ctrlr_get_regs_vs ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller VS (Version) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller VS (Version) register.

◆ spdk_nvme_ctrlr_get_transport_id()

const struct spdk_nvme_transport_id* spdk_nvme_ctrlr_get_transport_id ( struct spdk_nvme_ctrlr *  ctrlr)

Get the transport ID for a given NVMe controller.

Parameters
ctrlrController to get the transport ID.
Returns
Pointer to the controller's transport ID.

◆ spdk_nvme_ctrlr_io_cmd_raw_no_payload_build()

int spdk_nvme_ctrlr_io_cmd_raw_no_payload_build ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cmd cmd,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send the given NVM I/O command, I/O buffers, lists and all to the NVMe controller.

This is a low level interface for submitting I/O commands directly.

This function allows a caller to submit an I/O request that is COMPLETELY pre-defined, right down to the "physical" memory buffers. It is intended for testing hardware, specifying exact buffer location, alignment, and offset. It also allows for specific choice of PRP and SGLs.

The driver sets the CID. EVERYTHING else is assumed set by the caller. Needless to say, this is potentially extremely dangerous for both the host (accidental/malicionus storage usage/corruption), and the device. Thus its intent is for very specific hardware testing and environment reproduction.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

This function can only be used on PCIe controllers and qpairs.

Parameters
ctrlrOpaque handle to NVMe controller.
qpairI/O qpair to submit command.
cmdNVM I/O command to submit.
cb_fnCallback function invoked when the I/O command completes.
cb_argArgument passed to callback function.
Returns
0 on success, negated errno on failure.

◆ spdk_nvme_ctrlr_is_active_ns()

bool spdk_nvme_ctrlr_is_active_ns ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid 
)

Check whether the nsid is an active nv for the given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
nsidNamespace id.
Returns
true if nsid is an active ns, or false otherwise.

◆ spdk_nvme_ctrlr_is_discovery()

bool spdk_nvme_ctrlr_is_discovery ( struct spdk_nvme_ctrlr *  ctrlr)

Indicate whether a ctrlr handle is associated with a Discovery controller.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
true if a discovery controller, else false.

◆ spdk_nvme_ctrlr_is_feature_supported()

bool spdk_nvme_ctrlr_is_feature_supported ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  feature_code 
)

Determine if a particular feature is supported by the given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

See also
spdk_nvme_ctrlr_cmd_get_feature().
Parameters
ctrlrOpaque handle to NVMe controller.
feature_codeFeature to query.
Returns
true if supported, or false otherwise.

◆ spdk_nvme_ctrlr_is_log_page_supported()

bool spdk_nvme_ctrlr_is_log_page_supported ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  log_page 
)

Determine if a particular log page is supported by the given NVMe controller.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

See also
spdk_nvme_ctrlr_cmd_get_log_page().
Parameters
ctrlrOpaque handle to NVMe controller.
log_pageLog page to query.
Returns
true if supported, or false otherwise.

◆ spdk_nvme_ctrlr_process_admin_completions()

int32_t spdk_nvme_ctrlr_process_admin_completions ( struct spdk_nvme_ctrlr *  ctrlr)

Process any outstanding completions for admin commands.

This will process completions for admin commands submitted on any thread.

This call is non-blocking, i.e. it only processes completions that are ready at the time of this function call. It does not wait for outstanding commands to finish.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
number of completions processed (may be 0) or negated on error.

◆ spdk_nvme_ctrlr_register_aer_callback()

void spdk_nvme_ctrlr_register_aer_callback ( struct spdk_nvme_ctrlr *  ctrlr,
spdk_nvme_aer_cb  aer_cb_fn,
void *  aer_cb_arg 
)

Register callback function invoked when an AER command is completed for the given NVMe controller.

Parameters
ctrlrOpaque handle to NVMe controller.
aer_cb_fnCallback function invoked when an asynchronous error request command is completed.
aer_cb_argArgument passed to callback function.

◆ spdk_nvme_ctrlr_register_timeout_callback()

void spdk_nvme_ctrlr_register_timeout_callback ( struct spdk_nvme_ctrlr *  ctrlr,
uint64_t  timeout_us,
spdk_nvme_timeout_cb  cb_fn,
void *  cb_arg 
)

Register for timeout callback on a controller.

The application can choose to register for timeout callback or not register for timeout callback.

Parameters
ctrlrNVMe controller on which to monitor for timeout.
timeout_usTimeout value in microseconds.
cb_fnA function pointer that points to the callback function.
cb_argArgument to the callback function.

◆ spdk_nvme_ctrlr_reset()

int spdk_nvme_ctrlr_reset ( struct spdk_nvme_ctrlr *  ctrlr)

Perform a full hardware reset of the NVMe controller.

This function should be called from a single thread while no other threads are actively using the NVMe device.

Any pointers returned from spdk_nvme_ctrlr_get_ns() and spdk_nvme_ns_get_data() may be invalidated by calling this function. The number of namespaces as returned by spdk_nvme_ctrlr_get_num_ns() may also change.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
0 on success, -1 on failure.

◆ spdk_nvme_ctrlr_security_receive()

int spdk_nvme_ctrlr_security_receive ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  secp,
uint16_t  spsp,
uint8_t  nssf,
void *  payload,
size_t  size 
)

Receive security protocol data from controller.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrNVMe controller to use for security receive command submission.
secpSecurity Protocol that is used.
spspSecurity Protocol Specific field.
nssfNVMe Security Specific field. Indicate RPMB target when using Security Protocol EAh.
payloadThe pointer to the payload buffer.
sizeThe size of payload buffer.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_security_send()

int spdk_nvme_ctrlr_security_send ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  secp,
uint16_t  spsp,
uint8_t  nssf,
void *  payload,
size_t  size 
)

Send security protocol data to controller.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Call spdk_nvme_ctrlr_process_admin_completions() to poll for completion of commands submitted through this function.

Parameters
ctrlrNVMe controller to use for security send command submission.
secpSecurity Protocol that is used.
spspSecurity Protocol Specific field.
nssfNVMe Security Specific field. Indicate RPMB target when using Security Protocol EAh.
payloadThe pointer to the payload buffer.
sizeThe size of payload buffer.
Returns
0 if successfully submitted, negated errno if resources could not be allocated for this request.

◆ spdk_nvme_ctrlr_update_firmware()

int spdk_nvme_ctrlr_update_firmware ( struct spdk_nvme_ctrlr *  ctrlr,
void *  payload,
uint32_t  size,
int  slot,
enum spdk_nvme_fw_commit_action  commit_action,
struct spdk_nvme_status completion_status 
)

Download a new firmware image.

This function is thread safe and can be called at any point after spdk_nvme_probe().

Parameters
ctrlrNVMe controller to perform firmware operation on.
payloadThe data buffer for the firmware image.
sizeThe data size will be downloaded.
slotThe slot that the firmware image will be committed to.
commit_actionThe action to perform when firmware is committed.
completion_statusoutput parameter. Contains the completion status of the firmware commit operation.
Returns
0 if successfully submitted, ENOMEM if resources could not be allocated for this request, -1 if the size is not multiple of 4.

◆ spdk_nvme_detach()

int spdk_nvme_detach ( struct spdk_nvme_ctrlr *  ctrlr)

Detach specified device returned by spdk_nvme_probe()'s attach_cb from the NVMe driver.

On success, the spdk_nvme_ctrlr handle is no longer valid.

This function should be called from a single thread while no other threads are actively using the NVMe device.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
0 on success, -1 on failure.

◆ spdk_nvme_host_id_parse()

int spdk_nvme_host_id_parse ( struct spdk_nvme_host_id hostid,
const char *  str 
)

Parse the string representation of a host ID.

Parameters
hostidOutput host ID structure (must be allocated and initialized by caller).
strInput string representation of a transport ID to parse (hostid is a sub-configuration).

str must be a zero-terminated C string containing one or more key:value pairs separated by whitespace.

Key Value
hostaddr Transport address (e.g. 192.168.100.8 for RDMA)
hostsvcid Transport service identifier (e.g. 4420)

Unspecified fields of trid are left unmodified, so the caller must initialize hostid (for example, memset() to 0) before calling this function.

This function should not be used with Fiber Channel or PCIe as these transports do not require host information for connections.

Returns
0 if parsing was successful and hostid is filled out, or negated errno values on failure.

◆ spdk_nvme_ns_cmd_compare()

int spdk_nvme_ns_cmd_compare ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags 
)

Submit a compare I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the compare I/O.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the data payload.
lbaStarting LBA to compare the data.
lba_countLength (in sectors) for the compare operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_compare_with_md()

int spdk_nvme_ns_cmd_compare_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
void *  metadata,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a compare I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the compare I/O.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the data payload.
metadataVirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size().
lbaStarting LBA to compare the data.
lba_countLength (in sectors) for the compare operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
apptag_maskApplication tag mask.
apptagApplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_comparev()

int spdk_nvme_ns_cmd_comparev ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn 
)

Submit a compare I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the compare I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA to compare the data.
lba_countLength (in sectors) for the compare operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
reset_sgl_fnCallback function to reset scattered payload.
next_sge_fnCallback function to iterate each scattered payload memory segment.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_dataset_management()

int spdk_nvme_ns_cmd_dataset_management ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint32_t  type,
const struct spdk_nvme_dsm_range ranges,
uint16_t  num_ranges,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a data set management request to the specified NVMe namespace.

Data set management operations are designed to optimize interaction with the block translation layer inside the device. The most common type of operation is deallocate, which is often referred to as TRIM or UNMAP.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

This is a convenience wrapper that will automatically allocate and construct the correct data buffers. Therefore, ranges does not need to be allocated from pinned memory and can be placed on the stack. If a higher performance, zero-copy version of DSM is required, simply build and submit a raw command using spdk_nvme_ctrlr_cmd_io_raw().

Parameters
nsNVMe namespace to submit the DSM request
typeA bit field constructed from spdk_nvme_dsm_attribute.
qpairI/O queue pair to submit the request
rangesAn array of spdk_nvme_dsm_range elements describing the LBAs to operate on.
num_rangesThe number of elements in the ranges array.
cb_fnCallback function to invoke when the I/O is completed
cb_argArgument to pass to the callback function
Returns
0 if successfully submitted, negated POSIX errno values otherwise.

◆ spdk_nvme_ns_cmd_flush()

int spdk_nvme_ns_cmd_flush ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a flush request to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the flush request.
qpairI/O queue pair to submit the request.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_read()

int spdk_nvme_ns_cmd_read ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags 
)

Submits a read I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the read I/O.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the data payload.
lbaStarting LBA to read the data.
lba_countLength (in sectors) for the read operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_read_with_md()

int spdk_nvme_ns_cmd_read_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
void *  metadata,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submits a read I/O to the specified NVMe namespace.

Parameters
nsNVMe namespace to submit the read I/O
qpairI/O queue pair to submit the request
payloadvirtual address pointer to the data payload
metadatavirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size().
lbastarting LBA to read the data.
lba_countLength (in sectors) for the read operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
apptag_maskApplication tag mask.
apptagApplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_readv()

int spdk_nvme_ns_cmd_readv ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn 
)

Submit a read I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the read I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA to read the data.
lba_countLength (in sectors) for the read operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
reset_sgl_fnCallback function to reset scattered payload.
next_sge_fnCallback function to iterate each scattered payload memory segment.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_readv_with_md()

int spdk_nvme_ns_cmd_readv_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn,
void *  metadata,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a read I/O to the specified NVMe namespace.

Parameters
nsNVMe namespace to submit the read I/O
qpairI/O queue pair to submit the request
lbastarting LBA to read the data
lba_countlength (in sectors) for the read operation
cb_fncallback function to invoke when the I/O is completed
cb_argargument to pass to the callback function
io_flagsset flags, defined in nvme_spec.h, for this I/O
reset_sgl_fncallback function to reset scattered payload
next_sge_fncallback function to iterate each scattered payload memory segment
metadatavirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size()
apptag_maskapplication tag mask.
apptagapplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, ENOMEM if an nvme_request structure cannot be allocated for the I/O request

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

◆ spdk_nvme_ns_cmd_reservation_acquire()

int spdk_nvme_ns_cmd_reservation_acquire ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_reservation_acquire_data payload,
bool  ignore_key,
enum spdk_nvme_reservation_acquire_action  action,
enum spdk_nvme_reservation_type  type,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submits a reservation acquire to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the reservation acquire request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to reservation acquire data.
ignore_key'1' the current reservation key check is disabled.
actionSpecifies the reservation acquire action.
typeReservation type for the namespace.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_reservation_register()

int spdk_nvme_ns_cmd_reservation_register ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_reservation_register_data payload,
bool  ignore_key,
enum spdk_nvme_reservation_register_action  action,
enum spdk_nvme_reservation_register_cptpl  cptpl,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a reservation register to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the reservation register request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the reservation register data.
ignore_key'1' the current reservation key check is disabled.
actionSpecifies the registration action.
cptplChange the Persist Through Power Loss state.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_reservation_release()

int spdk_nvme_ns_cmd_reservation_release ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_reservation_key_data payload,
bool  ignore_key,
enum spdk_nvme_reservation_release_action  action,
enum spdk_nvme_reservation_type  type,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submits a reservation release to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the reservation release request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to current reservation key.
ignore_key'1' the current reservation key check is disabled.
actionSpecifies the reservation release action.
typeReservation type for the namespace.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_reservation_report()

int spdk_nvme_ns_cmd_reservation_report ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint32_t  len,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a reservation report to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the reservation report request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer for reservation status data.
lenLength bytes for reservation status data structure.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_write()

int spdk_nvme_ns_cmd_write ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags 
)

Submit a write I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the write I/O.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the data payload.
lbaStarting LBA to write the data.
lba_countLength (in sectors) for the write operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined by the SPDK_NVME_IO_FLAGS_* entries in spdk/nvme_spec.h, for this I/O.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request

◆ spdk_nvme_ns_cmd_write_with_md()

int spdk_nvme_ns_cmd_write_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
void *  metadata,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a write I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the write I/O.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer to the data payload.
metadataVirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size().
lbaStarting LBA to write the data.
lba_countLength (in sectors) for the write operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined by the SPDK_NVME_IO_FLAGS_* entries in spdk/nvme_spec.h, for this I/O.
apptag_maskApplication tag mask.
apptagApplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_write_zeroes()

int spdk_nvme_ns_cmd_write_zeroes ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags 
)

Submit a write zeroes I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the write zeroes I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA for this command.
lba_countLength (in sectors) for the write zero operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined by the SPDK_NVME_IO_FLAGS_* entries in spdk/nvme_spec.h, for this I/O.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_writev()

int spdk_nvme_ns_cmd_writev ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn 
)

Submit a write I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the write I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA to write the data.
lba_countLength (in sectors) for the write operation.
cb_fnCallback function to invoke when the I/O is completed.
cb_argArgument to pass to the callback function.
io_flagsSet flags, defined in nvme_spec.h, for this I/O.
reset_sgl_fnCallback function to reset scattered payload.
next_sge_fnCallback function to iterate each scattered payload memory segment.
Returns
0 if successfully submitted, negated errno if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_cmd_writev_with_md()

int spdk_nvme_ns_cmd_writev_with_md ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
uint64_t  lba,
uint32_t  lba_count,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
uint32_t  io_flags,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn,
void *  metadata,
uint16_t  apptag_mask,
uint16_t  apptag 
)

Submit a write I/O to the specified NVMe namespace.

The command is submitted to a qpair allocated by spdk_nvme_ctrlr_alloc_io_qpair(). The user must ensure that only one thread submits I/O on a given qpair at any given time.

Parameters
nsNVMe namespace to submit the write I/O
qpairI/O queue pair to submit the request
lbastarting LBA to write the data
lba_countlength (in sectors) for the write operation
cb_fncallback function to invoke when the I/O is completed
cb_argargument to pass to the callback function
io_flagsset flags, defined in nvme_spec.h, for this I/O
reset_sgl_fncallback function to reset scattered payload
next_sge_fncallback function to iterate each scattered payload memory segment
metadatavirtual address pointer to the metadata payload, the length of metadata is specified by spdk_nvme_ns_get_md_size()
apptag_maskapplication tag mask.
apptagapplication tag to use end-to-end protection information.
Returns
0 if successfully submitted, ENOMEM if an nvme_request structure cannot be allocated for the I/O request.

◆ spdk_nvme_ns_get_ctrlr()

struct spdk_nvme_ctrlr* spdk_nvme_ns_get_ctrlr ( struct spdk_nvme_ns *  ns)

Get the controller with which this namespace is associated.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace.
Returns
a pointer to the controller.

◆ spdk_nvme_ns_get_data()

const struct spdk_nvme_ns_data* spdk_nvme_ns_get_data ( struct spdk_nvme_ns *  ns)

Get the identify namespace data as defined by the NVMe specification.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace.
Returns
a pointer to the namespace data.

◆ spdk_nvme_ns_get_dealloc_logical_block_read_value()

enum spdk_nvme_dealloc_logical_block_read_value spdk_nvme_ns_get_dealloc_logical_block_read_value ( struct spdk_nvme_ns *  ns)

Determine the value returned when reading deallocated blocks.

If deallocated blocks return 0, the deallocate command can be used as a more efficient alternative to the write_zeroes command, especially for large requests.

Parameters
nsNamespace.
Returns
the logical block read value.

◆ spdk_nvme_ns_get_extended_sector_size()

uint32_t spdk_nvme_ns_get_extended_sector_size ( struct spdk_nvme_ns *  ns)

Get the extended sector size, in bytes, of the given namespace.

This function returns the size of the data sector plus metadata.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.

/return the extended sector size in bytes.

◆ spdk_nvme_ns_get_flags()

uint32_t spdk_nvme_ns_get_flags ( struct spdk_nvme_ns *  ns)

Get the flags for the given namespace.

See spdk_nvme_ns_flags for the possible flags returned.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the flags for the given namespace.

◆ spdk_nvme_ns_get_id()

uint32_t spdk_nvme_ns_get_id ( struct spdk_nvme_ns *  ns)

Get the namespace id (index number) from the given namespace handle.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace.
Returns
namespace id.

◆ spdk_nvme_ns_get_max_io_xfer_size()

uint32_t spdk_nvme_ns_get_max_io_xfer_size ( struct spdk_nvme_ns *  ns)

Get the maximum transfer size, in bytes, for an I/O sent to the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the maximum transfer size in bytes.

◆ spdk_nvme_ns_get_md_size()

uint32_t spdk_nvme_ns_get_md_size ( struct spdk_nvme_ns *  ns)

Get the metadata size, in bytes, of the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the metadata size of the given namespace in bytes.

◆ spdk_nvme_ns_get_num_sectors()

uint64_t spdk_nvme_ns_get_num_sectors ( struct spdk_nvme_ns *  ns)

Get the number of sectors for the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the number of sectors.

◆ spdk_nvme_ns_get_optimal_io_boundary()

uint32_t spdk_nvme_ns_get_optimal_io_boundary ( struct spdk_nvme_ns *  ns)

Get the optimal I/O boundary, in blocks, for the given namespace.

Read and write commands should not cross the optimal I/O boundary for best performance.

Parameters
nsNamespace to query.
Returns
Optimal granularity of I/O commands, in blocks, or 0 if no optimal granularity is reported.

◆ spdk_nvme_ns_get_pi_type()

enum spdk_nvme_pi_type spdk_nvme_ns_get_pi_type ( struct spdk_nvme_ns *  ns)

Get the end-to-end data protection information type of the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the end-to-end data protection information type.

◆ spdk_nvme_ns_get_sector_size()

uint32_t spdk_nvme_ns_get_sector_size ( struct spdk_nvme_ns *  ns)

Get the sector size, in bytes, of the given namespace.

This function returns the size of the data sector only. It does not include metadata size.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.

/return the sector size in bytes.

◆ spdk_nvme_ns_get_size()

uint64_t spdk_nvme_ns_get_size ( struct spdk_nvme_ns *  ns)

Get the size, in bytes, of the given namespace.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
the size of the given namespace in bytes.

◆ spdk_nvme_ns_get_uuid()

const struct spdk_uuid* spdk_nvme_ns_get_uuid ( const struct spdk_nvme_ns *  ns)

Get the UUID for the given namespace.

Parameters
nsNamespace to query.
Returns
a pointer to namespace UUID, or NULL if ns does not have a UUID.

◆ spdk_nvme_ns_is_active()

bool spdk_nvme_ns_is_active ( struct spdk_nvme_ns *  ns)

Determine whether a namespace is active.

Inactive namespaces cannot be the target of I/O commands.

Parameters
nsNamespace to query.
Returns
true if active, or false if inactive.

◆ spdk_nvme_ns_supports_extended_lba()

bool spdk_nvme_ns_supports_extended_lba ( struct spdk_nvme_ns *  ns)

Check whether if the namespace can support extended LBA when end-to-end data protection enabled.

This function is thread safe and can be called at any point while the controller is attached to the SPDK NVMe driver.

Parameters
nsNamespace to query.
Returns
true if the namespace can support extended LBA when end-to-end data protection enabled, or false otherwise.

◆ spdk_nvme_prchk_flags_parse()

int spdk_nvme_prchk_flags_parse ( uint32_t *  prchk_flags,
const char *  str 
)

Parse the string representation of PI check settings (prchk:guard|reftag)

Parameters
prchk_flagsOutput PI check flags.
strInput string representation of PI check settings.
Returns
0 if parsing was successful and prchk_flags is set, or negated errno values on failure.

◆ spdk_nvme_prchk_flags_str()

const char* spdk_nvme_prchk_flags_str ( uint32_t  prchk_flags)

Look up the string representation of PI check settings (prchk:guard|reftag)

Parameters
prchk_flagsPI check flags to convert.
Returns
static string constant describing PI check settings. If prchk_flags is 0, NULL is returned.

◆ spdk_nvme_probe()

int spdk_nvme_probe ( const struct spdk_nvme_transport_id trid,
void *  cb_ctx,
spdk_nvme_probe_cb  probe_cb,
spdk_nvme_attach_cb  attach_cb,
spdk_nvme_remove_cb  remove_cb 
)

Enumerate the bus indicated by the transport ID and attach the userspace NVMe driver to each device found if desired.

This function is not thread safe and should only be called from one thread at a time while no other threads are actively using any NVMe devices.

If called from a secondary process, only devices that have been attached to the userspace driver in the primary process will be probed.

If called more than once, only devices that are not already attached to the SPDK NVMe driver will be reported.

To stop using the the controller and release its associated resources, call spdk_nvme_detach() with the spdk_nvme_ctrlr instance from the attach_cb() function.

Parameters
tridThe transport ID indicating which bus to enumerate. If the trtype is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is RDMA, the traddr and trsvcid must point at the location of an NVMe-oF discovery service.
cb_ctxOpaque value which will be passed back in cb_ctx parameter of the callbacks.
probe_cbwill be called once per NVMe device found in the system.
attach_cbwill be called for devices for which probe_cb returned true once that NVMe controller has been attached to the userspace driver.
remove_cbwill be called for devices that were attached in a previous spdk_nvme_probe() call but are no longer attached to the system. Optional; specify NULL if removal notices are not desired.
Returns
0 on success, -1 on failure.

◆ spdk_nvme_probe_async()

struct spdk_nvme_probe_ctx* spdk_nvme_probe_async ( const struct spdk_nvme_transport_id trid,
void *  cb_ctx,
spdk_nvme_probe_cb  probe_cb,
spdk_nvme_attach_cb  attach_cb,
spdk_nvme_remove_cb  remove_cb 
)

Probe and add controllers to the probe context list.

Users must call spdk_nvme_probe_poll_async() to initialize controllers in the probe context list to the READY state.

Parameters
tridThe transport ID indicating which bus to enumerate. If the trtype is PCIe or trid is NULL, this will scan the local PCIe bus. If the trtype is RDMA, the traddr and trsvcid must point at the location of an NVMe-oF discovery service.
cb_ctxOpaque value which will be passed back in cb_ctx parameter of the callbacks.
probe_cbwill be called once per NVMe device found in the system.
attach_cbwill be called for devices for which probe_cb returned true once that NVMe controller has been attached to the userspace driver.
remove_cbwill be called for devices that were attached in a previous spdk_nvme_probe() call but are no longer attached to the system. Optional; specify NULL if removal notices are not desired.
Returns
probe context on success, NULL on failure.

◆ spdk_nvme_probe_poll_async()

int spdk_nvme_probe_poll_async ( struct spdk_nvme_probe_ctx *  probe_ctx)

Start controllers in the context list.

Users may call the function util it returns True.

Parameters
probe_ctxContext used to track probe actions.
Returns
0 if all probe operations are complete; the probe_ctx is also freed and no longer valid.
-EAGAIN if there are still pending probe operations; user must call spdk_nvme_probe_poll_async again to continue progress.
value other than 0 and -EAGAIN probe error with one controller.

◆ spdk_nvme_qpair_add_cmd_error_injection()

int spdk_nvme_qpair_add_cmd_error_injection ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
uint8_t  opc,
bool  do_not_submit,
uint64_t  timeout_in_us,
uint32_t  err_count,
uint8_t  sct,
uint8_t  sc 
)

Inject an error for the next request with a given opcode.

Parameters
ctrlrNVMe controller.
qpairI/O queue pair to add the error command, NULL for Admin queue pair.
opcOpcode for Admin or I/O commands.
do_not_submitTrue if matching requests should not be submitted to the controller, but instead completed manually after timeout_in_us has expired. False if matching requests should be submitted to the controller and have their completion status modified after the controller completes the request.
timeout_in_usWait specified microseconds when do_not_submit is true.
err_countNumber of matching requests to inject errors.
sctStatus code type.
scStatus code.
Returns
0 if successfully enabled, ENOMEM if an error command structure cannot be allocated.

The function can be called multiple times to inject errors for different commands. If the opcode matches an existing entry, the existing entry will be updated with the values specified.

◆ spdk_nvme_qpair_process_completions()

int32_t spdk_nvme_qpair_process_completions ( struct spdk_nvme_qpair *  qpair,
uint32_t  max_completions 
)

Process any outstanding completions for I/O submitted on a queue pair.

This call is non-blocking, i.e. it only processes completions that are ready at the time of this function call. It does not wait for outstanding commands to finish.

For each completed command, the request's callback function will be called if specified as non-NULL when the request was submitted.

The caller must ensure that each queue pair is only used from one thread at a time.

This function may be called at any point while the controller is attached to the SPDK NVMe driver.

See also
spdk_nvme_cmd_cb
Parameters
qpairQueue pair to check for completions.
max_completionsLimit the number of completions to be processed in one call, or 0 for unlimited.
Returns
number of completions processed (may be 0) or negated on error.

◆ spdk_nvme_qpair_remove_cmd_error_injection()

void spdk_nvme_qpair_remove_cmd_error_injection ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
uint8_t  opc 
)

Clear the specified NVMe command with error status.

Parameters
ctrlrNVMe controller.
qpairI/O queue pair to remove the error command, \ NULL for Admin queue pair.
opcOpcode for Admin or I/O commands.

The function will remove specified command in the error list.

◆ spdk_nvme_transport_available()

bool spdk_nvme_transport_available ( enum spdk_nvme_transport_type  trtype)

Determine whether the NVMe library can handle a specific NVMe over Fabrics transport type.

Parameters
trtypeNVMe over Fabrics transport type to check.
Returns
true if trtype is supported or false if it is not supported.

◆ spdk_nvme_transport_id_adrfam_str()

const char* spdk_nvme_transport_id_adrfam_str ( enum spdk_nvmf_adrfam  adrfam)

Look up the string representation of a transport ID address family.

Parameters
adrfamAddress family to convert.
Returns
static string constant describing adrfam, or NULL if adrmfam not found.

◆ spdk_nvme_transport_id_compare()

int spdk_nvme_transport_id_compare ( const struct spdk_nvme_transport_id trid1,
const struct spdk_nvme_transport_id trid2 
)

Compare two transport IDs.

The result of this function may be used to sort transport IDs in a consistent order; however, the comparison result is not guaranteed to be consistent across library versions.

This function uses a case-insensitive comparison for string fields, but it does not otherwise normalize the transport ID. It is the caller's responsibility to provide the transport IDs in a consistent format.

Parameters
trid1First transport ID to compare.
trid2Second transport ID to compare.
Returns
0 if trid1 == trid2, less than 0 if trid1 < trid2, greater than 0 if trid1 > trid2.

◆ spdk_nvme_transport_id_parse()

int spdk_nvme_transport_id_parse ( struct spdk_nvme_transport_id trid,
const char *  str 
)

Parse the string representation of a transport ID.

Parameters
tridOutput transport ID structure (must be allocated and initialized by caller).
strInput string representation of a transport ID to parse.

str must be a zero-terminated C string containing one or more key:value pairs separated by whitespace.

Key Value
trtype Transport type (e.g. PCIe, RDMA)
adrfam Address family (e.g. IPv4, IPv6)
traddr Transport address (e.g. 0000:04:00.0 for PCIe, 192.168.100.8 for RDMA, or WWN for FC)
trsvcid Transport service identifier (e.g. 4420)
subnqn Subsystem NQN

Unspecified fields of trid are left unmodified, so the caller must initialize trid (for example, memset() to 0) before calling this function.

Returns
0 if parsing was successful and trid is filled out, or negated errno values on failure.

◆ spdk_nvme_transport_id_parse_adrfam()

int spdk_nvme_transport_id_parse_adrfam ( enum spdk_nvmf_adrfam adrfam,
const char *  str 
)

Parse the string representation of a tranport ID address family.

Parameters
adrfamOutput address family (allocated by caller).
strInput string representation of address family (e.g. "IPv4", "IPv6").
Returns
0 if parsing was successful and adrfam is filled out, or negated errno values on failure.

◆ spdk_nvme_transport_id_parse_trtype()

int spdk_nvme_transport_id_parse_trtype ( enum spdk_nvme_transport_type trtype,
const char *  str 
)

Parse the string representation of a transport ID tranport type.

Parameters
trtypeOutput transport type (allocated by caller).
strInput string representation of transport type (e.g. "PCIe", "RDMA").
Returns
0 if parsing was successful and trtype is filled out, or negated errno values on failure.

◆ spdk_nvme_transport_id_trtype_str()

const char* spdk_nvme_transport_id_trtype_str ( enum spdk_nvme_transport_type  trtype)

Look up the string representation of a transport ID transport type.

Parameters
trtypeTransport type to convert.
Returns
static string constant describing trtype, or NULL if trtype not found.