diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/rst/fabrics.rst | 117 | ||||
| -rw-r--r-- | doc/rst/ioctl.rst | 48 | ||||
| -rw-r--r-- | doc/rst/linux.rst | 37 | ||||
| -rw-r--r-- | doc/rst/log.rst | 31 | ||||
| -rw-r--r-- | doc/rst/meson.build | 6 | ||||
| -rw-r--r-- | doc/rst/mi.rst | 42 | ||||
| -rw-r--r-- | doc/rst/tree.rst | 66 | ||||
| -rw-r--r-- | doc/rst/types.rst | 94 |
8 files changed, 418 insertions, 23 deletions
diff --git a/doc/rst/fabrics.rst b/doc/rst/fabrics.rst index 141c486..218084c 100644 --- a/doc/rst/fabrics.rst +++ b/doc/rst/fabrics.rst @@ -98,6 +98,55 @@ Fabrics-specific definitions. + + +.. c:struct:: nvme_fabrics_uri + + Parsed URI structure + +**Definition** + +:: + + struct nvme_fabrics_uri { + char *scheme; + char *protocol; + char *userinfo; + char *host; + int port; + char **path_segments; + char *query; + char *fragment; + }; + +**Members** + +``scheme`` + Scheme name (typically 'nvme') + +``protocol`` + Optional protocol/transport (e.g. 'tcp') + +``userinfo`` + Optional user information component of the URI authority + +``host`` + Host transport address + +``port`` + The port subcomponent or 0 if not specified + +``path_segments`` + NULL-terminated array of path segments + +``query`` + Optional query string component (separated by '?') + +``fragment`` + Optional fragment identifier component (separated by '#') + + + .. c:function:: const char * nvmf_trtype_str (__u8 trtype) Decode TRTYPE field @@ -434,6 +483,38 @@ An nvm namespace qualified name string based on the machine identifier, or NULL if not successful. +.. c:function:: char * nvmf_hostnqn_generate_from_hostid (char *hostid) + + Generate a host nqn from host identifier + +**Parameters** + +``char *hostid`` + Host identifier + +**Description** + +If **hostid** is NULL, the function generates it based on the machine +identifier. + +**Return** + +On success, an NVMe Qualified Name for host identification. This +name is based on the given host identifier. On failure, NULL. + + +.. c:function:: char * nvmf_hostid_generate () + + Generate a machine specific host identifier + +**Parameters** + +**Return** + +On success, an identifier string based on the machine identifier to +be used as NVMe Host Identifier, or NULL on failure. + + .. c:function:: char * nvmf_hostnqn_from_file () Reads the host nvm qualified name from the config default location @@ -543,3 +624,39 @@ tasks are supported: register, deregister, and registration update. 0 on success; on failure -1 is returned and errno is set +.. c:function:: struct nvme_fabrics_uri * nvme_parse_uri (const char *str) + + Parse the URI string + +**Parameters** + +``const char *str`` + URI string + +**Description** + +Parse the URI string as defined in the NVM Express Boot Specification. +Supported URI elements looks as follows: + + nvme+tcp://user**host**:port/subsys_nqn/nid?query=val#fragment + +**Return** + +:c:type:`nvme_fabrics_uri` structure on success; NULL on failure with errno +set. + + +.. c:function:: void nvme_free_uri (struct nvme_fabrics_uri *uri) + + Free the URI structure + +**Parameters** + +``struct nvme_fabrics_uri *uri`` + :c:type:`nvme_fabrics_uri` structure + +**Description** + +Free an :c:type:`nvme_fabrics_uri` structure. + + diff --git a/doc/rst/ioctl.rst b/doc/rst/ioctl.rst index 7b2003d..050bf99 100644 --- a/doc/rst/ioctl.rst +++ b/doc/rst/ioctl.rst @@ -2022,7 +2022,7 @@ This log consists of a header describing the log and descriptors containing the asymmetric namespace access information for ANA Groups that contain namespaces that are attached to the controller processing the command. -See :c:type:`struct nvme_ana_rsp_hdr <nvme_ana_rsp_hdr>` for the definition of the returned structure. +See :c:type:`struct nvme_ana_log <nvme_ana_log>` for the definition of the returned structure. **Return** @@ -2030,7 +2030,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_get_log_ana_groups (int fd, bool rae, __u32 len, struct nvme_ana_group_desc *log) +.. c:function:: int nvme_get_log_ana_groups (int fd, bool rae, __u32 len, struct nvme_ana_log *log) Retrieve Asymmetric Namespace Access groups only log page @@ -2045,12 +2045,12 @@ The nvme command status if a response was received (see ``__u32 len`` The allocated length of the log page -``struct nvme_ana_group_desc *log`` +``struct nvme_ana_log *log`` User address to store the ana group log **Description** -See :c:type:`struct nvme_ana_group_desc <nvme_ana_group_desc>` for the definition of the returned structure. +See :c:type:`struct nvme_ana_log <nvme_ana_log>` for the definition of the returned structure. **Return** @@ -2058,6 +2058,46 @@ 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_ana_log_atomic (int fd, bool rgo, bool rae, unsigned int retries, struct nvme_ana_log *log, __u32 *len) + + Retrieve Asymmetric Namespace Access log page atomically + +**Parameters** + +``int fd`` + File descriptor of nvme device + +``bool rgo`` + Whether to retrieve ANA groups only (no NSIDs) + +``bool rae`` + Whether to retain asynchronous events + +``unsigned int retries`` + The maximum number of times to retry on log page changes + +``struct nvme_ana_log *log`` + Pointer to a buffer to receive the ANA log page + +``__u32 *len`` + Input: the length of the log page buffer. + Output: the actual length of the ANA log page. + +**Description** + +See :c:type:`struct nvme_ana_log <nvme_ana_log>` for the definition of the returned structure. + +**Return** + +If successful, returns 0 and sets *len to the actual log page length. +If unsuccessful, returns 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. +Sets errno = EINVAL if retries == 0. +Sets errno = EAGAIN if unable to read the log page atomically +because chgcnt changed during each of the retries attempts. +Sets errno = ENOSPC if the full log page does not fit in the provided buffer. + + .. c:function:: int nvme_get_log_lba_status (int fd, bool rae, __u64 offset, __u32 len, void *log) Retrieve LBA Status diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst index cf49851..05d1418 100644 --- a/doc/rst/linux.rst +++ b/doc/rst/linux.rst @@ -205,6 +205,23 @@ 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:: size_t nvme_get_ana_log_len_from_id_ctrl (const struct nvme_id_ctrl *id_ctrl, bool rgo) + + Retrieve maximum possible ANA log size + +**Parameters** + +``const struct nvme_id_ctrl *id_ctrl`` + Controller identify data + +``bool rgo`` + If true, return maximum log page size without NSIDs + +**Return** + +A byte limit on the size of the controller's ANA log page + + .. c:function:: int nvme_get_ana_log_len (int fd, size_t *analen) Retrieve size of the current ANA log @@ -699,6 +716,26 @@ The string containing the TLS identity. It is the responsibility of the caller to free the returned string. +.. c:function:: long nvme_revoke_tls_key (const char *keyring, const char *key_type, const char *identity) + + Revoke TLS key from keyring + +**Parameters** + +``const char *keyring`` + Keyring to use + +``const char *key_type`` + Type of the key to revoke + +``const char *identity`` + Key identity string + +**Return** + +0 on success or on failure -1 with errno set. + + .. c:function:: char * nvme_export_tls_key (const unsigned char *key_data, int key_len) Export a TLS key diff --git a/doc/rst/log.rst b/doc/rst/log.rst index edbb330..76e616f 100644 --- a/doc/rst/log.rst +++ b/doc/rst/log.rst @@ -28,6 +28,30 @@ logging functions Sets the default logging variables for the library. +.. c:function:: void nvme_init_default_logging (FILE *fp, int lvl, bool log_pid, bool log_tstamp) + + Initialize default (fallback) logging + +**Parameters** + +``FILE *fp`` + File descriptor for logging messages + +``int lvl`` + Logging level to set + +``bool log_pid`` + Boolean to enable logging of the PID + +``bool log_tstamp`` + Boolean to enable logging of the timestamp + +**Description** + +Sets the default logging settings for the library in case the root object +is absent. + + .. c:function:: int nvme_get_logging_level (nvme_root_t r, bool *log_pid, bool *log_tstamp) Get current logging level @@ -72,6 +96,9 @@ 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. +This function is deprecated. Use nvme_init_default_logging or/and +nvme_init_logging instead. + .. c:function:: void nvme_set_debug (bool debug) @@ -84,7 +111,7 @@ the global root object. **Description** -Don't use it, it's debricated. +This function is deprecated. Use nvme_init_default_logging instead. .. c:function:: bool nvme_get_debug (void) @@ -99,7 +126,7 @@ Don't use it, it's debricated. **Description** -Don't use it, it's debricated. +This function is deprecated. Use nvme_get_logging_level instead. **Return** diff --git a/doc/rst/meson.build b/doc/rst/meson.build index e54c381..25d68ca 100644 --- a/doc/rst/meson.build +++ b/doc/rst/meson.build @@ -8,8 +8,8 @@ if want_docs != 'false' if want_docs_build kernel_doc = find_program(top_source_dir + 'scripts/kernel-doc') - conf = configuration_data() - conf.set('SYSCONFDIR', sysconfdir) + rst_conf = configuration_data() + rst_conf.set('SYSCONFDIR', sysconfdir) if want_docs == 'all' or want_docs == 'rst' or want_docs == 'html' foreach apif : api_files @@ -17,7 +17,7 @@ if want_docs != 'false' subst = configure_file( input: afile, output: '@BASENAME@.subst', - configuration: conf) + configuration: rst_conf) rst = custom_target( apif.underscorify() + '_rst', input: subst, diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst index 2aa7438..e5c2bd1 100644 --- a/doc/rst/mi.rst +++ b/doc/rst/mi.rst @@ -2459,7 +2459,7 @@ This log consists of a header describing the log and descriptors containing the asymmetric namespace access information for ANA Groups that contain namespaces that are attached to the controller processing the command. -See :c:type:`struct nvme_ana_rsp_hdr <nvme_ana_rsp_hdr>` for the definition of the returned structure. +See :c:type:`struct nvme_ana_log <nvme_ana_log>` for the definition of the returned structure. **Return** @@ -2495,6 +2495,46 @@ 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_ana_log_atomic (nvme_mi_ctrl_t ctrl, bool rgo, bool rae, unsigned int retries, struct nvme_ana_log *log, __u32 *len) + + Retrieve Asymmetric Namespace Access log page atomically + +**Parameters** + +``nvme_mi_ctrl_t ctrl`` + Controller to query + +``bool rgo`` + Whether to retrieve ANA groups only (no NSIDs) + +``bool rae`` + Whether to retain asynchronous events + +``unsigned int retries`` + The maximum number of times to retry on log page changes + +``struct nvme_ana_log *log`` + Pointer to a buffer to receive the ANA log page + +``__u32 *len`` + Input: the length of the log page buffer. + Output: the actual length of the ANA log page. + +**Description** + +See :c:type:`struct nvme_ana_log <nvme_ana_log>` for the definition of the returned structure. + +**Return** + +If successful, returns 0 and sets *len to the actual log page length. +If unsuccessful, returns 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. +Sets errno = EINVAL if retries == 0. +Sets errno = EAGAIN if unable to read the log page atomically +because chgcnt changed during each of the retries attempts. +Sets errno = ENOSPC if the full log page does not fit in the provided buffer. + + .. c:function:: int nvme_mi_admin_get_log_lba_status (nvme_mi_ctrl_t ctrl, bool rae, __u64 offset, __u32 len, void *log) Retrieve LBA Status diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst index 6f79703..ee46d11 100644 --- a/doc/rst/tree.rst +++ b/doc/rst/tree.rst @@ -53,6 +53,20 @@ Sets the managing application string for **r**. 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 @@ -229,14 +243,62 @@ true if PDC is enabled for **h**, else false **Description** -Initializes the default host object based on the values in -/etc/nvme/hostnqn and /etc/nvme/hostid and attaches it to **r**. +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 diff --git a/doc/rst/types.rst b/doc/rst/types.rst index 1d6ad5a..7236642 100644 --- a/doc/rst/types.rst +++ b/doc/rst/types.rst @@ -2148,6 +2148,12 @@ power scale value ``NVME_CTRL_CTRATT_ELBAS`` Extended LBA Formats supported +``NVME_CTRL_CTRATT_MEM`` + MDTS and Size Limits Exclude Metadata supported + +``NVME_CTRL_CTRATT_HMBR`` + HMB Restrict Non-Operational Power State Access + ``NVME_CTRL_CTRATT_FDPS`` Flexible Data Placement supported @@ -3162,6 +3168,34 @@ power scale value Mask to get the protection information format for the extended LBA format. +``NVME_NVM_ELBAF_QPIF_MASK`` + Mask to get the Qualified Protection Information + Format. + + + + +.. c:enum:: nvme_nvm_id_ns_pif + + This field indicates the type of the Protection Information Format + +**Constants** + +``NVME_NVM_PIF_16B_GUARD`` + 16-bit Guard Protection Information Format + +``NVME_NVM_PIF_32B_GUARD`` + 32-bit Guard Protection Information Format + +``NVME_NVM_PIF_64B_GUARD`` + 64-bit Guard Protection Information Format + +``NVME_NVM_PIF_QTYPE`` + If Qualified Protection Information Format Supports + and Protection Information Format is set to 3, then + protection information format is taken from Qualified + Protection Information Format field. + @@ -3759,7 +3793,9 @@ power scale value __u8 dmrl; __le32 dmrsl; __le64 dmsl; - __u8 rsvd16[4080]; + __u8 rsvd16[2]; + __le16 aocs; + __u8 rsvd20[4076]; }; **Members** @@ -3783,7 +3819,13 @@ power scale value Dataset Management Size Limit ``rsvd16`` - reserved + Reserved + +``aocs`` + Admin Optional Command Support + +``rsvd20`` + Reserved @@ -3800,9 +3842,13 @@ power scale value struct nvme_nvm_id_ns { __le64 lbstm; __u8 pic; - __u8 rsvd9[3]; + __u8 pifa; + __u8 rsvd10[2]; __le32 elbaf[64]; - __u8 rsvd268[3828]; + __le32 npdgl; + __u8 rsvd272[20]; + __le32 tlbaag; + __u8 rsvd296[3800]; }; **Members** @@ -3813,13 +3859,25 @@ power scale value ``pic`` Protection Information Capabilities -``rsvd9`` +``pifa`` + Protection Information Format Attribute + +``rsvd10`` Reserved ``elbaf`` List of Extended LBA Format Support -``rsvd268`` +``npdgl`` + Namespace Preferred Deallocate Granularity Large + +``rsvd272`` + Reserved + +``tlbaag`` + Tracked LBA Allocation Granularity + +``rsvd296`` Reserved @@ -5821,6 +5879,12 @@ bytes, in size. This log captures the controller’s internal state. ``NVME_PEL_THERMAL_EXCURSION_EVENT`` Thermal Excursion Event +``NVME_PEL_VENDOR_SPECIFIC_EVENT`` + Vendor Specific Event + +``NVME_PEL_TCG_DEFINED_EVENT`` + TCG Defined Event + @@ -6395,16 +6459,21 @@ bytes, in size. This log captures the controller’s internal state. .. c:enum:: nvme_lba_status_atype - Potentially Unrecoverable LBAs + Action type the controller uses to return LBA status **Constants** +``NVME_LBA_STATUS_ATYPE_ALLOCATED`` + Return tracked allocated LBAs status + ``NVME_LBA_STATUS_ATYPE_SCAN_UNTRACKED`` - Potentially Unrecoverable LBAs + Perform scan and return Untracked and + Tracked Potentially Unrecoverable LBAs + status -``NVME_LBA_STATUS_ATYPE_SCAN_TRACKED`` - Potentially Unrecoverable LBAs - associated with physical storage +``NVME_LBA_STATUS_ATYPE_TRACKED`` + Return Tracked Potentially Unrecoverable + LBAs associated with physical storage @@ -13061,6 +13130,9 @@ true if **status** is of the specified type and value ``nvme_cmd_resv_release`` Reservation Release +``nvme_cmd_cancel`` + Cancel + ``nvme_cmd_copy`` Copy |