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
objectconst 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
objectnvme_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
objectconst 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
objectchar *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
objectnvme_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
objectconst 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
objectnvme_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
objectconst 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
objectconst 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
objectnvme_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
objecth
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
objecth
nvme_host_t
object
-
nvme_for_each_subsystem_safe
nvme_for_each_subsystem_safe (h, s, _s)
Traverse subsystems
Parameters
h
nvme_host_t
objects
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
objects
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
objectc
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
objectc
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
objectn
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
objectn
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
-
void
nvme_unlink_ctrl
(struct nvme_ctrl *c) 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