summaryrefslogtreecommitdiffstats
path: root/doc/rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2023-12-24 07:51:48 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-12-24 07:51:48 +0000
commit8d843cc9cc0e989d3929f204f77223cd08730c7a (patch)
tree1fcba17d10325d9d7ccb68b2eb48cd9bbba6a534 /doc/rst
parentReleasing debian version 1.5-3. (diff)
downloadlibnvme-8d843cc9cc0e989d3929f204f77223cd08730c7a.tar.xz
libnvme-8d843cc9cc0e989d3929f204f77223cd08730c7a.zip
Merging upstream version 1.7.1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/rst')
-rw-r--r--doc/rst/ioctl.rst334
-rw-r--r--doc/rst/linux.rst139
-rw-r--r--doc/rst/log.rst19
-rw-r--r--doc/rst/mi.rst33
-rw-r--r--doc/rst/tree.rst202
-rw-r--r--doc/rst/types.rst469
-rw-r--r--doc/rst/util.rst117
7 files changed, 1287 insertions, 26 deletions
diff --git a/doc/rst/ioctl.rst b/doc/rst/ioctl.rst
index a2f3b86..4d8af34 100644
--- a/doc/rst/ioctl.rst
+++ b/doc/rst/ioctl.rst
@@ -1081,7 +1081,7 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
-.. c:function:: int nvme_identify_secondary_ctrl_list (int fd, __u32 nsid, __u16 cntid, struct nvme_secondary_ctrl_list *sc_list)
+.. c:function:: int nvme_identify_secondary_ctrl_list (int fd, __u16 cntid, struct nvme_secondary_ctrl_list *sc_list)
Retrieves secondary controller list
@@ -1090,9 +1090,6 @@ The nvme command status if a response was received (see
``int fd``
File descriptor of nvme device
-``__u32 nsid``
- Namespace identifier
-
``__u16 cntid``
Return controllers starting at this identifier
@@ -2185,6 +2182,34 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise
+.. c:function:: int nvme_get_log_phy_rx_eom (int fd, __u8 lsp, __u16 controller, __u32 len, struct nvme_phy_rx_eom_log *log)
+
+ Retrieve Physical Interface Receiver Eye Opening Measurement Log
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``__u8 lsp``
+ Log specific, controls action and measurement quality
+
+``__u16 controller``
+ Target controller ID
+
+``__u32 len``
+ The allocated size, minimum
+ struct nvme_phy_rx_eom_log
+
+``struct nvme_phy_rx_eom_log *log``
+ User address to store the log page
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise
+
+
.. c:function:: int nvme_get_log_discovery (int fd, bool rae, __u32 offset, __u32 len, void *log)
Retrieve Discovery log page
@@ -2499,7 +2524,7 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
-.. c:function:: int nvme_set_features_lba_range (int fd, __u32 nsid, __u32 nr_ranges, bool save, struct nvme_lba_range_type *data, __u32 *result)
+.. c:function:: int nvme_set_features_lba_range (int fd, __u32 nsid, __u8 nr_ranges, bool save, struct nvme_lba_range_type *data, __u32 *result)
Set LBA range feature
@@ -2511,7 +2536,7 @@ The nvme command status if a response was received (see
``__u32 nsid``
Namespace ID
-``__u32 nr_ranges``
+``__u8 nr_ranges``
Number of ranges in **data**
``bool save``
@@ -3063,6 +3088,39 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_set_features_resv_mask2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_set_features_resv_mask2 (int fd, __u32 nsid, __u32 mask, bool save, __u32 *result)
+
+ Set reservation notification mask feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``__u32 nsid``
+ Namespace ID
+
+``__u32 mask``
+ Reservation Notification Mask Field
+
+``bool save``
+ Save value across power states
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3087,6 +3145,39 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_set_features_resv_persist2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_set_features_resv_persist2 (int fd, __u32 nsid, bool ptpl, bool save, __u32 *result)
+
+ Set persist through power loss feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``__u32 nsid``
+ Namespace ID
+
+``bool ptpl``
+ Persist Through Power Loss
+
+``bool save``
+ Save value across power states
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3111,6 +3202,60 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_set_features_write_protect2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_set_features_write_protect2 (int fd, __u32 nsid, enum nvme_feat_nswpcfg_state state, bool save, __u32 *result)
+
+ Set write protect feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``__u32 nsid``
+ Namespace ID
+
+``enum nvme_feat_nswpcfg_state state``
+ Write Protection State
+
+``bool save``
+ Save value across power states
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_set_features_iocs_profile (int fd, __u16 iocsi, bool save)
+
+ Set I/O command set profile feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``__u16 iocsi``
+ I/O Command Set Combination Index
+
+``bool save``
+ Save value across power states
+
**Return**
The nvme command status if a response was received (see
@@ -3246,6 +3391,39 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_get_features_lba_range2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_features_lba_range2 (int fd, enum nvme_get_features_sel sel, __u32 nsid, struct nvme_lba_range_type *data, __u32 *result)
+
+ Get LBA range feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_get_features_sel sel``
+ Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel <nvme_get_features_sel>`
+
+``__u32 nsid``
+ Namespace ID
+
+``struct nvme_lba_range_type *data``
+ Buffer to receive LBA Range Type data structure
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3288,6 +3466,36 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_get_features_err_recovery2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_features_err_recovery2 (int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)
+
+ Get error recovery feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_get_features_sel sel``
+ Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel <nvme_get_features_sel>`
+
+``__u32 nsid``
+ Namespace ID
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3460,6 +3668,36 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't fetch the Host Memory Buffer Attributes data structure.
+Use nvme_get_features_host_mem_buf2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_features_host_mem_buf2 (int fd, enum nvme_get_features_sel sel, struct nvme_host_mem_buf_attrs *attrs, __u32 *result)
+
+ Get host memory buffer feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_get_features_sel sel``
+ Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel <nvme_get_features_sel>`
+
+``struct nvme_host_mem_buf_attrs *attrs``
+ Buffer for returned Host Memory Buffer Attributes
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3774,6 +4012,36 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_get_features_resv_mask2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_features_resv_mask2 (int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)
+
+ Get reservation mask feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_get_features_sel sel``
+ Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel <nvme_get_features_sel>`
+
+``__u32 nsid``
+ Namespace ID
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -3795,6 +4063,36 @@ The nvme command status if a response was received (see
``__u32 *result``
The command completion result from CQE dword0
+**Description**
+
+
+Deprecated: doesn't support specifying a NSID.
+Use nvme_get_features_resv_persist2() instead.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_features_resv_persist2 (int fd, enum nvme_get_features_sel sel, __u32 nsid, __u32 *result)
+
+ Get reservation persist feature
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_get_features_sel sel``
+ Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel <nvme_get_features_sel>`
+
+``__u32 nsid``
+ Namespace ID
+
+``__u32 *result``
+ The command completion result from CQE dword0
+
**Return**
The nvme command status if a response was received (see
@@ -4903,3 +5201,27 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+.. c:function:: void nvme_set_debug (bool debug)
+
+ Set NVMe command debugging output
+
+**Parameters**
+
+``bool debug``
+ true to enable or false to disable
+
+
+.. c:function:: bool nvme_get_debug (void)
+
+ Get NVMe command debugging output
+
+**Parameters**
+
+``void``
+ no arguments
+
+**Return**
+
+false if disabled or true if enabled.
+
+
diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst
index b437499..819ee68 100644
--- a/doc/rst/linux.rst
+++ b/doc/rst/linux.rst
@@ -53,6 +53,68 @@ The nvme command status if a response was received (see
Data Area 4
+.. c:function:: int nvme_get_telemetry_max (int fd, enum nvme_telemetry_da *da, size_t *max_data_tx)
+
+ Get telemetry limits
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``enum nvme_telemetry_da *da``
+ On success return max supported data area
+
+``size_t *max_data_tx``
+ On success set to max transfer chunk supported by the controller
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
+.. c:function:: int nvme_get_telemetry_log (int fd, bool create, bool ctrl, bool rae, size_t max_data_tx, enum nvme_telemetry_da da, struct nvme_telemetry_log **log, size_t *size)
+
+ Get specified telemetry log
+
+**Parameters**
+
+``int fd``
+ File descriptor of nvme device
+
+``bool create``
+ Generate new host initated telemetry capture
+
+``bool ctrl``
+ Get controller Initiated log
+
+``bool rae``
+ Retain asynchronous events
+
+``size_t max_data_tx``
+ Set the max data transfer size to be used retrieving telemetry.
+
+``enum nvme_telemetry_da da``
+ Log page data area, valid values: :c:type:`enum nvme_telemetry_da <nvme_telemetry_da>`.
+
+``struct nvme_telemetry_log **log``
+ On success, set to the value of the allocated and retrieved log.
+
+``size_t *size``
+ Ptr to the telemetry log size, so it can be returned
+
+**Description**
+
+The total size allocated can be calculated as:
+ (nvme_telemetry_log da size + 1) * NVME_LOG_TELEM_BLOCK_SIZE.
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+
+
.. c:function:: int nvme_get_ctrl_telemetry (int fd, bool rae, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size)
Get controller telemetry log
@@ -439,3 +501,80 @@ The key serial number if the key could be inserted into
the keyring or 0 with errno otherwise.
+.. c:function:: long nvme_insert_tls_key_versioned (const char *keyring, const char *key_type, const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)
+
+ Derive and insert TLS key
+
+**Parameters**
+
+``const char *keyring``
+ Keyring to use
+
+``const char *key_type``
+ Type of the resulting key
+
+``const char *hostnqn``
+ Host NVMe Qualified Name
+
+``const char *subsysnqn``
+ Subsystem NVMe Qualified Name
+
+``int version``
+ Key version to use
+
+``int hmac``
+ HMAC algorithm
+
+``unsigned char *configured_key``
+ Configured key data to derive the key from
+
+``int key_len``
+ Length of **configured_key**
+
+**Description**
+
+Derives a 'retained' TLS key as specified in NVMe TCP 1.0a (if
+**version** s set to '0') or NVMe TP8028 (if **version** is set to '1) and
+stores it as type **key_type** in the keyring specified by **keyring**.
+
+**Return**
+
+The key serial number if the key could be inserted into
+the keyring or 0 with errno otherwise.
+
+
+.. c:function:: char * nvme_generate_tls_key_identity (const char *hostnqn, const char *subsysnqn, int version, int hmac, unsigned char *configured_key, int key_len)
+
+ Generate the TLS key identity
+
+**Parameters**
+
+``const char *hostnqn``
+ Host NVMe Qualified Name
+
+``const char *subsysnqn``
+ Subsystem NVMe Qualified Name
+
+``int version``
+ Key version to use
+
+``int hmac``
+ HMAC algorithm
+
+``unsigned char *configured_key``
+ Configured key data to derive the key from
+
+``int key_len``
+ Length of **configured_key**
+
+**Description**
+
+Derives a 'retained' TLS key as specified in NVMe TCP and
+generate the corresponding TLs identity.
+
+**Return**
+
+The string containing the TLS identity. It is the responsibility
+of the caller to free the returned string.
+
+
diff --git a/doc/rst/log.rst b/doc/rst/log.rst
index 45b4689..67911a5 100644
--- a/doc/rst/log.rst
+++ b/doc/rst/log.rst
@@ -28,3 +28,22 @@ logging functions
Sets the default logging variables for the library.
+.. c:function:: void nvme_set_root (nvme_root_t r)
+
+ Set nvme_root_t context
+
+**Parameters**
+
+``nvme_root_t r``
+ nvme_root_t context
+
+**Description**
+
+In order to be able to log from code paths where no root object is passed in
+via the arguments use the the default one which can be set via this call.
+When creating a new root object with **nvme_create_root** the global root object
+will be set as well. This means the global root object is always pointing to
+the latest created root object. Note the first **nvme_free_tree** call will reset
+the global root object.
+
+
diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst
index ba0f29a..2aa7438 100644
--- a/doc/rst/mi.rst
+++ b/doc/rst/mi.rst
@@ -1923,7 +1923,7 @@ See: :c:type:`struct nvme_primary_ctrl_cap <nvme_primary_ctrl_cap>`
0 on success, non-zero on failure
-.. c:function:: int nvme_mi_admin_identify_secondary_ctrl_list (nvme_mi_ctrl_t ctrl, __u32 nsid, __u16 cntid, struct nvme_secondary_ctrl_list *list)
+.. c:function:: int nvme_mi_admin_identify_secondary_ctrl_list (nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_secondary_ctrl_list *list)
Perform an Admin identify for a secondary controller list.
@@ -1932,9 +1932,6 @@ See: :c:type:`struct nvme_primary_ctrl_cap <nvme_primary_ctrl_cap>`
``nvme_mi_ctrl_t ctrl``
Controller to process identify command
-``__u32 nsid``
- Namespace ID to specify list start
-
``__u16 cntid``
Controller ID to specify list start
@@ -2622,6 +2619,34 @@ The nvme command status if a response was received (see
:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
+.. c:function:: int nvme_mi_admin_get_log_phy_rx_eom (nvme_mi_ctrl_t ctrl, __u8 lsp, __u16 controller, __u32 len, struct nvme_phy_rx_eom_log *log)
+
+ Retrieve Physical Interface Receiver Eye Opening Measurement Log
+
+**Parameters**
+
+``nvme_mi_ctrl_t ctrl``
+ Controller to query
+
+``__u8 lsp``
+ Log specific, controls action and measurement quality
+
+``__u16 controller``
+ Target controller ID
+
+``__u32 len``
+ The allocated size, minimum
+ struct nvme_phy_rx_eom_log
+
+``struct nvme_phy_rx_eom_log *log``
+ User address to store the log page
+
+**Return**
+
+The nvme command status if a response was received (see
+:c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise
+
+
.. c:function:: int nvme_mi_admin_get_log_discovery (nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log)
Retrieve Discovery log page
diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst
index f964ec6..b73ffae 100644
--- a/doc/rst/tree.rst
+++ b/doc/rst/tree.rst
@@ -53,6 +53,22 @@ Sets the managing application string for **r**.
Returns the managing application string for **r** or NULL if not set.
+.. 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
@@ -469,6 +485,86 @@ will start at **p** instead of the first controller.
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
@@ -776,11 +872,30 @@ Next :c:type:`nvme_ns_t` object of an **s** iterator
``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
@@ -1302,11 +1417,30 @@ Parent namespace if present
``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
@@ -1350,6 +1484,26 @@ 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
@@ -1395,7 +1549,7 @@ Model string of **c**
.. c:function:: const char * nvme_ctrl_get_state (nvme_ctrl_t c)
- Running state of an controller
+ Running state of a controller
**Parameters**
@@ -1962,6 +2116,20 @@ Managing application string or NULL if not set.
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
@@ -2015,6 +2183,22 @@ Host NQN of **h**
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
@@ -2220,6 +2404,22 @@ String with the contents of **attr** or ``NULL`` in case of an empty value
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
diff --git a/doc/rst/types.rst b/doc/rst/types.rst
index 3c9725a..0ed38cf 100644
--- a/doc/rst/types.rst
+++ b/doc/rst/types.rst
@@ -607,7 +607,8 @@ power scale value
__le32 mnan;
__u8 maxdna[16];
__le32 maxcna;
- __u8 rsvd564[204];
+ __le32 oaqd;
+ __u8 rsvd568[200];
char subnqn[NVME_NQN_LENGTH];
__u8 rsvd1024[768];
__le32 ioccsz;
@@ -976,7 +977,12 @@ power scale value
maximum number of namespaces that are allowed to be attached to
this I/O controller.
-``rsvd564``
+``oaqd``
+ Optimal Aggregated Queue Depth indicates the recommended maximum
+ total number of outstanding I/O commands across all I/O queues
+ on the controller for optimal operation.
+
+``rsvd568``
Reserved
``subnqn``
@@ -1612,6 +1618,18 @@ power scale value
If set, then the controller supports
the copy command.
+``NVME_CTRL_ONCS_COPY_SINGLE_ATOMICITY``
+ If set, then the write portion of a
+ Copy command is performed as a single
+ write command to which the same
+ atomicity requirements that apply to
+ a write command apply.
+
+``NVME_CTRL_ONCS_ALL_FAST_COPY``
+ If set, then all copy operations for
+ the Copy command are fast copy
+ operations.
+
@@ -1886,8 +1904,7 @@ power scale value
__u8 nguid[16];
__u8 eui64[8];
struct nvme_lbaf lbaf[64];
- __le64 lbstm;
- __u8 vs[3704];
+ __u8 vs[3712];
};
**Members**
@@ -2070,9 +2087,6 @@ power scale value
``lbaf``
LBA Format, see :c:type:`struct nvme_lbaf <nvme_lbaf>`.
-``lbstm``
- Logical Block Storage Tag Mask for end-to-end protection
-
``vs``
Vendor Specific
@@ -4196,11 +4210,13 @@ bytes, in size. This log captures the controller’s internal state.
struct nvme_endurance_group_log {
__u8 critical_warning;
- __u8 rsvd1[2];
+ __u8 endurance_group_features;
+ __u8 rsvd2;
__u8 avl_spare;
__u8 avl_spare_threshold;
__u8 percent_used;
- __u8 rsvd6[26];
+ __le16 domain_identifier;
+ __u8 rsvd8[24];
__u8 endurance_estimate[16];
__u8 data_units_read[16];
__u8 data_units_written[16];
@@ -4209,7 +4225,9 @@ bytes, in size. This log captures the controller’s internal state.
__u8 host_write_cmds[16];
__u8 media_data_integrity_err[16];
__u8 num_err_info_log_entries[16];
- __u8 rsvd160[352];
+ __u8 total_end_grp_cap[16];
+ __u8 unalloc_end_grp_cap[16];
+ __u8 rsvd192[320];
};
**Members**
@@ -4217,7 +4235,10 @@ bytes, in size. This log captures the controller’s internal state.
``critical_warning``
Critical Warning
-``rsvd1``
+``endurance_group_features``
+ Endurance Group Features
+
+``rsvd2``
Reserved
``avl_spare``
@@ -4229,7 +4250,10 @@ bytes, in size. This log captures the controller’s internal state.
``percent_used``
Percentage Used
-``rsvd6``
+``domain_identifier``
+ Domain Identifier
+
+``rsvd8``
Reserved
``endurance_estimate``
@@ -4256,7 +4280,13 @@ bytes, in size. This log captures the controller’s internal state.
``num_err_info_log_entries``
Number of Error Information Log Entries
-``rsvd160``
+``total_end_grp_cap``
+ Total Endurance Group Capacity
+
+``unalloc_end_grp_cap``
+ Unallocated Endurance Group Capacity
+
+``rsvd192``
Reserved
@@ -5503,6 +5533,213 @@ bytes, in size. This log captures the controller’s internal state.
+.. c:struct:: nvme_eom_lane_desc
+
+ EOM Lane Descriptor
+
+**Definition**
+
+::
+
+ struct nvme_eom_lane_desc {
+ __u8 rsvd0;
+ __u8 mstatus;
+ __u8 lane;
+ __u8 eye;
+ __le16 top;
+ __le16 bottom;
+ __le16 left;
+ __le16 right;
+ __le16 nrows;
+ __le16 ncols;
+ __le16 edlen;
+ __u8 rsvd18[14];
+ __u8 eye_desc[];
+ };
+
+**Members**
+
+``rsvd0``
+ Reserved
+
+``mstatus``
+ Measurement Status
+
+``lane``
+ Lane number
+
+``eye``
+ Eye number
+
+``top``
+ Absolute number of rows from center to top edge of eye
+
+``bottom``
+ Absolute number of rows from center to bottom edge of eye
+
+``left``
+ Absolute number of rows from center to left edge of eye
+
+``right``
+ Absolute number of rows from center to right edge of eye
+
+``nrows``
+ Number of Rows
+
+``ncols``
+ Number of Columns
+
+``edlen``
+ Eye Data Length
+
+``rsvd18``
+ Reserved
+
+``eye_desc``
+ Printable Eye, Eye Data, and any Padding
+
+
+
+
+
+.. c:struct:: nvme_phy_rx_eom_log
+
+ Physical Interface Receiver Eye Opening Measurement Log
+
+**Definition**
+
+::
+
+ struct nvme_phy_rx_eom_log {
+ __u8 lid;
+ __u8 eomip;
+ __le16 hsize;
+ __le32 rsize;
+ __u8 eomdgn;
+ __u8 lr;
+ __u8 odp;
+ __u8 lanes;
+ __u8 epl;
+ __u8 lspfc;
+ __u8 li;
+ __u8 rsvd15[3];
+ __le16 lsic;
+ __le32 dsize;
+ __le16 nd;
+ __le16 maxtb;
+ __le16 maxlr;
+ __le16 etgood;
+ __le16 etbetter;
+ __le16 etbest;
+ __u8 rsvd36[28];
+ struct nvme_eom_lane_desc descs[];
+ };
+
+**Members**
+
+``lid``
+ Log Identifier
+
+``eomip``
+ EOM In Progress
+
+``hsize``
+ Header Size
+
+``rsize``
+ Result Size
+
+``eomdgn``
+ EOM Data Generation Number
+
+``lr``
+ Log Revision
+
+``odp``
+ Optional Data Present
+
+``lanes``
+ Number of lanes configured for this port
+
+``epl``
+ Eyes Per Lane
+
+``lspfc``
+ Log Specific Parameter Field Copy
+
+``li``
+ Link Information
+
+``rsvd15``
+ Reserved
+
+``lsic``
+ Log Specific Identifier Copy
+
+``dsize``
+ Descriptor Size
+
+``nd``
+ Number of Descriptors
+
+``maxtb``
+ Maximum Top Bottom
+
+``maxlr``
+ Maximum Left Right
+
+``etgood``
+ Estimated Time for Good Quality
+
+``etbetter``
+ Estimated Time for Better Quality
+
+``etbest``
+ Estimated Time for Best Quality
+
+``rsvd36``
+ Reserved
+
+``descs``
+ EOM Lane Descriptors
+
+
+
+
+
+.. c:enum:: nvme_eom_optional_data
+
+ EOM Optional Data Present Fields
+
+**Constants**
+
+``NVME_EOM_EYE_DATA_PRESENT``
+ Eye Data Present
+
+``NVME_EOM_PRINTABLE_EYE_PRESENT``
+ Printable Eye Present
+
+
+
+
+.. c:enum:: nvme_phy_rx_eom_progress
+
+ EOM In Progress Values
+
+**Constants**
+
+``NVME_PHY_RX_EOM_NOT_STARTED``
+ EOM Not Started
+
+``NVME_PHY_RX_EOM_IN_PROGRESS``
+ EOM In Progress
+
+``NVME_PHY_RX_EOM_COMPLETED``
+ EOM Completed
+
+
+
+
.. c:struct:: nvme_media_unit_stat_desc
Media Unit Status Descriptor
@@ -7232,7 +7469,11 @@ bytes, in size. This log captures the controller’s internal state.
struct nvme_feat_host_behavior {
__u8 acre;
- __u8 rsvd1[511];
+ __u8 etdas;
+ __u8 lbafee;
+ __u8 rsvd3;
+ __u16 cdfe;
+ __u8 rsvd6[506];
};
**Members**
@@ -7240,7 +7481,19 @@ bytes, in size. This log captures the controller’s internal state.
``acre``
Advanced Command Retry Enable
-``rsvd1``
+``etdas``
+ Extended Telemetry Data Area 4 Supported
+
+``lbafee``
+ LBA Format Extension Enable
+
+``rsvd3``
+ Reserved
+
+``cdfe``
+ Copy Descriptor Formats Enable
+
+``rsvd6``
Reserved
@@ -7380,6 +7633,130 @@ bytes, in size. This log captures the controller’s internal state.
+.. c:enum:: nvme_copy_range_sopt
+
+ NVMe Copy Range Source Options
+
+**Constants**
+
+``NVME_COPY_SOPT_FCO``
+ NVMe Copy Source Option Fast Copy Only
+
+
+
+
+.. c:struct:: nvme_copy_range_f2
+
+ Copy - Source Range Entries Descriptor Format 2h
+
+**Definition**
+
+::
+
+ struct nvme_copy_range_f2 {
+ __le32 snsid;
+ __u8 rsvd4[4];
+ __le64 slba;
+ __le16 nlb;
+ __u8 rsvd18[4];
+ __le16 sopt;
+ __le32 eilbrt;
+ __le16 elbat;
+ __le16 elbatm;
+ };
+
+**Members**
+
+``snsid``
+ Source Namespace Identifier
+
+``rsvd4``
+ Reserved
+
+``slba``
+ Starting LBA
+
+``nlb``
+ Number of Logical Blocks
+
+``rsvd18``
+ Reserved
+
+``sopt``
+ Source Options
+
+``eilbrt``
+ Expected Initial Logical Block Reference Tag /
+ Expected Logical Block Storage Tag
+
+``elbat``
+ Expected Logical Block Application Tag
+
+``elbatm``
+ Expected Logical Block Application Tag Mask
+
+
+
+
+
+.. c:struct:: nvme_copy_range_f3
+
+ Copy - Source Range Entries Descriptor Format 3h
+
+**Definition**
+
+::
+
+ struct nvme_copy_range_f3 {
+ __le32 snsid;
+ __u8 rsvd4[4];
+ __le64 slba;
+ __le16 nlb;
+ __u8 rsvd18[4];
+ __le16 sopt;
+ __u8 rsvd24[2];
+ __u8 elbt[10];
+ __le16 elbat;
+ __le16 elbatm;
+ };
+
+**Members**
+
+``snsid``
+ Source Namespace Identifier
+
+``rsvd4``
+ Reserved
+
+``slba``
+ Starting LBA
+
+``nlb``
+ Number of Logical Blocks
+
+``rsvd18``
+ Reserved
+
+``sopt``
+ Source Options
+
+``rsvd24``
+ Reserved
+
+``elbt``
+ Expected Initial Logical Block Reference Tag /
+ Expected Logical Block Storage Tag
+
+``elbat``
+ Expected Logical Block Application Tag
+
+``elbatm``
+ Expected Logical Block Application Tag Mask
+
+
+
+
+
.. c:struct:: nvme_registered_ctrl
Registered Controller Data Structure
@@ -9933,6 +10310,29 @@ entries are of a variable lengths (TEL), TEL is always a multiple of
``NVME_SC_CMD_SIZE_LIMIT_EXCEEDED``
Command Size Limit Exceeded
+``NVME_SC_INCOMPATIBLE_NS``
+ Incompatible Namespace or Format: At
+ least one source namespace and the
+ destination namespace have incompatible
+ formats.
+
+``NVME_SC_FAST_COPY_NOT_POSSIBLE``
+ Fast Copy Not Possible: The Fast Copy
+ Only (FCO) bit was set to ‘1’ in a Source
+ Range entry and the controller was not
+ able to use fast copy operations to copy
+ the specified data.
+
+``NVME_SC_OVERLAPPING_IO_RANGE``
+ Overlapping I/O Range: A source logical
+ block range overlaps the destination
+ logical block range.
+
+``NVME_SC_INSUFFICIENT_RESOURCES``
+ Insufficient Resources: A resource
+ shortage prevented the controller from
+ performing the requested copy.
+
``NVME_SC_CONNECT_FORMAT``
Incompatible Format: The NVM subsystem
does not support the record format
@@ -10508,6 +10908,9 @@ true if **status** is of the specified type and value
``NVME_LOG_LID_BOOT_PARTITION``
Boot Partition
+``NVME_LOG_LID_PHY_RX_EOM``
+ Physical Interface Receiver Eye Opening Measurement
+
``NVME_LOG_LID_FDP_CONFIGS``
FDP Configurations
@@ -11219,6 +11622,42 @@ true if **status** is of the specified type and value
+.. c:enum:: nvme_log_phy_rx_eom_action
+
+ Physical Interface Receiver Eye Opening Measurement Action
+
+**Constants**
+
+``NVME_LOG_PHY_RX_EOM_READ``
+ Read Log Data
+
+``NVME_LOG_PHY_RX_EOM_START_READ``
+ Start Measurement and Read Log Data
+
+``NVME_LOG_PHY_RX_EOM_ABORT_CLEAR``
+ Abort Measurement and Clear Log Data
+
+
+
+
+.. c:enum:: nvme_log_phy_rx_eom_quality
+
+ Physical Interface Receiver Eye Opening Measurement Quality
+
+**Constants**
+
+``NVME_LOG_PHY_RX_EOM_GOOD``
+ <= Better Quality
+
+``NVME_LOG_PHY_RX_EOM_BETTER``
+ <= Best Quality, >= Good Quality
+
+``NVME_LOG_PHY_RX_EOM_BEST``
+ >= Better Quality
+
+
+
+
.. c:enum:: nvme_pevent_log_action
Persistent Event Log - Action
diff --git a/doc/rst/util.rst b/doc/rst/util.rst
index 6f7974e..f45452e 100644
--- a/doc/rst/util.rst
+++ b/doc/rst/util.rst
@@ -233,6 +233,74 @@ otherwise.
Number of descriptors to construct
+.. c:function:: void nvme_init_copy_range_f2 (struct nvme_copy_range_f2 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
+
+ Constructs a copy range f2 structure
+
+**Parameters**
+
+``struct nvme_copy_range_f2 *copy``
+ Copy range array
+
+``__u32 *snsids``
+ Source namespace identifier
+
+``__u16 *nlbs``
+ Number of logical blocks
+
+``__u64 *slbas``
+ Starting LBA
+
+``__u16 *sopts``
+ Source options
+
+``__u32 *eilbrts``
+ Expected initial logical block reference tag
+
+``__u32 *elbatms``
+ Expected logical block application tag mask
+
+``__u32 *elbats``
+ Expected logical block application tag
+
+``__u16 nr``
+ Number of descriptors to construct
+
+
+.. c:function:: void nvme_init_copy_range_f3 (struct nvme_copy_range_f3 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
+
+ Constructs a copy range f3 structure
+
+**Parameters**
+
+``struct nvme_copy_range_f3 *copy``
+ Copy range array
+
+``__u32 *snsids``
+ Source namespace identifier
+
+``__u16 *nlbs``
+ Number of logical blocks
+
+``__u64 *slbas``
+ Starting LBA
+
+``__u16 *sopts``
+ Source options
+
+``__u64 *eilbrts``
+ Expected initial logical block reference tag
+
+``__u32 *elbatms``
+ Expected logical block application tag mask
+
+``__u32 *elbats``
+ Expected logical block application tag
+
+``__u16 nr``
+ Number of descriptors to construct
+
+
.. c:function:: int nvme_get_feature_length (int fid, __u32 cdw11, __u32 *len)
Retreive the command payload length for a specific feature identifier
@@ -598,3 +666,52 @@ Returns error code if generating of random number fails.
true if addr1 == addr2. false otherwise.
+.. c:function:: const char * nvme_iface_matching_addr (const struct ifaddrs *iface_list, const char *addr)
+
+ Get interface matching **addr**
+
+**Parameters**
+
+``const struct ifaddrs *iface_list``
+ Interface list returned by getifaddrs()
+
+``const char *addr``
+ Address to match
+
+**Description**
+
+Parse the interface list pointed to by **iface_list** looking
+for the interface that has **addr** as one of its assigned
+addresses.
+
+**Return**
+
+The name of the interface that owns **addr** or NULL.
+
+
+.. c:function:: bool nvme_iface_primary_addr_matches (const struct ifaddrs *iface_list, const char *iface, const char *addr)
+
+ Check that interface's primary address matches
+
+**Parameters**
+
+``const struct ifaddrs *iface_list``
+ Interface list returned by getifaddrs()
+
+``const char *iface``
+ Interface to match
+
+``const char *addr``
+ Address to match
+
+**Description**
+
+Parse the interface list pointed to by **iface_list** and looking for
+interface **iface**. The get its primary address and check if it matches
+**addr**.
+
+**Return**
+
+true if a match is found, false otherwise.
+
+