### Install libnvme

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Installs the compiled libnvme library to the system. This command requires appropriate permissions.

```bash
meson install -C .build
```

--------------------------------

### Setup Debug Build Configuration

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Configure the build for debugging purposes by disabling optimization and enabling debug symbols.

```bash
meson setup .build --buildtype=debug
```

--------------------------------

### nvme_subsystem_first_ns

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Start iterating through the namespaces of an NVMe subsystem. Returns the first namespace object.

```APIDOC
## nvme_subsystem_first_ns

### Description
Start namespace iterator for a given subsystem.

### Parameters
#### Path Parameters
- **s** (nvme_subsystem_t) - Required - The subsystem object.

### Return
First namespace object (nvme_ns_t) of the subsystem iterator.
```

--------------------------------

### NVMe Format NVM Start Event Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Defines the data structure for the start of a Format NVM operation, including namespace ID and attributes.

```c
struct nvme_format_nvm_start_event {
  __le32 nsid;
  __u8 fna;
  __u8 rsvd5[3];
  __le32 format_nvm_cdw10;
};
```

--------------------------------

### Run Tests with Address Sanitizer and LD_PRELOAD

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

This command sets up the build with the address sanitizer and ensures `libasan.so` is preloaded for testing. It combines Meson setup, LD_PRELOAD, and Ninja execution.

```bash
meson setup .build -Db_sanitize=address && LD_PRELOAD=/lib64/libasan.so.6 ninja -C .build test
```

--------------------------------

### NVMe Sanitize Start Event Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Defines the data structure for the start of a Sanitize operation, including sanitize capabilities and command parameters.

```c
struct nvme_sanitize_start_event {
  __le32 sani_cap;
  __le32 sani_cdw10;
  __le32 sani_cdw11;
};
```

--------------------------------

### nvme_get_property_args

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Arguments for NVMe Get Property command.

```APIDOC
## struct nvme_get_property_args

### Description
Arguments for NVMe Get Property command.

### Members
- **value** (*__u64* *) - Description: Where the property’s value will be stored on success
- **args_size** (*int*) - Description: Size of [struct nvme_get_property_args](#c.nvme_get_property_args)
- **fd** (*int*) - Description: File descriptor of nvme device
- **timeout** (*__u32*) - Description: Timeout in ms
- **offset** (*int*) - Description: Property offset from the base to retrieve
```

--------------------------------

### Get NVMe Discovery Log Page with Arguments

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Retrieves the discovery log page using an argument structure for more options. The caller must free the returned log page memory.

```c
struct nvme_get_discovery_log *nvmf_get_discovery_wargs(struct nvme_get_discovery_args *args)
```

--------------------------------

### NVMe Get LBA Status Arguments Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Defines the arguments for the NVMe Get LBA Status command. This structure is used to specify the starting LBA, data payload, and other parameters for retrieving LBA status information.

```c
struct nvme_get_lba_status_args {
  __u64 slba;
  __u32 *result;
  struct nvme_lba_status *lbas;
  int args_size;
  int fd;
  __u32 timeout;
  __u32 nsid;
  __u32 mndw;
  enum nvme_lba_status_atype atype;
  __u16 rl;
};
```

--------------------------------

### nvme_mi_init_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Initializes a NVMe controller under a given endpoint.

```APIDOC
## nvme_mi_init_ctrl

### Description
Initialise a NVMe controller.

Create a connection to a controller behind the endpoint specified in **ep**.
Controller IDs may be queried from the endpoint through
[`nvme_mi_mi_read_mi_data_ctrl_list`](#c.nvme_mi_mi_read_mi_data_ctrl_list).
See [`nvme_mi_close_ctrl`](#c.nvme_mi_close_ctrl)

### Parameters
- **ep** (nvme_mi_ep_t) - Endpoint to create under
- **ctrl_id** (__u16) - ID of controller to initialize.

### Return
New controller object, or NULL on failure.
```

--------------------------------

### View All Meson Build Configurations

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Use this command to see all available configuration options for the Meson build system.

```bash
meson configure .build
```

--------------------------------

### Get First NVMe MI Endpoint

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Starts an iterator to retrieve the first MI endpoint object under a given NVMe root object. Returns NULL if no endpoints are present.

```c
nvme_mi_ep_t nvme_mi_first_endpoint(nvme_root_t m);
```

--------------------------------

### Build libnvme with Samurai and Muon

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Uses the `scripts/build.sh` helper script to set up and build libnvme with minimal dependencies (samurai and muon), suitable for embedded systems.

```bash
scripts/build.sh -m muon
```

--------------------------------

### nvme_init_logging

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/log.md

Initializes the logging system with a specified context, logging level, and options for including PID and timestamps.

```APIDOC
## nvme_init_logging(nvme_root_t r, int lvl, bool log_pid, bool log_tstamp)

### Description
Initializes logging with the provided context and configuration.

### Parameters
- **r** (nvme_root_t) - The NVMe root context.
- **lvl** (int) - The logging level to set.
- **log_pid** (bool) - Enable logging of the Process ID.
- **log_tstamp** (bool) - Enable logging of timestamps.

### Description
Sets the default logging variables for the library.
```

--------------------------------

### NVMe Get Property Command Arguments

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Defines the arguments for the NVMe Get Property command. Use this structure to retrieve the value of a specific property from an NVMe device.

```c
struct nvme_get_property_args {
  __u64 *value;
  int args_size;
  int fd;
  __u32 timeout;
  int offset;
};
```

--------------------------------

### NVMe Get Features Command Arguments

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Defines the arguments for the NVMe Admin Get Feature command. This structure is used to retrieve the current settings of NVMe features.

```c
struct nvme_get_features_args {
  __u32 *result;
  void *data;
  int args_size;
  int fd;
  __u32 timeout;
  __u32 nsid;
  enum nvme_get_features_sel sel;
  __u32 cdw11;
  __u32 data_len;
  __u8 fid;
  __u8 uuidx;
};
```

--------------------------------

### nvme_mi_admin_ns_mgmt_create

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Helper function for the Namespace Management Create command.

```APIDOC
## nvme_mi_admin_ns_mgmt_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.

### Parameters
- **ctrl** (nvme_mi_ctrl_t) - Controller to send command to
- **ns** (struct nvme_id_ns *) - New namespace parameters
- **csi** (__u8) - Command Set Identifier for new NS
- **nsid** (__u32 *) - Set to new namespace ID on create
- **data** (struct nvme_ns_mgmt_host_sw_specified *) - Host Software Specified Fields that defines ns creation parameters

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### NVMe Get Log Command Arguments

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Defines the arguments for the NVMe Admin Get Log command. This structure is used to retrieve log pages from an NVMe device.

```c
struct nvme_get_log_args {
  __u64 lpo;
  __u32 *result;
  void *log;
  int args_size;
  int fd;
  __u32 timeout;
  enum nvme_cmd_get_log_lid lid;
  __u32 len;
  __u32 nsid;
  enum nvme_csi csi;
  __u16 lsi;
  __u8 lsp;
  __u8 uuidx;
  bool rae;
  bool ot;
};
```

--------------------------------

### Build libnvme with Meson (Static Library)

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Configures the project to build a static library using Meson. This is an alternative to the default shared library build.

```bash
meson setup --default-library=static .build
```

--------------------------------

### nvme_init_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Initializes an nvme_ctrl_t object for an existing controller using its instance number.

```APIDOC
## nvme_init_ctrl

### Description
Initializes an nvme_ctrl_t object for an existing controller using its instance number.

### Parameters
- **h** (nvme_host_t) - nvme_host_t object
- **c** (nvme_ctrl_t) - nvme_ctrl_t object
- **instance** (int) - Instance number (e.g. 1 for nvme1)

### Return
The ioctl() return code. Typically 0 on success.
```

--------------------------------

### Build libnvme with Meson (Shared Library)

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Configures the project to build a shared library using Meson. The build artifacts are placed in a separate directory.

```bash
meson setup .build
```

--------------------------------

### nvme_fdp_reclaim_unit_handle_status

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Gets the reclaim unit handle status for FDP.

```APIDOC
## nvme_fdp_reclaim_unit_handle_status

### Description
Gets the reclaim unit handle status for FDP.

### Parameters
#### File Descriptor
- **fd** (`int`) - File descriptor of the NVMe device.
#### Namespace Identifier
- **nsid** (`__u32`) - Namespace identifier.
#### Data Length
- **data_len** (`__u32`) - Length of the response buffer.
#### Data Buffer
- **data** (`void *`) - Response buffer.

### Return
The nvme command status if a response was received (see `enum nvme_status_field`) or -1 with errno set otherwise.
```

--------------------------------

### nvme_get_log

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Executes the NVMe Admin Get Log command.

```APIDOC
## nvme_get_log

### Description
NVMe Admin Get Log command

### Parameters
#### Path Parameters
- **args** (struct nvme_get_log_args *) - Required - [`struct nvme_get_log_args`](api-types.md#c.nvme_get_log_args) argument structure

### Return
The nvme command status if a response was received (see `enum nvme_status_field`) or -1 with errno set otherwise.
```

--------------------------------

### Connect and Discover NVMe Subsystems

Source: https://github.com/linux-nvme/libnvme/blob/master/libnvme/README.md

Use this script to connect to an NVMe host, discover available subsystems, and retrieve log pages. Ensure necessary parameters like subsysnqn, transport, traddr, and trsvcid are correctly configured.

```python
#!/usr/bin/env python3
import sys
import pprint
from libnvme import nvme

def disc_supp_str(dlp_supp_opts):
    bitmap = {
        nvme.NVMF_LOG_DISC_LID_EXTDLPES: "EXTDLPES",
        nvme.NVMF_LOG_DISC_LID_PLEOS:    "PLEOS",
        nvme.NVMF_LOG_DISC_LID_ALLSUBES: "ALLSUBES",
    }
    return [txt for msk, txt in bitmap.items() if dlp_supp_opts & msk]

root = nvme.root()      # This is a singleton
root.log_level('debug') # Optional: extra debug info

host = nvme.host(root)      # This "may be" a singleton. 
subsysnqn  = [string]       # e.g. nvme.NVME_DISC_SUBSYS_NAME, ...
transport  = [string]       # One of: 'tcp', 'rdma', 'fc', 'loop'.
traddr     = [IPv4 or IPv6] # e.g. '192.168.10.10', 'fd2e:853b:3cad:e135:506a:65ee:29f2:1b18', ...
trsvcid    = [string]       # e.g. '8009', '4420', ...
host_iface = [interface]    # e.g. 'eth1', ens256', ...
ctrl = nvme.ctrl(root, subsysnqn=subsysnqn, transport=transport, traddr=traddr, trsvcid=trsvcid, host_iface=host_iface)

try:
    cfg = {
        'hdr_digest': True,   # Enable header digests
        'data_digest': False, # Disable data digests       
    }
    ctrl.connect(host, cfg)
    print(f"connected to {ctrl.name} subsys {ctrl.subsystem.name}")
except Exception as e:
    sys.exit(f'Failed to connect: {e}')

supported_log_pages = ctrl.supported_log_pages()
try:
    # Get the supported options for the Get Discovery Log Page command
    dlp_supp_opts = supported_log_pages[nvme.NVME_LOG_LID_DISCOVER] >> 16
except (TypeError, IndexError):
    dlp_supp_opts = 0

print(f"LID {nvme.NVME_LOG_LID_DISCOVER:02x}h (Discovery), supports: {disc_supp_str(dlp_supp_opts)}")
try:
    lsp = nvme.NVMF_LOG_DISC_LSP_PLEO if dlp_supp_opts & nvme.NVMF_LOG_DISC_LID_PLEOS else 0
    log_pages = ctrl.discover(lsp=lsp)
    print(pprint.pformat(log_pages))
except Exception as e:
    sys.exit(f'Failed to retrieve log pages: {e}')

try:
    ctrl.disconnect()
except Exception as e:
    sys.exit(f'Failed to disconnect: {e}')

ctrl = None
host = None
root = None

```

--------------------------------

### nvme_identify_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Retrieves a list of controllers, starting from a specified controller ID.

```APIDOC
## nvme_identify_ctrl_list

### Description
Retrieves a list of controllers. Up to 2047 controller identifiers are returned, containing a controller identifier greater than or equal to the controller identifier specified in **cntid**.

### Parameters
#### Path Parameters
- **fd** (int) - Required - File descriptor of nvme device
- **cntid** (__u16) - Required - Starting CNTLID to return in the list
- **cntlist** (struct nvme_ctrl_list *) - Required - User space destination address to transfer the data

### Return
The nvme command status if a response was received or -1 with errno set otherwise.
```

--------------------------------

### nvme_init_default_logging

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/log.md

Initializes the default logging system using a file descriptor, logging level, and options for including PID and timestamps. This serves as a fallback when a root object is not available.

```APIDOC
## nvme_init_default_logging(FILE *fp, int lvl, bool log_pid, bool log_tstamp)

### Description
Initializes default (fallback) logging using a file descriptor.

### Parameters
- **fp** (FILE *) - The file descriptor for logging messages.
- **lvl** (int) - The logging level to set.
- **log_pid** (bool) - Enable logging of the Process ID.
- **log_tstamp** (bool) - Enable logging of timestamps.

### Description
Sets the default logging settings for the library in case the root object is absent.
```

--------------------------------

### nvme_ns_mgmt_create

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Creates a non-attached namespace.

```APIDOC
## nvme_ns_mgmt_create

### Description
Create a non attached namespace

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.

### Parameters
- **fd** (int) - File descriptor of nvme device
- **ns** (struct nvme_id_ns *) - Namespace identification that defines ns creation parameters
- **nsid** (__u32 *) - On success, set to the namespace id that was created
- **timeout** (__u32) - Override the default timeout to this value in milliseconds; set to 0 to use the system default.
- **csi** (__u8) - Command Set Identifier
- **data** (struct nvme_ns_mgmt_host_sw_specified *) - Host Software Specified Fields that defines ns creation parameters

### Return
The nvme command status if a response was received (see `enum nvme_status_field`) or -1 with errno set otherwise.
```

--------------------------------

### nvme_virtual_mgmt_args

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Arguments for the NVMe Virtualization resource management command.

```APIDOC
## struct nvme_virtual_mgmt_args

### Description
Arguments for the NVMe Virtualization resource management command.

### Members
- **result** (*__u32* *) - Description: If successful, the CQE dword0
- **args_size** (*int*) - Description: Size of [struct nvme_virtual_mgmt_args](#c.nvme_virtual_mgmt_args)
- **fd** (*int*) - Description: File descriptor of nvme device
- **timeout** (*__u32*) - Description: Timeout in ms
- **act** (*enum nvme_virt_mgmt_act*) - Description: Virtual resource action, see [enum nvme_virt_mgmt_act](types.md#c.nvme_virt_mgmt_act)
- **rt** (*enum nvme_virt_mgmt_rt*) - Description: Resource type to modify, see [enum nvme_virt_mgmt_rt](types.md#c.nvme_virt_mgmt_rt)
- **cntlid** (*__u16*) - Description: Controller id for which resources are bing modified
- **nr** (*__u16*) - Description: Number of resources being allocated or assigned
```

--------------------------------

### NVMe LBA Status Completion Condition Enum

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Enumerates the possible completion conditions for Get LBA Status commands.

```c
enum nvme_lba_status_cmpc {
  NVME_LBA_STATUS_CMPC_NO_CMPC,
  NVME_LBA_STATUS_CMPC_INCOMPLETE,
  NVME_LBA_STATUS_CMPC_COMPLETE
};
```

--------------------------------

### NVMe Timestamp Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Defines the timestamp data structure used in Get Features, containing the timestamp value and attributes.

```c
struct nvme_timestamp {
  __u8 timestamp[6];
  __u8 attr;
  __u8 rsvd;
};
```

--------------------------------

### NVMe Get Discovery Arguments Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Defines the structure for arguments used with nvmf_get_discovery_wargs. This structure provides more options than nvmf_get_discovery_log.

```c
struct nvme_get_discovery_args {
  nvme_ctrl_t c;
  int args_size;
  int max_retries;
  __u32 *result;
  __u32 timeout;
  __u8 lsp;
};
```

--------------------------------

### nvme_mi_first_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Initiates the iteration process for NVMe-MI controllers associated with a given endpoint. It returns the first controller found.

```APIDOC
## nvme_mi_first_ctrl

### Description
Start controller iterator.

### Parameters
- **ep** (nvme_mi_ep_t) - MI endpoint object

### Return
First MI controller object under this root, or NULL if no controllers are present.

### See Also
- `nvme_mi_next_ctrl`
- `nvme_mi_for_each_ctrl`
```

--------------------------------

### Enable Both Address and Undefined Behavior Sanitizers

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Configure the build to enable both the address sanitizer and the undefined behavior sanitizer simultaneously.

```bash
meson setup .build -Db_sanitize=address,undefined
```

--------------------------------

### Disable Python Bindings Build

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Example of how to explicitly disable the build of Python bindings using the `python` build option.

```bash
meson setup .build -Dpython=disabled
```

--------------------------------

### nvme_dev_self_test

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Starts or aborts a device self-test operation, which diagnoses the controller's integrity and functionality, potentially including associated namespaces.

```APIDOC
## nvme_dev_self_test

### Description

Start or abort a self test. 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.

### Signature

```c
int nvme_dev_self_test(struct nvme_dev_self_test_args *args)
```

### Parameters

#### Arguments Structure

- **args** (`struct nvme_dev_self_test_args *`) - Argument structure for the device self-test.

### Return

The nvme command status if a response was received (see `enum nvme_status_field`) or -1 with errno set otherwise.
```

--------------------------------

### nvme_subsystem_get_application

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Returns the application string associated with a subsystem, or NULL if not set.

```APIDOC
## nvme_subsystem_get_application

### Description
Returns the application string associated with a subsystem, or NULL if not set.

### Parameters
- **s** (nvme_subsystem_t) - nvme_subsystem_t object

### Return
Managing application string or NULL if not set.
```

--------------------------------

### nvme_mi_admin_identify_active_ns_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs an Admin identify for an active namespace list. It retrieves information about active namespaces starting from a specified namespace ID.

```APIDOC
## nvme_mi_admin_identify_active_ns_list

### Description
Perform an Admin identify for an active namespace list. It retrieves information about active namespaces starting from a specified namespace ID.

### Method
int

### Parameters
#### Path Parameters
- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to process identify command
- **nsid** (__u32) - Required - Namespace ID to specify list start
- **list** (struct nvme_ns_list *) - Required - List data to populate

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### NVMe Firmware Download Arguments

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Arguments for the NVMe Firmware Download command. Used to transfer firmware data to the device.

```c
struct nvme_fw_download_args {
  __u32 *result;
  void *data;
  int args_size;
  int fd;
  __u32 timeout;
  __u32 offset;
  __u32 data_len;
};
```

--------------------------------

### nvme_mi_admin_identify_allocated_ns_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs an Admin identify for an allocated namespace list. It retrieves information about allocated namespaces starting from a specified namespace ID.

```APIDOC
## nvme_mi_admin_identify_allocated_ns_list

### Description
Perform an Admin identify for an allocated namespace list. It retrieves information about allocated namespaces starting from a specified namespace ID.

### Method
int

### Parameters
#### Path Parameters
- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to process identify command
- **nsid** (__u32) - Required - Namespace ID to specify list start
- **list** (struct nvme_ns_list *) - Required - List data to populate

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### nvme_init_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/util.md

Initializes an `nvme_ctrl_list` structure from an array of controller identifiers. This is a preparatory function for operations involving multiple NVMe controllers.

```APIDOC
## nvme_init_ctrl_list

### Description
Initialize an nvme_ctrl_list structure from an array.

### Parameters
- **cntlist** (struct nvme_ctrl_list *) - Required - The controller list structure to initialize
- **num_ctrls** (__u16) - Required - The number of controllers in the array, `ctrlist`.
- **ctrlist** (__u16 *) - Required - An array of controller identifiers in CPU native endian.

### Notes
This is intended to be used with any command that takes a controller list argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().
```

--------------------------------

### Compile libnvme

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Compiles the libnvme library after configuration using Meson. This command should be run from the project's root directory.

```bash
meson compile -C .build
```

--------------------------------

### nvme_mi_mi_read_mi_data_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs a Read MI Data Structure command to retrieve a list of attached controllers, starting from a specified controller ID.

```APIDOC
## nvme_mi_mi_read_mi_data_ctrl_list

### Description
Perform a Read MI Data Structure command, retrieving the list of attached controllers. Retrieves the list of attached controllers, with IDs greater than or equal to `start_ctrlid`.

### Parameters
- **ep** (nvme_mi_ep_t) - Description: endpoint for MI communication
- **start_ctrlid** (__u8) - Description: starting controller ID
- **list** (struct nvme_ctrl_list *) - Description: controller list to populate

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.

### See Also
- [`struct nvme_ctrl_list`](types.md#c.nvme_ctrl_list)
```

--------------------------------

### nvme_ns_mgmt

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Issues a Namespace management command.

```APIDOC
## nvme_ns_mgmt

### Description
Issue a Namespace management command

### Parameters
- **args** (struct nvme_ns_mgmt_args *) - `struct nvme_ns_mgmt_args` Argument structure

### Return
The nvme command status if a response was received (see `enum nvme_status_field`) or -1 with errno set otherwise.
```

--------------------------------

### nvme_lookup_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Lookup an nvme_ctrl_t object within a subsystem based on transport details. It can optionally start the search from a previous controller instance.

```APIDOC
## nvme_lookup_ctrl

### Description
Lookup a controller in a subsystem based on transport, transport address, host transport address, host interface, and transport service identifier. A new object is created if none is found. If a previous controller instance is specified, the lookup will start from that instance.

### Parameters
#### Path Parameters
- **s** (nvme_subsystem_t) - Required - The subsystem object to search within.
- **transport** (const char *) - Required - The transport name (e.g., 'tcp', 'rdma').
- **traddr** (const char *) - Required - The transport address.
- **host_traddr** (const char *) - Optional - The host transport address.
- **host_iface** (const char *) - Optional - The host interface name.
- **trsvcid** (const char *) - Optional - The transport service identifier.
- **p** (nvme_ctrl_t) - Optional - Previous controller instance to start lookup from.

### Return
Controller instance (nvme_ctrl_t) on success.
```

--------------------------------

### Run libnvme Unit Tests

Source: https://github.com/linux-nvme/libnvme/blob/master/README.md

Executes the unit tests for the libnvme library using Meson. Ensure the project is compiled before running tests.

```bash
meson test -C .build
```

--------------------------------

### NVMe LBA Range Descriptor Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Defines the structure for an LBA range descriptor, specifying the starting LBA and the number of logical blocks.

```c
struct nvme_lba_rd {
  __le64 rslba;
  __le32 rnlb;
  __u8 rsvd12[4];
};
```

--------------------------------

### nvme_mi_admin_identify_nsid_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs an Admin identify for a controller list with a specific namespace ID. It retrieves controller information starting from a given controller ID.

```APIDOC
## nvme_mi_admin_identify_nsid_ctrl_list

### Description
Perform an Admin identify for a controller list with a specific namespace ID. It retrieves controller information starting from a given controller ID.

### Method
int

### Parameters
#### Path Parameters
- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to process identify command
- **nsid** (__u32) - Required - Namespace identifier
- **cntid** (__u16) - Required - Controller ID to specify list start
- **list** (struct nvme_ctrl_list *) - Required - List data to populate

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### nvme_resv_acquire

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Sends an NVMe reservation acquire command. This command acquires, preempts, or aborts a reservation on a namespace. It takes a pointer to a `nvme_resv_acquire_args` structure.

```APIDOC
## nvme_resv_acquire

### Description
Sends an NVMe reservation acquire command. 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.

### Parameters
#### Path Parameters
- `args` (struct nvme_resv_acquire_args *) - Required - Argument structure for the NVMe reservation acquire operation.

### Return
The NVMe command status if a response was received, or -1 with errno set otherwise.
```

--------------------------------

### nvme_mi_first_endpoint

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Retrieves the first MI endpoint associated with a given MI root object, serving as the starting point for iterating through available endpoints.

```APIDOC
## nvme_mi_first_endpoint

### Description
Start endpoint iterator

### Parameters
* **m** (nvme_root_t) - `nvme_root_t` object

### Return
first MI endpoint object under this root, or NULL if no endpoints are present.

### See Also
* `nvme_mi_next_endpoint`
* `nvme_mi_for_each_endpoint`
```

--------------------------------

### nvme_fw_download_args

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Arguments for the NVMe Firmware Download command. This structure contains parameters for downloading firmware to an NVMe device, including the firmware data, length, and offset.

```APIDOC
## struct nvme_fw_download_args

### Description
Arguments for the NVMe Firmware Download command.

### Members
- **result** (*__u32 ") - The command completion result from CQE dword0
- **data** (*void ") - Userspace address of the firmware data
- **args_size** (*int*) - Size of [`struct nvme_fw_download_args`](#c.nvme_fw_download_args)
- **fd** (*int*) - File descriptor of nvme device
- **timeout** (*__u32*) - Timeout in ms
- **offset** (*__u32*) - Offset in the firmware data
- **data_len** (*__u32*) - Length of data in this command in bytes
```

--------------------------------

### nvme_mi_admin_get_log_telemetry_host

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Gets the Telemetry Host-Initiated log page. It retrieves telemetry data at a specified offset from the NVMe controller, storing it in the provided user buffer.

```APIDOC
## nvme_mi_admin_get_log_telemetry_host

### Description
Get Telemetry Host-Initiated log page.

Retrieves the Telemetry Host-Initiated log page at the requested offset using the previously existing capture.

### Parameters

- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to query
- **offset** (__u64) - Required - Offset into the telemetry data
- **len** (__u32) - Required - Length of provided user buffer to hold the log data in bytes
- **log** (void *) - Required - User address for log page data

### Return

The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### Create NVMe MI Root Handle

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Creates the top-level MI (root) handle for managing NVMe-MI objects. Requires a file descriptor for logging and a log level.

```c
nvme_root_t nvme_mi_create_root(FILE *fp, int log_level);
```

--------------------------------

### nvme_for_each_subsystem

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Traverse the list of NVMe subsystems associated with the given NVMe host.

```APIDOC
## nvme_for_each_subsystem

### Description
Traverse the list of NVMe subsystems associated with the given NVMe host.

### Parameters
#### Path Parameters
- **h** (nvme_host_t) - Required - The NVMe host object.
- **s** (nvme_subsystem_t) - Required - Variable to hold the current subsystem object during iteration.
```

--------------------------------

### Get Next NVMe MI Endpoint

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Continues an iterator to retrieve the next MI endpoint object in sequence. Returns NULL if no further endpoints are present.

```c
nvme_mi_ep_t nvme_mi_next_endpoint(nvme_root_t m, nvme_mi_ep_t e);
```

--------------------------------

### nvme_get_directive_receive_length

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/util.md

Gets the expected payload length for a directive receive operation. This function requires specifying the directive type and operation to determine the correct length.

```APIDOC
## int nvme_get_directive_receive_length(enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len)

### Description
Get directive receive length.

### Parameters
- **dtype** (enum nvme_directive_dtype) - Directive type, see enum nvme_directive_dtype
- **doper** (enum nvme_directive_receive_doper) - Directive receive operation, see enum nvme_directive_receive_doper
- **len** (__u32 *) - 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 `dtype` or `doper`.
```

--------------------------------

### nvmf_hostnqn_from_file

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Reads the NVMe host NQN from the default configuration file location.

```APIDOC
## nvmf_hostnqn_from_file

### Description
Reads the host NVM qualified name from the config default location. Retrieves the qualified name from the config file located in $SYSCONFIDR/nvme. $SYSCONFDIR is usually /etc.

### Method
char *

### Return
The host NQN, or NULL if unsuccessful. If found, the caller is responsible to free the string.
```

--------------------------------

### nvme_create_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/tree.md

Allocate an unconnected NVMe controller instance. This is a preparatory step before adding a controller using nvme_add_ctrl().

```APIDOC
## nvme_create_ctrl

### Description
Allocate an unconnected NVMe controller to be used for nvme_add_ctrl().

### Parameters
#### Path Parameters
- **r** (nvme_root_t) - Required - NVMe root element.
- **subsysnqn** (const char *) - Required - Subsystem NQN.
- **transport** (const char *) - Required - Transport type.
- **traddr** (const char *) - Required - Transport address.
- **host_traddr** (const char *) - Required - Host transport address.
- **host_iface** (const char *) - Required - Host interface name.
- **trsvcid** (const char *) - Required - Transport service ID.

### Return
Controller instance (nvme_ctrl_t).
```

--------------------------------

### nvme_mi_admin_identify_secondary_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs an Admin identify for a secondary controller list. It retrieves information about secondary controllers associated with the primary controller, starting from a given controller ID.

```APIDOC
## nvme_mi_admin_identify_secondary_ctrl_list

### Description
Perform an Admin identify for a secondary controller list. It retrieves information about secondary controllers associated with the primary controller, starting from a given controller ID.

### Method
int

### Parameters
#### Path Parameters
- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to process identify command
- **cntid** (__u16) - Required - Controller ID to specify list start
- **list** (struct nvme_secondary_ctrl_list *) - Required - List data to populate

### Return
0 on success, non-zero on failure
```

--------------------------------

### nvme_mi_next_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Continues the iteration through NVMe-MI controllers. Given the current controller, it returns the next one in the sequence for the specified endpoint.

```APIDOC
## nvme_mi_next_ctrl

### Description
Continue ctrl iterator.

### Parameters
- **ep** (nvme_mi_ep_t) - MI endpoint object
- **c** (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.

### See Also
- `nvme_mi_first_ctrl`
- `nvme_mi_for_each_ctrl`
```

--------------------------------

### nvme_mi_admin_get_log_changed_alloc_ns_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Retrieves the Changed Allocated Namespace List Log for a given NVMe controller. This function is used to get a list of namespaces that have changed their allocation status.

```APIDOC
## nvme_mi_admin_get_log_changed_alloc_ns_list

### Description
Retrieve Changed Allocated Namespace List Log

### Parameters
- **ctrl** (nvme_mi_ctrl_t) - Controller to query
- **rae** (bool) - Retain asynchronous events
- **len** (__u32) - The allocated length of the log page
- **log** (struct nvme_ns_list *) - User address to store the log page

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### nvme_mi_admin_get_log_error

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Retrieves the NVMe error log page. This function is used to get detailed error information for commands that completed with an error or general error conditions.

```APIDOC
## nvme_mi_admin_get_log_error

### Description
Retrieve nvme error log. 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.

### Parameters
- **ctrl** (nvme_mi_ctrl_t) - Required - Controller to query
- **nr_entries** (unsigned int) - Required - Number of error log entries allocated
- **rae** (bool) - Required - Retain asynchronous events
- **err_log** (struct nvme_error_log_page *) - Required - Array of error logs of size ‘entries’

### Return
The nvme command status if a response was received (see enum nvme_status_field) or -1 with errno set otherwise.
```

--------------------------------

### nvme_compare

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Submits an NVMe user compare command. It takes a pointer to a `nvme_io_args` structure containing the necessary arguments for the compare operation.

```APIDOC
## nvme_compare

### Description
Submits an NVMe user compare command.

### Parameters
#### Path Parameters
- `args` (struct nvme_io_args *) - Required - Argument structure for the NVMe IO operation.

### Return
The NVMe command status if a response was received, or -1 with errno set otherwise.
```

--------------------------------

### Get NVMe Discovery Log Page

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Retrieves the discovery log page for an NVMe controller. The caller is responsible for freeing the returned log page memory.

```c
int nvmf_get_discovery_log(nvme_ctrl_t c, struct nvmf_discovery_log **logp, int max_retries)
```

--------------------------------

### NVMe Streams Directive Status Data Structure

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/types.md

Get status data structure for NVMe Streams Directive, containing the open stream count and stream identifiers.

```default
struct nvme_streams_directive_status {
  __le16 osc;
  __le16 sid[];
};

```

--------------------------------

### nvme_open

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/linux.md

Opens an NVMe controller or namespace device by its name.

```APIDOC
## nvme_open

### Description
Open an nvme controller or namespace device

### Parameters
- **name** (const char *) - 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.
```

--------------------------------

### nvme_mi_mi_config_get_mctp_mtu

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Retrieves the MCTP Maximum Transmission Unit (MTU) size for a specified port. This function performs a MI Configuration Get to query the current MTU configuration.

```APIDOC
## nvme_mi_mi_config_get_mctp_mtu

### Description
Gets the MCTP MTU configuration for a given port. 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.

### Parameters
- **ep** (nvme_mi_ep_t) - Required - Endpoint for MI communication.
- **port** (__u8) - Required - Port ID to query.
- **mtu** (__u16 *) - Required - Output value for current MCTP MTU configuration.

### Return
The nvme command status if a response was received or -1 with errno set otherwise.
```

--------------------------------

### Connect NVMe Controller

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Issues a 'connect' command to an NVMe-oF controller. The controller must be initialized and not connected to the topology.

```c
int nvmf_connect_ctrl(nvme_ctrl_t c)
```

--------------------------------

### nvme_get_lba_status_args

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/api-types.md

Arguments for the NVMe Get LBA Status command. This structure is used to specify parameters for retrieving the status of Logical Block Addresses (LBAs) on an NVMe device.

```APIDOC
## nvme_get_lba_status_args

### Description
Arguments for the NVMe Get LBA Status command.

### Members
- **slba** (*__u64*) - Starting logical block address to check statuses
- **result** (*__u32 ") - The command completion result from CQE dword0
- **lbas** (*struct nvme_lba_status ") - Data payload to return status descriptors
- **args_size** (*int*) - Size of [`struct nvme_get_lba_status_args`](#c.nvme_get_lba_status_args)
- **fd** (*int*) - File descriptor of nvme device
- **timeout** (*__u32*) - Timeout in ms
- **nsid** (*__u32*) - Namespace ID to retrieve LBA status
- **mndw** (*__u32*) - Maximum number of dwords to return
- **atype** (*enum nvme_lba_status_atype*) - Action type mechanism to determine LBA status descriptors to return, see [`enum nvme_lba_status_atype`](types.md#c.nvme_lba_status_atype)
- **rl** (*__u16*) - Range length from slba to perform the action
```

--------------------------------

### nvme_mi_admin_identify_ctrl_list

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/mi.md

Performs an Admin Identify command for a controller list, populating the provided controller list structure. The list starts with IDs greater than or equal to the specified controller ID.

```APIDOC
## nvme_mi_admin_identify_ctrl_list

### Description
Perform an Admin identify for a controller list.

### Parameters
- **ctrl** (nvme_mi_ctrl_t) - The controller to process the identify command.
- **cntid** (__u16) - Controller ID to specify list start.
- **list** (struct nvme_ctrl_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 `NVME_IDENTIFY_DATA_SIZE`, so **id** will be fully populated on success.

See: [`struct nvme_ctrl_list`](types.md#c.nvme_ctrl_list)

### Return
The nvme command status if a response was received (see [`enum nvme_status_field`](types.md#c.nvme_status_field)) or -1 with errno set otherwise.
```

--------------------------------

### nvme_copy

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Executes an NVMe copy command. It takes a pointer to a `nvme_copy_args` structure containing the necessary arguments for the copy operation.

```APIDOC
## nvme_copy

### Description
Executes an NVMe copy command.

### Parameters
#### Path Parameters
- `args` (struct nvme_copy_args *) - Required - Argument structure for the NVMe copy operation.

### Return
The NVMe command status if a response was received, or -1 with errno set otherwise.
```

--------------------------------

### nvme_get_log_ana_groups

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/ioctl.md

Retrieves only the Asymmetric Namespace Access (ANA) groups log page from an NVMe device. This function is used to get ANA group information without namespace IDs.

```APIDOC
## nvme_get_log_ana_groups

### Description
Retrieve Asymmetric Namespace Access groups only log page.

See [`struct nvme_ana_log`](types.md#c.nvme_ana_log) for the definition of the returned structure.

### Parameters
- **fd** (int) - File descriptor of nvme device
- **rae** (bool) - Retain asynchronous events
- **len** (__u32) - The allocated length of the log page
- **log** (struct nvme_ana_log *) - User address to store the ana group log

### Return
The nvme command status if a response was received (see
[`enum nvme_status_field`](types.md#c.nvme_status_field)) or -1 with errno set otherwise.
```

--------------------------------

### nvmf_add_ctrl

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Connects a controller to a host and updates the topology. This function issues a 'connect' command and inserts the controller into the topology.

```APIDOC
## nvmf_add_ctrl

### Description
Connects a controller to a host and updates the topology. Issues a ‘connect’ command to the NVMe-oF controller and inserts the controller into the topology using the host as parent. The controller must be initialized and not connected to the topology.

### Method
int

### Parameters
#### Input Parameters
- **h** (nvme_host_t) - The host to which the controller should be attached.
- **c** (nvme_ctrl_t) - The controller to be connected.
- **cfg** (const struct nvme_fabrics_config *) - Default configuration for the controller.

### Return
0 on success; on failure errno is set and -1 is returned.
```

--------------------------------

### Add and Connect NVMe Controller

Source: https://github.com/linux-nvme/libnvme/blob/master/doc/rst/fabrics.md

Connects an NVMe controller to a host and updates the topology. The controller must be initialized and not already connected.

```c
int nvmf_add_ctrl(nvme_host_t h, nvme_ctrl_t c, const struct nvme_fabrics_config *cfg)
```