libnvme

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.

libnvme

Navigation

Related Topics