tree.h

libnvme tree object interface

nvme_root_t nvme_create_root(FILE *fp, int log_level)

Initialize root object

Parameters

FILE *fp

File descriptor for logging messages

int log_level

Logging level to use

Return

Initialized nvme_root_t object

void nvme_root_set_application(nvme_root_t r, const char *a)

Specify managing application

Parameters

nvme_root_t r

nvme_root_t object

const char *a

Application string

Description

Sets the managing application string for r.

const char *nvme_root_get_application(nvme_root_t r)

Get managing application

Parameters

nvme_root_t r

nvme_root_t object

Description

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

void nvme_root_skip_namespaces(nvme_root_t r)

Skip namespace scanning

Parameters

nvme_root_t r

nvme_root_t object

Description

Sets a flag to skip namespaces during scanning.

void nvme_root_release_fds(nvme_root_t r)

Close all opened file descriptors in the tree

Parameters

nvme_root_t r

nvme_root_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 in the tree.

void nvme_free_tree(nvme_root_t r)

Free root object

Parameters

nvme_root_t r

nvme_root_t object

Description

Free an nvme_root_t object and all attached objects

nvme_host_t nvme_first_host(nvme_root_t r)

Start host iterator

Parameters

nvme_root_t r

nvme_root_t object

Return

First nvme_host_t object in an iterator

nvme_host_t nvme_next_host(nvme_root_t r, nvme_host_t h)

Next host iterator

Parameters

nvme_root_t r

nvme_root_t object

nvme_host_t h

Previous nvme_host_t iterator

Return

Next nvme_host_t object in an iterator

nvme_root_t nvme_host_get_root(nvme_host_t h)

Returns nvme_root_t object

Parameters

nvme_host_t h

nvme_host_t object

Return

nvme_root_t object from h

nvme_host_t nvme_lookup_host(nvme_root_t r, const char *hostnqn, const char *hostid)

Lookup nvme_host_t object

Parameters

nvme_root_t r

nvme_root_t object

const char *hostnqn

Host NQN

const char *hostid

Host ID

Description

Lookup a nvme_host_t object based on hostnqn and hostid or create one if not found.

Return

nvme_host_t object

const char *nvme_host_get_dhchap_key(nvme_host_t h)

Return host key

Parameters

nvme_host_t h

Host for which the key should be returned

Return

DH-HMAC-CHAP host key or NULL if not set

void nvme_host_set_dhchap_key(nvme_host_t h, const char *key)

set host key

Parameters

nvme_host_t h

Host for which the key should be set

const char *key

DH-HMAC-CHAP Key to set or NULL to clear existing key

void nvme_host_set_pdc_enabled(nvme_host_t h, bool enabled)

Set Persistent Discovery Controller flag

Parameters

nvme_host_t h

Host for which the falg should be set

bool enabled

The bool to set the enabled flag

Description

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

bool nvme_host_is_pdc_enabled(nvme_host_t h, bool fallback)

Is Persistenct Discovery Controller enabled

Parameters

nvme_host_t h

Host which to check if PDC is enabled

bool fallback

The fallback default value of the flag when nvme_host_set_pdc_enabled has not be used to set the flag.

Return

true if PDC is enabled for h, else false

nvme_host_t nvme_default_host(nvme_root_t r)

Initializes the default host

Parameters

nvme_root_t r

nvme_root_t object

Description

Initializes the default host object based on the hostnqn/hostid values returned by nvme_host_get_ids() and attaches it to r.

Return

nvme_host_t object

int nvme_host_get_ids(nvme_root_t r, char *hostnqn_arg, char *hostid_arg, char **hostnqn, char **hostid)

Retrieve host ids from various sources

Parameters

nvme_root_t r

nvme_root_t object

char *hostnqn_arg

Input hostnqn (command line) argument

char *hostid_arg

Input hostid (command line) argument

char **hostnqn

Output hostnqn

char **hostid

Output hostid

Description

nvme_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), -1 otherwise and errno is set.

nvme_subsystem_t nvme_first_subsystem(nvme_host_t h)

Start subsystem iterator

Parameters

nvme_host_t h

nvme_host_t object

Return

first nvme_subsystem_t object in an iterator

nvme_subsystem_t nvme_next_subsystem(nvme_host_t h, nvme_subsystem_t s)

Next subsystem iterator

Parameters

nvme_host_t h

nvme_host_t object

nvme_subsystem_t s

Previous nvme_subsystem_t iterator

Return

next nvme_subsystem_t object in an iterator

nvme_subsystem_t nvme_lookup_subsystem(struct nvme_host *h, const char *name, const char *subsysnqn)

Lookup nvme_subsystem_t object

Parameters

struct nvme_host *h

nvme_host_t object

const char *name

Name of the subsystem (may be NULL)

const char *subsysnqn

Subsystem NQN

Description

Lookup a nvme_subsystem_t object in h base on name (if present) and subsysnqn or create one if not found.

Return

nvme_subsystem_t object

void nvme_free_subsystem(struct nvme_subsystem *s)

Free a subsystem

Parameters

struct nvme_subsystem *s

subsystem

Description

Frees s and all related objects.

nvme_host_t nvme_subsystem_get_host(nvme_subsystem_t s)

Returns nvme_host_t object

Parameters

nvme_subsystem_t s

subsystem

Return

nvme_host_t object from s

nvme_ns_t nvme_ctrl_first_ns(nvme_ctrl_t c)

Start namespace iterator

Parameters

nvme_ctrl_t c

Controller instance

Return

First nvme_ns_t object of an c iterator

nvme_ns_t nvme_ctrl_next_ns(nvme_ctrl_t c, nvme_ns_t n)

Next namespace iterator

Parameters

nvme_ctrl_t c

Controller instance

nvme_ns_t n

Previous nvme_ns_t iterator

Return

Next nvme_ns_t object of an c iterator

nvme_path_t nvme_ctrl_first_path(nvme_ctrl_t c)

Start path iterator

Parameters

nvme_ctrl_t c

Controller instance

Return

First nvme_path_t object of an c iterator

nvme_path_t nvme_ctrl_next_path(nvme_ctrl_t c, nvme_path_t p)

Next path iterator

Parameters

nvme_ctrl_t c

Controller instance

nvme_path_t p

Previous nvme_path_t object of an c iterator

Return

Next nvme_path_t object of an c iterator

nvme_ctrl_t nvme_subsystem_first_ctrl(nvme_subsystem_t s)

First ctrl iterator

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

First controller of an s iterator

nvme_ctrl_t nvme_subsystem_next_ctrl(nvme_subsystem_t s, nvme_ctrl_t c)

Next ctrl iterator

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

nvme_ctrl_t c

Previous controller instance of an s iterator

Return

Next controller of an s iterator

nvme_path_t nvme_namespace_first_path(nvme_ns_t ns)

Start path iterator

Parameters

nvme_ns_t ns

Namespace instance

Return

First nvme_path_t object of an ns iterator

nvme_path_t nvme_namespace_next_path(nvme_ns_t ns, nvme_path_t p)

Next path iterator

Parameters

nvme_ns_t ns

Namespace instance

nvme_path_t p

Previous nvme_path_t object of an ns iterator

Return

Next nvme_path_t object of an ns iterator

nvme_ctrl_t nvme_lookup_ctrl(nvme_subsystem_t s, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid, nvme_ctrl_t p)

Lookup nvme_ctrl_t object

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

const char *transport

Transport name

const char *traddr

Transport address

const char *host_traddr

Host transport address

const char *host_iface

Host interface name

const char *trsvcid

Transport service identifier

nvme_ctrl_t p

Previous controller instance

Description

Lookup a controller in s based on transport, traddr, host_traddr, host_iface, and trsvcid. transport must be specified, other fields may be required depending on the transport. A new object is created if none is found. If p is specified the lookup will start at p instead of the first controller.

Return

Controller instance

nvme_ctrl_t nvme_ctrl_find(nvme_subsystem_t s, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)

Locate an existing controller

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

const char *transport

Transport name

const char *traddr

Transport address

const char *trsvcid

Transport service identifier

const char *subsysnqn

Subsystem NQN

const char *host_traddr

Host transport address

const char *host_iface

Host interface name

Description

Lookup a controller in s based on transport, traddr, trsvcid, subsysnqn, host_traddr, and host_iface. transport must be specified, other fields may be required depending on the transport. Parameters set to NULL will be ignored.

Unlike nvme_lookup_ctrl(), this function does not create a new object if an existing controller cannot be found.

Return

Controller instance on success, NULL otherwise.

bool nvme_ctrl_config_match(struct nvme_ctrl *c, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)

Check if ctrl c matches config params

Parameters

struct nvme_ctrl *c

An existing controller instance

const char *transport

Transport name

const char *traddr

Transport address

const char *trsvcid

Transport service identifier

const char *subsysnqn

Subsystem NQN

const char *host_traddr

Host transport address

const char *host_iface

Host interface name

Description

Check that controller c matches parameters: transport, traddr, trsvcid, subsysnqn, host_traddr, and host_iface. Parameters set to NULL will be ignored.

Return

true if there’s a match, false otherwise.

nvme_ctrl_t nvme_create_ctrl(nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid)

Allocate an unconnected NVMe controller

Parameters

nvme_root_t r

NVMe root element

const char *subsysnqn

Subsystem NQN

const char *transport

Transport type

const char *traddr

Transport address

const char *host_traddr

Host transport address

const char *host_iface

Host interface name

const char *trsvcid

Transport service ID

Description

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

Return

Controller instance

nvme_ns_t nvme_subsystem_first_ns(nvme_subsystem_t s)

Start namespace iterator

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

First nvme_ns_t object of an s iterator

nvme_ns_t nvme_subsystem_next_ns(nvme_subsystem_t s, nvme_ns_t n)

Next namespace iterator

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

nvme_ns_t n

Previous nvme_ns_t iterator

Return

Next nvme_ns_t object of an s iterator

nvme_for_each_host_safe

nvme_for_each_host_safe (r, h, _h)

Traverse host list

Parameters

r

nvme_root_t object

h

nvme_host_t object

_h

Temporary nvme_host_t object

nvme_for_each_host

nvme_for_each_host (r, h)

Traverse host list

Parameters

r

nvme_root_t object

h

nvme_host_t object

nvme_for_each_subsystem_safe

nvme_for_each_subsystem_safe (h, s, _s)

Traverse subsystems

Parameters

h

nvme_host_t object

s

nvme_subsystem_t object

_s

Temporary nvme_subsystem_t object

nvme_for_each_subsystem

nvme_for_each_subsystem (h, s)

Traverse subsystems

Parameters

h

nvme_host_t object

s

nvme_subsystem_t object

nvme_subsystem_for_each_ctrl_safe

nvme_subsystem_for_each_ctrl_safe (s, c, _c)

Traverse controllers

Parameters

s

nvme_subsystem_t object

c

Controller instance

_c

A nvme_ctrl_t_node to use as temporary storage

nvme_subsystem_for_each_ctrl

nvme_subsystem_for_each_ctrl (s, c)

Traverse controllers

Parameters

s

nvme_subsystem_t object

c

Controller instance

nvme_ctrl_for_each_ns_safe

nvme_ctrl_for_each_ns_safe (c, n, _n)

Traverse namespaces

Parameters

c

Controller instance

n

nvme_ns_t object

_n

A nvme_ns_t_node to use as temporary storage

nvme_ctrl_for_each_ns

nvme_ctrl_for_each_ns (c, n)

Traverse namespaces

Parameters

c

Controller instance

n

nvme_ns_t object

nvme_ctrl_for_each_path_safe

nvme_ctrl_for_each_path_safe (c, p, _p)

Traverse paths

Parameters

c

Controller instance

p

nvme_path_t object

_p

A nvme_path_t_node to use as temporary storage

nvme_ctrl_for_each_path

nvme_ctrl_for_each_path (c, p)

Traverse paths

Parameters

c

Controller instance

p

nvme_path_t object

nvme_subsystem_for_each_ns_safe

nvme_subsystem_for_each_ns_safe (s, n, _n)

Traverse namespaces

Parameters

s

nvme_subsystem_t object

n

nvme_ns_t object

_n

A nvme_ns_t_node to use as temporary storage

nvme_subsystem_for_each_ns

nvme_subsystem_for_each_ns (s, n)

Traverse namespaces

Parameters

s

nvme_subsystem_t object

n

nvme_ns_t object

nvme_namespace_for_each_path_safe

nvme_namespace_for_each_path_safe (n, p, _p)

Traverse paths

Parameters

n

Namespace instance

p

nvme_path_t object

_p

A nvme_path_t_node to use as temporary storage

nvme_namespace_for_each_path

nvme_namespace_for_each_path (n, p)

Traverse paths

Parameters

n

Namespace instance

p

nvme_path_t object

int nvme_ns_get_fd(nvme_ns_t n)

Get associated file descriptor

Parameters

nvme_ns_t n

Namespace instance

Description

libnvme will open() the file (if not already opened) and keep an internal copy of the file descriptor. Following calls to this API retrieve the internal cached copy of the file descriptor. The file will remain opened and the fd will remain cached until the ns object is deleted or nvme_ns_release_fd() is called.

Return

File descriptor associated with n or -1

void nvme_ns_release_fd(nvme_ns_t n)

Close fd and clear fd from ns object

Parameters

nvme_ns_t n

Namespace instance

int nvme_ns_get_nsid(nvme_ns_t n)

NSID of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

NSID of n

int nvme_ns_get_lba_size(nvme_ns_t n)

LBA size of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

LBA size of n

int nvme_ns_get_meta_size(nvme_ns_t n)

Metadata size of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

Metadata size of n

uint64_t nvme_ns_get_lba_count(nvme_ns_t n)

LBA count of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

LBA count of n

uint64_t nvme_ns_get_lba_util(nvme_ns_t n)

LBA utilization of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

LBA utilization of n

enum nvme_csi nvme_ns_get_csi(nvme_ns_t n)

Command set identifier of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

The namespace’s command set identifier in use

const uint8_t *nvme_ns_get_eui64(nvme_ns_t n)

64-bit eui of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

A pointer to the 64-bit eui

const uint8_t *nvme_ns_get_nguid(nvme_ns_t n)

128-bit nguid of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

A pointer to the 128-bit nguid

void nvme_ns_get_uuid(nvme_ns_t n, unsigned char out[NVME_UUID_LEN])

UUID of a namespace

Parameters

nvme_ns_t n

Namespace instance

unsigned char out[NVME_UUID_LEN]

buffer for the UUID

Description

Copies the namespace’s uuid into out

const char *nvme_ns_get_sysfs_dir(nvme_ns_t n)

sysfs directory of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

sysfs directory name of n

const char *nvme_ns_get_name(nvme_ns_t n)

sysfs name of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

sysfs name of n

const char *nvme_ns_get_generic_name(nvme_ns_t n)

Returns name of generic namespace chardev.

Parameters

nvme_ns_t n

Namespace instance

Return

Name of generic namespace chardev

const char *nvme_ns_get_firmware(nvme_ns_t n)

Firmware string of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

Firmware string of n

const char *nvme_ns_get_serial(nvme_ns_t n)

Serial number of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

Serial number string of n

const char *nvme_ns_get_model(nvme_ns_t n)

Model of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

Model string of n

nvme_subsystem_t nvme_ns_get_subsystem(nvme_ns_t n)

nvme_subsystem_t of a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

nvme_subsystem_t object of n

nvme_ctrl_t nvme_ns_get_ctrl(nvme_ns_t n)

nvme_ctrl_t of a namespace

Parameters

nvme_ns_t n

Namespace instance

Description

nvme_ctrl_t object may be NULL for a multipathed namespace

Return

nvme_ctrl_t object of n if present

void nvme_free_ns(struct nvme_ns *n)

Free a namespace object

Parameters

struct nvme_ns *n

Namespace instance

int nvme_ns_read(nvme_ns_t n, void *buf, off_t offset, size_t count)

Read from a namespace

Parameters

nvme_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 nvme_ns_write(nvme_ns_t n, void *buf, off_t offset, size_t count)

Write to a namespace

Parameters

nvme_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 nvme_ns_verify(nvme_ns_t n, off_t offset, size_t count)

Verify data on a namespace

Parameters

nvme_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 nvme_ns_compare(nvme_ns_t n, void *buf, off_t offset, size_t count)

Compare data on a namespace

Parameters

nvme_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 nvme_ns_write_zeros(nvme_ns_t n, off_t offset, size_t count)

Write zeros to a namespace

Parameters

nvme_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 nvme_ns_write_uncorrectable(nvme_ns_t n, off_t offset, size_t count)

Issus a ‘write uncorrectable’ command

Parameters

nvme_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 nvme_ns_flush(nvme_ns_t n)

Flush data to a namespace

Parameters

nvme_ns_t n

Namespace instance

Return

0 on success, -1 on error.

int nvme_ns_identify(nvme_ns_t n, struct nvme_id_ns *ns)

Issue an ‘identify namespace’ command

Parameters

nvme_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, -1 on error.

int nvme_ns_identify_descs(nvme_ns_t n, struct nvme_ns_id_desc *descs)

Issue an ‘identify descriptors’ command

Parameters

nvme_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, -1 on error.

const char *nvme_path_get_name(nvme_path_t p)

sysfs name of an nvme_path_t object

Parameters

nvme_path_t p

nvme_path_t object

Return

sysfs name of p

const char *nvme_path_get_sysfs_dir(nvme_path_t p)

sysfs directory of an nvme_path_t object

Parameters

nvme_path_t p

nvme_path_t object

Return

sysfs directory of p

const char *nvme_path_get_ana_state(nvme_path_t p)

ANA state of an nvme_path_t object

Parameters

nvme_path_t p

nvme_path_t object

Return

ANA (Asynchronous Namespace Access) state of p

nvme_ctrl_t nvme_path_get_ctrl(nvme_path_t p)

Parent controller of an nvme_path_t object

Parameters

nvme_path_t p

nvme_path_t object

Return

Parent controller if present

nvme_ns_t nvme_path_get_ns(nvme_path_t p)

Parent namespace of an nvme_path_t object

Parameters

nvme_path_t p

nvme_path_t object

Return

Parent namespace if present

int nvme_ctrl_get_fd(nvme_ctrl_t c)

Get associated file descriptor

Parameters

nvme_ctrl_t c

Controller instance

Description

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

Return

File descriptor associated with c or -1

void nvme_ctrl_release_fd(nvme_ctrl_t c)

Close fd and clear fd from controller object

Parameters

nvme_ctrl_t c

Controller instance

const char *nvme_ctrl_get_name(nvme_ctrl_t c)

sysfs name of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

sysfs name of c

const char *nvme_ctrl_get_sysfs_dir(nvme_ctrl_t c)

sysfs directory of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

sysfs directory name of c

const char *nvme_ctrl_get_address(nvme_ctrl_t c)

Address string of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

NVMe-over-Fabrics address string of c or empty string of no address is present.

char *nvme_ctrl_get_src_addr(nvme_ctrl_t c, char *src_addr, size_t src_addr_len)

Extract src_addr from the c->address string

Parameters

nvme_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 *nvme_ctrl_get_phy_slot(nvme_ctrl_t c)

PCI physical slot number of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

PCI physical slot number of c or empty string if slot number is not present.

const char *nvme_ctrl_get_firmware(nvme_ctrl_t c)

Firmware string of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Firmware string of c

const char *nvme_ctrl_get_model(nvme_ctrl_t c)

Model of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Model string of c

const char *nvme_ctrl_get_state(nvme_ctrl_t c)

Running state of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

String indicating the running state of c

const char *nvme_ctrl_get_numa_node(nvme_ctrl_t c)

NUMA node of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

String indicating the NUMA node

const char *nvme_ctrl_get_queue_count(nvme_ctrl_t c)

Queue count of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Queue count of c

const char *nvme_ctrl_get_serial(nvme_ctrl_t c)

Serial number of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Serial number string of c

const char *nvme_ctrl_get_sqsize(nvme_ctrl_t c)

SQ size of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

SQ size (as string) of c

const char *nvme_ctrl_get_transport(nvme_ctrl_t c)

Transport type of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Transport type of c

const char *nvme_ctrl_get_subsysnqn(nvme_ctrl_t c)

Subsystem NQN of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Subsystem NQN of c

nvme_subsystem_t nvme_ctrl_get_subsystem(nvme_ctrl_t c)

Parent subsystem of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Parent nvme_subsystem_t object

const char *nvme_ctrl_get_traddr(nvme_ctrl_t c)

Transport address of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Transport address of c

const char *nvme_ctrl_get_trsvcid(nvme_ctrl_t c)

Transport service identifier of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Transport service identifier of c (if present)

const char *nvme_ctrl_get_host_traddr(nvme_ctrl_t c)

Host transport address of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Host transport address of c (if present)

const char *nvme_ctrl_get_host_iface(nvme_ctrl_t c)

Host interface name of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Host interface name of c (if present)

const char *nvme_ctrl_get_dhchap_host_key(nvme_ctrl_t c)

Return host key

Parameters

nvme_ctrl_t c

Controller to be checked

Return

DH-HMAC-CHAP host key or NULL if not set

const char *nvme_ctrl_get_cntlid(nvme_ctrl_t c)

Controller id

Parameters

nvme_ctrl_t c

Controller to be checked

Return

Controller id of c

void nvme_ctrl_set_dhchap_host_key(nvme_ctrl_t c, const char *key)

Set host key

Parameters

nvme_ctrl_t c

Host for which the key should be set

const char *key

DH-HMAC-CHAP Key to set or NULL to clear existing key

const char *nvme_ctrl_get_dhchap_key(nvme_ctrl_t c)

Return controller key

Parameters

nvme_ctrl_t c

Controller for which the key should be set

Return

DH-HMAC-CHAP controller key or NULL if not set

void nvme_ctrl_set_dhchap_key(nvme_ctrl_t c, const char *key)

Set controller key

Parameters

nvme_ctrl_t c

Controller for which the key should be set

const char *key

DH-HMAC-CHAP Key to set or NULL to clear existing key

const char *nvme_ctrl_get_keyring(nvme_ctrl_t c)

Return keyring

Parameters

nvme_ctrl_t c

Controller to be used for the lookup

Return

Keyring or NULL if not set

void nvme_ctrl_set_keyring(nvme_ctrl_t c, const char *keyring)

Set keyring

Parameters

nvme_ctrl_t c

Controller for which the keyring should be set

const char *keyring

Keyring name

const char *nvme_ctrl_get_tls_key_identity(nvme_ctrl_t c)

Return Derive TLS Identity

Parameters

nvme_ctrl_t c

Controller to be used for the lookup

Return

Derive TLS Identity or NULL if not set

void nvme_ctrl_set_tls_key_identity(nvme_ctrl_t c, const char *identity)

Set Derive TLS Identity

Parameters

nvme_ctrl_t c

Controller for which the key should be set

const char *identity

Derive TLS identity or NULL to clear existing key

const char *nvme_ctrl_get_tls_key(nvme_ctrl_t c)

Return Derive TLS PSK

Parameters

nvme_ctrl_t c

Controller to be used for the lookup

Return

Key in PSK interchange format or NULL if not set

void nvme_ctrl_set_tls_key(nvme_ctrl_t c, const char *key)

Set Derive TLS PSK

Parameters

nvme_ctrl_t c

Controller for which the key should be set

const char *key

Key in interchange format or NULL to clear existing key

struct nvme_fabrics_config *nvme_ctrl_get_config(nvme_ctrl_t c)

Fabrics configuration of a controller

Parameters

nvme_ctrl_t c

Controller instance

Return

Fabrics configuration of c

void nvme_ctrl_set_discovered(nvme_ctrl_t c, bool discovered)

Set the ‘discovered’ flag

Parameters

nvme_ctrl_t c

nvme_ctrl_t object

bool discovered

Value of the ‘discovered’ flag

Description

Set the ‘discovered’ flag of c to discovered

bool nvme_ctrl_is_discovered(nvme_ctrl_t c)

Returns the value of the ‘discovered’ flag

Parameters

nvme_ctrl_t c

Controller instance

Return

Value of the ‘discovered’ flag of c

void nvme_ctrl_set_persistent(nvme_ctrl_t c, bool persistent)

Set the ‘persistent’ flag

Parameters

nvme_ctrl_t c

Controller instance

bool persistent

value of the ‘persistent’ flag

Description

Set the ‘persistent’ flag of c to persistent

bool nvme_ctrl_is_persistent(nvme_ctrl_t c)

Returns the value of the ‘persistent’ flag

Parameters

nvme_ctrl_t c

Controller instance

Return

Value of the ‘persistent’ flag of c

void nvme_ctrl_set_discovery_ctrl(nvme_ctrl_t c, bool discovery)

Set the ‘discovery_ctrl’ flag

Parameters

nvme_ctrl_t c

Controller to be modified

bool discovery

value of the discovery_ctrl flag

Description

Sets the ‘discovery_ctrl’ flag in c to specify whether c connects to a discovery subsystem.

bool nvme_ctrl_is_discovery_ctrl(nvme_ctrl_t c)

Check the ‘discovery_ctrl’ flag

Parameters

nvme_ctrl_t c

Controller to be checked

Description

Returns the value of the ‘discovery_ctrl’ flag which specifies whether c connects to a discovery subsystem.

Return

Value of the ‘discover_ctrl’ flag

void nvme_ctrl_set_unique_discovery_ctrl(nvme_ctrl_t c, bool unique)

Set the ‘unique_discovery_ctrl’ flag

Parameters

nvme_ctrl_t c

Controller to be modified

bool unique

value of the unique_disc_ctrl flag

Description

Sets the ‘unique_discovery_ctrl’ flag in c to specify wheter c is a unique discovery controller

bool nvme_ctrl_is_unique_discovery_ctrl(nvme_ctrl_t c)

Check the ‘unique_discovery_ctrl’ flag

Parameters

nvme_ctrl_t c

Controller to be checked

Return

Value of the ‘unique_discovery_ctrl’ flag

int nvme_ctrl_identify(nvme_ctrl_t c, struct nvme_id_ctrl *id)

Issues an ‘identify controller’ command

Parameters

nvme_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 or -1 on failure.

int nvme_disconnect_ctrl(nvme_ctrl_t c)

Disconnect a controller

Parameters

nvme_ctrl_t c

Controller instance

Description

Issues a ‘disconnect’ fabrics command to c

Return

0 on success, -1 on failure.

nvme_ctrl_t nvme_scan_ctrl(nvme_root_t r, const char *name)

Scan on a controller

Parameters

nvme_root_t r

nvme_root_t object

const char *name

Name of the controller

Description

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

Return

nvme_ctrl_t object

void nvme_rescan_ctrl(nvme_ctrl_t c)

Rescan an existing controller

Parameters

nvme_ctrl_t c

Controller instance

int nvme_init_ctrl(nvme_host_t h, nvme_ctrl_t c, int instance)

Initialize nvme_ctrl_t object for an existing controller.

Parameters

nvme_host_t h

nvme_host_t object

nvme_ctrl_t c

nvme_ctrl_t object

int instance

Instance number (e.g. 1 for nvme1)

Return

The ioctl() return code. Typically 0 on success.

void nvme_free_ctrl(struct nvme_ctrl *c)

Free controller

Parameters

struct nvme_ctrl *c

Controller instance

Unlink controller

Parameters

struct nvme_ctrl *c

Controller instance

const char *nvme_subsystem_get_nqn(nvme_subsystem_t s)

Retrieve NQN from subsystem

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

NQN of subsystem

const char *nvme_subsystem_get_sysfs_dir(nvme_subsystem_t s)

sysfs directory of an nvme_subsystem_t object

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

sysfs directory name of s

const char *nvme_subsystem_get_name(nvme_subsystem_t s)

sysfs name of an nvme_subsystem_t object

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

sysfs name of s

const char *nvme_subsystem_get_type(nvme_subsystem_t s)

Returns the type of a subsystem

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Description

Returns the subsystem type of s.

Return

‘nvm’ or ‘discovery’

const char *nvme_subsystem_get_application(nvme_subsystem_t s)

Return the application string

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

Managing application string or NULL if not set.

void nvme_subsystem_set_application(nvme_subsystem_t s, const char *a)

Set the application string

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

const char *a

application string

Description

Sets the managing application string for s.

const char *nvme_subsystem_get_iopolicy(nvme_subsystem_t s)

Return the IO policy of subsytem

Parameters

nvme_subsystem_t s

nvme_subsystem_t object

Return

IO policy used by current subsystem

int nvme_scan_topology(nvme_root_t r, nvme_scan_filter_t f, void *f_args)

Scan NVMe topology and apply filter

Parameters

nvme_root_t r

nvme_root_t object

nvme_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

Number of elements scanned

const char *nvme_host_get_hostnqn(nvme_host_t h)

Host NQN of an nvme_host_t object

Parameters

nvme_host_t h

nvme_host_t object

Return

Host NQN of h

const char *nvme_host_get_hostid(nvme_host_t h)

Host ID of an nvme_host_t object

Parameters

nvme_host_t h

nvme_host_t object

Return

Host ID of h

void nvme_host_release_fds(struct nvme_host *h)

Close all opened file descriptors under host

Parameters

struct nvme_host *h

nvme_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 nvme_free_host(nvme_host_t h)

Free nvme_host_t object

Parameters

nvme_host_t h

nvme_host_t object

nvme_root_t nvme_scan(const char *config_file)

Scan NVMe topology

Parameters

const char *config_file

Configuration file

Return

nvme_root_t object of found elements

int nvme_read_config(nvme_root_t r, const char *config_file)

Read NVMe JSON configuration file

Parameters

nvme_root_t r

nvme_root_t 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, -1 on failure with errno set.

void nvme_refresh_topology(nvme_root_t r)

Refresh nvme_root_t object contents

Parameters

nvme_root_t r

nvme_root_t object

Description

Removes all elements in r and rescans the existing topology.

int nvme_update_config(nvme_root_t r)

Update JSON configuration

Parameters

nvme_root_t r

nvme_root_t object

Description

Updates the JSON configuration file with the contents of r.

Return

0 on success, -1 on failure.

int nvme_dump_config(nvme_root_t r)

Print the JSON configuration

Parameters

nvme_root_t r

nvme_root_t object

Description

Prints the current contents of the JSON configuration file to stdout.

Return

0 on success, -1 on failure.

int nvme_dump_tree(nvme_root_t r)

Dump internal object tree

Parameters

nvme_root_t r

nvme_root_t object

Description

Prints the internal object tree in JSON format to stdout.

Return

0 on success, -1 on failure.

char *nvme_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 in case of an error (indicated by non-zero errno code).

char *nvme_get_subsys_attr(nvme_subsystem_t s, const char *attr)

Read subsystem sysfs attribute

Parameters

nvme_subsystem_t s

nvme_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 in case of an error (indicated by non-zero errno code).

char *nvme_get_ctrl_attr(nvme_ctrl_t c, const char *attr)

Read controller sysfs attribute

Parameters

nvme_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 (indicated by non-zero errno code).

char *nvme_get_ns_attr(nvme_ns_t n, const char *attr)

Read namespace sysfs attribute

Parameters

nvme_ns_t n

nvme_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 (indicated by non-zero errno code).

nvme_ns_t nvme_subsystem_lookup_namespace(struct nvme_subsystem *s, __u32 nsid)

lookup namespace by NSID

Parameters

struct nvme_subsystem *s

nvme_subsystem_t object

__u32 nsid

Namespace id

Return

nvme_ns_t of the namespace with id nsid in subsystem s

void nvme_subsystem_release_fds(struct nvme_subsystem *s)

Close all opened fds under subsystem

Parameters

struct nvme_subsystem *s

nvme_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 *nvme_get_path_attr(nvme_path_t p, const char *attr)

Read path sysfs attribute

Parameters

nvme_path_t p

nvme_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 (indicated by non-zero errno code).

nvme_ns_t nvme_scan_namespace(const char *name)

scan namespace based on sysfs name

Parameters

const char *name

sysfs name of the namespace to scan

Return

nvme_ns_t object or NULL if not found.

const char *nvme_host_get_hostsymname(nvme_host_t h)

Get the host’s symbolic name

Parameters

nvme_host_t h

Host for which the symbolic name should be returned.

Return

The symbolic name or NULL if a symbolic name hasn’t been configure.

void nvme_host_set_hostsymname(nvme_host_t h, const char *hostsymname)

Set the host’s symbolic name

Parameters

nvme_host_t h

Host for which the symbolic name should be set.

const char *hostsymname

Symbolic name