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_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 values in /etc/nvme/hostnqn and /etc/nvme/hostid and attaches it to r.

Return

nvme_host_t object

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_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(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(r, h)

Traverse host list

Parameters

r
nvme_root_t object
h
nvme_host_t object
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(h, s)

Traverse subsystems

Parameters

h
nvme_host_t object
s
nvme_subsystem_t object
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(s, c)

Traverse controllers

Parameters

s
nvme_subsystem_t object
c
Controller instance
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(c, n)

Traverse namespaces

Parameters

c
Controller instance
n
nvme_ns_t object
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(c, p)

Traverse paths

Parameters

c
Controller instance
p
nvme_path_t object
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(s, n)

Traverse namespaces

Parameters

s
nvme_subsystem_t object
n
nvme_ns_t object
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(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

Return

File descriptor associated with n or -1

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

Return

File descriptor associated with c or -1

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.

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 an 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

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
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’

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_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

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