API¶

This part of the documentation lists the full API reference of all public classes and functions.

ioctl.h

Linux NVMe ioctl interface functions

int libnvme_submit_admin_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd)¶: Submit an nvme passthrough admin command

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme admin command to send

Description

Uses LIBNVME_IOCTL_ADMIN_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field), or negative error code otherwise.

struct libnvme_passthru_completion¶: Async passthru completion record

Definition

struct libnvme_passthru_completion {
  struct libnvme_passthru_cmd *cmd;
  void *cookie;
  int status;
};

Members

cmd: Command that completed
cookie: User cookie provided to libnvme_submit_*_passthru_async()
status: Completion status (NVMe status or negative errno)

Description

Used for both admin and IO passthru command completions.

int libnvme_submit_admin_passthru_async(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, void *cookie)¶: Queue admin passthru command

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme admin command to send
void *cookie: User-defined opaque value returned at completion

Description

Queues cmd for asynchronous execution. Completion is reported via libnvme_reap_admin_passthru_async().

Return

0 on successful queueing, negative error code otherwise.

int libnvme_exec_admin_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd)¶: Submit an admin passthru command and wait

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme admin command to send

Description

Synchronous command execution.

Return

The nvme command status if a response was received (see enum nvme_status_field), or negative error code otherwise.

int libnvme_submit_io_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd)¶: Submit an nvme passthrough command

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme io command to send

Description

Uses LIBNVME_IOCTL_IO_CMD for the ioctl request.

Return

The nvme command status if a response was received (see enum nvme_status_field), or negative error code otherwise.

int libnvme_submit_io_passthru_async(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd, void *cookie)¶: Queue IO passthru command

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme IO command to send
void *cookie: User-defined opaque value returned at completion

Description

Queues cmd for asynchronous execution. Completion is reported via libnvme_reap_io_passthru_async().

Return

0 on successful queueing, negative error code otherwise.

int libnvme_exec_io_passthru(struct libnvme_transport_handle *hdl, struct libnvme_passthru_cmd *cmd)¶: Submit an IO passthru command and wait

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_cmd *cmd: The nvme IO command to send

Description

Synchronous command execution. Note: when io_uring is enabled, this shares the async queue. Avoid mixing this with direct async API usage on the same handle. For batching, use the async API exclusively.

Return

The nvme command status if a response was received (see enum nvme_status_field), or negative error code otherwise.

int libnvme_reap_passthru_async(struct libnvme_transport_handle *hdl, struct libnvme_passthru_completion *completion)¶: Reap one async completion

Parameters

struct libnvme_transport_handle *hdl: Transport handle
struct libnvme_passthru_completion *completion: Completion output structure

Description

Waits for one queued passthru command to complete and stores the completed command pointer, associated cookie, and completion status in completion.

Return

0 on success, negative error code otherwise.

int libnvme_wait_passthru(struct libnvme_transport_handle *hdl)¶: Wait for all pending passthru completions

Parameters

struct libnvme_transport_handle *hdl: Transport handle

Description

Drains all pending passthru commands from the async queue. Use this after batching multiple libnvme_submit_admin_passthru() calls when io_uring is enabled.

Return

0 on success, or the first non-zero status encountered.

int libnvme_reset_subsystem(struct libnvme_transport_handle *hdl)¶: Initiate a subsystem reset

Parameters

struct libnvme_transport_handle *hdl: Transport handle

Description

This should only be sent to controller handles, not to namespaces.

Return

Zero if a subsystem reset was initiated or negative error code otherwise.

int libnvme_reset_ctrl(struct libnvme_transport_handle *hdl)¶: Initiate a controller reset

Parameters

struct libnvme_transport_handle *hdl: Transport handle

Description

This should only be sent to controller handles, not to namespaces.

Return

0 if a reset was initiated or negative error code otherwise.

int libnvme_rescan_ns(struct libnvme_transport_handle *hdl)¶: Initiate a controller rescan

Parameters

struct libnvme_transport_handle *hdl: Transport handle

Description

This should only be sent to controller handles, not to namespaces.

Return

0 if a rescan was initiated or negative error code otherwise.

int libnvme_get_nsid(struct libnvme_transport_handle *hdl, __u32 *nsid)¶: Retrieve the NSID from a namespace file descriptor

Parameters

struct libnvme_transport_handle *hdl: Transport handle
__u32 *nsid: User pointer to namespace id

Description

This should only be sent to namespace handles, not to controllers. The kernel’s interface returns the nsid as the return value. This is unfortunate for many architectures that are incapable of allowing distinguishing a namespace id > 0x80000000 from a negative error number.

Return

0 if nsid was set successfully or negative error code otherwise.

int libnvme_update_block_size(struct libnvme_transport_handle *hdl, int block_size)¶: Update the block size

Parameters

struct libnvme_transport_handle *hdl: Transport handle
int block_size: New block size

Description

Notify the kernel blkdev to update its block size after a block size change. This should only be used for namespace handles, not controllers.

Return

0 if the block size was updated or a negative error code otherwise.

fabrics.h

Fabrics-specific definitions.

const char *libnvmf_trtype_str(__u8 trtype)¶: Decode TRTYPE field

Parameters

__u8 trtype: value to be decoded

Description

Decode the transport type field in the discovery log page entry.

Return

decoded string

const char *libnvmf_adrfam_str(__u8 adrfam)¶: Decode ADRFAM field

Parameters

__u8 adrfam: value to be decoded

Description

Decode the address family field in the discovery log page entry.

Return

decoded string

const char *libnvmf_subtype_str(__u8 subtype)¶: Decode SUBTYPE field

Parameters

__u8 subtype: value to be decoded

Description

Decode the subsystem type field in the discovery log page entry.

Return

decoded string

const char *libnvmf_treq_str(__u8 treq)¶: Decode TREQ field

Parameters

__u8 treq: value to be decoded

Description

Decode the transport requirements field in the discovery log page entry.

Return

decoded string

const char *libnvmf_eflags_str(__u16 eflags)¶: Decode EFLAGS field

Parameters

__u16 eflags: value to be decoded

Description

Decode the EFLAGS field in the discovery log page entry.

Return

decoded string

const char *libnvmf_sectype_str(__u8 sectype)¶: Decode SECTYPE field

Parameters

__u8 sectype: value to be decoded

Description

Decode the SECTYPE field in the discovery log page entry.

Return

decoded string

const char *libnvmf_prtype_str(__u8 prtype)¶: Decode RDMA Provider type field

Parameters

__u8 prtype: value to be decoded

Description

Decode the RDMA Provider type field in the discovery log page entry.

Return

decoded string

const char *libnvmf_qptype_str(__u8 qptype)¶: Decode RDMA QP Service type field

Parameters

__u8 qptype: value to be decoded

Description

Decode the RDMA QP Service type field in the discovery log page entry.

Return

decoded string

const char *libnvmf_cms_str(__u8 cms)¶: Decode RDMA connection management service field

Parameters

__u8 cms: value to be decoded

Description

Decode the RDMA connection management service field in the discovery log page entry.

Return

decoded string

int libnvmf_add_ctrl(libnvme_host_t h, libnvme_ctrl_t c)¶: Connect a controller and update topology

Parameters

libnvme_host_t h: Host to which the controller should be attached
libnvme_ctrl_t c: Controller to be connected

Description

Issues a ‘connect’ command to the NVMe-oF controller and inserts c into the topology using h as parent. c must be initialized and not connected to the topology.

Return

0 on success, negative error code otherwise.

int libnvmf_connect_ctrl(libnvme_ctrl_t c)¶: Connect a controller

Parameters

libnvme_ctrl_t c: Controller to be connected

Description

Issues a ‘connect’ command to the NVMe-oF controller. c must be initialized and not connected to the topology.

Return

0 on success, negative error code otherwise.

int libnvmf_get_discovery_log(libnvme_ctrl_t ctrl, const struct libnvmf_discovery_args *args, struct nvmf_discovery_log **logp)¶: Fetch the NVMe-oF discovery log page

Parameters

libnvme_ctrl_t ctrl: Discovery controller
const struct libnvmf_discovery_args *args: Optional arguments (pass NULL for defaults)
struct nvmf_discovery_log **logp: On success, set to the allocated log page (caller must free())

Description

Issues the three-phase Get Log Page protocol against ctrl, validates generation-counter atomicity, and normalises each log entry.

Return

0 on success, negative error code otherwise.

bool libnvmf_is_registration_supported(libnvme_ctrl_t c)¶: check whether registration can be performed.

Parameters

libnvme_ctrl_t c: Controller instance

Description

Only discovery controllers (DC) that comply with TP8010 support explicit registration with the DIM PDU. These can be identified by looking at the value of a dctype in the Identify command response. A value of 1 (DDC) or 2 (CDC) indicates that the DC supports explicit registration.

Return

true if controller supports explicit registration. false otherwise.

int libnvmf_register_ctrl(libnvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result)¶: Perform registration task with a DC

Parameters

libnvme_ctrl_t c: Controller instance
enum nvmf_dim_tas tas: Task field of the Command Dword 10 (cdw10). Indicates whether to perform a Registration, Deregistration, or Registration-update.
__u32 *result: The command-specific result returned by the DC upon command completion.

Description

Perform registration task with a Discovery Controller (DC). Three tasks are supported: register, deregister, and registration update.

Return

0 on success, negative error code otherwise.

int libnvmf_uri_parse(const char *str, struct libnvmf_uri **uri)¶: Parse the URI string

Parameters

const char *str: URI string
struct libnvmf_uri **uri: URI object to return

Description

Parse the URI string as defined in the NVM Express Boot Specification. Supported URI elements looks as follows:

nvme+tcp://user**host**:port/subsys_nqn/nid?query=val#fragment

Return

0 on success, negative error code otherwise.

void libnvmf_uri_free(struct libnvmf_uri *uri)¶: Free the URI structure

Parameters

struct libnvmf_uri *uri: libnvme_fabrics_uri structure

Description

Free an libnvmf_uri structure.

const char *libnvmf_get_default_trsvcid(const char *transport, bool discovery_ctrl)¶: Get default transport service ID

Parameters

const char *transport: Transport type string (e.g., “tcp”, “rdma”)
bool discovery_ctrl: True if for discovery controller, false otherwise

Description

Returns the default trsvcid (port) for the given transport and controller type.

Return

Allocated string with default trsvcid, or NULL on failure.

int libnvmf_context_create(struct libnvme_global_ctx *ctx, bool (*decide_retry)(struct libnvmf_context *fctx, int err, void *user_data), void (*connected)(struct libnvmf_context *fctx, struct libnvme_ctrl *c, void *user_data), void (*already_connected)(struct libnvmf_context *fctx, struct libnvme_host *host, const char *subsysnqn, const char *transport, const char *traddr, const char *trsvcid, void *user_data), void *user_data, struct libnvmf_context **fctxp)¶: Create a new fabrics context for discovery/connect

Parameters

struct libnvme_global_ctx *ctx: Global context
bool (*decide_retry)(struct libnvmf_context *fctx, int err, void *user_data): Hook to decide if a retry should be attempted
void (*connected)(struct libnvmf_context *fctx, struct libnvme_ctrl *c, void *user_data): Hook invoked when a connection is established
void (*already_connected)(struct libnvmf_context *fctx, struct libnvme_host *host, const char *subsysnqn, const char *transport, const char *traddr, const char *trsvcid, void *user_data): Hook invoked if already connected
void *user_data: User data passed to hooks
struct libnvmf_context **fctxp: Pointer to store the created context

Description

Allocates and initializes a new fabrics context for discovery/connect operations.

Return

0 on success, negative error code otherwise.

void libnvmf_context_free(struct libnvmf_context *fctx)¶: Free a fabrics context

Parameters

struct libnvmf_context *fctx: Fabrics context to free

Description

Releases all resources associated with fctx. The context must have been previously created with libnvmf_context_create().

After this call, fctx must not be used.

int libnvmf_context_set_discovery_hooks(struct libnvmf_context *fctx, void (*discovery_log)(struct libnvmf_context *fctx, bool connect, struct nvmf_discovery_log *log, uint64_t numrec, void *user_data), int (*parser_init)(struct libnvmf_context *fctx, void *user_data), void (*parser_cleanup)(struct libnvmf_context *fctx, void *user_data), int (*parser_next_line)(struct libnvmf_context *fctx, void *user_data))¶: Set discovery hooks for context

Parameters

struct libnvmf_context *fctx: Fabrics context
void (*discovery_log)(struct libnvmf_context *fctx, bool connect, struct nvmf_discovery_log *log, uint64_t numrec, void *user_data): Hook for discovery log events
int (*parser_init)(struct libnvmf_context *fctx, void *user_data): Hook to initialize parser
void (*parser_cleanup)(struct libnvmf_context *fctx, void *user_data): Hook to cleanup parser
int (*parser_next_line)(struct libnvmf_context *fctx, void *user_data): Hook to parse next line

Description

Sets the hooks used during discovery operations for the given context.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_connection(struct libnvmf_context *fctx, const char *subsysnqn, const char *transport, const char *traddr, const char *trsvcid, const char *host_traddr, const char *host_iface)¶: Set connection parameters for context

Parameters

struct libnvmf_context *fctx: Fabrics context
const char *subsysnqn: Subsystem NQN
const char *transport: Transport type
const char *traddr: Transport address
const char *trsvcid: Transport service ID
const char *host_traddr: Host transport address
const char *host_iface: Host interface

Description

Sets the connection parameters for the context.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_hostnqn(struct libnvmf_context *fctx, const char *hostnqn, const char *hostid)¶: Set host NQN and host ID for context

Parameters

struct libnvmf_context *fctx: Fabrics context
const char *hostnqn: Host NQN
const char *hostid: Host identifier

Description

Sets the host NQN and host ID for the context.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_crypto(struct libnvmf_context *fctx, const char *hostkey, const char *ctrlkey, const char *keyring, const char *tls_key, const char *tls_key_identity)¶: Set cryptographic parameters for context

Parameters

struct libnvmf_context *fctx: Fabrics context
const char *hostkey: Host key
const char *ctrlkey: Controller key
const char *keyring: Keyring identifier
const char *tls_key: TLS key
const char *tls_key_identity: TLS key identity

Description

Sets cryptographic and TLS parameters for the context.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_device(struct libnvmf_context *fctx, const char *device)¶: Set device for context

Parameters

struct libnvmf_context *fctx: Fabrics context
const char *device: Device path or identifier

Description

Sets the device to be used by the context.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_io_queues(struct libnvmf_context *fctx, int nr_io_queues, int nr_write_queues, int nr_poll_queues, int queue_size, bool disable_sqflow)¶: Set I/O queue topology for context

Parameters

struct libnvmf_context *fctx: Fabrics context
int nr_io_queues: Number of I/O queues
int nr_write_queues: Number of write-only queues
int nr_poll_queues: Number of polling queues
int queue_size: Number of entries per I/O queue (SQSIZE in Connect command)
bool disable_sqflow: Disable SQ flow control negotiation

Description

Convenience setter for the five parameters that together define the I/O queue structure used when establishing a controller connection. All five feed directly into the Connect command at queue creation time. nr_write_queues and nr_poll_queues are additive: total I/O queues is nr_io_queues + nr_write_queues + nr_poll_queues.

Individual libnvmf_context_set_nr_io_queues(), _set_nr_write_queues(), _set_nr_poll_queues(), _set_queue_size(), and _set_disable_sqflow() accessors are also available when only a subset needs to change.

Return

0 on success, negative error code otherwise.

int libnvmf_context_set_reconnect_policy(struct libnvmf_context *fctx, int ctrl_loss_tmo, int reconnect_delay, int fast_io_fail_tmo)¶: Set reconnect policy for context

Parameters

struct libnvmf_context *fctx: Fabrics context
int ctrl_loss_tmo: Controller loss timeout in seconds; negative means retry indefinitely
int reconnect_delay: Delay between reconnect attempts in seconds
int fast_io_fail_tmo: Fast I/O fail timeout in seconds; negative disables it; must not exceed ctrl_loss_tmo

Description

Convenience setter for the three coupled reconnect policy parameters. ctrl_loss_tmo and reconnect_delay are coupled: the kernel derives the maximum reconnect attempt count from their ratio. fast_io_fail_tmo controls how quickly outstanding I/O is failed while reconnection is in progress.

Individual libnvmf_context_set_ctrl_loss_tmo(), _set_reconnect_delay(), and _set_fast_io_fail_tmo() accessors are also available when only a subset needs to change.

Return

0 on success, negative error code otherwise.

int libnvmf_discovery(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force)¶: Perform fabrics discovery

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context
bool connect: Whether to connect discovered subsystems
bool force: Force discovery even if already connected

Description

Performs discovery for fabrics subsystems and optionally connects.

Return

0 on success, negative error code otherwise.

int libnvmf_discovery_config_json(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force)¶: Perform discovery using JSON config

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context
bool connect: Whether to connect discovered subsystems
bool force: Force discovery even if already connected

Description

Performs discovery using a JSON configuration.

Return

0 on success, negative error code otherwise.

int libnvmf_discovery_config_file(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, bool force)¶: Perform discovery using config file

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context
bool connect: Whether to connect discovered subsystems
bool force: Force discovery even if already connected

Description

Performs discovery using a configuration file.

Return

0 on success, negative error code otherwise.

int libnvmf_discovery_nbft(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, bool connect, char *nbft_path)¶: Perform discovery using NBFT

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context
bool connect: Whether to connect discovered subsystems
char *nbft_path: Path to NBFT file

Description

Performs discovery using the specified NBFT file.

Return

0 on success, negative error code otherwise.

int libnvmf_create_ctrl(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx, libnvme_ctrl_t *c)¶: Allocate an unconnected NVMe controller

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
struct libnvmf_context *fctx: Fabrics context
libnvme_ctrl_t *c: libnvme_ctrl_t object to return

Description

Creates an unconnected controller to be used for libnvme_add_ctrl().

Return

0 on success, negative error code otherwise.

int libnvmf_connect(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx)¶: Connect to fabrics subsystem

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context

Description

Connects to the fabrics subsystem using the provided context.

Return

0 on success, negative error code otherwise.

int libnvmf_disconnect_ctrl(libnvme_ctrl_t c)¶: Disconnect a controller

Parameters

libnvme_ctrl_t c: Controller instance

Description

Issues a ‘disconnect’ fabrics command to c

Return

0 on success, -1 on failure.

int libnvmf_connect_config_json(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx)¶: Connect using JSON config

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context

Description

Connects to the fabrics subsystem using a JSON configuration.

Return

0 on success, negative error code otherwise.

int libnvmf_config_modify(struct libnvme_global_ctx *ctx, struct libnvmf_context *fctx)¶: Modify and update the configurtion

Parameters

struct libnvme_global_ctx *ctx: Global context
struct libnvmf_context *fctx: Fabrics context

Description

Update the current configuration by adding the crypto information.

Return

0 on success, negative error code otherwise.

int libnvmf_nbft_read_files(struct libnvme_global_ctx *ctx, char *path, struct nbft_file_entry **head)¶: Read NBFT files from path

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
char *path: Path to NBFT files
struct nbft_file_entry **head: Pointer to store linked list of NBFT file entries

Description

Reads NBFT files from the specified path and populates a linked list.

Return

0 on success, negative error code otherwise.

void libnvmf_nbft_free(struct libnvme_global_ctx *ctx, struct nbft_file_entry *head)¶: Free NBFT file entry list

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
struct nbft_file_entry *head: Head of the NBFT file entry list

Description

Frees all memory associated with the NBFT file entry list.

linux.h

linux-specific utility functions

enum libnvme_hmac_alg¶: HMAC algorithm

Constants

LIBNVME_HMAC_ALG_NONE: No HMAC algorithm
LIBNVME_HMAC_ALG_SHA2_256: SHA2-256
LIBNVME_HMAC_ALG_SHA2_384: SHA2-384
LIBNVME_HMAC_ALG_SHA2_512: SHA2-512

int libnvme_gen_dhchap_key(struct libnvme_global_ctx *ctx, char *hostnqn, enum libnvme_hmac_alg hmac, unsigned int key_len, unsigned char *secret, unsigned char *key)¶: DH-HMAC-CHAP key generation

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
char *hostnqn: Host NVMe Qualified Name
enum libnvme_hmac_alg hmac: HMAC algorithm
unsigned int key_len: Output key length
unsigned char *secret: Secret to used for digest
unsigned char *key: Generated DH-HMAC-CHAP key

Return

If key generation was successful the function returns 0 or a negative error code otherwise.

int libnvme_lookup_keyring(struct libnvme_global_ctx *ctx, const char *keyring, long *key)¶: Lookup keyring serial number

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring name
long *key: Key serial number to return

Description

Looks up the serial number of the keyring keyring.

Return

0 on success, negative error code otherwise.

char *libnvme_describe_key_serial(struct libnvme_global_ctx *ctx, long key_id)¶: Return key description

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long key_id: Key serial number

Description

Fetches the description of the key or keyring identified by the serial number key_id.

Return

The description of key_id or NULL on failure. The returned string needs to be freed by the caller.

int libnvme_lookup_key(struct libnvme_global_ctx *ctx, const char *type, const char *identity, long *key)¶: Lookup key serial number

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *type: Key type
const char *identity: Key description
long *key: Key serial number to return

Description

Looks up the serial number of the key identity with type type in the current session keyring.

Return

0 on success, negative error code otherwise.

int libnvme_set_keyring(struct libnvme_global_ctx *ctx, long keyring_id)¶: Link keyring for lookup

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Keyring id

Description

Links keyring_id into the session keyring such that its keys are available for further key lookups.

Return

0 on success, negative error code otherwise.

int libnvme_create_raw_secret(struct libnvme_global_ctx *ctx, const char *secret, size_t key_len, unsigned char **raw_secret)¶: Generate a raw secret buffer from input data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *secret: Input secret data
size_t key_len: The length of the raw_secret in bytes
unsigned char **raw_secret: Return buffer with the generated raw secret

Description

Transforms the provided secret into a raw secret buffer suitable for use with NVMe key management operations.

The generated raw secret can subsequently be passed to libnvme_read_key() or libnvme_update_key().

Return

0 on success, negative error code otherwise.

int libnvme_read_key(struct libnvme_global_ctx *ctx, long keyring_id, long key_id, int *len, unsigned char **key)¶: Read key raw data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Id of the keyring holding key_id
long key_id: Key id
int *len: Length of the returned data
unsigned char **key: Key serial to return

Description

Links the keyring specified by keyring_id into the session keyring and reads the payload of the key specified by key_id. len holds the size of the returned buffer. If keyring is 0 the default keyring ‘.nvme’ is used.

Return

0 on success, negative error code otherwise.

int libnvme_update_key(struct libnvme_global_ctx *ctx, long keyring_id, const char *key_type, const char *identity, unsigned char *key_data, int key_len, long *key)¶: Update key raw data

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring_id: Id of the keyring holding key_id
const char *key_type: Type of the key to insert
const char *identity: Key identity string
unsigned char *key_data: Raw data of the key
int key_len: Length of key_data
long *key: Key serial to return

Description

Links the keyring specified by keyring_id into the session keyring and updates the key reference by identity with key_data. The old key with identity identity will be revoked to make it inaccessible.

Return

0 on success, negative error code otherwise.

libnvme_scan_tls_keys_cb_t¶: Typedef: Callback for iterating TLS keys

Syntax

void libnvme_scan_tls_keys_cb_t (struct libnvme_global_ctx *ctx, long keyring, long key, char *desc, int desc_len, void *data)

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
long keyring: Keyring which has been iterated
long key: Key for which the callback has been invoked
char *desc: Description of the key
int desc_len: Length of desc
void *data: Pointer for caller data

Description

Called for each TLS PSK in the keyring.

int libnvme_scan_tls_keys(struct libnvme_global_ctx *ctx, const char *keyring, libnvme_scan_tls_keys_cb_t cb, void *data)¶: Iterate over TLS keys in a keyring

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring holding TLS keys
libnvme_scan_tls_keys_cb_t cb: Callback function
void *data: Pointer for data to be passed to cb

Description

Iterates keyring and call cb for each TLS key. When keyring is NULL the default ‘.nvme’ keyring is used. A TLS key must be of type ‘psk’ and the description must be of the form ‘NVMe<0|1><R|G>0<1|2> <identity>’, otherwise it will be skipped during iteration.

Return

Number of keys for which cb was called, or negative error code

int libnvme_insert_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int hmac, unsigned char *configured_key, int key_len, long *key)¶: Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a and stores it as type key_type in the keyring specified by keyring.

Return

0 on success, negative error code otherwise.

int libnvme_insert_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, long *key)¶: Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring.

Return

0 on success, negative error code otherwise.

int libnvme_insert_tls_key_compat(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, long *key)¶: Derive and insert TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the resulting key
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
long *key: Key serial to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP 1.0a (if version s set to ‘0’) or NVMe TP8028 (if version is set to ‘1) and stores it as type key_type in the keyring specified by keyring. This version differs from libnvme_insert_tls_key_versioned() in that it uses the original implementation for HKDF Expand-Label which does not prefix the ‘info’ and ‘label’ strings with the length.

Return

The key serial number if the key could be inserted into the keyring or 0 with errno otherwise.

int libnvme_generate_tls_key_identity(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, char **identity)¶: Generate the TLS key identity

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
char **identity: TLS identity to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_generate_tls_key_identity_compat(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len, char **identity)¶: Generate the TLS key identity

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn: Host NVMe Qualified Name
const char *subsysnqn: Subsystem NVMe Qualified Name
int version: Key version to use
int hmac: HMAC algorithm
unsigned char *configured_key: Configured key data to derive the key from
int key_len: Length of configured_key
char **identity: TLS identity to return

Description

Derives a ‘retained’ TLS key as specified in NVMe TCP and generate the corresponding TLs identity. This version differs from libnvme_generate_tls_key_identity() in that it uses the original implementation for HKDF-Expand-Label which does not prefix the ‘info’ and ‘label’ string with the length.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_revoke_tls_key(struct libnvme_global_ctx *ctx, const char *keyring, const char *key_type, const char *identity)¶: Revoke TLS key from keyring

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *keyring: Keyring to use
const char *key_type: Type of the key to revoke
const char *identity: Key identity string

Return

0 on success, negative error code otherwise.

int libnvme_export_tls_key(struct libnvme_global_ctx *ctx, const unsigned char *key_data, int key_len, char **identity)¶: Export a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const unsigned char *key_data: Raw data of the key
int key_len: Length of key_data
char **identity: TLS identity

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_export_tls_key_versioned(struct libnvme_global_ctx *ctx, unsigned char version, unsigned char hmac, const unsigned char *key_data, size_t key_len, char **identity)¶: Export a TLS pre-shared key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
unsigned char version: Indicated the representation of the TLS PSK
unsigned char hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
const unsigned char *key_data: Raw data of the key
size_t key_len: Length of key_data
char **identity: TLS identity to return

Description

Returns key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_import_tls_key(struct libnvme_global_ctx *ctx, const char *encoded_key, int *key_len, unsigned int *hmac, unsigned char **key)¶: Import a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *encoded_key: TLS key in PSK interchange format
int *key_len: Length of the resulting key data
unsigned int *hmac: HMAC algorithm
unsigned char **key: Key serial to return

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

int libnvme_import_tls_key_versioned(struct libnvme_global_ctx *ctx, const char *encoded_key, unsigned char *version, unsigned char *hmac, size_t *key_len, unsigned char **key)¶: Import a TLS key

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *encoded_key: TLS key in PSK interchange format
unsigned char *version: Indicated the representation of the TLS PSK
unsigned char *hmac: HMAC algorithm used to transfor the configured PSK in a retained PSK
size_t *key_len: Length of the resulting key data
unsigned char **key: Key serial to return

Description

Imports key_data in the PSK Interchange format as defined in section 3.6.1.5 of the NVMe TCP Transport specification.

It is the responsibility of the caller to free the returned string.

Return

0 on success, negative error code otherwise.

char *libnvme_generate_hostnqn(void)¶: Generate a machine specific host nqn

Parameters

void: no arguments

Return

An nvm namespace qualified name string based on the machine identifier, or NULL if not successful.

char *libnvme_generate_hostnqn_from_hostid(char *hostid)¶: Generate a host nqn from host identifier

Parameters

char *hostid: Host identifier

Description

If hostid is NULL, the function generates it based on the machine identifier.

Return

On success, an NVMe Qualified Name for host identification. This name is based on the given host identifier. On failure, NULL.

char *libnvme_generate_hostid(void)¶: Generate a machine specific host identifier

Parameters

void: no arguments

Return

On success, an identifier string based on the machine identifier to be used as NVMe Host Identifier, or NULL on failure.

char *libnvme_read_hostnqn(void)¶: Reads the host nvm qualified name from the config default location

Parameters

void: no arguments

Description

Retrieve the qualified name from the config file located in $SYSCONFDIR/nvme. $SYSCONFDIR is usually /etc.

Return

The host nqn, or NULL if unsuccessful. If found, the caller is responsible to free the string.

char *libnvme_read_hostid(void)¶: Reads the host identifier from the config default location

Parameters

void: no arguments

Description

Retrieve the host idenditifer from the config file located in $SYSCONFDIR/nvme/. $SYSCONFDIR is usually /etc.

Return

The host identifier, or NULL if unsuccessful. If found, the caller: is responsible to free the string.

mi.h - NVMe Management Interface library (libnvme-mi) definitions.

These provide an abstraction for the MI messaging between controllers and a host, typically over an MCTP-over-i2c link to a NVMe device, used as part of the out-of-band management of a system.

We have a few data structures define here to reflect the topology of a MI connection with an NVMe subsystem:

libnvme_mi_ep_t: an MI endpoint - our mechanism of communication with a NVMe subsystem. For MCTP, an endpoint will be the component that holds the MCTP address (EID), and receives our request message.

endpoints are defined in the NVMe-MI spec, and are specific to the MI interface.

Each endpoint will provide access to one or more of:

libnvme_mi_ctrl_t: a NVMe controller, as defined by the NVMe base spec. The controllers are responsible for processing any NVMe standard commands (eg, the Admin command set). An endpoint (libnvme_mi_ep_t) may provide access to multiple controllers - so each of the controller- type commands will require a libnvme_mi_ctrl_t to be specified, rather than an endpoint

A couple of conventions with the libnvme-mi API:

All types and functions have the libnvme_mi prefix, to distinguish from the libnvme core.

We currently support either MI commands and Admin commands. The former adds a _mi prefix, the latter an _admin prefix. [This does result in the MI functions having a double _mi, like libnvme_mi_mi_subsystem_health_status_poll, which is apparently amusing for our German-speaking readers]

For return values: unless specified in the per-function documentation, all functions:

return 0 on success

return -1, with errno set, for errors communicating with the MI device, either in request or response data

return >1 on MI status errors. This value is the 8-bit MI status value, represented by enum nvme_mi_resp_status. Note that the status values may be vendor-defined above 0xe0.

For the second case, we have a few conventions for errno values:

EPROTO: response data violated the MI protocol, and libnvme cannot validly interpret the response

EIO: Other I/O error communicating with device (eg., valid but unexpected response data)

EINVAL: invalid input arguments for a command

In line with the core NVMe API, the Admin command functions take an _args structure to provide the command-specific parameters. However, for the MI interface, the fd and timeout members of these _args structs are ignored.

References to the specifications here will either to be the NVM Express Management Interface (“NVMe-MI”) or the NVM Express Base specification (“NVMe”). At the time of writing, the versions we’re referencing here are:

NVMe-MI 1.2b

NVMe 2.0b

with a couple of accommodations for older spec types, particularly NVMe-MI 1.1, where possible.

const char *libnvme_mi_status_to_string(int status)¶: return a string representation of the MI status.

Parameters

int status: MI response status

Description

Gives a string description of status, as per section 4.1.2 of the NVMe-MI spec. The status value should be of type NVME_STATUS_MI, and extracted from the return value using nvme_status_get_value().

Returned string is const, and should not be free()ed.

Return

A string representing the status value

type libnvme_mi_ep_t¶: MI Endpoint object.

Description

Represents our communication endpoint on the remote MI-capable device. To be used for direct MI commands for the endpoint (through the libnvme_mi_mi_* functions(), or to communicate with individual controllers (see libnvme_mi_init_ctrl).

Endpoints are created through a transport-specific constructor; currently only MCTP-connected endpoints are supported, through libnvme_mi_open_mctp. Subsequent operations on the endpoint (and related controllers) are transport-independent.

int libnvme_mi_set_csi(libnvme_mi_ep_t ep, uint8_t csi)¶: Assign a CSI to an endpoint.

Parameters

libnvme_mi_ep_t ep: Endpoint
uint8_t csi: value to use for CSI bit in NMP (0 or 1) for this endpoint

Return

0 if successful, -1 otherwise (some endpoints may not support)

libnvme_mi_ep_t libnvme_mi_first_endpoint(struct libnvme_global_ctx *ctx)¶: Start endpoint iterator

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Return

first MI endpoint object under this root, or NULL if no endpoints: are present.

Description

See: libnvme_mi_next_endpoint, libnvme_mi_for_each_endpoint

libnvme_mi_ep_t libnvme_mi_next_endpoint(struct libnvme_global_ctx *ctx, libnvme_mi_ep_t e)¶: Continue endpoint iterator

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
libnvme_mi_ep_t e: libnvme_mi_ep_t current position of iterator

Return

next endpoint MI endpoint object after e under this root, or NULL: if no further endpoints are present.

Description

See: libnvme_mi_first_endpoint, libnvme_mi_for_each_endpoint

libnvme_mi_for_each_endpoint¶

libnvme_mi_for_each_endpoint (c, e)

Iterator for NVMe-MI endpoints.

Parameters

c: struct libnvme_global_ctx object
e: libnvme_mi_ep_t object, set on each iteration

libnvme_mi_for_each_endpoint_safe¶

libnvme_mi_for_each_endpoint_safe (c, e, _e)

Iterator for NVMe-MI endpoints, allowing deletion during traversal

Parameters

c: struct libnvme_global_ctx object
e: libnvme_mi_ep_t object, set on each iteration
_e: libnvme_mi_ep_t object used as temporary storage

int libnvme_mi_ep_set_timeout(libnvme_mi_ep_t ep, unsigned int timeout_ms)¶: set a timeout for NVMe-MI responses

Parameters

libnvme_mi_ep_t ep: MI endpoint object
unsigned int timeout_ms: Timeout for MI responses, given in milliseconds

void libnvme_mi_ep_set_mprt_max(libnvme_mi_ep_t ep, unsigned int mprt_max_ms)¶: set the maximum wait time for a More Processing Required response

Parameters

libnvme_mi_ep_t ep: MI endpoint object
unsigned int mprt_max_ms: Maximum more processing required wait time

Description

NVMe-MI endpoints may respond to a request with a “More Processing Required” response; this also includes a hint on the worst-case processing time for the eventual response data, with a specification-defined maximum of 65.535 seconds.

This function provides a way to limit the maximum time we’re prepared to wait for the final response. Specify zero in mprt_max_ms for no limit. This should be larger than the command/response timeout set in :c:type:`libnvme_mi_ep_set_timeout`().

unsigned int libnvme_mi_ep_get_timeout(libnvme_mi_ep_t ep)¶: get the current timeout value for NVMe-MI responses

Parameters

libnvme_mi_ep_t ep: MI endpoint object

Description

Returns the current timeout value, in milliseconds, for this endpoint.

struct libnvme_transport_handle *libnvme_mi_first_transport_handle(libnvme_mi_ep_t ep)¶: Start transport handle iterator

Parameters

libnvme_mi_ep_t ep: libnvme_mi_ep_t object

Return

first transport handle to a MI controller object under this: root, or NULL if no controllers are present.

Description

See: libnvme_mi_next_transport_handle, libnvme_mi_for_each_transport_handle

struct libnvme_transport_handle *libnvme_mi_next_transport_handle(libnvme_mi_ep_t ep, struct libnvme_transport_handle *hdl)¶: Continue transport handle iterator

Parameters

libnvme_mi_ep_t ep: libnvme_mi_ep_t object
struct libnvme_transport_handle *hdl: nvme_transport_handle current position of iterator

Return

next transport handle to MI controller object after c under: this endpoint, or NULL if no further controllers are present.

Description

See: libnvme_mi_first_transport_handle, libnvme_mi_for_each_transport_handle

libnvme_mi_for_each_transport_handle¶

libnvme_mi_for_each_transport_handle (ep, hdl)

Iterator for transport handle to NVMe-MI controllers.

Parameters

ep: libnvme_mi_ep_t containing endpoints
hdl: nvme_trasnport_handle object, set on each iteration

Description

Allows iteration of the list of controllers behind an endpoint. Unless the controllers have already been created explicitly, you’ll probably want to call :c:type:`libnvme_mi_scan_ep`() to scan for the controllers first.

See: :c:type:`libnvme_mi_scan_ep`()

libnvme_mi_for_each_transport_handle_safe¶

libnvme_mi_for_each_transport_handle_safe (ep, hdl, _hdl)

Iterator for transport handle to NVMe-MI controllers, allowing deletion during traversal

Parameters

ep: libnvme_mi_ep_t containing controllers
hdl: nvme_transport_handle object, set on each iteration
_hdl: nvme_transport_handle object used as temporary storage

Description

Allows iteration of the list of controllers behind an endpoint, safe against deletion during iteration. Unless the controllers have already been created explicitly (or you’re just iterating to destroy controllers) you’ll probably want to call :c:type:`libnvme_mi_scan_ep`() to scan for the controllers first.

See: :c:type:`libnvme_mi_scan_ep`()

libnvme_mi_ep_t libnvme_mi_open_mctp(struct libnvme_global_ctx *ctx, unsigned int netid, uint8_t eid)¶: Create an endpoint using a MCTP connection.

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
unsigned int netid: MCTP network ID on this system
uint8_t eid: MCTP endpoint ID

Description

Transport-specific endpoint initialization for MI-connected endpoints. Once an endpoint is created, the rest of the API is transport-independent.

See libnvme_mi_close

Return

New endpoint object for netid & eid, or NULL on failure.

int libnvme_mi_aem_open(libnvme_mi_ep_t ep)¶: Prepare an existing endpoint to receive AEMs

Parameters

libnvme_mi_ep_t ep: Endpoint to configure for AEMs

Return

0 if success, -1 otherwise

void libnvme_mi_close(libnvme_mi_ep_t ep)¶: Close an endpoint connection and release resources, including controller objects.

Parameters

libnvme_mi_ep_t ep: Endpoint object to close

struct libnvme_global_ctx *libnvme_mi_scan_mctp(void)¶: look for MCTP-connected NVMe-MI endpoints.

Parameters

void: no arguments

Description

This function queries the system MCTP daemon (“mctpd”) over D-Bus, to find MCTP endpoints that report support for NVMe-MI over MCTP.

This requires libvnme-mi to be compiled with D-Bus support; if not, this will return NULL.

Return

A struct libnvme_global_ctx populated with a set of: MCTP-connected endpoints, or NULL on failure

int libnvme_mi_scan_ep(libnvme_mi_ep_t ep, bool force_rescan)¶: query an endpoint for its NVMe controllers.

Parameters

libnvme_mi_ep_t ep: Endpoint to scan
bool force_rescan: close existing controllers and rescan

Description

This function queries an MI endpoint for the controllers available, by performing an MI Read MI Data Structure command (requesting the controller list). The controllers are stored in the endpoint’s internal list, and can be iterated with libnvme_mi_for_each_ctrl.

This will only scan the endpoint once, unless force_rescan is set. If so, all existing controller objects will be freed - the caller must not hold a reference to those across this call.

See: libnvme_mi_for_each_ctrl

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

struct libnvme_transport_handle *libnvme_mi_init_transport_handle(libnvme_mi_ep_t ep, __u16 ctrl_id)¶: initialise a transport handle to NVMe controller.

Parameters

libnvme_mi_ep_t ep: Endpoint to create under
__u16 ctrl_id: ID of controller to initialize.

Description

Create a connection to a controller behind the endpoint specified in ep. Controller IDs may be queried from the endpoint through libnvme_mi_mi_read_mi_data_ctrl_list.

See libnvme_mi_close_transport_handle

Return

New transport handle object, or NULL on failure.

__u16 libnvme_mi_ctrl_id(struct libnvme_transport_handle *hdl)¶: get the ID of a controller

Parameters

struct libnvme_transport_handle *hdl: transport handle to controller to query

Description

Retrieve the ID of the controller, as defined by hardware, and available in the Identify (Controller List) data. This is the value passed to libnvme_mi_init_transport_handle, but may have been created internally via libnvme_mi_scan_ep.

Return

the (locally-stored) ID of this controller.

char *libnvme_mi_endpoint_desc(libnvme_mi_ep_t ep)¶: Get a string describing a MI endpoint.

Parameters

libnvme_mi_ep_t ep: endpoint to describe

Description

Generates a human-readable string describing the endpoint, with possibly transport-specific data. The string is allocated during the call, and the caller is responsible for free()-ing the string.

Return

a newly-allocated string containing the endpoint description, or: NULL on failure.

void libnvme_mi_ep_set_submit_entry(libnvme_mi_ep_t ep, void *(*mi_submit_entry)(struct libnvme_mi_ep *ep, __u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len))¶: Install MI submit-entry callback

Parameters

libnvme_mi_ep_t ep: endpoint to configure
void *(*mi_submit_entry)(struct libnvme_mi_ep *ep, __u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len): After input validation the callback is invoked before an MI command is submitted. The function receives the endpoint, message type, header, and data about to be sent, and may return an opaque pointer representing per-command context. This pointer is later passed unmodified to the mi_submit_exit callback. Implementations typically use this hook for logging, tracing, or allocating per-command state.

Description

Installs a callback invoked at the moment an MI command enters the submission path. This applies to all MI operations through this endpoint (both endpoint- level MI commands and controller admin commands). Passing NULL removes any previously installed callback.

void libnvme_mi_ep_set_submit_exit(libnvme_mi_ep_t ep, void (*mi_submit_exit)(struct libnvme_mi_ep *ep, __u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len, void *user_data))¶: Install MI submit-exit callback

Parameters

libnvme_mi_ep_t ep: endpoint to configure
void (*mi_submit_exit)(struct libnvme_mi_ep *ep, __u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len, void *user_data): Callback invoked after an MI command completes callback (i.e., after a response has been received and passed basic validation). The function receives the endpoint, message type, header, data, and the user_data pointer returned earlier by the mi_submit_entry callback. Implementations typically use this hook for logging, tracing, or freeing per-command state.

Description

Installs a callback invoked when an MI command completes. This applies to all MI operations through this endpoint. Passing NULL removes any previously installed callback.

int libnvme_mi_mi_xfer(libnvme_mi_ep_t ep, struct nvme_mi_mi_req_hdr *mi_req, size_t req_data_size, struct nvme_mi_mi_resp_hdr *mi_resp, size_t *resp_data_size)¶: Raw mi transfer interface.

Parameters

libnvme_mi_ep_t ep: endpoint to send the MI command to
struct nvme_mi_mi_req_hdr *mi_req: request data
size_t req_data_size: size of request data payload
struct nvme_mi_mi_resp_hdr *mi_resp: buffer for response data
size_t *resp_data_size: size of response data buffer, updated to received size

Description

Performs an arbitrary NVMe MI command, using the provided request data, in mi_req. The size of the request data payload is specified in req_data_size - this does not include the standard header length (so a header-only request would have a size of 0). Note that the Management Request Doublewords are considered part of the header data.

On success, response data is stored in mi_resp, which has an optional appended payload buffer of resp_data_size bytes. The actual payload size transferred will be stored in resp_data_size. This size does not include the MI response header, so 0 represents no payload.

See: struct nvme_mi_mi_req_hdr and struct nvme_mi_mi_resp_hdr.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_read_mi_data_subsys(libnvme_mi_ep_t ep, struct nvme_mi_read_nvm_ss_info *s)¶: Perform a Read MI Data Structure command, retrieving subsystem data.

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
struct nvme_mi_read_nvm_ss_info *s: subsystem information to populate

Description

Retrieves the Subsystem information - number of external ports and NVMe version information. See struct nvme_mi_read_nvm_ss_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_read_mi_data_port(libnvme_mi_ep_t ep, __u8 portid, struct nvme_mi_read_port_info *p)¶: Perform a Read MI Data Structure command, retrieving port data.

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 portid: id of port data to retrieve
struct nvme_mi_read_port_info *p: port information to populate

Description

Retrieves the Port information, for the specified port ID. The subsystem data (from libnvme_mi_mi_read_mi_data_subsys) nmp field contains the allowed range of port IDs.

See struct nvme_mi_read_port_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_read_mi_data_ctrl_list(libnvme_mi_ep_t ep, __u8 start_ctrlid, struct nvme_ctrl_list *list)¶: Perform a Read MI Data Structure command, retrieving the list of attached controllers.

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 start_ctrlid: starting controller ID
struct nvme_ctrl_list *list: controller list to populate

Description

Retrieves the list of attached controllers, with IDs greater than or equal to start_ctrlid.

See struct nvme_ctrl_list.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_read_mi_data_ctrl(libnvme_mi_ep_t ep, __u16 ctrl_id, struct nvme_mi_read_ctrl_info *ctrl)¶: Perform a Read MI Data Structure command, retrieving controller information

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u16 ctrl_id: ID of controller to query
struct nvme_mi_read_ctrl_info *ctrl: controller data to populate

Description

Retrieves the Controller Information Data Structure for the attached controller with ID ctrlid.

See struct nvme_mi_read_ctrl_info.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_subsystem_health_status_poll(libnvme_mi_ep_t ep, bool clear, struct nvme_mi_nvm_ss_health_status *nshds)¶: Read the Subsystem Health Data Structure from the NVM subsystem

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
bool clear: flag to clear the Composite Controller Status state
struct nvme_mi_nvm_ss_health_status *nshds: subsystem health status data to populate

Description

Retrieves the Subsystem Health Data Structure into nshds. If clear is set, requests that the Composite Controller Status bits are cleared after the read. See NVMe-MI section 5.6 for details on the CCS bits.

See struct nvme_mi_nvm_ss_health_status.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_get(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1, __u32 *nmresp)¶: query a configuration parameter

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u32 dw0: management doubleword 0, containing configuration identifier, plus config-specific fields
__u32 dw1: management doubleword 0, config-specific.
__u32 *nmresp: set to queried configuration data in NMRESP field of response.

Description

Performs a MI Configuration Get command, with the configuration identifier as the LSB of dw0. Other dw0 and dw1 data is configuration-identifier specific.

On a successful Configuration Get, the nmresp pointer will be populated with the bytes from the 3-byte NMRESP field, converted to native endian.

See enum nvme_mi_config_id for identifiers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_set(libnvme_mi_ep_t ep, __u32 dw0, __u32 dw1)¶: set a configuration parameter

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u32 dw0: management doubleword 0, containing configuration identifier, plus config-specific fields
__u32 dw1: management doubleword 0, config-specific.

Description

Performs a MI Configuration Set command, with the command as the LSB of dw0. Other dw0 and dw1 data is configuration-identifier specific.

See enum nvme_mi_config_id for identifiers.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_get_smbus_freq(libnvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq *freq)¶: get configuration: SMBus port frequency

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to query
enum nvme_mi_config_smbus_freq *freq: output value for current frequency configuration

Description

Performs a MI Configuration Get, to query the current SMBus frequency of the port specified in port. On success, populates freq with the port frequency

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_set_smbus_freq(libnvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq freq)¶: set configuration: SMBus port frequency

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to set
enum nvme_mi_config_smbus_freq freq: new frequency configuration

Description

Performs a MI Configuration Set, to update the current SMBus frequency of the port specified in port.

See struct nvme_mi_read_port_info for the maximum supported SMBus frequency for the port.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_set_health_status_change(libnvme_mi_ep_t ep, __u32 mask)¶: clear CCS bits in health status

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u32 mask: bitmask to clear

Description

Performs a MI Configuration Set, to update the current health status poll values of the Composite Controller Status bits. Bits set in mask will be cleared from future health status poll data, and may be re-triggered by a future health change event.

See libnvme_mi_mi_subsystem_health_status_poll`(), :c:type:`enum nvme_mi_ccs for values in mask.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_get_mctp_mtu(libnvme_mi_ep_t ep, __u8 port, __u16 *mtu)¶: get configuration: MCTP MTU

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to query
__u16 *mtu: output value for current MCTP MTU configuration

Description

Performs a MI Configuration Get, to query the current MCTP Maximum Transmission Unit size (MTU) of the port specified in port. On success, populates mtu with the MTU.

The default reset value is 64, corresponding to the MCTP baseline MTU.

Some controllers may also use this as the maximum receive unit size, and may not accept MCTP messages larger than the configured MTU.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_set_mctp_mtu(libnvme_mi_ep_t ep, __u8 port, __u16 mtu)¶: set configuration: MCTP MTU

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 port: port ID to set
__u16 mtu: new MTU configuration

Description

Performs a MI Configuration Set, to update the current MCTP MTU value for the port specified in port.

Some controllers may also use this as the maximum receive unit size, and may not accept MCTP messages larger than the configured MTU. When setting this value, you will likely need to change the MTU of the local MCTP interface(s) to match.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_get_async_event(libnvme_mi_ep_t ep, __u8 *aeelver, struct nvme_mi_aem_supported_list *list, size_t *list_num_bytes)¶: get configuration: Asynchronous Event

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 *aeelver: Asynchronous Event Enable List Version Number
struct nvme_mi_aem_supported_list *list: AE Supported list header and list contents
size_t *list_num_bytes: number of bytes in the list header and contents buffer. This will be populated with returned size of list and contents if successful.

Description

Performs a MI Configuration Get, to query the current enable Asynchronous Events. On success, populates aeelver and the list with current info,

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_mi_config_set_async_event(libnvme_mi_ep_t ep, bool envfa, bool empfa, bool encfa, __u8 aemd, __u8 aerd, struct nvme_mi_aem_enable_list *enable_list, size_t enable_list_size, struct nvme_mi_aem_occ_list_hdr *occ_list, size_t *occ_list_size)¶: set configuration: Asynchronous Event

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
bool envfa: Enable SR-IOV Virtual Functions AE
bool empfa: Enable SR-IOV Physical Functions AE
bool encfa: Enable PCI Functions AE.
__u8 aemd: AEM Delay Interval (for Sync only)
__u8 aerd: AEM Retry Delay (for Sync only; time in 100s of ms)
struct nvme_mi_aem_enable_list *enable_list: libnvme_mi_aem_enable_listucture containing header and items of events to be enabled or disabled. This is taken as a delta change from the current configuration.
size_t enable_list_size: Size of the enable_list including header and data. Meant to catch overrun issues.
struct nvme_mi_aem_occ_list_hdr *occ_list: Pointer to populate with the occurrence list (header and data)
size_t *occ_list_size: Total size of provided occ_list buffer. Will be updated with received size if successful

Description

Performs a MI Configuration Set, to ACK (sent after an AEM) or Sync (at anytime to enable or disable Asynchronous Events).

On success, populates occ_list. See TP6035a for details on how occ_list is populated in ACK versus Sync conditions

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_admin_xfer(struct libnvme_transport_handle *hdl, struct nvme_mi_admin_req_hdr *admin_req, size_t req_data_size, struct nvme_mi_admin_resp_hdr *admin_resp, off_t resp_data_offset, size_t *resp_data_size)¶: Raw admin transfer interface.

Parameters

struct libnvme_transport_handle *hdl: transport handle to send the admin command to
struct nvme_mi_admin_req_hdr *admin_req: request data
size_t req_data_size: size of request data payload
struct nvme_mi_admin_resp_hdr *admin_resp: buffer for response data
off_t resp_data_offset: offset into request data to retrieve from controller
size_t *resp_data_size: size of response data buffer, updated to received size

Description

Performs an arbitrary NVMe Admin command, using the provided request data, in admin_req. The size of the request data payload is specified in req_data_size - this does not include the standard header length (so a header-only request would have a size of 0).

On success, response data is stored in admin_resp, which has an optional appended payload buffer of resp_data_size bytes. The actual payload transferred will be stored in resp_data_size. These sizes do not include the Admin request header, so 0 represents no payload.

As with all Admin commands, we can request partial data from the Admin Response payload, offset by resp_data_offset.

See: struct nvme_mi_admin_req_hdr and struct nvme_mi_admin_resp_hdr.

Return

The nvme command status if a response was received (see enum nvme_status_field) or negative error code otherwise.

int libnvme_mi_control(libnvme_mi_ep_t ep, __u8 opcode, __u16 cpsp, __u16 *result_cpsr)¶: Perform a Control Primitive command

Parameters

libnvme_mi_ep_t ep: endpoint for MI communication
__u8 opcode: Control Primitive opcode (using enum nvme_mi_control_opcode)
__u16 cpsp: Control Primitive Specific Parameter
__u16 *result_cpsr: Optional field to return the result from the CPSR field

Description

Perform a Control Primitive command, using the opcode specified in opcode Stores the result from the CPSR field in result_cpsr if set.

See: enum nvme_mi_control_opcode

Return

0 on success, negative error code otherwise.

enum libnvme_mi_aem_handler_next_action¶: Next action for the AEM state machine handler

Constants

NVME_MI_AEM_HNA_ACK: Send an ack for the AEM
NVME_MI_AEM_HNA_NONE: No further action

Description

Used as return value for the AE callback generated when calling libnvme_mi_aem_process

struct libnvme_mi_event¶: AE event information structure

Definition

struct libnvme_mi_event {
  uint8_t aeoi;
  uint8_t aessi;
  uint32_t aeocidi;
  void *spec_info;
  size_t spec_info_len;
  void *vend_spec_info;
  size_t vend_spec_info_len;
};

Members

aeoi: Event identifier
aessi: Event occurrence scope info
aeocidi: Event occurrence scope ID info
spec_info: Specific info buffer
spec_info_len: Length of specific info buffer
vend_spec_info: Vendor specific info buffer
vend_spec_info_len: Length of vendor specific info buffer

Description

Application callbacks for libnvme_mi_aem_process will be able to call libnvme_mi_aem_get_next_event which will return a pointer to such an identifier for the next event the application should parse

struct libnvme_mi_event *libnvme_mi_aem_get_next_event(libnvme_mi_ep_t ep)¶: Get details for the next event to parse

Parameters

libnvme_mi_ep_t ep: The endpoint with the event

Description

When inside a aem_handler, call this and a returned struct pointer will provide details of event information. Will return NULL when end of parsing is occurred. spec_info and vend_spec_info must be copied to persist as they will not be valid after the handler_next_action has returned.

Return

Pointer no next libnvme_mi_event or NULL if this is the last one

struct libnvme_mi_aem_config¶: Provided for libnvme_mi_aem_enable

Definition

struct libnvme_mi_aem_config {
  enum libnvme_mi_aem_handler_next_action (*aem_handler)(libnvme_mi_ep_t ep,size_t num_events, void *userdata);
  struct libnvme_mi_aem_enabled_map enabled_map;
  bool envfa;
  bool empfa;
  bool encfa;
  __u8 aemd;
  __u8 aerd;
};

Members

aem_handler: Callback function for application processing of events
enabled_map: Map indicating which AE should be enabled on the endpoint
envfa: Enable SR-IOV virtual functions AE
empfa: Enable SR-IOV physical functions AE
encfa: Enable PCIe functions AE
aemd: AEM Delay (time in seconds from when event happens to AEM being batched and sent)
aerd: AEM Retry Delay (time in 100s of ms between AEM retries from the endpoint)

Description

Application callbacks for libnvme_mi_aem_process will be able to call libnvme_mi_aem_get_next_event which will return a pointer to such an identifier for the next event the application should parse

int libnvme_mi_aem_get_fd(libnvme_mi_ep_t ep)¶: Returns the pollable fd for AEM data available

Parameters

libnvme_mi_ep_t ep: The endpoint being monitored for asynchronous data

Description

This populated structure can be polled from the application to understand if a call to libnvme_mi_aem_process() is required (when a poll returns > 0).

Return

The fd value or -1 if error

int libnvme_mi_aem_enable(libnvme_mi_ep_t ep, struct libnvme_mi_aem_config *config, void *userdata)¶: Enable AE on the provided endpoint

Parameters

libnvme_mi_ep_t ep: Endpoint to enable AEs
struct libnvme_mi_aem_config *config: AE configuraiton including which events are enabled and the callback function
void *userdata: Application provided context pointer for callback function

Description

This function is called to enable AE on the endpoint. Endpoint will provide initial state (if any) of enabled AEs and application can parse those via the aem_handler fn pointer in callbacks. Thes can be obtained in the callback by calling libnvme_mi_aem_get_next_event().

Application should poll the fd that can be obtained from libnvme_mi_aem_get_fd and then call libnvme_mi_aem_process() when poll() indicates data available.

A call to libnvme_mi_aem_process() will grab AEM data and call the aem_handler fn pointer. At this point the application can call libnvme_mi_aem_get_next_event() to get information for each triggered event.

Return

0 on success, negative error code otherwise.

int libnvme_mi_aem_get_enabled(libnvme_mi_ep_t ep, struct libnvme_mi_aem_enabled_map *enabled)¶: Return information on which AEs are enabled

Parameters

libnvme_mi_ep_t ep: Endpoint to check enabled status
struct libnvme_mi_aem_enabled_map *enabled: libnvme_mi_aem_enabled_map indexed by AE event ID of enabled state

Return

0 on success, negative error code otherwise.

int libnvme_mi_aem_disable(libnvme_mi_ep_t ep)¶: Disable AE on the provided endpoint

Parameters

libnvme_mi_ep_t ep: Endpoint to disable AEs

Return

0 on success, negative error code otherwise.

int libnvme_mi_aem_process(libnvme_mi_ep_t ep, void *userdata)¶: Process AEM on the provided endpoint

Parameters

libnvme_mi_ep_t ep: Endpoint to process
void *userdata: Application provided context pointer for callback function

Description

Call this if poll() indicates data is available on the fd provided by libnvme_mi_aem_get_fd()

This will call the fn pointer, aem_handler, provided with libnvme_mi_aem_config and the application can call libnvme_mi_aem_get_next_event() from within this callback to get aem event data. The callback function should return NVME_MI_AEM_HNA_ACK for normal operation.

Return

0 on success, negative error code otherwise.

void *libnvme_mi_submit_entry(__u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len)¶: Weak hook called before an MI message is sent.

Parameters

__u8 type: MCTP message type
const struct nvme_mi_msg_hdr *hdr: Pointer to the MI message header
size_t hdr_len: Length of the message header in bytes
const void *data: Pointer to message payload data
size_t data_len: Length of payload data in bytes

Description

This is a weak symbol that can be overridden by an application to intercept outgoing MI messages for tracing or testing purposes. The return value is passed back as user_data to the matching libnvme_mi_submit_exit() call.

Return

An opaque pointer passed to libnvme_mi_submit_exit(), or NULL.

void libnvme_mi_submit_exit(__u8 type, const struct nvme_mi_msg_hdr *hdr, size_t hdr_len, const void *data, size_t data_len, void *user_data)¶: Weak hook called after an MI message completes.

Parameters

__u8 type: MCTP message type
const struct nvme_mi_msg_hdr *hdr: Pointer to the MI response message header
size_t hdr_len: Length of the response message header in bytes
const void *data: Pointer to response payload data
size_t data_len: Length of response payload data in bytes
void *user_data: Value returned by the matching libnvme_mi_submit_entry() call

Description

This is a weak symbol that can be overridden by an application to intercept completed MI transactions. Called with the opaque pointer returned by the corresponding libnvme_mi_submit_entry() call.

tree.h

libnvme tree object interface

void libnvme_set_application(struct libnvme_global_ctx *ctx, const char *a)¶: Specify managing application

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *a: Application string

Description

Sets the managing application string for r.

const char *libnvme_get_application(struct libnvme_global_ctx *ctx)¶: Get managing application

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Description

Returns the managing application string for r or NULL if not set.

void libnvme_skip_namespaces(struct libnvme_global_ctx *ctx)¶: Skip namespace scanning

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Description

Sets a flag to skip namespaces during scanning.

void libnvme_release_fds(struct libnvme_global_ctx *ctx)¶: Close all opened file descriptors in the tree

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds in the tree.

libnvme_host_t libnvme_first_host(struct libnvme_global_ctx *ctx)¶: Start host iterator

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Return

First libnvme_host_t object in an iterator

libnvme_host_t libnvme_next_host(struct libnvme_global_ctx *ctx, libnvme_host_t h)¶: Next host iterator

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
libnvme_host_t h: Previous libnvme_host_t iterator

Return

Next libnvme_host_t object in an iterator

struct libnvme_global_ctx *libnvme_host_get_global_ctx(libnvme_host_t h)¶: Returns libnvme_global_ctx object

Parameters

libnvme_host_t h: libnvme_host_t object

Return

struct libnvme_global_ctx object from h

void libnvme_host_set_pdc_enabled(libnvme_host_t h, bool enabled)¶: Set Persistent Discovery Controller flag

Parameters

libnvme_host_t h: Host for which the falg should be set
bool enabled: The bool to set the enabled flag

Description

When libnvme_host_set_pdc_enabled() is not used to set the PDC flag, libnvme_host_is_pdc_enabled() will return the default value which was passed into the function and not the undefined flag value.

bool libnvme_host_is_pdc_enabled(libnvme_host_t h, bool fallback)¶: Is Persistenct Discovery Controller enabled

Parameters

libnvme_host_t h: Host which to check if PDC is enabled
bool fallback: The fallback default value of the flag when libnvme_host_set_pdc_enabled has not be used to set the flag.

Return

true if PDC is enabled for h, else false

int libnvme_get_host(struct libnvme_global_ctx *ctx, const char *hostnqn, const char *hostid, libnvme_host_t *h)¶: Returns a host object

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn: Host NQN (optional)
const char *hostid: Host ID (optional)
libnvme_host_t *h: libnvme_host_t object to return

Description

Returns a host object based on the hostnqn/hostid values or the default if hostnqn/hostid are NULL.

Return

0 on success, negative error code otherwise.

int libnvme_host_get_ids(struct libnvme_global_ctx *ctx, const char *hostnqn_arg, const char *hostid_arg, char **hostnqn, char **hostid)¶: Retrieve host ids from various sources

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *hostnqn_arg: Input hostnqn (command line) argument
const char *hostid_arg: Input hostid (command line) argument
char **hostnqn: Output hostnqn
char **hostid: Output hostid

Description

libnvme_host_get_ids figures out which hostnqn/hostid is to be used. There are several sources where this information can be retrieved.

The order is:

Start with informartion from DMI or device-tree

Override hostnqn and hostid from /etc/nvme files

Override hostnqn or hostid with values from JSON configuration file. The first host entry in the file is considered the default host.

Override hostnqn or hostid with values from the command line (hostnqn_arg, hostid_arg).

If the IDs are still NULL after the lookup algorithm, the function will generate random IDs.

The function also verifies that hostnqn and hostid matches. The Linux NVMe implementation expects a 1:1 matching between the IDs.

Return

0 on success (hostnqn and hostid contain valid strings: which the caller needs to free), or negative error code otherwise.

libnvme_subsystem_t libnvme_first_subsystem(libnvme_host_t h)¶: Start subsystem iterator

Parameters

libnvme_host_t h: libnvme_host_t object

Return

first libnvme_subsystem_t object in an iterator

libnvme_subsystem_t libnvme_next_subsystem(libnvme_host_t h, libnvme_subsystem_t s)¶: Next subsystem iterator

Parameters

libnvme_host_t h: libnvme_host_t object
libnvme_subsystem_t s: Previous libnvme_subsystem_t iterator

Return

next libnvme_subsystem_t object in an iterator

int libnvme_get_subsystem(struct libnvme_global_ctx *ctx, struct libnvme_host *h, const char *name, const char *subsysnqn, struct libnvme_subsystem **s)¶: Returns libnvme_subsystem_t object

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
struct libnvme_host *h: libnvme_host_t object
const char *name: Name of the subsystem (may be NULL)
const char *subsysnqn: Subsystem NQN
struct libnvme_subsystem **s: libnvme_subsystem_t object

Description

Returns an libnvme_subsystem_t object in h base on name (if present) and subsysnqn or create one if not found.

void libnvme_free_subsystem(struct libnvme_subsystem *s)¶: Free a subsystem

Parameters

struct libnvme_subsystem *s: subsystem

Description

Frees s and all related objects.

libnvme_host_t libnvme_subsystem_get_host(libnvme_subsystem_t s)¶: Returns libnvme_host_t object

Parameters

libnvme_subsystem_t s: subsystem

Return

libnvme_host_t object from s

char *libnvme_subsystem_get_iopolicy(libnvme_subsystem_t s)¶: Get subsystem iopolicy name

Parameters

libnvme_subsystem_t s: subsystem

Return

The iopolicy configured in subsystem s

libnvme_ns_t libnvme_ctrl_first_ns(libnvme_ctrl_t c)¶: Start namespace iterator

Parameters

libnvme_ctrl_t c: Controller instance

Return

First libnvme_ns_t object of an c iterator

libnvme_ns_t libnvme_ctrl_next_ns(libnvme_ctrl_t c, libnvme_ns_t n)¶: Next namespace iterator

Parameters

libnvme_ctrl_t c: Controller instance
libnvme_ns_t n: Previous libnvme_ns_t iterator

Return

Next libnvme_ns_t object of an c iterator

libnvme_path_t libnvme_ctrl_first_path(libnvme_ctrl_t c)¶: Start path iterator

Parameters

libnvme_ctrl_t c: Controller instance

Return

First libnvme_path_t object of an c iterator

libnvme_path_t libnvme_ctrl_next_path(libnvme_ctrl_t c, libnvme_path_t p)¶: Next path iterator

Parameters

libnvme_ctrl_t c: Controller instance
libnvme_path_t p: Previous libnvme_path_t object of an c iterator

Return

Next libnvme_path_t object of an c iterator

libnvme_ctrl_t libnvme_subsystem_first_ctrl(libnvme_subsystem_t s)¶: First ctrl iterator

Parameters

libnvme_subsystem_t s: libnvme_subsystem_t object

Return

First controller of an s iterator

libnvme_ctrl_t libnvme_subsystem_next_ctrl(libnvme_subsystem_t s, libnvme_ctrl_t c)¶: Next ctrl iterator

Parameters

libnvme_subsystem_t s: libnvme_subsystem_t object
libnvme_ctrl_t c: Previous controller instance of an s iterator

Return

Next controller of an s iterator

libnvme_path_t libnvme_namespace_first_path(libnvme_ns_t ns)¶: Start path iterator

Parameters

libnvme_ns_t ns: Namespace instance

Return

First libnvme_path_t object of an ns iterator

libnvme_path_t libnvme_namespace_next_path(libnvme_ns_t ns, libnvme_path_t p)¶: Next path iterator

Parameters

libnvme_ns_t ns: Namespace instance
libnvme_path_t p: Previous libnvme_path_t object of an ns iterator

Return

Next libnvme_path_t object of an ns iterator

libnvme_ns_t libnvme_subsystem_first_ns(libnvme_subsystem_t s)¶: Start namespace iterator

Parameters

libnvme_subsystem_t s: libnvme_subsystem_t object

Return

First libnvme_ns_t object of an s iterator

libnvme_ns_t libnvme_subsystem_next_ns(libnvme_subsystem_t s, libnvme_ns_t n)¶: Next namespace iterator

Parameters

libnvme_subsystem_t s: libnvme_subsystem_t object
libnvme_ns_t n: Previous libnvme_ns_t iterator

Return

Next libnvme_ns_t object of an s iterator

libnvme_for_each_host_safe¶

libnvme_for_each_host_safe (r, h, _h)

Traverse host list

Parameters

r: libnvme_root_t object
h: libnvme_host_t object
_h: Temporary libnvme_host_t object

libnvme_for_each_host¶

libnvme_for_each_host (r, h)

Traverse host list

Parameters

r: libnvme_root_t object
h: libnvme_host_t object

libnvme_for_each_subsystem_safe¶

libnvme_for_each_subsystem_safe (h, s, _s)

Traverse subsystems

Parameters

h: libnvme_host_t object
s: libnvme_subsystem_t object
_s: Temporary libnvme_subsystem_t object

libnvme_for_each_subsystem¶

libnvme_for_each_subsystem (h, s)

Traverse subsystems

Parameters

h: libnvme_host_t object
s: libnvme_subsystem_t object

libnvme_subsystem_for_each_ctrl_safe¶

libnvme_subsystem_for_each_ctrl_safe (s, c, _c)

Traverse controllers

Parameters

s: libnvme_subsystem_t object
c: Controller instance
_c: A libnvme_ctrl_t_node to use as temporary storage

libnvme_subsystem_for_each_ctrl¶

libnvme_subsystem_for_each_ctrl (s, c)

Traverse controllers

Parameters

s: libnvme_subsystem_t object
c: Controller instance

libnvme_ctrl_for_each_ns_safe¶

libnvme_ctrl_for_each_ns_safe (c, n, _n)

Traverse namespaces

Parameters

c: Controller instance
n: libnvme_ns_t object
_n: A libnvme_ns_t_node to use as temporary storage

libnvme_ctrl_for_each_ns¶

libnvme_ctrl_for_each_ns (c, n)

Traverse namespaces

Parameters

c: Controller instance
n: libnvme_ns_t object

libnvme_ctrl_for_each_path_safe¶

libnvme_ctrl_for_each_path_safe (c, p, _p)

Traverse paths

Parameters

c: Controller instance
p: libnvme_path_t object
_p: A libnvme_path_t_node to use as temporary storage

libnvme_ctrl_for_each_path¶

libnvme_ctrl_for_each_path (c, p)

Traverse paths

Parameters

c: Controller instance
p: libnvme_path_t object

libnvme_subsystem_for_each_ns_safe¶

libnvme_subsystem_for_each_ns_safe (s, n, _n)

Traverse namespaces

Parameters

s: libnvme_subsystem_t object
n: libnvme_ns_t object
_n: A libnvme_ns_t_node to use as temporary storage

libnvme_subsystem_for_each_ns¶

libnvme_subsystem_for_each_ns (s, n)

Traverse namespaces

Parameters

s: libnvme_subsystem_t object
n: libnvme_ns_t object

libnvme_namespace_for_each_path_safe¶

libnvme_namespace_for_each_path_safe (n, p, _p)

Traverse paths

Parameters

n: Namespace instance
p: libnvme_path_t object
_p: A libnvme_path_t_node to use as temporary storage

libnvme_namespace_for_each_path¶

libnvme_namespace_for_each_path (n, p)

Traverse paths

Parameters

n: Namespace instance
p: libnvme_path_t object

void libnvme_ns_copy_uuid(libnvme_ns_t n, unsigned char out[NVME_UUID_LEN])¶: Copy UUID of a namespace into a caller buffer

Parameters

libnvme_ns_t n: Namespace instance
unsigned char out[NVME_UUID_LEN]: buffer for the UUID

Description

Copies the namespace’s uuid into out

long libnvme_ns_get_command_retry_count(libnvme_ns_t n)¶: Get command retry count

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Number of times any command issued to namespace n has to be retried

long libnvme_ns_get_command_error_count(libnvme_ns_t n)¶: Get command error count

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Number of times command issued to namespace n returns non-zero status or error

long libnvme_ns_get_requeue_no_usable_path_count(libnvme_ns_t n)¶: Get num of I/O requeue count

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Number of I/Os which are re-queued due to the unavalibility of any usable path (maybe path is currently experiencing transinet link failure)

long libnvme_ns_get_fail_no_available_path_count(libnvme_ns_t n)¶: Get num of I/Os forced to fail

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Number of I/Os which are forced to fail due to no path available

const char *libnvme_ns_get_firmware(libnvme_ns_t n)¶: Firmware string of a namespace

Parameters

libnvme_ns_t n: Namespace instance

Return

Firmware string of n

const char *libnvme_ns_get_serial(libnvme_ns_t n)¶: Serial number of a namespace

Parameters

libnvme_ns_t n: Namespace instance

Return

Serial number string of n

const char *libnvme_ns_get_model(libnvme_ns_t n)¶: Model of a namespace

Parameters

libnvme_ns_t n: Namespace instance

Return

Model string of n

libnvme_subsystem_t libnvme_ns_get_subsystem(libnvme_ns_t n)¶: libnvme_subsystem_t of a namespace

Parameters

libnvme_ns_t n: Namespace instance

Return

libnvme_subsystem_t object of n

libnvme_ctrl_t libnvme_ns_get_ctrl(libnvme_ns_t n)¶: libnvme_ctrl_t of a namespace

Parameters

libnvme_ns_t n: Namespace instance

Description

libnvme_ctrl_t object may be NULL for a multipathed namespace

Return

libnvme_ctrl_t object of n if present

void libnvme_free_ns(struct libnvme_ns *n)¶: Free a namespace object

Parameters

struct libnvme_ns *n: Namespace instance

int libnvme_ns_read(libnvme_ns_t n, void *buf, off_t offset, size_t count)¶: Read from a namespace

Parameters

libnvme_ns_t n: Namespace instance
void *buf: Buffer into which the data will be transferred
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors read or -1 on error.

int libnvme_ns_write(libnvme_ns_t n, void *buf, off_t offset, size_t count)¶: Write to a namespace

Parameters

libnvme_ns_t n: Namespace instance
void *buf: Buffer with data to be written
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors written or -1 on error

int libnvme_ns_verify(libnvme_ns_t n, off_t offset, size_t count)¶: Verify data on a namespace

Parameters

libnvme_ns_t n: Namespace instance
off_t offset: LBA offset of n
size_t count: Number of sectors to be verified

Return

Number of sectors verified

int libnvme_ns_compare(libnvme_ns_t n, void *buf, off_t offset, size_t count)¶: Compare data on a namespace

Parameters

libnvme_ns_t n: Namespace instance
void *buf: Buffer with data to be compared
off_t offset: LBA offset of n
size_t count: Number of sectors in buf

Return

Number of sectors compared

int libnvme_ns_write_zeros(libnvme_ns_t n, off_t offset, size_t count)¶: Write zeros to a namespace

Parameters

libnvme_ns_t n: Namespace instance
off_t offset: LBA offset in n
size_t count: Number of sectors to be written

Return

Number of sectors written

int libnvme_ns_write_uncorrectable(libnvme_ns_t n, off_t offset, size_t count)¶: Issus a ‘write uncorrectable’ command

Parameters

libnvme_ns_t n: Namespace instance
off_t offset: LBA offset in n
size_t count: Number of sectors to be written

Return

Number of sectors written

int libnvme_ns_flush(libnvme_ns_t n)¶: Flush data to a namespace

Parameters

libnvme_ns_t n: Namespace instance

Return

0 on success, negative error code otherwise.

int libnvme_ns_identify(libnvme_ns_t n, struct nvme_id_ns *ns)¶: Issue an ‘identify namespace’ command

Parameters

libnvme_ns_t n: Namespace instance
struct nvme_id_ns *ns: nvme_id_ns buffer

Description

Writes the data returned by the ‘identify namespace’ command into ns.

Return

0 on success, negative error code otherwise.

int libnvme_ns_identify_descs(libnvme_ns_t n, struct nvme_ns_id_desc *descs)¶: Issue an ‘identify descriptors’ command

Parameters

libnvme_ns_t n: Namespace instance
struct nvme_ns_id_desc *descs: List of identify descriptors

Description

Writes the data returned by the ‘identify descriptors’ command into descs.

Return

0 on success, negative error code otherwise.

int libnvme_path_get_queue_depth(libnvme_path_t p)¶: Queue depth of an libnvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Queue depth of p

char *libnvme_path_get_ana_state(libnvme_path_t p)¶: ANA state of an nvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

ANA state of p

char *libnvme_path_get_numa_nodes(libnvme_path_t p)¶: Numa nodes of an nvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Numa nodes of p

long libnvme_path_get_multipath_failover_count(libnvme_path_t p)¶: Get multipath failover count

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Number of times I/Os have to be failed over to another active path from path p maybe due to any transient error observed on path p

long libnvme_path_get_command_retry_count(libnvme_path_t p)¶: Get command retry count

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Number of times any command issued to the namespace represented by path p has to be retried

long libnvme_path_get_command_error_count(libnvme_path_t p)¶: Get command error count

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Number of times command issued to the namespace represented by path p returns non-zero status or error

libnvme_ctrl_t libnvme_path_get_ctrl(libnvme_path_t p)¶: Parent controller of an libnvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Parent controller if present

libnvme_ns_t libnvme_path_get_ns(libnvme_path_t p)¶: Parent namespace of an libnvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Parent namespace if present

void libnvme_path_reset_stat(libnvme_path_t p)¶: Resets namespace path nvme stat

Parameters

libnvme_path_t p: libnvme_path_t object

int libnvme_path_update_stat(libnvme_path_t p, bool diffstat)¶: Update stat of an nvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object
bool diffstat: If set to true then getters return the diff stat otherwise return the current absolute stat

Return

0 on success, negative error code otherwise.

unsigned long libnvme_path_get_read_ios(libnvme_path_t p)¶: Calculate and return read IOs

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Num of read IOs processed between two stat samples

unsigned long libnvme_path_get_write_ios(libnvme_path_t p)¶: Get write I/Os

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Num of write I/Os processed between two stat samples

unsigned int libnvme_path_get_read_ticks(libnvme_path_t p)¶: Get read I/O ticks

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Time, in milliseconds, sepnt processing read I/O requests: between two stat samples

unsigned long long libnvme_path_get_read_sectors(libnvme_path_t p)¶: Get read I/O sectors

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Number of sectors read from the device between two stat samples

unsigned long long libnvme_path_get_write_sectors(libnvme_path_t p)¶: Get write I/O sectors

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Num of sectors written to the device between two stat samples

unsigned int libnvme_path_get_write_ticks(libnvme_path_t p)¶: Get write I/O ticks

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Time, in milliseconds, sepnt processing write I/O requests: between two stat samples

double libnvme_path_get_stat_interval(libnvme_path_t p)¶: Get interval between two stat samples

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Interval, in milliseconds between collection of two consecutive: stat samples

unsigned int libnvme_path_get_io_ticks(libnvme_path_t p)¶: Get I/O ticks

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Time consumed, in milliseconds, processing I/O requests between: two stat samples

unsigned int libnvme_path_get_inflights(libnvme_path_t p)¶: Inflight IOs for nvme_path_t object

Parameters

libnvme_path_t p: libnvme_path_t object

Return

Inflight number of IOs

struct libnvme_transport_handle *libnvme_ctrl_get_transport_handle(libnvme_ctrl_t c)¶: Get associated transport handle

Parameters

libnvme_ctrl_t c: Controller instance

Description

libnvme will open() the device (if not already opened) and keep an internal copy of the link handle. Following calls to this API retrieve the internal cached copy of the link handle. The file will remain opened and the handle will remain cached until the controller object is deleted or libnvme_ctrl_release_transport_handle() is called.

Return

Link handle associated with c or NULL

void libnvme_ctrl_release_transport_handle(libnvme_ctrl_t c)¶: Free transport handle from controller object

Parameters

libnvme_ctrl_t c: Controller instance

char *libnvme_ctrl_get_src_addr(libnvme_ctrl_t c, char *src_addr, size_t src_addr_len)¶: Extract src_addr from the c->address string

Parameters

libnvme_ctrl_t c: Controller instance
char *src_addr: Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.
size_t src_addr_len: Length of the buffer src_addr.

Return

Pointer to src_addr on success. NULL on failure to extract the src_addr.

const char *libnvme_ctrl_get_state(libnvme_ctrl_t c)¶: Running state of a controller

Parameters

libnvme_ctrl_t c: Controller instance

Return

String indicating the running state of c

libnvme_subsystem_t libnvme_ctrl_get_subsystem(libnvme_ctrl_t c)¶: Parent subsystem of a controller

Parameters

libnvme_ctrl_t c: Controller instance

Return

Parent libnvme_subsystem_t object

const char *libnvme_ns_head_get_sysfs_dir(libnvme_ns_head_t head)¶: sysfs dir of namespave head

Parameters

libnvme_ns_head_t head: namespace head instance

Return

sysfs directory name of head

int libnvme_ns_update_stat(libnvme_ns_t n, bool diffstat)¶: update the nvme namespace stat

Parameters

libnvme_ns_t n: libnvme_ns_t object
bool diffstat: If set to true then getters return the diff stat otherwise return the current absolute stat

Return

0 on success, negative error code otherwise.

void libnvme_ns_reset_stat(libnvme_ns_t n)¶: Resets nvme namespace stat

Parameters

libnvme_ns_t n: libnvme_ns_t object

unsigned int libnvme_ns_get_inflights(libnvme_ns_t n)¶: Inflight IOs for nvme_ns_t object

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Inflight number of IOs

unsigned int libnvme_ns_get_io_ticks(libnvme_ns_t n)¶: Get IO ticks

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Time consumed, in milliseconds, processing I/O requests between: two stat samples

unsigned int libnvme_ns_get_read_ticks(libnvme_ns_t n)¶: Get read I/O ticks

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Time, in milliseconds, sepnt processing read I/O requests: between two stat samples

unsigned int libnvme_ns_get_write_ticks(libnvme_ns_t n)¶: Get write I/O ticks

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Time, in milliseconds, sepnt processing write I/O requests: between two stat samples

double libnvme_ns_get_stat_interval(libnvme_ns_t n)¶: Get interval between two stat samples

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Interval, in milliseconds, between collection of two consecutive: stat samples

unsigned long libnvme_ns_get_read_ios(libnvme_ns_t n)¶: Get num of read I/Os

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Num of read IOs processed between two stat samples

unsigned long libnvme_ns_get_write_ios(libnvme_ns_t n)¶: Get num of write I/Os

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Num of write IOs processed between two consecutive stat samples

unsigned long long libnvme_ns_get_read_sectors(libnvme_ns_t n)¶: Get num of read sectors

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Num of sectors read from the device between two stat samples

unsigned long long libnvme_ns_get_write_sectors(libnvme_ns_t n)¶: Get num of write sectors

Parameters

libnvme_ns_t n: libnvme_ns_t object

Return

Num of sectors written to the device between two stat samples

long libnvme_ctrl_get_command_error_count(libnvme_ctrl_t c)¶: Get admin command error count

Parameters

libnvme_ctrl_t c: Controller instance

Return

Number of times admin command issued to controller c failed or returned error status

long libnvme_ctrl_get_reset_count(libnvme_ctrl_t c)¶: Get controller reset count

Parameters

libnvme_ctrl_t c: Controller instance

Return

Number of timer controller c is reset

long libnvme_ctrl_get_reconnect_count(libnvme_ctrl_t c)¶: Get controller reconnect count

Parameters

libnvme_ctrl_t c: Controller instance

Return

Number of times controller has to reconnect to the target

int libnvme_ctrl_identify(libnvme_ctrl_t c, struct nvme_id_ctrl *id)¶: Issues an ‘identify controller’ command

Parameters

libnvme_ctrl_t c: Controller instance
struct nvme_id_ctrl *id: Identify controller data structure

Description

Issues an ‘identify controller’ command to c and copies the data into id.

Return

0 on success, negative error code otherwise.

int libnvme_scan_ctrl(struct libnvme_global_ctx *ctx, const char *name, libnvme_ctrl_t *c)¶: Scan on a controller

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *name: Name of the controller
libnvme_ctrl_t *c: libnvme_ctrl_t object to return

Description

Scans a controller with sysfs name name and add it to r.

Return

0 on success, negative error code otherwise.

void libnvme_rescan_ctrl(libnvme_ctrl_t c)¶: Rescan an existing controller

Parameters

libnvme_ctrl_t c: Controller instance

int libnvme_init_ctrl(libnvme_host_t h, libnvme_ctrl_t c, int instance)¶: Initialize libnvme_ctrl_t object for an existing controller.

Parameters

libnvme_host_t h: libnvme_host_t object
libnvme_ctrl_t c: libnvme_ctrl_t object
int instance: Instance number (e.g. 1 for nvme1)

Return

0 on success, negative error code otherwise.

void libnvme_free_ctrl(struct libnvme_ctrl *c)¶: Free controller

Parameters

struct libnvme_ctrl *c: Controller instance

void libnvme_unlink_ctrl(struct libnvme_ctrl *c)¶: Unlink controller

Parameters

struct libnvme_ctrl *c: Controller instance

int libnvme_scan_topology(struct libnvme_global_ctx *ctx, libnvme_scan_filter_t f, void *f_args)¶: Scan NVMe topology and apply filter

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
libnvme_scan_filter_t f: filter to apply
void *f_args: user-specified argument to f

Description

Scans the NVMe topology and filters out the resulting elements by applying f.

Return

0 on success, negative error code otherwise.

void libnvme_host_release_fds(struct libnvme_host *h)¶: Close all opened file descriptors under host

Parameters

struct libnvme_host *h: libnvme_host_t object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds under this host.

void libnvme_free_host(libnvme_host_t h)¶: Free libnvme_host_t object

Parameters

libnvme_host_t h: libnvme_host_t object

int libnvme_read_config(struct libnvme_global_ctx *ctx, const char *config_file)¶: Read NVMe JSON configuration file

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *config_file: JSON configuration file

Description

Read in the contents of config_file and merge them with the elements in r.

Return

0 on success, negative error code otherwise.

void libnvme_refresh_topology(struct libnvme_global_ctx *ctx)¶: Refresh libnvme_root_t object contents

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Description

Removes all elements in r and rescans the existing topology.

int libnvme_dump_config(struct libnvme_global_ctx *ctx, int fd)¶: Print the JSON configuration

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
int fd: File descriptor to write the JSON configuration.

Description

Writes the current contents of the JSON configuration to the file descriptor fd.

Return

0 on success, negative error code otherwise.

int libnvme_dump_tree(struct libnvme_global_ctx *ctx)¶: Dump internal object tree

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object

Description

Prints the internal object tree in JSON format to stdout.

Return

0 on success, negative error code otherwise.

char *libnvme_get_attr(const char *d, const char *attr)¶: Read sysfs attribute

Parameters

const char *d: sysfs directory
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty: value or error.

char *libnvme_get_subsys_attr(libnvme_subsystem_t s, const char *attr)¶: Read subsystem sysfs attribute

Parameters

libnvme_subsystem_t s: libnvme_subsystem_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty: value or error.

char *libnvme_get_ctrl_attr(libnvme_ctrl_t c, const char *attr)¶: Read controller sysfs attribute

Parameters

libnvme_ctrl_t c: Controller instance
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error.

char *libnvme_get_ns_attr(libnvme_ns_t n, const char *attr)¶: Read namespace sysfs attribute

Parameters

libnvme_ns_t n: libnvme_ns_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error.

libnvme_ns_t libnvme_subsystem_lookup_namespace(struct libnvme_subsystem *s, __u32 nsid)¶: lookup namespace by NSID

Parameters

struct libnvme_subsystem *s: libnvme_subsystem_t object
__u32 nsid: Namespace id

Return

libnvme_ns_t of the namespace with id nsid in subsystem s

void libnvme_subsystem_release_fds(struct libnvme_subsystem *s)¶: Close all opened fds under subsystem

Parameters

struct libnvme_subsystem *s: libnvme_subsystem_t object

Description

Controller and Namespace objects cache the file descriptors of opened nvme devices. This API can be used to close and clear all cached fds under this subsystem.

char *libnvme_get_path_attr(libnvme_path_t p, const char *attr)¶: Read path sysfs attribute

Parameters

libnvme_path_t p: libnvme_path_t object
const char *attr: sysfs attribute name

Return

String with the contents of attr or NULL in case of an empty value: or in case of an error.

int libnvme_scan_namespace(struct libnvme_global_ctx *ctx, const char *name, libnvme_ns_t *ns)¶: scan namespace based on sysfs name

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
const char *name: sysfs name of the namespace to scan
libnvme_ns_t *ns: libnvme_ns_t object to return

Return

0 on success, negative error code otherwise.

filters.h

libnvme directory filter

int libnvme_filter_namespace(const struct dirent *d)¶: Filter for namespaces

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int libnvme_filter_paths(const struct dirent *d)¶: Filter for paths

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int libnvme_filter_ctrls(const struct dirent *d)¶: Filter for controllers

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int libnvme_filter_subsys(const struct dirent *d)¶: Filter for subsystems

Parameters

const struct dirent *d: dirent to check

Return

1 if d matches, 0 otherwise

int libnvme_scan_subsystems(struct dirent ***subsys)¶: Scan for subsystems

Parameters

struct dirent ***subsys: Pointer to array of dirents

Return

number of entries in subsys or a negative error code

int libnvme_scan_subsystem_namespaces(libnvme_subsystem_t s, struct dirent ***ns)¶: Scan for namespaces in a subsystem

Parameters

libnvme_subsystem_t s: Subsystem to scan
struct dirent ***ns: Pointer to array of dirents

Return

number of entries in ns or a negative error code

int libnvme_scan_ctrls(struct dirent ***ctrls)¶: Scan for controllers

Parameters

struct dirent ***ctrls: Pointer to array of dirents

Return

number of entries in ctrls or a negative error code

int libnvme_scan_ctrl_namespace_paths(libnvme_ctrl_t c, struct dirent ***paths)¶: Scan for namespace paths in a controller

Parameters

libnvme_ctrl_t c: Controller to scan
struct dirent ***paths: Pointer to array of dirents

Return

number of entries in paths or a negative error code

int libnvme_scan_ctrl_namespaces(libnvme_ctrl_t c, struct dirent ***ns)¶: Scan for namespaces in a controller

Parameters

libnvme_ctrl_t c: Controller to scan
struct dirent ***ns: Pointer to array of dirents

Return

number of entries in ns or a negative error code

int libnvme_scan_ns_head_paths(libnvme_ns_head_t head, struct dirent ***paths)¶: Scan for namespace paths

Parameters

libnvme_ns_head_t head: Namespace head node to scan
struct dirent ***paths: Pointer to array of dirents

Return

number of entries in ents or a negative error code

util.h

libnvme utility functions

enum libnvme_connect_err¶: nvme connect error codes

Constants

ENVME_CONNECT_RESOLVE: failed to resolve host
ENVME_CONNECT_ADDRFAM: unrecognized address family
ENVME_CONNECT_TRADDR: failed to get traddr
ENVME_CONNECT_TARG: need a transport (-t) argument
ENVME_CONNECT_AARG: need a address (-a) argument
ENVME_CONNECT_OPEN: failed to open nvme-fabrics device
ENVME_CONNECT_WRITE: failed to write to nvme-fabrics device
ENVME_CONNECT_READ: failed to read from nvme-fabrics device
ENVME_CONNECT_PARSE: failed to parse ctrl info
ENVME_CONNECT_INVAL_TR: invalid transport type
ENVME_CONNECT_LOOKUP_SUBSYS_NAME: failed to lookup subsystem name
ENVME_CONNECT_LOOKUP_SUBSYS: failed to lookup subsystem
ENVME_CONNECT_ALREADY: the connect attempt failed, already connected
ENVME_CONNECT_INVAL: invalid arguments/configuration
ENVME_CONNECT_ADDRINUSE: hostnqn already in use
ENVME_CONNECT_NODEV: invalid interface
ENVME_CONNECT_OPNOTSUPP: not supported
ENVME_CONNECT_CONNREFUSED: connection refused
ENVME_CONNECT_ADDRNOTAVAIL: cannot assign requested address
ENVME_CONNECT_IGNORED: connect attempt is ignored due to configuration
ENVME_CONNECT_NOKEY: the TLS key is missing

__u8 libnvme_status_to_errno(int status, bool fabrics)¶: Converts nvme return status to errno

Parameters

int status: Return status from an nvme passthrough command
bool fabrics: Set to true if status is to a fabrics target.

Return

An errno representing the nvme status if it is an nvme status field, or unchanged status is < 0 since errno is already set.

const char *libnvme_status_to_string(int status, bool fabrics)¶: Returns string describing nvme return status.

Parameters

int status: Return status from an nvme passthrough command
bool fabrics: Set to true if status is to a fabrics target.

Return

String representation of the nvme status if it is an nvme status field, or a standard errno string if status is < 0.

const char *libnvme_sanitize_ns_status_to_string(__u16 sc)¶: Returns sanitize ns status string.

Parameters

__u16 sc: Return status code from an sanitize ns command

Return

The sanitize ns status string if it is a specific status code.

const char *libnvme_set_features_status_to_string(__u16 sc)¶: Returns set features status string.

Parameters

__u16 sc: Return status code from an set features command

Return

The set features status string if it is a specific status code.

const char *libnvme_opcode_status_to_string(int status, bool admin, __u8 opcode)¶: Returns nvme opcode status string.

Parameters

int status: Return status from an nvme passthrough command
bool admin: Set to true if an admin command
__u8 opcode: Opcode from an nvme passthrough command

Return

The nvme opcode status string if it is an nvme status field, or a standard errno string if status is < 0.

const char *libnvme_errno_to_string(int err)¶: Returns string describing nvme connect failures

Parameters

int err: Returned error code from libnvme_add_ctrl()

Return

String representation of the nvme connect error codes

const char *libnvme_strerror(int err)¶: Returns string describing nvme errors and errno

Parameters

int err: Returned error codes from all libnvme functions

Return

String representation of either the nvme connect error codes (positive values) or errno string (negative values)

struct nvmf_ext_attr *libnvmf_exat_ptr_next(struct nvmf_ext_attr *p)¶: Increment p to the next element in the array.

Parameters

struct nvmf_ext_attr *p: Pointer to an element of an array of “struct nvmf_ext_attr”.

Description

Extended attributes are saved to an array of “struct nvmf_ext_attr” where each element of the array is of variable size. In order to move to the next element in the array one must increment the pointer to the current element (p) by the size of the current element.

Return

Pointer to the next element in the array.

enum libnvme_version¶: Selector for version to be returned by libnvme_get_version

Constants

LIBNVME_VERSION_PROJECT: Project release version
LIBNVME_VERSION_GIT: Git reference

const char *libnvme_get_version(enum libnvme_version type)¶: Return version libnvme string

Parameters

enum libnvme_version type: Selects which version type (see struct libnvme_version)

Return

Returns version string for known types or else “n/a”

int libnvme_uuid_to_string(unsigned char uuid[NVME_UUID_LEN], char *str)¶: Return string represenation of encoded UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID
char *str: Output string represenation of UUID

Return

Returns error code if type conversion fails.

int libnvme_uuid_from_string(const char *str, unsigned char uuid[NVME_UUID_LEN])¶: Return encoded UUID represenation of string UUID

Parameters

const char *str: Output string represenation of UUID
unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID

Return

Returns error code if type conversion fails.

int libnvme_random_uuid(unsigned char uuid[NVME_UUID_LEN])¶: Generate random UUID

Parameters

unsigned char uuid[NVME_UUID_LEN]: Generated random UUID

Description

Generate random number according https://www.rfc-editor.org/rfc/rfc4122#section-4.4

Return

Returns error code if generating of random number fails.

int libnvme_find_uuid(struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN])¶: Find UUID position on UUID list

Parameters

struct nvme_id_uuid_list *uuid_list: UUID list returned by identify UUID
const unsigned char uuid[NVME_UUID_LEN]: Binary encoded input UUID

Return

The array position where given UUID is present, or negative error code otherwise.

char *libnvme_basename(const char *path)¶: Return the final path component (the one after the last ‘/’)

Parameters

const char *path: A string containing a filesystem path

Return

A pointer into the original null-terminated path string.

enum libnbft_primary_admin_host_flag¶: Primary Administrative Host Descriptor Flags

Constants

LIBNBFT_PRIMARY_ADMIN_HOST_FLAG_NOT_INDICATED: Not Indicated by Driver: The driver that created this NBFT provided no administrative priority hint for this NBFT.
LIBNBFT_PRIMARY_ADMIN_HOST_FLAG_UNSELECTED: Unselected: The driver that created this NBFT explicitly indicated that this NBFT should not be prioritized over any other NBFT.
LIBNBFT_PRIMARY_ADMIN_HOST_FLAG_SELECTED: Selected: The driver that created this NBFT explicitly indicated that this NBFT should be prioritized over any other NBFT.
LIBNBFT_PRIMARY_ADMIN_HOST_FLAG_RESERVED: Reserved.

struct libnbft_host¶: Host Descriptor

Definition

struct libnbft_host {
  unsigned char *id;
  char *nqn;
  bool host_id_configured;
  bool host_nqn_configured;
  enum libnbft_primary_admin_host_flag primary;
};

Members

id: Host ID (raw UUID, length = 16 bytes).
nqn: Host NQN.
host_id_configured: HostID Configured Flag: value of True indicates that id contains administratively-configured value, or driver default value if False.
host_nqn_configured: Host NQN Configured Flag: value of True indicates that nqn contains administratively-configured value, or driver default value if False.
primary: Primary Administrative Host Descriptor, see enum libnbft_primary_admin_host_flag.

struct libnbft_hfi_info_tcp¶: HFI Transport Info Descriptor - NVMe/TCP

Definition

struct libnbft_hfi_info_tcp {
  __u32 pci_sbdf;
  __u8 mac_addr[6];
  __u16 vlan;
  __u8 ip_origin;
  char ipaddr[40];
  __u8 subnet_mask_prefix;
  char gateway_ipaddr[40];
  __u16 route_metric;
  char primary_dns_ipaddr[40];
  char secondary_dns_ipaddr[40];
  char dhcp_server_ipaddr[40];
  char *host_name;
  bool this_hfi_is_default_route;
  bool dhcp_override;
};

Members

pci_sbdf: PCI Express Routing ID for the HFI Transport Function.
mac_addr: MAC Address: The MAC address of this HFI, in EUI-48TM format.
vlan: The VLAN identifier if the VLAN is associated with this HFI, as defined in IEEE 802.1q-2018 or zeroes if no VLAN is associated with this HFI.
ip_origin: The source of Ethernet L3 configuration information used by the driver or 0 if not used.
ipaddr: The IPv4 or IPv6 address of this HFI.
subnet_mask_prefix: The IPv4 or IPv6 subnet mask in CIDR routing prefix notation.
gateway_ipaddr: The IPv4 or IPv6 address of the IP gateway for this HFI or zeroes if no IP gateway is specified.
route_metric: The cost value for the route indicated by this HFI.
primary_dns_ipaddr: The IPv4 or IPv6 address of the Primary DNS server for this HFI.
secondary_dns_ipaddr: The IPv4 or IPv6 address of the Secondary DNS server for this HFI.
dhcp_server_ipaddr: The IPv4 or IPv6 address of the DHCP server used to assign this HFI address.
host_name: The Host Name string.
this_hfi_is_default_route: If True, then the BIOS utilized this interface described by HFI to be the default route with highest priority. If False, then routes are local to their own scope.
dhcp_override: If True, then HFI information was populated by consuming the DHCP on this interface. If False, then the HFI information was set administratively by a configuration interface to the driver and pre-OS envrionment.

struct libnbft_hfi¶: Host Fabric Interface (HFI) Descriptor

Definition

struct libnbft_hfi {
  int index;
  char transport[8];
  struct libnbft_hfi_info_tcp tcp_info;
};

Members

index: HFI Descriptor Index: indicates the number of this HFI Descriptor in the Host Fabric Interface Descriptor List.
transport: Transport Type string (e.g. ‘tcp’).
tcp_info: The HFI Transport Info Descriptor, see struct libnbft_hfi_info_tcp.

struct libnbft_discovery¶: Discovery Descriptor

Definition

struct libnbft_discovery {
  int index;
  struct libnbft_security *security;
  struct libnbft_hfi *hfi;
  char *uri;
  char *nqn;
};

Members

index: The number of this Discovery Descriptor in the Discovery Descriptor List.
security: The Security Profile Descriptor, see struct libnbft_security.
hfi: The HFI Descriptor associated with this Discovery Descriptor. See struct libnbft_hfi.
uri: A URI which indicates an NVMe Discovery controller associated with this Discovery Descriptor.
nqn: An NVMe Discovery controller NQN.

struct libnbft_security¶: Security Profile Descriptor

Definition

struct libnbft_security {
  int index;
};

Members

index: The number of this Security Profile Descriptor in the Security Profile Descriptor List.

enum libnbft_nid_type¶: Namespace Identifier Type (NIDT)

Constants

LIBNBFT_NID_TYPE_NONE: No identifier available.
LIBNBFT_NID_TYPE_EUI64: The EUI-64 identifier.
LIBNBFT_NID_TYPE_NGUID: The NSGUID identifier.
LIBNBFT_NID_TYPE_NS_UUID: The UUID identifier.

struct libnbft_subsystem_ns¶: Subsystem Namespace (SSNS) info

Definition

struct libnbft_subsystem_ns {
  int index;
  struct libnbft_discovery *discovery;
  struct libnbft_security *security;
  int num_hfis;
  struct libnbft_hfi **hfis;
  char transport[8];
  char traddr[40];
  char *trsvcid;
  __u16 subsys_port_id;
  __u32 nsid;
  enum libnbft_nid_type nid_type;
  __u8 *nid;
  char *subsys_nqn;
  bool pdu_header_digest_required;
  bool data_digest_required;
  int controller_id;
  int asqsz;
  char *dhcp_root_path_string;
  bool discovered;
  bool unavailable;
};

Members

index: SSNS Descriptor Index in the descriptor list.
discovery: Primary Discovery Controller associated with this SSNS Descriptor.
security: Security Profile Descriptor associated with this namespace.
num_hfis: Number of HFIs.
hfis: List of HFIs associated with this namespace. Includes the primary HFI at the first position and all secondary HFIs. This array is null-terminated.
transport: Transport Type string (e.g. ‘tcp’).
traddr: Subsystem Transport Address.
trsvcid: Subsystem Transport Service Identifier.
subsys_port_id: The Subsystem Port ID.
nsid: The Namespace ID of this descriptor or when nid should be used instead.
nid_type: Namespace Identifier Type, see enum libnbft_nid_type.
nid: The Namespace Identifier value.
subsys_nqn: Subsystem and Namespace NQN.
pdu_header_digest_required: PDU Header Digest (HDGST) Flag: the use of NVM Header Digest Enabled is required.
data_digest_required: Data Digest (DDGST) Flag: the use of NVM Data Digest Enabled is required.
controller_id: Controller ID (SSNS Extended Information Descriptor): The controller ID associated with the Admin Queue or 0 if not supported.
asqsz: Admin Submission Queue Size (SSNS Extended Information Descriptor) or 0 if not supported.
dhcp_root_path_string: DHCP Root Path Override string (SSNS Extended Information Descriptor).
discovered: Indicates that this namespace was acquired through discovery.
unavailable: Namespace is unavailable as indicated by the pre-OS driver.

struct libnbft_info¶: The parsed NBFT table data.

Definition

struct libnbft_info {
  char *filename;
  __u8 *raw_nbft;
  ssize_t raw_nbft_size;
  struct libnbft_host host;
  struct libnbft_hfi **hfi_list;
  struct libnbft_security **security_list;
  struct libnbft_discovery **discovery_list;
  struct libnbft_subsystem_ns **subsystem_ns_list;
};

Members

filename: Path to the NBFT table.
raw_nbft: The original NBFT table contents.
raw_nbft_size: Size of raw_nbft.
host: The Host Descriptor (should match other NBFTs).
hfi_list: The HFI Descriptor List (null-terminated array).
security_list: The Security Profile Descriptor List (null-terminated array).
discovery_list: The Discovery Descriptor List (null-terminated array).
subsystem_ns_list: The SSNS Descriptor List (null-terminated array).

int libnvmf_read_nbft(struct libnvme_global_ctx *ctx, struct libnbft_info **nbft, const char *filename)¶: Read and parse contents of an ACPI NBFT table

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
struct libnbft_info **nbft: Parsed NBFT table data.
const char *filename: Filename of the raw NBFT table to read.

Description

Read and parse the specified NBFT file into a struct libnbft_info. Free with libnvmf_free_nbft().

Return

0 on success, negative error code otherwise.

void libnvmf_free_nbft(struct libnvme_global_ctx *ctx, struct libnbft_info *nbft)¶: Free the struct libnbft_info and its contents

Parameters

struct libnvme_global_ctx *ctx: struct libnvme_global_ctx object
struct libnbft_info *nbft: Parsed NBFT table data.

struct nbft_file_entry¶: Linked list entry for NBFT files

Definition

struct nbft_file_entry {
  struct nbft_file_entry *next;
  struct libnbft_info *nbft;
};

Members

next: Pointer to next entry
nbft: Pointer to NBFT info structure

API¶

libnvme

Navigation

Related Topics