diff options
Diffstat (limited to 'doc/rst')
| -rw-r--r-- | doc/rst/ioctl.rst | 334 | ||||
| -rw-r--r-- | doc/rst/linux.rst | 139 | ||||
| -rw-r--r-- | doc/rst/log.rst | 19 | ||||
| -rw-r--r-- | doc/rst/mi.rst | 33 | ||||
| -rw-r--r-- | doc/rst/tree.rst | 202 | ||||
| -rw-r--r-- | doc/rst/types.rst | 469 | ||||
| -rw-r--r-- | doc/rst/util.rst | 117 |
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. + + |