From: Daniel Wagner Date: Wed, 16 Nov 2022 10:26:48 +0000 (+0100) Subject: doc: Generate rst documentation on the fly for readthedocs X-Git-Tag: v1.3~30^2 X-Git-Url: https://www.infradead.org/git/?a=commitdiff_plain;h=8be5a5ceaaf782fbfa2846fc6e7b6bd091d7fc3b;p=users%2Fsagi%2Flibnvme.git doc: Generate rst documentation on the fly for readthedocs Generate the rst files from the source files directly and avoid storing pre generated ones in the source tree. Signed-of-by: Daniel Wagner --- diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..283a2dc9 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: Apache-2.0 + +version: 2 + +python: + system_packages: true + +build: + os: ubuntu-22.04 + tools: + python: "3" + apt_packages: + - meson + - python3-lxml + - docbook-xsl + - xsltproc + - pandoc + jobs: + post_install: + - pip3 install lxml + pre_build: + - meson .build -Ddocs=rst -Ddocs-build=true || cat .build/meson-logs/meson-log.txt + - ninja -C .build + +sphinx: + configuration: .build/doc/conf.py diff --git a/doc/api.rst b/doc/api.rst deleted file mode 100644 index 34787661..00000000 --- a/doc/api.rst +++ /dev/null @@ -1,18 +0,0 @@ -=== -API -=== - -.. module:: libnvme - -This part of the documentation lists the full API reference of all public classes and -functions. - -.. include:: rst/types.rst -.. include:: rst/ioctl.rst -.. include:: rst/fabrics.rst -.. include:: rst/linux.rst -.. include:: rst/mi.rst -.. include:: rst/tree.rst -.. include:: rst/filters.rst -.. include:: rst/util.rst -.. include:: rst/log.rst diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index abfa57c9..00000000 --- a/doc/conf.py +++ /dev/null @@ -1,32 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - - -# -- Project information ----------------------------------------------------- - -project = 'libnvme' -copyright = '2020, Keith Busch' -author = 'Keith Busch ' -master_doc = 'index' - -release = '1.2' - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['html', 'man', 'Thumbs.db', '.DS_Store'] diff --git a/doc/config-schema.json b/doc/config-schema.json deleted file mode 100644 index 69fb6065..00000000 --- a/doc/config-schema.json +++ /dev/null @@ -1,168 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://github.com/linux-nvme/libnvme/doc/config-schema.json", - "title": "config.json", - "description": "libnvme JSON configuration", - "type": "object", - "properties": { - "hosts": { - "description": "Array of NVMe Host properties", - "type": "array", - "items": { "$ref": "#/$defs/host" } - } - }, - "$defs": { - "host": { - "description": "NVMe Host properties", - "type": "object", - "properties": { - "hostnqn": { - "description": "NVMe host NQN", - "type": "string", - "maxLength": 223 - }, - "hostid": { - "description": "NVMe host ID", - "type": "string" - }, - "dhchap_key": { - "description": "Host DH-HMAC-CHAP key", - "type": "string" - }, - "hostsymname": { - "description": "NVMe host symbolic name", - "type": "string" - }, - "required": [ "hostnqn" ], - "subsystems": { - "description": "Array of NVMe subsystem properties", - "type": "array", - "items": { "$ref": "#/$defs/subsystem" } - } - } - }, - "subsystem": { - "description": "NVMe subsystem properties", - "type": "object", - "properties": { - "nqn": { - "description": "Subsystem NQN", - "type": "string", - "maxLength": 223 - }, - "ports": { - "description": "Array of NVMe subsystem ports", - "type": "array", - "items": { "$ref": "#/$defs/port" } - }, - "required": [ "nqn" ] - } - }, - "port": { - "description": "NVMe subsystem port", - "type": "object", - "properties": { - "transport": { - "description": "Transport type", - "type": "string" - }, - "traddr": { - "description": "Transport address", - "type": "string" - }, - "host_traddr": { - "description": "Host transport address", - "type": "string" - }, - "host_iface": { - "description": "Host interface name", - "type": "string" - }, - "trsvcid": { - "description": "Transport service identifier", - "type": "string" - }, - "dhchap_key": { - "description": "Host DH-HMAC-CHAP key", - "type": "string" - }, - "dhchap_ctrl_key": { - "description": "Controller DH-HMAC-CHAP key", - "type": "string" - }, - "nr_io_queues": { - "description": "Number of I/O queues", - "type": "integer" - }, - "nr_write_queues": { - "description": "Number of write queues", - "type": "integer" - }, - "nr_poll_queues": { - "description": "Number of poll queues", - "type": "integer" - }, - "queue_size": { - "description": "Queue size", - "type": "integer" - }, - "keep_alive_tmo": { - "description": "Keep-Alive timeout (in seconds)", - "type": "integer" - }, - "reconnect_delay": { - "description": "Reconnect delay (in seconds)", - "type": "integer" - }, - "ctrl_loss_tmo": { - "description": "Controller loss timeout (in seconds)", - "type": "integer" - }, - "fast_io_fail_tmo": { - "description": "Fast I/O Fail timeout (in seconds)", - "type": "integer", - "default": 600 - }, - "tos": { - "description": "Type of service", - "type": "integer", - "default": -1 - }, - "duplicate_connect": { - "description": "Allow duplicate connections", - "type": "boolean", - "default": false - }, - "disable_sqflow": { - "description": "Explicitly disable SQ flow control", - "type": "boolean", - "default": false - }, - "hdr_digest": { - "description": "Enable header digest", - "type": "boolean", - "default": false - }, - "data_digest": { - "description": "Enable data digest", - "type": "boolean", - "default": false - }, - "tls": { - "description": "Enable TLS encryption", - "type": "boolean", - "default": false - }, - "persistent": { - "description": "Create persistent discovery connection", - "type": "boolean" - }, - "discovery": { - "description": "Connect to a discovery controller", - "type": "boolean" - } - }, - "required": [ "transport" ] - } - } -} diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 54c2415b..00000000 --- a/doc/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -Welcome to libnvme's documentation! -=================================== - -This is the libnvme development C library. libnvme provides type definitions for -NVMe specification structures, enumerations, and bit fields, -helper functions to construct, dispatch, and decode commands and payloads, -and utilities to connect, scan, and manage nvme devices on a Linux system. - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - installation.rst - quickstart.rst - mi.rst - api.rst - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/installation.rst b/doc/installation.rst deleted file mode 100644 index 0bc8f99a..00000000 --- a/doc/installation.rst +++ /dev/null @@ -1,52 +0,0 @@ -Installation -============ - -Debian / Ubuntu: --------------- - -.. code-block:: sh - - $ apt-get install libnvme - -Fedora / Red Hat: --------------- - -.. code-block:: sh - - $ dnf install libnvme - -Python Version --------------- - -The latest Python 3 version is always recommended, since it has all the latest bells and -whistles. libnvme supports Python 3.6 and above. - -Dependencies ------------- - -libnvme only uses packages from the standard library, -so no additional dependencies will be installed when installing libnvme. - -Install libnvme python -------------- - -Debian / Ubuntu: - -.. code-block:: sh - - $ apt-get install python3-libnvme - -Fedora / Red Hat: - -.. code-block:: sh - - $ dnf install python3-libnvme - -libnvme is available on `PyPI`_, and can be installed using pip. The version on PyPI is -always the latest stable release. - -.. _PyPi: https://pypi.org/project/libnvme/ - -.. code-block:: sh - - $ pip install libnvme diff --git a/doc/mi.rst b/doc/mi.rst deleted file mode 100644 index a75fd697..00000000 --- a/doc/mi.rst +++ /dev/null @@ -1,54 +0,0 @@ -NVMe Management Interface (NVMe-MI) support -=========================================== - -This libnvme project also includes support for the NVMe Management Interface -(NVMe-MI), currently over a Management Component Transport (MCTP) -protocol link. This MCTP link will typically use i2c/SMBus as the -hardware transport, enabling out-of-band management and control over NVMe -devices using a simple SMBus interface. - -The MI interface is compiled into a separate shared object, ``libnvme-mi.so``. - -Most of the MI API is transport-agnostic, except for the endpoint constructor -functions. Once an endpoint object (``nvme_mi_ep_t``) is created, the generic -functions can be used to manage it. - -When endpoints are created (through one of the transport-specific functions, -like ``nvme_mi_open_mctp()``), the endpoint hardware will be probed to -see if any device-specific workarounds ("quirks") are required. This is -implemented as an Identify Controller command, requesting a small amount of -data on controller ID 0. - -To suppress this probe, the ``LIBNVME_MI_PROBE_ENABLED`` environment var can be -set. Values of ``0``, ``false`` and ``disabled`` will disable the probe, and no -quirks will be applied. Other values, or an unset environment variable, will -enable the probe. - -MCTP Transport --------------- - -The MI API is generally transport-agnostic, but the only currently-supported -transport is MCTP, using the kernel ``AF_MCTP`` socket interface. - -MCTP endpoints are addressed by a (network-id, endpoint-id) pair. Endpoint -IDs (EIDs) are defined by the MCTP standard as an 8-bit value. Since the -address space is somewhat limited, the Linux `AF_MCTP` support allows for -separate MCTP "networks", which provide separate address spaces. These networks -each have a unique ``unsigned int`` as their ID. - -The default Network ID is 1; unless you have configured otherwise, MCTP -endpoints will appear on this network. - -If compiled with D-Bus support, ``libnvme-mi`` can query the system MCTP daemon -("``mctpd``") to find attached NVMe devices, via the ``nvme_mi_scan_mctp()`` -function. Calling this will establish a ``nvme_root_t`` object, populated -with the results of that scan. Use the ``nvme_mi_for_each_endpoint`` macro -to iterate through the scanned endpoints. - -Note that the MCTP daemon is provided separately, as part of the MCTP userspace -tools, at https://github.com/CodeConstruct/mctp . ``mctpd`` is responsible for -discovery and enumeration for MCTP endpoints on the system, and will query -each for its protocol capabilities during enumeration. Consequently, NVMe-MI -endpoints will need to report support for NVMe-MI-over-MCTP (protocol 0x4) in -their supported protocols list (ie., as returned by the MCTP Get Message Type -Support command) in order to be discovered. diff --git a/doc/quickstart.rst b/doc/quickstart.rst deleted file mode 100644 index d3561889..00000000 --- a/doc/quickstart.rst +++ /dev/null @@ -1,5 +0,0 @@ -========== -Quickstart -========== - -tbd \ No newline at end of file diff --git a/doc/rst/fabrics.rst b/doc/rst/fabrics.rst deleted file mode 100644 index f0249f09..00000000 --- a/doc/rst/fabrics.rst +++ /dev/null @@ -1,521 +0,0 @@ -.. _fabrics.h: - -**fabrics.h** - - -Fabrics-specific definitions. - - - -.. c:struct:: nvme_fabrics_config - - Defines all linux nvme fabrics initiator options - -**Definition** - -:: - - struct nvme_fabrics_config { - char *host_traddr; - char *host_iface; - int queue_size; - int nr_io_queues; - int reconnect_delay; - int ctrl_loss_tmo; - int fast_io_fail_tmo; - int keep_alive_tmo; - int nr_write_queues; - int nr_poll_queues; - int tos; - bool duplicate_connect; - bool disable_sqflow; - bool hdr_digest; - bool data_digest; - bool tls; - }; - -**Members** - -``host_traddr`` - Host transport address - -``host_iface`` - Host interface name - -``queue_size`` - Number of IO queue entries - -``nr_io_queues`` - Number of controller IO queues to establish - -``reconnect_delay`` - Time between two consecutive reconnect attempts. - -``ctrl_loss_tmo`` - Override the default controller reconnect attempt timeout in seconds - -``fast_io_fail_tmo`` - Set the fast I/O fail timeout in seconds. - -``keep_alive_tmo`` - Override the default keep-alive-timeout to this value in seconds - -``nr_write_queues`` - Number of queues to use for exclusively for writing - -``nr_poll_queues`` - Number of queues to reserve for polling completions - -``tos`` - Type of service - -``duplicate_connect`` - Allow multiple connections to the same target - -``disable_sqflow`` - Disable controller sq flow control - -``hdr_digest`` - Generate/verify header digest (TCP) - -``data_digest`` - Generate/verify data digest (TCP) - -``tls`` - Start TLS on the connection (TCP) - - - -.. c:function:: const char * nvmf_trtype_str (__u8 trtype) - - Decode TRTYPE field - -**Parameters** - -``__u8 trtype`` - value to be decoded - -**Description** - -Decode the transport type field in the discovery -log page entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_adrfam_str (__u8 adrfam) - - Decode ADRFAM field - -**Parameters** - -``__u8 adrfam`` - value to be decoded - -**Description** - -Decode the address family field in the discovery -log page entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_subtype_str (__u8 subtype) - - Decode SUBTYPE field - -**Parameters** - -``__u8 subtype`` - value to be decoded - -**Description** - -Decode the subsystem type field in the discovery -log page entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_treq_str (__u8 treq) - - Decode TREQ field - -**Parameters** - -``__u8 treq`` - value to be decoded - -**Description** - -Decode the transport requirements field in the -discovery log page entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_eflags_str (__u16 eflags) - - Decode EFLAGS field - -**Parameters** - -``__u16 eflags`` - value to be decoded - -**Description** - -Decode the EFLAGS field in the discovery log page -entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_sectype_str (__u8 sectype) - - Decode SECTYPE field - -**Parameters** - -``__u8 sectype`` - value to be decoded - -**Description** - -Decode the SECTYPE field in the discovery log page -entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_prtype_str (__u8 prtype) - - Decode RDMA Provider type field - -**Parameters** - -``__u8 prtype`` - value to be decoded - -**Description** - -Decode the RDMA Provider type field in the discovery -log page entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_qptype_str (__u8 qptype) - - Decode RDMA QP Service type field - -**Parameters** - -``__u8 qptype`` - value to be decoded - -**Description** - -Decode the RDMA QP Service type field in the discovery log page -entry. - -**Return** - -decoded string - - -.. c:function:: const char * nvmf_cms_str (__u8 cms) - - Decode RDMA connection management service field - -**Parameters** - -``__u8 cms`` - value to be decoded - -**Description** - -Decode the RDMA connection management service field in the discovery -log page entry. - -**Return** - -decoded string - - -.. c:function:: void nvmf_default_config (struct nvme_fabrics_config *cfg) - - Default values for fabrics configuration - -**Parameters** - -``struct nvme_fabrics_config *cfg`` - config values to set - -**Description** - -Initializes **cfg** with default values. - - -.. c:function:: void nvmf_update_config (nvme_ctrl_t c, const struct nvme_fabrics_config *cfg) - - Update fabrics configuration values - -**Parameters** - -``nvme_ctrl_t c`` - Controller to be modified - -``const struct nvme_fabrics_config *cfg`` - Updated configuration values - -**Description** - -Updates the values from **c** with the configuration values from **cfg**; -all non-default values from **cfg** will overwrite the values in **c**. - - -.. c:function:: int nvmf_add_ctrl (nvme_host_t h, nvme_ctrl_t c, const struct nvme_fabrics_config *cfg) - - Connect a controller and update topology - -**Parameters** - -``nvme_host_t h`` - Host to which the controller should be attached - -``nvme_ctrl_t c`` - Controller to be connected - -``const struct nvme_fabrics_config *cfg`` - Default configuration for the controller - -**Description** - -Issues a 'connect' command to the NVMe-oF controller and inserts **c** -into the topology using **h** as parent. -**c** must be initialized and not connected to the topology. - -**Return** - -0 on success; on failure errno is set and -1 is returned. - - -.. c:function:: int nvmf_get_discovery_log (nvme_ctrl_t c, struct nvmf_discovery_log **logp, int max_retries) - - Return the discovery log page - -**Parameters** - -``nvme_ctrl_t c`` - Discovery controller to use - -``struct nvmf_discovery_log **logp`` - Pointer to the log page to be returned - -``int max_retries`` - Number of retries in case of failure - -**Description** - -The memory allocated for the log page and returned in **logp** -must be freed by the caller using free(). - -**Note** - -Consider using nvmf_get_discovery_wargs() instead. - -**Return** - -0 on success; on failure -1 is returned and errno is set - - - - -.. c:struct:: nvme_get_discovery_args - - Arguments for nvmf_get_discovery_wargs() - -**Definition** - -:: - - struct nvme_get_discovery_args { - nvme_ctrl_t c; - int args_size; - int max_retries; - __u32 *result; - __u32 timeout; - __u8 lsp; - }; - -**Members** - -``c`` - Discovery controller - -``args_size`` - Length of the structure - -``max_retries`` - Number of retries in case of failure - -``result`` - The command completion result from CQE dword0 - -``timeout`` - Timeout in ms (default: NVME_DEFAULT_IOCTL_TIMEOUT) - -``lsp`` - Log specific field (See enum nvmf_log_discovery_lsp) - - - -.. c:function:: struct nvmf_discovery_log * nvmf_get_discovery_wargs (struct nvme_get_discovery_args *args) - - Get the discovery log page with args - -**Parameters** - -``struct nvme_get_discovery_args *args`` - Argument structure - -**Description** - -This function is similar to nvmf_get_discovery_log(), but -takes an extensible **args** parameter. **args** provides more -options than nvmf_get_discovery_log(). - -This function performs a get discovery log page (DLP) command -and returns the DLP. The memory allocated for the returned -DLP must be freed by the caller using free(). - -**Return** - -Pointer to the discovery log page (to be freed). NULL -on failure and errno is set. - - -.. c:function:: char * nvmf_hostnqn_generate () - - Generate a machine specific host nqn - -**Parameters** - -**Return** - -An nvm namespace qualified name string based on the machine -identifier, or NULL if not successful. - - -.. c:function:: char * nvmf_hostnqn_from_file () - - Reads the host nvm qualified name from the config default location in /etc/nvme/ - -**Parameters** - -**Return** - -The host nqn, or NULL if unsuccessful. If found, the caller -is responsible to free the string. - - -.. c:function:: char * nvmf_hostid_from_file () - - Reads the host identifier from the config default location in /etc/nvme/. - -**Parameters** - -**Return** - -The host identifier, or NULL if unsuccessful. If found, the caller - is responsible to free the string. - - -.. c:function:: nvme_ctrl_t nvmf_connect_disc_entry (nvme_host_t h, struct nvmf_disc_log_entry *e, const struct nvme_fabrics_config *defcfg, bool *discover) - - Connect controller based on the discovery log page entry - -**Parameters** - -``nvme_host_t h`` - Host to which the controller should be connected - -``struct nvmf_disc_log_entry *e`` - Discovery log page entry - -``const struct nvme_fabrics_config *defcfg`` - Default configuration to be used for the new controller - -``bool *discover`` - Set to 'true' if the new controller is a discovery controller - -**Return** - -Pointer to the new controller - - -.. c:function:: bool nvmf_is_registration_supported (nvme_ctrl_t c) - - check whether registration can be performed. - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Description** - -Only discovery controllers (DC) that comply with TP8010 support -explicit registration with the DIM PDU. These can be identified by -looking at the value of a dctype in the Identify command -response. A value of 1 (DDC) or 2 (CDC) indicates that the DC -supports explicit registration. - -**Return** - -true if controller supports explicit registration. false -otherwise. - - -.. c:function:: int nvmf_register_ctrl (nvme_ctrl_t c, enum nvmf_dim_tas tas, __u32 *result) - - Perform registration task with a DC - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``enum nvmf_dim_tas tas`` - Task field of the Command Dword 10 (cdw10). Indicates whether to - perform a Registration, Deregistration, or Registration-update. - -``__u32 *result`` - The command-specific result returned by the DC upon command - completion. - -**Description** - -Perform registration task with a Discovery Controller (DC). Three -tasks are supported: register, deregister, and registration update. - -**Return** - -0 on success; on failure -1 is returned and errno is set - - diff --git a/doc/rst/filters.rst b/doc/rst/filters.rst deleted file mode 100644 index 3e8c9979..00000000 --- a/doc/rst/filters.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _filters.h: - -**filters.h** - - -libnvme directory filter - -.. c:function:: int nvme_namespace_filter (const struct dirent *d) - - Filter for namespaces - -**Parameters** - -``const struct dirent *d`` - dirent to check - -**Return** - -1 if **d** matches, 0 otherwise - - -.. c:function:: int nvme_paths_filter (const struct dirent *d) - - Filter for paths - -**Parameters** - -``const struct dirent *d`` - dirent to check - -**Return** - -1 if **d** matches, 0 otherwise - - -.. c:function:: int nvme_ctrls_filter (const struct dirent *d) - - Filter for controllers - -**Parameters** - -``const struct dirent *d`` - dirent to check - -**Return** - -1 if **d** matches, 0 otherwise - - -.. c:function:: int nvme_subsys_filter (const struct dirent *d) - - Filter for subsystems - -**Parameters** - -``const struct dirent *d`` - dirent to check - -**Return** - -1 if **d** matches, 0 otherwise - - -.. c:function:: int nvme_scan_subsystems (struct dirent ***subsys) - - Scan for subsystems - -**Parameters** - -``struct dirent ***subsys`` - Pointer to array of dirents - -**Return** - -number of entries in **subsys** - - -.. c:function:: int nvme_scan_subsystem_namespaces (nvme_subsystem_t s, struct dirent ***ns) - - Scan for namespaces in a subsystem - -**Parameters** - -``nvme_subsystem_t s`` - Subsystem to scan - -``struct dirent ***ns`` - Pointer to array of dirents - -**Return** - -number of entries in **ns** - - -.. c:function:: int nvme_scan_ctrls (struct dirent ***ctrls) - - Scan for controllers - -**Parameters** - -``struct dirent ***ctrls`` - Pointer to array of dirents - -**Return** - -number of entries in **ctrls** - - -.. c:function:: int nvme_scan_ctrl_namespace_paths (nvme_ctrl_t c, struct dirent ***paths) - - Scan for namespace paths in a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller to scan - -``struct dirent ***paths`` - Pointer to array of dirents - -**Return** - -number of entries in **paths** - - -.. c:function:: int nvme_scan_ctrl_namespaces (nvme_ctrl_t c, struct dirent ***ns) - - Scan for namespaces in a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller to scan - -``struct dirent ***ns`` - Pointer to array of dirents - -**Return** - -number of entries in **ns** - - diff --git a/doc/rst/ioctl.rst b/doc/rst/ioctl.rst deleted file mode 100644 index 9e644f02..00000000 --- a/doc/rst/ioctl.rst +++ /dev/null @@ -1,4712 +0,0 @@ -.. _ioctl.h: - -**ioctl.h** - - -Linux NVMe ioctl interface functions - - - -.. c:struct:: nvme_passthru_cmd - - nvme passthrough command structure - -**Definition** - -:: - - struct nvme_passthru_cmd { - __u8 opcode; - __u8 flags; - __u16 rsvd1; - __u32 nsid; - __u32 cdw2; - __u32 cdw3; - __u64 metadata; - __u64 addr; - __u32 metadata_len; - __u32 data_len; - __u32 cdw10; - __u32 cdw11; - __u32 cdw12; - __u32 cdw13; - __u32 cdw14; - __u32 cdw15; - __u32 timeout_ms; - __u32 result; - }; - -**Members** - -``opcode`` - Operation code, see :c:type:`enum nvme_io_opcodes ` and :c:type:`enum nvme_admin_opcodes ` - -``flags`` - Not supported: intended for command flags (eg: SGL, FUSE) - -``rsvd1`` - Reserved for future use - -``nsid`` - Namespace Identifier, or Fabrics type - -``cdw2`` - Command Dword 2 (no spec defined use) - -``cdw3`` - Command Dword 3 (no spec defined use) - -``metadata`` - User space address to metadata buffer (NULL if not used) - -``addr`` - User space address to data buffer (NULL if not used) - -``metadata_len`` - Metadata buffer transfer length - -``data_len`` - Data buffer transfer length - -``cdw10`` - Command Dword 10 (command specific) - -``cdw11`` - Command Dword 11 (command specific) - -``cdw12`` - Command Dword 12 (command specific) - -``cdw13`` - Command Dword 13 (command specific) - -``cdw14`` - Command Dword 14 (command specific) - -``cdw15`` - Command Dword 15 (command specific) - -``timeout_ms`` - If non-zero, overrides system default timeout in milliseconds - -``result`` - Set on completion to the command's CQE DWORD 0 controller response - - - - - -.. c:struct:: nvme_passthru_cmd64 - - 64-bit nvme passthrough command structure - -**Definition** - -:: - - struct nvme_passthru_cmd64 { - __u8 opcode; - __u8 flags; - __u16 rsvd1; - __u32 nsid; - __u32 cdw2; - __u32 cdw3; - __u64 metadata; - __u64 addr; - __u32 metadata_len; - __u32 data_len; - __u32 cdw10; - __u32 cdw11; - __u32 cdw12; - __u32 cdw13; - __u32 cdw14; - __u32 cdw15; - __u32 timeout_ms; - __u32 rsvd2; - __u64 result; - }; - -**Members** - -``opcode`` - Operation code, see :c:type:`enum nvme_io_opcodes ` and :c:type:`enum nvme_admin_opcodes ` - -``flags`` - Not supported: intended for command flags (eg: SGL, FUSE) - -``rsvd1`` - Reserved for future use - -``nsid`` - Namespace Identifier, or Fabrics type - -``cdw2`` - Command Dword 2 (no spec defined use) - -``cdw3`` - Command Dword 3 (no spec defined use) - -``metadata`` - User space address to metadata buffer (NULL if not used) - -``addr`` - User space address to data buffer (NULL if not used) - -``metadata_len`` - Metadata buffer transfer length - -``data_len`` - Data buffer transfer length - -``cdw10`` - Command Dword 10 (command specific) - -``cdw11`` - Command Dword 11 (command specific) - -``cdw12`` - Command Dword 12 (command specific) - -``cdw13`` - Command Dword 13 (command specific) - -``cdw14`` - Command Dword 14 (command specific) - -``cdw15`` - Command Dword 15 (command specific) - -``timeout_ms`` - If non-zero, overrides system default timeout in milliseconds - -``rsvd2`` - Reserved for future use (and fills an implicit struct pad - -``result`` - Set on completion to the command's CQE DWORD 0-1 controller response - - - - - -.. c:struct:: nvme_uring_cmd - - nvme uring command structure - -**Definition** - -:: - - struct nvme_uring_cmd { - __u8 opcode; - __u8 flags; - __u16 rsvd1; - __u32 nsid; - __u32 cdw2; - __u32 cdw3; - __u64 metadata; - __u64 addr; - __u32 metadata_len; - __u32 data_len; - __u32 cdw10; - __u32 cdw11; - __u32 cdw12; - __u32 cdw13; - __u32 cdw14; - __u32 cdw15; - __u32 timeout_ms; - __u32 rsvd2; - }; - -**Members** - -``opcode`` - Operation code, see :c:type:`enum nvme_io_opcodes ` and :c:type:`enum nvme_admin_opcodes ` - -``flags`` - Not supported: intended for command flags (eg: SGL, FUSE) - -``rsvd1`` - Reserved for future use - -``nsid`` - Namespace Identifier, or Fabrics type - -``cdw2`` - Command Dword 2 (no spec defined use) - -``cdw3`` - Command Dword 3 (no spec defined use) - -``metadata`` - User space address to metadata buffer (NULL if not used) - -``addr`` - User space address to data buffer (NULL if not used) - -``metadata_len`` - Metadata buffer transfer length - -``data_len`` - Data buffer transfer length - -``cdw10`` - Command Dword 10 (command specific) - -``cdw11`` - Command Dword 11 (command specific) - -``cdw12`` - Command Dword 12 (command specific) - -``cdw13`` - Command Dword 13 (command specific) - -``cdw14`` - Command Dword 14 (command specific) - -``cdw15`` - Command Dword 15 (command specific) - -``timeout_ms`` - If non-zero, overrides system default timeout in milliseconds - -``rsvd2`` - Reserved for future use (and fills an implicit struct pad - - - -.. c:macro:: sizeof_args - -``sizeof_args (type, member, align)`` - - Helper function used to determine structure sizes - -**Parameters** - -``type`` - Argument structure type - -``member`` - Member inside the type - -``align`` - Alignment information - - -.. c:function:: int nvme_submit_admin_passthru64 (int fd, struct nvme_passthru_cmd64 *cmd, __u64 *result) - - Submit a 64-bit nvme passthrough admin command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_passthru_cmd64 *cmd`` - The nvme admin command to send - -``__u64 *result`` - Optional field to return the result from the CQE DW0-1 - -**Description** - -Uses NVME_IOCTL_ADMIN64_CMD for the ioctl request. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_admin_passthru64 (int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u64 *result) - - Submit a 64-bit nvme passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 opcode`` - The nvme io command to send - -``__u8 flags`` - NVMe command flags (not used) - -``__u16 rsvd`` - Reserved for future use - -``__u32 nsid`` - Namespace identifier - -``__u32 cdw2`` - Command dword 2 - -``__u32 cdw3`` - Command dword 3 - -``__u32 cdw10`` - Command dword 10 - -``__u32 cdw11`` - Command dword 11 - -``__u32 cdw12`` - Command dword 12 - -``__u32 cdw13`` - Command dword 13 - -``__u32 cdw14`` - Command dword 14 - -``__u32 cdw15`` - Command dword 15 - -``__u32 data_len`` - Length of the data transferred in this command in bytes - -``void *data`` - Pointer to user address of the data buffer - -``__u32 metadata_len`` - Length of metadata transferred in this command - -``void *metadata`` - Pointer to user address of the metadata buffer - -``__u32 timeout_ms`` - How long the kernel waits for the command to complete - -``__u64 *result`` - Optional field to return the result from the CQE dword 0 - -**Description** - -Parameterized form of nvme_submit_admin_passthru64(). This sets up and -submits a :c:type:`struct nvme_passthru_cmd64 `. - -Known values for **opcode** are defined in :c:type:`enum nvme_admin_opcode `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_submit_admin_passthru (int fd, struct nvme_passthru_cmd *cmd, __u32 *result) - - Submit an nvme passthrough admin command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_passthru_cmd *cmd`` - The nvme admin command to send - -``__u32 *result`` - Optional field to return the result from the CQE DW0 - -**Description** - -Uses NVME_IOCTL_ADMIN_CMD for the ioctl request. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_admin_passthru (int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u32 *result) - - Submit an nvme passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 opcode`` - The nvme io command to send - -``__u8 flags`` - NVMe command flags (not used) - -``__u16 rsvd`` - Reserved for future use - -``__u32 nsid`` - Namespace identifier - -``__u32 cdw2`` - Command dword 2 - -``__u32 cdw3`` - Command dword 3 - -``__u32 cdw10`` - Command dword 10 - -``__u32 cdw11`` - Command dword 11 - -``__u32 cdw12`` - Command dword 12 - -``__u32 cdw13`` - Command dword 13 - -``__u32 cdw14`` - Command dword 14 - -``__u32 cdw15`` - Command dword 15 - -``__u32 data_len`` - Length of the data transferred in this command in bytes - -``void *data`` - Pointer to user address of the data buffer - -``__u32 metadata_len`` - Length of metadata transferred in this command - -``void *metadata`` - Pointer to user address of the metadata buffer - -``__u32 timeout_ms`` - How long the kernel waits for the command to complete - -``__u32 *result`` - Optional field to return the result from the CQE dword 0 - -**Description** - -Parameterized form of nvme_submit_admin_passthru(). This sets up and -submits a :c:type:`struct nvme_passthru_cmd `. - -Known values for **opcode** are defined in :c:type:`enum nvme_admin_opcode `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_submit_io_passthru64 (int fd, struct nvme_passthru_cmd64 *cmd, __u64 *result) - - Submit a 64-bit nvme passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_passthru_cmd64 *cmd`` - The nvme io command to send - -``__u64 *result`` - Optional field to return the result from the CQE DW0-1 - -**Description** - -Uses NVME_IOCTL_IO64_CMD for the ioctl request. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_io_passthru64 (int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u64 *result) - - Submit an nvme io passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 opcode`` - The nvme io command to send - -``__u8 flags`` - NVMe command flags (not used) - -``__u16 rsvd`` - Reserved for future use - -``__u32 nsid`` - Namespace identifier - -``__u32 cdw2`` - Command dword 2 - -``__u32 cdw3`` - Command dword 3 - -``__u32 cdw10`` - Command dword 10 - -``__u32 cdw11`` - Command dword 11 - -``__u32 cdw12`` - Command dword 12 - -``__u32 cdw13`` - Command dword 13 - -``__u32 cdw14`` - Command dword 14 - -``__u32 cdw15`` - Command dword 15 - -``__u32 data_len`` - Length of the data transferred in this command in bytes - -``void *data`` - Pointer to user address of the data buffer - -``__u32 metadata_len`` - Length of metadata transferred in this command - -``void *metadata`` - Pointer to user address of the metadata buffer - -``__u32 timeout_ms`` - How long the kernel waits for the command to complete - -``__u64 *result`` - Optional field to return the result from the CQE dword 0 - -**Description** - -Parameterized form of nvme_submit_io_passthru64(). This sets up and submits -a :c:type:`struct nvme_passthru_cmd64 `. - -Known values for **opcode** are defined in :c:type:`enum nvme_io_opcode `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_submit_io_passthru (int fd, struct nvme_passthru_cmd *cmd, __u32 *result) - - Submit an nvme passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_passthru_cmd *cmd`` - The nvme io command to send - -``__u32 *result`` - Optional field to return the result from the CQE DW0 - -**Description** - -Uses NVME_IOCTL_IO_CMD for the ioctl request. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_io_passthru (int fd, __u8 opcode, __u8 flags, __u16 rsvd, __u32 nsid, __u32 cdw2, __u32 cdw3, __u32 cdw10, __u32 cdw11, __u32 cdw12, __u32 cdw13, __u32 cdw14, __u32 cdw15, __u32 data_len, void *data, __u32 metadata_len, void *metadata, __u32 timeout_ms, __u32 *result) - - Submit an nvme io passthrough command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 opcode`` - The nvme io command to send - -``__u8 flags`` - NVMe command flags (not used) - -``__u16 rsvd`` - Reserved for future use - -``__u32 nsid`` - Namespace identifier - -``__u32 cdw2`` - Command dword 2 - -``__u32 cdw3`` - Command dword 3 - -``__u32 cdw10`` - Command dword 10 - -``__u32 cdw11`` - Command dword 11 - -``__u32 cdw12`` - Command dword 12 - -``__u32 cdw13`` - Command dword 13 - -``__u32 cdw14`` - Command dword 14 - -``__u32 cdw15`` - Command dword 15 - -``__u32 data_len`` - Length of the data transferred in this command in bytes - -``void *data`` - Pointer to user address of the data buffer - -``__u32 metadata_len`` - Length of metadata transferred in this command - -``void *metadata`` - Pointer to user address of the metadata buffer - -``__u32 timeout_ms`` - How long the kernel waits for the command to complete - -``__u32 *result`` - Optional field to return the result from the CQE dword 0 - -**Description** - -Parameterized form of nvme_submit_io_passthru(). This sets up and submits -a :c:type:`struct nvme_passthru_cmd `. - -Known values for **opcode** are defined in :c:type:`enum nvme_io_opcode `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_subsystem_reset (int fd) - - Initiate a subsystem reset - -**Parameters** - -``int fd`` - File descriptor of nvme device - -**Description** - -This should only be sent to controller handles, not to namespaces. - -**Return** - -Zero if a subsystem reset was initiated or -1 with errno set -otherwise. - - -.. c:function:: int nvme_ctrl_reset (int fd) - - Initiate a controller reset - -**Parameters** - -``int fd`` - File descriptor of nvme device - -**Description** - -This should only be sent to controller handles, not to namespaces. - -**Return** - -0 if a reset was initiated or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_rescan (int fd) - - Initiate a controller rescan - -**Parameters** - -``int fd`` - File descriptor of nvme device - -**Description** - -This should only be sent to controller handles, not to namespaces. - -**Return** - -0 if a rescan was initiated or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_nsid (int fd, __u32 *nsid) - - Retrieve the NSID from a namespace file descriptor - -**Parameters** - -``int fd`` - File descriptor of nvme namespace - -``__u32 *nsid`` - User pointer to namespace id - -**Description** - -This should only be sent to namespace handles, not to controllers. The -kernel's interface returns the nsid as the return value. This is unfortunate -for many architectures that are incapable of allowing distinguishing a -namespace id > 0x80000000 from a negative error number. - -**Return** - -0 if **nsid** was set successfully or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify (struct nvme_identify_args *args) - - Send the NVMe Identify command - -**Parameters** - -``struct nvme_identify_args *args`` - :c:type:`struct nvme_identify_args ` argument structure - -**Description** - -The Identify command returns a data buffer that describes information about -the NVM subsystem, the controller or the namespace(s). - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ctrl (int fd, struct nvme_id_ctrl *id) - - Retrieves nvme identify controller - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_id_ctrl *id`` - User space destination address to transfer the data, - -**Description** - -Sends nvme identify with CNS value ``NVME_IDENTIFY_CNS_CTRL``. - -See :c:type:`struct nvme_id_ctrl ` for details on the data returned. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ns (int fd, __u32 nsid, struct nvme_id_ns *ns) - - Retrieves nvme identify namespace - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace to identify - -``struct nvme_id_ns *ns`` - User space destination address to transfer the data - -**Description** - -If the Namespace Identifier (NSID) field specifies an active NSID, then the -Identify Namespace data structure is returned to the host for that specified -namespace. - -If the controller supports the Namespace Management capability and the NSID -field is set to ``NVME_NSID_ALL``, then the controller returns an Identify Namespace -data structure that specifies capabilities that are common across namespaces -for this controller. - -See :c:type:`struct nvme_id_ns ` for details on the structure returned. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_allocated_ns (int fd, __u32 nsid, struct nvme_id_ns *ns) - - Same as nvme_identify_ns, but only for allocated namespaces - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace to identify - -``struct nvme_id_ns *ns`` - User space destination address to transfer the data - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_active_ns_list (int fd, __u32 nsid, struct nvme_ns_list *list) - - Retrieves active namespaces id list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return namespaces greater than this identifier - -``struct nvme_ns_list *list`` - User space destination address to transfer the data - -**Description** - -A list of 1024 namespace IDs is returned to the host containing NSIDs in -increasing order that are greater than the value specified in the Namespace -Identifier (nsid) field of the command. - -See :c:type:`struct nvme_ns_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_allocated_ns_list (int fd, __u32 nsid, struct nvme_ns_list *list) - - Retrieves allocated namespace id list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return namespaces greater than this identifier - -``struct nvme_ns_list *list`` - User space destination address to transfer the data - -**Description** - -A list of 1024 namespace IDs is returned to the host containing NSIDs in -increasing order that are greater than the value specified in the Namespace -Identifier (nsid) field of the command. - -See :c:type:`struct nvme_ns_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ctrl_list (int fd, __u16 cntid, struct nvme_ctrl_list *cntlist) - - Retrieves identify controller list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 cntid`` - Starting CNTLID to return in the list - -``struct nvme_ctrl_list *cntlist`` - User space destination address to transfer the data - -**Description** - -Up to 2047 controller identifiers is returned containing a controller -identifier greater than or equal to the controller identifier specified in -**cntid**. - -See :c:type:`struct nvme_ctrl_list ` for a definition of the structure returned. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_nsid_ctrl_list (int fd, __u32 nsid, __u16 cntid, struct nvme_ctrl_list *cntlist) - - Retrieves controller list attached to an nsid - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return controllers that are attached to this nsid - -``__u16 cntid`` - Starting CNTLID to return in the list - -``struct nvme_ctrl_list *cntlist`` - User space destination address to transfer the data - -**Description** - -Up to 2047 controller identifiers are returned containing a controller -identifier greater than or equal to the controller identifier specified in -**cntid** attached to **nsid**. - -See :c:type:`struct nvme_ctrl_list ` for a definition of the structure returned. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 - - -.. c:function:: int nvme_identify_ns_descs (int fd, __u32 nsid, struct nvme_ns_id_desc *descs) - - Retrieves namespace descriptor list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - The namespace id to retrieve descriptors - -``struct nvme_ns_id_desc *descs`` - User space destination address to transfer the data - -**Description** - -A list of Namespace Identification Descriptor structures is returned to the -host for the namespace specified in the Namespace Identifier (NSID) field if -it is an active NSID. - -The data returned is in the form of an array of 'struct nvme_ns_id_desc'. - -See :c:type:`struct nvme_ns_id_desc ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_nvmset_list (int fd, __u16 nvmsetid, struct nvme_id_nvmset_list *nvmset) - - Retrieves NVM Set List - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 nvmsetid`` - NVM Set Identifier - -``struct nvme_id_nvmset_list *nvmset`` - User space destination address to transfer the data - -**Description** - -Retrieves an NVM Set List, :c:type:`struct nvme_id_nvmset_list `. The data structure -is an ordered list by NVM Set Identifier, starting with the first NVM Set -Identifier supported by the NVM subsystem that is equal to or greater than -the NVM Set Identifier. - -See :c:type:`struct nvme_id_nvmset_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_primary_ctrl (int fd, __u16 cntid, struct nvme_primary_ctrl_cap *cap) - - Retrieve NVMe Primary Controller identification - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 cntid`` - Return controllers starting at this identifier - -``struct nvme_primary_ctrl_cap *cap`` - User space destination buffer address to transfer the data - -**Description** - -See :c:type:`struct nvme_primary_ctrl_cap ` for the definition of the returned structure, **cap**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum 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) - - Retrieves secondary controller list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace identifier - -``__u16 cntid`` - Return controllers starting at this identifier - -``struct nvme_secondary_ctrl_list *sc_list`` - User space destination address to transfer the data - -**Description** - -A Secondary Controller List is returned to the host for up to 127 secondary -controllers associated with the primary controller processing this command. -The list contains entries for controller identifiers greater than or equal -to the value specified in the Controller Identifier (cntid). - -See :c:type:`struct nvme_secondary_ctrls_list ` for a definition of the returned -structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ns_granularity (int fd, struct nvme_id_ns_granularity_list *gr_list) - - Retrieves namespace granularity identification - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_id_ns_granularity_list *gr_list`` - User space destination address to transfer the data - -**Description** - -If the controller supports reporting of Namespace Granularity, then a -Namespace Granularity List is returned to the host for up to sixteen -namespace granularity descriptors - -See :c:type:`struct nvme_id_ns_granularity_list ` for the definition of the returned -structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_uuid (int fd, struct nvme_id_uuid_list *uuid_list) - - Retrieves device's UUIDs - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_id_uuid_list *uuid_list`` - User space destination address to transfer the data - -**Description** - -Each UUID List entry is either 0h, the NVMe Invalid UUID, or a valid UUID. -Valid UUIDs are those which are non-zero and are not the NVMe Invalid UUID. - -See :c:type:`struct nvme_id_uuid_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ns_csi (int fd, __u32 nsid, __u8 uuidx, enum nvme_csi csi, void *data) - - I/O command set specific identify namespace data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace to identify - -``__u8 uuidx`` - UUID Index for differentiating vendor specific encoding - -``enum nvme_csi csi`` - Command Set Identifier - -``void *data`` - User space destination address to transfer the data - -**Description** - -An I/O Command Set specific Identify Namespace data structure is returned -for the namespace specified in **nsid**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ctrl_csi (int fd, enum nvme_csi csi, void *data) - - I/O command set specific Identify Controller data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_csi csi`` - Command Set Identifier - -``void *data`` - User space destination address to transfer the data - -**Description** - -An I/O Command Set specific Identify Controller data structure is returned -to the host for the controller processing the command. The specific Identify -Controller data structure to be returned is specified by **csi**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_active_ns_list_csi (int fd, __u32 nsid, enum nvme_csi csi, struct nvme_ns_list *ns_list) - - Active namespace ID list associated with a specified I/O command set - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return namespaces greater than this identifier - -``enum nvme_csi csi`` - Command Set Identifier - -``struct nvme_ns_list *ns_list`` - User space destination address to transfer the data - -**Description** - -A list of 1024 namespace IDs is returned to the host containing active -NSIDs in increasing order that are greater than the value specified in -the Namespace Identifier (nsid) field of the command and matching the -I/O Command Set specified in the **csi** argument. - -See :c:type:`struct nvme_ns_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_allocated_ns_list_csi (int fd, __u32 nsid, enum nvme_csi csi, struct nvme_ns_list *ns_list) - - Allocated namespace ID list associated with a specified I/O command set - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return namespaces greater than this identifier - -``enum nvme_csi csi`` - Command Set Identifier - -``struct nvme_ns_list *ns_list`` - User space destination address to transfer the data - -**Description** - -A list of 1024 namespace IDs is returned to the host containing allocated -NSIDs in increasing order that are greater than the value specified in -the **nsid** field of the command and matching the I/O Command Set -specified in the **csi** argument. - -See :c:type:`struct nvme_ns_list ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_independent_identify_ns (int fd, __u32 nsid, struct nvme_id_independent_id_ns *ns) - - I/O command set independent Identify namespace data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Return namespaces greater than this identifier - -``struct nvme_id_independent_id_ns *ns`` - I/O Command Set Independent Identify Namespace data - structure - -**Description** - -The I/O command set independent Identify namespace data structure for -the namespace identified with **ns** is returned to the host. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_ns_csi_user_data_format (int fd, __u16 user_data_format, __u8 uuidx, enum nvme_csi csi, void *data) - - Identify namespace user data format - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 user_data_format`` - Return namespaces capability of identifier - -``__u8 uuidx`` - UUID selection, if supported - -``enum nvme_csi csi`` - Command Set Identifier - -``void *data`` - User space destination address to transfer the data - -**Description** - -Identify Namespace data structure for the specified User Data Format -index containing the namespace capabilities for the NVM Command Set. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_iocs_ns_csi_user_data_format (int fd, __u16 user_data_format, __u8 uuidx, enum nvme_csi csi, void *data) - - Identify I/O command set namespace data structure - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 user_data_format`` - Return namespaces capability of identifier - -``__u8 uuidx`` - UUID selection, if supported - -``enum nvme_csi csi`` - Command Set Identifier - -``void *data`` - User space destination address to transfer the data - -**Description** - -I/O Command Set specific Identify Namespace data structure for -the specified User Data Format index containing the namespace -capabilities for the I/O Command Set specified in the CSI field. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_nvm_identify_ctrl (int fd, struct nvme_id_ctrl_nvm *id) - - Identify controller data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_id_ctrl_nvm *id`` - User space destination address to transfer the data - -**Description** - -Return an identify controller data structure to the host of -processing controller. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_domain_list (int fd, __u16 domid, struct nvme_id_domain_list *list) - - Domain list data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 domid`` - Domain ID - -``struct nvme_id_domain_list *list`` - User space destination address to transfer data - -**Description** - -A list of 31 domain IDs is returned to the host containing domain -attributes in increasing order that are greater than the value -specified in the **domid** field. - -See :c:type:`struct nvme_identify_domain_attr ` for the definition of the -returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_endurance_group_list (int fd, __u16 endgrp_id, struct nvme_id_endurance_group_list *list) - - Endurance group list data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 endgrp_id`` - Endurance group identifier - -``struct nvme_id_endurance_group_list *list`` - Array of endurance group identifiers - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_identify_iocs (int fd, __u16 cntlid, struct nvme_id_iocs *iocs) - - I/O command set data structure - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 cntlid`` - Controller ID - -``struct nvme_id_iocs *iocs`` - User space destination address to transfer the data - -**Description** - -Retrieves list of the controller's supported io command set vectors. See -:c:type:`struct nvme_id_iocs `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_identify_ns (int fd, __u32 nsid, struct nvme_zns_id_ns *data) - - ZNS identify namespace data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace to identify - -``struct nvme_zns_id_ns *data`` - User space destination address to transfer the data - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_identify_ctrl (int fd, struct nvme_zns_id_ctrl *id) - - ZNS identify controller data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_zns_id_ctrl *id`` - User space destination address to transfer the data - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log (struct nvme_get_log_args *args) - - NVMe Admin Get Log command - -**Parameters** - -``struct nvme_get_log_args *args`` - :c:type:`struct nvme_get_log_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_supported_log_pages (int fd, bool rae, struct nvme_supported_log_pages *log) - - Retrieve nmve supported log pages - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_supported_log_pages *log`` - Array of LID supported and Effects data structures - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_error (int fd, unsigned int nr_entries, bool rae, struct nvme_error_log_page *err_log) - - Retrieve nvme error log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``unsigned int nr_entries`` - Number of error log entries allocated - -``bool rae`` - Retain asynchronous events - -``struct nvme_error_log_page *err_log`` - Array of error logs of size 'entries' - -**Description** - -This log page describes extended error information for a command that -completed with error, or may report an error that is not specific to a -particular command. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_smart (int fd, __u32 nsid, bool rae, struct nvme_smart_log *smart_log) - - Retrieve nvme smart log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Optional namespace identifier - -``bool rae`` - Retain asynchronous events - -``struct nvme_smart_log *smart_log`` - User address to store the smart log - -**Description** - -This log page provides SMART and general health information. The information -provided is over the life of the controller and is retained across power -cycles. To request the controller log page, the namespace identifier -specified is FFFFFFFFh. The controller may also support requesting the log -page on a per namespace basis, as indicated by bit 0 of the LPA field in the -Identify Controller data structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_fw_slot (int fd, bool rae, struct nvme_firmware_slot *fw_log) - - Retrieves the controller firmware log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_firmware_slot *fw_log`` - User address to store the log page - -**Description** - -This log page describes the firmware revision stored in each firmware slot -supported. The firmware revision is indicated as an ASCII string. The log -page also indicates the active slot number. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_changed_ns_list (int fd, bool rae, struct nvme_ns_list *ns_log) - - Retrieve namespace changed list - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_ns_list *ns_log`` - User address to store the log page - -**Description** - -This log page describes namespaces attached to this controller that have -changed since the last time the namespace was identified, been added, or -deleted. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_cmd_effects (int fd, enum nvme_csi csi, struct nvme_cmd_effects_log *effects_log) - - Retrieve nvme command effects log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_csi csi`` - Command Set Identifier - -``struct nvme_cmd_effects_log *effects_log`` - User address to store the effects log - -**Description** - -This log page describes the commands that the controller supports and the -effects of those commands on the state of the NVM subsystem. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_device_self_test (int fd, struct nvme_self_test_log *log) - - Retrieve the device self test log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_self_test_log *log`` - Userspace address of the log payload - -**Description** - -The log page indicates the status of an in progress self test and the -percent complete of that operation, and the results of the previous 20 -self-test operations. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_create_telemetry_host (int fd, struct nvme_telemetry_log *log) - - Create host telemetry log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_telemetry_log *log`` - Userspace address of the log payload - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_telemetry_host (int fd, __u64 offset, __u32 len, void *log) - - Get Telemetry Host-Initiated log page - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u64 offset`` - Offset into the telemetry data - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Description** - -Retrieves the Telemetry Host-Initiated log page at the requested offset -using the previously existing capture. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_telemetry_ctrl (int fd, bool rae, __u64 offset, __u32 len, void *log) - - Get Telemetry Controller-Initiated log page - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset into the telemetry data - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Description** - -Retrieves the Telemetry Controller-Initiated log page at the requested offset -using the previously existing capture. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_endurance_group (int fd, __u16 endgid, struct nvme_endurance_group_log *log) - - Get Endurance Group log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 endgid`` - Starting group identifier to return in the list - -``struct nvme_endurance_group_log *log`` - User address to store the endurance log - -**Description** - -This log page indicates if an Endurance Group Event has occurred for a -particular Endurance Group. If an Endurance Group Event has occurred, the -details of the particular event are included in the Endurance Group -Information log page for that Endurance Group. An asynchronous event is -generated when an entry for an Endurance Group is newly added to this log -page. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_predictable_lat_nvmset (int fd, __u16 nvmsetid, struct nvme_nvmset_predictable_lat_log *log) - - Predictable Latency Per NVM Set - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 nvmsetid`` - NVM set id - -``struct nvme_nvmset_predictable_lat_log *log`` - User address to store the predictable latency log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_predictable_lat_event (int fd, bool rae, __u32 offset, __u32 len, void *log) - - Retrieve Predictable Latency Event Aggregate Log Page - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset into the predictable latency event - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_ana (int fd, enum nvme_log_ana_lsp lsp, bool rae, __u64 offset, __u32 len, void *log) - - Retrieve Asymmetric Namespace Access log page - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_log_ana_lsp lsp`` - Log specific, see :c:type:`enum nvme_get_log_ana_lsp ` - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *log`` - User address to store the ana log - -**Description** - -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 ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum 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) - - Retrieve Asymmetric Namespace Access groups only log page - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u32 len`` - The allocated length of the log page - -``struct nvme_ana_group_desc *log`` - User address to store the ana group log - -**Description** - -See :c:type:`struct nvme_ana_group_desc ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_lba_status (int fd, bool rae, __u64 offset, __u32 len, void *log) - - Retrieve LBA Status - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_endurance_grp_evt (int fd, bool rae, __u32 offset, __u32 len, void *log) - - Retrieve Rotational Media Information - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_fid_supported_effects (int fd, bool rae, struct nvme_fid_supported_effects_log *log) - - Retrieve Feature Identifiers Supported and Effects - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_fid_supported_effects_log *log`` - FID Supported and Effects data structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise - - -.. c:function:: int nvme_get_log_mi_cmd_supported_effects (int fd, bool rae, struct nvme_mi_cmd_supported_effects_log *log) - - displays the MI Commands Supported by the controller - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_mi_cmd_supported_effects_log *log`` - MI Command Supported and Effects data structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise - - -.. c:function:: int nvme_get_log_boot_partition (int fd, bool rae, __u8 lsp, __u32 len, struct nvme_boot_partition *part) - - Retrieve Boot Partition - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u8 lsp`` - The log specified field of LID - -``__u32 len`` - The allocated size, minimum - struct nvme_boot_partition - -``struct nvme_boot_partition *part`` - User address to store the log page - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum 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 - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset of this log to retrieve - -``__u32 len`` - The allocated size for this portion of the log - -``void *log`` - User address to store the discovery log - -**Description** - -Supported only by fabrics discovery controllers, returning discovery -records. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_media_unit_stat (int fd, __u16 domid, struct nvme_media_unit_stat_log *mus) - - Retrieve Media Unit Status - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 domid`` - Domain Identifier selection, if supported - -``struct nvme_media_unit_stat_log *mus`` - User address to store the Media Unit statistics log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise - - -.. c:function:: int nvme_get_log_support_cap_config_list (int fd, __u16 domid, struct nvme_supported_cap_config_list_log *cap) - - Retrieve Supported Capacity Configuration List - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 domid`` - Domain Identifier selection, if supported - -``struct nvme_supported_cap_config_list_log *cap`` - User address to store supported capabilities config list - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise - - -.. c:function:: int nvme_get_log_reservation (int fd, bool rae, struct nvme_resv_notification_log *log) - - Retrieve Reservation Notification - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_resv_notification_log *log`` - User address to store the reservation log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise - - -.. c:function:: int nvme_get_log_sanitize (int fd, bool rae, struct nvme_sanitize_log_page *log) - - Retrieve Sanitize Status - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_sanitize_log_page *log`` - User address to store the sanitize log - -**Description** - -The Sanitize Status log page reports sanitize operation time estimates and -information about the most recent sanitize operation. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_zns_changed_zones (int fd, __u32 nsid, bool rae, struct nvme_zns_changed_zone_log *log) - - Retrieve list of zones that have changed - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``bool rae`` - Retain asynchronous events - -``struct nvme_zns_changed_zone_log *log`` - User address to store the changed zone log - -**Description** - -The list of zones that have changed state due to an exceptional event. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_persistent_event (int fd, enum nvme_pevent_log_action action, __u32 size, void *pevent_log) - - Retrieve Persistent Event Log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_pevent_log_action action`` - Action the controller should take during processing this command - -``__u32 size`` - Size of **pevent_log** - -``void *pevent_log`` - User address to store the persistent event log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features (struct nvme_set_features_args *args) - - Set a feature attribute - -**Parameters** - -``struct nvme_set_features_args *args`` - :c:type:`struct nvme_set_features_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_data (int fd, __u8 fid, __u32 nsid, __u32 cdw11, bool save, __u32 data_len, void *data, __u32 *result) - - Helper function for **nvme_set_features\(\)** - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 fid`` - Feature identifier - -``__u32 nsid`` - Namespace ID, if applicable - -``__u32 cdw11`` - Value to set the feature to - -``bool save`` - Save value across power states - -``__u32 data_len`` - Length of feature data, if applicable, in bytes - -``void *data`` - User address of feature data, if applicable - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_simple (int fd, __u8 fid, __u32 nsid, __u32 cdw11, bool save, __u32 *result) - - Helper function for **nvme_set_features\(\)** - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 fid`` - Feature identifier - -``__u32 nsid`` - Namespace ID, if applicable - -``__u32 cdw11`` - Value to set the feature to - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_arbitration (int fd, __u8 ab, __u8 lpw, __u8 mpw, __u8 hpw, bool save, __u32 *result) - - Set arbitration features - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 ab`` - Arbitration Burst - -``__u8 lpw`` - Low Priority Weight - -``__u8 mpw`` - Medium Priority Weight - -``__u8 hpw`` - High Priority Weight - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_power_mgmt (int fd, __u8 ps, __u8 wh, bool save, __u32 *result) - - Set power management feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 ps`` - Power State - -``__u8 wh`` - Workload Hint - -``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 `) 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) - - Set LBA range feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``__u32 nr_ranges`` - Number of ranges in **data** - -``bool save`` - Save value across power states - -``struct nvme_lba_range_type *data`` - User address of feature data - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_temp_thresh (int fd, __u16 tmpth, __u8 tmpsel, enum nvme_feat_tmpthresh_thsel thsel, bool save, __u32 *result) - - Set temperature threshold feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 tmpth`` - Temperature Threshold - -``__u8 tmpsel`` - Threshold Temperature Select - -``enum nvme_feat_tmpthresh_thsel thsel`` - Threshold Type Select - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_err_recovery (int fd, __u32 nsid, __u16 tler, bool dulbe, bool save, __u32 *result) - - Set error recovery feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``__u16 tler`` - Time-limited error recovery value - -``bool dulbe`` - Deallocated or Unwritten Logical Block Error Enable - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_volatile_wc (int fd, bool wce, bool save, __u32 *result) - - Set volatile write cache feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool wce`` - Write cache enable - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_irq_coalesce (int fd, __u8 thr, __u8 time, bool save, __u32 *result) - - Set IRQ coalesce feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 thr`` - Aggregation Threshold - -``__u8 time`` - Aggregation Time - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_irq_config (int fd, __u16 iv, bool cd, bool save, __u32 *result) - - Set IRQ config feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 iv`` - Interrupt Vector - -``bool cd`` - Coalescing Disable - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_write_atomic (int fd, bool dn, bool save, __u32 *result) - - Set write atomic feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool dn`` - Disable Normal - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_async_event (int fd, __u32 events, bool save, __u32 *result) - - Set asynchronous event feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 events`` - Events to enable - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_auto_pst (int fd, bool apste, bool save, struct nvme_feat_auto_pst *apst, __u32 *result) - - Set autonomous power state feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool apste`` - Autonomous Power State Transition Enable - -``bool save`` - Save value across power states - -``struct nvme_feat_auto_pst *apst`` - Autonomous Power State Transition - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_timestamp (int fd, bool save, __u64 timestamp) - - Set timestamp feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool save`` - Save value across power states - -``__u64 timestamp`` - The current timestamp value to assign to this feature - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_hctm (int fd, __u16 tmt2, __u16 tmt1, bool save, __u32 *result) - - Set thermal management feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 tmt2`` - Thermal Management Temperature 2 - -``__u16 tmt1`` - Thermal Management Temperature 1 - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_nopsc (int fd, bool noppme, bool save, __u32 *result) - - Set non-operational power state feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool noppme`` - Non-Operational Power State Permissive Mode Enable - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_rrl (int fd, __u8 rrl, __u16 nvmsetid, bool save, __u32 *result) - - Set read recovery level feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 rrl`` - Read recovery level setting - -``__u16 nvmsetid`` - NVM set id - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_plm_config (int fd, bool enable, __u16 nvmsetid, bool save, struct nvme_plm_config *data, __u32 *result) - - Set predictable latency feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool enable`` - Predictable Latency Enable - -``__u16 nvmsetid`` - NVM Set Identifier - -``bool save`` - Save value across power states - -``struct nvme_plm_config *data`` - Pointer to structure nvme_plm_config - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_plm_window (int fd, enum nvme_feat_plm_window_select sel, __u16 nvmsetid, bool save, __u32 *result) - - Set window select feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_feat_plm_window_select sel`` - Window Select - -``__u16 nvmsetid`` - NVM Set Identifier - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_lba_sts_interval (int fd, __u16 lsiri, __u16 lsipi, bool save, __u32 *result) - - Set LBA status information feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 lsiri`` - LBA Status Information Report Interval - -``__u16 lsipi`` - LBA Status Information Poll Interval - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_host_behavior (int fd, bool save, struct nvme_feat_host_behavior *data) - - Set host behavior feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool save`` - Save value across power states - -``struct nvme_feat_host_behavior *data`` - Pointer to structure nvme_feat_host_behavior - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_sanitize (int fd, bool nodrm, bool save, __u32 *result) - - Set sanitize feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool nodrm`` - No-Deallocate Response Mode - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_endurance_evt_cfg (int fd, __u16 endgid, __u8 egwarn, bool save, __u32 *result) - - Set endurance event config feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u16 endgid`` - Endurance Group Identifier - -``__u8 egwarn`` - Flags to enable warning, see :c:type:`enum nvme_eg_critical_warning_flags ` - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_sw_progress (int fd, __u8 pbslc, bool save, __u32 *result) - - Set pre-boot software load count feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u8 pbslc`` - Pre-boot Software Load Count - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_host_id (int fd, bool exhid, bool save, __u8 *hostid) - - Set enable extended host identifiers feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool exhid`` - Enable Extended Host Identifier - -``bool save`` - Save value across power states - -``__u8 *hostid`` - Host ID to set - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_resv_mask (int fd, __u32 mask, bool save, __u32 *result) - - Set reservation notification mask feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__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 -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_resv_persist (int fd, bool ptpl, bool save, __u32 *result) - - Set persist through power loss feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``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 -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_features_write_protect (int fd, enum nvme_feat_nswpcfg_state state, bool save, __u32 *result) - - Set write protect feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features (struct nvme_get_features_args *args) - - Retrieve a feature attribute - -**Parameters** - -``struct nvme_get_features_args *args`` - :c:type:`struct nvme_get_features_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_data (int fd, enum nvme_features_id fid, __u32 nsid, __u32 data_len, void *data, __u32 *result) - - Helper function for **nvme_get_features\(\)** - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_features_id fid`` - Feature identifier - -``__u32 nsid`` - Namespace ID, if applicable - -``__u32 data_len`` - Length of feature data, if applicable, in bytes - -``void *data`` - User address of feature data, if applicable - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_simple (int fd, enum nvme_features_id fid, __u32 nsid, __u32 *result) - - Helper function for **nvme_get_features\(\)** - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``enum nvme_features_id fid`` - Feature identifier - -``__u32 nsid`` - Namespace ID, if applicable - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_arbitration (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get arbitration 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_power_mgmt (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get power management 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_lba_range (int fd, enum nvme_get_features_sel sel, 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 ` - -``struct nvme_lba_range_type *data`` - User address of feature data, if applicable - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_temp_thresh (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get temperature threshold 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_err_recovery (int fd, enum nvme_get_features_sel sel, __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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_volatile_wc (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get volatile write cache 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_num_queues (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get number of queues 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_irq_coalesce (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get IRQ coalesce 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_irq_config (int fd, enum nvme_get_features_sel sel, __u16 iv, __u32 *result) - - Get IRQ config 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 ` - -``__u16 iv`` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_write_atomic (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get write atomic 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_async_event (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get asynchronous event 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_auto_pst (int fd, enum nvme_get_features_sel sel, struct nvme_feat_auto_pst *apst, __u32 *result) - - Get autonomous power state 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 ` - -``struct nvme_feat_auto_pst *apst`` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_host_mem_buf (int fd, enum nvme_get_features_sel sel, __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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_timestamp (int fd, enum nvme_get_features_sel sel, struct nvme_timestamp *ts) - - Get timestamp 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 ` - -``struct nvme_timestamp *ts`` - Current timestamp - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_kato (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get keep alive timeout 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_hctm (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get thermal management 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_nopsc (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get non-operational power state 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_rrl (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get read recovery level 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_plm_config (int fd, enum nvme_get_features_sel sel, __u16 nvmsetid, struct nvme_plm_config *data, __u32 *result) - - Get predictable latency 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 ` - -``__u16 nvmsetid`` - NVM set id - -``struct nvme_plm_config *data`` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_plm_window (int fd, enum nvme_get_features_sel sel, __u16 nvmsetid, __u32 *result) - - Get window select 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 ` - -``__u16 nvmsetid`` - NVM set id - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_lba_sts_interval (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get LBA status information 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_host_behavior (int fd, enum nvme_get_features_sel sel, struct nvme_feat_host_behavior *data, __u32 *result) - - Get host behavior 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 ` - -``struct nvme_feat_host_behavior *data`` - Pointer to structure nvme_feat_host_behavior - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_sanitize (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get sanitize 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_endurance_event_cfg (int fd, enum nvme_get_features_sel sel, __u16 endgid, __u32 *result) - - Get endurance event config 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 ` - -``__u16 endgid`` - Endurance Group Identifier - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_sw_progress (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get software progress 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_host_id (int fd, enum nvme_get_features_sel sel, bool exhid, __u32 len, __u8 *hostid) - - Get host id 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 ` - -``bool exhid`` - Enable Extended Host Identifier - -``__u32 len`` - Length of **hostid** - -``__u8 *hostid`` - Buffer for returned host ID - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_resv_mask (int fd, enum nvme_get_features_sel sel, __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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_resv_persist (int fd, enum nvme_get_features_sel sel, __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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_write_protect (int fd, __u32 nsid, enum nvme_get_features_sel sel, __u32 *result) - - Get write protect feature - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``enum nvme_get_features_sel sel`` - Select which type of attribute to return, see :c:type:`enum nvme_get_features_sel ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_features_iocs_profile (int fd, enum nvme_get_features_sel sel, __u32 *result) - - Get IOCS profile 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 ` - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_format_nvm (struct nvme_format_nvm_args *args) - - Format nvme namespace(s) - -**Parameters** - -``struct nvme_format_nvm_args *args`` - :c:type:`struct nvme_format_nvme_args ` argument structure - -**Description** - -The Format NVM command low level formats the NVM media. This command is used -by the host to change the LBA data size and/or metadata size. A low level -format may destroy all data and metadata associated with all namespaces or -only the specific namespace associated with the command - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_mgmt (struct nvme_ns_mgmt_args *args) - - Issue a Namespace management command - -**Parameters** - -``struct nvme_ns_mgmt_args *args`` - :c:type:`struct nvme_ns_mgmt_args ` Argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_mgmt_create (int fd, struct nvme_id_ns *ns, __u32 *nsid, __u32 timeout, __u8 csi) - - Create a non attached namespace - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_id_ns *ns`` - Namespace identification that defines ns creation parameters - -``__u32 *nsid`` - On success, set to the namespace id that was created - -``__u32 timeout`` - Override the default timeout to this value in milliseconds; - set to 0 to use the system default. - -``__u8 csi`` - Command Set Identifier - -**Description** - -On successful creation, the namespace exists in the subsystem, but is not -attached to any controller. Use the nvme_ns_attach_ctrls() to assign the -namespace to one or more controllers. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_mgmt_delete (int fd, __u32 nsid) - - Delete a non attached namespace - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace identifier to delete - -**Description** - -It is recommended that a namespace being deleted is not attached to any -controller. Use the nvme_ns_detach_ctrls() first if the namespace is still -attached. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_attach (struct nvme_ns_attach_args *args) - - Attach or detach namespace to controller(s) - -**Parameters** - -``struct nvme_ns_attach_args *args`` - :c:type:`struct nvme_ns_attach_args ` Argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_attach_ctrls (int fd, __u32 nsid, struct nvme_ctrl_list *ctrlist) - - Attach namespace to controllers - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID to attach - -``struct nvme_ctrl_list *ctrlist`` - Controller list to modify attachment state of nsid - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_ns_detach_ctrls (int fd, __u32 nsid, struct nvme_ctrl_list *ctrlist) - - Detach namespace from controllers - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID to detach - -``struct nvme_ctrl_list *ctrlist`` - Controller list to modify attachment state of nsid - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_fw_download (struct nvme_fw_download_args *args) - - Download part or all of a firmware image to the controller - -**Parameters** - -``struct nvme_fw_download_args *args`` - :c:type:`struct nvme_fw_download_args ` argument structure - -**Description** - -The Firmware Image Download command downloads all or a portion of an image -for a future update to the controller. The Firmware Image Download command -downloads a new image (in whole or in part) to the controller. - -The image may be constructed of multiple pieces that are individually -downloaded with separate Firmware Image Download commands. Each Firmware -Image Download command includes a Dword Offset and Number of Dwords that -specify a dword range. - -The new firmware image is not activated as part of the Firmware Image -Download command. Use the nvme_fw_commit() to activate a newly downloaded -image. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_fw_commit (struct nvme_fw_commit_args *args) - - Commit firmware using the specified action - -**Parameters** - -``struct nvme_fw_commit_args *args`` - :c:type:`struct nvme_fw_commit_args ` argument structure - -**Description** - -The Firmware Commit command modifies the firmware image or Boot Partitions. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. The command -status response may specify additional reset actions required to complete -the commit process. - - -.. c:function:: int nvme_security_send (struct nvme_security_send_args *args) - - Security Send command - -**Parameters** - -``struct nvme_security_send_args *args`` - :c:type:`struct nvme_security_send ` argument structure - -**Description** - -The Security Send command transfers security protocol data to the -controller. The data structure transferred to the controller as part of this -command contains security protocol specific commands to be performed by the -controller. The data structure transferred may also contain data or -parameters associated with the security protocol commands. - -The security data is protocol specific and is not defined by the NVMe -specification. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_security_receive (struct nvme_security_receive_args *args) - - Security Receive command - -**Parameters** - -``struct nvme_security_receive_args *args`` - :c:type:`struct nvme_security_receive ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_lba_status (struct nvme_get_lba_status_args *args) - - Retrieve information on possibly unrecoverable LBAs - -**Parameters** - -``struct nvme_get_lba_status_args *args`` - :c:type:`struct nvme_get_lba_status_args ` argument structure - -**Description** - -The Get LBA Status command requests information about Potentially -Unrecoverable LBAs. Refer to the specification for action type descriptions. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_send (struct nvme_directive_send_args *args) - - Send directive command - -**Parameters** - -``struct nvme_directive_send_args *args`` - :c:type:`struct nvme_directive_send_args ` argument structure - -**Description** - -Directives is a mechanism to enable host and NVM subsystem or controller -information exchange. The Directive Send command transfers data related to a -specific Directive Type from the host to the controller. - -See the NVMe specification for more information. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_send_id_endir (int fd, __u32 nsid, bool endir, enum nvme_directive_dtype dtype, struct nvme_id_directives *id) - - Directive Send Enable Directive - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace Identifier - -``bool endir`` - Enable Directive - -``enum nvme_directive_dtype dtype`` - Directive Type - -``struct nvme_id_directives *id`` - Pointer to structure nvme_id_directives - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_send_stream_release_identifier (int fd, __u32 nsid, __u16 stream_id) - - Directive Send Stream release - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``__u16 stream_id`` - Stream identifier - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_send_stream_release_resource (int fd, __u32 nsid) - - Directive Send Stream release resources - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_recv (struct nvme_directive_recv_args *args) - - Receive directive specific data - -**Parameters** - -``struct nvme_directive_recv_args *args`` - :c:type:`struct nvme_directive_recv_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_recv_identify_parameters (int fd, __u32 nsid, struct nvme_id_directives *id) - - Directive receive identifier parameters - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``struct nvme_id_directives *id`` - Identify parameters buffer - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_recv_stream_parameters (int fd, __u32 nsid, struct nvme_streams_directive_params *parms) - - Directive receive stream parameters - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``struct nvme_streams_directive_params *parms`` - Streams directive parameters buffer - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_recv_stream_status (int fd, __u32 nsid, unsigned int nr_entries, struct nvme_streams_directive_status *id) - - Directive receive stream status - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``unsigned int nr_entries`` - Number of streams to receive - -``struct nvme_streams_directive_status *id`` - Stream status buffer - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_directive_recv_stream_allocate (int fd, __u32 nsid, __u16 nsr, __u32 *result) - - Directive receive stream allocate - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``__u16 nsr`` - Namespace Streams Requested - -``__u32 *result`` - If successful, the CQE dword0 value - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_capacity_mgmt (struct nvme_capacity_mgmt_args *args) - - Capacity management command - -**Parameters** - -``struct nvme_capacity_mgmt_args *args`` - :c:type:`struct nvme_capacity_mgmt_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_lockdown (struct nvme_lockdown_args *args) - - Issue lockdown command - -**Parameters** - -``struct nvme_lockdown_args *args`` - :c:type:`struct nvme_lockdown_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_set_property (struct nvme_set_property_args *args) - - Set controller property - -**Parameters** - -``struct nvme_set_property_args *args`` - :c:type:`struct nvme_set_property_args ` argument structure - -**Description** - -This is an NVMe-over-Fabrics specific command, not applicable to PCIe. These -properties align to the PCI MMIO controller registers. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_property (struct nvme_get_property_args *args) - - Get a controller property - -**Parameters** - -``struct nvme_get_property_args *args`` - :c:type:`struct nvme_get_propert_args ` argument structure - -**Description** - -This is an NVMe-over-Fabrics specific command, not applicable to PCIe. These -properties align to the PCI MMIO controller registers. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_sanitize_nvm (struct nvme_sanitize_nvm_args *args) - - Start a sanitize operation - -**Parameters** - -``struct nvme_sanitize_nvm_args *args`` - :c:type:`struct nvme_sanitize_nvm_args ` argument structure - -**Description** - -A sanitize operation alters all user data in the NVM subsystem such that -recovery of any previous user data from any cache, the non-volatile media, -or any Controller Memory Buffer is not possible. - -The Sanitize command starts a sanitize operation or to recover from a -previously failed sanitize operation. The sanitize operation types that may -be supported are Block Erase, Crypto Erase, and Overwrite. All sanitize -operations are processed in the background, i.e., completion of the sanitize -command does not indicate completion of the sanitize operation. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_dev_self_test (struct nvme_dev_self_test_args *args) - - Start or abort a self test - -**Parameters** - -``struct nvme_dev_self_test_args *args`` - :c:type:`struct nvme_dev_self_test ` argument structure - -**Description** - -The Device Self-test command starts a device self-test operation or abort a -device self-test operation. A device self-test operation is a diagnostic -testing sequence that tests the integrity and functionality of the -controller and may include testing of the media associated with namespaces. -The controller may return a response to this command immediately while -running the self-test in the background. - -Set the 'nsid' field to 0 to not include namespaces in the test. Set to -0xffffffff to test all namespaces. All other values tests a specific -namespace, if present. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_virtual_mgmt (struct nvme_virtual_mgmt_args *args) - - Virtualization resource management - -**Parameters** - -``struct nvme_virtual_mgmt_args *args`` - :c:type:`struct nvme_virtual_mgmt_args ` argument structure - -**Description** - -The Virtualization Management command is supported by primary controllers -that support the Virtualization Enhancements capability. This command is -used for several functions: - - - Modifying Flexible Resource allocation for the primary controller - - Assigning Flexible Resources for secondary controllers - - Setting the Online and Offline state for secondary controllers - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_flush (int fd, __u32 nsid) - - Send an nvme flush command - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace identifier - -**Description** - -The Flush command requests that the contents of volatile write cache be made -non-volatile. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_io (struct nvme_io_args *args, __u8 opcode) - - Submit an nvme user I/O command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -``__u8 opcode`` - Opcode to execute - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_read (struct nvme_io_args *args) - - Submit an nvme user read command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_write (struct nvme_io_args *args) - - Submit an nvme user write command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_compare (struct nvme_io_args *args) - - Submit an nvme user compare command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_write_zeros (struct nvme_io_args *args) - - Submit an nvme write zeroes command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Description** - -The Write Zeroes command sets a range of logical blocks to zero. After -successful completion of this command, the value returned by subsequent -reads of logical blocks in this range shall be all bytes cleared to 0h until -a write occurs to this LBA range. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_write_uncorrectable (struct nvme_io_args *args) - - Submit an nvme write uncorrectable command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Description** - -The Write Uncorrectable command marks a range of logical blocks as invalid. -When the specified logical block(s) are read after this operation, a failure -is returned with Unrecovered Read Error status. To clear the invalid logical -block status, a write operation on those logical blocks is required. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_verify (struct nvme_io_args *args) - - Send an nvme verify command - -**Parameters** - -``struct nvme_io_args *args`` - :c:type:`struct nvme_io_args ` argument structure - -**Description** - -The Verify command verifies integrity of stored information by reading data -and metadata, if applicable, for the LBAs indicated without transferring any -data or metadata to the host. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_dsm (struct nvme_dsm_args *args) - - Send an nvme data set management command - -**Parameters** - -``struct nvme_dsm_args *args`` - :c:type:`struct nvme_dsm_args ` argument structure - -**Description** - -The Dataset Management command is used by the host to indicate attributes -for ranges of logical blocks. This includes attributes like frequency that -data is read or written, access size, and other information that may be used -to optimize performance and reliability, and may be used to -deallocate/unmap/trim those logical blocks. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_copy (struct nvme_copy_args *args) - - Copy command - -**Parameters** - -``struct nvme_copy_args *args`` - :c:type:`struct nvme_copy_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_resv_acquire (struct nvme_resv_acquire_args *args) - - Send an nvme reservation acquire - -**Parameters** - -``struct nvme_resv_acquire_args *args`` - :c:type:`struct nvme_resv_acquire ` argument structure - -**Description** - -The Reservation Acquire command acquires a reservation on a namespace, -preempt a reservation held on a namespace, and abort a reservation held on a -namespace. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_resv_register (struct nvme_resv_register_args *args) - - Send an nvme reservation register - -**Parameters** - -``struct nvme_resv_register_args *args`` - :c:type:`struct nvme_resv_register_args ` argument structure - -**Description** - -The Reservation Register command registers, unregisters, or replaces a -reservation key. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_resv_release (struct nvme_resv_release_args *args) - - Send an nvme reservation release - -**Parameters** - -``struct nvme_resv_release_args *args`` - :c:type:`struct nvme_resv_release_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_resv_report (struct nvme_resv_report_args *args) - - Send an nvme reservation report - -**Parameters** - -``struct nvme_resv_report_args *args`` - struct nvme_resv_report_args argument structure - -**Description** - -Returns a Reservation Status data structure to memory that describes the -registration and reservation status of a namespace. See the definition for -the returned structure, :c:type:`struct nvme_reservation_status `, for more details. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_mgmt_send (struct nvme_zns_mgmt_send_args *args) - - ZNS management send command - -**Parameters** - -``struct nvme_zns_mgmt_send_args *args`` - :c:type:`struct nvme_zns_mgmt_send_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_mgmt_recv (struct nvme_zns_mgmt_recv_args *args) - - ZNS management receive command - -**Parameters** - -``struct nvme_zns_mgmt_recv_args *args`` - :c:type:`struct nvme_zns_mgmt_recv_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_report_zones (int fd, __u32 nsid, __u64 slba, enum nvme_zns_report_options opts, bool extended, bool partial, __u32 data_len, void *data, __u32 timeout, __u32 *result) - - Return the list of zones - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID - -``__u64 slba`` - Starting LBA - -``enum nvme_zns_report_options opts`` - Reporting options - -``bool extended`` - Extended report - -``bool partial`` - Partial report requested - -``__u32 data_len`` - Length of the data buffer - -``void *data`` - Userspace address of the report zones data - -``__u32 timeout`` - timeout in ms - -``__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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_zns_append (struct nvme_zns_append_args *args) - - Append data to a zone - -**Parameters** - -``struct nvme_zns_append_args *args`` - :c:type:`struct nvme_zns_append_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_dim_send (struct nvme_dim_args *args) - - Send a Discovery Information Management (DIM) command - -**Parameters** - -``struct nvme_dim_args *args`` - :c:type:`struct nvme_dim_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - diff --git a/doc/rst/linux.rst b/doc/rst/linux.rst deleted file mode 100644 index 83dbca92..00000000 --- a/doc/rst/linux.rst +++ /dev/null @@ -1,342 +0,0 @@ -.. _linux.h: - -**linux.h** - - -linux-specific utility functions - -.. c:function:: int nvme_fw_download_seq (int fd, __u32 size, __u32 xfer, __u32 offset, void *buf) - - Firmware download sequence - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 size`` - Total size of the firmware image to transfer - -``__u32 xfer`` - Maximum size to send with each partial transfer - -``__u32 offset`` - Starting offset to send with this firmware download - -``void *buf`` - Address of buffer containing all or part of the firmware image. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - - - -.. c:enum:: nvme_telemetry_da - - Telemetry Log Data Area - -**Constants** - -``NVME_TELEMETRY_DA_1`` - Data Area 1 - -``NVME_TELEMETRY_DA_2`` - Data Area 2 - -``NVME_TELEMETRY_DA_3`` - Data Area 3 - -``NVME_TELEMETRY_DA_4`` - Data Area 4 - - -.. 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 - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_telemetry_log **log`` - On success, set to the value of the allocated and retrieved log. - -``enum nvme_telemetry_da da`` - Log page data area, valid values: :c:type:`enum nvme_telemetry_da ` - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_host_telemetry (int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size) - - Get host telemetry log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_telemetry_log **log`` - On success, set to the value of the allocated and retrieved log. - -``enum nvme_telemetry_da da`` - Log page data area, valid values: :c:type:`enum nvme_telemetry_da ` - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_new_host_telemetry (int fd, struct nvme_telemetry_log **log, enum nvme_telemetry_da da, size_t *size) - - Get new host telemetry log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``struct nvme_telemetry_log **log`` - On success, set to the value of the allocated and retrieved log. - -``enum nvme_telemetry_da da`` - Log page data area, valid values: :c:type:`enum nvme_telemetry_da ` - -``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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_log_page (int fd, __u32 xfer_len, struct nvme_get_log_args *args) - - Get log page data - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 xfer_len`` - Max log transfer size per request to split the total. - -``struct nvme_get_log_args *args`` - :c:type:`struct nvme_get_log_args ` argument structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_ana_log_len (int fd, size_t *analen) - - Retrieve size of the current ANA log - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``size_t *analen`` - Pointer to where the length will be set on success - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_logical_block_size (int fd, __u32 nsid, int *blksize) - - Retrieve block size - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace id - -``int *blksize`` - Pointer to where the block size will be set on success - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_get_lba_status_log (int fd, bool rae, struct nvme_lba_status_log **log) - - Retrieve the LBA Status log page - -**Parameters** - -``int fd`` - File descriptor of the nvme device - -``bool rae`` - Retain asynchronous events - -``struct nvme_lba_status_log **log`` - On success, set to the value of the allocated and retrieved log. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_namespace_attach_ctrls (int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist) - - Attach namespace to controller(s) - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID to attach - -``__u16 num_ctrls`` - Number of controllers in ctrlist - -``__u16 *ctrlist`` - List of controller IDs to perform the attach action - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_namespace_detach_ctrls (int fd, __u32 nsid, __u16 num_ctrls, __u16 *ctrlist) - - Detach namespace from controller(s) - -**Parameters** - -``int fd`` - File descriptor of nvme device - -``__u32 nsid`` - Namespace ID to detach - -``__u16 num_ctrls`` - Number of controllers in ctrlist - -``__u16 *ctrlist`` - List of controller IDs to perform the detach action - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_open (const char *name) - - Open an nvme controller or namespace device - -**Parameters** - -``const char *name`` - The basename of the device to open - -**Description** - -This will look for the handle in /dev/ and validate the name and filetype -match linux conventions. - -**Return** - -A file descriptor for the device on a successful open, or -1 with -errno set otherwise. - - - - -.. c:enum:: nvme_hmac_alg - - HMAC algorithm - -**Constants** - -``NVME_HMAC_ALG_NONE`` - No HMAC algorithm - -``NVME_HMAC_ALG_SHA2_256`` - SHA2-256 - -``NVME_HMAC_ALG_SHA2_384`` - SHA2-384 - -``NVME_HMAC_ALG_SHA2_512`` - SHA2-512 - - -.. c:function:: int nvme_gen_dhchap_key (char *hostnqn, enum nvme_hmac_alg hmac, unsigned int key_len, unsigned char *secret, unsigned char *key) - - DH-HMAC-CHAP key generation - -**Parameters** - -``char *hostnqn`` - Host NVMe Qualified Name - -``enum nvme_hmac_alg hmac`` - HMAC algorithm - -``unsigned int key_len`` - Output key length - -``unsigned char *secret`` - Secret to used for digest - -``unsigned char *key`` - Generated DH-HMAC-CHAP key - -**Return** - -If key generation was successful the function returns 0 or --1 with errno set otherwise. - - diff --git a/doc/rst/log.rst b/doc/rst/log.rst deleted file mode 100644 index 45b46899..00000000 --- a/doc/rst/log.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _log.h: - -**log.h** - - -logging functions - -.. c:function:: void nvme_init_logging (nvme_root_t r, int lvl, bool log_pid, bool log_tstamp) - - Initialize logging - -**Parameters** - -``nvme_root_t r`` - nvme_root_t context - -``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 variables for the library. - - diff --git a/doc/rst/meson.build b/doc/rst/meson.build index 43874f04..ea791155 100644 --- a/doc/rst/meson.build +++ b/doc/rst/meson.build @@ -29,8 +29,6 @@ if want_docs != 'false' endforeach endif else - if want_docs == 'all' or want_docs == 'rst' - install_subdir('rst', install_dir: rstdir) - endif + # no prebuild docs endif endif diff --git a/doc/rst/mi.rst b/doc/rst/mi.rst deleted file mode 100644 index 3eaa20c9..00000000 --- a/doc/rst/mi.rst +++ /dev/null @@ -1,3059 +0,0 @@ -.. _mi.h - NVMe Management Interface library (libnvme-mi) definitions.: - -**mi.h - NVMe Management Interface library (libnvme-mi) definitions.** - - -These provide an abstraction for the MI messaging between controllers -and a host, typically over an MCTP-over-i2c link to a NVMe device, used -as part of the out-of-band management of a system. - -We have a few data structures define here to reflect the topology -of a MI connection with an NVMe subsystem: - - - :c:type:`nvme_mi_ep_t`: an MI endpoint - our mechanism of communication with a - NVMe subsystem. For MCTP, an endpoint will be the component that - holds the MCTP address (EID), and receives our request message. - - endpoints are defined in the NVMe-MI spec, and are specific to the MI - interface. - - Each endpoint will provide access to one or more of: - - - :c:type:`nvme_mi_ctrl_t`: a NVMe controller, as defined by the NVMe base spec. - The controllers are responsible for processing any NVMe standard - commands (eg, the Admin command set). An endpoint (:c:type:`nvme_mi_ep_t`) - may provide access to multiple controllers - so each of the controller- - type commands will require a :c:type:`nvme_mi_ctrl_t` to be specified, rather than - an endpoint - -A couple of conventions with the libnvme-mi API: - - - All types and functions have the nvme_mi prefix, to distinguish from - the libnvme core. - - - We currently support either MI commands and Admin commands. The - former adds a _mi prefix, the latter an _admin prefix. [This does - result in the MI functions having a double _mi, like - :c:type:`nvme_mi_mi_subsystem_health_status_poll`, which is apparently amusing - for our German-speaking readers] - -For return values: unless specified in the per-function documentation, -all functions: - - - return 0 on success - - - return -1, with errno set, for errors communicating with the MI device, - either in request or response data - - - return >1 on MI status errors. This value is the 8-bit MI status - value, represented by :c:type:`enum nvme_mi_resp_status `. Note that the - status values may be vendor-defined above 0xe0. - -For the second case, we have a few conventions for errno values: - - - EPROTO: response data violated the MI protocol, and libnvme cannot - validly interpret the response - - - EIO: Other I/O error communicating with device (eg., valid but - unexpected response data) - - - EINVAL: invalid input arguments for a command - -In line with the core NVMe API, the Admin command functions take an -`_args` structure to provide the command-specific parameters. However, -for the MI interface, the fd and timeout members of these _args structs -are ignored. - -References to the specifications here will either to be the NVM Express -Management Interface ("NVMe-MI") or the NVM Express Base specification -("NVMe"). At the time of writing, the versions we're referencing here -are: - - NVMe-MI 1.2b - - NVMe 2.0b -with a couple of accommodations for older spec types, particularly NVMe-MI -1.1, where possible. - -.. c:macro:: NVME_MI_MSGTYPE_NVME - -``NVME_MI_MSGTYPE_NVME ()`` - - MCTP message type for NVMe-MI messages. - -**Parameters** - -**Description** - - -This is defined by MCTP, but is referenced as part of the NVMe-MI message -spec. This is the MCTP NVMe message type (0x4), with the message-integrity -bit (0x80) set. - - - - -.. c:enum:: nvme_mi_message_type - - NVMe-MI message type field. - -**Constants** - -``NVME_MI_MT_CONTROL`` - NVME-MI Control Primitive - -``NVME_MI_MT_MI`` - NVMe-MI command - -``NVME_MI_MT_ADMIN`` - NVMe Admin command - -``NVME_MI_MT_PCIE`` - PCIe command - -**Description** - -Used as byte 1 of both request and response messages (NMIMT bits of NMP -byte). Not to be confused with the MCTP message type in byte 0. - - - - -.. c:enum:: nvme_mi_ror - - Request or response field. - -**Constants** - -``NVME_MI_ROR_REQ`` - request message - -``NVME_MI_ROR_RSP`` - response message - - - - -.. c:enum:: nvme_mi_resp_status - - values for the response status field - -**Constants** - -``NVME_MI_RESP_SUCCESS`` - success - -``NVME_MI_RESP_MPR`` - More Processing Required - -``NVME_MI_RESP_INTERNAL_ERR`` - Internal Error - -``NVME_MI_RESP_INVALID_OPCODE`` - Invalid command opcode - -``NVME_MI_RESP_INVALID_PARAM`` - Invalid command parameter - -``NVME_MI_RESP_INVALID_CMD_SIZE`` - Invalid command size - -``NVME_MI_RESP_INVALID_INPUT_SIZE`` - Invalid command input data size - -``NVME_MI_RESP_ACCESS_DENIED`` - Access Denied - -``NVME_MI_RESP_VPD_UPDATES_EXCEEDED`` - More VPD updates than allowed - -``NVME_MI_RESP_PCIE_INACCESSIBLE`` - PCIe functionality currently unavailable - -``NVME_MI_RESP_MEB_SANITIZED`` - MEB has been cleared due to sanitize - -``NVME_MI_RESP_ENC_SERV_FAILURE`` - Enclosure services process failed - -``NVME_MI_RESP_ENC_SERV_XFER_FAILURE`` - Transfer with enclosure services failed - -``NVME_MI_RESP_ENC_FAILURE`` - Unreoverable enclosure failure - -``NVME_MI_RESP_ENC_XFER_REFUSED`` - Enclosure services transfer refused - -``NVME_MI_RESP_ENC_FUNC_UNSUP`` - Unsupported enclosure services function - -``NVME_MI_RESP_ENC_SERV_UNAVAIL`` - Enclosure services unavailable - -``NVME_MI_RESP_ENC_DEGRADED`` - Noncritical failure detected by enc. services - -``NVME_MI_RESP_SANITIZE_IN_PROGRESS`` - Command prohibited during sanitize - - - - -.. c:struct:: nvme_mi_msg_hdr - - General MI message header. - -**Definition** - -:: - - struct nvme_mi_msg_hdr { - __u8 type; - __u8 nmp; - __u8 meb; - __u8 rsvd0; - }; - -**Members** - -``type`` - MCTP message type, will always be NVME_MI_MSGTYPE_NVME - -``nmp`` - NVMe-MI message parameters (including MI message type) - -``meb`` - Management Endpoint Buffer flag; unused for libnvme-mi implementation - -``rsvd0`` - currently reserved - - -**Description** - -Wire format shared by both request and response messages, per NVMe-MI -section 3.1. This is used for all message types, MI and Admin. - - - - -.. c:struct:: nvme_mi_msg_resp - - Generic response type. - -**Definition** - -:: - - struct nvme_mi_msg_resp { - struct nvme_mi_msg_hdr hdr; - __u8 status; - __u8 rsvd0[3]; - }; - -**Members** - -``hdr`` - the general request/response message header - -``status`` - response status value (see :c:type:`enum nvme_mi_resp_status `) - -``rsvd0`` - reserved data, may be defined by specific response - - -**Description** - -Every response will start with one of these; command-specific responses -will define parts of the reserved data, and may add further fields. - - - - -.. c:enum:: nvme_mi_mi_opcode - - Operation code for supported NVMe-MI commands. - -**Constants** - -``nvme_mi_mi_opcode_mi_data_read`` - Read NVMe-MI Data Structure - -``nvme_mi_mi_opcode_subsys_health_status_poll`` - Subsystem Health Status Poll - -``nvme_mi_mi_opcode_configuration_set`` - MI Configuration Set - -``nvme_mi_mi_opcode_configuration_get`` - MI Configuration Get - - - - -.. c:struct:: nvme_mi_mi_req_hdr - - MI request message header. - -**Definition** - -:: - - struct nvme_mi_mi_req_hdr { - struct nvme_mi_msg_hdr hdr; - __u8 opcode; - __u8 rsvd0[3]; - __le32 cdw0, cdw1; - }; - -**Members** - -``hdr`` - generic MI message header - -``opcode`` - opcode (OPC) for the specific MI command - -``rsvd0`` - reserved bytes - -``cdw0`` - Management Request Doubleword 0 - command specific usage - -``cdw1`` - Management Request Doubleword 1 - command specific usage - - -**Description** - -Wire format for MI request message headers, defined in section 5 of NVMe-MI. - - - - -.. c:struct:: nvme_mi_mi_resp_hdr - - MI response message header. - -**Definition** - -:: - - struct nvme_mi_mi_resp_hdr { - struct nvme_mi_msg_hdr hdr; - __u8 status; - __u8 nmresp[3]; - }; - -**Members** - -``hdr`` - generic MI message header - -``status`` - generic response status from command; non-zero on failure. - -``nmresp`` - NVMe Management Response: command-type-specific response data - - -**Description** - -Wire format for MI response message header, defined in section 5 of NVMe-MI. - - - - -.. c:enum:: nvme_mi_dtyp - - Data Structure Type field. - -**Constants** - -``nvme_mi_dtyp_subsys_info`` - NVM Subsystem Information - -``nvme_mi_dtyp_port_info`` - Port information - -``nvme_mi_dtyp_ctrl_list`` - Controller List - -``nvme_mi_dtyp_ctrl_info`` - Controller Information - -``nvme_mi_dtyp_opt_cmd_support`` - Optionally Supported Command List - -``nvme_mi_dtyp_meb_support`` - Management Endpoint Buffer Command Support List - -**Description** - -Data Structure Type field for Read NVMe-MI Data Structure command, used to -indicate the particular structure to query from the endpoint. - - - - -.. c:enum:: nvme_mi_config_id - - NVMe-MI Configuration identifier. - -**Constants** - -``NVME_MI_CONFIG_SMBUS_FREQ`` - Current SMBus/I2C frequency - -``NVME_MI_CONFIG_HEALTH_STATUS_CHANGE`` - Health Status change - used to clear - health status bits in CCS bits of - status poll. Only for Set ops. - -``NVME_MI_CONFIG_MCTP_MTU`` - MCTP maximum transmission unit size of port - specified in dw 0 - -**Description** - -Configuration parameters for the MI Get/Set Configuration commands. - -See :c:type:`nvme_mi_mi_config_get`() and :c:type:`nvme_mi_config_set`(). - - - - -.. c:enum:: nvme_mi_config_smbus_freq - - SMBus/I2C frequency values - -**Constants** - -``NVME_MI_CONFIG_SMBUS_FREQ_100kHz`` - 100kHz - -``NVME_MI_CONFIG_SMBUS_FREQ_400kHz`` - 400kHz - -``NVME_MI_CONFIG_SMBUS_FREQ_1MHz`` - 1MHz - -**Description** - -Values used in the SMBus Frequency device configuration. See -:c:type:`nvme_mi_mi_config_get_smbus_freq`() and :c:type:`nvme_mi_mi_config_set_smbus_freq`(). - - - - -.. c:struct:: nvme_mi_admin_req_hdr - - Admin command request header. - -**Definition** - -:: - - struct nvme_mi_admin_req_hdr { - struct nvme_mi_msg_hdr hdr; - __u8 opcode; - __u8 flags; - __le16 ctrl_id; - __le32 cdw1, cdw2, cdw3, cdw4, cdw5; - __le32 doff; - __le32 dlen; - __le32 rsvd0, rsvd1; - __le32 cdw10, cdw11, cdw12, cdw13, cdw14, cdw15; - }; - -**Members** - -``hdr`` - Generic MI message header - -``opcode`` - Admin command opcode (using enum nvme_admin_opcode) - -``flags`` - Command Flags, indicating dlen and doff validity; Only defined in - NVMe-MI version 1.1, no fields defined in 1.2 (where the dlen/doff - are always considered valid). - -``ctrl_id`` - Controller ID target of command - -``cdw1`` - Submission Queue Entry doubleword 1 - -``cdw2`` - Submission Queue Entry doubleword 2 - -``cdw3`` - Submission Queue Entry doubleword 3 - -``cdw4`` - Submission Queue Entry doubleword 4 - -``cdw5`` - Submission Queue Entry doubleword 5 - -``doff`` - Offset of data to return from command - -``dlen`` - Length of sent/returned data - -``rsvd0`` - Reserved - -``rsvd1`` - Reserved - -``cdw10`` - Submission Queue Entry doubleword 10 - -``cdw11`` - Submission Queue Entry doubleword 11 - -``cdw12`` - Submission Queue Entry doubleword 12 - -``cdw13`` - Submission Queue Entry doubleword 13 - -``cdw14`` - Submission Queue Entry doubleword 14 - -``cdw15`` - Submission Queue Entry doubleword 15 - - -**Description** - -Wire format for Admin command message headers, defined in section 6 of -NVMe-MI. - - - - -.. c:struct:: nvme_mi_admin_resp_hdr - - Admin command response header. - -**Definition** - -:: - - struct nvme_mi_admin_resp_hdr { - struct nvme_mi_msg_hdr hdr; - __u8 status; - __u8 rsvd0[3]; - __le32 cdw0, cdw1, cdw3; - }; - -**Members** - -``hdr`` - Generic MI message header - -``status`` - Generic response code, non-zero on failure - -``rsvd0`` - Reserved - -``cdw0`` - Completion Queue Entry doubleword 0 - -``cdw1`` - Completion Queue Entry doubleword 1 - -``cdw3`` - Completion Queue Entry doubleword 3 - - -**Description** - -This is the generic response format with the three doublewords of completion -queue data, plus optional response data. - - -.. c:function:: const char * nvme_mi_status_to_string (int status) - - return a string representation of the MI status. - -**Parameters** - -``int status`` - MI response status - -**Description** - -Gives a string description of **status**, as per section 4.1.2 of the NVMe-MI -spec. The status value should be of type NVME_STATUS_MI, and extracted -from the return value using nvme_status_get_value(). - -Returned string is const, and should not be free()ed. - -**Return** - -A string representing the status value - - -.. c:function:: nvme_root_t nvme_mi_create_root (FILE *fp, int log_level) - - Create top-level MI (root) handle. - -**Parameters** - -``FILE *fp`` - File descriptor for logging messages - -``int log_level`` - Logging level to use - -**Description** - -Create the top-level (library) handle for creating subsequent endpoint -objects. Similar to nvme_create_root(), but we provide this to allow linking -without the core libnvme. - -See :c:type:`nvme_create_root`. - -**Return** - -new root object, or NULL on failure. - - -.. c:function:: void nvme_mi_free_root (nvme_root_t root) - - Free root object. - -**Parameters** - -``nvme_root_t root`` - root to free - - - - -.. c:type:: nvme_mi_ep_t - - MI Endpoint object. - -**Description** - - -Represents our communication endpoint on the remote MI-capable device. -To be used for direct MI commands for the endpoint (through the -nvme_mi_mi_* functions(), or to communicate with individual controllers -(see :c:type:`nvme_mi_init_ctrl`). - -Endpoints are created through a transport-specific constructor; currently -only MCTP-connected endpoints are supported, through :c:type:`nvme_mi_open_mctp`. -Subsequent operations on the endpoint (and related controllers) are -transport-independent. - - -.. c:function:: nvme_mi_ep_t nvme_mi_first_endpoint (nvme_root_t m) - - Start endpoint iterator - -**Parameters** - -``nvme_root_t m`` - :c:type:`nvme_root_t` object - -**Return** - -first MI endpoint object under this root, or NULL if no endpoints - are present. - -**Description** - -See: :c:type:`nvme_mi_next_endpoint`, :c:type:`nvme_mi_for_each_endpoint` - - -.. c:function:: nvme_mi_ep_t nvme_mi_next_endpoint (nvme_root_t m, nvme_mi_ep_t e) - - Continue endpoint iterator - -**Parameters** - -``nvme_root_t m`` - :c:type:`nvme_root_t` object - -``nvme_mi_ep_t e`` - :c:type:`nvme_mi_ep_t` current position of iterator - -**Return** - -next endpoint MI endpoint object after **e** under this root, or NULL - if no further endpoints are present. - -**Description** - -See: :c:type:`nvme_mi_first_endpoint`, :c:type:`nvme_mi_for_each_endpoint` - - -.. c:macro:: nvme_mi_for_each_endpoint - -``nvme_mi_for_each_endpoint (m, e)`` - - Iterator for NVMe-MI endpoints. - -**Parameters** - -``m`` - :c:type:`nvme_root_t` containing endpoints - -``e`` - :c:type:`nvme_mi_ep_t` object, set on each iteration - - -.. c:macro:: nvme_mi_for_each_endpoint_safe - -``nvme_mi_for_each_endpoint_safe (m, e, _e)`` - - Iterator for NVMe-MI endpoints, allowing deletion during traversal - -**Parameters** - -``m`` - :c:type:`nvme_root_t` containing endpoints - -``e`` - :c:type:`nvme_mi_ep_t` object, set on each iteration - -``_e`` - :c:type:`nvme_mi_ep_t` object used as temporary storage - - -.. c:function:: int nvme_mi_ep_set_timeout (nvme_mi_ep_t ep, unsigned int timeout_ms) - - set a timeout for NVMe-MI responses - -**Parameters** - -``nvme_mi_ep_t ep`` - MI endpoint object - -``unsigned int timeout_ms`` - Timeout for MI responses, given in milliseconds - - -.. c:function:: void nvme_mi_ep_set_mprt_max (nvme_mi_ep_t ep, unsigned int mprt_max_ms) - - set the maximum wait time for a More Processing Required response - -**Parameters** - -``nvme_mi_ep_t ep`` - MI endpoint object - -``unsigned int mprt_max_ms`` - Maximum more processing required wait time - -**Description** - -NVMe-MI endpoints may respond to a request with a "More Processing Required" -response; this also includes a hint on the worst-case processing time for -the eventual response data, with a specification-defined maximum of 65.535 -seconds. - -This function provides a way to limit the maximum time we're prepared to -wait for the final response. Specify zero in **mprt_max_ms** for no limit. -This should be larger than the command/response timeout set in -:c:type:`nvme_mi_ep_set_timeout`(). - - -.. c:function:: unsigned int nvme_mi_ep_get_timeout (nvme_mi_ep_t ep) - - get the current timeout value for NVMe-MI responses - -**Parameters** - -``nvme_mi_ep_t ep`` - MI endpoint object - -**Description** - -Returns the current timeout value, in milliseconds, for this endpoint. - - - - -.. c:type:: nvme_mi_ctrl_t - - NVMe-MI Controller object. - -**Description** - - -Provides NVMe command functionality, through the MI interface. - - -.. c:function:: nvme_mi_ctrl_t nvme_mi_first_ctrl (nvme_mi_ep_t ep) - - Start controller iterator - -**Parameters** - -``nvme_mi_ep_t ep`` - :c:type:`nvme_mi_ep_t` object - -**Return** - -first MI controller object under this root, or NULL if no controllers - are present. - -**Description** - -See: :c:type:`nvme_mi_next_ctrl`, :c:type:`nvme_mi_for_each_ctrl` - - -.. c:function:: nvme_mi_ctrl_t nvme_mi_next_ctrl (nvme_mi_ep_t ep, nvme_mi_ctrl_t c) - - Continue ctrl iterator - -**Parameters** - -``nvme_mi_ep_t ep`` - :c:type:`nvme_mi_ep_t` object - -``nvme_mi_ctrl_t c`` - :c:type:`nvme_mi_ctrl_t` current position of iterator - -**Return** - -next MI controller object after **c** under this endpoint, or NULL - if no further controllers are present. - -**Description** - -See: :c:type:`nvme_mi_first_ctrl`, :c:type:`nvme_mi_for_each_ctrl` - - -.. c:macro:: nvme_mi_for_each_ctrl - -``nvme_mi_for_each_ctrl (ep, c)`` - - Iterator for NVMe-MI controllers. - -**Parameters** - -``ep`` - :c:type:`nvme_mi_ep_t` containing endpoints - -``c`` - :c:type:`nvme_mi_ctrl_t` object, set on each iteration - -**Description** - -Allows iteration of the list of controllers behind an endpoint. Unless the -controllers have already been created explicitly, you'll probably want to -call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first. - -See: :c:type:`nvme_mi_scan_ep`() - - -.. c:macro:: nvme_mi_for_each_ctrl_safe - -``nvme_mi_for_each_ctrl_safe (ep, c, _c)`` - - Iterator for NVMe-MI controllers, allowing deletion during traversal - -**Parameters** - -``ep`` - :c:type:`nvme_mi_ep_t` containing controllers - -``c`` - :c:type:`nvme_mi_ctrl_t` object, set on each iteration - -``_c`` - :c:type:`nvme_mi_ctrl_t` object used as temporary storage - -**Description** - -Allows iteration of the list of controllers behind an endpoint, safe against -deletion during iteration. Unless the controllers have already been created -explicitly (or you're just iterating to destroy controllers) you'll probably -want to call :c:type:`nvme_mi_scan_ep`() to scan for the controllers first. - -See: :c:type:`nvme_mi_scan_ep`() - - -.. c:function:: nvme_mi_ep_t nvme_mi_open_mctp (nvme_root_t root, unsigned int netid, uint8_t eid) - - Create an endpoint using a MCTP connection. - -**Parameters** - -``nvme_root_t root`` - root object to create under - -``unsigned int netid`` - MCTP network ID on this system - -``uint8_t eid`` - MCTP endpoint ID - -**Description** - -Transport-specific endpoint initialization for MI-connected endpoints. Once -an endpoint is created, the rest of the API is transport-independent. - -See :c:type:`nvme_mi_close` - -**Return** - -New endpoint object for **netid** & **eid**, or NULL on failure. - - -.. c:function:: void nvme_mi_close (nvme_mi_ep_t ep) - - Close an endpoint connection and release resources, including controller objects. - -**Parameters** - -``nvme_mi_ep_t ep`` - Endpoint object to close - - -.. c:function:: nvme_root_t nvme_mi_scan_mctp (void) - - look for MCTP-connected NVMe-MI endpoints. - -**Parameters** - -``void`` - no arguments - -**Description** - -This function queries the system MCTP daemon ("mctpd") over -D-Bus, to find MCTP endpoints that report support for NVMe-MI over MCTP. - -This requires libvnme-mi to be compiled with D-Bus support; if not, this -will return NULL. - -**Return** - -A **nvme_root_t** populated with a set of MCTP-connected endpoints, - or NULL on failure - - -.. c:function:: int nvme_mi_scan_ep (nvme_mi_ep_t ep, bool force_rescan) - - query an endpoint for its NVMe controllers. - -**Parameters** - -``nvme_mi_ep_t ep`` - Endpoint to scan - -``bool force_rescan`` - close existing controllers and rescan - -**Description** - -This function queries an MI endpoint for the controllers available, by -performing an MI Read MI Data Structure command (requesting the -controller list). The controllers are stored in the endpoint's internal -list, and can be iterated with nvme_mi_for_each_ctrl. - -This will only scan the endpoint once, unless **force_rescan** is set. If -so, all existing controller objects will be freed - the caller must not -hold a reference to those across this call. - -See: :c:type:`nvme_mi_for_each_ctrl` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: nvme_mi_ctrl_t nvme_mi_init_ctrl (nvme_mi_ep_t ep, __u16 ctrl_id) - - initialise a NVMe controller. - -**Parameters** - -``nvme_mi_ep_t ep`` - Endpoint to create under - -``__u16 ctrl_id`` - ID of controller to initialize. - -**Description** - -Create a connection to a controller behind the endpoint specified in **ep**. -Controller IDs may be queried from the endpoint through -:c:type:`nvme_mi_mi_read_mi_data_ctrl_list`. - -See :c:type:`nvme_mi_close_ctrl` - -**Return** - -New controller object, or NULL on failure. - - -.. c:function:: void nvme_mi_close_ctrl (nvme_mi_ctrl_t ctrl) - - free a controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - controller to free - - -.. c:function:: char * nvme_mi_endpoint_desc (nvme_mi_ep_t ep) - - Get a string describing a MI endpoint. - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint to describe - -**Description** - -Generates a human-readable string describing the endpoint, with possibly -transport-specific data. The string is allocated during the call, and the -caller is responsible for free()-ing the string. - -**Return** - -a newly-allocated string containing the endpoint description, or - NULL on failure. - - -.. c:function:: int nvme_mi_mi_read_mi_data_subsys (nvme_mi_ep_t ep, struct nvme_mi_read_nvm_ss_info *s) - - Perform a Read MI Data Structure command, retrieving subsystem data. - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``struct nvme_mi_read_nvm_ss_info *s`` - subsystem information to populate - -**Description** - -Retrieves the Subsystem information - number of external ports and -NVMe version information. See :c:type:`struct nvme_mi_read_nvm_ss_info `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_read_mi_data_port (nvme_mi_ep_t ep, __u8 portid, struct nvme_mi_read_port_info *p) - - Perform a Read MI Data Structure command, retrieving port data. - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 portid`` - id of port data to retrieve - -``struct nvme_mi_read_port_info *p`` - port information to populate - -**Description** - -Retrieves the Port information, for the specified port ID. The subsystem -data (from :c:type:`nvme_mi_mi_read_mi_data_subsys`) nmp field contains the allowed -range of port IDs. - -See :c:type:`struct nvme_mi_read_port_info `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_read_mi_data_ctrl_list (nvme_mi_ep_t ep, __u8 start_ctrlid, struct nvme_ctrl_list *list) - - Perform a Read MI Data Structure command, retrieving the list of attached controllers. - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 start_ctrlid`` - starting controller ID - -``struct nvme_ctrl_list *list`` - controller list to populate - -**Description** - -Retrieves the list of attached controllers, with IDs greater than or -equal to **start_ctrlid**. - -See :c:type:`struct nvme_ctrl_list `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_read_mi_data_ctrl (nvme_mi_ep_t ep, __u16 ctrl_id, struct nvme_mi_read_ctrl_info *ctrl) - - Perform a Read MI Data Structure command, retrieving controller information - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u16 ctrl_id`` - ID of controller to query - -``struct nvme_mi_read_ctrl_info *ctrl`` - controller data to populate - -**Description** - -Retrieves the Controller Information Data Structure for the attached -controller with ID **ctrlid**. - -See :c:type:`struct nvme_mi_read_ctrl_info `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_subsystem_health_status_poll (nvme_mi_ep_t ep, bool clear, struct nvme_mi_nvm_ss_health_status *nshds) - - Read the Subsystem Health Data Structure from the NVM subsystem - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``bool clear`` - flag to clear the Composite Controller Status state - -``struct nvme_mi_nvm_ss_health_status *nshds`` - subsystem health status data to populate - -**Description** - -Retrieves the Subsystem Health Data Structure into **nshds**. If **clear** is -set, requests that the Composite Controller Status bits are cleared after -the read. See NVMe-MI section 5.6 for details on the CCS bits. - -See :c:type:`struct nvme_mi_nvm_ss_health_status `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_get (nvme_mi_ep_t ep, __u32 dw0, __u32 dw1, __u32 *nmresp) - - query a configuration parameter - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u32 dw0`` - management doubleword 0, containing configuration identifier, plus - config-specific fields - -``__u32 dw1`` - management doubleword 0, config-specific. - -``__u32 *nmresp`` - set to queried configuration data in NMRESP field of response. - -**Description** - -Performs a MI Configuration Get command, with the configuration identifier -as the LSB of **dw0**. Other **dw0** and **dw1** data is configuration-identifier -specific. - -On a successful Configuration Get, the **nmresp** pointer will be populated with -the bytes from the 3-byte NMRESP field, converted to native endian. - -See :c:type:`enum nvme_mi_config_id ` for identifiers. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_set (nvme_mi_ep_t ep, __u32 dw0, __u32 dw1) - - set a configuration parameter - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u32 dw0`` - management doubleword 0, containing configuration identifier, plus - config-specific fields - -``__u32 dw1`` - management doubleword 0, config-specific. - -**Description** - -Performs a MI Configuration Set command, with the command as the LSB of -**dw0**. Other **dw0** and **dw1** data is configuration-identifier specific. - -See :c:type:`enum nvme_mi_config_id ` for identifiers. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_get_smbus_freq (nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq *freq) - - get configuration: SMBus port frequency - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 port`` - port ID to query - -``enum nvme_mi_config_smbus_freq *freq`` - output value for current frequency configuration - -**Description** - -Performs a MI Configuration Get, to query the current SMBus frequency of -the port specified in **port**. On success, populates **freq** with the port -frequency - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_set_smbus_freq (nvme_mi_ep_t ep, __u8 port, enum nvme_mi_config_smbus_freq freq) - - set configuration: SMBus port frequency - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 port`` - port ID to set - -``enum nvme_mi_config_smbus_freq freq`` - new frequency configuration - -**Description** - -Performs a MI Configuration Set, to update the current SMBus frequency of -the port specified in **port**. - -See :c:type:`struct nvme_mi_read_port_info ` for the maximum supported SMBus frequency -for the port. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_set_health_status_change (nvme_mi_ep_t ep, __u32 mask) - - clear CCS bits in health status - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u32 mask`` - bitmask to clear - -**Description** - -Performs a MI Configuration Set, to update the current health status poll -values of the Composite Controller Status bits. Bits set in **mask** will -be cleared from future health status poll data, and may be re-triggered by -a future health change event. - -See :c:type:`nvme_mi_mi_subsystem_health_status_poll`(), :c:type:`enum nvme_mi_ccs ` for -values in **mask**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_get_mctp_mtu (nvme_mi_ep_t ep, __u8 port, __u16 *mtu) - - get configuration: MCTP MTU - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 port`` - port ID to query - -``__u16 *mtu`` - output value for current MCTP MTU configuration - -**Description** - -Performs a MI Configuration Get, to query the current MCTP Maximum -Transmission Unit size (MTU) of the port specified in **port**. On success, -populates **mtu** with the MTU. - -The default reset value is 64, corresponding to the MCTP baseline MTU. - -Some controllers may also use this as the maximum receive unit size, and -may not accept MCTP messages larger than the configured MTU. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_mi_config_set_mctp_mtu (nvme_mi_ep_t ep, __u8 port, __u16 mtu) - - set configuration: MCTP MTU - -**Parameters** - -``nvme_mi_ep_t ep`` - endpoint for MI communication - -``__u8 port`` - port ID to set - -``__u16 mtu`` - new MTU configuration - -**Description** - -Performs a MI Configuration Set, to update the current MCTP MTU value for -the port specified in **port**. - -Some controllers may also use this as the maximum receive unit size, and -may not accept MCTP messages larger than the configured MTU. When setting -this value, you will likely need to change the MTU of the local MCTP -interface(s) to match. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_admin_xfer (nvme_mi_ctrl_t ctrl, struct nvme_mi_admin_req_hdr *admin_req, size_t req_data_size, struct nvme_mi_admin_resp_hdr *admin_resp, off_t resp_data_offset, size_t *resp_data_size) - - Raw admin transfer interface. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - controller to send the admin command to - -``struct nvme_mi_admin_req_hdr *admin_req`` - request data - -``size_t req_data_size`` - size of request data payload - -``struct nvme_mi_admin_resp_hdr *admin_resp`` - buffer for response data - -``off_t resp_data_offset`` - offset into request data to retrieve from controller - -``size_t *resp_data_size`` - size of response data buffer, updated to received size - -**Description** - -Performs an arbitrary NVMe Admin command, using the provided request data, -in **admin_req**. The size of the request data *payload* is specified in -**req_data_size** - this does not include the standard header length (so a -header-only request would have a size of 0). - -On success, response data is stored in **admin_resp**, which has an optional -appended payload buffer of **resp_data_size** bytes. The actual payload -transferred will be stored in **resp_data_size**. These sizes do not include -the Admin request header, so 0 represents no payload. - -As with all Admin commands, we can request partial data from the Admin -Response payload, offset by **resp_data_offset**. - -See: :c:type:`struct nvme_mi_admin_req_hdr ` and :c:type:`struct nvme_mi_admin_resp_hdr `. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise.. - - -.. c:function:: int nvme_mi_admin_identify_partial (nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args, off_t offset, size_t size) - - Perform an Admin identify command, and retrieve partial response data. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``struct nvme_identify_args *args`` - Identify command arguments - -``off_t offset`` - offset of identify data to retrieve from response - -``size_t size`` - size of identify data to return - -**Description** - -Perform an Identify command, using the Identify command parameters in **args**. -The **offset** and **size** arguments allow the caller to retrieve part of -the identify response. See NVMe-MI section 6.2 for the semantics (and some -handy diagrams) of the offset & size parameters. - -Will return an error if the length of the response data (from the controller) -did not match **size**. - -Unless you're performing a vendor-unique identify command, You'll probably -want to use one of the identify helpers (nvme_mi_admin_identify, -nvme_mi_admin_identify_cns_nsid, or nvme_mi_admin_identify_) instead -of this. If the type of your identify command is standardized but not -yet supported by libnvme-mi, please contact the maintainers. - -See: :c:type:`struct nvme_identify_args ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify (nvme_mi_ctrl_t ctrl, struct nvme_identify_args *args) - - Perform an Admin identify command. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``struct nvme_identify_args *args`` - Identify command arguments - -**Description** - -Perform an Identify command, using the Identify command parameters in **args**. -Stores the identify data in ->data, and (if set) the result from cdw0 -into args->result. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`. - -See: :c:type:`struct nvme_identify_args ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_cns_nsid (nvme_mi_ctrl_t ctrl, enum nvme_identify_cns cns, __u32 nsid, void *data) - - Perform an Admin identify command using specific CNS/NSID parameters. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``enum nvme_identify_cns cns`` - Controller or Namespace Structure, specifying identified object - -``__u32 nsid`` - namespace ID - -``void *data`` - buffer for identify data response - -**Description** - -Perform an Identify command, using the CNS specifier **cns**, and the -namespace ID **nsid** if required by the CNS type. - -Stores the identify data in **data**, which is expected to be a buffer of -:c:type:`NVME_IDENTIFY_DATA_SIZE` bytes. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_ns (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_id_ns *ns) - - Perform an Admin identify command for a namespace - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - namespace ID - -``struct nvme_id_ns *ns`` - Namespace identification to populate - -**Description** - -Perform an Identify (namespace) command, setting the namespace id data -in **ns**. The namespace is expected to active and allocated. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_ns_descs (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_id_desc *descs) - - Perform an Admin identify Namespace Identification Descriptor list command for a namespace - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - Namespace ID - -``struct nvme_ns_id_desc *descs`` - Namespace Identification Descriptor list to populate - -**Description** - -Perform an Identify namespace identification description list command, -setting the namespace identification description list in **descs** - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_allocated_ns (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_id_ns *ns) - - Perform an Admin identify command for an allocated namespace - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - namespace ID - -``struct nvme_id_ns *ns`` - Namespace identification to populate - -**Description** - -Perform an Identify (namespace) command, setting the namespace id data -in **ns**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_ctrl (nvme_mi_ctrl_t ctrl, struct nvme_id_ctrl *id) - - Perform an Admin identify for a controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``struct nvme_id_ctrl *id`` - Controller identify data to populate - -**Description** - -Perform an Identify command, for the controller specified by **ctrl**, -writing identify data to **id**. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **id** will be -fully populated on success. - -See: :c:type:`struct nvme_id_ctrl ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_ctrl_list (nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_ctrl_list *list) - - Perform an Admin identify for a controller list. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u16 cntid`` - Controller ID to specify list start - -``struct nvme_ctrl_list *list`` - List data to populate - -**Description** - -Perform an Identify command, for the controller list starting with -IDs greater than or equal to **cntid**. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **id** will be -fully populated on success. - -See: :c:type:`struct nvme_ctrl_list ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_nsid_ctrl_list (nvme_mi_ctrl_t ctrl, __u32 nsid, __u16 cntid, struct nvme_ctrl_list *list) - - Perform an Admin identify for a controller list with specific namespace ID - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - Namespace identifier - -``__u16 cntid`` - Controller ID to specify list start - -``struct nvme_ctrl_list *list`` - List data to populate - -**Description** - -Perform an Identify command, for the controller list for **nsid**, starting -with IDs greater than or equal to **cntid**. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **id** will be -fully populated on success. - -See: :c:type:`struct nvme_ctrl_list ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_allocated_ns_list (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_list *list) - - Perform an Admin identify for an allocated namespace list - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - Namespace ID to specify list start - -``struct nvme_ns_list *list`` - List data to populate - -**Description** - -Perform an Identify command, for the allocated namespace list starting with -IDs greater than or equal to **nsid**. Specify :c:type:`NVME_NSID_NONE` for the start -of the list. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **list** will be -be fully populated on success. - -See: :c:type:`struct nvme_ns_list ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_active_ns_list (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ns_list *list) - - Perform an Admin identify for an active namespace list - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u32 nsid`` - Namespace ID to specify list start - -``struct nvme_ns_list *list`` - List data to populate - -**Description** - -Perform an Identify command, for the active namespace list starting with -IDs greater than or equal to **nsid**. Specify :c:type:`NVME_NSID_NONE` for the start -of the list. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **list** will be -be fully populated on success. - -See: :c:type:`struct nvme_ns_list ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_identify_primary_ctrl (nvme_mi_ctrl_t ctrl, __u16 cntid, struct nvme_primary_ctrl_cap *cap) - - Perform an Admin identify for primary controller capabilities data structure. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to process identify command - -``__u16 cntid`` - Controller ID to specify - -``struct nvme_primary_ctrl_cap *cap`` - Primary Controller Capabilities data structure to populate - -**Description** - -Perform an Identify command to get the Primary Controller Capabilities data -for the controller specified by **cntid** - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **cap** will be -be fully populated on success. - -See: :c:type:`struct nvme_primary_ctrl_cap ` - -**Return** - -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) - - Perform an Admin identify for a secondary controller list. - -**Parameters** - -``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 - -``struct nvme_secondary_ctrl_list *list`` - List data to populate - -**Description** - -Perform an Identify command, for the secondary controllers associated with -the current primary controller. Only entries with IDs greater than or -equal to **cntid** are returned. - -Will return an error if the length of the response data (from the -controller) is not a full :c:type:`NVME_IDENTIFY_DATA_SIZE`, so **list** will be -be fully populated on success. - -See: :c:type:`struct nvme_secondary_ctrl_list ` - -**Return** - -0 on success, non-zero on failure - - -.. c:function:: int nvme_mi_admin_get_log (nvme_mi_ctrl_t ctrl, struct nvme_get_log_args *args) - - Retrieve log page data from controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``struct nvme_get_log_args *args`` - Get Log Page command arguments - -**Description** - -Performs a Get Log Page Admin command as specified by **args**. Response data -is stored in **args->data**, which should be a buffer of **args->data_len** bytes. -Resulting data length is stored in **args->data_len** on successful -command completion. - -This request may be implemented as multiple log page commands, in order -to fit within MI message-size limits. - -See: :c:type:`struct nvme_get_log_args ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_nsid_log (nvme_mi_ctrl_t ctrl, bool rae, enum nvme_cmd_get_log_lid lid, __u32 nsid, __u32 len, void *log) - - Helper for Get Log Page functions - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain Asynchronous Events - -``enum nvme_cmd_get_log_lid lid`` - Log identifier - -``__u32 nsid`` - Namespace ID - -``__u32 len`` - length of log buffer - -``void *log`` - pointer for resulting log data - -**Description** - -Performs a Get Log Page Admin command for a specific log ID **lid** and -namespace ID **nsid**. Log data is expected to be **len** bytes, and is stored -in **log** on success. The **rae** flag is passed as-is to the Get Log Page -command, and is specific to the Log Page requested. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_simple (nvme_mi_ctrl_t ctrl, enum nvme_cmd_get_log_lid lid, __u32 len, void *log) - - Helper for Get Log Page functions with no NSID or RAE requirements - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``enum nvme_cmd_get_log_lid lid`` - Log identifier - -``__u32 len`` - length of log buffer - -``void *log`` - pointer for resulting log data - -**Description** - -Performs a Get Log Page Admin command for a specific log ID **lid**, using -NVME_NSID_ALL for the namespace identifier, and rae set to false. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_supported_log_pages (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_supported_log_pages *log) - - Retrieve nmve supported log pages - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_supported_log_pages *log`` - Array of LID supported and Effects data structures - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_error (nvme_mi_ctrl_t ctrl, unsigned int nr_entries, bool rae, struct nvme_error_log_page *err_log) - - Retrieve nvme error log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``unsigned int nr_entries`` - Number of error log entries allocated - -``bool rae`` - Retain asynchronous events - -``struct nvme_error_log_page *err_log`` - Array of error logs of size 'entries' - -**Description** - -This log page describes extended error information for a command that -completed with error, or may report an error that is not specific to a -particular command. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_smart (nvme_mi_ctrl_t ctrl, __u32 nsid, bool rae, struct nvme_smart_log *smart_log) - - Retrieve nvme smart log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u32 nsid`` - Optional namespace identifier - -``bool rae`` - Retain asynchronous events - -``struct nvme_smart_log *smart_log`` - User address to store the smart log - -**Description** - -This log page provides SMART and general health information. The information -provided is over the life of the controller and is retained across power -cycles. To request the controller log page, the namespace identifier -specified is FFFFFFFFh. The controller may also support requesting the log -page on a per namespace basis, as indicated by bit 0 of the LPA field in the -Identify Controller data structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_fw_slot (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_firmware_slot *fw_log) - - Retrieves the controller firmware log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_firmware_slot *fw_log`` - User address to store the log page - -**Description** - -This log page describes the firmware revision stored in each firmware slot -supported. The firmware revision is indicated as an ASCII string. The log -page also indicates the active slot number. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_changed_ns_list (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_ns_list *ns_log) - - Retrieve namespace changed list - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_ns_list *ns_log`` - User address to store the log page - -**Description** - -This log page describes namespaces attached to this controller that have -changed since the last time the namespace was identified, been added, or -deleted. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_cmd_effects (nvme_mi_ctrl_t ctrl, enum nvme_csi csi, struct nvme_cmd_effects_log *effects_log) - - Retrieve nvme command effects log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``enum nvme_csi csi`` - Command Set Identifier - -``struct nvme_cmd_effects_log *effects_log`` - User address to store the effects log - -**Description** - -This log page describes the commands that the controller supports and the -effects of those commands on the state of the NVM subsystem. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_device_self_test (nvme_mi_ctrl_t ctrl, struct nvme_self_test_log *log) - - Retrieve the device self test log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``struct nvme_self_test_log *log`` - Userspace address of the log payload - -**Description** - -The log page indicates the status of an in progress self test and the -percent complete of that operation, and the results of the previous 20 -self-test operations. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_create_telemetry_host (nvme_mi_ctrl_t ctrl, struct nvme_telemetry_log *log) - - Create host telemetry log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``struct nvme_telemetry_log *log`` - Userspace address of the log payload - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_telemetry_host (nvme_mi_ctrl_t ctrl, __u64 offset, __u32 len, void *log) - - Get Telemetry Host-Initiated log page - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u64 offset`` - Offset into the telemetry data - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Description** - -Retrieves the Telemetry Host-Initiated log page at the requested offset -using the previously existing capture. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_telemetry_ctrl (nvme_mi_ctrl_t ctrl, bool rae, __u64 offset, __u32 len, void *log) - - Get Telemetry Controller-Initiated log page - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset into the telemetry data - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Description** - -Retrieves the Telemetry Controller-Initiated log page at the requested offset -using the previously existing capture. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_endurance_group (nvme_mi_ctrl_t ctrl, __u16 endgid, struct nvme_endurance_group_log *log) - - Get Endurance Group log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u16 endgid`` - Starting group identifier to return in the list - -``struct nvme_endurance_group_log *log`` - User address to store the endurance log - -**Description** - -This log page indicates if an Endurance Group Event has occurred for a -particular Endurance Group. If an Endurance Group Event has occurred, the -details of the particular event are included in the Endurance Group -Information log page for that Endurance Group. An asynchronous event is -generated when an entry for an Endurance Group is newly added to this log -page. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_predictable_lat_nvmset (nvme_mi_ctrl_t ctrl, __u16 nvmsetid, struct nvme_nvmset_predictable_lat_log *log) - - Predictable Latency Per NVM Set - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u16 nvmsetid`` - NVM set id - -``struct nvme_nvmset_predictable_lat_log *log`` - User address to store the predictable latency log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_predictable_lat_event (nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log) - - Retrieve Predictable Latency Event Aggregate Log Page - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset into the predictable latency event - -``__u32 len`` - Length of provided user buffer to hold the log data in bytes - -``void *log`` - User address for log page data - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_ana (nvme_mi_ctrl_t ctrl, enum nvme_log_ana_lsp lsp, bool rae, __u64 offset, __u32 len, void *log) - - Retrieve Asymmetric Namespace Access log page - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``enum nvme_log_ana_lsp lsp`` - Log specific, see :c:type:`enum nvme_get_log_ana_lsp ` - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *log`` - User address to store the ana log - -**Description** - -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 ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_ana_groups (nvme_mi_ctrl_t ctrl, bool rae, __u32 len, struct nvme_ana_group_desc *log) - - Retrieve Asymmetric Namespace Access groups only log page - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u32 len`` - The allocated length of the log page - -``struct nvme_ana_group_desc *log`` - User address to store the ana group log - -**Description** - -See :c:type:`struct nvme_ana_group_desc ` for the definition of the returned structure. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. 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 - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u64 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_endurance_grp_evt (nvme_mi_ctrl_t ctrl, bool rae, __u32 offset, __u32 len, void *log) - - Retrieve Rotational Media Information - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset to the start of the log page - -``__u32 len`` - The allocated length of the log page - -``void *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 `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_fid_supported_effects (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_fid_supported_effects_log *log) - - Retrieve Feature Identifiers Supported and Effects - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_fid_supported_effects_log *log`` - FID Supported and Effects data structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_mi_cmd_supported_effects (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_mi_cmd_supported_effects_log *log) - - displays the MI Commands Supported by the controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_mi_cmd_supported_effects_log *log`` - MI Command Supported and Effects data structure - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_boot_partition (nvme_mi_ctrl_t ctrl, bool rae, __u8 lsp, __u32 len, struct nvme_boot_partition *part) - - Retrieve Boot Partition - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u8 lsp`` - The log specified field of LID - -``__u32 len`` - The allocated size, minimum - struct nvme_boot_partition - -``struct nvme_boot_partition *part`` - User address to store the log page - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum 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 - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``__u32 offset`` - Offset of this log to retrieve - -``__u32 len`` - The allocated size for this portion of the log - -``void *log`` - User address to store the discovery log - -**Description** - -Supported only by fabrics discovery controllers, returning discovery -records. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_media_unit_stat (nvme_mi_ctrl_t ctrl, __u16 domid, struct nvme_media_unit_stat_log *mus) - - Retrieve Media Unit Status - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u16 domid`` - Domain Identifier selection, if supported - -``struct nvme_media_unit_stat_log *mus`` - User address to store the Media Unit statistics log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_support_cap_config_list (nvme_mi_ctrl_t ctrl, __u16 domid, struct nvme_supported_cap_config_list_log *cap) - - Retrieve Supported Capacity Configuration List - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u16 domid`` - Domain Identifier selection, if supported - -``struct nvme_supported_cap_config_list_log *cap`` - User address to store supported capabilities config list - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_reservation (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_resv_notification_log *log) - - Retrieve Reservation Notification - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_resv_notification_log *log`` - User address to store the reservation log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_sanitize (nvme_mi_ctrl_t ctrl, bool rae, struct nvme_sanitize_log_page *log) - - Retrieve Sanitize Status - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``bool rae`` - Retain asynchronous events - -``struct nvme_sanitize_log_page *log`` - User address to store the sanitize log - -**Description** - -The Sanitize Status log page reports sanitize operation time estimates and -information about the most recent sanitize operation. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_zns_changed_zones (nvme_mi_ctrl_t ctrl, __u32 nsid, bool rae, struct nvme_zns_changed_zone_log *log) - - Retrieve list of zones that have changed - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``__u32 nsid`` - Namespace ID - -``bool rae`` - Retain asynchronous events - -``struct nvme_zns_changed_zone_log *log`` - User address to store the changed zone log - -**Description** - -The list of zones that have changed state due to an exceptional event. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_log_persistent_event (nvme_mi_ctrl_t ctrl, enum nvme_pevent_log_action action, __u32 size, void *pevent_log) - - Retrieve Persistent Event Log - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to query - -``enum nvme_pevent_log_action action`` - Action the controller should take during processing this command - -``__u32 size`` - Size of **pevent_log** - -``void *pevent_log`` - User address to store the persistent event log - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_security_send (nvme_mi_ctrl_t ctrl, struct nvme_security_send_args *args) - - Perform a Security Send command on a controller. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_security_send_args *args`` - Security Send command arguments - -**Description** - -Performs a Security Send Admin command as specified by **args**. Response data -is stored in **args->data**, which should be a buffer of **args->data_len** bytes. -Resulting data length is stored in **args->data_len** on successful -command completion. - -Security Send data length should not be greater than 4096 bytes to -comply with specification limits. - -See: :c:type:`struct nvme_get_log_args ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_security_recv (nvme_mi_ctrl_t ctrl, struct nvme_security_receive_args *args) - - Perform a Security Receive command on a controller. - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_security_receive_args *args`` - Security Receive command arguments - -**Description** - -Performs a Security Receive Admin command as specified by **args**. Response -data is stored in **args->data**, which should be a buffer of **args->data_len** -bytes. Resulting data length is stored in **args->data_len** on successful -command completion. - -Security Receive data length should not be greater than 4096 bytes to -comply with specification limits. - -See: :c:type:`struct nvme_get_log_args ` - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_features (nvme_mi_ctrl_t ctrl, struct nvme_get_features_args *args) - - Perform a Get Feature command on a controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_get_features_args *args`` - Get Features command arguments - -**Description** - -Performs a Get Features Admin command as specified by **args**. Returned -feature data will be stored in **args->result** and **args->data**, depending -on the specification of the feature itself; most features do not return -additional data. See section 5.27.1 of the NVMe spec (v2.0b) for -feature-specific information. - -On success, **args->data_len** will be updated with the actual data length -received. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_features_data (nvme_mi_ctrl_t ctrl, enum nvme_features_id fid, __u32 nsid, __u32 data_len, void *data, __u32 *result) - - Helper function for :c:type:`nvme_mi_admin_get_features`() - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``enum nvme_features_id fid`` - Feature identifier - -``__u32 nsid`` - Namespace ID, if applicable for **fid** - -``__u32 data_len`` - Length of feature data, if applicable for **fid**, in bytes - -``void *data`` - User address of feature data, if applicable - -``__u32 *result`` - The command completion result from CQE dword0 - -**Description** - -Helper for optionally features that optionally return data, using the -SEL_CURRENT selector value. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_get_features_simple (nvme_mi_ctrl_t ctrl, enum nvme_features_id fid, __u32 nsid, __u32 *result) - - Get a simple feature value with no data - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``enum nvme_features_id fid`` - Feature identifier - -``__u32 nsid`` - Namespace id, if required by **fid** - -``__u32 *result`` - output feature data - - -.. c:function:: int nvme_mi_admin_set_features (nvme_mi_ctrl_t ctrl, struct nvme_set_features_args *args) - - Perform a Set Features command on a controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_set_features_args *args`` - Set Features command arguments - -**Description** - -Performs a Set Features Admin command as specified by **args**. Result -data will be stored in **args->result**. -on the specification of the feature itself; most features do not return -additional data. See section 5.27.1 of the NVMe spec (v2.0b) for -feature-specific information. - -On success, **args->data_len** will be updated with the actual data length -received. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_mgmt (nvme_mi_ctrl_t ctrl, struct nvme_ns_mgmt_args *args) - - Issue a Namespace Management command - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_ns_mgmt_args *args`` - Namespace management command arguments - -**Description** - -Issues a Namespace Management command to **ctrl**, with arguments specified -from **args**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_mgmt_create (nvme_mi_ctrl_t ctrl, struct nvme_id_ns *ns, __u8 csi, __u32 *nsid) - - Helper for Namespace Management Create command - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_id_ns *ns`` - New namespace parameters - -``__u8 csi`` - Command Set Identifier for new NS - -``__u32 *nsid`` - Set to new namespace ID on create - -**Description** - -Issues a Namespace Management (Create) command to **ctrl**, to create a -new namespace specified by **ns**, using command set **csi**. On success, -the new namespace ID will be written to **nsid**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_mgmt_delete (nvme_mi_ctrl_t ctrl, __u32 nsid) - - Helper for Namespace Management Delete command - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``__u32 nsid`` - Namespace ID to delete - -**Description** - -Issues a Namespace Management (Delete) command to **ctrl**, to delete the -namespace with id **nsid**. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_attach (nvme_mi_ctrl_t ctrl, struct nvme_ns_attach_args *args) - - Attach or detach namespace to controller(s) - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_ns_attach_args *args`` - Namespace Attach command arguments - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_attach_ctrls (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ctrl_list *ctrlist) - - Attach namespace to controllers - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``__u32 nsid`` - Namespace ID to attach - -``struct nvme_ctrl_list *ctrlist`` - Controller list to modify attachment state of nsid - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_ns_detach_ctrls (nvme_mi_ctrl_t ctrl, __u32 nsid, struct nvme_ctrl_list *ctrlist) - - Detach namespace from controllers - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``__u32 nsid`` - Namespace ID to detach - -``struct nvme_ctrl_list *ctrlist`` - Controller list to modify attachment state of nsid - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_fw_download (nvme_mi_ctrl_t ctrl, struct nvme_fw_download_args *args) - - Download part or all of a firmware image to the controller - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send firmware data to - -``struct nvme_fw_download_args *args`` - :c:type:`struct nvme_fw_download_args ` argument structure - -**Description** - -The Firmware Image Download command downloads all or a portion of an image -for a future update to the controller. The Firmware Image Download command -downloads a new image (in whole or in part) to the controller. - -The image may be constructed of multiple pieces that are individually -downloaded with separate Firmware Image Download commands. Each Firmware -Image Download command includes a Dword Offset and Number of Dwords that -specify a dword range. - -The new firmware image is not activated as part of the Firmware Image -Download command. Use the nvme_mi_admin_fw_commit() to activate a newly -downloaded image. - -**Return** - -0 on success, non-zero on failure - - -.. c:function:: int nvme_mi_admin_fw_commit (nvme_mi_ctrl_t ctrl, struct nvme_fw_commit_args *args) - - Commit firmware using the specified action - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send firmware data to - -``struct nvme_fw_commit_args *args`` - :c:type:`struct nvme_fw_download_args ` argument structure - -**Description** - -The Firmware Commit command modifies the firmware image or Boot Partitions. - -**Return** - -0 on success, non-zero on failure - - -.. c:function:: int nvme_mi_admin_format_nvm (nvme_mi_ctrl_t ctrl, struct nvme_format_nvm_args *args) - - Format NVMe namespace - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_format_nvm_args *args`` - Format NVM command arguments - -**Description** - -Perform a low-level format to set the LBA data & metadata size. May destroy -data & metadata on the specified namespaces - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - -.. c:function:: int nvme_mi_admin_sanitize_nvm (nvme_mi_ctrl_t ctrl, struct nvme_sanitize_nvm_args *args) - - Start a subsystem Sanitize operation - -**Parameters** - -``nvme_mi_ctrl_t ctrl`` - Controller to send command to - -``struct nvme_sanitize_nvm_args *args`` - Sanitize command arguments - -**Description** - -A sanitize operation alters all user data in the NVM subsystem such that -recovery of any previous user data from any cache, the non-volatile media, -or any Controller Memory Buffer is not possible. - -The Sanitize command starts a sanitize operation or to recover from a -previously failed sanitize operation. The sanitize operation types that may -be supported are Block Erase, Crypto Erase, and Overwrite. All sanitize -operations are processed in the background, i.e., completion of the sanitize -command does not indicate completion of the sanitize operation. - -**Return** - -The nvme command status if a response was received (see -:c:type:`enum nvme_status_field `) or -1 with errno set otherwise. - - diff --git a/doc/rst/tree.rst b/doc/rst/tree.rst deleted file mode 100644 index d6f270de..00000000 --- a/doc/rst/tree.rst +++ /dev/null @@ -1,2135 +0,0 @@ -.. _tree.h: - -**tree.h** - - -libnvme tree object interface - -.. c:function:: nvme_root_t nvme_create_root (FILE *fp, int log_level) - - Initialize root object - -**Parameters** - -``FILE *fp`` - File descriptor for logging messages - -``int log_level`` - Logging level to use - -**Return** - -Initialized :c:type:`nvme_root_t` object - - -.. c:function:: void nvme_free_tree (nvme_root_t r) - - Free root object - -**Parameters** - -``nvme_root_t r`` - :c:type:`nvme_root_t` object - -**Description** - -Free an :c:type:`nvme_root_t` object and all attached objects - - -.. c:function:: nvme_host_t nvme_first_host (nvme_root_t r) - - Start host iterator - -**Parameters** - -``nvme_root_t r`` - :c:type:`nvme_root_t` object - -**Return** - -First :c:type:`nvme_host_t` object in an iterator - - -.. c:function:: nvme_host_t nvme_next_host (nvme_root_t r, nvme_host_t h) - - Next host iterator - -**Parameters** - -``nvme_root_t r`` - :c:type:`nvme_root_t` object - -``nvme_host_t h`` - Previous :c:type:`nvme_host_t` iterator - -**Return** - -Next :c:type:`nvme_host_t` object in an iterator - - -.. c:function:: nvme_root_t nvme_host_get_root (nvme_host_t h) - - Returns nvme_root_t object - -**Parameters** - -``nvme_host_t h`` - :c:type:`nvme_host_t` object - -**Return** - -:c:type:`nvme_root_t` object from **h** - - -.. c:function:: nvme_host_t nvme_lookup_host (nvme_root_t r, const char *hostnqn, const char *hostid) - - Lookup nvme_host_t object - -**Parameters** - -``nvme_root_t r`` - :c:type:`nvme_root_t` object - -``const char *hostnqn`` - Host NQN - -``const char *hostid`` - Host ID - -**Description** - -Lookup a nvme_host_t object based on **hostnqn** and **hostid** -or create one if not found. - -**Return** - -:c:type:`nvme_host_t` object - - -.. c:function:: const char * nvme_host_get_dhchap_key (nvme_host_t h) - - Return host key - -**Parameters** - -``nvme_host_t h`` - Host for which the key should be returned - -**Return** - -DH-HMAC-CHAP host key or NULL if not set - - -.. c:function:: void nvme_host_set_dhchap_key (nvme_host_t h, const char *key) - - set host key - -**Parameters** - -``nvme_host_t h`` - Host for which the key should be set - -``const char *key`` - DH-HMAC-CHAP Key to set or NULL to clear existing key - - -.. c:function:: nvme_host_t nvme_default_host (nvme_root_t r) - - Initializes the default host - -**Parameters** - -``nvme_root_t r`` - :c:type:`nvme_root_t` object - -**Description** - -Initializes the default host object based on the values in -/etc/nvme/hostnqn and /etc/nvme/hostid and attaches it to **r**. - -**Return** - -:c:type:`nvme_host_t` object - - -.. c:function:: nvme_subsystem_t nvme_first_subsystem (nvme_host_t h) - - Start subsystem iterator - -**Parameters** - -``nvme_host_t h`` - :c:type:`nvme_host_t` object - -**Return** - -first :c:type:`nvme_subsystem_t` object in an iterator - - -.. c:function:: nvme_subsystem_t nvme_next_subsystem (nvme_host_t h, nvme_subsystem_t s) - - Next subsystem iterator - -**Parameters** - -``nvme_host_t h`` - :c:type:`nvme_host_t` object - -``nvme_subsystem_t s`` - Previous :c:type:`nvme_subsystem_t` iterator - -**Return** - -next :c:type:`nvme_subsystem_t` object in an iterator - - -.. c:function:: nvme_subsystem_t nvme_lookup_subsystem (struct nvme_host *h, const char *name, const char *subsysnqn) - - Lookup nvme_subsystem_t object - -**Parameters** - -``struct nvme_host *h`` - :c:type:`nvme_host_t` object - -``const char *name`` - Name of the subsystem (may be NULL) - -``const char *subsysnqn`` - Subsystem NQN - -**Description** - -Lookup a :c:type:`nvme_subsystem_t` object in **h** base on **name** (if present) -and **subsysnqn** or create one if not found. - -**Return** - -nvme_subsystem_t object - - -.. c:function:: void nvme_free_subsystem (struct nvme_subsystem *s) - - Free a subsystem - -**Parameters** - -``struct nvme_subsystem *s`` - subsystem - -**Description** - -Frees **s** and all related objects. - - -.. c:function:: nvme_host_t nvme_subsystem_get_host (nvme_subsystem_t s) - - Returns nvme_host_t object - -**Parameters** - -``nvme_subsystem_t s`` - subsystem - -**Return** - -:c:type:`nvme_host_t` object from **s** - - -.. c:function:: nvme_ns_t nvme_ctrl_first_ns (nvme_ctrl_t c) - - Start namespace iterator - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -First :c:type:`nvme_ns_t` object of an **c** iterator - - -.. c:function:: nvme_ns_t nvme_ctrl_next_ns (nvme_ctrl_t c, nvme_ns_t n) - - Next namespace iterator - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``nvme_ns_t n`` - Previous nvme_ns_t iterator - -**Return** - -Next nvme_ns_t object of an **c** iterator - - -.. c:function:: nvme_path_t nvme_ctrl_first_path (nvme_ctrl_t c) - - Start path iterator - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -First :c:type:`nvme_path_t` object of an **c** iterator - - -.. c:function:: nvme_path_t nvme_ctrl_next_path (nvme_ctrl_t c, nvme_path_t p) - - Next path iterator - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``nvme_path_t p`` - Previous :c:type:`nvme_path_t` object of an **c** iterator - -**Return** - -Next :c:type:`nvme_path_t` object of an **c** iterator - - -.. c:function:: nvme_ctrl_t nvme_subsystem_first_ctrl (nvme_subsystem_t s) - - First ctrl iterator - -**Parameters** - -``nvme_subsystem_t s`` - :c:type:`nvme_subsystem_t` object - -**Return** - -First controller of an **s** iterator - - -.. c:function:: nvme_ctrl_t nvme_subsystem_next_ctrl (nvme_subsystem_t s, nvme_ctrl_t c) - - Next ctrl iterator - -**Parameters** - -``nvme_subsystem_t s`` - :c:type:`nvme_subsystem_t` object - -``nvme_ctrl_t c`` - Previous controller instance of an **s** iterator - -**Return** - -Next controller of an **s** iterator - - -.. c:function:: nvme_path_t nvme_namespace_first_path (nvme_ns_t ns) - - Start path iterator - -**Parameters** - -``nvme_ns_t ns`` - Namespace instance - -**Return** - -First :c:type:`nvme_path_t` object of an **ns** iterator - - -.. c:function:: nvme_path_t nvme_namespace_next_path (nvme_ns_t ns, nvme_path_t p) - - Next path iterator - -**Parameters** - -``nvme_ns_t ns`` - Namespace instance - -``nvme_path_t p`` - Previous :c:type:`nvme_path_t` object of an **ns** iterator - -**Return** - -Next :c:type:`nvme_path_t` object of an **ns** iterator - - -.. c:function:: nvme_ctrl_t nvme_lookup_ctrl (nvme_subsystem_t s, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid, nvme_ctrl_t p) - - Lookup nvme_ctrl_t object - -**Parameters** - -``nvme_subsystem_t s`` - :c:type:`nvme_subsystem_t` object - -``const char *transport`` - Transport name - -``const char *traddr`` - Transport address - -``const char *host_traddr`` - Host transport address - -``const char *host_iface`` - Host interface name - -``const char *trsvcid`` - Transport service identifier - -``nvme_ctrl_t p`` - Previous controller instance - -**Description** - -Lookup a controller in **s** based on **transport**, **traddr**, -**host_traddr**, **host_iface**, and **trsvcid**. **transport** must be specified, -other fields may be required depending on the transport. A new -object is created if none is found. If **p** is specified the lookup -will start at **p** instead of the first controller. - -**Return** - -Controller instance - - -.. c:function:: nvme_ctrl_t nvme_create_ctrl (nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid) - - Allocate an unconnected NVMe controller - -**Parameters** - -``nvme_root_t r`` - NVMe root element - -``const char *subsysnqn`` - Subsystem NQN - -``const char *transport`` - Transport type - -``const char *traddr`` - Transport address - -``const char *host_traddr`` - Host transport address - -``const char *host_iface`` - Host interface name - -``const char *trsvcid`` - Transport service ID - -**Description** - -Creates an unconnected controller to be used for nvme_add_ctrl(). - -**Return** - -Controller instance - - -.. c:function:: nvme_ns_t nvme_subsystem_first_ns (nvme_subsystem_t s) - - Start namespace iterator - -**Parameters** - -``nvme_subsystem_t s`` - :c:type:`nvme_subsystem_t` object - -**Return** - -First :c:type:`nvme_ns_t` object of an **s** iterator - - -.. c:function:: nvme_ns_t nvme_subsystem_next_ns (nvme_subsystem_t s, nvme_ns_t n) - - Next namespace iterator - -**Parameters** - -``nvme_subsystem_t s`` - :c:type:`nvme_subsystem_t` object - -``nvme_ns_t n`` - Previous :c:type:`nvme_ns_t` iterator - -**Return** - -Next :c:type:`nvme_ns_t` object of an **s** iterator - - -.. c:macro:: nvme_for_each_host_safe - -``nvme_for_each_host_safe (r, h, _h)`` - - Traverse host list - -**Parameters** - -``r`` - :c:type:`nvme_root_t` object - -``h`` - :c:type:`nvme_host_t` object - -``_h`` - Temporary :c:type:`nvme_host_t` object - - -.. c:macro:: nvme_for_each_host - -``nvme_for_each_host (r, h)`` - - Traverse host list - -**Parameters** - -``r`` - :c:type:`nvme_root_t` object - -``h`` - :c:type:`nvme_host_t` object - - -.. c:macro:: nvme_for_each_subsystem_safe - -``nvme_for_each_subsystem_safe (h, s, _s)`` - - Traverse subsystems - -**Parameters** - -``h`` - :c:type:`nvme_host_t` object - -``s`` - :c:type:`nvme_subsystem_t` object - -``_s`` - Temporary :c:type:`nvme_subsystem_t` object - - -.. c:macro:: nvme_for_each_subsystem - -``nvme_for_each_subsystem (h, s)`` - - Traverse subsystems - -**Parameters** - -``h`` - :c:type:`nvme_host_t` object - -``s`` - :c:type:`nvme_subsystem_t` object - - -.. c:macro:: nvme_subsystem_for_each_ctrl_safe - -``nvme_subsystem_for_each_ctrl_safe (s, c, _c)`` - - Traverse controllers - -**Parameters** - -``s`` - :c:type:`nvme_subsystem_t` object - -``c`` - Controller instance - -``_c`` - A :c:type:`nvme_ctrl_t_node` to use as temporary storage - - -.. c:macro:: nvme_subsystem_for_each_ctrl - -``nvme_subsystem_for_each_ctrl (s, c)`` - - Traverse controllers - -**Parameters** - -``s`` - :c:type:`nvme_subsystem_t` object - -``c`` - Controller instance - - -.. c:macro:: nvme_ctrl_for_each_ns_safe - -``nvme_ctrl_for_each_ns_safe (c, n, _n)`` - - Traverse namespaces - -**Parameters** - -``c`` - Controller instance - -``n`` - :c:type:`nvme_ns_t` object - -``_n`` - A :c:type:`nvme_ns_t_node` to use as temporary storage - - -.. c:macro:: nvme_ctrl_for_each_ns - -``nvme_ctrl_for_each_ns (c, n)`` - - Traverse namespaces - -**Parameters** - -``c`` - Controller instance - -``n`` - :c:type:`nvme_ns_t` object - - -.. c:macro:: nvme_ctrl_for_each_path_safe - -``nvme_ctrl_for_each_path_safe (c, p, _p)`` - - Traverse paths - -**Parameters** - -``c`` - Controller instance - -``p`` - :c:type:`nvme_path_t` object - -``_p`` - A :c:type:`nvme_path_t_node` to use as temporary storage - - -.. c:macro:: nvme_ctrl_for_each_path - -``nvme_ctrl_for_each_path (c, p)`` - - Traverse paths - -**Parameters** - -``c`` - Controller instance - -``p`` - :c:type:`nvme_path_t` object - - -.. c:macro:: nvme_subsystem_for_each_ns_safe - -``nvme_subsystem_for_each_ns_safe (s, n, _n)`` - - Traverse namespaces - -**Parameters** - -``s`` - :c:type:`nvme_subsystem_t` object - -``n`` - :c:type:`nvme_ns_t` object - -``_n`` - A :c:type:`nvme_ns_t_node` to use as temporary storage - - -.. c:macro:: nvme_subsystem_for_each_ns - -``nvme_subsystem_for_each_ns (s, n)`` - - Traverse namespaces - -**Parameters** - -``s`` - :c:type:`nvme_subsystem_t` object - -``n`` - :c:type:`nvme_ns_t` object - - -.. c:macro:: nvme_namespace_for_each_path_safe - -``nvme_namespace_for_each_path_safe (n, p, _p)`` - - Traverse paths - -**Parameters** - -``n`` - Namespace instance - -``p`` - :c:type:`nvme_path_t` object - -``_p`` - A :c:type:`nvme_path_t_node` to use as temporary storage - - -.. c:macro:: nvme_namespace_for_each_path - -``nvme_namespace_for_each_path (n, p)`` - - Traverse paths - -**Parameters** - -``n`` - Namespace instance - -``p`` - :c:type:`nvme_path_t` object - - -.. c:function:: int nvme_ns_get_fd (nvme_ns_t n) - - Get associated file descriptor - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -File descriptor associated with **n** or -1 - - -.. c:function:: int nvme_ns_get_nsid (nvme_ns_t n) - - NSID of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -NSID of **n** - - -.. c:function:: int nvme_ns_get_lba_size (nvme_ns_t n) - - LBA size of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -LBA size of **n** - - -.. c:function:: int nvme_ns_get_meta_size (nvme_ns_t n) - - Metadata size of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -Metadata size of **n** - - -.. c:function:: uint64_t nvme_ns_get_lba_count (nvme_ns_t n) - - LBA count of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -LBA count of **n** - - -.. c:function:: uint64_t nvme_ns_get_lba_util (nvme_ns_t n) - - LBA utilization of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -LBA utilization of **n** - - -.. c:function:: enum nvme_csi nvme_ns_get_csi (nvme_ns_t n) - - Command set identifier of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -The namespace's command set identifier in use - - -.. c:function:: const uint8_t * nvme_ns_get_eui64 (nvme_ns_t n) - - 64-bit eui of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -A pointer to the 64-bit eui - - -.. c:function:: const uint8_t * nvme_ns_get_nguid (nvme_ns_t n) - - 128-bit nguid of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -A pointer to the 128-bit nguid - - -.. c:function:: void nvme_ns_get_uuid (nvme_ns_t n, unsigned char out[NVME_UUID_LEN]) - - UUID of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``unsigned char out[NVME_UUID_LEN]`` - buffer for the UUID - -**Description** - -Copies the namespace's uuid into **out** - - -.. c:function:: const char * nvme_ns_get_sysfs_dir (nvme_ns_t n) - - sysfs directory of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -sysfs directory name of **n** - - -.. c:function:: const char * nvme_ns_get_name (nvme_ns_t n) - - sysfs name of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -sysfs name of **n** - - -.. c:function:: const char * nvme_ns_get_generic_name (nvme_ns_t n) - - Returns name of generic namespace chardev. - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -Name of generic namespace chardev - - -.. c:function:: const char * nvme_ns_get_firmware (nvme_ns_t n) - - Firmware string of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -Firmware string of **n** - - -.. c:function:: const char * nvme_ns_get_serial (nvme_ns_t n) - - Serial number of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -Serial number string of **n** - - -.. c:function:: const char * nvme_ns_get_model (nvme_ns_t n) - - Model of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -Model string of **n** - - -.. c:function:: nvme_subsystem_t nvme_ns_get_subsystem (nvme_ns_t n) - - :c:type:`nvme_subsystem_t` of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -nvme_subsystem_t object of **n** - - -.. c:function:: nvme_ctrl_t nvme_ns_get_ctrl (nvme_ns_t n) - - :c:type:`nvme_ctrl_t` of a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Description** - -nvme_ctrl_t object may be NULL for a multipathed namespace - -**Return** - -nvme_ctrl_t object of **n** if present - - -.. c:function:: void nvme_free_ns (struct nvme_ns *n) - - Free a namespace object - -**Parameters** - -``struct nvme_ns *n`` - Namespace instance - - -.. c:function:: int nvme_ns_read (nvme_ns_t n, void *buf, off_t offset, size_t count) - - Read from a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``void *buf`` - Buffer into which the data will be transferred - -``off_t offset`` - LBA offset of **n** - -``size_t count`` - Number of sectors in **buf** - -**Return** - -Number of sectors read or -1 on error. - - -.. c:function:: int nvme_ns_write (nvme_ns_t n, void *buf, off_t offset, size_t count) - - Write to a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``void *buf`` - Buffer with data to be written - -``off_t offset`` - LBA offset of **n** - -``size_t count`` - Number of sectors in **buf** - -**Return** - -Number of sectors written or -1 on error - - -.. c:function:: int nvme_ns_verify (nvme_ns_t n, off_t offset, size_t count) - - Verify data on a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``off_t offset`` - LBA offset of **n** - -``size_t count`` - Number of sectors to be verified - -**Return** - -Number of sectors verified - - -.. c:function:: int nvme_ns_compare (nvme_ns_t n, void *buf, off_t offset, size_t count) - - Compare data on a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``void *buf`` - Buffer with data to be compared - -``off_t offset`` - LBA offset of **n** - -``size_t count`` - Number of sectors in **buf** - -**Return** - -Number of sectors compared - - -.. c:function:: int nvme_ns_write_zeros (nvme_ns_t n, off_t offset, size_t count) - - Write zeros to a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``off_t offset`` - LBA offset in **n** - -``size_t count`` - Number of sectors to be written - -**Return** - -Number of sectors written - - -.. c:function:: int nvme_ns_write_uncorrectable (nvme_ns_t n, off_t offset, size_t count) - - Issus a 'write uncorrectable' command - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``off_t offset`` - LBA offset in **n** - -``size_t count`` - Number of sectors to be written - -**Return** - -Number of sectors written - - -.. c:function:: int nvme_ns_flush (nvme_ns_t n) - - Flush data to a namespace - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -**Return** - -0 on success, -1 on error. - - -.. c:function:: int nvme_ns_identify (nvme_ns_t n, struct nvme_id_ns *ns) - - Issue an 'identify namespace' command - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``struct nvme_id_ns *ns`` - :c:type:`nvme_id_ns` buffer - -**Description** - -Writes the data returned by the 'identify namespace' command -into **ns**. - -**Return** - -0 on success, -1 on error. - - -.. c:function:: int nvme_ns_identify_descs (nvme_ns_t n, struct nvme_ns_id_desc *descs) - - Issue an 'identify descriptors' command - -**Parameters** - -``nvme_ns_t n`` - Namespace instance - -``struct nvme_ns_id_desc *descs`` - List of identify descriptors - -**Description** - -Writes the data returned by the 'identify descriptors' command -into **descs**. - -**Return** - -0 on success, -1 on error. - - -.. c:function:: const char * nvme_path_get_name (nvme_path_t p) - - sysfs name of an :c:type:`nvme_path_t` object - -**Parameters** - -``nvme_path_t p`` - :c:type:`nvme_path_t` object - -**Return** - -sysfs name of **p** - - -.. c:function:: const char * nvme_path_get_sysfs_dir (nvme_path_t p) - - sysfs directory of an nvme_path_t object - -**Parameters** - -``nvme_path_t p`` - :c:type:`nvme_path_t` object - -**Return** - -sysfs directory of **p** - - -.. c:function:: const char * nvme_path_get_ana_state (nvme_path_t p) - - ANA state of an nvme_path_t object - -**Parameters** - -``nvme_path_t p`` - :c:type:`nvme_path_t` object - -**Return** - -ANA (Asynchronous Namespace Access) state of **p** - - -.. c:function:: nvme_ctrl_t nvme_path_get_ctrl (nvme_path_t p) - - Parent controller of an nvme_path_t object - -**Parameters** - -``nvme_path_t p`` - :c:type:`nvme_path_t` object - -**Return** - -Parent controller if present - - -.. c:function:: nvme_ns_t nvme_path_get_ns (nvme_path_t p) - - Parent namespace of an nvme_path_t object - -**Parameters** - -``nvme_path_t p`` - :c:type:`nvme_path_t` object - -**Return** - -Parent namespace if present - - -.. c:function:: int nvme_ctrl_get_fd (nvme_ctrl_t c) - - Get associated file descriptor - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -File descriptor associated with **c** or -1 - - -.. c:function:: const char * nvme_ctrl_get_name (nvme_ctrl_t c) - - sysfs name of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -sysfs name of **c** - - -.. c:function:: const char * nvme_ctrl_get_sysfs_dir (nvme_ctrl_t c) - - sysfs directory of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -sysfs directory name of **c** - - -.. c:function:: const char * nvme_ctrl_get_address (nvme_ctrl_t c) - - Address string of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -NVMe-over-Fabrics address string of **c** or empty string -of no address is present. - - -.. c:function:: const char * nvme_ctrl_get_firmware (nvme_ctrl_t c) - - Firmware string of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Firmware string of **c** - - -.. c:function:: const char * nvme_ctrl_get_model (nvme_ctrl_t c) - - Model of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Model string of **c** - - -.. c:function:: const char * nvme_ctrl_get_state (nvme_ctrl_t c) - - Running state of an controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -String indicating the running state of **c** - - -.. c:function:: const char * nvme_ctrl_get_numa_node (nvme_ctrl_t c) - - NUMA node of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -String indicating the NUMA node - - -.. c:function:: const char * nvme_ctrl_get_queue_count (nvme_ctrl_t c) - - Queue count of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Queue count of **c** - - -.. c:function:: const char * nvme_ctrl_get_serial (nvme_ctrl_t c) - - Serial number of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Serial number string of **c** - - -.. c:function:: const char * nvme_ctrl_get_sqsize (nvme_ctrl_t c) - - SQ size of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -SQ size (as string) of **c** - - -.. c:function:: const char * nvme_ctrl_get_transport (nvme_ctrl_t c) - - Transport type of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Transport type of **c** - - -.. c:function:: const char * nvme_ctrl_get_subsysnqn (nvme_ctrl_t c) - - Subsystem NQN of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Subsystem NQN of **c** - - -.. c:function:: nvme_subsystem_t nvme_ctrl_get_subsystem (nvme_ctrl_t c) - - Parent subsystem of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Parent nvme_subsystem_t object - - -.. c:function:: const char * nvme_ctrl_get_traddr (nvme_ctrl_t c) - - Transport address of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Transport address of **c** - - -.. c:function:: const char * nvme_ctrl_get_trsvcid (nvme_ctrl_t c) - - Transport service identifier of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Transport service identifier of **c** (if present) - - -.. c:function:: const char * nvme_ctrl_get_host_traddr (nvme_ctrl_t c) - - Host transport address of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Host transport address of **c** (if present) - - -.. c:function:: const char * nvme_ctrl_get_host_iface (nvme_ctrl_t c) - - Host interface name of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Host interface name of **c** (if present) - - -.. c:function:: const char * nvme_ctrl_get_dhchap_host_key (nvme_ctrl_t c) - - Return host key - -**Parameters** - -``nvme_ctrl_t c`` - Controller to be checked - -**Return** - -DH-HMAC-CHAP host key or NULL if not set - - -.. c:function:: void nvme_ctrl_set_dhchap_host_key (nvme_ctrl_t c, const char *key) - - Set host key - -**Parameters** - -``nvme_ctrl_t c`` - Host for which the key should be set - -``const char *key`` - DH-HMAC-CHAP Key to set or NULL to clear existing key - - -.. c:function:: const char * nvme_ctrl_get_dhchap_key (nvme_ctrl_t c) - - Return controller key - -**Parameters** - -``nvme_ctrl_t c`` - Controller for which the key should be set - -**Return** - -DH-HMAC-CHAP controller key or NULL if not set - - -.. c:function:: void nvme_ctrl_set_dhchap_key (nvme_ctrl_t c, const char *key) - - Set controller key - -**Parameters** - -``nvme_ctrl_t c`` - Controller for which the key should be set - -``const char *key`` - DH-HMAC-CHAP Key to set or NULL to clear existing key - - -.. c:function:: struct nvme_fabrics_config * nvme_ctrl_get_config (nvme_ctrl_t c) - - Fabrics configuration of a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Fabrics configuration of **c** - - -.. c:function:: void nvme_ctrl_set_discovered (nvme_ctrl_t c, bool discovered) - - Set the 'discovered' flag - -**Parameters** - -``nvme_ctrl_t c`` - nvme_ctrl_t object - -``bool discovered`` - Value of the 'discovered' flag - -**Description** - -Set the 'discovered' flag of **c** to **discovered** - - -.. c:function:: bool nvme_ctrl_is_discovered (nvme_ctrl_t c) - - Returns the value of the 'discovered' flag - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Value of the 'discovered' flag of **c** - - -.. c:function:: void nvme_ctrl_set_persistent (nvme_ctrl_t c, bool persistent) - - Set the 'persistent' flag - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``bool persistent`` - value of the 'persistent' flag - -**Description** - -Set the 'persistent' flag of **c** to **persistent** - - -.. c:function:: bool nvme_ctrl_is_persistent (nvme_ctrl_t c) - - Returns the value of the 'persistent' flag - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Return** - -Value of the 'persistent' flag of **c** - - -.. c:function:: void nvme_ctrl_set_discovery_ctrl (nvme_ctrl_t c, bool discovery) - - Set the 'discovery_ctrl' flag - -**Parameters** - -``nvme_ctrl_t c`` - Controller to be modified - -``bool discovery`` - value of the discovery_ctrl flag - -**Description** - -Sets the 'discovery_ctrl' flag in **c** to specify whether -**c** connects to a discovery subsystem. - - -.. c:function:: bool nvme_ctrl_is_discovery_ctrl (nvme_ctrl_t c) - - Check the 'discovery_ctrl' flag - -**Parameters** - -``nvme_ctrl_t c`` - Controller to be checked - -**Description** - -Returns the value of the 'discovery_ctrl' flag which specifies whether -**c** connects to a discovery subsystem. - -**Return** - -Value of the 'discover_ctrl' flag - - -.. c:function:: int nvme_ctrl_identify (nvme_ctrl_t c, struct nvme_id_ctrl *id) - - Issues an 'identify controller' command - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``struct nvme_id_ctrl *id`` - Identify controller data structure - -**Description** - -Issues an 'identify controller' command to **c** and copies the -data into **id**. - -**Return** - -0 on success or -1 on failure. - - -.. c:function:: int nvme_disconnect_ctrl (nvme_ctrl_t c) - - Disconnect a controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -**Description** - -Issues a 'disconnect' fabrics command to **c** - -**Return** - -0 on success, -1 on failure. - - -.. c:function:: nvme_ctrl_t nvme_scan_ctrl (nvme_root_t r, const char *name) - - Scan on a controller - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -``const char *name`` - Name of the controller - -**Description** - -Scans a controller with sysfs name **name** and add it to **r**. - -**Return** - -nvme_ctrl_t object - - -.. c:function:: void nvme_rescan_ctrl (nvme_ctrl_t c) - - Rescan an existing controller - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - - -.. c:function:: int nvme_init_ctrl (nvme_host_t h, nvme_ctrl_t c, int instance) - - Initialize nvme_ctrl_t object for an existing controller. - -**Parameters** - -``nvme_host_t h`` - nvme_host_t object - -``nvme_ctrl_t c`` - nvme_ctrl_t object - -``int instance`` - Instance number (e.g. 1 for nvme1) - -**Return** - -The ioctl() return code. Typically 0 on success. - - -.. c:function:: void nvme_free_ctrl (struct nvme_ctrl *c) - - Free controller - -**Parameters** - -``struct nvme_ctrl *c`` - Controller instance - - -.. c:function:: void nvme_unlink_ctrl (struct nvme_ctrl *c) - - Unlink controller - -**Parameters** - -``struct nvme_ctrl *c`` - Controller instance - - -.. c:function:: const char * nvme_subsystem_get_nqn (nvme_subsystem_t s) - - Retrieve NQN from subsystem - -**Parameters** - -``nvme_subsystem_t s`` - nvme_subsystem_t object - -**Return** - -NQN of subsystem - - -.. c:function:: const char * nvme_subsystem_get_sysfs_dir (nvme_subsystem_t s) - - sysfs directory of an nvme_subsystem_t object - -**Parameters** - -``nvme_subsystem_t s`` - nvme_subsystem_t object - -**Return** - -sysfs directory name of **s** - - -.. c:function:: const char * nvme_subsystem_get_name (nvme_subsystem_t s) - - sysfs name of an nvme_subsystem_t object - -**Parameters** - -``nvme_subsystem_t s`` - nvme_subsystem_t object - -**Return** - -sysfs name of **s** - - -.. c:function:: const char * nvme_subsystem_get_type (nvme_subsystem_t s) - - Returns the type of a subsystem - -**Parameters** - -``nvme_subsystem_t s`` - nvme_subsystem_t object - -**Description** - -Returns the subsystem type of **s**. - -**Return** - -'nvm' or 'discovery' - - -.. c:function:: int nvme_scan_topology (nvme_root_t r, nvme_scan_filter_t f, void *f_args) - - Scan NVMe topology and apply filter - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -``nvme_scan_filter_t f`` - filter to apply - -``void *f_args`` - user-specified argument to **f** - -**Description** - -Scans the NVMe topology and filters out the resulting elements -by applying **f**. - -**Return** - -Number of elements scanned - - -.. c:function:: const char * nvme_host_get_hostnqn (nvme_host_t h) - - Host NQN of an nvme_host_t object - -**Parameters** - -``nvme_host_t h`` - nvme_host_t object - -**Return** - -Host NQN of **h** - - -.. c:function:: const char * nvme_host_get_hostid (nvme_host_t h) - - Host ID of an nvme_host_t object - -**Parameters** - -``nvme_host_t h`` - nvme_host_t object - -**Return** - -Host ID of **h** - - -.. c:function:: void nvme_free_host (nvme_host_t h) - - Free nvme_host_t object - -**Parameters** - -``nvme_host_t h`` - nvme_host_t object - - -.. c:function:: nvme_root_t nvme_scan (const char *config_file) - - Scan NVMe topology - -**Parameters** - -``const char *config_file`` - Configuration file - -**Return** - -nvme_root_t object of found elements - - -.. c:function:: int nvme_read_config (nvme_root_t r, const char *config_file) - - Read NVMe JSON configuration file - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -``const char *config_file`` - JSON configuration file - -**Description** - -Read in the contents of **config_file** and merge them with -the elements in **r**. - -**Return** - -0 on success, -1 on failure with errno set. - - -.. c:function:: void nvme_refresh_topology (nvme_root_t r) - - Refresh nvme_root_t object contents - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -**Description** - -Removes all elements in **r** and rescans the existing topology. - - -.. c:function:: int nvme_update_config (nvme_root_t r) - - Update JSON configuration - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -**Description** - -Updates the JSON configuration file with the contents of **r**. - -**Return** - -0 on success, -1 on failure. - - -.. c:function:: int nvme_dump_config (nvme_root_t r) - - Print the JSON configuration - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -**Description** - -Prints the current contents of the JSON configuration -file to stdout. - -**Return** - -0 on success, -1 on failure. - - -.. c:function:: int nvme_dump_tree (nvme_root_t r) - - Dump internal object tree - -**Parameters** - -``nvme_root_t r`` - nvme_root_t object - -**Description** - -Prints the internal object tree in JSON format -to stdout. - -**Return** - -0 on success, -1 on failure. - - -.. c:function:: char * nvme_get_attr (const char *d, const char *attr) - - Read sysfs attribute - -**Parameters** - -``const char *d`` - sysfs directory - -``const char *attr`` - sysfs attribute name - -**Return** - -String with the contents of **attr** or ``NULL`` in case of an empty value - or in case of an error (indicated by non-zero errno code). - - -.. c:function:: char * nvme_get_subsys_attr (nvme_subsystem_t s, const char *attr) - - Read subsystem sysfs attribute - -**Parameters** - -``nvme_subsystem_t s`` - nvme_subsystem_t object - -``const char *attr`` - sysfs attribute name - -**Return** - -String with the contents of **attr** or ``NULL`` in case of an empty value - or in case of an error (indicated by non-zero errno code). - - -.. c:function:: char * nvme_get_ctrl_attr (nvme_ctrl_t c, const char *attr) - - Read controller sysfs attribute - -**Parameters** - -``nvme_ctrl_t c`` - Controller instance - -``const char *attr`` - sysfs attribute name - -**Return** - -String with the contents of **attr** or ``NULL`` in case of an empty value - or in case of an error (indicated by non-zero errno code). - - -.. c:function:: char * nvme_get_ns_attr (nvme_ns_t n, const char *attr) - - Read namespace sysfs attribute - -**Parameters** - -``nvme_ns_t n`` - nvme_ns_t object - -``const char *attr`` - sysfs attribute name - -**Return** - -String with the contents of **attr** or ``NULL`` in case of an empty value - or in case of an error (indicated by non-zero errno code). - - -.. c:function:: nvme_ns_t nvme_subsystem_lookup_namespace (struct nvme_subsystem *s, __u32 nsid) - - lookup namespace by NSID - -**Parameters** - -``struct nvme_subsystem *s`` - nvme_subsystem_t object - -``__u32 nsid`` - Namespace id - -**Return** - -nvme_ns_t of the namespace with id **nsid** in subsystem **s** - - -.. c:function:: char * nvme_get_path_attr (nvme_path_t p, const char *attr) - - Read path sysfs attribute - -**Parameters** - -``nvme_path_t p`` - nvme_path_t object - -``const char *attr`` - sysfs attribute name - -**Return** - -String with the contents of **attr** or ``NULL`` in case of an empty value - or in case of an error (indicated by non-zero errno code). - - -.. c:function:: nvme_ns_t nvme_scan_namespace (const char *name) - - scan namespace based on sysfs name - -**Parameters** - -``const char *name`` - sysfs name of the namespace to scan - -**Return** - -nvme_ns_t object or NULL if not found. - - -.. c:function:: const char * nvme_host_get_hostsymname (nvme_host_t h) - - Get the host's symbolic name - -**Parameters** - -``nvme_host_t h`` - Host for which the symbolic name should be returned. - -**Return** - -The symbolic name or NULL if a symbolic name hasn't been -configure. - - -.. c:function:: void nvme_host_set_hostsymname (nvme_host_t h, const char *hostsymname) - - Set the host's symbolic name - -**Parameters** - -``nvme_host_t h`` - Host for which the symbolic name should be set. - -``const char *hostsymname`` - Symbolic name - - diff --git a/doc/rst/types.rst b/doc/rst/types.rst deleted file mode 100644 index 9140821c..00000000 --- a/doc/rst/types.rst +++ /dev/null @@ -1,11081 +0,0 @@ -.. _types.h: - -**types.h** - - -NVMe standard definitions - -.. c:macro:: NVME_GET - -``NVME_GET (value, name)`` - - extract field from complex value - -**Parameters** - -``value`` - The original value of a complex field - -``name`` - The name of the sub-field within an nvme value - -**Description** - -By convention, this library defines _SHIFT and _MASK such that mask can be -applied after the shift to isolate a specific set of bits that decode to a -sub-field. - -**Return** - -The 'name' field from 'value' - - -.. c:macro:: NVME_SET - -``NVME_SET (value, name)`` - - set field into complex value - -**Parameters** - -``value`` - The value to be set in its completed position - -``name`` - The name of the sub-field within an nvme value - -**Return** - -The 'name' field from 'value' - - - - -.. c:enum:: nvme_constants - - A place to stash various constant nvme values - -**Constants** - -``NVME_NSID_ALL`` - A broadcast value that is used to specify all - namespaces - -``NVME_NSID_NONE`` - The invalid namespace id, for when the nsid - parameter is not used in a command - -``NVME_UUID_NONE`` - Use to omit a uuid command parameter - -``NVME_CNTLID_NONE`` - Use to omit a cntlid command parameter - -``NVME_CNSSPECID_NONE`` - Use to omit a cns_specific_id command parameter - -``NVME_LOG_LSP_NONE`` - Use to omit a log lsp command parameter - -``NVME_LOG_LSI_NONE`` - Use to omit a log lsi command parameter - -``NVME_LOG_LPO_NONE`` - Use to omit a log lpo command parameter - -``NVME_IDENTIFY_DATA_SIZE`` - The transfer size for nvme identify commands - -``NVME_LOG_SUPPORTED_LOG_PAGES_MAX`` - The largest possible index in the supported - log pages log. - -``NVME_ID_NVMSET_LIST_MAX`` - The largest possible nvmset index in identify - nvmeset - -``NVME_ID_UUID_LIST_MAX`` - The largest possible uuid index in identify - uuid list - -``NVME_ID_CTRL_LIST_MAX`` - The largest possible controller index in - identify controller list - -``NVME_ID_NS_LIST_MAX`` - The largest possible namespace index in - identify namespace list - -``NVME_ID_SECONDARY_CTRL_MAX`` - The largest possible secondary controller index - in identify secondary controller - -``NVME_ID_DOMAIN_LIST_MAX`` - The largest possible domain index in the - in domain list - -``NVME_ID_ENDURANCE_GROUP_LIST_MAX`` - The largest possible endurance group - index in the endurance group list - -``NVME_ID_ND_DESCRIPTOR_MAX`` - The largest possible namespace granularity - index in the namespace granularity descriptor - list - -``NVME_FEAT_LBA_RANGE_MAX`` - The largest possible LBA range index in feature - lba range type - -``NVME_LOG_ST_MAX_RESULTS`` - The largest possible self test result index in the - device self test log - -``NVME_LOG_TELEM_BLOCK_SIZE`` - Specification defined size of Telemetry Data Blocks - -``NVME_LOG_FID_SUPPORTED_EFFECTS_MAX`` - The largest possible FID index in the - feature identifiers effects log. - -``NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_MAX`` - The largest possible MI Command index - in the MI Command effects log. - -``NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_RESERVED`` - The reserved space in the MI Command - effects log. - -``NVME_DSM_MAX_RANGES`` - The largest possible range index in a data-set - management command - -``NVME_NQN_LENGTH`` - Max length for NVMe Qualified Name - -``NVMF_TRADDR_SIZE`` - Max Transport Address size - -``NVMF_TSAS_SIZE`` - Max Transport Specific Address Subtype size - -``NVME_ZNS_CHANGED_ZONES_MAX`` - Max number of zones in the changed zones log - page - - - - -.. c:enum:: nvme_csi - - Defined command set indicators - -**Constants** - -``NVME_CSI_NVM`` - NVM Command Set Indicator - -``NVME_CSI_KV`` - Key Value Command Set - -``NVME_CSI_ZNS`` - Zoned Namespace Command Set - - - - -.. c:enum:: nvme_register_offsets - - controller registers for all transports. This is the layout of BAR0/1 for PCIe, and properties for fabrics. - -**Constants** - -``NVME_REG_CAP`` - Controller Capabilities - -``NVME_REG_VS`` - Version - -``NVME_REG_INTMS`` - Interrupt Mask Set - -``NVME_REG_INTMC`` - Interrupt Mask Clear - -``NVME_REG_CC`` - Controller Configuration - -``NVME_REG_CSTS`` - Controller Status - -``NVME_REG_NSSR`` - NVM Subsystem Reset - -``NVME_REG_AQA`` - Admin Queue Attributes - -``NVME_REG_ASQ`` - Admin SQ Base Address - -``NVME_REG_ACQ`` - Admin CQ Base Address - -``NVME_REG_CMBLOC`` - Controller Memory Buffer Location - -``NVME_REG_CMBSZ`` - Controller Memory Buffer Size - -``NVME_REG_BPINFO`` - Boot Partition Information - -``NVME_REG_BPRSEL`` - Boot Partition Read Select - -``NVME_REG_BPMBL`` - Boot Partition Memory Buffer Location - -``NVME_REG_CMBMSC`` - Controller Memory Buffer Memory Space Control - -``NVME_REG_CMBSTS`` - Controller Memory Buffer Status - -``NVME_REG_CRTO`` - Controller Ready Timeouts - -``NVME_REG_PMRCAP`` - Persistent Memory Capabilities - -``NVME_REG_PMRCTL`` - Persistent Memory Region Control - -``NVME_REG_PMRSTS`` - Persistent Memory Region Status - -``NVME_REG_PMREBS`` - Persistent Memory Region Elasticity Buffer Size - -``NVME_REG_PMRSWTP`` - Memory Region Sustained Write Throughput - -``NVME_REG_PMRMSCL`` - Persistent Memory Region Controller Memory Space Control Lower - -``NVME_REG_PMRMSCU`` - Persistent Memory Region Controller Memory Space Control Upper - - -.. c:function:: bool nvme_is_64bit_reg (__u32 offset) - - Checks if offset of the controller register is a know 64bit value. - -**Parameters** - -``__u32 offset`` - Offset of controller register field in bytes - -**Description** - -This function does not care about transport so that the offset is not going -to be checked inside of this function for the unsupported fields in a -specific transport. For example, BPMBL(Boot Partition Memory Buffer -Location) register is not supported by fabrics, but it can be checked here. - -**Return** - -true if given offset is 64bit register, otherwise it returns false. - - -.. c:function:: __u64 nvme_cmb_size (__u32 cmbsz) - - Calculate size of the controller memory buffer - -**Parameters** - -``__u32 cmbsz`` - Value from controller register ``NVME_REG_CMBSZ`` - -**Return** - -size of controller memory buffer in bytes - - -.. c:function:: __u64 nvme_pmr_size (__u32 pmrebs) - - Calculate size of persistent memory region elasticity buffer - -**Parameters** - -``__u32 pmrebs`` - Value from controller register ``NVME_REG_PMREBS`` - -**Return** - -size of controller persistent memory buffer in bytes - - -.. c:function:: __u64 nvme_pmr_throughput (__u32 pmrswtp) - - Calculate throughput of persistent memory buffer - -**Parameters** - -``__u32 pmrswtp`` - Value from controller register ``NVME_REG_PMRSWTP`` - -**Return** - -throughput of controller persistent memory buffer in bytes/second - - - - -.. c:enum:: nvme_psd_flags - - Possible flag values in nvme power state descriptor - -**Constants** - -``NVME_PSD_FLAGS_MXPS`` - Indicates the scale for the Maximum Power - field. If this bit is cleared, then the scale of the - Maximum Power field is in 0.01 Watts. If this bit is - set, then the scale of the Maximum Power field is in - 0.0001 Watts. - -``NVME_PSD_FLAGS_NOPS`` - Indicates whether the controller processes I/O - commands in this power state. If this bit is cleared, - then the controller processes I/O commands in this - power state. If this bit is set, then the controller - does not process I/O commands in this power state. - - - - -.. c:enum:: nvme_psd_ps - - Known values for :c:type:`struct nvme_psd ` ``ips`` and ``aps``. Use with nvme_psd_power_scale() to extract the power scale field to match this enum. - -**Constants** - -``NVME_PSD_PS_NOT_REPORTED`` - Not reported - -``NVME_PSD_PS_100_MICRO_WATT`` - 0.0001 watt scale - -``NVME_PSD_PS_10_MILLI_WATT`` - 0.01 watt scale - - -.. c:function:: unsigned int nvme_psd_power_scale (__u8 ps) - - power scale occupies the upper 3 bits - -**Parameters** - -``__u8 ps`` - power scale value - -**Return** - -power scale value - - - - -.. c:enum:: nvme_psd_workload - - Specifies a workload hint in the Power Management Feature (see :c:type:`struct nvme_psd `.apw) to inform the NVM subsystem or indicate the conditions for the active power level. - -**Constants** - -``NVME_PSD_WORKLOAD_NP`` - The workload is unknown or not provided. - -``NVME_PSD_WORKLOAD_1`` - Extended Idle Period with a Burst of Random Write - consists of five minutes of idle followed by - thirty-two random write commands of size 1 MiB - submitted to a single controller while all other - controllers in the NVM subsystem are idle, and then - thirty (30) seconds of idle. - -``NVME_PSD_WORKLOAD_2`` - Heavy Sequential Writes consists of 80,000 - sequential write commands of size 128 KiB submitted to - a single controller while all other controllers in the - NVM subsystem are idle. The submission queue(s) - should be sufficiently large allowing the host to - ensure there are multiple commands pending at all - times during the workload. - - - - -.. c:struct:: nvme_id_psd - - Power Management data structure - -**Definition** - -:: - - struct nvme_id_psd { - __le16 mp; - __u8 rsvd2; - __u8 flags; - __le32 enlat; - __le32 exlat; - __u8 rrt; - __u8 rrl; - __u8 rwt; - __u8 rwl; - __le16 idlp; - __u8 ips; - __u8 rsvd19; - __le16 actp; - __u8 apws; - __u8 rsvd23[9]; - }; - -**Members** - -``mp`` - Maximum Power indicates the sustained maximum power consumed by the - NVM subsystem in this power state. The power in Watts is equal to - the value in this field multiplied by the scale specified in the Max - Power Scale bit (see :c:type:`enum nvme_psd_flags `). A value of 0 indicates - Maximum Power is not reported. - -``rsvd2`` - Reserved - -``flags`` - Additional decoding flags, see :c:type:`enum nvme_psd_flags `. - -``enlat`` - Entry Latency indicates the maximum latency in microseconds - associated with entering this power state. A value of 0 indicates - Entry Latency is not reported. - -``exlat`` - Exit Latency indicates the maximum latency in microseconds - associated with exiting this power state. A value of 0 indicates - Exit Latency is not reported. - -``rrt`` - Relative Read Throughput indicates the read throughput rank - associated with this power state relative to others. The value in - this is less than the number of supported power states. - -``rrl`` - Relative Read Latency indicates the read latency rank associated - with this power state relative to others. The value in this field is - less than the number of supported power states. - -``rwt`` - Relative Write Throughput indicates write throughput rank associated - with this power state relative to others. The value in this field is - less than the number of supported power states - -``rwl`` - Relative Write Latency indicates the write latency rank associated - with this power state relative to others. The value in this field is - less than the number of supported power states - -``idlp`` - Idle Power indicates the typical power consumed by the NVM - subsystem over 30 seconds in this power state when idle. - -``ips`` - Idle Power Scale indicates the scale for :c:type:`struct nvme_id_psd `.idlp, - see :c:type:`enum nvme_psd_ps ` for decoding this field. - -``rsvd19`` - Reserved - -``actp`` - Active Power indicates the largest average power consumed by the - NVM subsystem over a 10 second period in this power state with - the workload indicated in the Active Power Workload field. - -``apws`` - Bits 7-6: Active Power Scale(APS) indicates the scale for the :c:type:`struct - nvme_id_psd `.actp, see :c:type:`enum nvme_psd_ps ` for decoding this value. - Bits 2-0: Active Power Workload(APW) indicates the workload - used to calculate maximum power for this power state. - See :c:type:`enum nvme_psd_workload ` for decoding this field. - -``rsvd23`` - Reserved - - - - - -.. c:struct:: nvme_id_ctrl - - Identify Controller data structure - -**Definition** - -:: - - struct nvme_id_ctrl { - __le16 vid; - __le16 ssvid; - char sn[20]; - char mn[40]; - char fr[8]; - __u8 rab; - __u8 ieee[3]; - __u8 cmic; - __u8 mdts; - __le16 cntlid; - __le32 ver; - __le32 rtd3r; - __le32 rtd3e; - __le32 oaes; - __le32 ctratt; - __le16 rrls; - __u8 rsvd102[9]; - __u8 cntrltype; - __u8 fguid[16]; - __le16 crdt1; - __le16 crdt2; - __le16 crdt3; - __u8 rsvd134[119]; - __u8 nvmsr; - __u8 vwci; - __u8 mec; - __le16 oacs; - __u8 acl; - __u8 aerl; - __u8 frmw; - __u8 lpa; - __u8 elpe; - __u8 npss; - __u8 avscc; - __u8 apsta; - __le16 wctemp; - __le16 cctemp; - __le16 mtfa; - __le32 hmpre; - __le32 hmmin; - __u8 tnvmcap[16]; - __u8 unvmcap[16]; - __le32 rpmbs; - __le16 edstt; - __u8 dsto; - __u8 fwug; - __le16 kas; - __le16 hctma; - __le16 mntmt; - __le16 mxtmt; - __le32 sanicap; - __le32 hmminds; - __le16 hmmaxd; - __le16 nsetidmax; - __le16 endgidmax; - __u8 anatt; - __u8 anacap; - __le32 anagrpmax; - __le32 nanagrpid; - __le32 pels; - __le16 domainid; - __u8 rsvd358[10]; - __u8 megcap[16]; - __u8 rsvd384[128]; - __u8 sqes; - __u8 cqes; - __le16 maxcmd; - __le32 nn; - __le16 oncs; - __le16 fuses; - __u8 fna; - __u8 vwc; - __le16 awun; - __le16 awupf; - __u8 icsvscc; - __u8 nwpc; - __le16 acwu; - __le16 ocfs; - __le32 sgls; - __le32 mnan; - __u8 maxdna[16]; - __le32 maxcna; - __u8 rsvd564[204]; - char subnqn[NVME_NQN_LENGTH]; - __u8 rsvd1024[768]; - __le32 ioccsz; - __le32 iorcsz; - __le16 icdoff; - __u8 fcatt; - __u8 msdbd; - __le16 ofcs; - __u8 dctype; - __u8 rsvd1807[241]; - struct nvme_id_psd psd[32]; - __u8 vs[1024]; - }; - -**Members** - -``vid`` - PCI Vendor ID, the company vendor identifier that is assigned by - the PCI SIG. - -``ssvid`` - PCI Subsystem Vendor ID, the company vendor identifier that is - assigned by the PCI SIG for the subsystem. - -``sn`` - Serial Number in ASCII - -``mn`` - Model Number in ASCII - -``fr`` - Firmware Revision in ASCII, the currently active firmware - revision for the NVM subsystem - -``rab`` - Recommended Arbitration Burst, reported as a power of two - -``ieee`` - IEEE assigned Organization Unique Identifier - -``cmic`` - Controller Multipath IO and Namespace Sharing Capabilities of - the controller and NVM subsystem. See :c:type:`enum nvme_id_ctrl_cmic `. - -``mdts`` - Max Data Transfer Size is the largest data transfer size. The - host should not submit a command that exceeds this maximum data - transfer size. The value is in units of the minimum memory page - size (CAP.MPSMIN) and is reported as a power of two - -``cntlid`` - Controller ID, the NVM subsystem unique controller identifier - associated with the controller. - -``ver`` - Version, this field contains the value reported in the Version - register, or property (see :c:type:`enum nvme_registers ` ``NVME_REG_VS``). - -``rtd3r`` - RTD3 Resume Latency, the expected latency in microseconds to resume - from Runtime D3 - -``rtd3e`` - RTD3 Exit Latency, the typical latency in microseconds to enter - Runtime D3. - -``oaes`` - Optional Async Events Supported, see **enum** nvme_id_ctrl_oaes. - -``ctratt`` - Controller Attributes, see **enum** nvme_id_ctrl_ctratt. - -``rrls`` - Read Recovery Levels. If a bit is set, then the corresponding - Read Recovery Level is supported. If a bit is cleared, then the - corresponding Read Recovery Level is not supported. - -``rsvd102`` - Reserved - -``cntrltype`` - Controller Type, see :c:type:`enum nvme_id_ctrl_cntrltype ` - -``fguid`` - FRU GUID, a 128-bit value that is globally unique for a given - Field Replaceable Unit - -``crdt1`` - Controller Retry Delay time in 100 millisecond units if CQE CRD - field is 1 - -``crdt2`` - Controller Retry Delay time in 100 millisecond units if CQE CRD - field is 2 - -``crdt3`` - Controller Retry Delay time in 100 millisecond units if CQE CRD - field is 3 - -``rsvd134`` - Reserved - -``nvmsr`` - NVM Subsystem Report, see :c:type:`enum nvme_id_ctrl_nvmsr ` - -``vwci`` - VPD Write Cycle Information, see :c:type:`enum nvme_id_ctrl_vwci ` - -``mec`` - Management Endpoint Capabilities, see :c:type:`enum nvme_id_ctrl_mec ` - -``oacs`` - Optional Admin Command Support,the optional Admin commands and - features supported by the controller, see :c:type:`enum nvme_id_ctrl_oacs `. - -``acl`` - Abort Command Limit, the maximum number of concurrently - executing Abort commands supported by the controller. This is a - 0's based value. - -``aerl`` - Async Event Request Limit, the maximum number of concurrently - outstanding Asynchronous Event Request commands supported by the - controller This is a 0's based value. - -``frmw`` - Firmware Updates indicates capabilities regarding firmware - updates. See :c:type:`enum nvme_id_ctrl_frmw `. - -``lpa`` - Log Page Attributes, see :c:type:`enum nvme_id_ctrl_lpa `. - -``elpe`` - Error Log Page Entries, the maximum number of Error Information - log entries that are stored by the controller. This field is a - 0's based value. - -``npss`` - Number of Power States Supported, the number of NVM Express - power states supported by the controller, indicating the number - of valid entries in :c:type:`struct nvme_id_ctrl `.psd. This is a 0's - based value. - -``avscc`` - Admin Vendor Specific Command Configuration, see - :c:type:`enum nvme_id_ctrl_avscc `. - -``apsta`` - Autonomous Power State Transition Attributes, see - :c:type:`enum nvme_id_ctrl_apsta `. - -``wctemp`` - Warning Composite Temperature Threshold indicates - the minimum Composite Temperature field value (see :c:type:`struct - nvme_smart_log `.critical_comp_time) that indicates an overheating - condition during which controller operation continues. - -``cctemp`` - Critical Composite Temperature Threshold, field indicates the - minimum Composite Temperature field value (see :c:type:`struct - nvme_smart_log `.critical_comp_time) that indicates a critical - overheating condition. - -``mtfa`` - Maximum Time for Firmware Activation indicates the maximum time - the controller temporarily stops processing commands to activate - the firmware image, specified in 100 millisecond units. This - field is always valid if the controller supports firmware - activation without a reset. - -``hmpre`` - Host Memory Buffer Preferred Size indicates the preferred size - that the host is requested to allocate for the Host Memory - Buffer feature in 4 KiB units. - -``hmmin`` - Host Memory Buffer Minimum Size indicates the minimum size that - the host is requested to allocate for the Host Memory Buffer - feature in 4 KiB units. - -``tnvmcap`` - Total NVM Capacity, the total NVM capacity in the NVM subsystem. - The value is in bytes. - -``unvmcap`` - Unallocated NVM Capacity, the unallocated NVM capacity in the - NVM subsystem. The value is in bytes. - -``rpmbs`` - Replay Protected Memory Block Support, see - :c:type:`enum nvme_id_ctrl_rpmbs `. - -``edstt`` - Extended Device Self-test Time, if Device Self-test command is - supported (see :c:type:`struct nvme_id_ctrl `.oacs, ``NVME_CTRL_OACS_SELF_TEST``), - then this field indicates the nominal amount of time in one - minute units that the controller takes to complete an extended - device self-test operation when in power state 0. - -``dsto`` - Device Self-test Options, see :c:type:`enum nvme_id_ctrl_dsto `. - -``fwug`` - Firmware Update Granularity indicates the granularity and - alignment requirement of the firmware image being updated by the - Firmware Image Download command. The value is reported in 4 KiB - units. A value of 0h indicates no information on granularity is - provided. A value of FFh indicates no restriction - -``kas`` - Keep Alive Support indicates the granularity of the Keep Alive - Timer in 100 millisecond units. - -``hctma`` - Host Controlled Thermal Management Attributes, see - :c:type:`enum nvme_id_ctrl_hctm `. - -``mntmt`` - Minimum Thermal Management Temperature indicates the minimum - temperature, in degrees Kelvin, that the host may request in the - Thermal Management Temperature 1 field and Thermal Management - Temperature 2 field of a Set Features command with the Feature - Identifier field set to ``NVME_FEAT_FID_HCTM``. - -``mxtmt`` - Maximum Thermal Management Temperature indicates the maximum - temperature, in degrees Kelvin, that the host may request in the - Thermal Management Temperature 1 field and Thermal Management - Temperature 2 field of the Set Features command with the Feature - Identifier set to ``NVME_FEAT_FID_HCTM``. - -``sanicap`` - Sanitize Capabilities, see :c:type:`enum nvme_id_ctrl_sanicap ` - -``hmminds`` - Host Memory Buffer Minimum Descriptor Entry Size indicates the - minimum usable size of a Host Memory Buffer Descriptor Entry in - 4 KiB units. - -``hmmaxd`` - Host Memory Maximum Descriptors Entries indicates the number of - usable Host Memory Buffer Descriptor Entries. - -``nsetidmax`` - NVM Set Identifier Maximum, defines the maximum value of a valid - NVM Set Identifier for any controller in the NVM subsystem. - -``endgidmax`` - Endurance Group Identifier Maximum, defines the maximum value of - a valid Endurance Group Identifier for any controller in the NVM - subsystem. - -``anatt`` - ANA Transition Time indicates the maximum amount of time, in - seconds, for a transition between ANA states or the maximum - amount of time, in seconds, that the controller reports the ANA - change state. - -``anacap`` - Asymmetric Namespace Access Capabilities, see - :c:type:`enum nvme_id_ctrl_anacap `. - -``anagrpmax`` - ANA Group Identifier Maximum indicates the maximum value of a - valid ANA Group Identifier for any controller in the NVM - subsystem. - -``nanagrpid`` - Number of ANA Group Identifiers indicates the number of ANA - groups supported by this controller. - -``pels`` - Persistent Event Log Size indicates the maximum reportable size - for the Persistent Event Log. - -``domainid`` - Domain Identifier indicates the identifier of the domain - that contains this controller. - -``rsvd358`` - Reserved - -``megcap`` - Max Endurance Group Capacity indicates the maximum capacity - of a single Endurance Group. - -``rsvd384`` - Reserved - -``sqes`` - Submission Queue Entry Size, see :c:type:`enum nvme_id_ctrl_sqes `. - -``cqes`` - Completion Queue Entry Size, see :c:type:`enum nvme_id_ctrl_cqes `. - -``maxcmd`` - Maximum Outstanding Commands indicates the maximum number of - commands that the controller processes at one time for a - particular queue. - -``nn`` - Number of Namespaces indicates the maximum value of a valid - nsid for the NVM subsystem. If the MNAN (:c:type:`struct nvme_id_ctrl `.mnan - field is cleared to 0h, then this field also indicates the - maximum number of namespaces supported by the NVM subsystem. - -``oncs`` - Optional NVM Command Support, see :c:type:`enum nvme_id_ctrl_oncs `. - -``fuses`` - Fused Operation Support, see :c:type:`enum nvme_id_ctrl_fuses `. - -``fna`` - Format NVM Attributes, see :c:type:`enum nvme_id_ctrl_fna `. - -``vwc`` - Volatile Write Cache, see :c:type:`enum nvme_id_ctrl_vwc `. - -``awun`` - Atomic Write Unit Normal indicates the size of the write - operation guaranteed to be written atomically to the NVM across - all namespaces with any supported namespace format during normal - operation. This field is specified in logical blocks and is a - 0's based value. - -``awupf`` - Atomic Write Unit Power Fail indicates the size of the write - operation guaranteed to be written atomically to the NVM across - all namespaces with any supported namespace format during a - power fail or error condition. This field is specified in - logical blocks and is a 0’s based value. - -``icsvscc`` - NVM Vendor Specific Command Configuration, see - :c:type:`enum nvme_id_ctrl_nvscc `. - -``nwpc`` - Namespace Write Protection Capabilities, see - :c:type:`enum nvme_id_ctrl_nwpc `. - -``acwu`` - Atomic Compare & Write Unit indicates the size of the write - operation guaranteed to be written atomically to the NVM across - all namespaces with any supported namespace format for a Compare - and Write fused operation. This field is specified in logical - blocks and is a 0’s based value. - -``ocfs`` - Optional Copy Formats Supported, each bit n means controller - supports Copy Format n. - -``sgls`` - SGL Support, see :c:type:`enum nvme_id_ctrl_sgls ` - -``mnan`` - Maximum Number of Allowed Namespaces indicates the maximum - number of namespaces supported by the NVM subsystem. - -``maxdna`` - Maximum Domain Namespace Attachments indicates the maximum - of the sum of the number of namespaces attached to each I/O - controller in the Domain. - -``maxcna`` - Maximum I/O Controller Namespace Attachments indicates the - maximum number of namespaces that are allowed to be attached to - this I/O controller. - -``rsvd564`` - Reserved - -``subnqn`` - NVM Subsystem NVMe Qualified Name, UTF-8 null terminated string - -``rsvd1024`` - Reserved - -``ioccsz`` - I/O Queue Command Capsule Supported Size, defines the maximum - I/O command capsule size in 16 byte units. - -``iorcsz`` - I/O Queue Response Capsule Supported Size, defines the maximum - I/O response capsule size in 16 byte units. - -``icdoff`` - In Capsule Data Offset, defines the offset where data starts - within a capsule. This value is applicable to I/O Queues only. - -``fcatt`` - Fabrics Controller Attributes, see :c:type:`enum nvme_id_ctrl_fcatt `. - -``msdbd`` - Maximum SGL Data Block Descriptors indicates the maximum - number of SGL Data Block or Keyed SGL Data Block descriptors - that a host is allowed to place in a capsule. A value of 0h - indicates no limit. - -``ofcs`` - Optional Fabric Commands Support, see :c:type:`enum nvme_id_ctrl_ofcs `. - -``dctype`` - Discovery Controller Type (DCTYPE). This field indicates what - type of Discovery controller the controller is (see enum - nvme_id_ctrl_dctype) - -``rsvd1807`` - Reserved - -``psd`` - Power State Descriptors, see :c:type:`struct nvme_id_psd `. - -``vs`` - Vendor Specific - - - - - -.. c:enum:: nvme_id_ctrl_cmic - - Controller Multipath IO and Namespace Sharing Capabilities of the controller and NVM subsystem. - -**Constants** - -``NVME_CTRL_CMIC_MULTI_PORT`` - If set, then the NVM subsystem may contain - more than one NVM subsystem port, otherwise - the NVM subsystem contains only a single - NVM subsystem port. - -``NVME_CTRL_CMIC_MULTI_CTRL`` - If set, then the NVM subsystem may contain - two or more controllers, otherwise the - NVM subsystem contains only a single - controller. An NVM subsystem that contains - multiple controllers may be used by - multiple hosts, or may provide multiple - paths for a single host. - -``NVME_CTRL_CMIC_MULTI_SRIOV`` - If set, then the controller is associated - with an SR-IOV Virtual Function, otherwise - it is associated with a PCI Function - or a Fabrics connection. - -``NVME_CTRL_CMIC_MULTI_ANA_REPORTING`` - If set, then the NVM subsystem supports - Asymmetric Namespace Access Reporting. - - - - -.. c:enum:: nvme_id_ctrl_oaes - - Optional Asynchronous Events Supported - -**Constants** - -``NVME_CTRL_OAES_NA`` - Namespace Attribute Notices event supported - -``NVME_CTRL_OAES_FA`` - Firmware Activation Notices event supported - -``NVME_CTRL_OAES_ANA`` - ANA Change Notices supported - -``NVME_CTRL_OAES_PLEA`` - Predictable Latency Event Aggregate Log - Change Notices event supported - -``NVME_CTRL_OAES_LBAS`` - LBA Status Information Notices event supported - -``NVME_CTRL_OAES_EGE`` - Endurance Group Events Aggregate Log Change - Notices event supported - -``NVME_CTRL_OAES_NS`` - Normal NVM Subsystem Shutdown event supported - -``NVME_CTRL_OAES_ZD`` - Zone Descriptor Change Notifications supported - -``NVME_CTRL_OAES_DL`` - Discover Log Page Change Notifications supported - - - - -.. c:enum:: nvme_id_ctrl_ctratt - - Controller attributes - -**Constants** - -``NVME_CTRL_CTRATT_128_ID`` - 128-bit Host Identifier supported - -``NVME_CTRL_CTRATT_NON_OP_PSP`` - Non-Operational Poser State Permissive Mode - supported - -``NVME_CTRL_CTRATT_NVM_SETS`` - NVM Sets supported - -``NVME_CTRL_CTRATT_READ_RECV_LVLS`` - Read Recovery Levels supported - -``NVME_CTRL_CTRATT_ENDURANCE_GROUPS`` - Endurance Groups supported - -``NVME_CTRL_CTRATT_PREDICTABLE_LAT`` - Predictable Latency Mode supported - -``NVME_CTRL_CTRATT_TBKAS`` - Traffic Based Keep Alive Support - -``NVME_CTRL_CTRATT_NAMESPACE_GRANULARITY`` - Namespace Granularity reporting - supported - -``NVME_CTRL_CTRATT_SQ_ASSOCIATIONS`` - SQ Associations supported - -``NVME_CTRL_CTRATT_UUID_LIST`` - UUID List reporting supported - -``NVME_CTRL_CTRATT_MDS`` - Multi-Domain Subsystem supported - -``NVME_CTRL_CTRATT_FIXED_CAP`` - Fixed Capacity Management supported - -``NVME_CTRL_CTRATT_VARIABLE_CAP`` - Variable Capacity Management supported - -``NVME_CTRL_CTRATT_DEL_ENDURANCE_GROUPS`` - Delete Endurance Groups supported - -``NVME_CTRL_CTRATT_DEL_NVM_SETS`` - Delete NVM Sets supported - -``NVME_CTRL_CTRATT_ELBAS`` - Extended LBA Formats supported - - - - -.. c:enum:: nvme_id_ctrl_cntrltype - - Controller types - -**Constants** - -``NVME_CTRL_CNTRLTYPE_IO`` - NVM I/O controller - -``NVME_CTRL_CNTRLTYPE_DISCOVERY`` - Discovery controller - -``NVME_CTRL_CNTRLTYPE_ADMIN`` - Admin controller - - - - -.. c:enum:: nvme_id_ctrl_dctype - - Discovery Controller types - -**Constants** - -``NVME_CTRL_DCTYPE_NOT_REPORTED`` - Not reported (I/O, Admin, and pre-TP8010) - -``NVME_CTRL_DCTYPE_DDC`` - Direct Discovery controller - -``NVME_CTRL_DCTYPE_CDC`` - Central Discovery controller - - - - -.. c:enum:: nvme_id_ctrl_nvmsr - - This field reports information associated with the NVM Subsystem, see :c:type:`struct nvme_id_ctrl `.nvmsr. - -**Constants** - -``NVME_CTRL_NVMSR_NVMESD`` - If set, then the NVM Subsystem is part of an NVMe - Storage Device; if cleared, then the NVM Subsystem - is not part of an NVMe Storage Device. - -``NVME_CTRL_NVMSR_NVMEE`` - If set’, then the NVM Subsystem is part of an NVMe - Enclosure; if cleared, then the NVM Subsystem is - not part of an NVMe Enclosure. - - - - -.. c:enum:: nvme_id_ctrl_vwci - - This field indicates information about remaining number of times that VPD contents are able to be updated using the VPD Write command, see :c:type:`struct nvme_id_ctrl `.vwci. - -**Constants** - -``NVME_CTRL_VWCI_VWCR`` - Mask to get value of VPD Write Cycles Remaining. If - the VPD Write Cycle Remaining Valid bit is set, then - this field contains a value indicating the remaining - number of times that VPD contents are able to be - updated using the VPD Write command. If this field is - set to 7Fh, then the remaining number of times that - VPD contents are able to be updated using the VPD - Write command is greater than or equal to 7Fh. - -``NVME_CTRL_VWCI_VWCRV`` - VPD Write Cycle Remaining Valid. If this bit is set, - then the VPD Write Cycle Remaining field is valid. If - this bit is cleared, then the VPD Write Cycles - Remaining field is invalid and cleared to 0h. - - - - -.. c:enum:: nvme_id_ctrl_mec - - Flags indicating the capabilities of the Management Endpoint in the Controller, :c:type:`struct nvme_id_ctrl `.mec. - -**Constants** - -``NVME_CTRL_MEC_SMBUSME`` - If set, then the NVM Subsystem contains a Management - Endpoint on an SMBus/I2C port. - -``NVME_CTRL_MEC_PCIEME`` - If set, then the NVM Subsystem contains a Management - Endpoint on a PCIe port. - - - - -.. c:enum:: nvme_id_ctrl_oacs - - Flags indicating the optional Admin commands and features supported by the controller, see :c:type:`struct nvme_id_ctrl `.oacs. - -**Constants** - -``NVME_CTRL_OACS_SECURITY`` - If set, then the controller supports the - Security Send and Security Receive commands. - -``NVME_CTRL_OACS_FORMAT`` - If set then the controller supports the Format - NVM command. - -``NVME_CTRL_OACS_FW`` - If set, then the controller supports the - Firmware Commit and Firmware Image Download commands. - -``NVME_CTRL_OACS_NS_MGMT`` - If set, then the controller supports the - Namespace Management capability - -``NVME_CTRL_OACS_SELF_TEST`` - If set, then the controller supports the Device - Self-test command. - -``NVME_CTRL_OACS_DIRECTIVES`` - If set, then the controller supports Directives - and the Directive Send and Directive Receive - commands. - -``NVME_CTRL_OACS_NVME_MI`` - If set, then the controller supports the NVMe-MI - Send and NVMe-MI Receive commands. - -``NVME_CTRL_OACS_VIRT_MGMT`` - If set, then the controller supports the - Virtualization Management command. - -``NVME_CTRL_OACS_DBBUF_CFG`` - If set, then the controller supports the - Doorbell Buffer Config command. - -``NVME_CTRL_OACS_LBA_STATUS`` - If set, then the controller supports the Get LBA - Status capability. - -``NVME_CTRL_OACS_CMD_FEAT_LD`` - If set, then the controller supports the command - and feature lockdown capability. - - - - -.. c:enum:: nvme_id_ctrl_frmw - - Flags and values indicates capabilities regarding firmware updates from :c:type:`struct nvme_id_ctrl `.frmw. - -**Constants** - -``NVME_CTRL_FRMW_1ST_RO`` - If set, the first firmware slot is readonly - -``NVME_CTRL_FRMW_NR_SLOTS`` - Mask to get the value of the number of - firmware slots that the controller supports. - -``NVME_CTRL_FRMW_FW_ACT_NO_RESET`` - If set, the controller supports firmware - activation without a reset. - -``NVME_CTRL_FRMW_MP_UP_DETECTION`` - If set, the controller is able to detect - overlapping firmware/boot partition - image update. - - - - -.. c:enum:: nvme_id_ctrl_lpa - - Flags indicating optional attributes for log pages that are accessed via the Get Log Page command. - -**Constants** - -``NVME_CTRL_LPA_SMART_PER_NS`` - If set, controller supports SMART/Health log - page on a per namespace basis. - -``NVME_CTRL_LPA_CMD_EFFECTS`` - If Set, the controller supports the commands - supported and effects log page. - -``NVME_CTRL_LPA_EXTENDED`` - If set, the controller supports extended data - for log page command including extended number - of dwords and log page offset fields. - -``NVME_CTRL_LPA_TELEMETRY`` - If set, the controller supports the telemetry - host-initiated and telemetry controller-initiated - log pages and sending telemetry log notices. - -``NVME_CTRL_LPA_PERSETENT_EVENT`` - If set, the controller supports - persistent event log. - -``NVME_CTRL_LPA_LI0_LI5_LI12_LI13`` - If set, the controller supports - - log pages log page. - - returning scope of each command in - commands supported and effects log - page. - - feature identifiers supported and - effects log page. - - NVMe-MI commands supported and - effects log page. - -``NVME_CTRL_LPA_DA4_TELEMETRY`` - If set, the controller supports data - area 4 for telemetry host-initiated and - telemetry. - - - - -.. c:enum:: nvme_id_ctrl_avscc - - Flags indicating the configuration settings for Admin Vendor Specific command handling. - -**Constants** - -``NVME_CTRL_AVSCC_AVS`` - If set, all Admin Vendor Specific Commands use the - optional vendor specific command format with NDT and - NDM fields. - - - - -.. c:enum:: nvme_id_ctrl_apsta - - Flags indicating the attributes of the autonomous power state transition feature. - -**Constants** - -``NVME_CTRL_APSTA_APST`` - If set, then the controller supports autonomous power - state transitions. - - - - -.. c:enum:: nvme_id_ctrl_rpmbs - - This field indicates if the controller supports one or more Replay Protected Memory Blocks, from :c:type:`struct nvme_id_ctrl `.rpmbs. - -**Constants** - -``NVME_CTRL_RPMBS_NR_UNITS`` - Mask to get the value of the Number of RPMB Units - -``NVME_CTRL_RPMBS_AUTH_METHOD`` - Mask to get the value of the Authentication Method - -``NVME_CTRL_RPMBS_TOTAL_SIZE`` - Mask to get the value of Total Size - -``NVME_CTRL_RPMBS_ACCESS_SIZE`` - Mask to get the value of Access Size - - - - -.. c:enum:: nvme_id_ctrl_dsto - - Flags indicating the optional Device Self-test command or operation behaviors supported by the controller or NVM subsystem. - -**Constants** - -``NVME_CTRL_DSTO_ONE_DST`` - If set, then the NVM subsystem supports only one - device self-test operation in progress at a time. - - - - -.. c:enum:: nvme_id_ctrl_hctm - - Flags indicate the attributes of the host controlled thermal management feature - -**Constants** - -``NVME_CTRL_HCTMA_HCTM`` - then the controller supports host controlled thermal - management, and the Set Features command and Get - Features command with the Feature Identifier field - set to ``NVME_FEAT_FID_HCTM``. - - - - -.. c:enum:: nvme_id_ctrl_sanicap - - Indicates attributes for sanitize operations. - -**Constants** - -``NVME_CTRL_SANICAP_CES`` - Crypto Erase Support. If set, then the - controller supports the Crypto Erase sanitize operation. - -``NVME_CTRL_SANICAP_BES`` - Block Erase Support. If set, then the controller - supports the Block Erase sanitize operation. - -``NVME_CTRL_SANICAP_OWS`` - Overwrite Support. If set, then the controller - supports the Overwrite sanitize operation. - -``NVME_CTRL_SANICAP_NDI`` - No-Deallocate Inhibited. If set and the No- - Deallocate Response Mode bit is set, then the - controller deallocates after the sanitize - operation even if the No-Deallocate After - Sanitize bit is set in a Sanitize command. - -``NVME_CTRL_SANICAP_NODMMAS`` - No-Deallocate Modifies Media After Sanitize, - mask to extract value. - - - - -.. c:enum:: nvme_id_ctrl_anacap - - This field indicates the capabilities associated with Asymmetric Namespace Access Reporting. - -**Constants** - -``NVME_CTRL_ANACAP_OPT`` - If set, then the controller is able to - report ANA Optimized state. - -``NVME_CTRL_ANACAP_NON_OPT`` - If set, then the controller is able to - report ANA Non-Optimized state. - -``NVME_CTRL_ANACAP_INACCESSIBLE`` - If set, then the controller is able to - report ANA Inaccessible state. - -``NVME_CTRL_ANACAP_PERSISTENT_LOSS`` - If set, then the controller is able to - report ANA Persistent Loss state. - -``NVME_CTRL_ANACAP_CHANGE`` - If set, then the controller is able to - report ANA Change state. - -``NVME_CTRL_ANACAP_GRPID_NO_CHG`` - If set, then the ANAGRPID field in the - Identify Namespace data structure - (:c:type:`struct nvme_id_ns `.anagrpid), does not - change while the namespace is attached to - any controller. - -``NVME_CTRL_ANACAP_GRPID_MGMT`` - If set, then the controller supports a - non-zero value in the ANAGRPID field of - the Namespace Management command. - - - - -.. c:enum:: nvme_id_ctrl_sqes - - Defines the required and maximum Submission Queue entry size when using the NVM Command Set. - -**Constants** - -``NVME_CTRL_SQES_MIN`` - Mask to get the value of the required Submission Queue - Entry size when using the NVM Command Set. - -``NVME_CTRL_SQES_MAX`` - Mask to get the value of the maximum Submission Queue - entry size when using the NVM Command Set. - - - - -.. c:enum:: nvme_id_ctrl_cqes - - Defines the required and maximum Completion Queue entry size when using the NVM Command Set. - -**Constants** - -``NVME_CTRL_CQES_MIN`` - Mask to get the value of the required Completion Queue - Entry size when using the NVM Command Set. - -``NVME_CTRL_CQES_MAX`` - Mask to get the value of the maximum Completion Queue - entry size when using the NVM Command Set. - - - - -.. c:enum:: nvme_id_ctrl_oncs - - This field indicates the optional NVM commands and features supported by the controller. - -**Constants** - -``NVME_CTRL_ONCS_COMPARE`` - If set, then the controller supports - the Compare command. - -``NVME_CTRL_ONCS_WRITE_UNCORRECTABLE`` - If set, then the controller supports - the Write Uncorrectable command. - -``NVME_CTRL_ONCS_DSM`` - If set, then the controller supports - the Dataset Management command. - -``NVME_CTRL_ONCS_WRITE_ZEROES`` - If set, then the controller supports - the Write Zeroes command. - -``NVME_CTRL_ONCS_SAVE_FEATURES`` - If set, then the controller supports - the Save field set to a non-zero value - in the Set Features command and the - Select field set to a non-zero value in - the Get Features command. - -``NVME_CTRL_ONCS_RESERVATIONS`` - If set, then the controller supports - reservations. - -``NVME_CTRL_ONCS_TIMESTAMP`` - If set, then the controller supports - the Timestamp feature. - -``NVME_CTRL_ONCS_VERIFY`` - If set, then the controller supports - the Verify command. - -``NVME_CTRL_ONCS_COPY`` - If set, then the controller supports - the copy command. - - - - -.. c:enum:: nvme_id_ctrl_fuses - - This field indicates the fused operations that the controller supports. - -**Constants** - -``NVME_CTRL_FUSES_COMPARE_AND_WRITE`` - If set, then the controller supports the - Compare and Write fused operation. - - - - -.. c:enum:: nvme_id_ctrl_fna - - This field indicates attributes for the Format NVM command. - -**Constants** - -``NVME_CTRL_FNA_FMT_ALL_NAMESPACES`` - If set, then all namespaces in an NVM - subsystem shall be configured with the - same attributes and a format (excluding - secure erase) of any namespace results in - a format of all namespaces in an NVM - subsystem. If cleared, then the - controller supports format on a per - namespace basis. - -``NVME_CTRL_FNA_SEC_ALL_NAMESPACES`` - If set, then any secure erase performed - as part of a format operation results in - a secure erase of all namespaces in the - NVM subsystem. If cleared, then any - secure erase performed as part of a - format results in a secure erase of the - particular namespace specified. - -``NVME_CTRL_FNA_CRYPTO_ERASE`` - If set, then cryptographic erase is - supported. If cleared, then cryptographic - erase is not supported. - -``NVME_CTRL_FNA_NSID_FFFFFFFF`` - If set, then format does not support - nsid value set to FFFFFFFFh. If cleared, - format supports nsid value set to - FFFFFFFFh. - - - - -.. c:enum:: nvme_id_ctrl_vwc - - Volatile write cache - -**Constants** - -``NVME_CTRL_VWC_PRESENT`` - If set, indicates a volatile write cache is present. - If a volatile write cache is present, then the host - controls whether the volatile write cache is enabled - with a Set Features command specifying the value - ``NVME_FEAT_FID_VOLATILE_WC``. - -``NVME_CTRL_VWC_FLUSH`` - Mask to get the value of the flush command behavior. - - - - -.. c:enum:: nvme_id_ctrl_nvscc - - This field indicates the configuration settings for NVM Vendor Specific command handling. - -**Constants** - -``NVME_CTRL_NVSCC_FMT`` - If set, all NVM Vendor Specific Commands use the - format with NDT and NDM fields. - - - - -.. c:enum:: nvme_id_ctrl_nwpc - - This field indicates the optional namespace write protection capabilities supported by the controller. - -**Constants** - -``NVME_CTRL_NWPC_WRITE_PROTECT`` - If set, then the controller shall - support the No Write Protect and - Write Protect namespace write - protection states and may support - the Write Protect Until Power - Cycle state and Permanent Write - Protect namespace write - protection states. - -``NVME_CTRL_NWPC_WRITE_PROTECT_POWER_CYCLE`` - If set, then the controller - supports the Write Protect Until - Power Cycle state. - -``NVME_CTRL_NWPC_WRITE_PROTECT_PERMANENT`` - If set, then the controller - supports the Permanent Write - Protect state. - - - - -.. c:enum:: nvme_id_ctrl_sgls - - This field indicates if SGLs are supported for the NVM Command Set and the particular SGL types supported. - -**Constants** - -``NVME_CTRL_SGLS_SUPPORTED`` - -``NVME_CTRL_SGLS_KEYED`` - -``NVME_CTRL_SGLS_BIT_BUCKET`` - -``NVME_CTRL_SGLS_MPTR_BYTE_ALIGNED`` - -``NVME_CTRL_SGLS_OVERSIZE`` - -``NVME_CTRL_SGLS_MPTR_SGL`` - -``NVME_CTRL_SGLS_OFFSET`` - -``NVME_CTRL_SGLS_TPORT`` - - - - -.. c:enum:: nvme_id_ctrl_fcatt - - This field indicates attributes of the controller that are specific to NVMe over Fabrics. - -**Constants** - -``NVME_CTRL_FCATT_DYNAMIC`` - If cleared, then the NVM subsystem uses a dynamic - controller model. If set, then the NVM subsystem - uses a static controller model. - - - - -.. c:enum:: nvme_id_ctrl_ofcs - - Indicate whether the controller supports optional fabric commands. - -**Constants** - -``NVME_CTRL_OFCS_DISCONNECT`` - If set, then the controller supports the - Disconnect command and deletion of individual - I/O Queues. - - - - -.. c:struct:: nvme_lbaf - - LBA Format Data Structure - -**Definition** - -:: - - struct nvme_lbaf { - __le16 ms; - __u8 ds; - __u8 rp; - }; - -**Members** - -``ms`` - Metadata Size indicates the number of metadata bytes provided per LBA - based on the LBA Data Size indicated. - -``ds`` - LBA Data Size indicates the LBA data size supported, reported as a - power of two. - -``rp`` - Relative Performance, see :c:type:`enum nvme_lbaf_rp `. - - - - - -.. c:enum:: nvme_lbaf_rp - - This field indicates the relative performance of the LBA format indicated relative to other LBA formats supported by the controller. - -**Constants** - -``NVME_LBAF_RP_BEST`` - Best performance - -``NVME_LBAF_RP_BETTER`` - Better performance - -``NVME_LBAF_RP_GOOD`` - Good performance - -``NVME_LBAF_RP_DEGRADED`` - Degraded performance - -``NVME_LBAF_RP_MASK`` - Mask to get the relative performance value from the - field - - - - -.. c:struct:: nvme_id_ns - - Identify Namespace data structure - -**Definition** - -:: - - struct nvme_id_ns { - __le64 nsze; - __le64 ncap; - __le64 nuse; - __u8 nsfeat; - __u8 nlbaf; - __u8 flbas; - __u8 mc; - __u8 dpc; - __u8 dps; - __u8 nmic; - __u8 rescap; - __u8 fpi; - __u8 dlfeat; - __le16 nawun; - __le16 nawupf; - __le16 nacwu; - __le16 nabsn; - __le16 nabo; - __le16 nabspf; - __le16 noiob; - __u8 nvmcap[16]; - __le16 npwg; - __le16 npwa; - __le16 npdg; - __le16 npda; - __le16 nows; - __le16 mssrl; - __le32 mcl; - __u8 msrc; - __u8 rsvd81; - __u8 nulbaf; - __u8 rsvd83[9]; - __le32 anagrpid; - __u8 rsvd96[3]; - __u8 nsattr; - __le16 nvmsetid; - __le16 endgid; - __u8 nguid[16]; - __u8 eui64[8]; - struct nvme_lbaf lbaf[64]; - __le64 lbstm; - __u8 vs[3704]; - }; - -**Members** - -``nsze`` - Namespace Size indicates the total size of the namespace in - logical blocks. The number of logical blocks is based on the - formatted LBA size. - -``ncap`` - Namespace Capacity indicates the maximum number of logical blocks - that may be allocated in the namespace at any point in time. The - number of logical blocks is based on the formatted LBA size. - -``nuse`` - Namespace Utilization indicates the current number of logical - blocks allocated in the namespace. This field is smaller than or - equal to the Namespace Capacity. The number of logical blocks is - based on the formatted LBA size. - -``nsfeat`` - Namespace Features, see :c:type:`enum nvme_id_nsfeat `. - -``nlbaf`` - Number of LBA Formats defines the number of supported LBA data - size and metadata size combinations supported by the namespace - and the highest possible index to :c:type:`struct nvme_id_ns `.lbaf. - -``flbas`` - Formatted LBA Size, see :c:type:`enum nvme_id_ns_flbas `. - -``mc`` - Metadata Capabilities, see :c:type:`enum nvme_id_ns_mc `. - -``dpc`` - End-to-end Data Protection Capabilities, see - :c:type:`enum nvme_id_ns_dpc `. - -``dps`` - End-to-end Data Protection Type Settings, see - :c:type:`enum nvme_id_ns_dps `. - -``nmic`` - Namespace Multi-path I/O and Namespace Sharing Capabilities, see - :c:type:`enum nvme_id_ns_nmic `. - -``rescap`` - Reservation Capabilities, see :c:type:`enum nvme_id_ns_rescap `. - -``fpi`` - Format Progress Indicator, see :c:type:`enum nvme_nd_ns_fpi `. - -``dlfeat`` - Deallocate Logical Block Features, see :c:type:`enum nvme_id_ns_dlfeat `. - -``nawun`` - Namespace Atomic Write Unit Normal indicates the - namespace specific size of the write operation guaranteed to be - written atomically to the NVM during normal operation. - -``nawupf`` - Namespace Atomic Write Unit Power Fail indicates the - namespace specific size of the write operation guaranteed to be - written atomically to the NVM during a power fail or error - condition. - -``nacwu`` - Namespace Atomic Compare & Write Unit indicates the namespace - specific size of the write operation guaranteed to be written - atomically to the NVM for a Compare and Write fused command. - -``nabsn`` - Namespace Atomic Boundary Size Normal indicates the atomic - boundary size for this namespace for the NAWUN value. This field - is specified in logical blocks. - -``nabo`` - Namespace Atomic Boundary Offset indicates the LBA on this - namespace where the first atomic boundary starts. - -``nabspf`` - Namespace Atomic Boundary Size Power Fail indicates the atomic - boundary size for this namespace specific to the Namespace Atomic - Write Unit Power Fail value. This field is specified in logical - blocks. - -``noiob`` - Namespace Optimal I/O Boundary indicates the optimal I/O boundary - for this namespace. This field is specified in logical blocks. - The host should construct Read and Write commands that do not - cross the I/O boundary to achieve optimal performance. - -``nvmcap`` - NVM Capacity indicates the total size of the NVM allocated to - this namespace. The value is in bytes. - -``npwg`` - Namespace Preferred Write Granularity indicates the smallest - recommended write granularity in logical blocks for this - namespace. This is a 0's based value. - -``npwa`` - Namespace Preferred Write Alignment indicates the recommended - write alignment in logical blocks for this namespace. This is a - 0's based value. - -``npdg`` - Namespace Preferred Deallocate Granularity indicates the - recommended granularity in logical blocks for the Dataset - Management command with the Attribute - Deallocate bit. - -``npda`` - Namespace Preferred Deallocate Alignment indicates the - recommended alignment in logical blocks for the Dataset - Management command with the Attribute - Deallocate bit - -``nows`` - Namespace Optimal Write Size indicates the size in logical blocks - for optimal write performance for this namespace. This is a 0's - based value. - -``mssrl`` - Maximum Single Source Range Length indicates the maximum number - of logical blocks that may be specified in each valid Source Range - field of a Copy command. - -``mcl`` - Maximum Copy Length indicates the maximum number of logical - blocks that may be specified in a Copy command. - -``msrc`` - Maximum Source Range Count indicates the maximum number of Source - Range entries that may be used to specify source data in a Copy - command. This is a 0’s based value. - -``rsvd81`` - Reserved - -``nulbaf`` - Number of Unique Capability LBA Formats defines the number of - supported user data size and metadata size combinations supported - by the namespace that may not share the same capabilities. LBA - formats shall be allocated in order and packed sequentially. - -``rsvd83`` - Reserved - -``anagrpid`` - ANA Group Identifier indicates the ANA Group Identifier of the - ANA group of which the namespace is a member. - -``rsvd96`` - Reserved - -``nsattr`` - Namespace Attributes, see :c:type:`enum nvme_id_ns_attr `. - -``nvmsetid`` - NVM Set Identifier indicates the NVM Set with which this - namespace is associated. - -``endgid`` - Endurance Group Identifier indicates the Endurance Group with - which this namespace is associated. - -``nguid`` - Namespace Globally Unique Identifier contains a 128-bit value - that is globally unique and assigned to the namespace when the - namespace is created. This field remains fixed throughout the - life of the namespace and is preserved across namespace and - controller operations - -``eui64`` - IEEE Extended Unique Identifier contains a 64-bit IEEE Extended - Unique Identifier (EUI-64) that is globally unique and assigned - to the namespace when the namespace is created. This field - remains fixed throughout the life of the namespace and is - preserved across namespace and controller operations - -``lbaf`` - LBA Format, see :c:type:`struct nvme_lbaf `. - -``lbstm`` - Logical Block Storage Tag Mask for end-to-end protection - -``vs`` - Vendor Specific - - - - - -.. c:enum:: nvme_id_nsfeat - - This field defines features of the namespace. - -**Constants** - -``NVME_NS_FEAT_THIN`` - If set, indicates that the namespace supports thin - provisioning. Specifically, the Namespace Capacity - reported may be less than the Namespace Size. - -``NVME_NS_FEAT_NATOMIC`` - If set, indicates that the fields NAWUN, NAWUPF, and - NACWU are defined for this namespace and should be - used by the host for this namespace instead of the - AWUN, AWUPF, and ACWU fields in the Identify - Controller data structure. - -``NVME_NS_FEAT_DULBE`` - If set, indicates that the controller supports the - Deallocated or Unwritten Logical Block error for - this namespace. - -``NVME_NS_FEAT_ID_REUSE`` - If set, indicates that the value in the NGUID field - for this namespace, if non- zero, is never reused by - the controller and that the value in the EUI64 field - for this namespace, if non-zero, is never reused by - the controller. - -``NVME_NS_FEAT_IO_OPT`` - If set, indicates that the fields NPWG, NPWA, NPDG, - NPDA, and NOWS are defined for this namespace and - should be used by the host for I/O optimization - - - - -.. c:enum:: nvme_id_ns_flbas - - This field indicates the LBA data size & metadata size combination that the namespace has been formatted with - -**Constants** - -``NVME_NS_FLBAS_LOWER_MASK`` - Mask to get the index of one of the supported - LBA Formats's least significant - 4bits indicated in - :c:type:`struct nvme_id_ns `.lbaf. - -``NVME_NS_FLBAS_META_EXT`` - Applicable only if format contains metadata. If - this bit is set, indicates that the metadata is - transferred at the end of the data LBA, creating an - extended data LBA. If cleared, indicates that all - of the metadata for a command is transferred as a - separate contiguous buffer of data. - -``NVME_NS_FLBAS_HIGHER_MASK`` - Mask to get the index of one of - the supported LBA Formats's most significant - 2bits indicated in - :c:type:`struct nvme_id_ns `.lbaf. - - - - -.. c:enum:: nvme_nvm_id_ns_elbaf - - This field indicates the extended LBA format - -**Constants** - -``NVME_NVM_ELBAF_STS_MASK`` - Mask to get the storage tag size used to determine - the variable-sized storage tag/reference tag fields - -``NVME_NVM_ELBAF_PIF_MASK`` - Mask to get the protection information format for - the extended LBA format. - - - - -.. c:enum:: nvme_id_ns_mc - - This field indicates the capabilities for metadata. - -**Constants** - -``NVME_NS_MC_EXTENDED`` - If set, indicates the namespace supports the metadata - being transferred as part of a separate buffer that is - specified in the Metadata Pointer. - -``NVME_NS_MC_SEPARATE`` - If set, indicates that the namespace supports the - metadata being transferred as part of an extended data LBA. - - - - -.. c:enum:: nvme_id_ns_dpc - - This field indicates the capabilities for the end-to-end data protection feature. - -**Constants** - -``NVME_NS_DPC_PI_TYPE1`` - If set, indicates that the namespace supports - Protection Information Type 1. - -``NVME_NS_DPC_PI_TYPE2`` - If set, indicates that the namespace supports - Protection Information Type 2. - -``NVME_NS_DPC_PI_TYPE3`` - If set, indicates that the namespace supports - Protection Information Type 3. - -``NVME_NS_DPC_PI_FIRST`` - If set, indicates that the namespace supports - protection information transferred as the first eight - bytes of metadata. - -``NVME_NS_DPC_PI_LAST`` - If set, indicates that the namespace supports - protection information transferred as the last eight - bytes of metadata. - - - - -.. c:enum:: nvme_id_ns_dps - - This field indicates the Type settings for the end-to-end data protection feature. - -**Constants** - -``NVME_NS_DPS_PI_NONE`` - Protection information is not enabled - -``NVME_NS_DPS_PI_TYPE1`` - Protection information is enabled, Type 1 - -``NVME_NS_DPS_PI_TYPE2`` - Protection information is enabled, Type 2 - -``NVME_NS_DPS_PI_TYPE3`` - Protection information is enabled, Type 3 - -``NVME_NS_DPS_PI_MASK`` - Mask to get the value of the PI type - -``NVME_NS_DPS_PI_FIRST`` - If set, indicates that the protection information, if - enabled, is transferred as the first eight bytes of - metadata. - - - - -.. c:enum:: nvme_id_ns_nmic - - This field specifies multi-path I/O and namespace sharing capabilities of the namespace. - -**Constants** - -``NVME_NS_NMIC_SHARED`` - If set, then the namespace may be attached to two or - more controllers in the NVM subsystem concurrently - - - - -.. c:enum:: nvme_id_ns_rescap - - This field indicates the reservation capabilities of the namespace. - -**Constants** - -``NVME_NS_RESCAP_PTPL`` - If set, indicates that the namespace supports the - Persist Through Power Loss capability. - -``NVME_NS_RESCAP_WE`` - If set, indicates that the namespace supports the - Write Exclusive reservation type. - -``NVME_NS_RESCAP_EA`` - If set, indicates that the namespace supports the - Exclusive Access reservation type. - -``NVME_NS_RESCAP_WERO`` - If set, indicates that the namespace supports the - Write Exclusive - Registrants Only reservation type. - -``NVME_NS_RESCAP_EARO`` - If set, indicates that the namespace supports the - Exclusive Access - Registrants Only reservation type. - -``NVME_NS_RESCAP_WEAR`` - If set, indicates that the namespace supports the - Write Exclusive - All Registrants reservation type. - -``NVME_NS_RESCAP_EAAR`` - If set, indicates that the namespace supports the - Exclusive Access - All Registrants reservation type. - -``NVME_NS_RESCAP_IEK_13`` - If set, indicates that Ignore Existing Key is used - as defined in revision 1.3 or later of this specification. - - - - -.. c:enum:: nvme_nd_ns_fpi - - If a format operation is in progress, this field indicates the percentage of the namespace that remains to be formatted. - -**Constants** - -``NVME_NS_FPI_REMAINING`` - Mask to get the format percent remaining value - -``NVME_NS_FPI_SUPPORTED`` - If set, indicates that the namespace supports the - Format Progress Indicator defined for the field. - - - - -.. c:enum:: nvme_id_ns_dlfeat - - This field indicates information about features that affect deallocating logical blocks for this namespace. - -**Constants** - -``NVME_NS_DLFEAT_RB`` - Mask to get the value of the read behavior - -``NVME_NS_DLFEAT_RB_NR`` - Read behvaior is not reported - -``NVME_NS_DLFEAT_RB_ALL_0S`` - A deallocated logical block returns all bytes - cleared to 0h. - -``NVME_NS_DLFEAT_RB_ALL_FS`` - A deallocated logical block returns all bytes - set to FFh. - -``NVME_NS_DLFEAT_WRITE_ZEROES`` - If set, indicates that the controller supports - the Deallocate bit in the Write Zeroes command - for this namespace. - -``NVME_NS_DLFEAT_CRC_GUARD`` - If set, indicates that the Guard field for - deallocated logical blocks that contain - protection information is set to the CRC for - the value read from the deallocated logical - block and its metadata - - - - -.. c:enum:: nvme_id_ns_attr - - Specifies attributes of the namespace. - -**Constants** - -``NVME_NS_NSATTR_WRITE_PROTECTED`` - If set, then the namespace is currently - write protected and all write access to the - namespace shall fail. - - - - -.. c:struct:: nvme_ns_id_desc - - Namespace identifier type descriptor - -**Definition** - -:: - - struct nvme_ns_id_desc { - __u8 nidt; - __u8 nidl; - __le16 rsvd; - __u8 nid[]; - }; - -**Members** - -``nidt`` - Namespace Identifier Type, see :c:type:`enum nvme_ns_id_desc_nidt ` - -``nidl`` - Namespace Identifier Length contains the length in bytes of the - :c:type:`struct nvme_id_ns `.nid. - -``rsvd`` - Reserved - -``nid`` - Namespace Identifier contains a value that is globally unique and - assigned to the namespace when the namespace is created. The length - is defined in :c:type:`struct nvme_id_ns `.nidl. - - - - - -.. c:enum:: nvme_ns_id_desc_nidt - - Known namespace identifier types - -**Constants** - -``NVME_NIDT_EUI64`` - IEEE Extended Unique Identifier, the NID field contains a - copy of the EUI64 field in the struct nvme_id_ns.eui64. - -``NVME_NIDT_NGUID`` - Namespace Globally Unique Identifier, the NID field - contains a copy of the NGUID field in struct nvme_id_ns.nguid. - -``NVME_NIDT_UUID`` - The NID field contains a 128-bit Universally Unique - Identifier (UUID) as specified in RFC 4122. - -``NVME_NIDT_CSI`` - The NID field contains the command set identifier. - - - - -.. c:struct:: nvme_nvmset_attr - - NVM Set Attributes Entry - -**Definition** - -:: - - struct nvme_nvmset_attr { - __le16 nvmsetid; - __le16 endgid; - __u8 rsvd4[4]; - __le32 rr4kt; - __le32 ows; - __u8 tnvmsetcap[16]; - __u8 unvmsetcap[16]; - __u8 rsvd48[80]; - }; - -**Members** - -``nvmsetid`` - NVM Set Identifier - -``endgid`` - Endurance Group Identifier - -``rsvd4`` - Reserved - -``rr4kt`` - Random 4 KiB Read Typical indicates the typical - time to complete a 4 KiB random read in 100 nanosecond units - when the NVM Set is in a Predictable Latency Mode Deterministic - Window and there is 1 outstanding command per NVM Set. - -``ows`` - Optimal Write Size - -``tnvmsetcap`` - Total NVM Set Capacity - -``unvmsetcap`` - Unallocated NVM Set Capacity - -``rsvd48`` - Reserved - - - - - -.. c:struct:: nvme_id_nvmset_list - - NVM set list - -**Definition** - -:: - - struct nvme_id_nvmset_list { - __u8 nid; - __u8 rsvd1[127]; - struct nvme_nvmset_attr ent[NVME_ID_NVMSET_LIST_MAX]; - }; - -**Members** - -``nid`` - Nvmset id - -``rsvd1`` - Reserved - -``ent`` - nvmset id list - - - - - -.. c:struct:: nvme_id_independent_id_ns - - Identify - I/O Command Set Independent Identify Namespace Data Structure - -**Definition** - -:: - - struct nvme_id_independent_id_ns { - __u8 nsfeat; - __u8 nmic; - __u8 rescap; - __u8 fpi; - __le32 anagrpid; - __u8 nsattr; - __u8 rsvd9; - __le16 nvmsetid; - __le16 endgid; - __u8 nstat; - __u8 rsvd15[4081]; - }; - -**Members** - -``nsfeat`` - common namespace features - -``nmic`` - Namespace Multi-path I/O and Namespace - Sharing Capabilities - -``rescap`` - Reservation Capabilities - -``fpi`` - Format Progress Indicator - -``anagrpid`` - ANA Group Identifier - -``nsattr`` - Namespace Attributes - -``rsvd9`` - reserved - -``nvmsetid`` - NVM Set Identifier - -``endgid`` - Endurance Group Identifier - -``nstat`` - Namespace Status - -``rsvd15`` - reserved - - - - - -.. c:struct:: nvme_id_ns_granularity_desc - - Namespace Granularity Descriptor - -**Definition** - -:: - - struct nvme_id_ns_granularity_desc { - __le64 nszegran; - __le64 ncapgran; - }; - -**Members** - -``nszegran`` - Namespace Size Granularity - -``ncapgran`` - Namespace Capacity Granularity - - - - - -.. c:struct:: nvme_id_ns_granularity_list - - Namespace Granularity List - -**Definition** - -:: - - struct nvme_id_ns_granularity_list { - __le32 attributes; - __u8 num_descriptors; - __u8 rsvd5[27]; - struct nvme_id_ns_granularity_desc entry[NVME_ID_ND_DESCRIPTOR_MAX]; - __u8 rsvd288[3808]; - }; - -**Members** - -``attributes`` - Namespace Granularity Attributes - -``num_descriptors`` - Number of Descriptors - -``rsvd5`` - reserved - -``entry`` - Namespace Granularity Descriptor - -``rsvd288`` - reserved - - - - - -.. c:struct:: nvme_id_uuid_list_entry - - UUID List Entry - -**Definition** - -:: - - struct nvme_id_uuid_list_entry { - __u8 header; - __u8 rsvd1[15]; - __u8 uuid[16]; - }; - -**Members** - -``header`` - UUID Lists Entry Header - -``rsvd1`` - reserved - -``uuid`` - 128-bit Universally Unique Identifier - - - - - -.. c:enum:: nvme_id_uuid - - Identifier Association - -**Constants** - -``NVME_ID_UUID_HDR_ASSOCIATION_MASK`` - -``NVME_ID_UUID_ASSOCIATION_NONE`` - -``NVME_ID_UUID_ASSOCIATION_VENDOR`` - -``NVME_ID_UUID_ASSOCIATION_SUBSYSTEM_VENDOR`` - - - - -.. c:struct:: nvme_id_uuid_list - - UUID list - -**Definition** - -:: - - struct nvme_id_uuid_list { - __u8 rsvd0[32]; - struct nvme_id_uuid_list_entry entry[NVME_ID_UUID_LIST_MAX]; - }; - -**Members** - -``rsvd0`` - reserved - -``entry`` - UUID list entry - - - - - -.. c:struct:: nvme_ctrl_list - - Controller List - -**Definition** - -:: - - struct nvme_ctrl_list { - __le16 num; - __le16 identifier[NVME_ID_CTRL_LIST_MAX]; - }; - -**Members** - -``num`` - Number of Identifiers - -``identifier`` - NVM subsystem unique controller identifier - - - - - -.. c:struct:: nvme_ns_list - - Namespace List - -**Definition** - -:: - - struct nvme_ns_list { - __le32 ns[NVME_ID_NS_LIST_MAX]; - }; - -**Members** - -``ns`` - Namespace Identifier - - - - - -.. c:struct:: nvme_id_ctrl_nvm - - I/O Command Set Specific Identify Controller data structure - -**Definition** - -:: - - struct nvme_id_ctrl_nvm { - __u8 vsl; - __u8 wzsl; - __u8 wusl; - __u8 dmrl; - __u32 dmrsl; - __u64 dmsl; - __u8 rsvd16[4080]; - }; - -**Members** - -``vsl`` - Verify Size Limit - -``wzsl`` - Write Zeroes Size Limit - -``wusl`` - Write Uncorrectable Size Limit - -``dmrl`` - Dataset Management Ranges Limit - -``dmrsl`` - Dataset Management Range Size Limit - -``dmsl`` - Dataset Management Size Limit - -``rsvd16`` - reserved - - - - - -.. c:struct:: nvme_nvm_id_ns - - NVME Command Set I/O Command Set Specific Identify Namespace Data Structure - -**Definition** - -:: - - struct nvme_nvm_id_ns { - __le64 lbstm; - __u8 pic; - __u8 rsvd9[3]; - __le32 elbaf[64]; - __u8 rsvd268[3828]; - }; - -**Members** - -``lbstm`` - Logical Block Storage Tag Mask - -``pic`` - Protection Information Capabilities - -``rsvd9`` - Reserved - -``elbaf`` - List of Extended LBA Format Support - -``rsvd268`` - Reserved - - - - - -.. c:struct:: nvme_zns_lbafe - - LBA Format Extension Data Structure - -**Definition** - -:: - - struct nvme_zns_lbafe { - __le64 zsze; - __u8 zdes; - __u8 rsvd9[7]; - }; - -**Members** - -``zsze`` - Zone Size - -``zdes`` - Zone Descriptor Extension Size - -``rsvd9`` - reserved - - - - - -.. c:struct:: nvme_zns_id_ns - - Zoned Namespace Command Set Specific Identify Namespace Data Structure - -**Definition** - -:: - - struct nvme_zns_id_ns { - __le16 zoc; - __le16 ozcs; - __le32 mar; - __le32 mor; - __le32 rrl; - __le32 frl; - __le32 rrl1; - __le32 rrl2; - __le32 rrl3; - __le32 frl1; - __le32 frl2; - __le32 frl3; - __le32 numzrwa; - __le16 zrwafg; - __le16 zrwasz; - __u8 zrwacap; - __u8 rsvd53[2763]; - struct nvme_zns_lbafe lbafe[64]; - __u8 vs[256]; - }; - -**Members** - -``zoc`` - Zone Operation Characteristics - -``ozcs`` - Optional Zoned Command Support - -``mar`` - Maximum Active Resources - -``mor`` - Maximum Open Resources - -``rrl`` - Reset Recommended Limit - -``frl`` - Finish Recommended Limit - -``rrl1`` - Reset Recommended Limit 1 - -``rrl2`` - Reset Recommended Limit 2 - -``rrl3`` - Reset Recommended Limit 3 - -``frl1`` - Finish Recommended Limit 1 - -``frl2`` - Finish Recommended Limit 2 - -``frl3`` - Finish Recommended Limit 3 - -``numzrwa`` - Number of ZRWA Resources - -``zrwafg`` - ZRWA Flush Granularity - -``zrwasz`` - ZRWA Size - -``zrwacap`` - ZRWA Capability - -``rsvd53`` - Reserved - -``lbafe`` - LBA Format Extension - -``vs`` - Vendor Specific - - - - - -.. c:struct:: nvme_zns_id_ctrl - - I/O Command Set Specific Identify Controller Data Structure for the Zoned Namespace Command Set - -**Definition** - -:: - - struct nvme_zns_id_ctrl { - __u8 zasl; - __u8 rsvd1[4095]; - }; - -**Members** - -``zasl`` - Zone Append Size Limit - -``rsvd1`` - Reserved - - - - - -.. c:struct:: nvme_primary_ctrl_cap - - Identify - Controller Capabilities Structure - -**Definition** - -:: - - struct nvme_primary_ctrl_cap { - __le16 cntlid; - __le16 portid; - __u8 crt; - __u8 rsvd5[27]; - __le32 vqfrt; - __le32 vqrfa; - __le16 vqrfap; - __le16 vqprt; - __le16 vqfrsm; - __le16 vqgran; - __u8 rsvd48[16]; - __le32 vifrt; - __le32 virfa; - __le16 virfap; - __le16 viprt; - __le16 vifrsm; - __le16 vigran; - __u8 rsvd80[4016]; - }; - -**Members** - -``cntlid`` - Controller Identifier - -``portid`` - Port Identifier - -``crt`` - Controller Resource Types - -``rsvd5`` - reserved - -``vqfrt`` - VQ Resources Flexible Total - -``vqrfa`` - VQ Resources Flexible Assigned - -``vqrfap`` - VQ Resources Flexible Allocated to Primary - -``vqprt`` - VQ Resources Private Total - -``vqfrsm`` - VQ Resources Flexible Secondary Maximum - -``vqgran`` - VQ Flexible Resource Preferred Granularity - -``rsvd48`` - reserved - -``vifrt`` - VI Resources Flexible Total - -``virfa`` - VI Resources Flexible Assigned - -``virfap`` - VI Resources Flexible Allocated to Primary - -``viprt`` - VI Resources Private Total - -``vifrsm`` - VI Resources Flexible Secondary Maximum - -``vigran`` - VI Flexible Resource Preferred Granularity - -``rsvd80`` - reserved - - - - - -.. c:struct:: nvme_secondary_ctrl - - Secondary Controller Entry - -**Definition** - -:: - - struct nvme_secondary_ctrl { - __le16 scid; - __le16 pcid; - __u8 scs; - __u8 rsvd5[3]; - __le16 vfn; - __le16 nvq; - __le16 nvi; - __u8 rsvd14[18]; - }; - -**Members** - -``scid`` - Secondary Controller Identifier - -``pcid`` - Primary Controller Identifier - -``scs`` - Secondary Controller State - -``rsvd5`` - Reserved - -``vfn`` - Virtual Function Number - -``nvq`` - Number of VQ Flexible Resources Assigned - -``nvi`` - Number of VI Flexible Resources Assigned - -``rsvd14`` - Reserved - - - - - -.. c:struct:: nvme_secondary_ctrl_list - - Secondary Controller List - -**Definition** - -:: - - struct nvme_secondary_ctrl_list { - __u8 num; - __u8 rsvd[31]; - struct nvme_secondary_ctrl sc_entry[NVME_ID_SECONDARY_CTRL_MAX]; - }; - -**Members** - -``num`` - Number of Identifiers - -``rsvd`` - Reserved - -``sc_entry`` - Secondary Controller Entry - - - - - -.. c:struct:: nvme_id_iocs - - NVMe Identify IO Command Set data structure - -**Definition** - -:: - - struct nvme_id_iocs { - __u64 iocsc[512]; - }; - -**Members** - -``iocsc`` - List of supported IO Command Set Combination vectors - - - - - -.. c:struct:: nvme_id_domain_attr - - Domain Attributes Entry - -**Definition** - -:: - - struct nvme_id_domain_attr { - __le16 dom_id; - __u8 rsvd2[14]; - __u8 dom_cap[16]; - __u8 unalloc_dom_cap[16]; - __u8 max_egrp_dom_cap[16]; - __u8 rsvd64[64]; - }; - -**Members** - -``dom_id`` - Domain Identifier - -``rsvd2`` - Reserved - -``dom_cap`` - Total Domain Capacity - -``unalloc_dom_cap`` - Unallocated Domain Capacity - -``max_egrp_dom_cap`` - Max Endurance Group Domain Capacity - -``rsvd64`` - Reserved - - - - - -.. c:struct:: nvme_id_domain_list - - Domain List - -**Definition** - -:: - - struct nvme_id_domain_list { - __u8 num; - __u8 rsvd[127]; - struct nvme_id_domain_attr domain_attr[NVME_ID_DOMAIN_LIST_MAX]; - }; - -**Members** - -``num`` - Number of domain attributes - -``rsvd`` - Reserved - -``domain_attr`` - List of domain attributes - - - - - -.. c:struct:: nvme_id_endurance_group_list - - Endurance Group List - -**Definition** - -:: - - struct nvme_id_endurance_group_list { - __le16 num; - __le16 identifier[NVME_ID_ENDURANCE_GROUP_LIST_MAX]; - }; - -**Members** - -``num`` - Number of Identifiers - -``identifier`` - Endurance Group Identifier - - - - - -.. c:struct:: nvme_supported_log_pages - - Supported Log Pages - Log - -**Definition** - -:: - - struct nvme_supported_log_pages { - __le32 lid_support[NVME_LOG_SUPPORTED_LOG_PAGES_MAX]; - }; - -**Members** - -``lid_support`` - Log Page Identifier Supported - - -**Description** - -Supported Log Pages (Log Identifier 00h) - - - - -.. c:struct:: nvme_error_log_page - - Error Information Log Entry (Log Identifier 01h) - -**Definition** - -:: - - struct nvme_error_log_page { - __le64 error_count; - __le16 sqid; - __le16 cmdid; - __le16 status_field; - __le16 parm_error_location; - __le64 lba; - __le32 nsid; - __u8 vs; - __u8 trtype; - __u8 rsvd[2]; - __le64 cs; - __le16 trtype_spec_info; - __u8 rsvd2[22]; - }; - -**Members** - -``error_count`` - Error Count: a 64-bit incrementing error count, - indicating a unique identifier for this error. The error - count starts at ``1h``, is incremented for each unique error - log entry, and is retained across power off conditions. - A value of ``0h`` indicates an invalid entry; this value - is used when there are lost entries or when there are - fewer errors than the maximum number of entries the - controller supports. If the value of this field is - ``FFFFFFFFh``, then the field shall be set to 1h when - incremented (i.e., rolls over to ``1h``). Prior to NVMe - 1.4, processing of incrementing beyond ``FFFFFFFFh`` is - unspecified. - -``sqid`` - Submission Queue ID: indicates the Submission Queue - Identifier of the command that the error information is - associated with. If the error is not specific to - a particular command, then this field shall be set to - ``FFFFh``. - -``cmdid`` - Command ID: indicates the Command Identifier of the - command that the error is associated with. If the error - is not specific to a particular command, then this field - shall be set to ``FFFFh``. - -``status_field`` - Bits 15-1: Status Field: indicates the Status Field for - the command that completed. If the error is not specific - to a particular command, then this field reports the most - applicable status value. - Bit 0: Phase Tag: may indicate the Phase Tag posted for - the command. - -``parm_error_location`` - Parameter Error Location: indicates the byte and bit of - the command parameter that the error is associated with, - if applicable. If the parameter spans multiple bytes or - bits, then the location indicates the first byte and bit - of the parameter. - Bits 10-8: Bit in command that contained the error. - Valid values are 0 to 7. - Bits 7-0: Byte in command that contained the error. - Valid values are 0 to 63. - -``lba`` - LBA: This field indicates the first LBA that experienced - the error condition, if applicable. - -``nsid`` - Namespace: This field indicates the NSID of the namespace - that the error is associated with, if applicable. - -``vs`` - Vendor Specific Information Available: If there is - additional vendor specific error information available, - this field provides the log page identifier associated - with that page. A value of ``0h`` indicates that no additional - information is available. Valid values are in the range - of ``80h`` to ``FFh``. - -``trtype`` - Transport Type (TRTYPE): indicates the Transport Type of - the transport associated with the error. The values in - this field are the same as the TRTYPE values in the - Discovery Log Page Entry. If the error is not transport - related, this field shall be cleared to ``0h``. If the error - is transport related, this field shall be set to the type - of the transport - see :c:type:`enum nvme_trtype `. - -``rsvd`` - Reserved - -``cs`` - Command Specific Information: This field contains command - specific information. If used, the command definition - specifies the information returned. - -``trtype_spec_info`` - Transport Type Specific Information - -``rsvd2`` - Reserved - - - - - -.. c:struct:: nvme_smart_log - - SMART / Health Information Log (Log Identifier 02h) - -**Definition** - -:: - - struct nvme_smart_log { - __u8 critical_warning; - __u8 temperature[2]; - __u8 avail_spare; - __u8 spare_thresh; - __u8 percent_used; - __u8 endu_grp_crit_warn_sumry; - __u8 rsvd7[25]; - __u8 data_units_read[16]; - __u8 data_units_written[16]; - __u8 host_reads[16]; - __u8 host_writes[16]; - __u8 ctrl_busy_time[16]; - __u8 power_cycles[16]; - __u8 power_on_hours[16]; - __u8 unsafe_shutdowns[16]; - __u8 media_errors[16]; - __u8 num_err_log_entries[16]; - __le32 warning_temp_time; - __le32 critical_comp_time; - __le16 temp_sensor[8]; - __le32 thm_temp1_trans_count; - __le32 thm_temp2_trans_count; - __le32 thm_temp1_total_time; - __le32 thm_temp2_total_time; - __u8 rsvd232[280]; - }; - -**Members** - -``critical_warning`` - This field indicates critical warnings for the state - of the controller. Critical warnings may result in an - asynchronous event notification to the host. Bits in - this field represent the current associated state and - are not persistent (see :c:type:`enum nvme_smart_crit `). - -``temperature`` - Composite Temperature: Contains a value corresponding - to a temperature in Kelvins that represents the current - composite temperature of the controller and namespace(s) - associated with that controller. The manner in which - this value is computed is implementation specific and - may not represent the actual temperature of any physical - point in the NVM subsystem. Warning and critical - overheating composite temperature threshold values are - reported by the WCTEMP and CCTEMP fields in the Identify - Controller data structure. - -``avail_spare`` - Available Spare: Contains a normalized percentage (0% - to 100%) of the remaining spare capacity available. - -``spare_thresh`` - Available Spare Threshold: When the Available Spare - falls below the threshold indicated in this field, an - asynchronous event completion may occur. The value is - indicated as a normalized percentage (0% to 100%). - The values 101 to 255 are reserved. - -``percent_used`` - Percentage Used: Contains a vendor specific estimate - of the percentage of NVM subsystem life used based on - the actual usage and the manufacturer's prediction of - NVM life. A value of 100 indicates that the estimated - endurance of the NVM in the NVM subsystem has been - consumed, but may not indicate an NVM subsystem failure. - The value is allowed to exceed 100. Percentages greater - than 254 shall be represented as 255. This value shall - be updated once per power-on hour (when the controller - is not in a sleep state). - -``endu_grp_crit_warn_sumry`` - Endurance Group Critical Warning Summary: This field - indicates critical warnings for the state of Endurance - Groups. Bits in this field represent the current associated - state and are not persistent (see :c:type:`enum nvme_smart_egcw `). - -``rsvd7`` - Reserved - -``data_units_read`` - Data Units Read: Contains the number of 512 byte data - units the host has read from the controller; this value - does not include metadata. This value is reported in - thousands (i.e., a value of 1 corresponds to 1000 - units of 512 bytes read) and is rounded up (e.g., one - indicates the that number of 512 byte data units read - is from 1 to 1000, three indicates that the number of - 512 byte data units read is from 2001 to 3000). When - the LBA size is a value other than 512 bytes, the - controller shall convert the amount of data read to - 512 byte units. For the NVM command set, logical blocks - read as part of Compare, Read, and Verify operations - shall be included in this value. A value of ``0h`` in - this field indicates that the number of Data Units Read - is not reported. - -``data_units_written`` - Data Units Written: Contains the number of 512 byte - data units the host has written to the controller; - this value does not include metadata. This value is - reported in thousands (i.e., a value of 1 corresponds - to 1000 units of 512 bytes written) and is rounded up - (e.g., one indicates that the number of 512 byte data - units written is from 1 to 1,000, three indicates that - the number of 512 byte data units written is from 2001 - to 3000). When the LBA size is a value other than 512 - bytes, the controller shall convert the amount of data - written to 512 byte units. For the NVM command set, - logical blocks written as part of Write operations shall - be included in this value. Write Uncorrectable commands - and Write Zeroes commands shall not impact this value. - A value of ``0h`` in this field indicates that the number - of Data Units Written is not reported. - -``host_reads`` - Host Read Commands: Contains the number of read commands - completed by the controller. For the NVM command set, - this value is the sum of the number of Compare commands - and the number of Read commands. - -``host_writes`` - Host Write Commands: Contains the number of write - commands completed by the controller. For the NVM - command set, this is the number of Write commands. - -``ctrl_busy_time`` - Controller Busy Time: Contains the amount of time the - controller is busy with I/O commands. The controller - is busy when there is a command outstanding to an I/O - Queue (specifically, a command was issued via an I/O - Submission Queue Tail doorbell write and the corresponding - completion queue entry has not been posted yet to the - associated I/O Completion Queue). This value is - reported in minutes. - -``power_cycles`` - Power Cycles: Contains the number of power cycles. - -``power_on_hours`` - Power On Hours: Contains the number of power-on hours. - This may not include time that the controller was - powered and in a non-operational power state. - -``unsafe_shutdowns`` - Unsafe Shutdowns: Contains the number of unsafe - shutdowns. This count is incremented when a Shutdown - Notification (CC.SHN) is not received prior to loss of power. - -``media_errors`` - Media and Data Integrity Errors: Contains the number - of occurrences where the controller detected an - unrecovered data integrity error. Errors such as - uncorrectable ECC, CRC checksum failure, or LBA tag - mismatch are included in this field. Errors introduced - as a result of a Write Uncorrectable command may or - may not be included in this field. - -``num_err_log_entries`` - Number of Error Information Log Entries: Contains the - number of Error Information log entries over the life - of the controller. - -``warning_temp_time`` - Warning Composite Temperature Time: Contains the amount - of time in minutes that the controller is operational - and the Composite Temperature is greater than or equal - to the Warning Composite Temperature Threshold (WCTEMP) - field and less than the Critical Composite Temperature - Threshold (CCTEMP) field in the Identify Controller - data structure. If the value of the WCTEMP or CCTEMP - field is ``0h``, then this field is always cleared to ``0h`` - regardless of the Composite Temperature value. - -``critical_comp_time`` - Critical Composite Temperature Time: Contains the amount - of time in minutes that the controller is operational - and the Composite Temperature is greater than or equal - to the Critical Composite Temperature Threshold (CCTEMP) - field in the Identify Controller data structure. If - the value of the CCTEMP field is ``0h``, then this field - is always cleared to 0h regardless of the Composite - Temperature value. - -``temp_sensor`` - Temperature Sensor 1-8: Contains the current temperature - in degrees Kelvin reported by temperature sensors 1-8. - The physical point in the NVM subsystem whose temperature - is reported by the temperature sensor and the temperature - accuracy is implementation specific. An implementation - that does not implement the temperature sensor reports - a value of ``0h``. - -``thm_temp1_trans_count`` - Thermal Management Temperature 1 Transition Count: - Contains the number of times the controller transitioned - to lower power active power states or performed vendor - specific thermal management actions while minimizing - the impact on performance in order to attempt to reduce - the Composite Temperature because of the host controlled - thermal management feature (i.e., the Composite - Temperature rose above the Thermal Management - Temperature 1). This counter shall not wrap once the - value ``FFFFFFFFh`` is reached. A value of ``0h``, indicates - that this transition has never occurred or this field - is not implemented. - -``thm_temp2_trans_count`` - Thermal Management Temperature 2 Transition Count - -``thm_temp1_total_time`` - Total Time For Thermal Management Temperature 1: - Contains the number of seconds that the controller - had transitioned to lower power active power states or - performed vendor specific thermal management actions - while minimizing the impact on performance in order to - attempt to reduce the Composite Temperature because of - the host controlled thermal management feature. This - counter shall not wrap once the value ``FFFFFFFFh`` is - reached. A value of ``0h``, indicates that this transition - has never occurred or this field is not implemented. - -``thm_temp2_total_time`` - Total Time For Thermal Management Temperature 2 - -``rsvd232`` - Reserved - - - - - -.. c:enum:: nvme_smart_crit - - Critical Warning - -**Constants** - -``NVME_SMART_CRIT_SPARE`` - If set, then the available spare capacity has fallen - below the threshold. - -``NVME_SMART_CRIT_TEMPERATURE`` - If set, then a temperature is either greater - than or equal to an over temperature threshold; or - less than or equal to an under temperature threshold. - -``NVME_SMART_CRIT_DEGRADED`` - If set, then the NVM subsystem reliability has - been degraded due to significant media related errors - or any internal error that degrades NVM subsystem - reliability. - -``NVME_SMART_CRIT_MEDIA`` - If set, then all of the media has been placed in read - only mode. The controller shall not set this bit if - the read-only condition on the media is a result of - a change in the write protection state of a namespace. - -``NVME_SMART_CRIT_VOLATILE_MEMORY`` - If set, then the volatile memory backup - device has failed. This field is only valid if the - controller has a volatile memory backup solution. - -``NVME_SMART_CRIT_PMR_RO`` - If set, then the Persistent Memory Region has become - read-only or unreliable. - - - - -.. c:enum:: nvme_smart_egcw - - Endurance Group Critical Warning Summary - -**Constants** - -``NVME_SMART_EGCW_SPARE`` - If set, then the available spare capacity of one or - more Endurance Groups has fallen below the threshold. - -``NVME_SMART_EGCW_DEGRADED`` - If set, then the reliability of one or more - Endurance Groups has been degraded due to significant - media related errors or any internal error that - degrades NVM subsystem reliability. - -``NVME_SMART_EGCW_RO`` - If set, then the namespaces in one or more Endurance - Groups have been placed in read only mode not as - a result of a change in the write protection state - of a namespace. - - - - -.. c:struct:: nvme_firmware_slot - - Firmware Slot Information Log - -**Definition** - -:: - - struct nvme_firmware_slot { - __u8 afi; - __u8 rsvd1[7]; - char frs[7][8]; - __u8 rsvd2[448]; - }; - -**Members** - -``afi`` - Active Firmware Info - -``rsvd1`` - Reserved - -``frs`` - Firmware Revision for Slot - -``rsvd2`` - Reserved - - - - - -.. c:struct:: nvme_cmd_effects_log - - Commands Supported and Effects Log - -**Definition** - -:: - - struct nvme_cmd_effects_log { - __le32 acs[256]; - __le32 iocs[256]; - __u8 rsvd[2048]; - }; - -**Members** - -``acs`` - Admin Command Supported - -``iocs`` - I/O Command Supported - -``rsvd`` - Reserved - - - - - -.. c:enum:: nvme_cmd_effects - - Commands Supported and Effects - -**Constants** - -``NVME_CMD_EFFECTS_CSUPP`` - Command Supported - -``NVME_CMD_EFFECTS_LBCC`` - Logical Block Content Change - -``NVME_CMD_EFFECTS_NCC`` - Namespace Capability Change - -``NVME_CMD_EFFECTS_NIC`` - Namespace Inventory Change - -``NVME_CMD_EFFECTS_CCC`` - Controller Capability Change - -``NVME_CMD_EFFECTS_CSE_MASK`` - Command Submission and Execution - -``NVME_CMD_EFFECTS_UUID_SEL`` - UUID Selection Supported - - - - -.. c:struct:: nvme_st_result - - Self-test Result - -**Definition** - -:: - - struct nvme_st_result { - __u8 dsts; - __u8 seg; - __u8 vdi; - __u8 rsvd; - __le64 poh; - __le32 nsid; - __le64 flba; - __u8 sct; - __u8 sc; - __u8 vs[2]; - }; - -**Members** - -``dsts`` - Device Self-test Status: Indicates the device self-test code and the - status of the operation (see :c:type:`enum nvme_status_result ` and :c:type:`enum nvme_st_code `). - -``seg`` - Segment Number: Iindicates the segment number where the first self-test - failure occurred. If Device Self-test Status (**dsts**) is not set to - #NVME_ST_RESULT_KNOWN_SEG_FAIL, then this field should be ignored. - -``vdi`` - Valid Diagnostic Information: Indicates the diagnostic failure - information that is reported. See :c:type:`enum nvme_st_valid_diag_info `. - -``rsvd`` - Reserved - -``poh`` - Power On Hours (POH): Indicates the number of power-on hours at the - time the device self-test operation was completed or aborted. This - does not include time that the controller was powered and in a low - power state condition. - -``nsid`` - Namespace Identifier (NSID): Indicates the namespace that the Failing - LBA occurred on. Valid only when the NSID Valid bit - (#NVME_ST_VALID_DIAG_INFO_NSID) is set in the Valid Diagnostic - Information (**vdi**) field. - -``flba`` - Failing LBA: indicates the LBA of the logical block that caused the - test to fail. If the device encountered more than one failed logical - block during the test, then this field only indicates one of those - failed logical blocks. Valid only when the NSID Valid bit - (#NVME_ST_VALID_DIAG_INFO_FLBA) is set in the Valid Diagnostic - Information (**vdi**) field. - -``sct`` - Status Code Type: This field may contain additional information related - to errors or conditions. Bits 2:0 may contain additional information - relating to errors or conditions that occurred during the device - self-test operation represented in the same format used in the Status - Code Type field of the completion queue entry (refer to :c:type:`enum nvme_status_field `). - Valid only when the NSID Valid bit (#NVME_ST_VALID_DIAG_INFO_SCT) is - set in the Valid Diagnostic Information (**vdi**) field. - -``sc`` - Status Code: This field may contain additional information relating - to errors or conditions that occurred during the device self-test - operation represented in the same format used in the Status Code field - of the completion queue entry. Valid only when the SCT Valid bit - (#NVME_ST_VALID_DIAG_INFO_SC) is set in the Valid Diagnostic - Information (**vdi**) field. - -``vs`` - Vendor Specific. - - - - - -.. c:enum:: nvme_status_result - - Result of the device self-test operation - -**Constants** - -``NVME_ST_RESULT_NO_ERR`` - Operation completed without error. - -``NVME_ST_RESULT_ABORTED`` - Operation was aborted by a Device Self-test command. - -``NVME_ST_RESULT_CLR`` - Operation was aborted by a Controller Level Reset. - -``NVME_ST_RESULT_NS_REMOVED`` - Operation was aborted due to a removal of - a namespace from the namespace inventory. - -``NVME_ST_RESULT_ABORTED_FORMAT`` - Operation was aborted due to the processing - of a Format NVM command. - -``NVME_ST_RESULT_FATAL_ERR`` - A fatal error or unknown test error occurred - while the controller was executing the device - self-test operation and the operation did - not complete. - -``NVME_ST_RESULT_UNKNOWN_SEG_FAIL`` - Operation completed with a segment that failed - and the segment that failed is not known. - -``NVME_ST_RESULT_KNOWN_SEG_FAIL`` - Operation completed with one or more failed - segments and the first segment that failed - is indicated in the Segment Number field. - -``NVME_ST_RESULT_ABORTED_UNKNOWN`` - Operation was aborted for unknown reason. - -``NVME_ST_RESULT_ABORTED_SANITIZE`` - Operation was aborted due to a sanitize operation. - -``NVME_ST_RESULT_NOT_USED`` - Entry not used (does not contain a test result). - -``NVME_ST_RESULT_MASK`` - Mask to get the status result value from - the :c:type:`struct nvme_st_result `.dsts field. - - - - -.. c:enum:: nvme_st_code - - Self-test Code value - -**Constants** - -``NVME_ST_CODE_RESERVED`` - Reserved. - -``NVME_ST_CODE_SHORT`` - Short device self-test operation. - -``NVME_ST_CODE_EXTENDED`` - Extended device self-test operation. - -``NVME_ST_CODE_VS`` - Vendor specific. - -``NVME_ST_CODE_SHIFT`` - Shift amount to get the code value from the - :c:type:`struct nvme_st_result `.dsts field. - - - - -.. c:enum:: nvme_st_curr_op - - Current Device Self-Test Operation - -**Constants** - -``NVME_ST_CURR_OP_NOT_RUNNING`` - No device self-test operation in progress. - -``NVME_ST_CURR_OP_SHORT`` - Short device self-test operation in progress. - -``NVME_ST_CURR_OP_EXTENDED`` - Extended device self-test operation in progress. - -``NVME_ST_CURR_OP_VS`` - Vendor specific. - -``NVME_ST_CURR_OP_RESERVED`` - Reserved. - -``NVME_ST_CURR_OP_MASK`` - Mask to get the current operation value from the - :c:type:`struct nvme_self_test_log `.current_operation field. - -``NVME_ST_CURR_OP_CMPL_MASK`` - Mask to get the current operation completion value - from the :c:type:`struct nvme_self_test_log `.completion field. - - - - -.. c:enum:: nvme_st_valid_diag_info - - Valid Diagnostic Information - -**Constants** - -``NVME_ST_VALID_DIAG_INFO_NSID`` - NSID Valid: if set, then the contents of - the Namespace Identifier field are valid. - -``NVME_ST_VALID_DIAG_INFO_FLBA`` - FLBA Valid: if set, then the contents of - the Failing LBA field are valid. - -``NVME_ST_VALID_DIAG_INFO_SCT`` - SCT Valid: if set, then the contents of - the Status Code Type field are valid. - -``NVME_ST_VALID_DIAG_INFO_SC`` - SC Valid: if set, then the contents of - the Status Code field are valid. - - - - -.. c:struct:: nvme_self_test_log - - Device Self-test (Log Identifier 06h) - -**Definition** - -:: - - struct nvme_self_test_log { - __u8 current_operation; - __u8 completion; - __u8 rsvd[2]; - struct nvme_st_result result[NVME_LOG_ST_MAX_RESULTS]; - }; - -**Members** - -``current_operation`` - Current Device Self-Test Operation: indicates the status - of the current device self-test operation. If a device - self-test operation is in process (i.e., this field is set - to #NVME_ST_CURR_OP_SHORT or #NVME_ST_CURR_OP_EXTENDED), - then the controller shall not set this field to - #NVME_ST_CURR_OP_NOT_RUNNING until a new Self-test Result - Data Structure is created (i.e., if a device self-test - operation completes or is aborted, then the controller - shall create a Self-test Result Data Structure prior to - setting this field to #NVME_ST_CURR_OP_NOT_RUNNING). - See :c:type:`enum nvme_st_curr_op `. - -``completion`` - Current Device Self-Test Completion: indicates the percentage - of the device self-test operation that is complete (e.g., - a value of 25 indicates that 25% of the device self-test - operation is complete and 75% remains to be tested). - If the **current_operation** field is cleared to - #NVME_ST_CURR_OP_NOT_RUNNING (indicating there is no device - self-test operation in progress), then this field is ignored. - -``rsvd`` - Reserved - -``result`` - Self-test Result Data Structures, see :c:type:`struct nvme_st_result `. - - - - - -.. c:enum:: nvme_cmd_get_log_telemetry_host_lsp - - Telemetry Host-Initiated log specific field - -**Constants** - -``NVME_LOG_TELEM_HOST_LSP_RETAIN`` - Get Telemetry Data Blocks - -``NVME_LOG_TELEM_HOST_LSP_CREATE`` - Create Telemetry Data Blocks - - - - -.. c:struct:: nvme_telemetry_log - - Retrieve internal data specific to the manufacturer. - -**Definition** - -:: - - struct nvme_telemetry_log { - __u8 lpi; - __u8 rsvd1[4]; - __u8 ieee[3]; - __le16 dalb1; - __le16 dalb2; - __le16 dalb3; - __u8 rsvd14[2]; - __le32 dalb4; - __u8 rsvd20[361]; - __u8 hostdgn; - __u8 ctrlavail; - __u8 ctrldgn; - __u8 rsnident[128]; - __u8 data_area[]; - }; - -**Members** - -``lpi`` - Log Identifier, either ``NVME_LOG_LID_TELEMETRY_HOST`` or - ``NVME_LOG_LID_TELEMETRY_CTRL`` - -``rsvd1`` - Reserved - -``ieee`` - IEEE OUI Identifier is the Organization Unique Identifier (OUI) - for the controller vendor that is able to interpret the data. - -``dalb1`` - Telemetry Controller-Initiated Data Area 1 Last Block is - the value of the last block in this area. - -``dalb2`` - Telemetry Controller-Initiated Data Area 1 Last Block is - the value of the last block in this area. - -``dalb3`` - Telemetry Controller-Initiated Data Area 1 Last Block is - the value of the last block in this area. - -``rsvd14`` - Reserved - -``dalb4`` - Telemetry Controller-Initiated Data Area 4 Last Block is - the value of the last block in this area. - -``rsvd20`` - Reserved - -``hostdgn`` - Telemetry Host-Initiated Data Generation Number is a - value that is incremented each time the host initiates a - capture of its internal controller state in the controller . - -``ctrlavail`` - Telemetry Controller-Initiated Data Available, if cleared, - then the controller telemetry log does not contain saved - internal controller state. If this field is set to 1h, the - controller log contains saved internal controller state. If - this field is set to 1h, the data will be latched until the - host releases it by reading the log with RAE cleared. - -``ctrldgn`` - Telemetry Controller-Initiated Data Generation Number is - a value that is incremented each time the controller initiates a - capture of its internal controller state in the controller . - -``rsnident`` - Reason Identifiers a vendor specific identifier that describes - the operating conditions of the controller at the time of - capture. - -``data_area`` - Telemetry data blocks, vendor specific information data. - - -**Description** - -This log consists of a header describing the log and zero or more Telemetry -Data Blocks. All Telemetry Data Blocks are ``NVME_LOG_TELEM_BLOCK_SIZE``, 512 -bytes, in size. This log captures the controller’s internal state. - - - - -.. c:struct:: nvme_endurance_group_log - - Endurance Group Information Log - -**Definition** - -:: - - struct nvme_endurance_group_log { - __u8 critical_warning; - __u8 rsvd1[2]; - __u8 avl_spare; - __u8 avl_spare_threshold; - __u8 percent_used; - __u8 rsvd6[26]; - __u8 endurance_estimate[16]; - __u8 data_units_read[16]; - __u8 data_units_written[16]; - __u8 media_units_written[16]; - __u8 host_read_cmds[16]; - __u8 host_write_cmds[16]; - __u8 media_data_integrity_err[16]; - __u8 num_err_info_log_entries[16]; - __u8 rsvd160[352]; - }; - -**Members** - -``critical_warning`` - Critical Warning - -``rsvd1`` - Reserved - -``avl_spare`` - Available Spare - -``avl_spare_threshold`` - Available Spare Threshold - -``percent_used`` - Percentage Used - -``rsvd6`` - Reserved - -``endurance_estimate`` - Endurance Estimate - -``data_units_read`` - Data Units Read - -``data_units_written`` - Data Units Written - -``media_units_written`` - Media Units Written - -``host_read_cmds`` - Host Read Commands - -``host_write_cmds`` - Host Write Commands - -``media_data_integrity_err`` - Media and Data Integrity Errors - -``num_err_info_log_entries`` - Number of Error Information Log Entries - -``rsvd160`` - Reserved - - - - - -.. c:enum:: nvme_eg_critical_warning_flags - - Endurance Group Information Log - Critical Warning - -**Constants** - -``NVME_EG_CRITICAL_WARNING_SPARE`` - Available spare capacity of the Endurance Group - has fallen below the threshold - -``NVME_EG_CRITICAL_WARNING_DEGRADED`` - Endurance Group reliability has been degraded - -``NVME_EG_CRITICAL_WARNING_READ_ONLY`` - Endurance Group have been placed in read only - mode - - - - -.. c:struct:: nvme_aggregate_endurance_group_event - - Endurance Group Event Aggregate - -**Definition** - -:: - - struct nvme_aggregate_endurance_group_event { - __le64 num_entries; - __le16 entries[]; - }; - -**Members** - -``num_entries`` - Number or entries - -``entries`` - List of entries - - - - - -.. c:struct:: nvme_nvmset_predictable_lat_log - - Predictable Latency Mode - Deterministic Threshold Configuration Data - -**Definition** - -:: - - struct nvme_nvmset_predictable_lat_log { - __u8 status; - __u8 rsvd1; - __le16 event_type; - __u8 rsvd4[28]; - __le64 dtwin_rt; - __le64 dtwin_wt; - __le64 dtwin_tmax; - __le64 ndwin_tmin_hi; - __le64 ndwin_tmin_lo; - __u8 rsvd72[56]; - __le64 dtwin_re; - __le64 dtwin_we; - __le64 dtwin_te; - __u8 rsvd152[360]; - }; - -**Members** - -``status`` - Status - -``rsvd1`` - Reserved - -``event_type`` - Event Type - -``rsvd4`` - Reserved - -``dtwin_rt`` - DTWIN Reads Typical - -``dtwin_wt`` - DTWIN Writes Typical - -``dtwin_tmax`` - DTWIN Time Maximum - -``ndwin_tmin_hi`` - NDWIN Time Minimum High - -``ndwin_tmin_lo`` - NDWIN Time Minimum Low - -``rsvd72`` - Reserved - -``dtwin_re`` - DTWIN Reads Estimate - -``dtwin_we`` - DTWIN Writes Estimate - -``dtwin_te`` - DTWIN Time Estimate - -``rsvd152`` - Reserved - - - - - -.. c:enum:: nvme_nvmeset_pl_status - - Predictable Latency Per NVM Set Log - Status - -**Constants** - -``NVME_NVMSET_PL_STATUS_DISABLED`` - Not used (Predictable Latency Mode not enabled) - -``NVME_NVMSET_PL_STATUS_DTWIN`` - Deterministic Window (DTWIN) - -``NVME_NVMSET_PL_STATUS_NDWIN`` - Non-Deterministic Window (NDWIN) - - - - -.. c:enum:: nvme_nvmset_pl_events - - Predictable Latency Per NVM Set Log - Event Type - -**Constants** - -``NVME_NVMSET_PL_EVENT_DTWIN_READ_WARN`` - DTWIN Reads Warning - -``NVME_NVMSET_PL_EVENT_DTWIN_WRITE_WARN`` - DTWIN Writes Warning - -``NVME_NVMSET_PL_EVENT_DTWIN_TIME_WARN`` - DTWIN Time Warning - -``NVME_NVMSET_PL_EVENT_DTWIN_EXCEEDED`` - Autonomous transition from DTWIN - to NDWIN due to typical or - maximum value exceeded - -``NVME_NVMSET_PL_EVENT_DTWIN_EXCURSION`` - Autonomous transition from DTWIN - to NDWIN due to Deterministic - Excursion - - - - -.. c:struct:: nvme_aggregate_predictable_lat_event - - Predictable Latency Event Aggregate Log Page - -**Definition** - -:: - - struct nvme_aggregate_predictable_lat_event { - __le64 num_entries; - __le16 entries[]; - }; - -**Members** - -``num_entries`` - Number of entries - -``entries`` - Entry list - - - - - -.. c:struct:: nvme_ana_group_desc - - ANA Group Descriptor - -**Definition** - -:: - - struct nvme_ana_group_desc { - __le32 grpid; - __le32 nnsids; - __le64 chgcnt; - __u8 state; - __u8 rsvd17[15]; - __le32 nsids[]; - }; - -**Members** - -``grpid`` - ANA group id - -``nnsids`` - Number of namespaces in **nsids** - -``chgcnt`` - Change counter - -``state`` - ANA state - -``rsvd17`` - Reserved - -``nsids`` - List of namespaces - - - - - -.. c:enum:: nvme_ana_state - - ANA Group Descriptor - Asymmetric Namespace Access State - -**Constants** - -``NVME_ANA_STATE_OPTIMIZED`` - ANA Optimized state - -``NVME_ANA_STATE_NONOPTIMIZED`` - ANA Non-Optimized state - -``NVME_ANA_STATE_INACCESSIBLE`` - ANA Inaccessible state - -``NVME_ANA_STATE_PERSISTENT_LOSS`` - ANA Persistent Loss state - -``NVME_ANA_STATE_CHANGE`` - ANA Change state - - - - -.. c:struct:: nvme_ana_log - - Asymmetric Namespace Access Log - -**Definition** - -:: - - struct nvme_ana_log { - __le64 chgcnt; - __le16 ngrps; - __u8 rsvd10[6]; - struct nvme_ana_group_desc descs[]; - }; - -**Members** - -``chgcnt`` - Change Count - -``ngrps`` - Number of ANA Group Descriptors - -``rsvd10`` - Reserved - -``descs`` - ANA Group Descriptor - - - - - -.. c:struct:: nvme_persistent_event_log - - Persistent Event Log - -**Definition** - -:: - - struct nvme_persistent_event_log { - __u8 lid; - __u8 rsvd1[3]; - __le32 tnev; - __le64 tll; - __u8 rv; - __u8 rsvd17; - __le16 lhl; - __le64 ts; - __u8 poh[16]; - __le64 pcc; - __le16 vid; - __le16 ssvid; - char sn[20]; - char mn[40]; - char subnqn[NVME_NQN_LENGTH]; - __le16 gen_number; - __le32 rci; - __u8 rsvd378[102]; - __u8 seb[32]; - }; - -**Members** - -``lid`` - Log Identifier - -``rsvd1`` - Reserved - -``tnev`` - Total Number of Events - -``tll`` - Total Log Length - -``rv`` - Log Revision - -``rsvd17`` - Reserved - -``lhl`` - Log Header Length - -``ts`` - Timestamp - -``poh`` - Power on Hours - -``pcc`` - Power Cycle Count - -``vid`` - PCI Vendor ID - -``ssvid`` - PCI Subsystem Vendor ID - -``sn`` - Serial Number - -``mn`` - Model Number - -``subnqn`` - NVM Subsystem NVMe Qualified Name - -``gen_number`` - Generation Number - -``rci`` - Reporting Context Information - -``rsvd378`` - Reserved - -``seb`` - Supported Events Bitmap - - - - - -.. c:struct:: nvme_persistent_event_entry - - Persistent Event - -**Definition** - -:: - - struct nvme_persistent_event_entry { - __u8 etype; - __u8 etype_rev; - __u8 ehl; - __u8 ehai; - __le16 cntlid; - __le64 ets; - __le16 pelpid; - __u8 rsvd16[4]; - __le16 vsil; - __le16 el; - }; - -**Members** - -``etype`` - Event Type - -``etype_rev`` - Event Type Revision - -``ehl`` - Event Header Length - -``ehai`` - Event Header Additional Info - -``cntlid`` - Controller Identifier - -``ets`` - Event Timestamp - -``pelpid`` - Port Identifier - -``rsvd16`` - Reserved - -``vsil`` - Vendor Specific Information Length - -``el`` - Event Length - - - - - -.. c:enum:: nvme_persistent_event_types - - Persistent event log events - -**Constants** - -``NVME_PEL_SMART_HEALTH_EVENT`` - SMART / Health Log Snapshot Event - -``NVME_PEL_FW_COMMIT_EVENT`` - Firmware Commit Event - -``NVME_PEL_TIMESTAMP_EVENT`` - Timestamp Change Event - -``NVME_PEL_POWER_ON_RESET_EVENT`` - Power-on or Reset Event - -``NVME_PEL_NSS_HW_ERROR_EVENT`` - NVM Subsystem Hardware Error Event - -``NVME_PEL_CHANGE_NS_EVENT`` - Change Namespace Event - -``NVME_PEL_FORMAT_START_EVENT`` - Format NVM Start Event - -``NVME_PEL_FORMAT_COMPLETION_EVENT`` - Format NVM Completion Event - -``NVME_PEL_SANITIZE_START_EVENT`` - Sanitize Start Event - -``NVME_PEL_SANITIZE_COMPLETION_EVENT`` - Sanitize Completion Event - -``NVME_PEL_SET_FEATURE_EVENT`` - Set Feature Event - -``NVME_PEL_TELEMETRY_CRT`` - Telemetry Log Create Event - -``NVME_PEL_THERMAL_EXCURSION_EVENT`` - Thermal Excursion Event - - - - -.. c:struct:: nvme_fw_commit_event - - Firmware Commit Event Data - -**Definition** - -:: - - struct nvme_fw_commit_event { - __le64 old_fw_rev; - __le64 new_fw_rev; - __u8 fw_commit_action; - __u8 fw_slot; - __u8 sct_fw; - __u8 sc_fw; - __le16 vndr_assign_fw_commit_rc; - }; - -**Members** - -``old_fw_rev`` - Old Firmware Revision - -``new_fw_rev`` - New Firmware Revision - -``fw_commit_action`` - Firmware Commit Action - -``fw_slot`` - Firmware Slot - -``sct_fw`` - Status Code Type for Firmware Commit Command - -``sc_fw`` - Status Returned for Firmware Commit Command - -``vndr_assign_fw_commit_rc`` - Vendor Assigned Firmware Commit Result Code - - - - - -.. c:struct:: nvme_time_stamp_change_event - - Timestamp Change Event - -**Definition** - -:: - - struct nvme_time_stamp_change_event { - __le64 previous_timestamp; - __le64 ml_secs_since_reset; - }; - -**Members** - -``previous_timestamp`` - Previous Timestamp - -``ml_secs_since_reset`` - Milliseconds Since Reset - - - - - -.. c:struct:: nvme_power_on_reset_info_list - - Controller Reset Information - -**Definition** - -:: - - struct nvme_power_on_reset_info_list { - __le16 cid; - __u8 fw_act; - __u8 op_in_prog; - __u8 rsvd4[12]; - __le32 ctrl_power_cycle; - __le64 power_on_ml_seconds; - __le64 ctrl_time_stamp; - }; - -**Members** - -``cid`` - Controller ID - -``fw_act`` - Firmware Activation - -``op_in_prog`` - Operation in Progress - -``rsvd4`` - Reserved - -``ctrl_power_cycle`` - Controller Power Cycle - -``power_on_ml_seconds`` - Power on milliseconds - -``ctrl_time_stamp`` - Controller Timestamp - - - - - -.. c:struct:: nvme_nss_hw_err_event - - NVM Subsystem Hardware Error Event - -**Definition** - -:: - - struct nvme_nss_hw_err_event { - __le16 nss_hw_err_event_code; - __u8 rsvd2[2]; - __u8 *add_hw_err_info; - }; - -**Members** - -``nss_hw_err_event_code`` - NVM Subsystem Hardware Error Event Code - -``rsvd2`` - Reserved - -``add_hw_err_info`` - Additional Hardware Error Information - - - - - -.. c:struct:: nvme_change_ns_event - - Change Namespace Event Data - -**Definition** - -:: - - struct nvme_change_ns_event { - __le32 nsmgt_cdw10; - __u8 rsvd4[4]; - __le64 nsze; - __u8 rsvd16[8]; - __le64 nscap; - __u8 flbas; - __u8 dps; - __u8 nmic; - __u8 rsvd35; - __le32 ana_grp_id; - __le16 nvmset_id; - __le16 rsvd42; - __le32 nsid; - }; - -**Members** - -``nsmgt_cdw10`` - Namespace Management CDW10 - -``rsvd4`` - Reserved - -``nsze`` - Namespace Size - -``rsvd16`` - Reserved - -``nscap`` - Namespace Capacity - -``flbas`` - Formatted LBA Size - -``dps`` - End-to-end Data Protection Type Settings - -``nmic`` - Namespace Multi-path I/O and Namespace Sharing Capabilities - -``rsvd35`` - Reserved - -``ana_grp_id`` - ANA Group Identifier - -``nvmset_id`` - NVM Set Identifier - -``rsvd42`` - Reserved - -``nsid`` - Namespace ID - - - - - -.. c:struct:: nvme_format_nvm_start_event - - Format NVM Start Event Data - -**Definition** - -:: - - struct nvme_format_nvm_start_event { - __le32 nsid; - __u8 fna; - __u8 rsvd5[3]; - __le32 format_nvm_cdw10; - }; - -**Members** - -``nsid`` - Namespace Identifier - -``fna`` - Format NVM Attributes - -``rsvd5`` - Reserved - -``format_nvm_cdw10`` - Format NVM CDW10 - - - - - -.. c:struct:: nvme_format_nvm_compln_event - - Format NVM Completion Event Data - -**Definition** - -:: - - struct nvme_format_nvm_compln_event { - __le32 nsid; - __u8 smallest_fpi; - __u8 format_nvm_status; - __le16 compln_info; - __le32 status_field; - }; - -**Members** - -``nsid`` - Namespace Identifier - -``smallest_fpi`` - Smallest Format Progress Indicator - -``format_nvm_status`` - Format NVM Status - -``compln_info`` - Completion Information - -``status_field`` - Status Field - - - - - -.. c:struct:: nvme_sanitize_start_event - - Sanitize Start Event Data - -**Definition** - -:: - - struct nvme_sanitize_start_event { - __le32 sani_cap; - __le32 sani_cdw10; - __le32 sani_cdw11; - }; - -**Members** - -``sani_cap`` - SANICAP - -``sani_cdw10`` - Sanitize CDW10 - -``sani_cdw11`` - Sanitize CDW11 - - - - - -.. c:struct:: nvme_sanitize_compln_event - - Sanitize Completion Event Data - -**Definition** - -:: - - struct nvme_sanitize_compln_event { - __le16 sani_prog; - __le16 sani_status; - __le16 cmpln_info; - __u8 rsvd6[2]; - }; - -**Members** - -``sani_prog`` - Sanitize Progress - -``sani_status`` - Sanitize Status - -``cmpln_info`` - Completion Information - -``rsvd6`` - Reserved - - - - - -.. c:struct:: nvme_set_feature_event - - Set Feature Event Data - -**Definition** - -:: - - struct nvme_set_feature_event { - __le32 layout; - __le32 cdw_mem[0]; - }; - -**Members** - -``layout`` - Set Feature Event Layout - -``cdw_mem`` - Command Dwords Memory buffer - - - - - -.. c:struct:: nvme_thermal_exc_event - - Thermal Excursion Event Data - -**Definition** - -:: - - struct nvme_thermal_exc_event { - __u8 over_temp; - __u8 threshold; - }; - -**Members** - -``over_temp`` - Over Temperature - -``threshold`` - temperature threshold - - - - - -.. c:struct:: nvme_lba_rd - - LBA Range Descriptor - -**Definition** - -:: - - struct nvme_lba_rd { - __le64 rslba; - __le32 rnlb; - __u8 rsvd12[4]; - }; - -**Members** - -``rslba`` - Range Starting LBA - -``rnlb`` - Range Number of Logical Blocks - -``rsvd12`` - Reserved - - - - - -.. c:struct:: nvme_lbas_ns_element - - LBA Status Log Namespace Element - -**Definition** - -:: - - struct nvme_lbas_ns_element { - __le32 neid; - __le32 nlrd; - __u8 ratype; - __u8 rsvd8[7]; - struct nvme_lba_rd lba_rd[]; - }; - -**Members** - -``neid`` - Namespace Element Identifier - -``nlrd`` - Number of LBA Range Descriptors - -``ratype`` - Recommended Action Type. see **enum** nvme_lba_status_atype - -``rsvd8`` - Reserved - -``lba_rd`` - LBA Range Descriptor - - - - - -.. c:enum:: nvme_lba_status_atype - - Potentially Unrecoverable LBAs - -**Constants** - -``NVME_LBA_STATUS_ATYPE_SCAN_UNTRACKED`` - Potentially Unrecoverable LBAs - -``NVME_LBA_STATUS_ATYPE_SCAN_TRACKED`` - Potentially Unrecoverable LBAs - associated with physical storage - - - - -.. c:struct:: nvme_lba_status_log - - LBA Status Information Log - -**Definition** - -:: - - struct nvme_lba_status_log { - __le32 lslplen; - __le32 nlslne; - __le32 estulb; - __u8 rsvd12[2]; - __le16 lsgc; - struct nvme_lbas_ns_element elements[]; - }; - -**Members** - -``lslplen`` - LBA Status Log Page Length - -``nlslne`` - Number of LBA Status Log Namespace Elements - -``estulb`` - Estimate of Unrecoverable Logical Blocks - -``rsvd12`` - Reserved - -``lsgc`` - LBA Status Generation Counter - -``elements`` - LBA Status Log Namespace Element List - - - - - -.. c:struct:: nvme_eg_event_aggregate_log - - Endurance Group Event Aggregate - -**Definition** - -:: - - struct nvme_eg_event_aggregate_log { - __le64 nr_entries; - __le16 egids[]; - }; - -**Members** - -``nr_entries`` - Number of Entries - -``egids`` - Endurance Group Identifier - - - - - -.. c:enum:: nvme_fid_supported_effects - - FID Supported and Effects Data Structure definitions - -**Constants** - -``NVME_FID_SUPPORTED_EFFECTS_FSUPP`` - FID Supported - -``NVME_FID_SUPPORTED_EFFECTS_UDCC`` - User Data Content Change - -``NVME_FID_SUPPORTED_EFFECTS_NCC`` - Namespace Capability Change - -``NVME_FID_SUPPORTED_EFFECTS_NIC`` - Namespace Inventory Change - -``NVME_FID_SUPPORTED_EFFECTS_CCC`` - Controller Capability Change - -``NVME_FID_SUPPORTED_EFFECTS_UUID_SEL`` - UUID Selection Supported - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_SHIFT`` - FID Scope Shift - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_MASK`` - FID Scope Mask - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_NS`` - Namespace Scope - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_CTRL`` - Controller Scope - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_NVM_SET`` - NVM Set Scope - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_ENDGRP`` - Endurance Group Scope - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_DOMAIN`` - Domain Scope - -``NVME_FID_SUPPORTED_EFFECTS_SCOPE_NSS`` - NVM Subsystem Scope - - - - -.. c:struct:: nvme_fid_supported_effects_log - - Feature Identifiers Supported and Effects - -**Definition** - -:: - - struct nvme_fid_supported_effects_log { - __le32 fid_support[NVME_LOG_FID_SUPPORTED_EFFECTS_MAX]; - }; - -**Members** - -``fid_support`` - Feature Identifier Supported - - - - - -.. c:enum:: nvme_mi_cmd_supported_effects - - MI Command Supported and Effects Data Structure - -**Constants** - -``NVME_MI_CMD_SUPPORTED_EFFECTS_CSUPP`` - Command Supported - -``NVME_MI_CMD_SUPPORTED_EFFECTS_UDCC`` - User Data Content Change - -``NVME_MI_CMD_SUPPORTED_EFFECTS_NCC`` - Namespace Capability Change - -``NVME_MI_CMD_SUPPORTED_EFFECTS_NIC`` - Namespace Inventory Change - -``NVME_MI_CMD_SUPPORTED_EFFECTS_CCC`` - Controller Capability Change - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_SHIFT`` - 20 bit shift - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_MASK`` - 12 bit mask - 0xfff - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_NS`` - Namespace Scope - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_CTRL`` - Controller Scope - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_NVM_SET`` - NVM Set Scope - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_ENDGRP`` - Endurance Group Scope - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_DOMAIN`` - Domain Scope - -``NVME_MI_CMD_SUPPORTED_EFFECTS_SCOPE_NSS`` - NVM Subsystem Scope - - - - -.. c:struct:: nvme_mi_cmd_supported_effects_log - - NVMe-MI Commands Supported and Effects Log - -**Definition** - -:: - - struct nvme_mi_cmd_supported_effects_log { - __le32 mi_cmd_support[NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_MAX]; - __le32 reserved1[NVME_LOG_MI_CMD_SUPPORTED_EFFECTS_RESERVED]; - }; - -**Members** - -``mi_cmd_support`` - NVMe-MI Commands Supported - -``reserved1`` - Reserved - - - - - -.. c:struct:: nvme_boot_partition - - Boot Partition Log - -**Definition** - -:: - - struct nvme_boot_partition { - __u8 lid; - __u8 rsvd1[3]; - __le32 bpinfo; - __u8 rsvd8[8]; - __u8 boot_partition_data[]; - }; - -**Members** - -``lid`` - Boot Partition Identifier - -``rsvd1`` - Reserved - -``bpinfo`` - Boot Partition Information - -``rsvd8`` - Reserved - -``boot_partition_data`` - Contains the contents of the - specified Boot Partition - - - - - -.. c:struct:: nvme_media_unit_stat_desc - - Media Unit Status Descriptor - -**Definition** - -:: - - struct nvme_media_unit_stat_desc { - __le16 muid; - __le16 domainid; - __le16 endgid; - __le16 nvmsetid; - __le16 cap_adj_fctr; - __u8 avl_spare; - __u8 percent_used; - __u8 mucs; - __u8 cio; - }; - -**Members** - -``muid`` - Media Unit Identifier - -``domainid`` - Domain Identifier - -``endgid`` - Endurance Group Identifier - -``nvmsetid`` - NVM Set Identifier - -``cap_adj_fctr`` - Capacity Adjustment Factor - -``avl_spare`` - Available Spare - -``percent_used`` - Percentage Used - -``mucs`` - Number of Channels attached to media units - -``cio`` - Channel Identifiers Offset - - - - - -.. c:struct:: nvme_media_unit_stat_log - - Media Unit Status - -**Definition** - -:: - - struct nvme_media_unit_stat_log { - __le16 nmu; - __le16 cchans; - __le16 sel_config; - __u8 rsvd6[10]; - struct nvme_media_unit_stat_desc mus_desc[]; - }; - -**Members** - -``nmu`` - Number unit status descriptor - -``cchans`` - Number of Channels - -``sel_config`` - Selected Configuration - -``rsvd6`` - Reserved - -``mus_desc`` - Media unit statistic descriptors - - - - - -.. c:struct:: nvme_media_unit_config_desc - - Media Unit Configuration Descriptor - -**Definition** - -:: - - struct nvme_media_unit_config_desc { - __le16 muid; - __u8 rsvd2[4]; - __le16 mudl; - }; - -**Members** - -``muid`` - Media Unit Identifier - -``rsvd2`` - Reserved - -``mudl`` - Media Unit Descriptor Length - - - - - -.. c:struct:: nvme_channel_config_desc - - Channel Configuration Descriptor - -**Definition** - -:: - - struct nvme_channel_config_desc { - __le16 chanid; - __le16 chmus; - struct nvme_media_unit_config_desc mu_config_desc[]; - }; - -**Members** - -``chanid`` - Channel Identifier - -``chmus`` - Number Channel Media Units - -``mu_config_desc`` - Channel Unit config descriptors. - See **struct** nvme_media_unit_config_desc - - - - - -.. c:struct:: nvme_end_grp_chan_desc - - Endurance Group Channel Configuration Descriptor - -**Definition** - -:: - - struct nvme_end_grp_chan_desc { - __le16 egchans; - struct nvme_channel_config_desc chan_config_desc[]; - }; - -**Members** - -``egchans`` - Number of Channels - -``chan_config_desc`` - Channel config descriptors. - See **struct** nvme_channel_config_desc - - - - - -.. c:struct:: nvme_end_grp_config_desc - - Endurance Group Configuration Descriptor - -**Definition** - -:: - - struct nvme_end_grp_config_desc { - __le16 endgid; - __le16 cap_adj_factor; - __u8 rsvd4[12]; - __u8 tegcap[16]; - __u8 segcap[16]; - __u8 end_est[16]; - __u8 rsvd64[16]; - __le16 egsets; - __le16 nvmsetid[]; - }; - -**Members** - -``endgid`` - Endurance Group Identifier - -``cap_adj_factor`` - Capacity Adjustment Factor - -``rsvd4`` - Reserved - -``tegcap`` - Total Endurance Group Capacity - -``segcap`` - Spare Endurance Group Capacity - -``end_est`` - Endurance Estimate - -``rsvd64`` - Reserved - -``egsets`` - Number of NVM Sets - -``nvmsetid`` - NVM Set Identifier - - - - - -.. c:struct:: nvme_capacity_config_desc - - Capacity Configuration structure definitions - -**Definition** - -:: - - struct nvme_capacity_config_desc { - __le16 cap_config_id; - __le16 domainid; - __le16 egcn; - __u8 rsvd6[26]; - struct nvme_end_grp_config_desc egcd[]; - }; - -**Members** - -``cap_config_id`` - Capacity Configuration Identifier - -``domainid`` - Domain Identifier - -``egcn`` - Number Endurance Group Configuration - Descriptors - -``rsvd6`` - Reserved - -``egcd`` - Endurance Group Config descriptors. - See **struct** nvme_end_grp_config_desc - - - - - -.. c:struct:: nvme_supported_cap_config_list_log - - Supported Capacity Configuration list log page - -**Definition** - -:: - - struct nvme_supported_cap_config_list_log { - __u8 sccn; - __u8 rsvd1[15]; - struct nvme_capacity_config_desc cap_config_desc[]; - }; - -**Members** - -``sccn`` - Number of capacity configuration - -``rsvd1`` - Reserved - -``cap_config_desc`` - Capacity configuration descriptor. - See **struct** nvme_capacity_config_desc - - - - - -.. c:struct:: nvme_resv_notification_log - - Reservation Notification Log - -**Definition** - -:: - - struct nvme_resv_notification_log { - __le64 lpc; - __u8 rnlpt; - __u8 nalp; - __u8 rsvd9[2]; - __le32 nsid; - __u8 rsvd16[48]; - }; - -**Members** - -``lpc`` - Log Page Count - -``rnlpt`` - See :c:type:`enum nvme_resv_notify_rnlpt `. - -``nalp`` - Number of Available Log Pages - -``rsvd9`` - Reserved - -``nsid`` - Namespace ID - -``rsvd16`` - Reserved - - - - - -.. c:enum:: nvme_resv_notify_rnlpt - - Reservation Notification Log - Reservation Notification Log Page Type - -**Constants** - -``NVME_RESV_NOTIFY_RNLPT_EMPTY`` - Empty Log Page - -``NVME_RESV_NOTIFY_RNLPT_REGISTRATION_PREEMPTED`` - Registration Preempted - -``NVME_RESV_NOTIFY_RNLPT_RESERVATION_RELEASED`` - Reservation Released - -``NVME_RESV_NOTIFY_RNLPT_RESERVATION_PREEMPTED`` - Reservation Preempted - - - - -.. c:struct:: nvme_sanitize_log_page - - Sanitize Status (Log Identifier 81h) - -**Definition** - -:: - - struct nvme_sanitize_log_page { - __le16 sprog; - __le16 sstat; - __le32 scdw10; - __le32 eto; - __le32 etbe; - __le32 etce; - __le32 etond; - __le32 etbend; - __le32 etcend; - __u8 rsvd32[480]; - }; - -**Members** - -``sprog`` - Sanitize Progress (SPROG): indicates the fraction complete of the - sanitize operation. The value is a numerator of the fraction - complete that has 65,536 (10000h) as its denominator. This value - shall be set to FFFFh if the **sstat** field is not set to - ``NVME_SANITIZE_SSTAT_STATUS_IN_PROGESS``. - -``sstat`` - Sanitize Status (SSTAT): indicates the status associated with - the most recent sanitize operation. See :c:type:`enum nvme_sanitize_sstat `. - -``scdw10`` - Sanitize Command Dword 10 Information (SCDW10): contains the value - of the Command Dword 10 field of the Sanitize command that started - the sanitize operation. - -``eto`` - Estimated Time For Overwrite: indicates the number of seconds required - to complete an Overwrite sanitize operation with 16 passes in - the background when the No-Deallocate Modifies Media After Sanitize - field is not set to 10b. A value of 0h indicates that the sanitize - operation is expected to be completed in the background when the - Sanitize command that started that operation is completed. A value - of FFFFFFFFh indicates that no time period is reported. - -``etbe`` - Estimated Time For Block Erase: indicates the number of seconds - required to complete a Block Erase sanitize operation in the - background when the No-Deallocate Modifies Media After Sanitize - field is not set to 10b. A value of 0h indicates that the sanitize - operation is expected to be completed in the background when the - Sanitize command that started that operation is completed. - A value of FFFFFFFFh indicates that no time period is reported. - -``etce`` - Estimated Time For Crypto Erase: indicates the number of seconds - required to complete a Crypto Erase sanitize operation in the - background when the No-Deallocate Modifies Media After Sanitize - field is not set to 10b. A value of 0h indicates that the sanitize - operation is expected to be completed in the background when the - Sanitize command that started that operation is completed. - A value of FFFFFFFFh indicates that no time period is reported. - -``etond`` - Estimated Time For Overwrite With No-Deallocate Media Modification: - indicates the number of seconds required to complete an Overwrite - sanitize operation and the associated additional media modification - after the Overwrite sanitize operation in the background when - the No-Deallocate After Sanitize bit was set to 1 in the Sanitize - command that requested the Overwrite sanitize operation; and - the No-Deallocate Modifies Media After Sanitize field is set to 10b. - A value of 0h indicates that the sanitize operation is expected - to be completed in the background when the Sanitize command that - started that operation is completed. A value of FFFFFFFFh indicates - that no time period is reported. - -``etbend`` - Estimated Time For Block Erase With No-Deallocate Media Modification: - indicates the number of seconds required to complete a Block Erase - sanitize operation and the associated additional media modification - after the Block Erase sanitize operation in the background when - the No-Deallocate After Sanitize bit was set to 1 in the Sanitize - command that requested the Overwrite sanitize operation; and - the No-Deallocate Modifies Media After Sanitize field is set to 10b. - A value of 0h indicates that the sanitize operation is expected - to be completed in the background when the Sanitize command that - started that operation is completed. A value of FFFFFFFFh indicates - that no time period is reported. - -``etcend`` - Estimated Time For Crypto Erase With No-Deallocate Media Modification: - indicates the number of seconds required to complete a Crypto Erase - sanitize operation and the associated additional media modification - after the Crypto Erase sanitize operation in the background when - the No-Deallocate After Sanitize bit was set to 1 in the Sanitize - command that requested the Overwrite sanitize operation; and - the No-Deallocate Modifies Media After Sanitize field is set to 10b. - A value of 0h indicates that the sanitize operation is expected - to be completed in the background when the Sanitize command that - started that operation is completed. A value of FFFFFFFFh indicates - that no time period is reported. - -``rsvd32`` - Reserved - - - - - -.. c:enum:: nvme_sanitize_sstat - - Sanitize Status (SSTAT) - -**Constants** - -``NVME_SANITIZE_SSTAT_STATUS_SHIFT`` - Shift amount to get the status value of - the most recent sanitize operation from - the :c:type:`struct nvme_sanitize_log_page `.sstat - field. - -``NVME_SANITIZE_SSTAT_STATUS_MASK`` - Mask to get the status value of the most - recent sanitize operation. - -``NVME_SANITIZE_SSTAT_STATUS_NEVER_SANITIZED`` - The NVM subsystem has never been - sanitized. - -``NVME_SANITIZE_SSTAT_STATUS_COMPLETE_SUCCESS`` - The most recent sanitize operation - completed successfully including any - additional media modification. - -``NVME_SANITIZE_SSTAT_STATUS_IN_PROGESS`` - A sanitize operation is currently in progress. - -``NVME_SANITIZE_SSTAT_STATUS_COMPLETED_FAILED`` - The most recent sanitize operation - failed. - -``NVME_SANITIZE_SSTAT_STATUS_ND_COMPLETE_SUCCESS`` - The most recent sanitize operation - for which No-Deallocate After Sanitize was - requested has completed successfully with - deallocation of all user data. - -``NVME_SANITIZE_SSTAT_COMPLETED_PASSES_SHIFT`` - Shift amount to get the number - of completed passes if the most recent - sanitize operation was an Overwrite. This - value shall be cleared to 0h if the most - recent sanitize operation was not - an Overwrite. - -``NVME_SANITIZE_SSTAT_COMPLETED_PASSES_MASK`` - Mask to get the number of completed - passes. - -``NVME_SANITIZE_SSTAT_GLOBAL_DATA_ERASED_SHIFT`` - Shift amount to get the Global - Data Erased value from the - :c:type:`struct nvme_sanitize_log_page `.sstat field. - -``NVME_SANITIZE_SSTAT_GLOBAL_DATA_ERASED_MASK`` - Mask to get the Global Data Erased - value. - -``NVME_SANITIZE_SSTAT_GLOBAL_DATA_ERASED`` - Global Data Erased: if set, then no - namespace user data in the NVM subsystem - has been written to and no Persistent - Memory Region in the NVM subsystem has - been enabled since being manufactured and - the NVM subsystem has never been sanitized; - or since the most recent successful sanitize - operation. - - - - -.. c:struct:: nvme_zns_changed_zone_log - - ZNS Changed Zone List log - -**Definition** - -:: - - struct nvme_zns_changed_zone_log { - __le16 nrzid; - __u8 rsvd2[6]; - __le64 zid[NVME_ZNS_CHANGED_ZONES_MAX]; - }; - -**Members** - -``nrzid`` - Number of Zone Identifiers - -``rsvd2`` - Reserved - -``zid`` - Zone Identifier - - - - - -.. c:enum:: nvme_zns_zt - - Zone Descriptor Data Structure - Zone Type - -**Constants** - -``NVME_ZONE_TYPE_SEQWRITE_REQ`` - Sequential Write Required - - - - -.. c:enum:: nvme_zns_za - - Zone Descriptor Data Structure - -**Constants** - -``NVME_ZNS_ZA_ZFC`` - Zone Finished by Controller - -``NVME_ZNS_ZA_FZR`` - Finish Zone Recommended - -``NVME_ZNS_ZA_RZR`` - Reset Zone Recommended - -``NVME_ZNS_ZA_ZRWAV`` - -``NVME_ZNS_ZA_ZDEV`` - Zone Descriptor Extension Valid - - - - -.. c:enum:: nvme_zns_zs - - Zone Descriptor Data Structure - Zone State - -**Constants** - -``NVME_ZNS_ZS_EMPTY`` - Empty state - -``NVME_ZNS_ZS_IMPL_OPEN`` - Implicitly open state - -``NVME_ZNS_ZS_EXPL_OPEN`` - Explicitly open state - -``NVME_ZNS_ZS_CLOSED`` - Closed state - -``NVME_ZNS_ZS_READ_ONLY`` - Read only state - -``NVME_ZNS_ZS_FULL`` - Full state - -``NVME_ZNS_ZS_OFFLINE`` - Offline state - - - - -.. c:struct:: nvme_zns_desc - - Zone Descriptor Data Structure - -**Definition** - -:: - - struct nvme_zns_desc { - __u8 zt; - __u8 zs; - __u8 za; - __u8 zai; - __u8 rsvd4[4]; - __le64 zcap; - __le64 zslba; - __le64 wp; - __u8 rsvd32[32]; - }; - -**Members** - -``zt`` - Zone Type - -``zs`` - Zone State - -``za`` - Zone Attributes - -``zai`` - Zone Attributes Information - -``rsvd4`` - Reserved - -``zcap`` - Zone Capacity - -``zslba`` - Zone Start Logical Block Address - -``wp`` - Write Pointer - -``rsvd32`` - Reserved - - - - - -.. c:struct:: nvme_zone_report - - Report Zones Data Structure - -**Definition** - -:: - - struct nvme_zone_report { - __le64 nr_zones; - __u8 rsvd8[56]; - struct nvme_zns_desc entries[]; - }; - -**Members** - -``nr_zones`` - Number of descriptors in **entries** - -``rsvd8`` - Reserved - -``entries`` - Zoned namespace descriptors - - - - - -.. c:struct:: nvme_lba_status_desc - - LBA Status Descriptor Entry - -**Definition** - -:: - - struct nvme_lba_status_desc { - __le64 dslba; - __le32 nlb; - __u8 rsvd12; - __u8 status; - __u8 rsvd14[2]; - }; - -**Members** - -``dslba`` - Descriptor Starting LBA - -``nlb`` - Number of Logical Blocks - -``rsvd12`` - Reserved - -``status`` - Additional status about this LBA range - -``rsvd14`` - Reserved - - - - - -.. c:struct:: nvme_lba_status - - LBA Status Descriptor List - -**Definition** - -:: - - struct nvme_lba_status { - __le32 nlsd; - __u8 cmpc; - __u8 rsvd5[3]; - struct nvme_lba_status_desc descs[]; - }; - -**Members** - -``nlsd`` - Number of LBA Status Descriptors - -``cmpc`` - Completion Condition - -``rsvd5`` - Reserved - -``descs`` - LBA status descriptor Entry - - - - - -.. c:struct:: nvme_feat_auto_pst - - Autonomous Power State Transition - -**Definition** - -:: - - struct nvme_feat_auto_pst { - __le64 apst_entry[32]; - }; - -**Members** - -``apst_entry`` - See :c:type:`enum nvme_apst_entry ` - - - - - -.. c:enum:: nvme_apst_entry - - Autonomous Power State Transition - -**Constants** - -``NVME_APST_ENTRY_ITPS_SHIFT`` - Idle Transition Power State Shift - -``NVME_APST_ENTRY_ITPT_SHIFT`` - Idle Time Prior to Transition Shift - -``NVME_APST_ENTRY_ITPS_MASK`` - Idle Transition Power State Mask - -``NVME_APST_ENTRY_ITPT_MASK`` - Idle Time Prior to Transition Mask - - - - -.. c:struct:: nvme_metadata_element_desc - - Metadata Element Descriptor - -**Definition** - -:: - - struct nvme_metadata_element_desc { - __u8 type; - __u8 rev; - __u16 len; - __u8 val[0]; - }; - -**Members** - -``type`` - Element Type (ET) - -``rev`` - Element Revision (ER) - -``len`` - Element Length (ELEN) - -``val`` - Element Value (EVAL), UTF-8 string - - - - - -.. c:struct:: nvme_host_metadata - - Host Metadata Data Structure - -**Definition** - -:: - - struct nvme_host_metadata { - __u8 ndesc; - __u8 rsvd1; - union { - struct nvme_metadata_element_desc descs[0]; - __u8 descs_buf[4094]; - }; - }; - -**Members** - -``ndesc`` - Number of metadata element descriptors - -``rsvd1`` - Reserved - -``{unnamed_union}`` - anonymous - -``descs`` - Metadata element descriptors - -``descs_buf`` - Metadata element descriptor buffer - - - - - -.. c:enum:: nvme_ctrl_metadata_type - - Controller Metadata Element Types - -**Constants** - -``NVME_CTRL_METADATA_OS_CTRL_NAME`` - Name of the controller in - the operating system. - -``NVME_CTRL_METADATA_OS_DRIVER_NAME`` - Name of the driver in the - operating system. - -``NVME_CTRL_METADATA_OS_DRIVER_VER`` - Version of the driver in - the operating system. - -``NVME_CTRL_METADATA_PRE_BOOT_CTRL_NAME`` - Name of the controller in - the pre-boot environment. - -``NVME_CTRL_METADATA_PRE_BOOT_DRIVER_NAME`` - Name of the driver in the - pre-boot environment. - -``NVME_CTRL_METADATA_PRE_BOOT_DRIVER_VER`` - Version of the driver in the - pre-boot environment. - -``NVME_CTRL_METADATA_SYS_PROC_MODEL`` - Model of the processor. - -``NVME_CTRL_METADATA_CHIPSET_DRV_NAME`` - Chipset driver name. - -``NVME_CTRL_METADATA_CHIPSET_DRV_VERSION`` - Chipset driver version. - -``NVME_CTRL_METADATA_OS_NAME_AND_BUILD`` - Operating system name and build. - -``NVME_CTRL_METADATA_SYS_PROD_NAME`` - System product name. - -``NVME_CTRL_METADATA_FIRMWARE_VERSION`` - Host firmware (e.g UEFI) version. - -``NVME_CTRL_METADATA_OS_DRIVER_FILENAME`` - Operating system driver filename. - -``NVME_CTRL_METADATA_DISPLAY_DRV_NAME`` - Display driver name. - -``NVME_CTRL_METADATA_DISPLAY_DRV_VERSION`` - Display driver version. - -``NVME_CTRL_METADATA_HOST_DET_FAIL_REC`` - Failure record. - - - - -.. c:enum:: nvme_ns_metadata_type - - Namespace Metadata Element Types - -**Constants** - -``NVME_NS_METADATA_OS_NS_NAME`` - Name of the namespace in the - operating system - -``NVME_NS_METADATA_PRE_BOOT_NS_NAME`` - Name of the namespace in the pre-boot - environment. - -``NVME_NS_METADATA_OS_NS_QUAL_1`` - First qualifier of the Operating System - Namespace Name. - -``NVME_NS_METADATA_OS_NS_QUAL_2`` - Second qualifier of the Operating System - Namespace Name. - - - - -.. c:struct:: nvme_timestamp - - Timestamp - Data Structure for Get Features - -**Definition** - -:: - - struct nvme_timestamp { - __u8 timestamp[6]; - __u8 attr; - __u8 rsvd; - }; - -**Members** - -``timestamp`` - Timestamp value based on origin and synch field - -``attr`` - Attribute - -``rsvd`` - Reserved - - - - - -.. c:struct:: nvme_lba_range_type_entry - - LBA Range Type - Data Structure Entry - -**Definition** - -:: - - struct nvme_lba_range_type_entry { - __u8 type; - __u8 attributes; - __u8 rsvd2[14]; - __u64 slba; - __u64 nlb; - __u8 guid[16]; - __u8 rsvd48[16]; - }; - -**Members** - -``type`` - Specifies the Type of the LBA range - -``attributes`` - Specifies attributes of the LBA range - -``rsvd2`` - Reserved - -``slba`` - Starting LBA - -``nlb`` - Number of Logical Blocks - -``guid`` - Unique Identifier - -``rsvd48`` - Reserved - - - - - -.. c:enum:: nvme_lbart - - LBA Range Type - Data Structure Entry - -**Constants** - -``NVME_LBART_TYPE_GP`` - General Purpose - -``NVME_LBART_TYPE_FS`` - Filesystem - -``NVME_LBART_TYPE_RAID`` - RAID - -``NVME_LBART_TYPE_CACHE`` - Cache - -``NVME_LBART_TYPE_SWAP`` - Page / swap file - -``NVME_LBART_ATTRIB_TEMP`` - Temp - -``NVME_LBART_ATTRIB_HIDE`` - Hidden - - - - -.. c:struct:: nvme_lba_range_type - - LBA Range Type - -**Definition** - -:: - - struct nvme_lba_range_type { - struct nvme_lba_range_type_entry entry[NVME_FEAT_LBA_RANGE_MAX]; - }; - -**Members** - -``entry`` - LBA range type entry. See **struct** nvme_lba_range_type_entry - - - - - -.. c:struct:: nvme_plm_config - - Predictable Latency Mode - Deterministic Threshold Configuration Data Structure - -**Definition** - -:: - - struct nvme_plm_config { - __le16 ee; - __u8 rsvd2[30]; - __le64 dtwinrt; - __le64 dtwinwt; - __le64 dtwintt; - __u8 rsvd56[456]; - }; - -**Members** - -``ee`` - Enable Event - -``rsvd2`` - Reserved - -``dtwinrt`` - DTWIN Reads Threshold - -``dtwinwt`` - DTWIN Writes Threshold - -``dtwintt`` - DTWIN Time Threshold - -``rsvd56`` - Reserved - - - - - -.. c:struct:: nvme_feat_host_behavior - - Host Behavior Support - Data Structure - -**Definition** - -:: - - struct nvme_feat_host_behavior { - __u8 acre; - __u8 rsvd1[511]; - }; - -**Members** - -``acre`` - Advanced Command Retry Enable - -``rsvd1`` - Reserved - - - - - -.. c:enum:: nvme_host_behavior_support - - Enable Advanced Command - -**Constants** - -``NVME_ENABLE_ACRE`` - Enable Advanced Command Retry Enable - - - - -.. c:struct:: nvme_dsm_range - - Dataset Management - Range Definition - -**Definition** - -:: - - struct nvme_dsm_range { - __le32 cattr; - __le32 nlb; - __le64 slba; - }; - -**Members** - -``cattr`` - Context Attributes - -``nlb`` - Length in logical blocks - -``slba`` - Starting LBA - - - - - -.. c:struct:: nvme_copy_range - - Copy - Source Range Entries Descriptor Format - -**Definition** - -:: - - struct nvme_copy_range { - __u8 rsvd0[8]; - __le64 slba; - __le16 nlb; - __u8 rsvd18[6]; - __le32 eilbrt; - __le16 elbatm; - __le16 elbat; - }; - -**Members** - -``rsvd0`` - Reserved - -``slba`` - Starting LBA - -``nlb`` - Number of Logical Blocks - -``rsvd18`` - Reserved - -``eilbrt`` - Expected Initial Logical Block Reference Tag / - Expected Logical Block Storage Tag - -``elbatm`` - Expected Logical Block Application Tag Mask - -``elbat`` - Expected Logical Block Application Tag - - - - - -.. c:struct:: nvme_copy_range_f1 - - Copy - Source Range Entries Descriptor Format 1h - -**Definition** - -:: - - struct nvme_copy_range_f1 { - __u8 rsvd0[8]; - __le64 slba; - __le16 nlb; - __u8 rsvd18[8]; - __u8 elbt[10]; - __le16 elbatm; - __le16 elbat; - }; - -**Members** - -``rsvd0`` - Reserved - -``slba`` - Starting LBA - -``nlb`` - Number of Logical Blocks - -``rsvd18`` - Reserved - -``elbt`` - Expected Initial Logical Block Reference Tag / - Expected Logical Block Storage Tag - -``elbatm`` - Expected Logical Block Application Tag Mask - -``elbat`` - Expected Logical Block Application Tag - - - - - -.. c:struct:: nvme_registered_ctrl - - Registered Controller Data Structure - -**Definition** - -:: - - struct nvme_registered_ctrl { - __le16 cntlid; - __u8 rcsts; - __u8 rsvd3[5]; - __le64 hostid; - __le64 rkey; - }; - -**Members** - -``cntlid`` - Controller ID - -``rcsts`` - Reservation Status - -``rsvd3`` - Reserved - -``hostid`` - Host Identifier - -``rkey`` - Reservation Key - - - - - -.. c:struct:: nvme_registered_ctrl_ext - - Registered Controller Extended Data Structure - -**Definition** - -:: - - struct nvme_registered_ctrl_ext { - __le16 cntlid; - __u8 rcsts; - __u8 rsvd3[5]; - __le64 rkey; - __u8 hostid[16]; - __u8 rsvd32[32]; - }; - -**Members** - -``cntlid`` - Controller ID - -``rcsts`` - Reservation Status - -``rsvd3`` - Reserved - -``rkey`` - Reservation Key - -``hostid`` - Host Identifier - -``rsvd32`` - Reserved - - - - - -.. c:struct:: nvme_resv_status - - Reservation Status Data Structure - -**Definition** - -:: - - struct nvme_resv_status { - __le32 gen; - __u8 rtype; - __u8 regctl[2]; - __u8 rsvd7[2]; - __u8 ptpls; - __u8 rsvd10[14]; - union { - struct { - __u8 rsvd24[40]; - struct nvme_registered_ctrl_ext regctl_eds[0]; - }; - struct nvme_registered_ctrl regctl_ds[0]; - }; - }; - -**Members** - -``gen`` - Generation - -``rtype`` - Reservation Type - -``regctl`` - Number of Registered Controllers - -``rsvd7`` - Reserved - -``ptpls`` - Persist Through Power Loss State - -``rsvd10`` - Reserved - -``{unnamed_union}`` - anonymous - -``{unnamed_struct}`` - anonymous - -``rsvd24`` - Reserved - -``regctl_eds`` - Registered Controller Extended Data Structure - -``regctl_ds`` - Registered Controller Data Structure - - - - - -.. c:struct:: nvme_streams_directive_params - - Streams Directive - Return Parameters Data Structure - -**Definition** - -:: - - struct nvme_streams_directive_params { - __le16 msl; - __le16 nssa; - __le16 nsso; - __u8 nssc; - __u8 rsvd[9]; - __le32 sws; - __le16 sgs; - __le16 nsa; - __le16 nso; - __u8 rsvd2[6]; - }; - -**Members** - -``msl`` - Max Streams Limit - -``nssa`` - NVM Subsystem Streams Available - -``nsso`` - NVM Subsystem Streams Open - -``nssc`` - NVM Subsystem Stream Capability - -``rsvd`` - Reserved - -``sws`` - Stream Write Size - -``sgs`` - Stream Granularity Size - -``nsa`` - Namespace Streams Allocated - -``nso`` - Namespace Streams Open - -``rsvd2`` - Reserved - - - - - -.. c:struct:: nvme_streams_directive_status - - Streams Directive - Get Status Data Structure - -**Definition** - -:: - - struct nvme_streams_directive_status { - __le16 osc; - __le16 sid[]; - }; - -**Members** - -``osc`` - Open Stream Count - -``sid`` - Stream Identifier - - - - - -.. c:struct:: nvme_id_directives - - Identify Directive - Return Parameters Data Structure - -**Definition** - -:: - - struct nvme_id_directives { - __u8 supported[32]; - __u8 enabled[32]; - __u8 rsvd64[4032]; - }; - -**Members** - -``supported`` - Identify directive is supported - -``enabled`` - Identify directive is Enabled - -``rsvd64`` - Reserved - - - - - -.. c:enum:: nvme_directive_types - - Directives Supported or Enabled - -**Constants** - -``NVME_ID_DIR_ID_BIT`` - Identify directive is supported - -``NVME_ID_DIR_SD_BIT`` - Streams directive is supported - - - - -.. c:struct:: nvme_host_mem_buf_attrs - - Host Memory Buffer - Attributes Data Structure - -**Definition** - -:: - - struct nvme_host_mem_buf_attrs { - __le32 hsize; - __le32 hmdlal; - __le32 hmdlau; - __le32 hmdlec; - __u8 rsvd16[4080]; - }; - -**Members** - -``hsize`` - Host Memory Buffer Size - -``hmdlal`` - Host Memory Descriptor List Lower Address - -``hmdlau`` - Host Memory Descriptor List Upper Address - -``hmdlec`` - Host Memory Descriptor List Entry Count - -``rsvd16`` - Reserved - - - - - -.. c:enum:: nvme_ae_type - - Asynchronous Event Type - -**Constants** - -``NVME_AER_ERROR`` - Error event - -``NVME_AER_SMART`` - SMART / Health Status event - -``NVME_AER_NOTICE`` - Notice event - -``NVME_AER_CSS`` - NVM Command Set Specific events - -``NVME_AER_VS`` - Vendor Specific event - - - - -.. c:enum:: nvme_ae_info_error - - Asynchronous Event Information - Error Status - -**Constants** - -``NVME_AER_ERROR_INVALID_DB_REG`` - Write to Invalid Doorbell Register - -``NVME_AER_ERROR_INVALID_DB_VAL`` - Invalid Doorbell Write Value - -``NVME_AER_ERROR_DIAG_FAILURE`` - Diagnostic Failure - -``NVME_AER_ERROR_PERSISTENT_INTERNAL_ERROR`` - Persistent Internal Error - -``NVME_AER_ERROR_TRANSIENT_INTERNAL_ERROR`` - Transient Internal Error - -``NVME_AER_ERROR_FW_IMAGE_LOAD_ERROR`` - Firmware Image Load Error - - - - -.. c:enum:: nvme_ae_info_smart - - Asynchronous Event Information - SMART / Health Status - -**Constants** - -``NVME_AER_SMART_SUBSYSTEM_RELIABILITY`` - NVM subsystem Reliability - -``NVME_AER_SMART_TEMPERATURE_THRESHOLD`` - Temperature Threshold - -``NVME_AER_SMART_SPARE_THRESHOLD`` - Spare Below Threshold - - - - -.. c:enum:: nvme_ae_info_css_nvm - - Asynchronous Event Information - I/O Command Specific Status - -**Constants** - -``NVME_AER_CSS_NVM_RESERVATION`` - Reservation Log Page Available - -``NVME_AER_CSS_NVM_SANITIZE_COMPLETED`` - Sanitize Operation Completed - -``NVME_AER_CSS_NVM_UNEXPECTED_SANITIZE_DEALLOC`` - Sanitize Operation Completed - With Unexpected Deallocation - - - - -.. c:enum:: nvme_ae_info_notice - - Asynchronous Event Information - Notice - -**Constants** - -``NVME_AER_NOTICE_NS_CHANGED`` - Namespace Attribute Changed - -``NVME_AER_NOTICE_FW_ACT_STARTING`` - Firmware Activation Starting - -``NVME_AER_NOTICE_TELEMETRY`` - Telemetry Log Changed - -``NVME_AER_NOTICE_ANA`` - Asymmetric Namespace Access Change - -``NVME_AER_NOTICE_PL_EVENT`` - Predictable Latency Event Aggregate Log Change - -``NVME_AER_NOTICE_LBA_STATUS_ALERT`` - LBA Status Information Alert - -``NVME_AER_NOTICE_EG_EVENT`` - Endurance Group Event Aggregate Log Page Change - -``NVME_AER_NOTICE_DISC_CHANGED`` - Discovery Log Page Change - - - - -.. c:enum:: nvme_subsys_type - - Type of the NVM subsystem. - -**Constants** - -``NVME_NQN_DISC`` - Discovery type target subsystem. Describes a referral to another - Discovery Service composed of Discovery controllers that provide - additional discovery records. Multiple Referral entries may - be reported for each Discovery Service (if that Discovery Service - has multiple NVM subsystem ports or supports multiple protocols). - -``NVME_NQN_NVME`` - NVME type target subsystem. Describes an NVM subsystem whose - controllers may have attached namespaces (an NVM subsystem - that is not composed of Discovery controllers). Multiple NVM - Subsystem entries may be reported for each NVM subsystem if - that NVM subsystem has multiple NVM subsystem ports. - -``NVME_NQN_CURR`` - Current Discovery type target subsystem. Describes this Discovery - subsystem (the Discovery Service that contains the controller - processing the Get Log Page command). Multiple Current Discovery - Subsystem entries may be reported for this Discovery subsystem - if the current Discovery subsystem has multiple NVM subsystem - ports. - - - - -.. c:enum:: nvmf_disc_eflags - - Discovery Log Page entry flags. - -**Constants** - -``NVMF_DISC_EFLAGS_NONE`` - Indicates that none of the DUPRETINFO or EPCSD - features are supported. - -``NVMF_DISC_EFLAGS_DUPRETINFO`` - Duplicate Returned Information (DUPRETINFO): - Indicates that using the content of this entry - to access this Discovery Service returns the same - information that is returned by using the content - of other entries in this log page that also have - this flag set. - -``NVMF_DISC_EFLAGS_EPCSD`` - Explicit Persistent Connection Support for Discovery (EPCSD): - Indicates that Explicit Persistent Connections are - supported for the Discovery controller. - -``NVMF_DISC_EFLAGS_NCC`` - No CDC Connectivity (NCC): If set to - '1', then no DDC that describes this entry - is currently connected to the CDC. If - cleared to '0', then at least one DDC that - describes this entry is currently - connected to the CDC. If the Discovery - controller returning this log page is not - a CDC, then this bit shall be cleared to - '0' and should be ignored by the host. - - - - -.. c:union:: nvmf_tsas - - Transport Specific Address Subtype - -**Definition** - -:: - - union nvmf_tsas { - char common[NVMF_TSAS_SIZE]; - struct rdma { - __u8 qptype; - __u8 prtype; - __u8 cms; - __u8 rsvd3[5]; - __u16 pkey; - __u8 rsvd10[246]; - } rdma; - struct tcp { - __u8 sectype; - } tcp; - }; - -**Members** - -``common`` - Common transport specific attributes - -``rdma`` - RDMA transport specific attribute settings - -``tcp`` - TCP transport specific attribute settings - - - - - -.. c:struct:: nvmf_disc_log_entry - - Discovery Log Page entry - -**Definition** - -:: - - struct nvmf_disc_log_entry { - __u8 trtype; - __u8 adrfam; - __u8 subtype; - __u8 treq; - __le16 portid; - __le16 cntlid; - __le16 asqsz; - __le16 eflags; - __u8 rsvd12[20]; - char trsvcid[NVMF_TRSVCID_SIZE]; - __u8 rsvd64[192]; - char subnqn[NVME_NQN_LENGTH]; - char traddr[NVMF_TRADDR_SIZE]; - union nvmf_tsas tsas; - }; - -**Members** - -``trtype`` - Transport Type (TRTYPE): Specifies the NVMe Transport type. - See :c:type:`enum nvmf_trtype `. - -``adrfam`` - Address Family (ADRFAM): Specifies the address family. - See :c:type:`enum nvmf_addr_family `. - -``subtype`` - Subsystem Type (SUBTYPE): Specifies the type of the NVM subsystem - that is indicated in this entry. See :c:type:`enum nvme_subsys_type `. - -``treq`` - Transport Requirements (TREQ): Indicates requirements for the NVMe - Transport. See :c:type:`enum nvmf_treq `. - -``portid`` - Port ID (PORTID): Specifies a particular NVM subsystem port. - Different NVMe Transports or address families may utilize the same - Port ID value (e.g. a Port ID may support both iWARP and RoCE). - -``cntlid`` - Controller ID (CNTLID): Specifies the controller ID. If the NVM - subsystem uses a dynamic controller model, then this field shall - be set to FFFFh. If the NVM subsystem uses a static controller model, - then this field may be set to a specific controller ID (values 0h - to FFEFh are valid). If the NVM subsystem uses a static controller - model and the value indicated is FFFEh, then the host should remember - the Controller ID returned as part of the Fabrics Connect command - in order to re-establish an association in the future with the same - controller. - -``asqsz`` - Admin Max SQ Size (ASQSZ): Specifies the maximum size of an Admin - Submission Queue. This applies to all controllers in the NVM - subsystem. The value shall be a minimum of 32 entries. - -``eflags`` - Entry Flags (EFLAGS): Indicates additional information related to - the current entry. See :c:type:`enum nvmf_disc_eflags `. - -``rsvd12`` - Reserved - -``trsvcid`` - Transport Service Identifier (TRSVCID): Specifies the NVMe Transport - service identifier as an ASCII string. The NVMe Transport service - identifier is specified by the associated NVMe Transport binding - specification. - -``rsvd64`` - Reserved - -``subnqn`` - NVM Subsystem Qualified Name (SUBNQN): NVMe Qualified Name (NQN) - that uniquely identifies the NVM subsystem. For a subsystem, if that - Discovery subsystem has a unique NQN (i.e., the NVM Subsystem NVMe - Qualified Name (SUBNQN) field in that Discovery subsystem's Identify - Controller data structure contains a unique NQN value), then the - value returned shall be that unique NQN. If the Discovery subsystem - does not have a unique NQN, then the value returned shall be the - well-known Discovery Service NQN (nqn.2014-08.org.nvmexpress.discovery). - -``traddr`` - Transport Address (TRADDR): Specifies the address of the NVM subsystem - that may be used for a Connect command as an ASCII string. The - Address Family field describes the reference for parsing this field. - -``tsas`` - Transport specific attribute settings - - - - - -.. c:enum:: nvmf_trtype - - Transport Type codes for Discovery Log Page entry TRTYPE field - -**Constants** - -``NVMF_TRTYPE_UNSPECIFIED`` - Not indicated - -``NVMF_TRTYPE_RDMA`` - RDMA - -``NVMF_TRTYPE_FC`` - Fibre Channel - -``NVMF_TRTYPE_TCP`` - TCP - -``NVMF_TRTYPE_LOOP`` - Intra-host Transport (i.e., loopback), reserved - for host usage. - -``NVMF_TRTYPE_MAX`` - Maximum value for :c:type:`enum nvmf_trtype ` - - - - -.. c:enum:: nvmf_addr_family - - Address Family codes for Discovery Log Page entry ADRFAM field - -**Constants** - -``NVMF_ADDR_FAMILY_PCI`` - PCIe - -``NVMF_ADDR_FAMILY_IP4`` - AF_INET: IPv4 address family. - -``NVMF_ADDR_FAMILY_IP6`` - AF_INET6: IPv6 address family. - -``NVMF_ADDR_FAMILY_IB`` - AF_IB: InfiniBand address family. - -``NVMF_ADDR_FAMILY_FC`` - Fibre Channel address family. - -``NVMF_ADDR_FAMILY_LOOP`` - Intra-host Transport (i.e., loopback), reserved - for host usage. - - - - -.. c:enum:: nvmf_treq - - Transport Requirements codes for Discovery Log Page entry TREQ field - -**Constants** - -``NVMF_TREQ_NOT_SPECIFIED`` - Not specified - -``NVMF_TREQ_REQUIRED`` - Required - -``NVMF_TREQ_NOT_REQUIRED`` - Not Required - -``NVMF_TREQ_DISABLE_SQFLOW`` - SQ flow control disable supported - - - - -.. c:enum:: nvmf_rdma_qptype - - RDMA QP Service Type codes for Discovery Log Page entry TSAS RDMA_QPTYPE field - -**Constants** - -``NVMF_RDMA_QPTYPE_CONNECTED`` - Reliable Connected - -``NVMF_RDMA_QPTYPE_DATAGRAM`` - Reliable Datagram - - - - -.. c:enum:: nvmf_rdma_prtype - - RDMA Provider Type codes for Discovery Log Page entry TSAS RDMA_PRTYPE field - -**Constants** - -``NVMF_RDMA_PRTYPE_NOT_SPECIFIED`` - No Provider Specified - -``NVMF_RDMA_PRTYPE_IB`` - InfiniBand - -``NVMF_RDMA_PRTYPE_ROCE`` - InfiniBand RoCE - -``NVMF_RDMA_PRTYPE_ROCEV2`` - InfiniBand RoCEV2 - -``NVMF_RDMA_PRTYPE_IWARP`` - iWARP - - - - -.. c:enum:: nvmf_rdma_cms - - RDMA Connection Management Service Type codes for Discovery Log Page entry TSAS RDMA_CMS field - -**Constants** - -``NVMF_RDMA_CMS_RDMA_CM`` - Sockets based endpoint addressing - - - - -.. c:enum:: nvmf_tcp_sectype - - Transport Specific Address Subtype Definition for NVMe/TCP Transport - -**Constants** - -``NVMF_TCP_SECTYPE_NONE`` - No Security - -``NVMF_TCP_SECTYPE_TLS`` - Transport Layer Security version 1.2 - -``NVMF_TCP_SECTYPE_TLS13`` - Transport Layer Security version 1.3 or a subsequent - version. The TLS protocol negotiates the version and - cipher suite for each TCP connection. - - - - -.. c:enum:: nvmf_log_discovery_lid_support - - Discovery log specific support - -**Constants** - -``NVMF_LOG_DISC_LID_NONE`` - None - -``NVMF_LOG_DISC_LID_EXTDLPES`` - Extended Discovery Log Page Entries Supported - -``NVMF_LOG_DISC_LID_PLEOS`` - Port Local Entries Only Supported - -``NVMF_LOG_DISC_LID_ALLSUBES`` - All NVM Subsystem Entries Supported - - - - -.. c:enum:: nvmf_log_discovery_lsp - - Discovery log specific field - -**Constants** - -``NVMF_LOG_DISC_LSP_NONE`` - None - -``NVMF_LOG_DISC_LSP_EXTDLPE`` - Extended Discovery Log Page Entries - -``NVMF_LOG_DISC_LSP_PLEO`` - Port Local Entries Only - -``NVMF_LOG_DISC_LSP_ALLSUBE`` - All NVM Subsystem Entries - - - - -.. c:struct:: nvmf_discovery_log - - Discovery Log Page (Log Identifier 70h) - -**Definition** - -:: - - struct nvmf_discovery_log { - __le64 genctr; - __le64 numrec; - __le16 recfmt; - __u8 rsvd14[1006]; - struct nvmf_disc_log_entry entries[]; - }; - -**Members** - -``genctr`` - Generation Counter (GENCTR): Indicates the version of the discovery - information, starting at a value of 0h. For each change in the - Discovery Log Page, this counter is incremented by one. If the value - of this field is FFFFFFFF_FFFFFFFFh, then the field shall be cleared - to 0h when incremented (i.e., rolls over to 0h). - -``numrec`` - Number of Records (NUMREC): Indicates the number of records - contained in the log. - -``recfmt`` - Record Format (RECFMT): Specifies the format of the Discovery Log - Page. If a new format is defined, this value is incremented by one. - The format of the record specified in this definition shall be 0h. - -``rsvd14`` - Reserved - -``entries`` - Discovery Log Page Entries - see :c:type:`struct nvmf_disc_log_entry `. - - - - - -.. c:enum:: nvmf_dim_tas - - Discovery Information Management Task - -**Constants** - -``NVMF_DIM_TAS_REGISTER`` - Register - -``NVMF_DIM_TAS_DEREGISTER`` - Deregister - -``NVMF_DIM_TAS_UPDATE`` - Update - - - - -.. c:enum:: nvmf_dim_entfmt - - Discovery Information Management Entry Format - -**Constants** - -``NVMF_DIM_ENTFMT_BASIC`` - Basic discovery information entry - -``NVMF_DIM_ENTFMT_EXTENDED`` - Extended discovery information entry - - - - -.. c:enum:: nvmf_dim_etype - - Discovery Information Management Entity Type - -**Constants** - -``NVMF_DIM_ETYPE_HOST`` - Host - -``NVMF_DIM_ETYPE_DDC`` - Direct Discovery controller - -``NVMF_DIM_ETYPE_CDC`` - Centralized Discovery controller - - - - -.. c:enum:: nvmf_exattype - - Extended Attribute Type - -**Constants** - -``NVMF_EXATTYPE_HOSTID`` - Host Identifier - -``NVMF_EXATTYPE_SYMNAME`` - Symblic Name - - - - -.. c:struct:: nvmf_ext_attr - - Extended Attribute (EXAT) - -**Definition** - -:: - - struct nvmf_ext_attr { - __le16 exattype; - __le16 exatlen; - __u8 exatval[]; - }; - -**Members** - -``exattype`` - Extended Attribute Type (EXATTYPE) - see **enum** nvmf_exattype - -``exatlen`` - Extended Attribute Length (EXATLEN) - -``exatval`` - Extended Attribute Value (EXATVAL) - size allocated for array - must be a multiple of 4 bytes - - - - - -.. c:struct:: nvmf_ext_die - - Extended Discovery Information Entry (DIE) - -**Definition** - -:: - - struct nvmf_ext_die { - __u8 trtype; - __u8 adrfam; - __u8 subtype; - __u8 treq; - __le16 portid; - __le16 cntlid; - __le16 asqsz; - __u8 rsvd10[22]; - char trsvcid[NVMF_TRSVCID_SIZE]; - __u8 resv64[192]; - char nqn[NVME_NQN_LENGTH]; - char traddr[NVMF_TRADDR_SIZE]; - union nvmf_tsas tsas; - __le32 tel; - __le16 numexat; - __u8 resv1030[2]; - struct nvmf_ext_attr exat[]; - }; - -**Members** - -``trtype`` - Transport Type (:c:type:`enum nvmf_trtype `) - -``adrfam`` - Address Family (:c:type:`enum nvmf_addr_family `) - -``subtype`` - Subsystem Type (:c:type:`enum nvme_subsys_type `) - -``treq`` - Transport Requirements (:c:type:`enum nvmf_treq `) - -``portid`` - Port ID - -``cntlid`` - Controller ID - -``asqsz`` - Admin Max SQ Size - -``rsvd10`` - Reserved - -``trsvcid`` - Transport Service Identifier - -``resv64`` - Reserved - -``nqn`` - NVM Qualified Name - -``traddr`` - Transport Address - -``tsas`` - Transport Specific Address Subtype (:c:type:`union nvmf_tsas `) - -``tel`` - Total Entry Length - -``numexat`` - Number of Extended Attributes - -``resv1030`` - Reserved - -``exat`` - Extended Attributes 0 (:c:type:`struct nvmf_ext_attr `) - - - - - -.. c:union:: nvmf_die - - Discovery Information Entry (DIE) - -**Definition** - -:: - - union nvmf_die { - struct nvmf_disc_log_entry basic[0]; - struct nvmf_ext_die extended; - }; - -**Members** - -``basic`` - Basic format (:c:type:`struct nvmf_disc_log_entry `) - -``extended`` - Extended format (:c:type:`struct nvmf_ext_die `) - - -**Description** - -Depending on the ENTFMT specified in the DIM, DIEs can be entered -with the Basic or Extended formats. For Basic format, each entry -has a fixed length. Therefore, the "basic" field defined below can -be accessed as a C array. For the Extended format, however, each -entry is of variable length (TEL). Therefore, the "extended" field -defined below cannot be accessed as a C array. Instead, the -"extended" field is akin to a linked-list, where one can "walk" -through the list. To move to the next entry, one simply adds the -current entry's length (TEL) to the "walk" pointer. The number of -entries in the list is specified by NUMENT. Although extended -entries are of a variable lengths (TEL), TEL is always a multiple of -4 bytes. - - - - -.. c:struct:: nvmf_dim_data - - Discovery Information Management (DIM) - Data - -**Definition** - -:: - - struct nvmf_dim_data { - __le32 tdl; - __u8 rsvd4[4]; - __le64 nument; - __le16 entfmt; - __le16 etype; - __u8 portlcl; - __u8 rsvd21; - __le16 ektype; - char eid[NVME_NQN_LENGTH]; - char ename[NVMF_ENAME_LEN]; - char ever[NVMF_EVER_LEN]; - __u8 rsvd600[424]; - union nvmf_die die[]; - }; - -**Members** - -``tdl`` - Total Data Length - -``rsvd4`` - Reserved - -``nument`` - Number of entries - -``entfmt`` - Entry Format (:c:type:`enum nvmf_dim_entfmt `) - -``etype`` - Entity Type (:c:type:`enum nvmf_dim_etype `) - -``portlcl`` - Port Local - -``rsvd21`` - Reserved - -``ektype`` - Entry Key Type - -``eid`` - Entity Identifier (e.g. Host NQN) - -``ename`` - Entity Name (e.g. hostname) - -``ever`` - Entity Version (e.g. OS Name/Version) - -``rsvd600`` - Reserved - -``die`` - Discovery Information Entry (see **nument** above) - - - - - -.. c:struct:: nvmf_connect_data - - Data payload for the 'connect' command - -**Definition** - -:: - - struct nvmf_connect_data { - __u8 hostid[16]; - __le16 cntlid; - char rsvd4[238]; - char subsysnqn[NVME_NQN_LENGTH]; - char hostnqn[NVME_NQN_LENGTH]; - char rsvd5[256]; - }; - -**Members** - -``hostid`` - Host ID of the connecting host - -``cntlid`` - Requested controller ID - -``rsvd4`` - Reserved - -``subsysnqn`` - Subsystem NQN to connect to - -``hostnqn`` - Host NQN of the connecting host - -``rsvd5`` - Reserved - - - - - -.. c:struct:: nvme_mi_read_nvm_ss_info - - NVM Subsystem Information Data Structure - -**Definition** - -:: - - struct nvme_mi_read_nvm_ss_info { - __u8 nump; - __u8 mjr; - __u8 mnr; - __u8 rsvd3[29]; - }; - -**Members** - -``nump`` - Number of Ports - -``mjr`` - NVMe-MI Major Version Number - -``mnr`` - NVMe-MI Minor Version Number - -``rsvd3`` - Reserved - - - - - -.. c:struct:: nvme_mi_port_pcie - - PCIe Port Specific Data - -**Definition** - -:: - - struct nvme_mi_port_pcie { - __u8 mps; - __u8 sls; - __u8 cls; - __u8 mlw; - __u8 nlw; - __u8 pn; - __u8 rsvd14[18]; - }; - -**Members** - -``mps`` - PCIe Maximum Payload Size - -``sls`` - PCIe Supported Link Speeds Vector - -``cls`` - PCIe Current Link Speed - -``mlw`` - PCIe Maximum Link Width - -``nlw`` - PCIe Negotiated Link Width - -``pn`` - PCIe Port Number - -``rsvd14`` - Reserved - - - - - -.. c:struct:: nvme_mi_port_smb - - SMBus Port Specific Data - -**Definition** - -:: - - struct nvme_mi_port_smb { - __u8 vpd_addr; - __u8 mvpd_freq; - __u8 mme_addr; - __u8 mme_freq; - __u8 nvmebm; - __u8 rsvd13[19]; - }; - -**Members** - -``vpd_addr`` - Current VPD SMBus/I2C Address - -``mvpd_freq`` - Maximum VPD Access SMBus/I2C Frequency - -``mme_addr`` - Current Management Endpoint SMBus/I2C Address - -``mme_freq`` - Maximum Management Endpoint SMBus/I2C Frequency - -``nvmebm`` - NVMe Basic Management - -``rsvd13`` - Reserved - - - - - -.. c:struct:: nvme_mi_read_port_info - - Port Information Data Structure - -**Definition** - -:: - - struct nvme_mi_read_port_info { - __u8 portt; - __u8 rsvd1; - __le16 mmctptus; - __le32 meb; - union { - struct nvme_mi_port_pcie pcie; - struct nvme_mi_port_smb smb; - }; - }; - -**Members** - -``portt`` - Port Type - -``rsvd1`` - Reserved - -``mmctptus`` - Maximum MCTP Transmission Unit Size - -``meb`` - Management Endpoint Buffer Size - -``{unnamed_union}`` - anonymous - -``pcie`` - PCIe Port Specific Data - -``smb`` - SMBus Port Specific Data - - - - - -.. c:struct:: nvme_mi_read_ctrl_info - - Controller Information Data Structure - -**Definition** - -:: - - struct nvme_mi_read_ctrl_info { - __u8 portid; - __u8 rsvd1[4]; - __u8 prii; - __le16 pri; - __le16 vid; - __le16 did; - __le16 ssvid; - __le16 ssid; - __u8 rsvd16[16]; - }; - -**Members** - -``portid`` - Port Identifier - -``rsvd1`` - Reserved - -``prii`` - PCIe Routing ID Information - -``pri`` - PCIe Routing ID - -``vid`` - PCI Vendor ID - -``did`` - PCI Device ID - -``ssvid`` - PCI Subsystem Vendor ID - -``ssid`` - PCI Subsystem Device ID - -``rsvd16`` - Reserved - - - - - -.. c:struct:: nvme_mi_osc - - Optionally Supported Command Data Structure - -**Definition** - -:: - - struct nvme_mi_osc { - __u8 type; - __u8 opc; - }; - -**Members** - -``type`` - Command Type - -``opc`` - Opcode - - - - - -.. c:struct:: nvme_mi_read_sc_list - - Management Endpoint Buffer Supported Command List Data Structure - -**Definition** - -:: - - struct nvme_mi_read_sc_list { - __le16 numcmd; - struct nvme_mi_osc cmds[]; - }; - -**Members** - -``numcmd`` - Number of Commands - -``cmds`` - MEB supported Command Data Structure. - See **struct** nvme_mi_osc - - - - - -.. c:struct:: nvme_mi_nvm_ss_health_status - - Subsystem Management Data Structure - -**Definition** - -:: - - struct nvme_mi_nvm_ss_health_status { - __u8 nss; - __u8 sw; - __u8 ctemp; - __u8 pdlu; - __le16 ccs; - __u8 rsvd8[2]; - }; - -**Members** - -``nss`` - NVM Subsystem Status - -``sw`` - Smart Warnings - -``ctemp`` - Composite Temperature - -``pdlu`` - Percentage Drive Life Used - -``ccs`` - Composite Controller Status - -``rsvd8`` - Reserved - - - - - -.. c:enum:: nvme_mi_ccs - - Get State Control Primitive Success Response Fields - Control Primitive Specific Response - -**Constants** - -``NVME_MI_CCS_RDY`` - Ready - -``NVME_MI_CCS_CFS`` - Controller Fatal Status - -``NVME_MI_CCS_SHST`` - Shutdown Status - -``NVME_MI_CCS_NSSRO`` - NVM Subsystem Reset Occurred - -``NVME_MI_CCS_CECO`` - Controller Enable Change Occurred - -``NVME_MI_CCS_NAC`` - Namespace Attribute Changed - -``NVME_MI_CCS_FA`` - Firmware Activated - -``NVME_MI_CCS_CSTS`` - Controller Status Change - -``NVME_MI_CCS_CTEMP`` - Composite Temperature Change - -``NVME_MI_CCS_PDLU`` - Percentage Used - -``NVME_MI_CCS_SPARE`` - Available Spare - -``NVME_MI_CCS_CCWARN`` - Critical Warning - - - - -.. c:struct:: nvme_mi_ctrl_health_status - - Controller Health Data Structure (CHDS) - -**Definition** - -:: - - struct nvme_mi_ctrl_health_status { - __le16 ctlid; - __le16 csts; - __le16 ctemp; - __u8 pdlu; - __u8 spare; - __u8 cwarn; - __u8 rsvd9[7]; - }; - -**Members** - -``ctlid`` - Controller Identifier - -``csts`` - Controller Status - -``ctemp`` - Composite Temperature - -``pdlu`` - Percentage Used - -``spare`` - Available Spare - -``cwarn`` - Critical Warning - -``rsvd9`` - Reserved - - - - - -.. c:enum:: nvme_mi_csts - - Controller Health Data Structure (CHDS) - Controller Status (CSTS) - -**Constants** - -``NVME_MI_CSTS_RDY`` - Ready - -``NVME_MI_CSTS_CFS`` - Controller Fatal Status - -``NVME_MI_CSTS_SHST`` - Shutdown Status - -``NVME_MI_CSTS_NSSRO`` - NVM Subsystem Reset Occurred - -``NVME_MI_CSTS_CECO`` - Controller Enable Change Occurred - -``NVME_MI_CSTS_NAC`` - Namespace Attribute Changed - -``NVME_MI_CSTS_FA`` - Firmware Activated - - - - -.. c:enum:: nvme_mi_cwarn - - Controller Health Data Structure (CHDS) - Critical Warning (CWARN) - -**Constants** - -``NVME_MI_CWARN_ST`` - Spare Threshold - -``NVME_MI_CWARN_TAUT`` - Temperature Above or Under Threshold - -``NVME_MI_CWARN_RD`` - Reliability Degraded - -``NVME_MI_CWARN_RO`` - Read Only - -``NVME_MI_CWARN_VMBF`` - Volatile Memory Backup Failed - - - - -.. c:struct:: nvme_mi_vpd_mra - - NVMe MultiRecord Area - -**Definition** - -:: - - struct nvme_mi_vpd_mra { - __u8 nmravn; - __u8 ff; - __u8 rsvd7[6]; - __u8 i18vpwr; - __u8 m18vpwr; - __u8 i33vpwr; - __u8 m33vpwr; - __u8 rsvd17; - __u8 m33vapsr; - __u8 i5vapsr; - __u8 m5vapsr; - __u8 i12vapsr; - __u8 m12vapsr; - __u8 mtl; - __u8 tnvmcap[16]; - __u8 rsvd37[27]; - }; - -**Members** - -``nmravn`` - NVMe MultiRecord Area Version Number - -``ff`` - Form Factor - -``rsvd7`` - Reserved - -``i18vpwr`` - Initial 1.8 V Power Supply Requirements - -``m18vpwr`` - Maximum 1.8 V Power Supply Requirements - -``i33vpwr`` - Initial 3.3 V Power Supply Requirements - -``m33vpwr`` - Maximum 3.3 V Power Supply Requirements - -``rsvd17`` - Reserved - -``m33vapsr`` - Maximum 3.3 Vi aux Power Supply Requirements - -``i5vapsr`` - Initial 5 V Power Supply Requirements - -``m5vapsr`` - Maximum 5 V Power Supply Requirements - -``i12vapsr`` - Initial 12 V Power Supply Requirements - -``m12vapsr`` - Maximum 12 V Power Supply Requirements - -``mtl`` - Maximum Thermal Load - -``tnvmcap`` - Total NVM Capacity - -``rsvd37`` - Reserved - - - - - -.. c:struct:: nvme_mi_vpd_ppmra - - NVMe PCIe Port MultiRecord Area - -**Definition** - -:: - - struct nvme_mi_vpd_ppmra { - __u8 nppmravn; - __u8 pn; - __u8 ppi; - __u8 ls; - __u8 mlw; - __u8 mctp; - __u8 refccap; - __u8 pi; - __u8 rsvd13[3]; - }; - -**Members** - -``nppmravn`` - NVMe PCIe Port MultiRecord Area Version Number - -``pn`` - PCIe Port Number - -``ppi`` - Port Information - -``ls`` - PCIe Link Speed - -``mlw`` - PCIe Maximum Link Width - -``mctp`` - MCTP Support - -``refccap`` - Ref Clk Capability - -``pi`` - Port Identifier - -``rsvd13`` - Reserved - - - - - -.. c:struct:: nvme_mi_vpd_telem - - Vital Product Data Element Descriptor - -**Definition** - -:: - - struct nvme_mi_vpd_telem { - __u8 type; - __u8 rev; - __u8 len; - __u8 data[0]; - }; - -**Members** - -``type`` - Type of the Element Descriptor - -``rev`` - Revision of the Element Descriptor - -``len`` - Number of bytes in the Element Descriptor - -``data`` - Type-specific information associated with - the Element Descriptor - - - - - -.. c:enum:: nvme_mi_elem - - Element Descriptor Types - -**Constants** - -``NVME_MI_ELEM_EED`` - Extended Element Descriptor - -``NVME_MI_ELEM_USCE`` - Upstream Connector Element Descriptor - -``NVME_MI_ELEM_ECED`` - Expansion Connector Element Descriptor - -``NVME_MI_ELEM_LED`` - Label Element Descriptor - -``NVME_MI_ELEM_SMBMED`` - SMBus/I2C Mux Element Descriptor - -``NVME_MI_ELEM_PCIESED`` - PCIe Switch Element Descriptor - -``NVME_MI_ELEM_NVMED`` - NVM Subsystem Element Descriptor - - - - -.. c:struct:: nvme_mi_vpd_tra - - Vital Product Data Topology MultiRecord - -**Definition** - -:: - - struct nvme_mi_vpd_tra { - __u8 vn; - __u8 rsvd6; - __u8 ec; - struct nvme_mi_vpd_telem elems[0]; - }; - -**Members** - -``vn`` - Version Number - -``rsvd6`` - Reserved - -``ec`` - Element Count - -``elems`` - Element Descriptor - - - - - -.. c:struct:: nvme_mi_vpd_mr_common - - NVMe MultiRecord Area - -**Definition** - -:: - - struct nvme_mi_vpd_mr_common { - __u8 type; - __u8 rf; - __u8 rlen; - __u8 rchksum; - __u8 hchksum; - union { - struct nvme_mi_vpd_mra nmra; - struct nvme_mi_vpd_ppmra ppmra; - struct nvme_mi_vpd_tra tmra; - }; - }; - -**Members** - -``type`` - NVMe Record Type ID - -``rf`` - Record Format - -``rlen`` - Record Length - -``rchksum`` - Record Checksum - -``hchksum`` - Header Checksum - -``{unnamed_union}`` - anonymous - -``nmra`` - NVMe MultiRecord Area - -``ppmra`` - NVMe PCIe Port MultiRecord Area - -``tmra`` - Topology MultiRecord Area - - - - - -.. c:struct:: nvme_mi_vpd_hdr - - Vital Product Data Common Header - -**Definition** - -:: - - struct nvme_mi_vpd_hdr { - __u8 ipmiver; - __u8 iuaoff; - __u8 ciaoff; - __u8 biaoff; - __u8 piaoff; - __u8 mrioff; - __u8 rsvd6; - __u8 chchk; - __u8 vpd[]; - }; - -**Members** - -``ipmiver`` - IPMI Format Version Number - -``iuaoff`` - Internal Use Area Starting Offset - -``ciaoff`` - Chassis Info Area Starting Offset - -``biaoff`` - Board Info Area Starting Offset - -``piaoff`` - Product Info Area Starting Offset - -``mrioff`` - MultiRecord Info Area Starting Offset - -``rsvd6`` - Reserved - -``chchk`` - Common Header Checksum - -``vpd`` - Vital Product Data - - - - - -.. c:enum:: nvme_status_field - - Defines all parts of the nvme status field: status code, status code type, and additional flags. - -**Constants** - -``NVME_SCT_GENERIC`` - Generic errors applicable to multiple opcodes - -``NVME_SCT_CMD_SPECIFIC`` - Errors associated to a specific opcode - -``NVME_SCT_MEDIA`` - Errors associated with media and data integrity - -``NVME_SCT_PATH`` - Errors associated with the paths connection - -``NVME_SCT_VS`` - Vendor specific errors - -``NVME_SCT_MASK`` - Mask to get the value of the Status Code Type - -``NVME_SCT_SHIFT`` - Shift value to get the value of the Status - Code Type - -``NVME_SC_MASK`` - Mask to get the value of the status code. - -``NVME_SC_SHIFT`` - Shift value to get the value of the status - code. - -``NVME_SC_SUCCESS`` - Successful Completion: The command - completed without error. - -``NVME_SC_INVALID_OPCODE`` - Invalid Command Opcode: A reserved coded - value or an unsupported value in the - command opcode field. - -``NVME_SC_INVALID_FIELD`` - Invalid Field in Command: A reserved - coded value or an unsupported value in a - defined field. - -``NVME_SC_CMDID_CONFLICT`` - Command ID Conflict: The command - identifier is already in use. - -``NVME_SC_DATA_XFER_ERROR`` - Data Transfer Error: Transferring the - data or metadata associated with a - command experienced an error. - -``NVME_SC_POWER_LOSS`` - Commands Aborted due to Power Loss - Notification: Indicates that the command - was aborted due to a power loss - notification. - -``NVME_SC_INTERNAL`` - Internal Error: The command was not - completed successfully due to an internal error. - -``NVME_SC_ABORT_REQ`` - Command Abort Requested: The command was - aborted due to an Abort command being - received that specified the Submission - Queue Identifier and Command Identifier - of this command. - -``NVME_SC_ABORT_QUEUE`` - Command Aborted due to SQ Deletion: The - command was aborted due to a Delete I/O - Submission Queue request received for the - Submission Queue to which the command was - submitted. - -``NVME_SC_FUSED_FAIL`` - Command Aborted due to Failed Fused Command: - The command was aborted due to the other - command in a fused operation failing. - -``NVME_SC_FUSED_MISSING`` - Aborted due to Missing Fused Command: The - fused command was aborted due to the - adjacent submission queue entry not - containing a fused command that is the - other command. - -``NVME_SC_INVALID_NS`` - Invalid Namespace or Format: The - namespace or the format of that namespace - is invalid. - -``NVME_SC_CMD_SEQ_ERROR`` - Command Sequence Error: The command was - aborted due to a protocol violation in a - multi-command sequence. - -``NVME_SC_SGL_INVALID_LAST`` - Invalid SGL Segment Descriptor: The - command includes an invalid SGL Last - Segment or SGL Segment descriptor. - -``NVME_SC_SGL_INVALID_COUNT`` - Invalid Number of SGL Descriptors: There - is an SGL Last Segment descriptor or an - SGL Segment descriptor in a location - other than the last descriptor of a - segment based on the length indicated. - -``NVME_SC_SGL_INVALID_DATA`` - Data SGL Length Invalid: This may occur - if the length of a Data SGL is too short. - This may occur if the length of a Data - SGL is too long and the controller does - not support SGL transfers longer than the - amount of data to be transferred as - indicated in the SGL Support field of the - Identify Controller data structure. - -``NVME_SC_SGL_INVALID_METADATA`` - Metadata SGL Length Invalid: This may - occur if the length of a Metadata SGL is - too short. This may occur if the length - of a Metadata SGL is too long and the - controller does not support SGL transfers - longer than the amount of data to be - transferred as indicated in the SGL - Support field of the Identify Controller - data structure. - -``NVME_SC_SGL_INVALID_TYPE`` - SGL Descriptor Type Invalid: The type of - an SGL Descriptor is a type that is not - supported by the controller. - -``NVME_SC_CMB_INVALID_USE`` - Invalid Use of Controller Memory Buffer: - The attempted use of the Controller - Memory Buffer is not supported by the - controller. - -``NVME_SC_PRP_INVALID_OFFSET`` - PRP Offset Invalid: The Offset field for - a PRP entry is invalid. - -``NVME_SC_AWU_EXCEEDED`` - Atomic Write Unit Exceeded: The length - specified exceeds the atomic write unit size. - -``NVME_SC_OP_DENIED`` - Operation Denied: The command was denied - due to lack of access rights. Refer to - the appropriate security specification. - -``NVME_SC_SGL_INVALID_OFFSET`` - SGL Offset Invalid: The offset specified - in a descriptor is invalid. This may - occur when using capsules for data - transfers in NVMe over Fabrics - implementations and an invalid offset in - the capsule is specified. - -``NVME_SC_HOSTID_FORMAT`` - Host Identifier Inconsistent Format: The - NVM subsystem detected the simultaneous - use of 64- bit and 128-bit Host - Identifier values on different - controllers. - -``NVME_SC_KAT_EXPIRED`` - Keep Alive Timer Expired: The Keep Alive - Timer expired. - -``NVME_SC_KAT_INVALID`` - Keep Alive Timeout Invalid: The Keep - Alive Timeout value specified is invalid. - -``NVME_SC_CMD_ABORTED_PREMEPT`` - Command Aborted due to Preempt and Abort: - The command was aborted due to a - Reservation Acquire command. - -``NVME_SC_SANITIZE_FAILED`` - Sanitize Failed: The most recent sanitize - operation failed and no recovery action - has been successfully completed. - -``NVME_SC_SANITIZE_IN_PROGRESS`` - Sanitize In Progress: The requested - function (e.g., command) is prohibited - while a sanitize operation is in - progress. - -``NVME_SC_SGL_INVALID_GRANULARITY`` - SGL Data Block Granularity Invalid: The - Address alignment or Length granularity - for an SGL Data Block descriptor is - invalid. - -``NVME_SC_CMD_IN_CMBQ_NOT_SUPP`` - Command Not Supported for Queue in CMB: - The implementation does not support - submission of the command to a Submission - Queue in the Controller Memory Buffer or - command completion to a Completion Queue - in the Controller Memory Buffer. - -``NVME_SC_NS_WRITE_PROTECTED`` - Namespace is Write Protected: The command - is prohibited while the namespace is - write protected as a result of a change - in the namespace write protection state - as defined by the Namespace Write - Protection State Machine. - -``NVME_SC_CMD_INTERRUPTED`` - Command Interrupted: Command processing - was interrupted and the controller is - unable to successfully complete the - command. The host should retry the - command. - -``NVME_SC_TRAN_TPORT_ERROR`` - Transient Transport Error: A transient - transport error was detected. If the - command is retried on the same - controller, the command is likely to - succeed. A command that fails with a - transient transport error four or more - times should be treated as a persistent - transport error that is not likely to - succeed if retried on the same - controller. - -``NVME_SC_PROHIBITED_BY_CMD_AND_FEAT`` - Command Prohibited by Command and Feature - Lockdown: The command was aborted due to - command execution being prohibited by - the Command and Feature Lockdown. - -``NVME_SC_ADMIN_CMD_MEDIA_NOT_READY`` - Admin Command Media Not Ready: The Admin - command requires access to media and - the media is not ready. - -``NVME_SC_LBA_RANGE`` - LBA Out of Range: The command references - an LBA that exceeds the size of the namespace. - -``NVME_SC_CAP_EXCEEDED`` - Capacity Exceeded: Execution of the - command has caused the capacity of the - namespace to be exceeded. - -``NVME_SC_NS_NOT_READY`` - Namespace Not Ready: The namespace is not - ready to be accessed as a result of a - condition other than a condition that is - reported as an Asymmetric Namespace - Access condition. - -``NVME_SC_RESERVATION_CONFLICT`` - Reservation Conflict: The command was - aborted due to a conflict with a - reservation held on the accessed - namespace. - -``NVME_SC_FORMAT_IN_PROGRESS`` - Format In Progress: A Format NVM command - is in progress on the namespace. - -``NVME_SC_CQ_INVALID`` - Completion Queue Invalid: The Completion - Queue identifier specified in the command - does not exist. - -``NVME_SC_QID_INVALID`` - Invalid Queue Identifier: The creation of - the I/O Completion Queue failed due to an - invalid queue identifier specified as - part of the command. An invalid queue - identifier is one that is currently in - use or one that is outside the range - supported by the controller. - -``NVME_SC_QUEUE_SIZE`` - Invalid Queue Size: The host attempted to - create an I/O Completion Queue with an - invalid number of entries. - -``NVME_SC_ABORT_LIMIT`` - Abort Command Limit Exceeded: The number - of concurrently outstanding Abort commands - has exceeded the limit indicated in the - Identify Controller data structure. - -``NVME_SC_ABORT_MISSING`` - Abort Command is missing: The abort - command is missing. - -``NVME_SC_ASYNC_LIMIT`` - Asynchronous Event Request Limit - Exceeded: The number of concurrently - outstanding Asynchronous Event Request - commands has been exceeded. - -``NVME_SC_FIRMWARE_SLOT`` - Invalid Firmware Slot: The firmware slot - indicated is invalid or read only. This - error is indicated if the firmware slot - exceeds the number supported. - -``NVME_SC_FIRMWARE_IMAGE`` - Invalid Firmware Image: The firmware - image specified for activation is invalid - and not loaded by the controller. - -``NVME_SC_INVALID_VECTOR`` - Invalid Interrupt Vector: The creation of - the I/O Completion Queue failed due to an - invalid interrupt vector specified as - part of the command. - -``NVME_SC_INVALID_LOG_PAGE`` - Invalid Log Page: The log page indicated - is invalid. This error condition is also - returned if a reserved log page is - requested. - -``NVME_SC_INVALID_FORMAT`` - Invalid Format: The LBA Format specified - is not supported. - -``NVME_SC_FW_NEEDS_CONV_RESET`` - Firmware Activation Requires Conventional Reset: - The firmware commit was successful, - however, activation of the firmware image - requires a conventional reset. - -``NVME_SC_INVALID_QUEUE`` - Invalid Queue Deletion: Invalid I/O - Completion Queue specified to delete. - -``NVME_SC_FEATURE_NOT_SAVEABLE`` - Feature Identifier Not Saveable: The - Feature Identifier specified does not - support a saveable value. - -``NVME_SC_FEATURE_NOT_CHANGEABLE`` - Feature Not Changeable: The Feature - Identifier is not able to be changed. - -``NVME_SC_FEATURE_NOT_PER_NS`` - Feature Not Namespace Specific: The - Feature Identifier specified is not - namespace specific. The Feature - Identifier settings apply across all - namespaces. - -``NVME_SC_FW_NEEDS_SUBSYS_RESET`` - Firmware Activation Requires NVM - Subsystem Reset: The firmware commit was - successful, however, activation of the - firmware image requires an NVM Subsystem. - -``NVME_SC_FW_NEEDS_RESET`` - Firmware Activation Requires Controller - Level Reset: The firmware commit was - successful; however, the image specified - does not support being activated without - a reset. - -``NVME_SC_FW_NEEDS_MAX_TIME`` - Firmware Activation Requires Maximum Time - Violation: The image specified if - activated immediately would exceed the - Maximum Time for Firmware Activation - (MTFA) value reported in Identify - Controller. - -``NVME_SC_FW_ACTIVATE_PROHIBITED`` - Firmware Activation Prohibited: The image - specified is being prohibited from - activation by the controller for vendor - specific reasons. - -``NVME_SC_OVERLAPPING_RANGE`` - Overlapping Range: The downloaded - firmware image has overlapping ranges. - -``NVME_SC_NS_INSUFFICIENT_CAP`` - Namespace Insufficient Capacity: Creating - the namespace requires more free space - than is currently available. - -``NVME_SC_NS_ID_UNAVAILABLE`` - Namespace Identifier Unavailable: The - number of namespaces supported has been - exceeded. - -``NVME_SC_NS_ALREADY_ATTACHED`` - Namespace Already Attached: The - controller is already attached to the - namespace specified. - -``NVME_SC_NS_IS_PRIVATE`` - Namespace Is Private: The namespace is - private and is already attached to one - controller. - -``NVME_SC_NS_NOT_ATTACHED`` - Namespace Not Attached: The request to - detach the controller could not be - completed because the controller is not - attached to the namespace. - -``NVME_SC_THIN_PROV_NOT_SUPP`` - Thin Provisioning Not Supported: Thin - provisioning is not supported by the - controller. - -``NVME_SC_CTRL_LIST_INVALID`` - Controller List Invalid: The controller - list provided contains invalid controller - ids. - -``NVME_SC_SELF_TEST_IN_PROGRESS`` - Device Self-test In Progress: The controller - or NVM subsystem already has a device - self-test operation in process. - -``NVME_SC_BP_WRITE_PROHIBITED`` - Boot Partition Write Prohibited: The - command is trying to modify a locked Boot - Partition. - -``NVME_SC_INVALID_CTRL_ID`` - Invalid Controller Identifier: - -``NVME_SC_INVALID_SEC_CTRL_STATE`` - Invalid Secondary Controller State - -``NVME_SC_INVALID_CTRL_RESOURCES`` - Invalid Number of Controller Resources - -``NVME_SC_INVALID_RESOURCE_ID`` - Invalid Resource Identifier - -``NVME_SC_PMR_SAN_PROHIBITED`` - Sanitize Prohibited While Persistent - Memory Region is Enabled - -``NVME_SC_ANA_GROUP_ID_INVALID`` - ANA Group Identifier Invalid: The specified - ANA Group Identifier (ANAGRPID) is not - supported in the submitted command. - -``NVME_SC_ANA_ATTACH_FAILED`` - ANA Attach Failed: The controller is not - attached to the namespace as a result - of an ANA condition. - -``NVME_SC_INSUFFICIENT_CAP`` - Insufficient Capacity: Requested operation - requires more free space than is currently - available. - -``NVME_SC_NS_ATTACHMENT_LIMIT_EXCEEDED`` - Namespace Attachment Limit Exceeded: - Attaching the ns to a controller causes - max number of ns attachments allowed - to be exceeded. - -``NVME_SC_PROHIBIT_CMD_EXEC_NOT_SUPPORTED`` - Prohibition of Command Execution - Not Supported - -``NVME_SC_IOCS_NOT_SUPPORTED`` - I/O Command Set Not Supported - -``NVME_SC_IOCS_NOT_ENABLED`` - I/O Command Set Not Enabled - -``NVME_SC_IOCS_COMBINATION_REJECTED`` - I/O Command Set Combination Rejected - -``NVME_SC_INVALID_IOCS`` - Invalid I/O Command Set - -``NVME_SC_ID_UNAVAILABLE`` - Identifier Unavailable - -``NVME_SC_INVALID_DISCOVERY_INFO`` - The discovery information provided in - one or more extended discovery - information entries is not applicable - for the type of entity selected in - the Entity Type (ETYPE) field of the - Discovery Information Management - command data portion’s header. - -``NVME_SC_ZONING_DATA_STRUCT_LOCKED`` - The requested Zoning data structure - is locked on the CDC. - -``NVME_SC_ZONING_DATA_STRUCT_NOTFND`` - The requested Zoning data structure - does not exist on the CDC. - -``NVME_SC_INSUFFICIENT_DISC_RES`` - The number of discover information - entries provided in the data portion - of the Discovery Information - Management command for a registration - task (i.e., TAS field cleared to 0h) - exceeds the available capacity for - new discovery information entries on - the CDC or DDC. This may be a - transient condition. - -``NVME_SC_REQSTD_FUNCTION_DISABLED`` - Fabric Zoning is not enabled on the - CDC - -``NVME_SC_ZONEGRP_ORIGINATOR_INVLD`` - The NQN contained in the ZoneGroup - Originator field does not match the - Host NQN used by the DDC to connect - to the CDC. - -``NVME_SC_BAD_ATTRIBUTES`` - Conflicting Dataset Management Attributes - -``NVME_SC_INVALID_PI`` - Invalid Protection Information - -``NVME_SC_READ_ONLY`` - Attempted Write to Read Only Range - -``NVME_SC_CMD_SIZE_LIMIT_EXCEEDED`` - Command Size Limit Exceeded - -``NVME_SC_CONNECT_FORMAT`` - Incompatible Format: The NVM subsystem - does not support the record format - specified by the host. - -``NVME_SC_CONNECT_CTRL_BUSY`` - Controller Busy: The controller is - already associated with a host. - -``NVME_SC_CONNECT_INVALID_PARAM`` - Connect Invalid Parameters: One or more - of the command parameters. - -``NVME_SC_CONNECT_RESTART_DISC`` - Connect Restart Discovery: The NVM - subsystem requested is not available. - -``NVME_SC_CONNECT_INVALID_HOST`` - Connect Invalid Host: The host is either - not allowed to establish an association - to any controller in the NVM subsystem or - the host is not allowed to establish an - association to the specified controller - -``NVME_SC_DISCONNECT_INVALID_QTYPE`` - Invalid Queue Type: The command was sent - on the wrong queue type. - -``NVME_SC_DISCOVERY_RESTART`` - Discover Restart: The snapshot of the - records is now invalid or out of date. - -``NVME_SC_AUTH_REQUIRED`` - Authentication Required: NVMe in-band - authentication is required and the queue - has not yet been authenticated. - -``NVME_SC_ZNS_INVALID_OP_REQUEST`` - Invalid Zone Operation Request: - The operation requested is invalid. This may be due to - various conditions, including: attempting to allocate a - ZRWA when a zone is not in the ZSE:Empty state; or - invalid Flush Explicit ZRWA Range Send Zone Action - operation. - -``NVME_SC_ZNS_ZRWA_RESOURCES_UNAVAILABLE`` - ZRWA Resources Unavailable: - No ZRWAs are available. - -``NVME_SC_ZNS_BOUNDARY_ERROR`` - Zone Boundary Error: The command specifies - logical blocks in more than one zone. - -``NVME_SC_ZNS_FULL`` - Zone Is Full: The accessed zone is in the - ZSF:Full state. - -``NVME_SC_ZNS_READ_ONLY`` - Zone Is Read Only: The accessed zone is - in the ZSRO:Read Only state. - -``NVME_SC_ZNS_OFFLINE`` - Zone Is Offline: The accessed zone is - in the ZSO:Offline state. - -``NVME_SC_ZNS_INVALID_WRITE`` - Zone Invalid Write: The write to a zone - was not at the write pointer. - -``NVME_SC_ZNS_TOO_MANY_ACTIVE`` - Too Many Active Zones: The controller - does not allow additional active zones. - -``NVME_SC_ZNS_TOO_MANY_OPENS`` - Too Many Open Zones: The controller does - not allow additional open zones. - -``NVME_SC_ZNS_INVAL_TRANSITION`` - Invalid Zone State Transition: The request - is not a valid zone state transition. - -``NVME_SC_WRITE_FAULT`` - Write Fault: The write data could not be - committed to the media. - -``NVME_SC_READ_ERROR`` - Unrecovered Read Error: The read data - could not be recovered from the media. - -``NVME_SC_GUARD_CHECK`` - End-to-end Guard Check Error: The command - was aborted due to an end-to-end guard - check failure. - -``NVME_SC_APPTAG_CHECK`` - End-to-end Application Tag Check Error: - The command was aborted due to an - end-to-end application tag check failure. - -``NVME_SC_REFTAG_CHECK`` - End-to-end Reference Tag Check Error: The - command was aborted due to an end-to-end - reference tag check failure. - -``NVME_SC_COMPARE_FAILED`` - Compare Failure: The command failed due - to a miscompare during a Compare command. - -``NVME_SC_ACCESS_DENIED`` - Access Denied: Access to the namespace - and/or LBA range is denied due to lack of - access rights. - -``NVME_SC_UNWRITTEN_BLOCK`` - Deallocated or Unwritten Logical Block: - The command failed due to an attempt to - read from or verify an LBA range - containing a deallocated or unwritten - logical block. - -``NVME_SC_STORAGE_TAG_CHECK`` - End-to-End Storage Tag Check Error: The - command was aborted due to an end-to-end - storage tag check failure. - -``NVME_SC_ANA_INTERNAL_PATH_ERROR`` - Internal Path Error: The command was not - completed as the result of a controller - internal error that is specific to the - controller processing the command. - -``NVME_SC_ANA_PERSISTENT_LOSS`` - Asymmetric Access Persistent Loss: The - requested function (e.g., command) is not - able to be performed as a result of the - relationship between the controller and - the namespace being in the ANA Persistent - Loss state. - -``NVME_SC_ANA_INACCESSIBLE`` - Asymmetric Access Inaccessible: The - requested function (e.g., command) is not - able to be performed as a result of the - relationship between the controller and - the namespace being in the ANA - Inaccessible state. - -``NVME_SC_ANA_TRANSITION`` - Asymmetric Access Transition: The - requested function (e.g., command) is not - able to be performed as a result of the - relationship between the controller and - the namespace transitioning between - Asymmetric Namespace Access states. - -``NVME_SC_CTRL_PATH_ERROR`` - Controller Pathing Error: A pathing error - was detected by the controller. - -``NVME_SC_HOST_PATH_ERROR`` - Host Pathing Error: A pathing error was - detected by the host. - -``NVME_SC_CMD_ABORTED_BY_HOST`` - Command Aborted By Host: The command was - aborted as a result of host action. - -``NVME_SC_CRD`` - Mask to get value of Command Retry Delay - index - -``NVME_SC_MORE`` - More bit. If set, more status information - for this command as part of the Error - Information log that may be retrieved with - the Get Log Page command. - -``NVME_SC_DNR`` - Do Not Retry bit. If set, if the same - command is re-submitted to any controller - in the NVM subsystem, then that - re-submitted command is expected to fail. - - -.. c:function:: __u16 nvme_status_code_type (__u16 status_field) - - Returns the NVMe Status Code Type - -**Parameters** - -``__u16 status_field`` - The NVMe Completion Queue Entry's Status Field - See :c:type:`enum nvme_status_field ` - -**Return** - -status code type - - -.. c:function:: __u16 nvme_status_code (__u16 status_field) - - Returns the NVMe Status Code - -**Parameters** - -``__u16 status_field`` - The NVMe Completion Queue Entry's Status Field - See :c:type:`enum nvme_status_field ` - -**Return** - -status code - - - - -.. c:enum:: nvme_status_type - - type encoding for NVMe return values, when represented as an int. - -**Constants** - -``NVME_STATUS_TYPE_SHIFT`` - shift value for status bits - -``NVME_STATUS_TYPE_MASK`` - mask value for status bits - -``NVME_STATUS_TYPE_NVME`` - NVMe command status value, typically from CDW3 - -``NVME_STATUS_TYPE_MI`` - NVMe-MI header status - -**Description** - - -The nvme_* api returns an int, with negative values indicating an internal -or syscall error, zero signifying success, positive values representing -the NVMe status. - -That latter case (the NVMe status) may represent status values from -different parts of the transport/controller/etc, and are at most 16 bits of -data. So, we use the most-significant 3 bits of the signed int to indicate -which type of status this is. - - -.. c:function:: __u32 nvme_status_get_type (int status) - - extract the type from a nvme_* return value - -**Parameters** - -``int status`` - the (non-negative) return value from the NVMe API - -**Return** - -the type component of the status. - - -.. c:function:: __u32 nvme_status_get_value (int status) - - extract the status value from a nvme_* return value - -**Parameters** - -``int status`` - the (non-negative) return value from the NVMe API - -**Return** - -the value component of the status; the set of values will depend -on the status type. - - -.. c:function:: __u32 nvme_status_equals (int status, enum nvme_status_type type, unsigned int value) - - helper to check a status against a type and value - -**Parameters** - -``int status`` - the (non-negative) return value from the NVMe API - -``enum nvme_status_type type`` - the status type - -``unsigned int value`` - the status value - -**Return** - -true if **status** is of the specified type and value - - - - -.. c:enum:: nvme_admin_opcode - - Known NVMe admin opcodes - -**Constants** - -``nvme_admin_delete_sq`` - Delete I/O Submission Queue - -``nvme_admin_create_sq`` - Create I/O Submission Queue - -``nvme_admin_get_log_page`` - Get Log Page - -``nvme_admin_delete_cq`` - Delete I/O Completion Queue - -``nvme_admin_create_cq`` - Create I/O Completion Queue - -``nvme_admin_identify`` - Identify - -``nvme_admin_abort_cmd`` - Abort - -``nvme_admin_set_features`` - Set Features - -``nvme_admin_get_features`` - Get Features - -``nvme_admin_async_event`` - Asynchronous Event Request - -``nvme_admin_ns_mgmt`` - Namespace Management - -``nvme_admin_fw_commit`` - Firmware Commit - -``nvme_admin_fw_activate`` - Firmware Commit - -``nvme_admin_fw_download`` - Firmware Image Download - -``nvme_admin_dev_self_test`` - Device Self-test - -``nvme_admin_ns_attach`` - Namespace Attachment - -``nvme_admin_keep_alive`` - Keep Alive - -``nvme_admin_directive_send`` - Directive Send - -``nvme_admin_directive_recv`` - Directive Receive - -``nvme_admin_virtual_mgmt`` - Virtualization Management - -``nvme_admin_nvme_mi_send`` - NVMe-MI Send - -``nvme_admin_nvme_mi_recv`` - NVMe-MI Receive - -``nvme_admin_capacity_mgmt`` - Capacity Management - -``nvme_admin_discovery_info_mgmt`` - Discovery Information Management (DIM) - -``nvme_admin_fabric_zoning_recv`` - Fabric Zoning Receive - -``nvme_admin_lockdown`` - Lockdown - -``nvme_admin_fabric_zoning_lookup`` - Fabric Zoning Lookup - -``nvme_admin_fabric_zoning_send`` - Fabric Zoning Send - -``nvme_admin_dbbuf`` - Doorbell Buffer Config - -``nvme_admin_fabrics`` - Fabrics Commands - -``nvme_admin_format_nvm`` - Format NVM - -``nvme_admin_security_send`` - Security Send - -``nvme_admin_security_recv`` - Security Receive - -``nvme_admin_sanitize_nvm`` - Sanitize - -``nvme_admin_get_lba_status`` - Get LBA Status - - - - -.. c:enum:: nvme_identify_cns - - Identify - CNS Values - -**Constants** - -``NVME_IDENTIFY_CNS_NS`` - Identify Namespace data structure - -``NVME_IDENTIFY_CNS_CTRL`` - Identify Controller data structure - -``NVME_IDENTIFY_CNS_NS_ACTIVE_LIST`` - Active Namespace ID list - -``NVME_IDENTIFY_CNS_NS_DESC_LIST`` - Namespace Identification Descriptor list - -``NVME_IDENTIFY_CNS_NVMSET_LIST`` - NVM Set List - -``NVME_IDENTIFY_CNS_CSI_NS`` - I/O Command Set specific Identify - Namespace data structure - -``NVME_IDENTIFY_CNS_CSI_CTRL`` - I/O Command Set specific Identify - Controller data structure - -``NVME_IDENTIFY_CNS_CSI_NS_ACTIVE_LIST`` - Active Namespace ID list associated - with the specified I/O Command Set - -``NVME_IDENTIFY_CNS_CSI_INDEPENDENT_ID_NS`` - I/O Command Set Independent Identify - -``NVME_IDENTIFY_CNS_NS_USER_DATA_FORMAT`` - Namespace user data format - -``NVME_IDENTIFY_CNS_CSI_NS_USER_DATA_FORMAT`` - I/O Command Set specific user data - format - Namespace data structure - -``NVME_IDENTIFY_CNS_ALLOCATED_NS_LIST`` - Allocated Namespace ID list - -``NVME_IDENTIFY_CNS_ALLOCATED_NS`` - Identify Namespace data structure for - the specified allocated NSID - -``NVME_IDENTIFY_CNS_NS_CTRL_LIST`` - Controller List of controllers attached - to the specified NSID - -``NVME_IDENTIFY_CNS_CTRL_LIST`` - Controller List of controllers that exist - in the NVM subsystem - -``NVME_IDENTIFY_CNS_PRIMARY_CTRL_CAP`` - Primary Controller Capabilities data - structure for the specified primary controller - -``NVME_IDENTIFY_CNS_SECONDARY_CTRL_LIST`` - Secondary Controller list of controllers - associated with the primary controller - processing the command - -``NVME_IDENTIFY_CNS_NS_GRANULARITY`` - A Namespace Granularity List - -``NVME_IDENTIFY_CNS_UUID_LIST`` - A UUID List - -``NVME_IDENTIFY_CNS_DOMAIN_LIST`` - Domain List - -``NVME_IDENTIFY_CNS_ENDURANCE_GROUP_ID`` - Endurance Group List - -``NVME_IDENTIFY_CNS_CSI_ALLOCATED_NS_LIST`` - I/O Command Set specific Allocated Namespace - ID list - -``NVME_IDENTIFY_CNS_CSI_ID_NS_DATA_STRUCTURE`` - I/O Command Set specific ID Namespace - Data Structure for Allocated Namespace ID - -``NVME_IDENTIFY_CNS_COMMAND_SET_STRUCTURE`` - Base Specification 2.0a section 5.17.2.21 - - - - -.. c:enum:: nvme_cmd_get_log_lid - - Get Log Page -Log Page Identifiers - -**Constants** - -``NVME_LOG_LID_SUPPORTED_LOG_PAGES`` - Supported Log Pages - -``NVME_LOG_LID_ERROR`` - Error Information - -``NVME_LOG_LID_SMART`` - SMART / Health Information - -``NVME_LOG_LID_FW_SLOT`` - Firmware Slot Information - -``NVME_LOG_LID_CHANGED_NS`` - Changed Namespace List - -``NVME_LOG_LID_CMD_EFFECTS`` - Commands Supported and Effects - -``NVME_LOG_LID_DEVICE_SELF_TEST`` - Device Self-test - -``NVME_LOG_LID_TELEMETRY_HOST`` - Telemetry Host-Initiated - -``NVME_LOG_LID_TELEMETRY_CTRL`` - Telemetry Controller-Initiated - -``NVME_LOG_LID_ENDURANCE_GROUP`` - Endurance Group Information - -``NVME_LOG_LID_PREDICTABLE_LAT_NVMSET`` - Predictable Latency Per NVM Set - -``NVME_LOG_LID_PREDICTABLE_LAT_AGG`` - Predictable Latency Event Aggregate - -``NVME_LOG_LID_ANA`` - Asymmetric Namespace Access - -``NVME_LOG_LID_PERSISTENT_EVENT`` - Persistent Event Log - -``NVME_LOG_LID_LBA_STATUS`` - LBA Status Information - -``NVME_LOG_LID_ENDURANCE_GRP_EVT`` - Endurance Group Event Aggregate - -``NVME_LOG_LID_MEDIA_UNIT_STATUS`` - Media Unit Status - -``NVME_LOG_LID_SUPPORTED_CAP_CONFIG_LIST`` - Supported Capacity Configuration Lis - -``NVME_LOG_LID_FID_SUPPORTED_EFFECTS`` - Feature Identifiers Supported and Effects - -``NVME_LOG_LID_MI_CMD_SUPPORTED_EFFECTS`` - NVMe-MI Commands Supported and Effects - -``NVME_LOG_LID_BOOT_PARTITION`` - Boot Partition - -``NVME_LOG_LID_DISCOVER`` - Discovery - -``NVME_LOG_LID_RESERVATION`` - Reservation Notification - -``NVME_LOG_LID_SANITIZE`` - Sanitize Status - -``NVME_LOG_LID_ZNS_CHANGED_ZONES`` - Changed Zone List - - - - -.. c:enum:: nvme_features_id - - Features - Feature Identifiers - -**Constants** - -``NVME_FEAT_FID_ARBITRATION`` - Arbitration - -``NVME_FEAT_FID_POWER_MGMT`` - Power Management - -``NVME_FEAT_FID_LBA_RANGE`` - LBA Range Type - -``NVME_FEAT_FID_TEMP_THRESH`` - Temperature Threshold - -``NVME_FEAT_FID_ERR_RECOVERY`` - Error Recovery - -``NVME_FEAT_FID_VOLATILE_WC`` - Volatile Write Cache - -``NVME_FEAT_FID_NUM_QUEUES`` - Number of Queues - -``NVME_FEAT_FID_IRQ_COALESCE`` - Interrupt Coalescing - -``NVME_FEAT_FID_IRQ_CONFIG`` - Interrupt Vector Configuration - -``NVME_FEAT_FID_WRITE_ATOMIC`` - Write Atomicity Normal - -``NVME_FEAT_FID_ASYNC_EVENT`` - Asynchronous Event Configuration - -``NVME_FEAT_FID_AUTO_PST`` - Autonomous Power State Transition - -``NVME_FEAT_FID_HOST_MEM_BUF`` - Host Memory Buffer - -``NVME_FEAT_FID_TIMESTAMP`` - Timestamp - -``NVME_FEAT_FID_KATO`` - Keep Alive Timer - -``NVME_FEAT_FID_HCTM`` - Host Controlled Thermal Management - -``NVME_FEAT_FID_NOPSC`` - Non-Operational Power State Config - -``NVME_FEAT_FID_RRL`` - Read Recovery Level Config - -``NVME_FEAT_FID_PLM_CONFIG`` - Predictable Latency Mode Config - -``NVME_FEAT_FID_PLM_WINDOW`` - Predictable Latency Mode Window - -``NVME_FEAT_FID_LBA_STS_INTERVAL`` - LBA Status Information Report Interval - -``NVME_FEAT_FID_HOST_BEHAVIOR`` - Host Behavior Support - -``NVME_FEAT_FID_SANITIZE`` - Endurance Group Event Configuration - -``NVME_FEAT_FID_ENDURANCE_EVT_CFG`` - Endurance Group Event Configuration - -``NVME_FEAT_FID_IOCS_PROFILE`` - I/O Command Set Profile - -``NVME_FEAT_FID_SPINUP_CONTROL`` - Spinup Control - -``NVME_FEAT_FID_ENH_CTRL_METADATA`` - Enhanced Controller Metadata - -``NVME_FEAT_FID_CTRL_METADATA`` - Controller Metadata - -``NVME_FEAT_FID_NS_METADATA`` - Namespace Metadata - -``NVME_FEAT_FID_SW_PROGRESS`` - Software Progress Marker - -``NVME_FEAT_FID_HOST_ID`` - Host Identifier - -``NVME_FEAT_FID_RESV_MASK`` - Reservation Notification Mask - -``NVME_FEAT_FID_RESV_PERSIST`` - Reservation Persistence - -``NVME_FEAT_FID_WRITE_PROTECT`` - Namespace Write Protection Config - - - - -.. c:enum:: nvme_feat - - Features Access Shifts/Masks values - -**Constants** - -``NVME_FEAT_ARBITRATION_BURST_SHIFT`` - -``NVME_FEAT_ARBITRATION_BURST_MASK`` - -``NVME_FEAT_ARBITRATION_LPW_SHIFT`` - -``NVME_FEAT_ARBITRATION_LPW_MASK`` - -``NVME_FEAT_ARBITRATION_MPW_SHIFT`` - -``NVME_FEAT_ARBITRATION_MPW_MASK`` - -``NVME_FEAT_ARBITRATION_HPW_SHIFT`` - -``NVME_FEAT_ARBITRATION_HPW_MASK`` - -``NVME_FEAT_PWRMGMT_PS_SHIFT`` - -``NVME_FEAT_PWRMGMT_PS_MASK`` - -``NVME_FEAT_PWRMGMT_WH_SHIFT`` - -``NVME_FEAT_PWRMGMT_WH_MASK`` - -``NVME_FEAT_LBAR_NR_SHIFT`` - -``NVME_FEAT_LBAR_NR_MASK`` - -``NVME_FEAT_TT_TMPTH_SHIFT`` - -``NVME_FEAT_TT_TMPTH_MASK`` - -``NVME_FEAT_TT_TMPSEL_SHIFT`` - -``NVME_FEAT_TT_TMPSEL_MASK`` - -``NVME_FEAT_TT_THSEL_SHIFT`` - -``NVME_FEAT_TT_THSEL_MASK`` - -``NVME_FEAT_ERROR_RECOVERY_TLER_SHIFT`` - -``NVME_FEAT_ERROR_RECOVERY_TLER_MASK`` - -``NVME_FEAT_ERROR_RECOVERY_DULBE_SHIFT`` - -``NVME_FEAT_ERROR_RECOVERY_DULBE_MASK`` - -``NVME_FEAT_VWC_WCE_SHIFT`` - -``NVME_FEAT_VWC_WCE_MASK`` - -``NVME_FEAT_NRQS_NSQR_SHIFT`` - -``NVME_FEAT_NRQS_NSQR_MASK`` - -``NVME_FEAT_NRQS_NCQR_SHIFT`` - -``NVME_FEAT_NRQS_NCQR_MASK`` - -``NVME_FEAT_IRQC_THR_SHIFT`` - -``NVME_FEAT_IRQC_THR_MASK`` - -``NVME_FEAT_IRQC_TIME_SHIFT`` - -``NVME_FEAT_IRQC_TIME_MASK`` - -``NVME_FEAT_ICFG_IV_SHIFT`` - -``NVME_FEAT_ICFG_IV_MASK`` - -``NVME_FEAT_ICFG_CD_SHIFT`` - -``NVME_FEAT_ICFG_CD_MASK`` - -``NVME_FEAT_WA_DN_SHIFT`` - -``NVME_FEAT_WA_DN_MASK`` - -``NVME_FEAT_AE_SMART_SHIFT`` - -``NVME_FEAT_AE_SMART_MASK`` - -``NVME_FEAT_AE_NAN_SHIFT`` - -``NVME_FEAT_AE_NAN_MASK`` - -``NVME_FEAT_AE_FW_SHIFT`` - -``NVME_FEAT_AE_FW_MASK`` - -``NVME_FEAT_AE_TELEM_SHIFT`` - -``NVME_FEAT_AE_TELEM_MASK`` - -``NVME_FEAT_AE_ANA_SHIFT`` - -``NVME_FEAT_AE_ANA_MASK`` - -``NVME_FEAT_AE_PLA_SHIFT`` - -``NVME_FEAT_AE_PLA_MASK`` - -``NVME_FEAT_AE_LBAS_SHIFT`` - -``NVME_FEAT_AE_LBAS_MASK`` - -``NVME_FEAT_AE_EGA_SHIFT`` - -``NVME_FEAT_AE_EGA_MASK`` - -``NVME_FEAT_APST_APSTE_SHIFT`` - -``NVME_FEAT_APST_APSTE_MASK`` - -``NVME_FEAT_HMEM_EHM_SHIFT`` - -``NVME_FEAT_HMEM_EHM_MASK`` - -``NVME_FEAT_HCTM_TMT2_SHIFT`` - -``NVME_FEAT_HCTM_TMT2_MASK`` - -``NVME_FEAT_HCTM_TMT1_SHIFT`` - -``NVME_FEAT_HCTM_TMT1_MASK`` - -``NVME_FEAT_NOPS_NOPPME_SHIFT`` - -``NVME_FEAT_NOPS_NOPPME_MASK`` - -``NVME_FEAT_RRL_RRL_SHIFT`` - -``NVME_FEAT_RRL_RRL_MASK`` - -``NVME_FEAT_PLM_PLME_SHIFT`` - -``NVME_FEAT_PLM_PLME_MASK`` - -``NVME_FEAT_PLMW_WS_SHIFT`` - -``NVME_FEAT_PLMW_WS_MASK`` - -``NVME_FEAT_LBAS_LSIRI_SHIFT`` - -``NVME_FEAT_LBAS_LSIRI_MASK`` - -``NVME_FEAT_LBAS_LSIPI_SHIFT`` - -``NVME_FEAT_LBAS_LSIPI_MASK`` - -``NVME_FEAT_SC_NODRM_SHIFT`` - -``NVME_FEAT_SC_NODRM_MASK`` - -``NVME_FEAT_EG_ENDGID_SHIFT`` - -``NVME_FEAT_EG_ENDGID_MASK`` - -``NVME_FEAT_EG_EGCW_SHIFT`` - -``NVME_FEAT_EG_EGCW_MASK`` - -``NVME_FEAT_SPM_PBSLC_SHIFT`` - -``NVME_FEAT_SPM_PBSLC_MASK`` - -``NVME_FEAT_HOSTID_EXHID_SHIFT`` - -``NVME_FEAT_HOSTID_EXHID_MASK`` - -``NVME_FEAT_RM_REGPRE_SHIFT`` - -``NVME_FEAT_RM_REGPRE_MASK`` - -``NVME_FEAT_RM_RESREL_SHIFT`` - -``NVME_FEAT_RM_RESREL_MASK`` - -``NVME_FEAT_RM_RESPRE_SHIFT`` - -``NVME_FEAT_RM_RESPRE_MASK`` - -``NVME_FEAT_RP_PTPL_SHIFT`` - -``NVME_FEAT_RP_PTPL_MASK`` - -``NVME_FEAT_WP_WPS_SHIFT`` - -``NVME_FEAT_WP_WPS_MASK`` - -``NVME_FEAT_IOCSP_IOCSCI_SHIFT`` - -``NVME_FEAT_IOCSP_IOCSCI_MASK`` - - - - -.. c:enum:: nvme_get_features_sel - - Get Features - Select - -**Constants** - -``NVME_GET_FEATURES_SEL_CURRENT`` - Current value - -``NVME_GET_FEATURES_SEL_DEFAULT`` - Default value - -``NVME_GET_FEATURES_SEL_SAVED`` - Saved value - -``NVME_GET_FEATURES_SEL_SUPPORTED`` - Supported capabilities - - - - -.. c:enum:: nvme_cmd_format_mset - - Format NVM - Metadata Settings - -**Constants** - -``NVME_FORMAT_MSET_SEPARATE`` - indicates that the metadata is transferred - as part of a separate buffer. - -``NVME_FORMAT_MSET_EXTENDED`` - indicates that the metadata is transferred - as part of an extended data LBA. - - - - -.. c:enum:: nvme_cmd_format_pi - - Format NVM - Protection Information - -**Constants** - -``NVME_FORMAT_PI_DISABLE`` - Protection information is not enabled. - -``NVME_FORMAT_PI_TYPE1`` - Protection information is enabled, Type 1. - -``NVME_FORMAT_PI_TYPE2`` - Protection information is enabled, Type 2. - -``NVME_FORMAT_PI_TYPE3`` - Protection information is enabled, Type 3. - - - - -.. c:enum:: nvme_cmd_format_pil - - Format NVM - Protection Information Location - -**Constants** - -``NVME_FORMAT_PIL_LAST`` - Protection information is transferred as the last - bytes of metadata. - -``NVME_FORMAT_PIL_FIRST`` - Protection information is transferred as the first - bytes of metadata. - - - - -.. c:enum:: nvme_cmd_format_ses - - Format NVM - Secure Erase Settings - -**Constants** - -``NVME_FORMAT_SES_NONE`` - No secure erase operation requested. - -``NVME_FORMAT_SES_USER_DATA_ERASE`` - User Data Erase: All user data shall be erased, - contents of the user data after the erase is - indeterminate (e.g. the user data may be zero - filled, one filled, etc.). If a User Data Erase - is requested and all affected user data is - encrypted, then the controller is allowed - to use a cryptographic erase to perform - the requested User Data Erase. - -``NVME_FORMAT_SES_CRYPTO_ERASE`` - Cryptographic Erase: All user data shall - be erased cryptographically. This is - accomplished by deleting the encryption key. - - - - -.. c:enum:: nvme_ns_mgmt_sel - - Namespace Management - Select - -**Constants** - -``NVME_NS_MGMT_SEL_CREATE`` - Namespace Create selection - -``NVME_NS_MGMT_SEL_DELETE`` - Namespace Delete selection - - - - -.. c:enum:: nvme_ns_attach_sel - - Namespace Attachment - Select - -**Constants** - -``NVME_NS_ATTACH_SEL_CTRL_ATTACH`` - Namespace attach selection - -``NVME_NS_ATTACH_SEL_CTRL_DEATTACH`` - Namespace detach selection - - - - -.. c:enum:: nvme_fw_commit_ca - - Firmware Commit - Commit Action - -**Constants** - -``NVME_FW_COMMIT_CA_REPLACE`` - Downloaded image replaces the existing - image, if any, in the specified Firmware - Slot. The newly placed image is not - activated. - -``NVME_FW_COMMIT_CA_REPLACE_AND_ACTIVATE`` - Downloaded image replaces the existing - image, if any, in the specified Firmware - Slot. The newly placed image is activated - at the next Controller Level Reset. - -``NVME_FW_COMMIT_CA_SET_ACTIVE`` - The existing image in the specified - Firmware Slot is activated at the - next Controller Level Reset. - -``NVME_FW_COMMIT_CA_REPLACE_AND_ACTIVATE_IMMEDIATE`` - Downloaded image replaces the existing - image, if any, in the specified Firmware - Slot and is then activated immediately. - If there is not a newly downloaded image, - then the existing image in the specified - firmware slot is activated immediately. - -``NVME_FW_COMMIT_CA_REPLACE_BOOT_PARTITION`` - Downloaded image replaces the Boot - Partition specified by the Boot - Partition ID field. - -``NVME_FW_COMMIT_CA_ACTIVATE_BOOT_PARTITION`` - Mark the Boot Partition specified in - the BPID field as active and update - BPINFO.ABPID. - - - - -.. c:enum:: nvme_directive_dtype - - Directive Types - -**Constants** - -``NVME_DIRECTIVE_DTYPE_IDENTIFY`` - Identify directive type - -``NVME_DIRECTIVE_DTYPE_STREAMS`` - Streams directive type - - - - -.. c:enum:: nvme_directive_receive_doper - - Directive Receive Directive Operation - -**Constants** - -``NVME_DIRECTIVE_RECEIVE_IDENTIFY_DOPER_PARAM`` - -``NVME_DIRECTIVE_RECEIVE_STREAMS_DOPER_PARAM`` - -``NVME_DIRECTIVE_RECEIVE_STREAMS_DOPER_STATUS`` - -``NVME_DIRECTIVE_RECEIVE_STREAMS_DOPER_RESOURCE`` - - - - -.. c:enum:: nvme_directive_send_doper - - Directive Send Directive Operation - -**Constants** - -``NVME_DIRECTIVE_SEND_IDENTIFY_DOPER_ENDIR`` - -``NVME_DIRECTIVE_SEND_STREAMS_DOPER_RELEASE_IDENTIFIER`` - -``NVME_DIRECTIVE_SEND_STREAMS_DOPER_RELEASE_RESOURCE`` - - - - -.. c:enum:: nvme_directive_send_identify_endir - - Enable Directive - -**Constants** - -``NVME_DIRECTIVE_SEND_IDENTIFY_ENDIR_DISABLE`` - -``NVME_DIRECTIVE_SEND_IDENTIFY_ENDIR_ENABLE`` - - - - -.. c:enum:: nvme_sanitize_sanact - - Sanitize Action - -**Constants** - -``NVME_SANITIZE_SANACT_EXIT_FAILURE`` - Exit Failure Mode. - -``NVME_SANITIZE_SANACT_START_BLOCK_ERASE`` - Start a Block Erase sanitize operation. - -``NVME_SANITIZE_SANACT_START_OVERWRITE`` - Start an Overwrite sanitize operation. - -``NVME_SANITIZE_SANACT_START_CRYPTO_ERASE`` - Start a Crypto Erase sanitize operation. - - - - -.. c:enum:: nvme_dst_stc - - Action taken by the Device Self-test command - -**Constants** - -``NVME_DST_STC_SHORT`` - Start a short device self-test operation - -``NVME_DST_STC_LONG`` - Start an extended device self-test operation - -``NVME_DST_STC_VS`` - Start a vendor specific device self-test operation - -``NVME_DST_STC_ABORT`` - Abort device self-test operation - - - - -.. c:enum:: nvme_virt_mgmt_act - - Virtualization Management - Action - -**Constants** - -``NVME_VIRT_MGMT_ACT_PRIM_CTRL_FLEX_ALLOC`` - Primary Controller Flexible - Allocation - -``NVME_VIRT_MGMT_ACT_OFFLINE_SEC_CTRL`` - Secondary Controller Offline - -``NVME_VIRT_MGMT_ACT_ASSIGN_SEC_CTRL`` - Secondary Controller Assign - -``NVME_VIRT_MGMT_ACT_ONLINE_SEC_CTRL`` - Secondary Controller Online - - - - -.. c:enum:: nvme_virt_mgmt_rt - - Virtualization Management - Resource Type - -**Constants** - -``NVME_VIRT_MGMT_RT_VQ_RESOURCE`` - VQ Resources - -``NVME_VIRT_MGMT_RT_VI_RESOURCE`` - VI Resources - - - - -.. c:enum:: nvme_ns_write_protect_cfg - - Write Protection - Write Protection State - -**Constants** - -``NVME_NS_WP_CFG_NONE`` - No Write Protect - -``NVME_NS_WP_CFG_PROTECT`` - Write Protect - -``NVME_NS_WP_CFG_PROTECT_POWER_CYCLE`` - Write Protect Until Power Cycle - -``NVME_NS_WP_CFG_PROTECT_PERMANENT`` - Permanent Write Protect - - - - -.. c:enum:: nvme_log_ana_lsp - - Asymmetric Namespace Access - Return Groups Only - -**Constants** - -``NVME_LOG_ANA_LSP_RGO_NAMESPACES`` - -``NVME_LOG_ANA_LSP_RGO_GROUPS_ONLY`` - - - - -.. c:enum:: nvme_pevent_log_action - - Persistent Event Log - Action - -**Constants** - -``NVME_PEVENT_LOG_READ`` - Read Log Data - -``NVME_PEVENT_LOG_EST_CTX_AND_READ`` - Establish Context and Read Log Data - -``NVME_PEVENT_LOG_RELEASE_CTX`` - Release Context - - - - -.. c:enum:: nvme_feat_tmpthresh_thsel - - Temperature Threshold - Threshold Type Select - -**Constants** - -``NVME_FEATURE_TEMPTHRESH_THSEL_OVER`` - Over temperature threshold select - -``NVME_FEATURE_TEMPTHRESH_THSEL_UNDER`` - Under temperature threshold select - - - - -.. c:enum:: nvme_features_async_event_config_flags - - Asynchronous Event Configuration configuration flags - -**Constants** - -``NVME_FEATURE_AENCFG_SMART_CRIT_SPARE`` - -``NVME_FEATURE_AENCFG_SMART_CRIT_TEMPERATURE`` - -``NVME_FEATURE_AENCFG_SMART_CRIT_DEGRADED`` - -``NVME_FEATURE_AENCFG_SMART_CRIT_READ_ONLY`` - -``NVME_FEATURE_AENCFG_SMART_CRIT_VOLATILE_BACKUP`` - -``NVME_FEATURE_AENCFG_SMART_CRIT_READ_ONLY_PMR`` - -``NVME_FEATURE_AENCFG_NOTICE_NAMESPACE_ATTRIBUTES`` - -``NVME_FEATURE_AENCFG_NOTICE_FIRMWARE_ACTIVATION`` - -``NVME_FEATURE_AENCFG_NOTICE_TELEMETRY_LOG`` - -``NVME_FEATURE_AENCFG_NOTICE_ANA_CHANGE`` - -``NVME_FEATURE_AENCFG_NOTICE_PL_EVENT`` - -``NVME_FEATURE_AENCFG_NOTICE_LBA_STATUS`` - -``NVME_FEATURE_AENCFG_NOTICE_EG_EVENT`` - -``NVME_FEATURE_AENCFG_NOTICE_DISCOVERY_CHANGE`` - - - - -.. c:enum:: nvme_feat_plm_window_select - - Predictable Latency Per NVM Set Log - -**Constants** - -``NVME_FEATURE_PLM_DTWIN`` - Deterministic Window select - -``NVME_FEATURE_PLM_NDWIN`` - Non-Deterministic Window select - - - - -.. c:enum:: nvme_feat_resv_notify_flags - - Reservation Notification Configuration - -**Constants** - -``NVME_FEAT_RESV_NOTIFY_REGPRE`` - Mask Registration Preempted Notification - -``NVME_FEAT_RESV_NOTIFY_RESREL`` - Mask Reservation Released Notification - -``NVME_FEAT_RESV_NOTIFY_RESPRE`` - Mask Reservation Preempted Notification - - - - -.. c:enum:: nvme_feat_nswpcfg_state - - Write Protection - Write Protection State - -**Constants** - -``NVME_FEAT_NS_NO_WRITE_PROTECT`` - No Write Protect - -``NVME_FEAT_NS_WRITE_PROTECT`` - Write Protect - -``NVME_FEAT_NS_WRITE_PROTECT_PWR_CYCLE`` - Write Protect Until Power Cycle - -``NVME_FEAT_NS_WRITE_PROTECT_PERMANENT`` - Permanent Write Protect - - - - -.. c:enum:: nvme_fctype - - Fabrics Command Types - -**Constants** - -``nvme_fabrics_type_property_set`` - Property set - -``nvme_fabrics_type_connect`` - Connect - -``nvme_fabrics_type_property_get`` - Property Get - -``nvme_fabrics_type_auth_send`` - Authentication Send - -``nvme_fabrics_type_auth_receive`` - Authentication Receive - -``nvme_fabrics_type_disconnect`` - Disconnect - - - - -.. c:enum:: nvme_data_tfr - - Data transfer direction of the command - -**Constants** - -``NVME_DATA_TFR_NO_DATA_TFR`` - No data transfer - -``NVME_DATA_TFR_HOST_TO_CTRL`` - Host to controller - -``NVME_DATA_TFR_CTRL_TO_HOST`` - Controller to host - -``NVME_DATA_TFR_BIDIRECTIONAL`` - Bidirectional - - - - -.. c:enum:: nvme_io_opcode - - Opcodes for I/O Commands - -**Constants** - -``nvme_cmd_flush`` - Flush - -``nvme_cmd_write`` - Write - -``nvme_cmd_read`` - Read - -``nvme_cmd_write_uncor`` - Write Uncorrectable - -``nvme_cmd_compare`` - Compare - -``nvme_cmd_write_zeroes`` - write Zeros - -``nvme_cmd_dsm`` - Dataset Management - -``nvme_cmd_verify`` - Verify - -``nvme_cmd_resv_register`` - Reservation Register - -``nvme_cmd_resv_report`` - Reservation Report - -``nvme_cmd_resv_acquire`` - Reservation Acquire - -``nvme_cmd_resv_release`` - Reservation Release - -``nvme_cmd_copy`` - Copy - -``nvme_zns_cmd_mgmt_send`` - Zone Management Send - -``nvme_zns_cmd_mgmt_recv`` - Zone Management Receive - -``nvme_zns_cmd_append`` - Zone Append - - - - -.. c:enum:: nvme_io_control_flags - - I/O control flags - -**Constants** - -``NVME_IO_DTYPE_STREAMS`` - Directive Type Streams - -``NVME_IO_STC`` - Storage Tag Check - -``NVME_IO_DEAC`` - Deallocate - -``NVME_IO_ZNS_APPEND_PIREMAP`` - Protection Information Remap - -``NVME_IO_PRINFO_PRCHK_REF`` - Protection Information Check Reference Tag - -``NVME_IO_PRINFO_PRCHK_APP`` - Protection Information Check Application Tag - -``NVME_IO_PRINFO_PRCHK_GUARD`` - Protection Information Check Guard field - -``NVME_IO_PRINFO_PRACT`` - Protection Information Action - -``NVME_IO_FUA`` - Force Unit Access - -``NVME_IO_LR`` - Limited Retry - - - - -.. c:enum:: nvme_io_dsm_flags - - Dataset Management flags - -**Constants** - -``NVME_IO_DSM_FREQ_UNSPEC`` - No frequency information provided - -``NVME_IO_DSM_FREQ_TYPICAL`` - Typical number of reads and writes - expected for this LBA range - -``NVME_IO_DSM_FREQ_RARE`` - Infrequent writes and infrequent - reads to the LBA range indicated - -``NVME_IO_DSM_FREQ_READS`` - Infrequent writes and frequent - reads to the LBA range indicated - -``NVME_IO_DSM_FREQ_WRITES`` - Frequent writes and infrequent - reads to the LBA range indicated - -``NVME_IO_DSM_FREQ_RW`` - Frequent writes and frequent reads - to the LBA range indicated - -``NVME_IO_DSM_FREQ_ONCE`` - -``NVME_IO_DSM_FREQ_PREFETCH`` - -``NVME_IO_DSM_FREQ_TEMP`` - -``NVME_IO_DSM_LATENCY_NONE`` - No latency information provided - -``NVME_IO_DSM_LATENCY_IDLE`` - Longer latency acceptable - -``NVME_IO_DSM_LATENCY_NORM`` - Typical latency - -``NVME_IO_DSM_LATENCY_LOW`` - Smallest possible latency - -``NVME_IO_DSM_SEQ_REQ`` - -``NVME_IO_DSM_COMPRESSED`` - - - - -.. c:enum:: nvme_dsm_attributes - - Dataset Management attributes - -**Constants** - -``NVME_DSMGMT_IDR`` - Attribute -Integral Dataset for Read - -``NVME_DSMGMT_IDW`` - Attribute - Integral Dataset for Write - -``NVME_DSMGMT_AD`` - Attribute - Deallocate - - - - -.. c:enum:: nvme_resv_rtype - - Reservation Type Encoding - -**Constants** - -``NVME_RESERVATION_RTYPE_WE`` - Write Exclusive Reservation - -``NVME_RESERVATION_RTYPE_EA`` - Exclusive Access Reservation - -``NVME_RESERVATION_RTYPE_WERO`` - Write Exclusive - Registrants Only Reservation - -``NVME_RESERVATION_RTYPE_EARO`` - Exclusive Access - Registrants Only Reservation - -``NVME_RESERVATION_RTYPE_WEAR`` - Write Exclusive - All Registrants Reservation - -``NVME_RESERVATION_RTYPE_EAAR`` - Exclusive Access - All Registrants Reservation - - - - -.. c:enum:: nvme_resv_racqa - - Reservation Acquire - Reservation Acquire Action - -**Constants** - -``NVME_RESERVATION_RACQA_ACQUIRE`` - Acquire - -``NVME_RESERVATION_RACQA_PREEMPT`` - Preempt - -``NVME_RESERVATION_RACQA_PREEMPT_AND_ABORT`` - Preempt and Abort - - - - -.. c:enum:: nvme_resv_rrega - - Reservation Register - Reservation Register Action - -**Constants** - -``NVME_RESERVATION_RREGA_REGISTER_KEY`` - Register Reservation Key - -``NVME_RESERVATION_RREGA_UNREGISTER_KEY`` - Unregister Reservation Key - -``NVME_RESERVATION_RREGA_REPLACE_KEY`` - Replace Reservation Key - - - - -.. c:enum:: nvme_resv_cptpl - - Reservation Register - Change Persist Through Power Loss State - -**Constants** - -``NVME_RESERVATION_CPTPL_NO_CHANGE`` - No change to PTPL state - -``NVME_RESERVATION_CPTPL_CLEAR`` - Reservations are released and - registrants are cleared on a power on - -``NVME_RESERVATION_CPTPL_PERSIST`` - Reservations and registrants persist - across a power loss - - - - -.. c:enum:: nvme_resv_rrela - - Reservation Release - Reservation Release Action - -**Constants** - -``NVME_RESERVATION_RRELA_RELEASE`` - Release - -``NVME_RESERVATION_RRELA_CLEAR`` - Clear - - - - -.. c:enum:: nvme_zns_send_action - - Zone Management Send - Zone Send Action - -**Constants** - -``NVME_ZNS_ZSA_CLOSE`` - Close Zone - -``NVME_ZNS_ZSA_FINISH`` - Finish Zone - -``NVME_ZNS_ZSA_OPEN`` - Open Zone - -``NVME_ZNS_ZSA_RESET`` - Reset Zone - -``NVME_ZNS_ZSA_OFFLINE`` - Offline Zone - -``NVME_ZNS_ZSA_SET_DESC_EXT`` - Set Zone Descriptor Extension - -``NVME_ZNS_ZSA_ZRWA_FLUSH`` - Flush - - - - -.. c:enum:: nvme_zns_recv_action - - Zone Management Receive - Zone Receive Action Specific Features - -**Constants** - -``NVME_ZNS_ZRA_REPORT_ZONES`` - Report Zones - -``NVME_ZNS_ZRA_EXTENDED_REPORT_ZONES`` - Extended Report Zones - - - - -.. c:enum:: nvme_zns_report_options - - Zone Management Receive - Zone Receive Action Specific Field - -**Constants** - -``NVME_ZNS_ZRAS_REPORT_ALL`` - List all zones - -``NVME_ZNS_ZRAS_REPORT_EMPTY`` - List the zones in the ZSE:Empty state - -``NVME_ZNS_ZRAS_REPORT_IMPL_OPENED`` - List the zones in the ZSIO:Implicitly Opened state - -``NVME_ZNS_ZRAS_REPORT_EXPL_OPENED`` - List the zones in the ZSEO:Explicitly Opened state - -``NVME_ZNS_ZRAS_REPORT_CLOSED`` - List the zones in the ZSC:Closed state - -``NVME_ZNS_ZRAS_REPORT_FULL`` - List the zones in the ZSF:Full state - -``NVME_ZNS_ZRAS_REPORT_READ_ONLY`` - List the zones in the ZSRO:Read Only state - -``NVME_ZNS_ZRAS_REPORT_OFFLINE`` - List the zones in the ZSO:Offline state - - diff --git a/doc/rst/util.rst b/doc/rst/util.rst deleted file mode 100644 index a0af1a09..00000000 --- a/doc/rst/util.rst +++ /dev/null @@ -1,574 +0,0 @@ -.. _util.h: - -**util.h** - - -libnvme utility functions - - - -.. c:enum:: nvme_connect_err - - nvme connect error codes - -**Constants** - -``ENVME_CONNECT_RESOLVE`` - failed to resolve host - -``ENVME_CONNECT_ADDRFAM`` - unrecognized address family - -``ENVME_CONNECT_TRADDR`` - failed to get traddr - -``ENVME_CONNECT_TARG`` - need a transport (-t) argument - -``ENVME_CONNECT_AARG`` - need a address (-a) argument - -``ENVME_CONNECT_OPEN`` - failed to open nvme-fabrics device - -``ENVME_CONNECT_WRITE`` - failed to write to nvme-fabrics device - -``ENVME_CONNECT_READ`` - failed to read from nvme-fabrics device - -``ENVME_CONNECT_PARSE`` - failed to parse ctrl info - -``ENVME_CONNECT_INVAL_TR`` - invalid transport type - -``ENVME_CONNECT_LOOKUP_SUBSYS_NAME`` - failed to lookup subsystem name - -``ENVME_CONNECT_LOOKUP_SUBSYS`` - failed to lookup subsystem - -``ENVME_CONNECT_ALREADY`` - the connect attempt failed, already connected - -``ENVME_CONNECT_INVAL`` - invalid arguments/configuration - -``ENVME_CONNECT_ADDRINUSE`` - hostnqn already in use - -``ENVME_CONNECT_NODEV`` - invalid interface - -``ENVME_CONNECT_OPNOTSUPP`` - not supported - - -.. c:function:: __u8 nvme_status_to_errno (int status, bool fabrics) - - Converts nvme return status to errno - -**Parameters** - -``int status`` - Return status from an nvme passthrough command - -``bool fabrics`` - Set to true if :c:type:`status` is to a fabrics target. - -**Return** - -An errno representing the nvme status if it is an nvme status field, -or unchanged status is < 0 since errno is already set. - - -.. c:function:: const char * nvme_status_to_string (int status, bool fabrics) - - Returns string describing nvme return status. - -**Parameters** - -``int status`` - Return status from an nvme passthrough command - -``bool fabrics`` - Set to true if :c:type:`status` is to a fabrics target. - -**Return** - -String representation of the nvme status if it is an nvme status field, -or a standard errno string if status is < 0. - - -.. c:function:: const char * nvme_errno_to_string (int err) - - Returns string describing nvme connect failures - -**Parameters** - -``int err`` - Returned error code from nvme_add_ctrl() - -**Return** - -String representation of the nvme connect error codes - - -.. c:function:: void nvme_init_ctrl_list (struct nvme_ctrl_list *cntlist, __u16 num_ctrls, __u16 *ctrlist) - - Initialize an nvme_ctrl_list structure from an array. - -**Parameters** - -``struct nvme_ctrl_list *cntlist`` - The controller list structure to initialize - -``__u16 num_ctrls`` - The number of controllers in the array, :c:type:`ctrlist`. - -``__u16 *ctrlist`` - An array of controller identifiers in CPU native endian. - -**Description** - -This is intended to be used with any command that takes a controller list -argument. See nvme_ns_attach_ctrls() and nvme_ns_detach(). - - -.. c:function:: void nvme_init_dsm_range (struct nvme_dsm_range *dsm, __u32 *ctx_attrs, __u32 *llbas, __u64 *slbas, __u16 nr_ranges) - - Constructs a data set range structure - -**Parameters** - -``struct nvme_dsm_range *dsm`` - DSM range array - -``__u32 *ctx_attrs`` - Array of context attributes - -``__u32 *llbas`` - Array of length in logical blocks - -``__u64 *slbas`` - Array of starting logical blocks - -``__u16 nr_ranges`` - The size of the dsm arrays - -**Description** - -Each array must be the same size of size 'nr_ranges'. This is intended to be -used with constructing a payload for nvme_dsm(). - -**Return** - -The nvme command status if a response was received or -errno -otherwise. - - -.. c:function:: void nvme_init_copy_range (struct nvme_copy_range *copy, __u16 *nlbs, __u64 *slbas, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr) - - Constructs a copy range structure - -**Parameters** - -``struct nvme_copy_range *copy`` - Copy range array - -``__u16 *nlbs`` - Number of logical blocks - -``__u64 *slbas`` - Starting LBA - -``__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_f1 (struct nvme_copy_range_f1 *copy, __u16 *nlbs, __u64 *slbas, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr) - - Constructs a copy range f1 structure - -**Parameters** - -``struct nvme_copy_range_f1 *copy`` - Copy range array - -``__u16 *nlbs`` - Number of logical blocks - -``__u64 *slbas`` - Starting LBA - -``__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) - - Retrieve the command payload length for a specific feature identifier - -**Parameters** - -``int fid`` - Feature identifier, see :c:type:`enum nvme_features_id `. - -``__u32 cdw11`` - The cdw11 value may affect the transfer (only known fid is - ``NVME_FEAT_FID_HOST_ID``) - -``__u32 *len`` - On success, set to this features payload length in bytes. - -**Return** - -0 on success, -1 with errno set to EINVAL if the function did not -recognize :c:type:`fid`. - - -.. c:function:: int nvme_get_feature_length2 (int fid, __u32 cdw11, enum nvme_data_tfr dir, __u32 *len) - - Retrieve the command payload length for a specific feature identifier - -**Parameters** - -``int fid`` - Feature identifier, see :c:type:`enum nvme_features_id `. - -``__u32 cdw11`` - The cdw11 value may affect the transfer (only known fid is - ``NVME_FEAT_FID_HOST_ID``) - -``enum nvme_data_tfr dir`` - Data transfer direction: false - host to controller, true - - controller to host may affect the transfer (only known fid is - ``NVME_FEAT_FID_HOST_MEM_BUF``). - -``__u32 *len`` - On success, set to this features payload length in bytes. - -**Return** - -0 on success, -1 with errno set to EINVAL if the function did not -recognize :c:type:`fid`. - - -.. c:function:: int nvme_get_directive_receive_length (enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len) - - Get directive receive length - -**Parameters** - -``enum nvme_directive_dtype dtype`` - Directive type, see :c:type:`enum nvme_directive_dtype ` - -``enum nvme_directive_receive_doper doper`` - Directive receive operation, see :c:type:`enum nvme_directive_receive_doper ` - -``__u32 *len`` - On success, set to this directives payload length in bytes. - -**Return** - -0 on success, -1 with errno set to EINVAL if the function did not -recognize :c:type:`dtype` or :c:type:`doper`. - - -.. c:function:: size_t get_entity_name (char *buffer, size_t bufsz) - - Get Entity Name (ENAME). - -**Parameters** - -``char *buffer`` - The buffer where the ENAME will be saved as an ASCII string. - -``size_t bufsz`` - The size of **buffer**. - -**Description** - -Per TP8010, ENAME is defined as the name associated with the host (i.e. -hostname). - -**Return** - -Number of characters copied to **buffer**. - - -.. c:function:: size_t get_entity_version (char *buffer, size_t bufsz) - - Get Entity Version (EVER). - -**Parameters** - -``char *buffer`` - The buffer where the EVER will be saved as an ASCII string. - -``size_t bufsz`` - The size of **buffer**. - -**Description** - -EVER is defined as the operating system name and version as an ASCII -string. This function reads different files from the file system and -builds a string as follows: [os type] [os release] [distro release] - - E.g. "Linux 5.17.0-rc1 SLES 15.4" - -**Return** - -Number of characters copied to **buffer**. - - -.. c:function:: char * kv_strip (char *kv) - - Strip blanks from key value string - -**Parameters** - -``char *kv`` - The key-value string to strip - -**Description** - -Strip leading/trailing blanks as well as trailing comments from the -Key=Value string pointed to by **kv**. - -**Return** - -A pointer to the stripped string. Note that the original string, -**kv**, gets modified. - - -.. c:function:: char * kv_keymatch (const char *kv, const char *key) - - Look for key in key value string - -**Parameters** - -``const char *kv`` - The key=value string to search for the presence of **key** - -``const char *key`` - The key to look for - -**Description** - -Look for **key** in the Key=Value pair pointed to by **k** and return a -pointer to the Value if **key** is found. - -Check if **kv** starts with **key**. If it does then make sure that we -have a whole-word match on the **key**, and if we do, return a pointer -to the first character of value (i.e. skip leading spaces, tabs, -and equal sign) - -**Return** - -A pointer to the first character of "value" if a match is found. -NULL otherwise. - - -.. c:function:: char * startswith (const char *s, const char *prefix) - - Checks that a string starts with a given prefix. - -**Parameters** - -``const char *s`` - The string to check - -``const char *prefix`` - A string that **s** could be starting with - -**Return** - -If **s** starts with **prefix**, then return a pointer within **s** at -the first character after the matched **prefix**. NULL otherwise. - - -.. c:macro:: round_up - -``round_up (val, mult)`` - - Round a value **val** to the next multiple specified by **mult**. - -**Parameters** - -``val`` - Value to round - -``mult`` - Multiple to round to. - -**Description** - -usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16 - - -.. c:function:: __u16 nvmf_exat_len (size_t val_len) - - Return length rounded up by 4 - -**Parameters** - -``size_t val_len`` - Value length - -**Description** - -Return the size in bytes, rounded to a multiple of 4 (e.g., size of -__u32), of the buffer needed to hold the exat value of size -**val_len**. - -**Return** - -Length rounded up by 4 - - -.. c:function:: __u16 nvmf_exat_size (size_t val_len) - - Return min aligned size to hold value - -**Parameters** - -``size_t val_len`` - This is the length of the data to be copied to the "exatval" - field of a "struct nvmf_ext_attr". - -**Description** - -Return the size of the "struct nvmf_ext_attr" needed to hold -a value of size **val_len**. - -**Return** - -The size in bytes, rounded to a multiple of 4 (i.e. size of -__u32), of the "struct nvmf_ext_attr" required to hold a string of -length **val_len**. - - -.. c:function:: struct nvmf_ext_attr * nvmf_exat_ptr_next (struct nvmf_ext_attr *p) - - Increment **p** to the next element in the array. - -**Parameters** - -``struct nvmf_ext_attr *p`` - Pointer to an element of an array of "struct nvmf_ext_attr". - -**Description** - -Extended attributes are saved to an array of "struct nvmf_ext_attr" -where each element of the array is of variable size. In order to -move to the next element in the array one must increment the -pointer to the current element (**p**) by the size of the current -element. - -**Return** - -Pointer to the next element in the array. - - - - -.. c:enum:: nvme_version - - Selector for version to be returned by **nvme_get_version** - -**Constants** - -``NVME_VERSION_PROJECT`` - Project release version - -``NVME_VERSION_GIT`` - Git reference - - -.. c:function:: const char * nvme_get_version (enum nvme_version type) - - Return version libnvme string - -**Parameters** - -``enum nvme_version type`` - Selects which version type (see **struct** nvme_version) - -**Return** - -Returns version string for known types or else "n/a" - - -.. c:function:: int nvme_uuid_to_string (unsigned char uuid[NVME_UUID_LEN], char *str) - - Return string represenation of encoded UUID - -**Parameters** - -``unsigned char uuid[NVME_UUID_LEN]`` - Binary encoded input UUID - -``char *str`` - Output string represenation of UUID - -**Return** - -Returns error code if type conversion fails. - - -.. c:function:: int nvme_uuid_from_string (const char *str, unsigned char uuid[NVME_UUID_LEN]) - - Return encoded UUID represenation of string UUID - -**Parameters** - -``const char *str`` - Output string represenation of UUID - -``unsigned char uuid[NVME_UUID_LEN]`` - Binary encoded input UUID - -**Return** - -Returns error code if type conversion fails. - - -.. c:function:: int nvme_uuid_random (unsigned char uuid[NVME_UUID_LEN]) - - Generate random UUID - -**Parameters** - -``unsigned char uuid[NVME_UUID_LEN]`` - Generated random UUID - -**Description** - -Generate random number according -https://www.rfc-editor.org/rfc/rfc4122#section-4.4 - -**Return** - -Returns error code if generating of random number fails. - -