2611 lines
43 KiB
ReStructuredText
2611 lines
43 KiB
ReStructuredText
.. _tree.h:
|
|
|
|
**tree.h**
|
|
|
|
|
|
libnvme tree object interface
|
|
|
|
.. c:function:: 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 :c:type:`nvme_root_t` object
|
|
|
|
|
|
.. c:function:: void nvme_root_set_application (nvme_root_t r, const char *a)
|
|
|
|
Specify managing application
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
``const char *a``
|
|
Application string
|
|
|
|
**Description**
|
|
|
|
Sets the managing application string for **r**.
|
|
|
|
|
|
.. c:function:: const char * nvme_root_get_application (nvme_root_t r)
|
|
|
|
Get managing application
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
**Description**
|
|
|
|
Returns the managing application string for **r** or NULL if not set.
|
|
|
|
|
|
.. c:function:: void nvme_root_skip_namespaces (nvme_root_t r)
|
|
|
|
Skip namespace scanning
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
**Description**
|
|
|
|
Sets a flag to skip namespaces during scanning.
|
|
|
|
|
|
.. c:function:: void nvme_root_release_fds (nvme_root_t r)
|
|
|
|
Close all opened file descriptors in the tree
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`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.
|
|
|
|
|
|
.. c:function:: void nvme_free_tree (nvme_root_t r)
|
|
|
|
Free root object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
**Description**
|
|
|
|
Free an :c:type:`nvme_root_t` object and all attached objects
|
|
|
|
|
|
.. c:function:: nvme_host_t nvme_first_host (nvme_root_t r)
|
|
|
|
Start host iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
**Return**
|
|
|
|
First :c:type:`nvme_host_t` object in an iterator
|
|
|
|
|
|
.. c:function:: nvme_host_t nvme_next_host (nvme_root_t r, nvme_host_t h)
|
|
|
|
Next host iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
``nvme_host_t h``
|
|
Previous :c:type:`nvme_host_t` iterator
|
|
|
|
**Return**
|
|
|
|
Next :c:type:`nvme_host_t` object in an iterator
|
|
|
|
|
|
.. c:function:: nvme_root_t nvme_host_get_root (nvme_host_t h)
|
|
|
|
Returns nvme_root_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_host_t h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
**Return**
|
|
|
|
:c:type:`nvme_root_t` object from **h**
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`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**
|
|
|
|
:c:type:`nvme_host_t` object
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: nvme_host_t nvme_default_host (nvme_root_t r)
|
|
|
|
Initializes the default host
|
|
|
|
**Parameters**
|
|
|
|
``nvme_root_t r``
|
|
:c:type:`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**
|
|
|
|
:c:type:`nvme_host_t` object
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`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.
|
|
|
|
|
|
.. c:function:: nvme_subsystem_t nvme_first_subsystem (nvme_host_t h)
|
|
|
|
Start subsystem iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_host_t h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
**Return**
|
|
|
|
first :c:type:`nvme_subsystem_t` object in an iterator
|
|
|
|
|
|
.. c:function:: nvme_subsystem_t nvme_next_subsystem (nvme_host_t h, nvme_subsystem_t s)
|
|
|
|
Next subsystem iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_host_t h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
``nvme_subsystem_t s``
|
|
Previous :c:type:`nvme_subsystem_t` iterator
|
|
|
|
**Return**
|
|
|
|
next :c:type:`nvme_subsystem_t` object in an iterator
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
``const char *name``
|
|
Name of the subsystem (may be NULL)
|
|
|
|
``const char *subsysnqn``
|
|
Subsystem NQN
|
|
|
|
**Description**
|
|
|
|
Lookup a :c:type:`nvme_subsystem_t` object in **h** base on **name** (if present)
|
|
and **subsysnqn** or create one if not found.
|
|
|
|
**Return**
|
|
|
|
nvme_subsystem_t object
|
|
|
|
|
|
.. c:function:: void nvme_free_subsystem (struct nvme_subsystem *s)
|
|
|
|
Free a subsystem
|
|
|
|
**Parameters**
|
|
|
|
``struct nvme_subsystem *s``
|
|
subsystem
|
|
|
|
**Description**
|
|
|
|
Frees **s** and all related objects.
|
|
|
|
|
|
.. c:function:: nvme_host_t nvme_subsystem_get_host (nvme_subsystem_t s)
|
|
|
|
Returns nvme_host_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_subsystem_t s``
|
|
subsystem
|
|
|
|
**Return**
|
|
|
|
:c:type:`nvme_host_t` object from **s**
|
|
|
|
|
|
.. c:function:: nvme_ns_t nvme_ctrl_first_ns (nvme_ctrl_t c)
|
|
|
|
Start namespace iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ctrl_t c``
|
|
Controller instance
|
|
|
|
**Return**
|
|
|
|
First :c:type:`nvme_ns_t` object of an **c** iterator
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: nvme_path_t nvme_ctrl_first_path (nvme_ctrl_t c)
|
|
|
|
Start path iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ctrl_t c``
|
|
Controller instance
|
|
|
|
**Return**
|
|
|
|
First :c:type:`nvme_path_t` object of an **c** iterator
|
|
|
|
|
|
.. c:function:: 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 :c:type:`nvme_path_t` object of an **c** iterator
|
|
|
|
**Return**
|
|
|
|
Next :c:type:`nvme_path_t` object of an **c** iterator
|
|
|
|
|
|
.. c:function:: nvme_ctrl_t nvme_subsystem_first_ctrl (nvme_subsystem_t s)
|
|
|
|
First ctrl iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_subsystem_t s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
**Return**
|
|
|
|
First controller of an **s** iterator
|
|
|
|
|
|
.. c:function:: nvme_ctrl_t nvme_subsystem_next_ctrl (nvme_subsystem_t s, nvme_ctrl_t c)
|
|
|
|
Next ctrl iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_subsystem_t s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``nvme_ctrl_t c``
|
|
Previous controller instance of an **s** iterator
|
|
|
|
**Return**
|
|
|
|
Next controller of an **s** iterator
|
|
|
|
|
|
.. c:function:: nvme_path_t nvme_namespace_first_path (nvme_ns_t ns)
|
|
|
|
Start path iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ns_t ns``
|
|
Namespace instance
|
|
|
|
**Return**
|
|
|
|
First :c:type:`nvme_path_t` object of an **ns** iterator
|
|
|
|
|
|
.. c:function:: 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 :c:type:`nvme_path_t` object of an **ns** iterator
|
|
|
|
**Return**
|
|
|
|
Next :c:type:`nvme_path_t` object of an **ns** iterator
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`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
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: nvme_ns_t nvme_subsystem_first_ns (nvme_subsystem_t s)
|
|
|
|
Start namespace iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_subsystem_t s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
**Return**
|
|
|
|
First :c:type:`nvme_ns_t` object of an **s** iterator
|
|
|
|
|
|
.. c:function:: nvme_ns_t nvme_subsystem_next_ns (nvme_subsystem_t s, nvme_ns_t n)
|
|
|
|
Next namespace iterator
|
|
|
|
**Parameters**
|
|
|
|
``nvme_subsystem_t s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``nvme_ns_t n``
|
|
Previous :c:type:`nvme_ns_t` iterator
|
|
|
|
**Return**
|
|
|
|
Next :c:type:`nvme_ns_t` object of an **s** iterator
|
|
|
|
|
|
.. c:function:: nvme_for_each_host_safe (r, h, _h)
|
|
|
|
Traverse host list
|
|
|
|
**Parameters**
|
|
|
|
``r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
``h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
``_h``
|
|
Temporary :c:type:`nvme_host_t` object
|
|
|
|
|
|
.. c:function:: nvme_for_each_host (r, h)
|
|
|
|
Traverse host list
|
|
|
|
**Parameters**
|
|
|
|
``r``
|
|
:c:type:`nvme_root_t` object
|
|
|
|
``h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
|
|
.. c:function:: nvme_for_each_subsystem_safe (h, s, _s)
|
|
|
|
Traverse subsystems
|
|
|
|
**Parameters**
|
|
|
|
``h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``_s``
|
|
Temporary :c:type:`nvme_subsystem_t` object
|
|
|
|
|
|
.. c:function:: nvme_for_each_subsystem (h, s)
|
|
|
|
Traverse subsystems
|
|
|
|
**Parameters**
|
|
|
|
``h``
|
|
:c:type:`nvme_host_t` object
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
|
|
.. c:function:: nvme_subsystem_for_each_ctrl_safe (s, c, _c)
|
|
|
|
Traverse controllers
|
|
|
|
**Parameters**
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
``_c``
|
|
A :c:type:`nvme_ctrl_t_node` to use as temporary storage
|
|
|
|
|
|
.. c:function:: nvme_subsystem_for_each_ctrl (s, c)
|
|
|
|
Traverse controllers
|
|
|
|
**Parameters**
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
|
|
.. c:function:: nvme_ctrl_for_each_ns_safe (c, n, _n)
|
|
|
|
Traverse namespaces
|
|
|
|
**Parameters**
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
``n``
|
|
:c:type:`nvme_ns_t` object
|
|
|
|
``_n``
|
|
A :c:type:`nvme_ns_t_node` to use as temporary storage
|
|
|
|
|
|
.. c:function:: nvme_ctrl_for_each_ns (c, n)
|
|
|
|
Traverse namespaces
|
|
|
|
**Parameters**
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
``n``
|
|
:c:type:`nvme_ns_t` object
|
|
|
|
|
|
.. c:function:: nvme_ctrl_for_each_path_safe (c, p, _p)
|
|
|
|
Traverse paths
|
|
|
|
**Parameters**
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
``p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
``_p``
|
|
A :c:type:`nvme_path_t_node` to use as temporary storage
|
|
|
|
|
|
.. c:function:: nvme_ctrl_for_each_path (c, p)
|
|
|
|
Traverse paths
|
|
|
|
**Parameters**
|
|
|
|
``c``
|
|
Controller instance
|
|
|
|
``p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
|
|
.. c:function:: nvme_subsystem_for_each_ns_safe (s, n, _n)
|
|
|
|
Traverse namespaces
|
|
|
|
**Parameters**
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``n``
|
|
:c:type:`nvme_ns_t` object
|
|
|
|
``_n``
|
|
A :c:type:`nvme_ns_t_node` to use as temporary storage
|
|
|
|
|
|
.. c:function:: nvme_subsystem_for_each_ns (s, n)
|
|
|
|
Traverse namespaces
|
|
|
|
**Parameters**
|
|
|
|
``s``
|
|
:c:type:`nvme_subsystem_t` object
|
|
|
|
``n``
|
|
:c:type:`nvme_ns_t` object
|
|
|
|
|
|
.. c:function:: nvme_namespace_for_each_path_safe (n, p, _p)
|
|
|
|
Traverse paths
|
|
|
|
**Parameters**
|
|
|
|
``n``
|
|
Namespace instance
|
|
|
|
``p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
``_p``
|
|
A :c:type:`nvme_path_t_node` to use as temporary storage
|
|
|
|
|
|
.. c:function:: nvme_namespace_for_each_path (n, p)
|
|
|
|
Traverse paths
|
|
|
|
**Parameters**
|
|
|
|
``n``
|
|
Namespace instance
|
|
|
|
``p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: void nvme_ns_release_fd (nvme_ns_t n)
|
|
|
|
Close fd and clear fd from ns object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ns_t n``
|
|
Namespace instance
|
|
|
|
|
|
.. c:function:: int nvme_ns_get_nsid (nvme_ns_t n)
|
|
|
|
NSID of a namespace
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ns_t n``
|
|
Namespace instance
|
|
|
|
**Return**
|
|
|
|
NSID of **n**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: nvme_subsystem_t nvme_ns_get_subsystem (nvme_ns_t n)
|
|
|
|
:c:type:`nvme_subsystem_t` of a namespace
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ns_t n``
|
|
Namespace instance
|
|
|
|
**Return**
|
|
|
|
nvme_subsystem_t object of **n**
|
|
|
|
|
|
.. c:function:: nvme_ctrl_t nvme_ns_get_ctrl (nvme_ns_t n)
|
|
|
|
:c:type:`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
|
|
|
|
|
|
.. c:function:: void nvme_free_ns (struct nvme_ns *n)
|
|
|
|
Free a namespace object
|
|
|
|
**Parameters**
|
|
|
|
``struct nvme_ns *n``
|
|
Namespace instance
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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``
|
|
:c:type:`nvme_id_ns` buffer
|
|
|
|
**Description**
|
|
|
|
Writes the data returned by the 'identify namespace' command
|
|
into **ns**.
|
|
|
|
**Return**
|
|
|
|
0 on success, -1 on error.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: const char * nvme_path_get_name (nvme_path_t p)
|
|
|
|
sysfs name of an :c:type:`nvme_path_t` object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_path_t p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
**Return**
|
|
|
|
sysfs name of **p**
|
|
|
|
|
|
.. c:function:: const char * nvme_path_get_sysfs_dir (nvme_path_t p)
|
|
|
|
sysfs directory of an nvme_path_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_path_t p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
**Return**
|
|
|
|
sysfs directory of **p**
|
|
|
|
|
|
.. c:function:: const char * nvme_path_get_ana_state (nvme_path_t p)
|
|
|
|
ANA state of an nvme_path_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_path_t p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
**Return**
|
|
|
|
ANA (Asynchronous Namespace Access) state of **p**
|
|
|
|
|
|
.. c:function:: nvme_ctrl_t nvme_path_get_ctrl (nvme_path_t p)
|
|
|
|
Parent controller of an nvme_path_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_path_t p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
**Return**
|
|
|
|
Parent controller if present
|
|
|
|
|
|
.. c:function:: nvme_ns_t nvme_path_get_ns (nvme_path_t p)
|
|
|
|
Parent namespace of an nvme_path_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_path_t p``
|
|
:c:type:`nvme_path_t` object
|
|
|
|
**Return**
|
|
|
|
Parent namespace if present
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: void nvme_ctrl_release_fd (nvme_ctrl_t c)
|
|
|
|
Close fd and clear fd from controller object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ctrl_t c``
|
|
Controller instance
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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)
|
|
|
|
|
|
.. c:function:: 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)
|
|
|
|
|
|
.. c:function:: 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)
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: void nvme_rescan_ctrl (nvme_ctrl_t c)
|
|
|
|
Rescan an existing controller
|
|
|
|
**Parameters**
|
|
|
|
``nvme_ctrl_t c``
|
|
Controller instance
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: void nvme_free_ctrl (struct nvme_ctrl *c)
|
|
|
|
Free controller
|
|
|
|
**Parameters**
|
|
|
|
``struct nvme_ctrl *c``
|
|
Controller instance
|
|
|
|
|
|
.. c:function:: void nvme_unlink_ctrl (struct nvme_ctrl *c)
|
|
|
|
Unlink controller
|
|
|
|
**Parameters**
|
|
|
|
``struct nvme_ctrl *c``
|
|
Controller instance
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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'
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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**.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: void nvme_free_host (nvme_host_t h)
|
|
|
|
Free nvme_host_t object
|
|
|
|
**Parameters**
|
|
|
|
``nvme_host_t h``
|
|
nvme_host_t object
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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).
|
|
|
|
|
|
.. c:function:: 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).
|
|
|
|
|
|
.. c:function:: 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).
|
|
|
|
|
|
.. c:function:: 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).
|
|
|
|
|
|
.. c:function:: 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**
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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).
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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.
|
|
|
|
|
|
.. c:function:: 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
|
|
|
|
|