NVMe: libblockdev Reference Manual for libblockdev 3.3.1.

## NVMe NVMe — plugin for NVMe device reporting and management |

## Functions

void | bd_nvme_close ()
gboolean | bd_nvme_init ()
GQuark | bd_nvme_error_quark ()
gboolean | bd_nvme_is_tech_avail ()
BDNVMEControllerInfo * | bd_nvme_get_controller_info ()
void | bd_nvme_controller_info_free ()
BDNVMEControllerInfo * | bd_nvme_controller_info_copy ()
void | bd_nvme_lba_format_free ()
BDNVMELBAFormat * | bd_nvme_lba_format_copy ()
BDNVMENamespaceInfo * | bd_nvme_get_namespace_info ()
void | bd_nvme_namespace_info_free ()
BDNVMENamespaceInfo * | bd_nvme_namespace_info_copy ()
BDNVMESmartLog * | bd_nvme_get_smart_log ()
void | bd_nvme_smart_log_free ()
BDNVMESmartLog * | bd_nvme_smart_log_copy ()
BDNVMEErrorLogEntry ** | bd_nvme_get_error_log_entries ()
void | bd_nvme_error_log_entry_free ()
BDNVMEErrorLogEntry * | bd_nvme_error_log_entry_copy ()
BDNVMESelfTestLog * | bd_nvme_get_self_test_log ()
void | bd_nvme_self_test_log_free ()
BDNVMESelfTestLog * | bd_nvme_self_test_log_copy ()
void | bd_nvme_self_test_log_entry_free ()
BDNVMESelfTestLogEntry * | bd_nvme_self_test_log_entry_copy ()
const gchar * | bd_nvme_self_test_result_to_string ()
gboolean | bd_nvme_device_self_test ()
gboolean | bd_nvme_format ()
BDNVMESanitizeLog * | bd_nvme_get_sanitize_log ()
void | bd_nvme_sanitize_log_free ()
BDNVMESanitizeLog * | bd_nvme_sanitize_log_copy ()
gboolean | bd_nvme_sanitize ()
gchar * | bd_nvme_get_host_nqn ()
gchar * | bd_nvme_get_host_id ()
gchar * | bd_nvme_generate_host_nqn ()
gboolean | bd_nvme_set_host_nqn ()
gboolean | bd_nvme_set_host_id ()
gboolean | bd_nvme_connect ()
gboolean | bd_nvme_disconnect ()
gboolean | bd_nvme_disconnect_by_path ()
gchar ** | bd_nvme_find_ctrls_for_ns ()

## Types and Values

#define | BD_NVME_ERROR
enum | BDNVMEError
enum | BDNVMETech
enum | BDNVMETechMode
enum | BDNVMEControllerFeature
enum | BDNVMEControllerType
| BDNVMEControllerInfo
enum | BDNVMELBAFormatRelativePerformance
| BDNVMELBAFormat
enum | BDNVMENamespaceFeature
| BDNVMENamespaceInfo
enum | BDNVMESmartCriticalWarning
| BDNVMESmartLog
enum | BDNVMETransportType
| BDNVMEErrorLogEntry
| BDNVMESelfTestLog
| BDNVMESelfTestLogEntry
enum | BDNVMESelfTestAction
enum | BDNVMESelfTestResult
enum | BDNVMEFormatSecureErase
enum | BDNVMESanitizeStatus
| BDNVMESanitizeLog
enum | BDNVMESanitizeAction

## Includes

    #include <nvme.h>

## Description

A plugin for NVMe device reporting and management, based around libnvme.

## Functions

### bd_nvme_close ()

    void
    bd_nvme_close (void);

Cleans up after the plugin. **This function is called automatically by the library's functions that unload it.**

### bd_nvme_init ()

    gboolean
    bd_nvme_init (void);

Initializes the plugin. **This function is called automatically by the library's initialization functions.**

### bd_nvme_error_quark ()

    GQuark
    bd_nvme_error_quark (void);

[skip]

### bd_nvme_is_tech_avail ()

    gboolean
    bd_nvme_is_tech_avail (BDNVMETech tech,
                           guint64 mode,
                           GError **error);

#### Parameters

tech | the queried tech |
mode | a bit mask of queried modes of operation (BDNVMETechMode) for `tech` |
error | place to store error (details about why the `tech` -`mode` combination is not available). | [out][nullable]

#### Returns

whether the `tech` -`mode` combination is available -- supported by the plugin implementation and having all the runtime dependencies available

### bd_nvme_get_controller_info ()

    BDNVMEControllerInfo *
    bd_nvme_get_controller_info (const gchar *device,
                                 GError **error);

Retrieves information about the NVMe controller (the Identify Controller command) as specified by the `device` block device path.

#### Parameters

device | a NVMe controller device (e.g. `/dev/nvme0`) |
error | place to store error (if any). | [out][nullable]

#### Returns

information about given controller or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full]

### bd_nvme_controller_info_free ()

    void
    bd_nvme_controller_info_free (BDNVMEControllerInfo *info);

Frees `info` .

[skip]

#### Parameters

info | `BDNVMEControllerInfo` to free. | [nullable]

### bd_nvme_controller_info_copy ()

    BDNVMEControllerInfo *
    bd_nvme_controller_info_copy (BDNVMEControllerInfo *info);

Creates a new copy of `info` .

[skip]

#### Parameters

info | `BDNVMEControllerInfo` to copy. | [nullable]

### bd_nvme_lba_format_free ()

    void
    bd_nvme_lba_format_free (BDNVMELBAFormat *fmt);

Frees `fmt` .

[skip]

#### Parameters

fmt | `BDNVMELBAFormat` to free. | [nullable]

### bd_nvme_lba_format_copy ()

    BDNVMELBAFormat *
    bd_nvme_lba_format_copy (BDNVMELBAFormat *fmt);

Creates a new copy of `fmt` .

[skip]

#### Parameters

fmt | `BDNVMELBAFormat` to copy. | [nullable]

### bd_nvme_get_namespace_info ()

    BDNVMENamespaceInfo *
    bd_nvme_get_namespace_info (const gchar *device,
                                GError **error);

Retrieves information about the NVMe namespace (the Identify Namespace command) as specified by the `device` block device path.

#### Parameters

device | a NVMe namespace device (e.g. `/dev/nvme0n1`) |
error | place to store error (if any). | [out][nullable]

#### Returns

information about given namespace or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full]

### bd_nvme_namespace_info_free ()

    void
    bd_nvme_namespace_info_free (BDNVMENamespaceInfo *info);

Frees `info` .

[skip]

#### Parameters

info | `BDNVMENamespaceInfo` to free. | [nullable]

### bd_nvme_namespace_info_copy ()

    BDNVMENamespaceInfo *
    bd_nvme_namespace_info_copy (BDNVMENamespaceInfo *info);

Creates a new copy of `info` .

[skip]

#### Parameters

info | `BDNVMENamespaceInfo` to copy. | [nullable]

### bd_nvme_get_smart_log ()

    BDNVMESmartLog *
    bd_nvme_get_smart_log (const gchar *device,
                           GError **error);

Retrieves drive SMART and general health information (Log Identifier `02h`). The information provided is over the life of the controller and is retained across power cycles.

#### Parameters

device | a NVMe controller device (e.g. `/dev/nvme0`) |
error | place to store error (if any). | [out][nullable]

#### Returns

health log data or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full]

### bd_nvme_smart_log_free ()

    void
    bd_nvme_smart_log_free (BDNVMESmartLog *log);

Frees `log` .

[skip]

#### Parameters

log | `BDNVMESmartLog` to free. | [nullable]

### bd_nvme_smart_log_copy ()

    BDNVMESmartLog *
    bd_nvme_smart_log_copy (BDNVMESmartLog *log);

Creates a new copy of `log` .

[skip]

#### Parameters

log | `BDNVMESmartLog` to copy. | [nullable]

### bd_nvme_get_error_log_entries ()

    BDNVMEErrorLogEntry **
    bd_nvme_get_error_log_entries (const gchar *device,
                                   GError **error);

Retrieves Error Information Log (Log Identifier `01h`) entries, used to describe extended error information for a command that completed with error or to report an error that is not specific to a particular command. This log is global to the controller. The ordering of the entries is based on the time when the error occurred, with the most recent error being returned as the first log entry. As the number of entries is typically limited by the drive implementation, only most recent entries are provided.

#### Parameters

device | a NVMe controller device (e.g. `/dev/nvme0`) |
error | place to store error (if any). | [out][nullable]

#### Returns

null-terminated list of error entries or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full][array zero-terminated=1]

### bd_nvme_error_log_entry_free ()

    void
    bd_nvme_error_log_entry_free (BDNVMEErrorLogEntry *entry);

Frees `entry` .

[skip]

#### Parameters

entry | `BDNVMEErrorLogEntry` to free. | [nullable]

### bd_nvme_error_log_entry_copy ()

    BDNVMEErrorLogEntry *
    bd_nvme_error_log_entry_copy (BDNVMEErrorLogEntry *entry);

Creates a new copy of `entry` .

[skip]

#### Parameters

entry | `BDNVMEErrorLogEntry` to copy. | [nullable]

### bd_nvme_get_self_test_log ()

    BDNVMESelfTestLog *
    bd_nvme_get_self_test_log (const gchar *device,
                               GError **error);

Retrieves drive self-test log (Log Identifier `06h`). Provides the status of a self-test operation in progress and the percentage complete of that operation, along with the results of the last 20 device self-test operations.

#### Parameters

device | a NVMe controller device (e.g. `/dev/nvme0`) |
error | place to store error (if any). | [out][nullable]

#### Returns

self-test log data or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full]

### bd_nvme_self_test_log_free ()

    void
    bd_nvme_self_test_log_free (BDNVMESelfTestLog *log);

Frees `log` .

[skip]

#### Parameters

log | `BDNVMESelfTestLog` to free. | [nullable]

### bd_nvme_self_test_log_copy ()

    BDNVMESelfTestLog *
    bd_nvme_self_test_log_copy (BDNVMESelfTestLog *log);

Creates a new copy of `log` .

[skip]

#### Parameters

log | `BDNVMESelfTestLog` to copy. | [nullable]

### bd_nvme_self_test_log_entry_free ()

    void
    bd_nvme_self_test_log_entry_free (BDNVMESelfTestLogEntry *entry);

Frees `entry` .

[skip]

#### Parameters

entry | `BDNVMESelfTestLogEntry` to free. | [nullable]

### bd_nvme_self_test_log_entry_copy ()

    BDNVMESelfTestLogEntry *
    bd_nvme_self_test_log_entry_copy (BDNVMESelfTestLogEntry *entry);

Creates a new copy of `entry` .

[skip]

#### Parameters

entry | `BDNVMESelfTestLogEntry` to copy. | [nullable]

### bd_nvme_self_test_result_to_string ()

    const gchar *
    bd_nvme_self_test_result_to_string (BDNVMESelfTestResult result,
                                        GError **error);

#### Parameters

result | A `BDNVMESelfTestResult`. |
error | place to store error (if any). | [out][optional]

#### Returns

A string representation of `result` for use as an identifier string or `NULL` when the code is unknown.

[transfer none]

### bd_nvme_device_self_test ()

    gboolean
    bd_nvme_device_self_test (const gchar *device,
                              BDNVMESelfTestAction action,
                              GError **error);

Initiates or aborts the Device Self-test operation on the controller or a namespace, distinguished by the `device` path specified. In case a controller device is specified then the self-test operation would include all active namespaces.

To abort a running operation, pass BD_NVME_SELF_TEST_ACTION_ABORT as `action` . To retrieve progress of a current running operation, check the self-test log using `bd_nvme_get_self_test_log()`.

#### Parameters

device | a NVMe controller or namespace device (e.g. `/dev/nvme0`) |
action | self-test action to take. |
error | place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the device self-test command was issued successfully, `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_MANAGE`

### bd_nvme_format ()

    gboolean
    bd_nvme_format (const gchar *device,
                    guint16 lba_data_size,
                    guint16 metadata_size,
                    BDNVMEFormatSecureErase secure_erase,
                    GError **error);

Performs low level format of the NVM media, destroying all data and metadata for either a specific namespace or all attached namespaces to the controller. Use this command to change LBA sector size. Optional secure erase method can be specified as well.

Supported LBA data sizes for a given namespace can be listed using the `bd_nvme_get_namespace_info()` call. In case of a special value `0` the current LBA format for a given namespace will be retained. When called on a controller device the first namespace is used as a reference.

Note that the NVMe controller may define a Format NVM attribute indicating that the format operation would apply to all namespaces and a format (excluding secure erase) of any namespace results in a format of all namespaces in the NVM subsystem. In such case and when `device` is a namespace block device the BD_NVME_ERROR_WOULD_FORMAT_ALL_NS error is returned to prevent further damage. This is then supposed to be handled by the caller and `bd_nvme_format()` is supposed to be called on a controller device instead.

This call blocks until the format operation has finished. To retrieve progress of a current running operation, check the namespace info using `bd_nvme_get_namespace_info()`.

#### Parameters

device | NVMe namespace or controller device to format (e.g. `/dev/nvme0n1`) |
lba_data_size | desired LBA data size (i.e. a sector size) in bytes or `0` to keep current. See BDNVMELBAFormat and `bd_nvme_get_namespace_info()`. |
metadata_size | desired metadata size in bytes or `0` for default. See BDNVMELBAFormat and `bd_nvme_get_namespace_info()`. |
secure_erase | optional secure erase action to take. |
error | place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the format command finished successfully, `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_MANAGE`

### bd_nvme_get_sanitize_log ()

    BDNVMESanitizeLog *
    bd_nvme_get_sanitize_log (const gchar *device,
                              GError **error);

Retrieves the drive sanitize status log (Log Identifier `81h`) that includes information about the most recent sanitize operation and the sanitize operation time estimates.

As advised in the NVMe specification whitepaper the host should limit polling to retrieve progress of a running sanitize operations (e.g. to at most once every several minutes) to avoid interfering with the progress of the sanitize operation itself.

#### Parameters

device | a NVMe controller device (e.g. `/dev/nvme0`) |
error | place to store error (if any). | [out][nullable]

#### Returns

sanitize log data or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_INFO`.

[transfer full]

### bd_nvme_sanitize_log_free ()

    void
    bd_nvme_sanitize_log_free (BDNVMESanitizeLog *log);

Frees `log` .

[skip]

#### Parameters

log | `BDNVMESanitizeLog` to free. | [nullable]

### bd_nvme_sanitize_log_copy ()

    BDNVMESanitizeLog *
    bd_nvme_sanitize_log_copy (BDNVMESanitizeLog *log);

Creates a new copy of `log` .

[skip]

#### Parameters

log | `BDNVMESanitizeLog` to copy. | [nullable]

### bd_nvme_sanitize ()

    gboolean
    bd_nvme_sanitize (const gchar *device,
                      BDNVMESanitizeAction action,
                      gboolean no_dealloc,
                      gint overwrite_pass_count,
                      guint32 overwrite_pattern,
                      gboolean overwrite_invert_pattern,
                      GError **error);

Starts a sanitize operation or recovers from a previously failed sanitize operation. By definition, 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 scope of a sanitize operation is all locations in the NVM subsystem that are able to contain user data, including caches, Persistent Memory Regions, and unallocated or deallocated areas of the media.

Once started, a sanitize operation is not able to be aborted and continues after a Controller Level Reset including across power cycles. Once the sanitize operation has run the media affected may not be immediately ready for use unless additional media modification mechanism is run. This is often vendor specific and also depends on the sanitize method (`action` ) used. Callers to this sanitize operation should set `no_dealloc` to `TRUE` for the added convenience.

The controller also ignores Critical Warning(s) in the SMART / Health Information log page (e.g., read only mode) and attempts to complete the sanitize operation requested.

This call returns immediately and the actual sanitize operation is performed in the background. Use `bd_nvme_get_sanitize_log()` to retrieve status and progress of a running sanitize operation. In case a sanitize operation fails the controller may restrict its operation until a subsequent sanitize operation is started (i.e. retried) or an BD_NVME_SANITIZE_ACTION_EXIT_FAILURE action is used to acknowledge the failure explicitly.

The `overwrite_pass_count` , `overwrite_pattern` and `overwrite_invert_pattern` arguments are only valid when `action` is BD_NVME_SANITIZE_ACTION_OVERWRITE.

The sanitize operation is set to run under the Allow Unrestricted Sanitize Exit mode.

#### Parameters

device | NVMe namespace or controller device to format (e.g. `/dev/nvme0n1`) |
action | the sanitize action to perform. |
no_dealloc | instruct the controller to not deallocate the affected media area. |
overwrite_pass_count | number of overwrite passes [1-15] or 0 for the default (16 passes). |
overwrite_pattern | a 32-bit pattern used for the Overwrite sanitize operation. |
overwrite_invert_pattern | invert the overwrite pattern between passes. |
error | place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the format command finished successfully, `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_NVME`-`BD_NVME_TECH_MODE_MANAGE`

### bd_nvme_get_host_nqn ()

    gchar *
    bd_nvme_get_host_nqn (GError **error);

Reads the Host NQN (NVM Qualified Name) value from the global `/etc/nvme/hostnqn` file. An empty string is an indication that no Host NQN has been set.

#### Parameters

error | Place to store error (if any). | [out][nullable]

#### Returns

the Host NQN string or an empty string if none set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`.

[transfer full]

### bd_nvme_get_host_id ()

    gchar *
    bd_nvme_get_host_id (GError **error);

Reads the Host ID value from the global `/etc/nvme/hostid` file. An empty string is an indication that no Host ID has been set.

#### Parameters

error | Place to store error (if any). | [out][nullable]

#### Returns

the Host ID string or an empty string if none set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`.

[transfer full]

### bd_nvme_generate_host_nqn ()

    gchar *
    bd_nvme_generate_host_nqn (GError **error);

Compute new Host NQN (NVM Qualified Name) value for the current system. This takes in account various system identifiers (DMI, device tree) with the goal of a stable unique identifier whenever feasible.

#### Parameters

error | Place to store error (if any). | [out][nullable]

#### Returns

the Host NQN string or `NULL` with `error` set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`.

[transfer full]

### bd_nvme_set_host_nqn ()

    gboolean
    bd_nvme_set_host_nqn (const gchar *host_nqn,
                          GError **error);

Writes the Host NQN (NVM Qualified Name) value to the system `/etc/nvme/hostnqn` file. No validation of the string is performed.

#### Parameters

host_nqn | The Host NVM Qualified Name. |
error | Place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the value was set successfully or `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`

### bd_nvme_set_host_id ()

    gboolean
    bd_nvme_set_host_id (const gchar *host_id,
                         GError **error);

Writes the Host ID value to the system `/etc/nvme/hostid` file. No validation of the string is performed.

#### Parameters

host_id | The Host ID. |
error | Place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the value was set successfully or `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`

### bd_nvme_connect ()

    gboolean
    bd_nvme_connect (const gchar *subsysnqn,
                     const gchar *transport,
                     const gchar *transport_addr,
                     const gchar *transport_svcid,
                     const gchar *host_traddr,
                     const gchar *host_iface,
                     const gchar *host_nqn,
                     const gchar *host_id,
                     const BDExtraArg **extra,
                     GError **error);

Creates a transport connection to a remote system (specified by `transport_addr` and `transport_svcid` ) and creates a NVMe over Fabrics controller for the NVMe subsystem specified by the `subsysnqn` option.

Valid values for `transport` include:

- `"rdma"`: An rdma network (RoCE, iWARP, Infiniband, basic rdma, etc.)

- `"fc"`: A Fibre Channel network.

- `"tcp"`: A TCP/IP network.

- `"loop"`: A NVMe over Fabrics target on the local host.

In addition to the primary options it's possible to supply `extra` arguments:

- `"config"`: Use the specified JSON configuration file instead of the default file (see below) or specify `"none"` to avoid reading any configuration file.

- `"dhchap_key"`: NVMe In-band authentication secret in ASCII format as described in the NVMe 2.0 specification. When not specified, the secret is by default read from `/etc/nvme/hostkey`. In case that file does not exist no in-band authentication is attempted.

- `"dhchap_ctrl_key"`: NVMe In-band authentication controller secret for bi-directional authentication. When not specified, no bi-directional authentication is attempted.

- `"nr_io_queues"`: The number of I/O queues.

- `"nr_write_queues"`: Number of additional queues that will be used for write I/O.

- `"nr_poll_queues"`: Number of additional queues that will be used for polling latency sensitive I/O.

- `"queue_size"`: Number of elements in the I/O queues.

- `"keep_alive_tmo"`: The keep alive timeout (in seconds).

- `"reconnect_delay"`: The delay (in seconds) before reconnect is attempted after a connect loss.

- `"ctrl_loss_tmo"`: The controller loss timeout period (in seconds). A special value of `-1` will cause reconnecting forever.

- `"fast_io_fail_tmo"`: Fast I/O Fail timeout (in seconds).

- `"tos"`: Type of service.

- `"duplicate_connect"`: Allow duplicated connections between same transport host and subsystem port. Boolean value.

- `"disable_sqflow"`: Disables SQ flow control to omit head doorbell update for submission queues when sending nvme completions. Boolean value.

- `"hdr_digest"`: Generates/verifies header digest (TCP). Boolean value.

- `"data_digest"`: Generates/verifies data digest (TCP). Boolean value.

- `"tls"`: Enable TLS encryption (TCP). Boolean value.

- `"hostsymname"`: TP8010: NVMe host symbolic name.

- `"keyring"`: Keyring to store and lookup keys. String value.

- `"tls_key"`: TLS PSK for the connection. String value.

Boolean values can be expressed by "0"/"1", "on"/"off" or "True"/"False" case-insensitive strings. Failed numerical or boolean string conversions will result in the option being ignored.

By default additional options are read from the default configuration file `/etc/nvme/config.json`. This follows the default behaviour of `nvme-cli`. Use the `extra` `"config"` argument to either specify a different config file or disable use of it. The JSON configuration file format is documented in https://raw.githubusercontent.com/linux-nvme/libnvme/master/doc/config-schema.json. As a rule `extra` key names are kept consistent with the JSON config file schema. Any `extra` option generally overrides particular option specified in a configuration file.

#### Parameters

subsysnqn | The name for the NVMe subsystem to connect to. |
transport | The network fabric used for a NVMe-over-Fabrics network. |
transport_addr | The network address of the Controller. For transports using IP addressing (e.g. `rdma`) this should be an IP-based address. | [nullable]
transport_svcid | The transport service id. For transports using IP addressing (e.g. `rdma`) this field is the port number. By default, the IP port number for the `RDMA` transport is `4420`. | [nullable]
host_traddr | The network address used on the host to connect to the Controller. For TCP, this sets the source address on the socket. | [nullable]
host_iface | The network interface used on the host to connect to the Controller (e.g. IP `eth1`, `enp2s0`). This forces the connection to be made on a specific interface instead of letting the system decide. | [nullable]
host_nqn | Overrides the default Host NQN that identifies the NVMe Host. If this option is `NULL`, the default is read from `/etc/nvme/hostnqn` first. If that does not exist, the autogenerated NQN value from the NVMe Host kernel module is used next. The Host NQN uniquely identifies the NVMe Host. | [nullable]
host_id | User-defined host UUID or `NULL` to use default (as defined in `/etc/nvme/hostid`). | [nullable]
extra | Additional arguments. | [nullable][array zero-terminated=1]
error | Place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the subsystem was connected successfully, `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`

### bd_nvme_disconnect ()

    gboolean
    bd_nvme_disconnect (const gchar *subsysnqn,
                        GError **error);

Disconnects and removes one or more existing NVMe over Fabrics controllers. This may disconnect multiple controllers with matching `subsysnqn` and `TRUE` is only returned when all controllers were disconnected successfully.

#### Parameters

subsysnqn | The name of the NVMe subsystem to disconnect. |
error | Place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if all matching controllers were disconnected successfully, `FALSE` with `error` set in case of a disconnect error or when no matching controllers were found.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`

### bd_nvme_disconnect_by_path ()

    gboolean
    bd_nvme_disconnect_by_path (const gchar *path,
                                GError **error);

Disconnects and removes a NVMe over Fabrics controller represented by a block device path.

#### Parameters

path | NVMe controller device to disconnect (e.g. `/dev/nvme0`). |
error | Place to store error (if any). | [out][nullable]

#### Returns

`TRUE` if the controller was disconnected successfully, `FALSE` otherwise with `error` set.

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`

### bd_nvme_find_ctrls_for_ns ()

    gchar **
    bd_nvme_find_ctrls_for_ns (const gchar *ns_sysfs_path,
                               const gchar *subsysnqn,
                               const gchar *host_nqn,
                               const gchar *host_id,
                               GError **error);

A convenient utility function to look up all controllers associated with a NVMe subsystem the specified namespace is part of.

#### Parameters

ns_sysfs_path | NVMe namespace device file. |
subsysnqn | Limit matching to the specified subsystem NQN. | [nullable]
host_nqn | Limit matching to the specified host NQN. | [nullable]
host_id | Limit matching to the specified host ID. | [nullable]
error | Place to store error (if any). | [out][nullable]

#### Returns

list of controller sysfs paths or `NULL` in case of an error (with `error` set).

Tech category: `BD_NVME_TECH_FABRICS`-`BD_NVME_TECH_MODE_INITIATOR`.

[transfer full][array zero-terminated=1]

## Types and Values

### BD_NVME_ERROR

    #define             BD_NVME_ERROR

### enum BDNVMEError

#### Members

BD_NVME_ERROR_TECH_UNAVAIL | NVMe support not available. |
BD_NVME_ERROR_FAILED | General error. |
BD_NVME_ERROR_BUSY | The device is temporarily unavailable or in an inconsistent state. |
BD_NVME_ERROR_INVALID_ARGUMENT | Invalid argument. |
BD_NVME_ERROR_WOULD_FORMAT_ALL_NS | The NVMe controller indicates that it would format all namespaces in the NVM subsystem. |
BD_NVME_ERROR_SC_GENERIC | Generic NVMe Command Status Code. |
BD_NVME_ERROR_SC_CMD_SPECIFIC | NVMe Command Specific error. |
BD_NVME_ERROR_SC_MEDIA | Media and Data Integrity Errors: media specific errors that occur in the NVM or data integrity type errors. |
BD_NVME_ERROR_SC_PATH | Path related error. |
BD_NVME_ERROR_SC_VENDOR_SPECIFIC | NVMe Vendor specific error. |
BD_NVME_ERROR_NO_MATCH | No matching resource found (e.g. a Fabrics Controller). |
BD_NVME_ERROR_CONNECT | General connection error. |
BD_NVME_ERROR_CONNECT_ALREADY | Already connected. |
BD_NVME_ERROR_CONNECT_INVALID | Invalid argument specified. |
BD_NVME_ERROR_CONNECT_ADDRINUSE | HostNQN already in use. |
BD_NVME_ERROR_CONNECT_NODEV | Invalid interface. |
BD_NVME_ERROR_CONNECT_OPNOTSUPP | Operation not supported. |
BD_NVME_ERROR_CONNECT_REFUSED | Connection refused. |

### enum BDNVMETech

#### Members

BD_NVME_TECH_NVME |  |
BD_NVME_TECH_FABRICS |  |

### enum BDNVMETechMode

#### Members

BD_NVME_TECH_MODE_INFO |  |
BD_NVME_TECH_MODE_MANAGE |  |
BD_NVME_TECH_MODE_INITIATOR |  |

### enum BDNVMEControllerFeature

#### Members

BD_NVME_CTRL_FEAT_MULTIPORT | if set, then the NVM subsystem may contain more than one NVM subsystem port, otherwise it's single-port only. |
BD_NVME_CTRL_FEAT_MULTICTRL | if set, then the NVM subsystem may contain two or more controllers, otherwise contains only single controller. |
BD_NVME_CTRL_FEAT_SRIOV | if set, then the controller is associated with an SR-IOV Virtual Function, otherwise it's associated with a PCI Function or a Fabrics connection. |
BD_NVME_CTRL_FEAT_ANA_REPORTING | indicates that the NVM subsystem supports Asymmetric Namespace Access (ANA) Reporting. |
BD_NVME_CTRL_FEAT_FORMAT | indicates that the controller supports the Format NVM command. |
BD_NVME_CTRL_FEAT_FORMAT_ALL_NS | if set, then a format (excluding secure erase) of any namespace results in a format of all namespaces in an NVM subsystem with all namespaces in an NVM subsystem configured with the same attributes. If not set, then the controller supports format on a per namespace basis. |
BD_NVME_CTRL_FEAT_NS_MGMT | indicates that the controller supports the Namespace Management and Attachment capability. |
BD_NVME_CTRL_FEAT_SELFTEST | indicates that the controller supports the Device Self-test command. |
BD_NVME_CTRL_FEAT_SELFTEST_SINGLE | indicates that the NVM subsystem supports only one device self-test operation in progress at a time. |
BD_NVME_CTRL_FEAT_SANITIZE_CRYPTO | indicates that the controller supports the Crypto Erase sanitize operation. |
BD_NVME_CTRL_FEAT_SANITIZE_BLOCK | indicates that the controller supports the Block Erase sanitize operation. |
BD_NVME_CTRL_FEAT_SANITIZE_OVERWRITE | indicates that the controller supports the Overwrite sanitize operation. |
BD_NVME_CTRL_FEAT_SECURE_ERASE_ALL_NS | 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 not set, then any secure erase performed as part of a format results in a secure erase of the particular namespace specified. |
BD_NVME_CTRL_FEAT_SECURE_ERASE_CRYPTO | indicates that the cryptographic erase is supported. |
BD_NVME_CTRL_FEAT_STORAGE_DEVICE | indicates that the NVM subsystem is part of an NVMe Storage Device. |
BD_NVME_CTRL_FEAT_ENCLOSURE | indicates that the NVM subsystem is part of an NVMe Enclosure. |
BD_NVME_CTRL_FEAT_MGMT_PCIE | indicates that the NVM subsystem contains a Management Endpoint on a PCIe port. |
BD_NVME_CTRL_FEAT_MGMT_SMBUS | indicates that the NVM subsystem contains a Management Endpoint on an SMBus/I2C port. |

### enum BDNVMEControllerType

#### Members

BD_NVME_CTRL_TYPE_UNKNOWN | Controller type not reported (as reported by older NVMe-compliant devices). |
BD_NVME_CTRL_TYPE_IO | I/O controller. |
BD_NVME_CTRL_TYPE_DISCOVERY | Discovery controller. |
BD_NVME_CTRL_TYPE_ADMIN | Administrative controller. |

### BDNVMEControllerInfo

    typedef struct {
        guint16 pci_vendor_id;
        guint16 pci_subsys_vendor_id;
        guint16 ctrl_id;
        gchar *fguid;
        gchar *model_number;
        gchar *serial_number;
        gchar *firmware_ver;
        gchar *nvme_ver;
        guint64 features;
        BDNVMEControllerType controller_type;
        gint selftest_ext_time;
        guint64 hmb_pref_size;
        guint64 hmb_min_size;
        guint64 size_total;
        guint64 size_unalloc;
        guint num_namespaces;
        gchar *subsysnqn;
    } BDNVMEControllerInfo;

#### Members

guint16 `pci_vendor_id`; | The PCI Vendor ID. |
guint16 `pci_subsys_vendor_id`; | The PCI Subsystem Vendor ID. |
guint16 `ctrl_id`; | Controller ID, the NVM subsystem unique controller identifier associated with the controller. |
gchar *`fguid`; | FRU GUID, a 128-bit value that is globally unique for a given Field Replaceable Unit. |
gchar *`model_number`; | The model number. |
gchar *`serial_number`; | The serial number. |
gchar *`firmware_ver`; | The currently active firmware revision. |
gchar *`nvme_ver`; | The NVM Express base specification that the controller implementation supports or `NULL` when not reported by the device. |
guint64 `features`; | features and capabilities present for this controller, see BDNVMEControllerFeature. |
BDNVMEControllerType `controller_type`; | The controller type. |
gint `selftest_ext_time`; | Extended Device Self-test Time, if BD_NVME_CTRL_FEAT_SELFTEST is supported 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. |
guint64 `hmb_pref_size`; | Host Memory Buffer Preferred Size indicates the preferred size that the host is requested to allocate for the Host Memory Buffer feature in bytes. |
guint64 `hmb_min_size`; | Host Memory Buffer Minimum Size indicates the minimum size that the host is requested to allocate for the Host Memory Buffer feature in bytes. |
guint64 `size_total`; | Total NVM Capacity in the NVM subsystem in bytes. |
guint64 `size_unalloc`; | Unallocated NVM Capacity in the NVM subsystem in bytes. |
guint `num_namespaces`; | Maximum Number of Allowed Namespaces supported by the NVM subsystem. |
gchar *`subsysnqn`; | NVM Subsystem NVMe Qualified Name, UTF-8 null terminated string. |

### enum BDNVMELBAFormatRelativePerformance

#### Members

BD_NVME_LBA_FORMAT_RELATIVE_PERFORMANCE_UNKNOWN | Unknown relative performance index. |
BD_NVME_LBA_FORMAT_RELATIVE_PERFORMANCE_BEST | Best performance. |
BD_NVME_LBA_FORMAT_RELATIVE_PERFORMANCE_BETTER | Better performance. |
BD_NVME_LBA_FORMAT_RELATIVE_PERFORMANCE_GOOD | Good performance. |
BD_NVME_LBA_FORMAT_RELATIVE_PERFORMANCE_DEGRADED | Degraded performance. |

### BDNVMELBAFormat

    typedef struct {
        guint16 data_size;
        guint16 metadata_size;
        BDNVMELBAFormatRelativePerformance relative_performance;
    } BDNVMELBAFormat;

#### Members

guint16 `data_size`; | LBA data size (i.e. a sector size) in bytes. |
guint16 `metadata_size`; | metadata size in bytes or `0` in case of no metadata support. |
BDNVMELBAFormatRelativePerformance `relative_performance`; | Relative Performance index, see BDNVMELBAFormatRelativePerformance. |

### enum BDNVMENamespaceFeature

#### Members

BD_NVME_NS_FEAT_THIN | indicates that the namespace supports thin provisioning. Specifically, the Namespace Capacity reported may be less than the Namespace Size. |
BD_NVME_NS_FEAT_MULTIPATH_SHARED | indicates the capability to attach the namespace to two or more controllers in the NVM subsystem concurrently. |
BD_NVME_NS_FEAT_FORMAT_PROGRESS | indicates the capability to report the percentage of the namespace that remains to be formatted. |
BD_NVME_NS_FEAT_ROTATIONAL | indicates a rotational medium. |

### BDNVMENamespaceInfo

    typedef struct {
        guint32 nsid;
        gchar *eui64;
        gchar *uuid;
        gchar *nguid;
        guint64 nsize;
        guint64 ncap;
        guint64 nuse;
        guint64 features;
        guint8 format_progress_remaining;
        gboolean write_protected;
        BDNVMELBAFormat **lba_formats;
        BDNVMELBAFormat current_lba_format;
    } BDNVMENamespaceInfo;

#### Members

guint32 `nsid`; | The Namespace Identifier (NSID). |
gchar *`eui64`; | IEEE Extended Unique Identifier: a 64-bit IEEE Extended Unique Identifier (EUI-64) that is globally unique and assigned to the namespace when the namespace is created. Remains fixed throughout the life of the namespace and is preserved across namespace and controller operations. |
gchar *`uuid`; | Namespace 128-bit Universally Unique Identifier (UUID) as specified in RFC 4122. |
gchar *`nguid`; | Namespace Globally Unique Identifier: a 128-bit value that is globally unique and assigned to the namespace when the namespace is created. Remains fixed throughout the life of the namespace and is preserved across namespace and controller operations. |
guint64 `nsize`; | Namespace Size: total size of the namespace in logical blocks. The number of logical blocks is based on the formatted LBA size (see `current_lba_format` ). |
guint64 `ncap`; | Namespace Capacity: 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 (see `current_lba_format` ). |
guint64 `nuse`; | Namespace Utilization: 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 (see `current_lba_format` ). |
guint64 `features`; | features and capabilities present for this namespace, see BDNVMENamespaceFeature. |
guint8 `format_progress_remaining`; | The percentage value remaining of a format operation in progress. |
gboolean `write_protected`; | `TRUE` if the namespace is currently write protected and all write access to the namespace shall fail. |
BDNVMELBAFormat **`lba_formats`; | A list of supported LBA Formats. | [array zero-terminated=1]
BDNVMELBAFormat `current_lba_format`; | A LBA Format currently used for the namespace. Contains zeroes in case of an invalid or no supported LBA Format reported. |

### enum BDNVMESmartCriticalWarning

#### Members

BD_NVME_SMART_CRITICAL_WARNING_SPARE | the available spare capacity has fallen below the threshold. |
BD_NVME_SMART_CRITICAL_WARNING_TEMPERATURE | a temperature is either greater than or equal to an over temperature threshold; or less than or equal to an under temperature threshold. |
BD_NVME_SMART_CRITICAL_WARNING_DEGRADED | the NVM subsystem reliability has been degraded due to significant media related errors or any internal error that degrades NVM subsystem reliability. |
BD_NVME_SMART_CRITICAL_WARNING_READONLY | all of the media has been placed in read only mode. Unrelated to the write protection state of a namespace. |
BD_NVME_SMART_CRITICAL_WARNING_VOLATILE_MEM | the volatile memory backup device has failed. Valid only if the controller has a volatile memory backup solution. |
BD_NVME_SMART_CRITICAL_WARNING_PMR_READONLY | Persistent Memory Region has become read-only or unreliable. |

### BDNVMESmartLog

    typedef struct {
        guint critical_warning;
        guint8 avail_spare;
        guint8 spare_thresh;
        guint8 percent_used;
        guint64 total_data_read;
        guint64 total_data_written;
        guint64 ctrl_busy_time;
        guint64 power_cycles;
        guint64 power_on_hours;
        guint64 unsafe_shutdowns;
        guint64 media_errors;
        guint64 num_err_log_entries;
        guint16 temperature;
        guint16 temp_sensors[8];
        guint16 wctemp;
        guint16 cctemp;
        guint warning_temp_time;
        guint critical_temp_time;
    } BDNVMESmartLog;

#### Members

guint `critical_warning`; | critical warnings for the state of the controller, see BDNVMESmartCriticalWarning. |
guint8 `avail_spare`; | Available Spare: a normalized percentage (0% to 100%) of the remaining spare capacity available. |
guint8 `spare_thresh`; | Available Spare Threshold: a normalized percentage (0% to 100%) of the available spare threshold. |
guint8 `percent_used`; | Percentage Used: a vendor specific estimate of the percentage drive life used based on the actual usage and the manufacturer's prediction. A value of 100 indicates that the estimated endurance has been consumed, but may not indicate an NVM subsystem failure. The value is allowed to exceed 100. |
guint64 `total_data_read`; | An estimated calculation of total data read in bytes based on calculation of data units read from the host. A value of 0 indicates that the number of Data Units Read is not reported. |
guint64 `total_data_written`; | An estimated calculation of total data written in bytes based on calculation of data units written by the host. A value of 0 indicates that the number of Data Units Written is not reported. |
guint64 `ctrl_busy_time`; | Amount of time the controller is busy with I/O commands, reported in minutes. |
guint64 `power_cycles`; | The number of power cycles. |
guint64 `power_on_hours`; | The number of power-on hours, excluding a non-operational power state. |
guint64 `unsafe_shutdowns`; | The number of unsafe shutdowns as a result of a Shutdown Notification not received prior to loss of power. |
guint64 `media_errors`; | Media and Data Integrity Errors: the number of occurrences where the controller detected an unrecovered data integrity error (e.g. uncorrectable ECC, CRC checksum failure, or LBA tag mismatch). |
guint64 `num_err_log_entries`; | Number of Error Information Log Entries: the number of Error Information log entries over the life of the controller. |
guint16 `temperature`; | Composite Temperature: temperature in Kelvins that represents the current composite temperature of the controller and associated namespaces or 0 when not applicable. |
guint16 `temp_sensors`[8]; | Temperature Sensor 1-8: array of the current temperature reported by temperature sensors 1-8 in Kelvins or 0 when the particular sensor is not available. |
guint16 `wctemp`; | Warning Composite Temperature Threshold (WCTEMP): indicates the minimum Composite Temperature (`temperature` ) value that indicates an overheating condition during which controller operation continues. A value of 0 indicates that no warning temperature threshold value is reported by the controller. |
guint16 `cctemp`; | Critical Composite Temperature Threshold (CCTEMP): indicates the minimum Composite Temperature (`temperature` ) value that indicates a critical overheating condition (e.g., may prevent continued normal operation, possibility of data loss, automatic device shutdown, extreme performance throttling, or permanent damage). A value of 0 indicates that no critical temperature threshold value is reported by the controller. |
guint `warning_temp_time`; | Warning Composite Temperature Time: the amount of time in minutes that the Composite Temperature (`temperature` ) is greater than or equal to the Warning Composite Temperature Threshold (`wctemp` ) and less than the Critical Composite Temperature Threshold (`cctemp` ). |
guint `critical_temp_time`; | Critical Composite Temperature Time: the amount of time in minutes that the Composite Temperature (`temperature` ) is greater than or equal to the Critical Composite Temperature Threshold (`cctemp` ). |

### enum BDNVMETransportType

#### Members

BD_NVME_TRANSPORT_TYPE_UNSPECIFIED | Not indicated |
BD_NVME_TRANSPORT_TYPE_RDMA | RDMA Transport |
BD_NVME_TRANSPORT_TYPE_FC | Fibre Channel Transport |
BD_NVME_TRANSPORT_TYPE_TCP | TCP Transport |
BD_NVME_TRANSPORT_TYPE_LOOP | Intra-host Transport (loopback) |

### BDNVMEErrorLogEntry

    typedef struct {
        guint64 error_count;
        guint16 command_id;
        guint64 command_specific;
        guint16 command_status;
        GError *command_error;
        guint64 lba;
        guint32 nsid;
        BDNVMETransportType transport_type;
    } BDNVMEErrorLogEntry;

#### Members

guint64 `error_count`; | internal error counter, a unique identifier for the error. |
guint16 `command_id`; | the Command Identifier of the command that the error is associated with or `0xffff` if the error is not specific to a particular command. |
guint64 `command_specific`; | Command Specific Information specific to `command_id` . |
guint16 `command_status`; | the Status code for the command that completed. |
GError *`command_error`; | translated command error in the BD_NVME_ERROR domain or `NULL` in case `command_status` indicates success. |
guint64 `lba`; | the first LBA that experienced the error condition. |
guint32 `nsid`; | the NSID of the namespace that the error is associated with. |
BDNVMETransportType `transport_type`; | type of the transport associated with the error. |

### BDNVMESelfTestLog

    typedef struct {
        BDNVMESelfTestAction current_operation;
        guint8 current_operation_completion;
        BDNVMESelfTestLogEntry **entries;
    } BDNVMESelfTestLog;

#### Members

BDNVMESelfTestAction `current_operation`; | Current running device self-test operation. There's no corresponding record in `entries` for a device self-test operation that is in progress. |
guint8 `current_operation_completion`; | Percentage of the currently running device self-test operation. Only valid when `current_operation` is other than BD_NVME_SELF_TEST_ACTION_NOT_RUNNING. |
BDNVMESelfTestLogEntry **`entries`; | Self-test log entries for the last 20 operations, sorted from newest (first element) to oldest. | [array zero-terminated=1]

### BDNVMESelfTestLogEntry

    typedef struct {
        BDNVMESelfTestResult result;
        BDNVMESelfTestAction action;
        guint8 segment;
        guint64 power_on_hours;
        guint32 nsid;
        guint64 failing_lba;
        GError *status_code_error;
    } BDNVMESelfTestLogEntry;

#### Members

BDNVMESelfTestResult `result`; | Result of the device self-test operation. |
BDNVMESelfTestAction `action`; | The Self-test Code value (action) that was specified in the Device Self-test command that started this device self-test operation. |
guint8 `segment`; | Segment number where the first self-test failure occurred. Valid only when `result` is set to BD_NVME_SELF_TEST_RESULT_KNOWN_SEG_FAIL. |
guint64 `power_on_hours`; | Number of power-on hours at the time the device self-test operation was completed or aborted. Does not include time that the controller was powered and in a low power state condition. |
guint32 `nsid`; | Namespace ID that the Failing LBA occurred on. |
guint64 `failing_lba`; | 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. |
GError *`status_code_error`; | Translated NVMe Command Status Code representing additional information related to errors or conditions. |

### enum BDNVMESelfTestAction

#### Members

BD_NVME_SELF_TEST_ACTION_NOT_RUNNING | No device self-test operation in progress. Not a valid argument for `bd_nvme_device_self_test()`. |
BD_NVME_SELF_TEST_ACTION_SHORT | Start a short device self-test operation. |
BD_NVME_SELF_TEST_ACTION_EXTENDED | Start an extended device self-test operation. |
BD_NVME_SELF_TEST_ACTION_VENDOR_SPECIFIC | Start a vendor specific device self-test operation. |
BD_NVME_SELF_TEST_ACTION_ABORT | Abort the device self-test operation. Only valid for `bd_nvme_device_self_test()`. |

### enum BDNVMESelfTestResult

#### Members

BD_NVME_SELF_TEST_RESULT_NO_ERROR | Operation completed without error. |
BD_NVME_SELF_TEST_RESULT_ABORTED | Operation was aborted by a Device Self-test command. |
BD_NVME_SELF_TEST_RESULT_CTRL_RESET | Operation was aborted by a Controller Level Reset. |
BD_NVME_SELF_TEST_RESULT_NS_REMOVED | Operation was aborted due to a removal of a namespace from the namespace inventory. |
BD_NVME_SELF_TEST_RESULT_ABORTED_FORMAT | Operation was aborted due to the processing of a Format NVM command. |
BD_NVME_SELF_TEST_RESULT_FATAL_ERROR | A fatal error or unknown test error occurred while the controller was executing the device self-test operation and the operation did not complete. |
BD_NVME_SELF_TEST_RESULT_UNKNOWN_SEG_FAIL | Operation completed with a segment that failed and the segment that failed is not known. |
BD_NVME_SELF_TEST_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. |
BD_NVME_SELF_TEST_RESULT_ABORTED_UNKNOWN | Operation was aborted for unknown reason. |
BD_NVME_SELF_TEST_RESULT_ABORTED_SANITIZE | Operation was aborted due to a sanitize operation. |

### enum BDNVMEFormatSecureErase

#### Members

BD_NVME_FORMAT_SECURE_ERASE_NONE | No secure erase operation requested. |
BD_NVME_FORMAT_SECURE_ERASE_USER_DATA | 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. |
BD_NVME_FORMAT_SECURE_ERASE_CRYPTO | Cryptographic Erase: All user data shall be erased cryptographically. This is accomplished by deleting the encryption key. |

### enum BDNVMESanitizeStatus

#### Members

BD_NVME_SANITIZE_STATUS_NEVER_SANITIZED | The NVM subsystem has never been sanitized. |
BD_NVME_SANITIZE_STATUS_IN_PROGESS | A sanitize operation is currently in progress. |
BD_NVME_SANITIZE_STATUS_SUCCESS | The most recent sanitize operation completed successfully including any additional media modification. |
BD_NVME_SANITIZE_STATUS_SUCCESS_NO_DEALLOC | The most recent sanitize operation for which No-Deallocate After Sanitize was requested has completed successfully with deallocation of all user data. |
BD_NVME_SANITIZE_STATUS_FAILED | The most recent sanitize operation failed. |

### BDNVMESanitizeLog

    typedef struct {
        gdouble sanitize_progress;
        BDNVMESanitizeStatus sanitize_status;
        gboolean global_data_erased;
        guint8 overwrite_passes;
        gint64 time_for_overwrite;
        gint64 time_for_block_erase;
        gint64 time_for_crypto_erase;
        gint64 time_for_overwrite_nd;
        gint64 time_for_block_erase_nd;
        gint64 time_for_crypto_erase_nd;
    } BDNVMESanitizeLog;

#### Members

gdouble `sanitize_progress`; | The percentage complete of the sanitize operation. |
BDNVMESanitizeStatus `sanitize_status`; | The status of the most recent sanitize operation. |
gboolean `global_data_erased`; | Indicates that no user data has been written either since the drive was manufactured and has never been sanitized or since the most recent successful sanitize operation. |
guint8 `overwrite_passes`; | Number of completed passes if the most recent sanitize operation was an Overwrite. |
gint64 `time_for_overwrite`; | Estimated time in seconds needed to complete an Overwrite sanitize operation with 16 passes in the background. A value of -1 means that no time estimate is reported. A value of 0 means that the operation is expected to be completed in the background when the Sanitize command is completed. |
gint64 `time_for_block_erase`; | Estimated time in seconds needed to complete a Block Erase sanitize operation in the background. A value of -1 means that no time estimate is reported. A value of 0 means that the operation is expected to be completed in the background when the Sanitize command is completed. |
gint64 `time_for_crypto_erase`; | Estimated time in seconds needed to complete a Crypto Erase sanitize operation in the background. A value of -1 means that no time estimate is reported. A value of 0 means that the operation is expected to be completed in the background when the Sanitize command is completed. |
gint64 `time_for_overwrite_nd`; | Estimated time in seconds needed to complete an Overwrite sanitize operation and the associated additional media modification in the background when the No-Deallocate After Sanitize or the No-Deallocate Modifies Media After Sanitize features have been requested. |
gint64 `time_for_block_erase_nd`; | Estimated time in seconds needed to complete a Block Erase sanitize operation and the associated additional media modification in the background when the No-Deallocate After Sanitize or the No-Deallocate Modifies Media After Sanitize features have been requested. |
gint64 `time_for_crypto_erase_nd`; | Estimated time in seconds needed to complete a Crypto Erase sanitize operation and the associated additional media modification in the background when the No-Deallocate After Sanitize or the No-Deallocate Modifies Media After Sanitize features have been requested. |

### enum BDNVMESanitizeAction

#### Members

BD_NVME_SANITIZE_ACTION_EXIT_FAILURE | Exit Failure Mode. |
BD_NVME_SANITIZE_ACTION_BLOCK_ERASE | Start a Block Erase sanitize operation - a low-level block erase method that is specific to the media. |
BD_NVME_SANITIZE_ACTION_OVERWRITE | Start an Overwrite sanitize operation - writing a fixed data pattern or related patterns in multiple passes. |
BD_NVME_SANITIZE_ACTION_CRYPTO_ERASE | Start a Crypto Erase sanitize operation - changing the media encryption keys for all locations on the media. |