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);

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.

bd_nvme_controller_info_free ()

void
bd_nvme_controller_info_free (BDNVMEControllerInfo *info);

Frees info .

[skip]

bd_nvme_controller_info_copy ()

BDNVMEControllerInfo *
bd_nvme_controller_info_copy (BDNVMEControllerInfo *info);

Creates a new copy of info .

[skip]

bd_nvme_lba_format_free ()

void
bd_nvme_lba_format_free (BDNVMELBAFormat *fmt);

Frees fmt .

[skip]

bd_nvme_lba_format_copy ()

BDNVMELBAFormat *
bd_nvme_lba_format_copy (BDNVMELBAFormat *fmt);

Creates a new copy of fmt .

[skip]

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.

bd_nvme_namespace_info_free ()

void
bd_nvme_namespace_info_free (BDNVMENamespaceInfo *info);

Frees info .

[skip]

bd_nvme_namespace_info_copy ()

BDNVMENamespaceInfo *
bd_nvme_namespace_info_copy (BDNVMENamespaceInfo *info);

Creates a new copy of info .

[skip]

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.

bd_nvme_smart_log_free ()

void
bd_nvme_smart_log_free (BDNVMESmartLog *log);

Frees log .

[skip]

bd_nvme_smart_log_copy ()

BDNVMESmartLog *
bd_nvme_smart_log_copy (BDNVMESmartLog *log);

Creates a new copy of log .

[skip]

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.

bd_nvme_error_log_entry_free ()

void
bd_nvme_error_log_entry_free (BDNVMEErrorLogEntry *entry);

Frees entry .

[skip]

bd_nvme_error_log_entry_copy ()

BDNVMEErrorLogEntry *
bd_nvme_error_log_entry_copy (BDNVMEErrorLogEntry *entry);

Creates a new copy of entry .

[skip]

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.

bd_nvme_self_test_log_free ()

void
bd_nvme_self_test_log_free (BDNVMESelfTestLog *log);

Frees log .

[skip]

bd_nvme_self_test_log_copy ()

BDNVMESelfTestLog *
bd_nvme_self_test_log_copy (BDNVMESelfTestLog *log);

Creates a new copy of log .

[skip]

bd_nvme_self_test_log_entry_free ()

void
bd_nvme_self_test_log_entry_free (BDNVMESelfTestLogEntry *entry);

Frees entry .

[skip]

bd_nvme_self_test_log_entry_copy ()

BDNVMESelfTestLogEntry *
bd_nvme_self_test_log_entry_copy (BDNVMESelfTestLogEntry *entry);

Creates a new copy of entry .

[skip]

bd_nvme_self_test_result_to_string ()

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

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().

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().

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.

bd_nvme_sanitize_log_free ()

void
bd_nvme_sanitize_log_free (BDNVMESanitizeLog *log);

Frees log .

[skip]

bd_nvme_sanitize_log_copy ()

BDNVMESanitizeLog *
bd_nvme_sanitize_log_copy (BDNVMESanitizeLog *log);

Creates a new copy of log .

[skip]

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.

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.

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.

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.

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.

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.

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:

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

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.

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.

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.

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.

BD_NVME_ERROR

#define             BD_NVME_ERROR

enum BDNVMEError

enum BDNVMETech

enum BDNVMETechMode

enum BDNVMEControllerFeature

enum BDNVMEControllerType

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;

enum BDNVMELBAFormatRelativePerformance

BDNVMELBAFormat

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

enum BDNVMENamespaceFeature

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;

enum BDNVMESmartCriticalWarning

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;

enum BDNVMETransportType

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;

BDNVMESelfTestLog

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

BDNVMESelfTestLogEntry

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

enum BDNVMESelfTestAction

enum BDNVMESelfTestResult

enum BDNVMEFormatSecureErase

enum BDNVMESanitizeStatus

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;

enum BDNVMESanitizeAction