nvme.h File Reference

NVMe driver public API. More...

Data Structures

struct  spdk_nvme_ctrlr_opts
 NVMe controller initialization options. More...
 
struct  spdk_nvme_accel_fn_table
 Function table for the NVMe accelerator device. More...
 
struct  spdk_nvme_transport_id
 NVMe transport identifier. More...
 
struct  spdk_nvme_host_id
 NVMe host identifier. More...
 
struct  spdk_nvme_rdma_device_stat
 
struct  spdk_nvme_pcie_stat
 
struct  spdk_nvme_tcp_stat
 
struct  spdk_nvme_transport_poll_group_stat
 
struct  spdk_nvme_poll_group_stat
 
struct  spdk_nvme_ns_cmd_ext_io_opts
 Structure with optional IO request parameters. More...
 
struct  spdk_nvme_io_qpair_opts
 NVMe I/O queue pair initialization options. More...
 
struct  spdk_nvme_rdma_hooks
 RDMA Transport Hooks. More...
 
struct  spdk_nvme_transport_ops
 
struct  spdk_nvme_transport_opts
 NVMe transport options. More...
 

Macros

#define SPDK_NVME_TRANSPORT_NAME_FC   "FC"
 
#define SPDK_NVME_TRANSPORT_NAME_PCIE   "PCIE"
 
#define SPDK_NVME_TRANSPORT_NAME_RDMA   "RDMA"
 
#define SPDK_NVME_TRANSPORT_NAME_TCP   "TCP"
 
#define SPDK_NVME_TRANSPORT_NAME_VFIOUSER   "VFIOUSER"
 
#define SPDK_NVME_TRANSPORT_NAME_CUSTOM   "CUSTOM"
 
#define SPDK_NVMF_PRIORITY_MAX_LEN   4
 
#define SPDK_NVME_TRANSPORT_REGISTER(name, transport_ops)
 

Typedefs

typedef void(* spdk_nvme_accel_completion_cb) (void *cb_arg, int status)
 NVMe acceleration operation callback. More...
 
typedef void(* spdk_nvme_accel_step_cb) (void *cb_arg)
 Completion callback for a single operation in a sequence. More...
 
typedef enum spdk_nvme_qp_failure_reason spdk_nvme_qp_failure_reason
 
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 bool(* spdk_nvme_pcie_hotplug_filter_cb) (const struct spdk_pci_addr *addr)
 
typedef void(* spdk_nvme_cmd_cb) (void *ctx, const struct spdk_nvme_cpl *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 *cpl)
 Signature for callback function invoked when an asynchronous event 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_discovery_cb) (void *cb_arg, int rc, const struct spdk_nvme_cpl *cpl, struct spdk_nvmf_discovery_log_page *log_page)
 Signature for the callback function when a spdk_nvme_ctrlr_get_discovery_log_page operation is completed. 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...
 
typedef void(* spdk_nvme_disconnected_qpair_cb) (struct spdk_nvme_qpair *qpair, void *poll_group_ctx)
 This function alerts the user to disconnected qpairs when calling spdk_nvme_poll_group_process_completions.
 
typedef void(* spdk_nvme_reg_cb) (void *ctx, uint64_t value, const struct spdk_nvme_cpl *cpl)
 Signature for callback invoked after completing a register read/write operation. More...
 

Enumerations

enum  spdk_nvme_qp_failure_reason {
  SPDK_NVME_QPAIR_FAILURE_NONE = 0 , SPDK_NVME_QPAIR_FAILURE_LOCAL , SPDK_NVME_QPAIR_FAILURE_REMOTE , SPDK_NVME_QPAIR_FAILURE_UNKNOWN ,
  SPDK_NVME_QPAIR_FAILURE_RESET
}
 Reason for qpair disconnect at the transport layer. More...
 
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 ,
  SPDK_NVME_TRANSPORT_VFIOUSER = 1024 , SPDK_NVME_TRANSPORT_CUSTOM = 4096 , SPDK_NVME_TRANSPORT_CUSTOM_FABRICS = 4097
}
 NVMe library transports. More...
 
enum  spdk_nvme_ctrlr_flags {
  SPDK_NVME_CTRLR_SGL_SUPPORTED = 1 << 0 , SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED = 1 << 1 , SPDK_NVME_CTRLR_WRR_SUPPORTED = 1 << 2 , SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED = 1 << 3 ,
  SPDK_NVME_CTRLR_SGL_REQUIRES_DWORD_ALIGNMENT = 1 << 4 , SPDK_NVME_CTRLR_ZONE_APPEND_SUPPORTED = 1 << 5 , SPDK_NVME_CTRLR_DIRECTIVES_SUPPORTED = 1 << 6 , SPDK_NVME_CTRLR_MPTR_SGL_SUPPORTED = 1 << 7 ,
  SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED = 1 << 8
}
 
enum  spdk_nvme_ns_flags {
  SPDK_NVME_NS_DEALLOCATE_SUPPORTED = 1 << 0 , SPDK_NVME_NS_FLUSH_SUPPORTED = 1 << 1 , SPDK_NVME_NS_RESERVATION_SUPPORTED = 1 << 2 , SPDK_NVME_NS_WRITE_ZEROES_SUPPORTED = 1 << 3 ,
  SPDK_NVME_NS_DPS_PI_SUPPORTED = 1 << 4 , SPDK_NVME_NS_EXTENDED_LBA_SUPPORTED = 1 << 5 , SPDK_NVME_NS_WRITE_UNCORRECTABLE_SUPPORTED = 1 << 6 , SPDK_NVME_NS_COMPARE_SUPPORTED = 1 << 7
}
 Namespace command support flags. More...
 

Functions

 SPDK_STATIC_ASSERT (sizeof(struct spdk_nvme_ctrlr_opts)==832, "Incorrect size")
 
bool spdk_nvme_ctrlr_is_discovery (struct spdk_nvme_ctrlr *ctrlr)
 Indicate whether a ctrlr handle is associated with a Discovery controller. More...
 
bool spdk_nvme_ctrlr_is_fabrics (struct spdk_nvme_ctrlr *ctrlr)
 Indicate whether a ctrlr handle is associated with a fabrics 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...
 
const struct spdk_nvme_ctrlr_optsspdk_nvme_ctrlr_get_opts (struct spdk_nvme_ctrlr *ctrlr)
 
static bool spdk_nvme_trtype_is_fabrics (enum spdk_nvme_transport_type trtype)
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_nvme_ns_cmd_ext_io_opts)==56, "Incorrect size")
 
int spdk_nvme_transport_id_parse (struct spdk_nvme_transport_id *trid, const char *str)
 Parse the string representation of a transport ID. More...
 
void spdk_nvme_trid_populate_transport (struct spdk_nvme_transport_id *trid, enum spdk_nvme_transport_type trtype)
 Fill in the trtype and trstring fields of this trid based on a known transport type. 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_populate_trstring (struct spdk_nvme_transport_id *trid, const char *trstring)
 Parse the string representation of a transport ID transport type into the trid struct. 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 transport 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 transport 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...
 
bool spdk_nvme_transport_available_by_name (const char *transport_name)
 Determine whether the NVMe library can handle a specific NVMe over Fabrics transport type. More...
 
void spdk_nvme_pcie_set_hotplug_filter (spdk_nvme_pcie_hotplug_filter_cb filter_cb)
 Register the associated function to allow filtering of hot-inserted PCIe SSDs. 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)
 Proceed with attaching controllers associated with the probe context. 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_detach_async (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_detach_ctx **detach_ctx)
 Allocate a context to track detachment of multiple controllers if this call is the first successful start of detachment in a sequence, or use the passed context otherwise. More...
 
int spdk_nvme_detach_poll_async (struct spdk_nvme_detach_ctx *detach_ctx)
 Poll detachment of multiple controllers until they complete. More...
 
void spdk_nvme_detach_poll (struct spdk_nvme_detach_ctx *detach_ctx)
 Continue calling spdk_nvme_detach_poll_async() internally until it returns 0. More...
 
int spdk_nvme_ctrlr_set_trid (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_transport_id *trid)
 Update the transport ID for a given controller. More...
 
void spdk_nvme_ctrlr_set_remove_cb (struct spdk_nvme_ctrlr *ctrlr, spdk_nvme_remove_cb remove_cb, void *remove_ctx)
 Set the remove callback and context to be invoked if the controller is removed. More...
 
int spdk_nvme_ctrlr_reset (struct spdk_nvme_ctrlr *ctrlr)
 Perform a full hardware reset of the NVMe controller. More...
 
int spdk_nvme_ctrlr_disconnect (struct spdk_nvme_ctrlr *ctrlr)
 Disconnect the given NVMe controller. More...
 
void spdk_nvme_ctrlr_reconnect_async (struct spdk_nvme_ctrlr *ctrlr)
 Start re-enabling the given NVMe controller in a full reset sequence. More...
 
int spdk_nvme_ctrlr_reconnect_poll_async (struct spdk_nvme_ctrlr *ctrlr)
 Proceed with re-enabling the given NVMe controller. More...
 
int spdk_nvme_ctrlr_reset_subsystem (struct spdk_nvme_ctrlr *ctrlr)
 Perform a NVMe subsystem reset. More...
 
void spdk_nvme_ctrlr_fail (struct spdk_nvme_ctrlr *ctrlr)
 Fail the given NVMe controller. More...
 
bool spdk_nvme_ctrlr_is_failed (struct spdk_nvme_ctrlr *ctrlr)
 This function returns the failed status of a given 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_cc_register spdk_nvme_ctrlr_get_regs_cc (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller CC (Configuration) 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...
 
union spdk_nvme_pmrcap_register spdk_nvme_ctrlr_get_regs_pmrcap (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register. More...
 
union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller BPINFO (Boot Partition Information) register. More...
 
uint64_t spdk_nvme_ctrlr_get_pmrsz (struct spdk_nvme_ctrlr *ctrlr)
 Get the NVMe controller PMR size. More...
 
uint32_t spdk_nvme_ctrlr_get_num_ns (struct spdk_nvme_ctrlr *ctrlr)
 Get the maximum NSID value that will ever be used for the given 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...
 
uint16_t spdk_nvme_ctrlr_get_max_sges (const struct spdk_nvme_ctrlr *ctrlr)
 Get the maximum number of SGEs per request for the 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_disable_read_changed_ns_list_log_page (struct spdk_nvme_ctrlr *ctrlr)
 Disable reading the CHANGED_NS_LIST log page for the specified controller. More...
 
void spdk_nvme_ctrlr_register_timeout_callback (struct spdk_nvme_ctrlr *ctrlr, uint64_t timeout_io_us, uint64_t timeout_admin_us, spdk_nvme_timeout_cb cb_fn, void *cb_arg)
 Register for timeout callback on a controller. More...
 
int spdk_nvme_ctrlr_get_discovery_log_page (struct spdk_nvme_ctrlr *ctrlr, spdk_nvme_discovery_cb cb_fn, void *cb_arg)
 Get a full discovery log page from the specified controller. More...
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_nvme_io_qpair_opts)==72, "Incorrect size")
 
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_connect_io_qpair (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair)
 Connect a newly created I/O qpair. More...
 
void spdk_nvme_ctrlr_disconnect_io_qpair (struct spdk_nvme_qpair *qpair)
 Disconnect the given I/O qpair. More...
 
int spdk_nvme_ctrlr_reconnect_io_qpair (struct spdk_nvme_qpair *qpair)
 Attempt to reconnect the given qpair. More...
 
spdk_nvme_qp_failure_reason spdk_nvme_ctrlr_get_admin_qp_failure_reason (struct spdk_nvme_ctrlr *ctrlr)
 Returns the reason the admin qpair for a given controller is disconnected. 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...
 
int spdk_nvme_ctrlr_cmd_iov_raw_with_md (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, struct spdk_nvme_cmd *cmd, uint32_t len, void *md_buf, spdk_nvme_cmd_cb cb_fn, void *cb_arg, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn)
 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...
 
spdk_nvme_qp_failure_reason spdk_nvme_qpair_get_failure_reason (struct spdk_nvme_qpair *qpair)
 Returns the reason the qpair is disconnected. More...
 
void spdk_nvme_qpair_set_abort_dnr (struct spdk_nvme_qpair *qpair, bool dnr)
 Control if DNR is set or not for aborted commands. More...
 
bool spdk_nvme_qpair_is_connected (struct spdk_nvme_qpair *qpair)
 Return the connection status of a given qpair. 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_get_log_page_ext (struct spdk_nvme_ctrlr *ctrlr, uint8_t log_page, uint32_t nsid, void *payload, uint32_t payload_size, uint64_t offset, uint32_t cdw10, uint32_t cdw11, uint32_t cdw14, 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_abort_ext (struct spdk_nvme_ctrlr *ctrlr, struct spdk_nvme_qpair *qpair, void *cmd_cb_arg, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Abort previously submitted commands which have cmd_cb_arg as its callback argument. 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_cmd_security_receive (struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, uint8_t nssf, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Receive security protocol data from controller. More...
 
int spdk_nvme_ctrlr_cmd_security_send (struct spdk_nvme_ctrlr *ctrlr, uint8_t secp, uint16_t spsp, uint8_t nssf, void *payload, uint32_t payload_size, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send security protocol data to controller. 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...
 
int spdk_nvme_ctrlr_cmd_directive_receive (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, uint32_t doper, uint32_t dtype, uint32_t dspec, void *payload, uint32_t payload_size, uint32_t cdw12, uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Receive data related to a specific Directive Type from the controller. More...
 
int spdk_nvme_ctrlr_cmd_directive_send (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, uint32_t doper, uint32_t dtype, uint32_t dspec, void *payload, uint32_t payload_size, uint32_t cdw12, uint32_t cdw13, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Send data related to a specific Directive Type to the 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...
 
int spdk_nvme_ctrlr_read_boot_partition_start (struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t bprsz, uint32_t bprof, uint32_t bpid)
 Start the Read from a Boot Partition. More...
 
int spdk_nvme_ctrlr_read_boot_partition_poll (struct spdk_nvme_ctrlr *ctrlr)
 Poll the status of the Read from a Boot Partition. More...
 
int spdk_nvme_ctrlr_write_boot_partition (struct spdk_nvme_ctrlr *ctrlr, void *payload, uint32_t size, uint32_t bpid, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Write to a Boot Partition. 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...
 
int spdk_nvme_ctrlr_reserve_cmb (struct spdk_nvme_ctrlr *ctrlr)
 Reserve the controller memory buffer for data transfer use. More...
 
void * spdk_nvme_ctrlr_map_cmb (struct spdk_nvme_ctrlr *ctrlr, size_t *size)
 Map a previously reserved controller memory buffer so that it's data is visible from the CPU. More...
 
void spdk_nvme_ctrlr_unmap_cmb (struct spdk_nvme_ctrlr *ctrlr)
 Free a controller memory I/O buffer. More...
 
int spdk_nvme_ctrlr_enable_pmr (struct spdk_nvme_ctrlr *ctrlr)
 Enable the Persistent Memory Region. More...
 
int spdk_nvme_ctrlr_disable_pmr (struct spdk_nvme_ctrlr *ctrlr)
 Disable the Persistent Memory Region. More...
 
void * spdk_nvme_ctrlr_map_pmr (struct spdk_nvme_ctrlr *ctrlr, size_t *size)
 Map the Persistent Memory Region so that it's data is visible from the CPU. More...
 
int spdk_nvme_ctrlr_unmap_pmr (struct spdk_nvme_ctrlr *ctrlr)
 Free the Persistent Memory Region. 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...
 
int32_t spdk_nvme_ctrlr_alloc_qid (struct spdk_nvme_ctrlr *ctrlr)
 Alloc NVMe I/O queue identifier. More...
 
void spdk_nvme_ctrlr_free_qid (struct spdk_nvme_ctrlr *ctrlr, uint16_t qid)
 Free NVMe I/O queue identifier. More...
 
struct spdk_nvme_poll_group * spdk_nvme_poll_group_create (void *ctx, struct spdk_nvme_accel_fn_table *table)
 Create a new poll group. More...
 
struct spdk_nvme_poll_group * spdk_nvme_qpair_get_optimal_poll_group (struct spdk_nvme_qpair *qpair)
 Get a optimal poll group. More...
 
int spdk_nvme_poll_group_add (struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair)
 Add an spdk_nvme_qpair to a poll group. More...
 
int spdk_nvme_poll_group_remove (struct spdk_nvme_poll_group *group, struct spdk_nvme_qpair *qpair)
 Remove a disconnected spdk_nvme_qpair from a poll group. More...
 
int spdk_nvme_poll_group_destroy (struct spdk_nvme_poll_group *group)
 Destroy an empty poll group. More...
 
int64_t spdk_nvme_poll_group_process_completions (struct spdk_nvme_poll_group *group, uint32_t completions_per_qpair, spdk_nvme_disconnected_qpair_cb disconnected_qpair_cb)
 Poll for completions on all qpairs in this poll group. More...
 
int spdk_nvme_poll_group_all_connected (struct spdk_nvme_poll_group *group)
 Check if all qpairs in the poll group are connected. More...
 
void * spdk_nvme_poll_group_get_ctx (struct spdk_nvme_poll_group *group)
 Retrieve the user context for this specific poll group. More...
 
int spdk_nvme_poll_group_get_stats (struct spdk_nvme_poll_group *group, struct spdk_nvme_poll_group_stat **stats)
 Retrieves transport statistics for the given poll group. More...
 
void spdk_nvme_poll_group_free_stats (struct spdk_nvme_poll_group *group, struct spdk_nvme_poll_group_stat *stat)
 Frees poll group statistics retrieved using spdk_nvme_poll_group_get_stats function. 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...
 
uint32_t spdk_nvme_ns_get_format_index (const struct spdk_nvme_ns_data *nsdata)
 Get the format index 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...
 
bool spdk_nvme_ns_supports_compare (struct spdk_nvme_ns *ns)
 Check whether if the namespace supports compare operation. 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 uint8_t * spdk_nvme_ns_get_nguid (const struct spdk_nvme_ns *ns)
 Get the NGUID 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...
 
enum spdk_nvme_csi spdk_nvme_ns_get_csi (const struct spdk_nvme_ns *ns)
 Get the Command Set Identifier 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...
 
uint32_t spdk_nvme_ns_get_ana_group_id (const struct spdk_nvme_ns *ns)
 Get the ANA group ID for the given namespace. More...
 
enum spdk_nvme_ana_state spdk_nvme_ns_get_ana_state (const struct spdk_nvme_ns *ns)
 Get the ANA state 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_writev_ext (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, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn, struct spdk_nvme_ns_cmd_ext_io_opts *opts)
 Submit a write I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_write_ext (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, struct spdk_nvme_ns_cmd_ext_io_opts *opts)
 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_verify (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 verify I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_write_uncorrectable (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)
 Submit a write uncorrectable 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_readv_ext (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, spdk_nvme_req_reset_sgl_cb reset_sgl_fn, spdk_nvme_req_next_sge_cb next_sge_fn, struct spdk_nvme_ns_cmd_ext_io_opts *opts)
 Submit a read I/O to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_read_ext (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, struct spdk_nvme_ns_cmd_ext_io_opts *opts)
 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_copy (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, const struct spdk_nvme_scc_source_range *ranges, uint16_t num_ranges, uint64_t dest_lba, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit a simple copy command 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_io_mgmt_recv (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint32_t len, uint8_t mo, uint16_t mos, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit an I/O management receive command to the specified NVMe namespace. More...
 
int spdk_nvme_ns_cmd_io_mgmt_send (struct spdk_nvme_ns *ns, struct spdk_nvme_qpair *qpair, void *payload, uint32_t len, uint8_t mo, uint16_t mos, spdk_nvme_cmd_cb cb_fn, void *cb_arg)
 Submit an I/O management send command 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_comparev_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 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...
 
const char * spdk_nvme_cpl_get_status_string (const struct spdk_nvme_status *status)
 Given NVMe status, return ASCII string for that error. More...
 
const char * spdk_nvme_cpl_get_status_type_string (const struct spdk_nvme_status *status)
 Given NVMe status, return ASCII string for the type of that error. More...
 
void spdk_nvme_qpair_print_command (struct spdk_nvme_qpair *qpair, struct spdk_nvme_cmd *cmd)
 Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command). More...
 
void spdk_nvme_qpair_print_completion (struct spdk_nvme_qpair *qpair, struct spdk_nvme_cpl *cpl)
 Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry. More...
 
uint16_t spdk_nvme_qpair_get_id (struct spdk_nvme_qpair *qpair)
 Gets the NVMe qpair ID for the specified qpair. More...
 
uint32_t spdk_nvme_qpair_get_num_outstanding_reqs (struct spdk_nvme_qpair *qpair)
 Gets the number of outstanding requests for the specified qpair. More...
 
void spdk_nvme_print_command (uint16_t qid, struct spdk_nvme_cmd *cmd)
 Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command). More...
 
void spdk_nvme_print_completion (uint16_t qid, struct spdk_nvme_cpl *cpl)
 Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry. More...
 
void spdk_nvme_rdma_init_hooks (struct spdk_nvme_rdma_hooks *hooks)
 Set the global hooks for the RDMA transport, if necessary. More...
 
int spdk_nvme_cuse_get_ctrlr_name (struct spdk_nvme_ctrlr *ctrlr, char *name, size_t *size)
 Get name of cuse device associated with NVMe controller. More...
 
int spdk_nvme_cuse_get_ns_name (struct spdk_nvme_ctrlr *ctrlr, uint32_t nsid, char *name, size_t *size)
 Get name of cuse device associated with NVMe namespace. More...
 
int spdk_nvme_cuse_register (struct spdk_nvme_ctrlr *ctrlr)
 Create a character device at the path specified. More...
 
int spdk_nvme_cuse_unregister (struct spdk_nvme_ctrlr *ctrlr)
 Remove a previously created character device. More...
 
int spdk_nvme_ctrlr_get_memory_domains (const struct spdk_nvme_ctrlr *ctrlr, struct spdk_memory_domain **domains, int array_size)
 Get SPDK memory domains used by the given nvme controller. More...
 
void spdk_nvme_cuse_update_namespaces (struct spdk_nvme_ctrlr *ctrlr)
 Update and populate namespace CUSE devices (Experimental) More...
 
void spdk_nvme_transport_register (const struct spdk_nvme_transport_ops *ops)
 Register the operations for a given transport type. More...
 
 SPDK_STATIC_ASSERT (sizeof(struct spdk_nvme_transport_opts)==24, "Incorrect size")
 
void spdk_nvme_transport_get_opts (struct spdk_nvme_transport_opts *opts, size_t opts_size)
 Get the current NVMe transport options. More...
 
int spdk_nvme_transport_set_opts (const struct spdk_nvme_transport_opts *opts, size_t opts_size)
 Set the NVMe transport options. More...
 

Detailed Description

NVMe driver public API.

Macro Definition Documentation

◆ SPDK_NVME_TRANSPORT_REGISTER

#define SPDK_NVME_TRANSPORT_REGISTER (   name,
  transport_ops 
)
Value:
static void __attribute__((constructor)) _spdk_nvme_transport_register_##name(void) \
{ \
spdk_nvme_transport_register(transport_ops); \
}

Typedef Documentation

◆ spdk_nvme_accel_completion_cb

typedef void(* spdk_nvme_accel_completion_cb) (void *cb_arg, int status)

NVMe acceleration operation callback.

Parameters
cb_argThe user provided arg which is passed to the corresponding accelerated function call defined in struct spdk_nvme_accel_fn_table.
status0 if it completed successfully, or negative errno if it failed.

◆ spdk_nvme_accel_step_cb

typedef void(* spdk_nvme_accel_step_cb) (void *cb_arg)

Completion callback for a single operation in a sequence.

Parameters
cb_argArgument provided by the user when appending an operation to a sequence.

◆ spdk_nvme_aer_cb

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

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

Parameters
aer_cb_argContext specified by spdk_nvme_register_aer_callback().
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 *ctx, const struct spdk_nvme_cpl *cpl)

Signature for callback function invoked when a command is completed.

Parameters
ctxCallback context provided when the command was submitted.
cplCompletion queue entry that contains the completion status.

◆ spdk_nvme_discovery_cb

typedef void(* spdk_nvme_discovery_cb) (void *cb_arg, int rc, const struct spdk_nvme_cpl *cpl, struct spdk_nvmf_discovery_log_page *log_page)

Signature for the callback function when a spdk_nvme_ctrlr_get_discovery_log_page operation is completed.

Parameters
cb_argArgument passed to callback function.
rcStatus of operation. 0 means success, and that the cpl argument is valid. Failure indicated by negative errno value.
cplNVMe completion status of the operation. NULL if rc != 0. If multiple completions with error status occurred during the operation, the cpl value for the first error will be used here.
log_pagePointer to the full discovery log page. The application is responsible for freeing this buffer using free().

◆ 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_reg_cb

typedef void(* spdk_nvme_reg_cb) (void *ctx, uint64_t value, const struct spdk_nvme_cpl *cpl)

Signature for callback invoked after completing a register read/write operation.

Parameters
ctxContext passed by the user.
valueValue of the register, undefined in case of a failure.
cplCompletion queue entry that contains the status of the command.

◆ 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, a value of UINT64_MAX means the segment should be described via Bit Bucket SGL.
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 function.
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 

SGL is supported.

SPDK_NVME_CTRLR_SECURITY_SEND_RECV_SUPPORTED 

security send/receive is supported

SPDK_NVME_CTRLR_WRR_SUPPORTED 

Weighted Round Robin is supported.

SPDK_NVME_CTRLR_COMPARE_AND_WRITE_SUPPORTED 

Compare and write fused operations supported.

SPDK_NVME_CTRLR_SGL_REQUIRES_DWORD_ALIGNMENT 

Dword alignment is required for SGL.

SPDK_NVME_CTRLR_ZONE_APPEND_SUPPORTED 

Zone Append is supported (within Zoned Namespaces)

SPDK_NVME_CTRLR_DIRECTIVES_SUPPORTED 

The Directives is supported.

SPDK_NVME_CTRLR_MPTR_SGL_SUPPORTED 

MPTR containing SGL descriptor is supported.

SPDK_NVME_CTRLR_ACCEL_SEQUENCE_SUPPORTED 

Support for sending I/O requests with accel sequnece.

◆ 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_NS_WRITE_UNCORRECTABLE_SUPPORTED 

The write uncorrectable command is supported.

SPDK_NVME_NS_COMPARE_SUPPORTED 

The compare command is supported.

◆ spdk_nvme_qp_failure_reason

Reason for qpair disconnect at the transport layer.

NONE implies that the qpair is still connected while UNKNOWN means that the qpair is disconnected, but the cause was not apparent.

◆ 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.

SPDK_NVME_TRANSPORT_VFIOUSER 

Custom VFIO User Transport (Not spec defined)

SPDK_NVME_TRANSPORT_CUSTOM 

Custom Transport (Not spec defined)

SPDK_NVME_TRANSPORT_CUSTOM_FABRICS 

Custom Fabric Transport (Not spec defined)

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_cpl_get_status_string()

const char* spdk_nvme_cpl_get_status_string ( const struct spdk_nvme_status status)

Given NVMe status, return ASCII string for that error.

Parameters
statusStatus from NVMe completion queue element.
Returns
Returns status as an ASCII string.

◆ spdk_nvme_cpl_get_status_type_string()

const char* spdk_nvme_cpl_get_status_type_string ( const struct spdk_nvme_status status)

Given NVMe status, return ASCII string for the type of that error.

Parameters
statusStatus from NVMe completion queue element.
Returns
Returns status type as an ASCII string.

◆ 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).

This function by default also performs any connection activities required for a newly created qpair. To avoid that behavior, the user should set the create_only flag in the opts structure to true.

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_get_default_io_qpair_opts().
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_alloc_qid()

int32_t spdk_nvme_ctrlr_alloc_qid ( struct spdk_nvme_ctrlr *  ctrlr)

Alloc NVMe I/O queue identifier.

This function is only needed for the non-standard case of allocating queues using the raw command interface. In most cases spdk_nvme_ctrlr_alloc_io_qpair should be sufficient.

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

◆ 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().

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 if resources could not be allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.

◆ spdk_nvme_ctrlr_cmd_abort_ext()

int spdk_nvme_ctrlr_cmd_abort_ext ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
void *  cmd_cb_arg,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Abort previously submitted commands which have cmd_cb_arg as its callback argument.

Parameters
ctrlrNVMe controller to which the commands were submitted.
qpairNVMe queue pair to which the commands were submitted. For admin commands, pass NULL for the qpair.
cmd_cb_argCallback argument for the NVMe commands which this function attempts to abort.
cb_fnCallback function to invoke when this function has completed.
cb_argArgument to pass to the callback function.
Returns
0 if successfully submitted, negated errno 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 if successfully submitted, negated errno if resources could not be allocated for this request, -ENXIO if the admin qpair is failed at the transport layer.

◆ spdk_nvme_ctrlr_cmd_directive_receive()

int spdk_nvme_ctrlr_cmd_directive_receive ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
uint32_t  doper,
uint32_t  dtype,
uint32_t  dspec,
void *  payload,
uint32_t  payload_size,
uint32_t  cdw12,
uint32_t  cdw13,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Receive data related to a specific Directive Type from the 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 directive receive command submission.
nsidSpecific Namespace Identifier.
doperDirective Operation defined in nvme_spec.h.
dtypeDirective Type defined in nvme_spec.h.
dspecDirective Specific defined in nvme_spec.h.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cdw12Command dword 12.
cdw13Command dword 13.
cb_fnCallback function to invoke when the command has been completed.
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_directive_send()

int spdk_nvme_ctrlr_cmd_directive_send ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
uint32_t  doper,
uint32_t  dtype,
uint32_t  dspec,
void *  payload,
uint32_t  payload_size,
uint32_t  cdw12,
uint32_t  cdw13,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send data related to a specific Directive Type to the 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 directive send command submission.
nsidSpecific Namespace Identifier.
doperDirective Operation defined in nvme_spec.h.
dtypeDirective Type defined in nvme_spec.h.
dspecDirective Specific defined in nvme_spec.h.
payloadThe pointer to the payload buffer.
payload_sizeThe size of payload buffer.
cdw12Command dword 12.
cdw13Command dword 13.
cb_fnCallback function to invoke when the command has been completed.
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_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, -ENXIO if the admin qpair is failed at the transport layer.

◆ 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, -ENXIO if the admin qpair is failed at the transport layer.

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, -ENXIO if the admin qpair is failed at the transport layer.

◆ spdk_nvme_ctrlr_cmd_get_log_page_ext()

int spdk_nvme_ctrlr_cmd_get_log_page_ext ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  log_page,
uint32_t  nsid,
void *  payload,
uint32_t  payload_size,
uint64_t  offset,
uint32_t  cdw10,
uint32_t  cdw11,
uint32_t  cdw14,
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.

This function allows specifying extra fields in cdw10 and cdw11 such as Retain Asynchronous Event and Log Specific Field.

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.
cdw10Value to specify for cdw10. Specify 0 for numdl - it will be set by this function based on the payload_size parameter. Specify 0 for lid - it will be set by this function based on the log_page parameter.
cdw11Value to specify for cdw11. Specify 0 for numdu - it will be set by this function based on the payload_size.
cdw14Value to specify for cdw14.
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, -ENXIO if the admin qpair is failed at the transport layer.

◆ 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 if successfully submitted, negated errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 if successfully submitted, negated errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ctrlr_cmd_iov_raw_with_md()

int spdk_nvme_ctrlr_cmd_iov_raw_with_md ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cmd cmd,
uint32_t  len,
void *  md_buf,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn 
)

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!

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.
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.
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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ctrlr_cmd_security_receive()

int spdk_nvme_ctrlr_cmd_security_receive ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  secp,
uint16_t  spsp,
uint8_t  nssf,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Receive security protocol data from controller.

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

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.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the command has been completed.
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_security_send()

int spdk_nvme_ctrlr_cmd_security_send ( struct spdk_nvme_ctrlr *  ctrlr,
uint8_t  secp,
uint16_t  spsp,
uint8_t  nssf,
void *  payload,
uint32_t  payload_size,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Send security protocol data to controller.

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

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.
payload_sizeThe size of payload buffer.
cb_fnCallback function to invoke when the command has been completed.
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()

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, -ENXIO if the admin qpair is failed at the transport layer.

◆ 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, -ENXIO if the admin qpair is failed at the transport layer.

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_connect_io_qpair()

int spdk_nvme_ctrlr_connect_io_qpair ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_qpair *  qpair 
)

Connect a newly created I/O qpair.

This function does any connection activities required for a newly created qpair. It should be called after spdk_nvme_ctrlr_alloc_io_qpair has been called with the create_only flag set to true in the spdk_nvme_io_qpair_opts structure.

This call will fail if performed on a qpair that is already connected. For reconnecting qpairs, see spdk_nvme_ctrlr_reconnect_io_qpair.

For fabrics like TCP and RDMA, this function actually sends the commands over the wire that connect the qpair. For PCIe, this function performs some internal state machine operations.

Parameters
ctrlrNVMe controller for which to allocate the I/O queue pair.
qpairOpaque handle to the qpair to connect.

return 0 on success or negated errno on failure. Specifically -EISCONN if the qpair is already connected.

◆ 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().

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().

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_disable_pmr()

int spdk_nvme_ctrlr_disable_pmr ( struct spdk_nvme_ctrlr *  ctrlr)

Disable the Persistent Memory Region.

Parameters
ctrlrController that contains the Persistent Memory Region
Returns
0 on success. Negated errno on the following error conditions: -ENOTSUP: PMR is not supported by the Controller. -EIO: Registers access failure. -EINVAL: PMR Time Units Invalid or PMR is already disabled. -ETIMEDOUT: Timed out to Disable PMR. -ENOSYS: Transport does not support Disable PMR function.

◆ spdk_nvme_ctrlr_disable_read_changed_ns_list_log_page()

void spdk_nvme_ctrlr_disable_read_changed_ns_list_log_page ( struct spdk_nvme_ctrlr *  ctrlr)

Disable reading the CHANGED_NS_LIST log page for the specified controller.

Applications that register an AER callback may wish to read the CHANGED_NS_LIST log page itself, rather than relying on the driver to do it. Calling this function will ensure that the driver does not read this log page if the controller returns a NS_ATTR_CHANGED AEN.

Reading of this log page can alternatively be disabled by setting the disable_read_changed_ns_list_log_page flag in the spdk_nvme_ctrlr_opts when attaching the controller.

Parameters
ctrlrNVMe controller on which to disable the log page read.

◆ spdk_nvme_ctrlr_disconnect()

int spdk_nvme_ctrlr_disconnect ( struct spdk_nvme_ctrlr *  ctrlr)

Disconnect the given NVMe controller.

This function is used as the first operation of a full reset sequence of the given NVMe controller. The NVMe controller is ready to reconnect after completing this function.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
0 on success, -EBUSY if controller is already resetting, or -ENXIO if controller has been removed.

◆ spdk_nvme_ctrlr_disconnect_io_qpair()

void spdk_nvme_ctrlr_disconnect_io_qpair ( struct spdk_nvme_qpair *  qpair)

Disconnect the given I/O qpair.

This function must be called from the same thread as spdk_nvme_qpair_process_completions and the spdk_nvme_ns_cmd_* functions.

After disconnect, calling spdk_nvme_qpair_process_completions or one of the spdk_nvme_ns_cmd* on a qpair will result in a return value of -ENXIO. A disconnected qpair may be reconnected with either the spdk_nvme_ctrlr_connect_io_qpair or spdk_nvme_ctrlr_reconnect_io_qpair APIs.

Parameters
qpairThe qpair to disconnect.

◆ spdk_nvme_ctrlr_enable_pmr()

int spdk_nvme_ctrlr_enable_pmr ( struct spdk_nvme_ctrlr *  ctrlr)

Enable the Persistent Memory Region.

Parameters
ctrlrController that contains the Persistent Memory Region
Returns
0 on success. Negated errno on the following error conditions: -ENOTSUP: PMR is not supported by the Controller. -EIO: Registers access failure. -EINVAL: PMR Time Units Invalid or PMR is already enabled. -ETIMEDOUT: Timed out to Enable PMR. -ENOSYS: Transport does not support Enable PMR function.

◆ spdk_nvme_ctrlr_fail()

void spdk_nvme_ctrlr_fail ( struct spdk_nvme_ctrlr *  ctrlr)

Fail the given NVMe controller.

This function gives the application the opportunity to fail a controller at will. When a controller is failed, any calls to process completions or submit I/O on qpairs associated with that controller will fail with an error code of -ENXIO. The controller can only be taken from the failed state by calling spdk_nvme_ctrlr_reset. After the controller has been successfully reset, any I/O pending when the controller was moved to failed will be aborted back to the application and can be resubmitted. I/O can then resume.

Parameters
ctrlrOpaque handle to an NVMe controller.

◆ 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_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().

The qpair must not be accessed after calling this function.

Parameters
qpairI/O queue pair to free.
Returns
0 on success. This function will never return any value other than 0.

◆ spdk_nvme_ctrlr_free_qid()

void spdk_nvme_ctrlr_free_qid ( struct spdk_nvme_ctrlr *  ctrlr,
uint16_t  qid 
)

Free NVMe I/O queue identifier.

This function must only be called with qids previously allocated with spdk_nvme_ctrlr_alloc_qid.

Parameters
ctrlrOpaque handle to NVMe controller.
qidNVMe Queue Identifier.

◆ spdk_nvme_ctrlr_get_admin_qp_failure_reason()

spdk_nvme_qp_failure_reason spdk_nvme_ctrlr_get_admin_qp_failure_reason ( struct spdk_nvme_ctrlr *  ctrlr)

Returns the reason the admin qpair for a given controller is disconnected.

Parameters
ctrlrThe controller to check.
Returns
a valid spdk_nvme_qp_failure_reason.

◆ 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_discovery_log_page()

int spdk_nvme_ctrlr_get_discovery_log_page ( struct spdk_nvme_ctrlr *  ctrlr,
spdk_nvme_discovery_cb  cb_fn,
void *  cb_arg 
)

Get a full discovery log page from the specified controller.

This function will first read the discovery log header to determine the total number of valid entries in the discovery log, then it will allocate a buffer to hold the entire log and issue multiple GET_LOG_PAGE commands to get all of the entries.

The application is responsible for calling spdk_nvme_ctrlr_process_admin_completions to trigger processing of completions submitted by this function.

Parameters
ctrlrPointer to the discovery controller.
cb_fnFunction to call when the operation is complete.
cb_argArgument to pass to cb_fn.

◆ 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_sges()

uint16_t spdk_nvme_ctrlr_get_max_sges ( const struct spdk_nvme_ctrlr *  ctrlr)

Get the maximum number of SGEs per request for the given NVMe controller.

Controllers that do not support SGL will return UINT16_MAX.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
Maximum number of SGEs per request

◆ 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.

Parameters
ctrlrOpaque handle to 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_memory_domains()

int spdk_nvme_ctrlr_get_memory_domains ( const struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_memory_domain **  domains,
int  array_size 
)

Get SPDK memory domains used by the given nvme controller.

The user can call this function with domains set to NULL and array_size set to 0 to get the number of memory domains used by nvme controller

Parameters
ctrlrOpaque handle to the NVMe controller.
domainsPointer to an array of memory domains to be filled by this function. The user should allocate big enough array to keep all memory domains used by nvme controller
array_sizesize of domains array
Returns
the number of entries in domains array or negated errno. If returned value is bigger than array_size passed by the user then the user should increase the size of domains array and call this function again. There is no guarantees that the content of domains array is valid in that case. -EINVAL if input parameters were invalid

◆ 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 maximum NSID value that will ever be used for the given 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.

The NN field in the NVMe specification represents the maximum value that a namespace ID can ever have. Prior to NVMe 1.2, this was also the number of active namespaces, but from 1.2 onward the list of namespaces may be sparsely populated. Unfortunately, the meaning of this field is often misinterpreted by drive manufacturers and NVMe-oF implementers so it is not considered reliable. AVOID USING THIS FUNCTION WHENEVER POSSIBLE.

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_pmrsz()

uint64_t spdk_nvme_ctrlr_get_pmrsz ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller PMR size.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller PMR size or 0 if PMR is not supported.

◆ 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_bpinfo()

union spdk_nvme_bpinfo_register spdk_nvme_ctrlr_get_regs_bpinfo ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller BPINFO (Boot Partition Information) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller BPINFO (Boot Partition Information) register.

◆ 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_cc()

union spdk_nvme_cc_register spdk_nvme_ctrlr_get_regs_cc ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller CC (Configuration) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller CC (Configuration) 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_pmrcap()

union spdk_nvme_pmrcap_register spdk_nvme_ctrlr_get_regs_pmrcap ( struct spdk_nvme_ctrlr *  ctrlr)

Get the NVMe controller PMRCAP (Persistent Memory Region Capabilities) register.

Parameters
ctrlrOpaque handle to NVMe controller.
Returns
the NVMe controller PMRCAP (Persistent Memory Region Capabilities) 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/malicious 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 if successfully submitted, negated errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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_fabrics()

bool spdk_nvme_ctrlr_is_fabrics ( struct spdk_nvme_ctrlr *  ctrlr)

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

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

◆ spdk_nvme_ctrlr_is_failed()

bool spdk_nvme_ctrlr_is_failed ( struct spdk_nvme_ctrlr *  ctrlr)

This function returns the failed status of a given controller.

Parameters
ctrlrOpaque handle to an NVMe controller.
Returns
True if the controller is failed, false otherwise.

◆ 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_map_cmb()

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

Map a previously reserved controller memory buffer so that it's data is visible from the CPU.

This operation is not always possible.

Parameters
ctrlrController that contains the memory buffer
sizeSize of buffer that was mapped.
Returns
Pointer to controller memory buffer, or NULL on failure.

◆ spdk_nvme_ctrlr_map_pmr()

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

Map the Persistent Memory Region so that it's data is visible from the CPU.

Parameters
ctrlrController that contains the Persistent Memory Region
sizeSize of the region that was mapped.
Returns
Pointer to Persistent Memory Region, or NULL on failure.

◆ 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. -ENXIO in the special case that the qpair is failed at the transport layer.

◆ spdk_nvme_ctrlr_read_boot_partition_poll()

int spdk_nvme_ctrlr_read_boot_partition_poll ( struct spdk_nvme_ctrlr *  ctrlr)

Poll the status of the Read from a Boot Partition.

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

Parameters
ctrlrNVMe controller to perform the Boot Partition read.
Returns
0 if Boot Partition read is successful. Negated errno on the following error conditions: -EIO: Registers access failure. -EINVAL: Invalid read status or the Boot Partition read is not initiated yet. -EAGAIN: If the read is still in progress; users must call spdk_nvme_ctrlr_read_boot_partition_poll again to check the read status.

◆ spdk_nvme_ctrlr_read_boot_partition_start()

int spdk_nvme_ctrlr_read_boot_partition_start ( struct spdk_nvme_ctrlr *  ctrlr,
void *  payload,
uint32_t  bprsz,
uint32_t  bprof,
uint32_t  bpid 
)

Start the Read from a Boot Partition.

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

Parameters
ctrlrNVMe controller to perform the Boot Partition read.
payloadThe data buffer for Boot Partition read.
bprszRead size in multiples of 4 KiB to copy into the Boot Partition Memory Buffer.
bprofBoot Partition offset to read from in 4 KiB units.
bpidBoot Partition identifier for the Boot Partition read operation.
Returns
0 if Boot Partition read is successful. Negated errno on the following error conditions: -ENOMEM: if resources could not be allocated. -ENOTSUP: Boot Partition is not supported by the Controller. -EIO: Registers access failure. -EINVAL: Parameters are invalid. -EFAULT: Invalid address was specified as part of payload. -EALREADY: Boot Partition read already initiated.

◆ spdk_nvme_ctrlr_reconnect_async()

void spdk_nvme_ctrlr_reconnect_async ( struct spdk_nvme_ctrlr *  ctrlr)

Start re-enabling the given NVMe controller in a full reset sequence.

Parameters
ctrlrOpaque handle to NVMe controller.

◆ spdk_nvme_ctrlr_reconnect_io_qpair()

int spdk_nvme_ctrlr_reconnect_io_qpair ( struct spdk_nvme_qpair *  qpair)

Attempt to reconnect the given qpair.

This function is intended to be called on qpairs that have already been connected, but have since entered a failed state as indicated by a return value of -ENXIO from either spdk_nvme_qpair_process_completions or one of the spdk_nvme_ns_cmd_* functions. This function must be called from the same thread as spdk_nvme_qpair_process_completions and the spdk_nvme_ns_cmd_* functions.

Calling this function has the same effect as calling spdk_nvme_ctrlr_disconnect_io_qpair followed by spdk_nvme_ctrlr_connect_io_qpair.

This function may be called on newly created qpairs, but it does extra checks and attempts to disconnect the qpair before connecting it. The recommended API for newly created qpairs is spdk_nvme_ctrlr_connect_io_qpair.

Parameters
qpairThe qpair to reconnect.
Returns
0 on success, or if the qpair was already connected. -EAGAIN if the driver was unable to reconnect during this call, but the controller is still connected and is either resetting or enabled. -ENODEV if the controller is removed. In this case, the controller cannot be recovered and the application will have to destroy it and the associated qpairs. -ENXIO if the controller is in a failed state but is not yet resetting. In this case, the application should call spdk_nvme_ctrlr_reset to reset the entire controller.

◆ spdk_nvme_ctrlr_reconnect_poll_async()

int spdk_nvme_ctrlr_reconnect_poll_async ( struct spdk_nvme_ctrlr *  ctrlr)

Proceed with re-enabling the given NVMe controller.

Users must call this function in a full reset sequence until it returns a value other than -EAGAIN.

Returns
0 if the given NVMe controller is enabled, or -EBUSY if there are still pending operations to enable it.

◆ 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 event 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_io_us,
uint64_t  timeout_admin_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_io_usTimeout value in microseconds for io commands.
timeout_admin_usTimeout value in microseconds for admin commands.
cb_fnA function pointer that points to the callback function.
cb_argArgument to the callback function.

◆ spdk_nvme_ctrlr_reserve_cmb()

int spdk_nvme_ctrlr_reserve_cmb ( struct spdk_nvme_ctrlr *  ctrlr)

Reserve the controller memory buffer for data transfer use.

This function reserves the full size of the controller memory buffer for use in data transfers. If submission queues or completion queues are already placed in the controller memory buffer, this call will fail.

Parameters
ctrlrController from which to allocate memory buffer
Returns
The size of the controller memory buffer on success. Negated errno on failure.

◆ 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(), spdk_nvme_ns_get_data(), spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_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_reset_subsystem()

int spdk_nvme_ctrlr_reset_subsystem ( struct spdk_nvme_ctrlr *  ctrlr)

Perform a NVMe subsystem reset.

This function should be called from a single thread while no other threads are actively using the NVMe device. A subsystem reset is typically seen by the OS as a hot remove, followed by a hot add event.

Any pointers returned from spdk_nvme_ctrlr_get_ns(), spdk_nvme_ns_get_data(), spdk_nvme_zns_ns_get_data(), and spdk_nvme_zns_ctrlr_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, -ENOTSUP if subsystem reset is not supported.

◆ 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().

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().

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_set_remove_cb()

void spdk_nvme_ctrlr_set_remove_cb ( struct spdk_nvme_ctrlr *  ctrlr,
spdk_nvme_remove_cb  remove_cb,
void *  remove_ctx 
)

Set the remove callback and context to be invoked if the controller is removed.

This will override any remove_cb and/or ctx specified when the controller was probed.

This function may only be called from the primary process. This function has no effect if called from a secondary process.

Parameters
ctrlrOpaque handle to an NVMe controller.
remove_cbremove callback
remove_ctxremove callback context

◆ spdk_nvme_ctrlr_set_trid()

int spdk_nvme_ctrlr_set_trid ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_transport_id trid 
)

Update the transport ID for a given controller.

This function allows the user to set a new trid for a controller only if the controller is failed. The controller's failed state can be obtained from spdk_nvme_ctrlr_is_failed(). The controller can also be forced to the failed state using spdk_nvme_ctrlr_fail().

This function also requires that the transport type and subnqn of the new trid be the same as the old trid.

Parameters
ctrlrOpaque handle to an NVMe controller.
tridThe new transport ID.
Returns
0 on success, -EINVAL if the trid is invalid, -EPERM if the ctrlr is not failed.

◆ spdk_nvme_ctrlr_unmap_cmb()

void spdk_nvme_ctrlr_unmap_cmb ( struct spdk_nvme_ctrlr *  ctrlr)

Free a controller memory I/O buffer.

Parameters
ctrlrController from which to unmap the memory buffer.

◆ spdk_nvme_ctrlr_unmap_pmr()

int spdk_nvme_ctrlr_unmap_pmr ( struct spdk_nvme_ctrlr *  ctrlr)

Free the Persistent Memory Region.

Parameters
ctrlrController from which to unmap the Persistent Memory Region.
Returns
0 on success, negative errno on failure. -ENXIO: Either PMR is not supported by the Controller or the PMR is already unmapped. -ENOSYS: Transport does not support Unmap PMR function.

◆ 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_ctrlr_write_boot_partition()

int spdk_nvme_ctrlr_write_boot_partition ( struct spdk_nvme_ctrlr *  ctrlr,
void *  payload,
uint32_t  size,
uint32_t  bpid,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Write to a Boot Partition.

This function is thread safe and can be called at any point after spdk_nvme_probe(). Users will get the completion after the data is downloaded, image is replaced and Boot Partition is activated or when the sequence encounters an error.

Parameters
ctrlrNVMe controller to perform the Boot Partition write.
payloadThe data buffer for Boot Partition write.
sizeData size to write to the Boot Partition.
bpidBoot Partition identifier for the Boot Partition write operation.
cb_fnCallback function to invoke when the operation is completed.
cb_argArgument to pass to the callback function.
Returns
0 if Boot Partition write submit is successful. Negated errno on the following error conditions: -ENOMEM: if resources could not be allocated. -ENOTSUP: Boot Partition is not supported by the Controller. -EIO: Registers access failure. -EINVAL: Parameters are invalid.

◆ spdk_nvme_cuse_get_ctrlr_name()

int spdk_nvme_cuse_get_ctrlr_name ( struct spdk_nvme_ctrlr *  ctrlr,
char *  name,
size_t *  size 
)

Get name of cuse device associated with NVMe controller.

Parameters
ctrlrOpaque handle to NVMe controller.
nameBuffer of be filled with cuse device name.
sizeSize of name buffer.
Returns
0 on success. Negated errno on the following error conditions: -ENODEV: No cuse device registered for the controller. -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.

◆ spdk_nvme_cuse_get_ns_name()

int spdk_nvme_cuse_get_ns_name ( struct spdk_nvme_ctrlr *  ctrlr,
uint32_t  nsid,
char *  name,
size_t *  size 
)

Get name of cuse device associated with NVMe namespace.

Parameters
ctrlrOpaque handle to NVMe controller.
nsidNamespace id.
nameBuffer of be filled with cuse device name.
sizeSize of name buffer.
Returns
0 on success. Negated errno on the following error conditions: -ENODEV: No cuse device registered for the namespace. -ENSPC: Too small buffer size passed. Value of size pointer changed to the required length.

◆ spdk_nvme_cuse_register()

int spdk_nvme_cuse_register ( struct spdk_nvme_ctrlr *  ctrlr)

Create a character device at the path specified.

The character device can handle ioctls and is compatible with a standard Linux kernel NVMe device. Tools such as nvme-cli can be used to configure SPDK devices through this interface.

The user is expected to be polling the admin qpair for this controller periodically for the CUSE device to function.

Parameters
ctrlrOpaque handle to the NVMe controller.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_cuse_unregister()

int spdk_nvme_cuse_unregister ( struct spdk_nvme_ctrlr *  ctrlr)

Remove a previously created character device.

Parameters
ctrlrOpaque handle to the NVMe controller.
Returns
0 on success. Negated errno on failure.

◆ spdk_nvme_cuse_update_namespaces()

void spdk_nvme_cuse_update_namespaces ( struct spdk_nvme_ctrlr *  ctrlr)

Update and populate namespace CUSE devices (Experimental)

Parameters
ctrlrOpaque handle to the NVMe controller.

◆ 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_detach_async()

int spdk_nvme_detach_async ( struct spdk_nvme_ctrlr *  ctrlr,
struct spdk_nvme_detach_ctx **  detach_ctx 
)

Allocate a context to track detachment of multiple controllers if this call is the first successful start of detachment in a sequence, or use the passed context otherwise.

Then, start detaching the specified device returned by spdk_nvme_probe()'s attach_cb from the NVMe driver, and append this detachment to the context.

User must call spdk_nvme_detach_poll_async() to complete the detachment.

If the context is not allocated before this call, and if the specified device is detached locally from the caller process but any other process still attaches it or failed to be detached, context is not allocated.

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.
detach_ctxReference to the context in a sequence. An new context is allocated if this call is the first successful start of detachment in a sequence, or use the passed context.

◆ spdk_nvme_detach_poll()

void spdk_nvme_detach_poll ( struct spdk_nvme_detach_ctx *  detach_ctx)

Continue calling spdk_nvme_detach_poll_async() internally until it returns 0.

Parameters
detach_ctxContext to track the detachment.

◆ spdk_nvme_detach_poll_async()

int spdk_nvme_detach_poll_async ( struct spdk_nvme_detach_ctx *  detach_ctx)

Poll detachment of multiple controllers until they complete.

User must call this function until it returns 0.

Parameters
detach_ctxContext to track the detachment.
Returns
0 if all detachments complete; the context is also freed and no longer valid.
-EAGAIN if any detachment is still in progress; users must call spdk_nvme_detach_poll_async() again to continue progress.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_comparev_with_md()

int spdk_nvme_ns_cmd_comparev_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 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.
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, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_copy()

int spdk_nvme_ns_cmd_copy ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
const struct spdk_nvme_scc_source_range ranges,
uint16_t  num_ranges,
uint64_t  dest_lba,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit a simple copy command 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.

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 SCC is required, simply build and submit a raw command using spdk_nvme_ctrlr_cmd_io_raw().

Parameters
nsNVMe namespace to submit the SCC request
qpairI/O queue pair to submit the request
rangesAn array of spdk_nvme_scc_source_range elements describing the LBAs to operate on.
num_rangesThe number of elements in the ranges array.
dest_lbaDestination LBA to copy the data.
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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -EINVAL: Invalid ranges. -ENXIO: The qpair is failed at the transport level.

◆ 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.

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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_io_mgmt_recv()

int spdk_nvme_ns_cmd_io_mgmt_recv ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint32_t  len,
uint8_t  mo,
uint16_t  mos,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit an I/O management receive command 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 I/O mgmt receive request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer for I/O mgmt receive data.
lenLength bytes for I/O mgmt receive data structure.
moManagement operation to perform.
mosManagement operation specific field for the mo.
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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_io_mgmt_send()

int spdk_nvme_ns_cmd_io_mgmt_send ( struct spdk_nvme_ns *  ns,
struct spdk_nvme_qpair *  qpair,
void *  payload,
uint32_t  len,
uint8_t  mo,
uint16_t  mos,
spdk_nvme_cmd_cb  cb_fn,
void *  cb_arg 
)

Submit an I/O management send command 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 I/O mgmt send request.
qpairI/O queue pair to submit the request.
payloadVirtual address pointer for I/O mgmt send data.
lenLength bytes for I/O mgmt send data structure.
moManagement operation to perform.
mosManagement operation specific field for the mo.
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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_read_ext()

int spdk_nvme_ns_cmd_read_ext ( 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,
struct spdk_nvme_ns_cmd_ext_io_opts opts 
)

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
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
optsOptional structure with extended IO request options. If provided, the caller must guarantee that this structure is accessible until IO completes
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level. -EFAULT: Invalid address was specified as part of payload. cb_fn is also called with error status including dnr=1 in this case.

◆ 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.

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
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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_readv_ext()

int spdk_nvme_ns_cmd_readv_ext ( 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,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn,
struct spdk_nvme_ns_cmd_ext_io_opts opts 
)

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
reset_sgl_fncallback function to reset scattered payload
next_sge_fncallback function to iterate each scattered payload memory segment
optsOptional structure with extended IO request options. If provided, the caller must guarantee that this structure is accessible until IO completes
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level. -EFAULT: Invalid address was specified as part of payload. cb_fn is also called with error status including dnr=1 in this case.

◆ 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.

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
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, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_verify()

int spdk_nvme_ns_cmd_verify ( 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 verify 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 verify I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA to verify the data.
lba_countLength (in sectors) for the verify 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_write_ext()

int spdk_nvme_ns_cmd_write_ext ( 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,
struct spdk_nvme_ns_cmd_ext_io_opts opts 
)

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
optsOptional structure with extended IO request options. If provided, the caller must guarantee that this structure is accessible until IO completes
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level. -EFAULT: Invalid address was specified as part of payload. cb_fn is also called with error status including dnr=1 in this case.

◆ spdk_nvme_ns_cmd_write_uncorrectable()

int spdk_nvme_ns_cmd_write_uncorrectable ( 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 
)

Submit a write uncorrectable 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 uncorrectable I/O.
qpairI/O queue pair to submit the request.
lbaStarting LBA for this command.
lba_countLength (in sectors) for the write uncorrectable operation.
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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ 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 errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_cmd_writev_ext()

int spdk_nvme_ns_cmd_writev_ext ( 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,
spdk_nvme_req_reset_sgl_cb  reset_sgl_fn,
spdk_nvme_req_next_sge_cb  next_sge_fn,
struct spdk_nvme_ns_cmd_ext_io_opts opts 
)

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
reset_sgl_fncallback function to reset scattered payload
next_sge_fncallback function to iterate each scattered payload memory segment
optsOptional structure with extended IO request options. If provided, the caller must guarantee that this structure is accessible until IO completes
Returns
0 if successfully submitted, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level. -EFAULT: Invalid address was specified as part of payload. cb_fn is also called with error status including dnr=1 in this case.

◆ 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, negated errnos on the following error conditions: -EINVAL: The request is malformed. -ENOMEM: The request cannot be allocated. -ENXIO: The qpair is failed at the transport level.

◆ spdk_nvme_ns_get_ana_group_id()

uint32_t spdk_nvme_ns_get_ana_group_id ( const struct spdk_nvme_ns *  ns)

Get the ANA group ID for the given namespace.

This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.

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 ANA group ID for the given namespace.

◆ spdk_nvme_ns_get_ana_state()

enum spdk_nvme_ana_state spdk_nvme_ns_get_ana_state ( const struct spdk_nvme_ns *  ns)

Get the ANA state for the given namespace.

This function should be called only if spdk_nvme_ctrlr_is_log_page_supported() returns true for the controller and log page ID SPDK_NVME_LOG_ASYMMETRIC_NAMESPACE_ACCESS.

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 ANA state for the given namespace.

◆ spdk_nvme_ns_get_csi()

enum spdk_nvme_csi spdk_nvme_ns_get_csi ( const struct spdk_nvme_ns *  ns)

Get the Command Set Identifier for the given namespace.

Parameters
nsNamespace to query.
Returns
the namespace Command Set Identifier.

◆ 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_format_index()

uint32_t spdk_nvme_ns_get_format_index ( const struct spdk_nvme_ns_data nsdata)

Get the format index 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
nsdatapointer to the NVMe namespace data.
Returns
the format index of 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_nguid()

const uint8_t* spdk_nvme_ns_get_nguid ( const struct spdk_nvme_ns *  ns)

Get the NGUID for the given namespace.

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

◆ 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_compare()

bool spdk_nvme_ns_supports_compare ( struct spdk_nvme_ns *  ns)

Check whether if the namespace supports compare operation.

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 supports compare operation, or false otherwise.

◆ 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_pcie_set_hotplug_filter()

void spdk_nvme_pcie_set_hotplug_filter ( spdk_nvme_pcie_hotplug_filter_cb  filter_cb)

Register the associated function to allow filtering of hot-inserted PCIe SSDs.

If an application is using spdk_nvme_probe() to detect hot-inserted SSDs, this function may be used to register a function to filter those SSDs. If the filter function returns true, the nvme library will notify the SPDK env layer to allow probing of the device.

Registering a filter function is optional. If none is registered, the nvme library will allow probing of all hot-inserted SSDs.

Parameters
filter_cbFilter function callback routine

◆ spdk_nvme_poll_group_add()

int spdk_nvme_poll_group_add ( struct spdk_nvme_poll_group *  group,
struct spdk_nvme_qpair *  qpair 
)

Add an spdk_nvme_qpair to a poll group.

qpairs may only be added to a poll group if they are in the disconnected state; i.e. either they were just allocated and not yet connected or they have been disconnected with a call to spdk_nvme_ctrlr_disconnect_io_qpair.

Parameters
groupThe group to which the qpair will be added.
qpairThe qpair to add to the poll group.

return 0 on success, -EINVAL if the qpair is not in the disabled state, -ENODEV if the transport doesn't exist, -ENOMEM on memory allocation failures, or -EPROTO on a protocol (transport) specific failure.

◆ spdk_nvme_poll_group_all_connected()

int spdk_nvme_poll_group_all_connected ( struct spdk_nvme_poll_group *  group)

Check if all qpairs in the poll group are connected.

This function allows the caller to check if all qpairs in a poll group are connected. This API is generally only suitable during application startup, to check when a large number of async connections have completed.

It is useful for applications like benchmarking tools to create a large number of qpairs, but then ensuring they are all fully connected before proceeding with I/O.

Parameters
groupThe group on which to poll connecting qpairs.

return 0 if all qpairs are in CONNECTED state, -EIO if any connections failed to connect, -EAGAIN if any qpairs are still trying to connected.

◆ spdk_nvme_poll_group_create()

struct spdk_nvme_poll_group* spdk_nvme_poll_group_create ( void *  ctx,
struct spdk_nvme_accel_fn_table table 
)

Create a new poll group.

Parameters
ctxA user supplied context that can be retrieved later with spdk_nvme_poll_group_get_ctx
tableThe call back table defined by users which contains the accelerated functions which can be used to accelerate some operations such as crc32c.
Returns
Pointer to the new poll group, or NULL on error.

◆ spdk_nvme_poll_group_destroy()

int spdk_nvme_poll_group_destroy ( struct spdk_nvme_poll_group *  group)

Destroy an empty poll group.

Parameters
groupThe group to destroy.

return 0 on success, -EBUSY if the poll group is not empty.

◆ spdk_nvme_poll_group_free_stats()

void spdk_nvme_poll_group_free_stats ( struct spdk_nvme_poll_group *  group,
struct spdk_nvme_poll_group_stat stat 
)

Frees poll group statistics retrieved using spdk_nvme_poll_group_get_stats function.

Parameters
groupPointer to a poll group
statPointer to statistics to be released

◆ spdk_nvme_poll_group_get_ctx()

void* spdk_nvme_poll_group_get_ctx ( struct spdk_nvme_poll_group *  group)

Retrieve the user context for this specific poll group.

Parameters
groupThe poll group from which to retrieve the context.
Returns
A pointer to the user provided poll group context.

◆ spdk_nvme_poll_group_get_stats()

int spdk_nvme_poll_group_get_stats ( struct spdk_nvme_poll_group *  group,
struct spdk_nvme_poll_group_stat **  stats 
)

Retrieves transport statistics for the given poll group.

Note: the structure returned by this function should later be freed with spdk_nvme_poll_group_free_stats function

Parameters
groupPointer to NVME poll group
statsDouble pointer to statistics to be filled by this function
Returns
0 on success or negated errno on failure

◆ spdk_nvme_poll_group_process_completions()

int64_t spdk_nvme_poll_group_process_completions ( struct spdk_nvme_poll_group *  group,
uint32_t  completions_per_qpair,
spdk_nvme_disconnected_qpair_cb  disconnected_qpair_cb 
)

Poll for completions on all qpairs in this poll group.

the disconnected_qpair_cb will be called for all disconnected qpairs in the poll group including qpairs which fail within the context of this call. The user is responsible for trying to reconnect or destroy those qpairs.

Parameters
groupThe group on which to poll for completions.
completions_per_qpairThe maximum number of completions per qpair.
disconnected_qpair_cbA callback function of type spdk_nvme_disconnected_qpair_cb. Must be non-NULL.

return The number of completions across all qpairs, -EINVAL if no disconnected_qpair_cb is passed, or -EIO if the shared completion queue cannot be polled for the RDMA transport.

◆ spdk_nvme_poll_group_remove()

int spdk_nvme_poll_group_remove ( struct spdk_nvme_poll_group *  group,
struct spdk_nvme_qpair *  qpair 
)

Remove a disconnected spdk_nvme_qpair from a poll group.

Parameters
groupThe group from which to remove the qpair.
qpairThe qpair to remove from the poll group.

return 0 on success, -ENOENT if the qpair is not found in the group, -EINVAL if the qpair is not disconnected in the group, or -EPROTO on a protocol (transport) specific failure.

◆ 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_print_command()

void spdk_nvme_print_command ( uint16_t  qid,
struct spdk_nvme_cmd cmd 
)

Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).

Parameters
qidQueue identifier.
cmdPointer to the submission queue command to be formatted.

◆ spdk_nvme_print_completion()

void spdk_nvme_print_completion ( uint16_t  qid,
struct spdk_nvme_cpl cpl 
)

Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.

Parameters
qidQueue identifier.
cplPointer to the completion queue element to be formatted.

◆ 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)

Proceed with attaching controllers associated with the probe context.

The probe context is one returned from a previous call to spdk_nvme_probe_async(). Users must call this function on the probe context until it returns 0.

If any controllers fail to attach, there is no explicit notification. Users can detect attachment failure by comparing attach_cb invocations with the number of times where the user returned true for the probe_cb.

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.

◆ 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_get_failure_reason()

spdk_nvme_qp_failure_reason spdk_nvme_qpair_get_failure_reason ( struct spdk_nvme_qpair *  qpair)

Returns the reason the qpair is disconnected.

Parameters
qpairThe qpair to check.
Returns
a valid spdk_nvme_qp_failure_reason.

◆ spdk_nvme_qpair_get_id()

uint16_t spdk_nvme_qpair_get_id ( struct spdk_nvme_qpair *  qpair)

Gets the NVMe qpair ID for the specified qpair.

Parameters
qpairPointer to the NVMe queue pair.
Returns
ID for the specified qpair.

◆ spdk_nvme_qpair_get_num_outstanding_reqs()

uint32_t spdk_nvme_qpair_get_num_outstanding_reqs ( struct spdk_nvme_qpair *  qpair)

Gets the number of outstanding requests for the specified qpair.

This number is not decremented until after a request's callback function is completed.

This number is not matched necessarily to the number of NVMe commands submitted by the user. For example, nvme driver may split a request due to MDTS limitations, that will also allocate a request for the parent, etc.

Parameters
qpairPointer to the NVMe queue pair.
Returns
number of outstanding requests for the specified qpair.

◆ spdk_nvme_qpair_get_optimal_poll_group()

struct spdk_nvme_poll_group* spdk_nvme_qpair_get_optimal_poll_group ( struct spdk_nvme_qpair *  qpair)

Get a optimal poll group.

Parameters
qpairThe qpair to get the optimal poll group.
Returns
Pointer to the optimal poll group, or NULL if not found.

◆ spdk_nvme_qpair_is_connected()

bool spdk_nvme_qpair_is_connected ( struct spdk_nvme_qpair *  qpair)

Return the connection status of a given qpair.

Parameters
qpairThe qpair to check.
Returns
true if the qpair is connected, or false otherwise.

◆ spdk_nvme_qpair_print_command()

void spdk_nvme_qpair_print_command ( struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cmd cmd 
)

Prints (SPDK_NOTICELOG) the contents of an NVMe submission queue entry (command).

Parameters
qpairPointer to the NVMe queue pair - used to determine admin versus I/O queue.
cmdPointer to the submission queue command to be formatted.

◆ spdk_nvme_qpair_print_completion()

void spdk_nvme_qpair_print_completion ( struct spdk_nvme_qpair *  qpair,
struct spdk_nvme_cpl cpl 
)

Prints (SPDK_NOTICELOG) the contents of an NVMe completion queue entry.

Parameters
qpairPointer to the NVMe queue pair - presently unused.
cplPointer to the completion queue element to be formatted.

◆ 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. -ENXIO in the special case that the qpair is failed at the transport layer.

◆ 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_qpair_set_abort_dnr()

void spdk_nvme_qpair_set_abort_dnr ( struct spdk_nvme_qpair *  qpair,
bool  dnr 
)

Control if DNR is set or not for aborted commands.

The default value is false.

Parameters
qpairThe qpair to set.
dnrSet the DNR bit to 1 if true or 0 if false for aborted commands.

◆ spdk_nvme_rdma_init_hooks()

void spdk_nvme_rdma_init_hooks ( struct spdk_nvme_rdma_hooks hooks)

Set the global hooks for the RDMA transport, if necessary.

This call is optional and must be performed prior to probing for any devices. By default, the RDMA transport will use the ibverbs library to create protection domains and register memory. This is a mechanism to subvert that and use an existing registration.

This function may only be called one time per process.

Parameters
hooksfor initializing global hooks

◆ 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 or if SPDK_NVME_TRANSPORT_CUSTOM is supplied as trtype since it can represent multiple transports.

◆ spdk_nvme_transport_available_by_name()

bool spdk_nvme_transport_available_by_name ( const char *  transport_name)

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

Parameters
transport_nameName of the NVMe over Fabrics transport type to check.
Returns
true if transport_name is supported or false if it is not supported.

◆ spdk_nvme_transport_get_opts()

void spdk_nvme_transport_get_opts ( struct spdk_nvme_transport_opts opts,
size_t  opts_size 
)

Get the current NVMe transport options.

Parameters
[out]optsWill be filled with the current options for spdk_nvme_transport_set_opts().
opts_sizeMust be set to sizeof(struct spdk_nvme_transport_opts).

◆ 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 adrfam 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 transport 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 transport 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_populate_trstring()

int spdk_nvme_transport_id_populate_trstring ( struct spdk_nvme_transport_id trid,
const char *  trstring 
)

Parse the string representation of a transport ID transport type into the trid struct.

Parameters
tridThe trid to write to
trstringInput string representation of transport type (e.g. "PCIe", "RDMA").
Returns
0 if parsing was successful and trtype is filled out, or negated errno values if the provided string was an invalid transport string.

◆ 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.

◆ spdk_nvme_transport_register()

void spdk_nvme_transport_register ( const struct spdk_nvme_transport_ops ops)

Register the operations for a given transport type.

This function should be invoked by referencing the macro SPDK_NVME_TRANSPORT_REGISTER macro in the transport's .c file.

Parameters
opsThe operations associated with an NVMe-oF transport.

◆ spdk_nvme_transport_set_opts()

int spdk_nvme_transport_set_opts ( const struct spdk_nvme_transport_opts opts,
size_t  opts_size 
)

Set the NVMe transport options.

Parameters
optsPointer to the allocated spdk_nvme_transport_opts structure with new values.
opts_sizeMust be set to sizeof(struct spdk_nvme_transport_opts).
Returns
0 on success, or negated errno on failure.

◆ spdk_nvme_trid_populate_transport()

void spdk_nvme_trid_populate_transport ( struct spdk_nvme_transport_id trid,
enum spdk_nvme_transport_type  trtype 
)

Fill in the trtype and trstring fields of this trid based on a known transport type.

Parameters
tridThe trid to fill out.
trtypeThe transport type to use for filling the trid fields. Only valid for transport types referenced in the NVMe-oF spec.