org.freedesktop.UDisks2.NVMe.Controller: UDisks Reference Manual

org.freedesktop.UDisks2.NVMe.Controller

org.freedesktop.UDisks2.NVMe.Controller — NVMe controller device

Methods

SmartUpdate        (IN  a{sv} options);
SmartGetAttributes (IN  a{sv} options,
                    OUT a{sv} attributes);
SmartSelftestStart (IN  s     type,
                    IN  a{sv} options);
SmartSelftestAbort (IN  a{sv} options);
SanitizeStart      (IN  s     action,
                    IN  a{sv} options);

Properties

State                          readable   s
ControllerID                   readable   q
SubsystemNQN                   readable   ay
FGUID                          readable   s
NVMeRevision                   readable   s
UnallocatedCapacity            readable   t
SmartUpdated                   readable   t
SmartCriticalWarning           readable   as
SmartPowerOnHours              readable   t
SmartTemperature               readable   q
SmartSelftestStatus            readable   s
SmartSelftestPercentRemaining  readable   i
SanitizeStatus                 readable   s
SanitizePercentRemaining       readable   i

Description

This interface represents a controller device in a NVM subsystem.

Method Details

The SmartUpdate() method

SmartUpdate (IN  a{sv} options);

Reads SMART/Health Information from the NVMe controller and update relevant properties. Data in this interface are typically updated on every uevent or as a result of Asynchronous Event Notification.

IN a{sv} options:

Options (currently unused except for standard options).

Since 2.10.0

The SmartGetAttributes() method

SmartGetAttributes (IN  a{sv} options,
                    OUT a{sv} attributes);

Get the SMART/Health Information attributes.

Known values include:

avail_spare (type 'y')	Available Spare: a normalized percentage (0 to 100) of the remaining spare capacity available.
spare_thresh (type 'y')	Available Spare Threshold: a normalized percentage (0 to 100) of the available spare threshold.
percent_used (type 'y')	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.
total_data_read (type 't')	An estimated calculation of total data read in bytes based on calculation of data units read from the host.
total_data_written (type 't')	An estimated calculation of total data written in bytes based on calculation of data units written by the host.
ctrl_busy_time (type 't')	Amount of time the controller is busy with I/O commands, reported in minutes.
power_cycles (type 't')	The number of power cycles.
unsafe_shutdowns (type 't')	The number of unsafe shutdowns as a result of a Shutdown Notification not received prior to loss of power.
media_errors (type 't')	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).
num_err_log_entries (type 't')	Number of Error Information Log Entries: the number of Error Information log entries over the life of the controller.
temp_sensors (type 'aq')	Array of the current temperature reported by temperature sensors 1-8 in Kelvins or 0 when the particular sensor is not available.
wctemp (type 'q')	Warning Composite Temperature Threshold (WCTEMP): indicates the minimum Composite Temperature (`SmartTemperature`) value that indicates an overheating condition during which controller operation continues.
cctemp (type 'q')	Critical Composite Temperature Threshold (CCTEMP): indicates the minimum Composite Temperature (`SmartTemperature`) 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).
warning_temp_time (type 'u')	Warning Composite Temperature Time: the amount of time in minutes that the Composite Temperature (`SmartTemperature`) is greater than or equal to the Warning Composite Temperature Threshold (`wctemp`) and less than the Critical Composite Temperature Threshold (`cctemp`).
critical_temp_time (type 'u')	Critical Composite Temperature Time: the amount of time in minutes that the Composite Temperature (`SmartTemperature`) is greater than or equal to the Critical Composite Temperature Threshold (`cctemp`).

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT a{sv} attributes`:	The SMART attributes.

Since 2.10.0

The SmartSelftestStart() method

SmartSelftestStart (IN  s     type,
                    IN  a{sv} options);

Starts a device selftest operation on all active namespaces accessible through the controller at the time the operation is started. A device selftest 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 type parameter indicates the type of test to start - valid values are short, extended and vendor-specific.

Note that the method returns immediately after the test has been started successfully and the operation is performed in the background.

`IN s type`:	The type test to run.
`IN a{sv} options`:	Options (currently unused except for standard options).

Since 2.10.0

The SmartSelftestAbort() method

SmartSelftestAbort (IN  a{sv} options);

Aborts a running device selftest.

IN a{sv} options:

Options (currently unused except for standard options).

Since 2.10.0

The SanitizeStart() method

SanitizeStart (IN  s     action,
               IN  a{sv} options);

Starts a sanitize operation in the background. 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.

The sanitize operation is set to be executed with the No-Deallocate After Sanitize feature turned on, i.e. the controller shall not deallocate any user data as a result of successfully completing the sanitize operation.

The action parameter indicates the type of the sanitize action to take - valid values are block-erase, overwrite and crypto-erase.

In case of the overwrite action additional options are taken in account. The overwrite_pass_count option specifies number of overwrite passes (1-15) defaulting to 16 passes when not specified. The overwrite_pattern option specifies a 32-bit pattern, defaulting to zero if not specified. The overwrite_invert_pattern option indicates that the overwrite pattern should be inverted between passes.

`IN s action`:	The sanitize action to perform.
`IN a{sv} options`:	Options - known options (in addition to standard options) includes `overwrite_pass_count` (of type 'y'), `overwrite_pattern` (of type 'u') and `overwrite_invert_pattern` (of type 'b').

Since 2.10.0

Property Details

The "State" property

State  readable   s

The controller operating state. Values other than live may result in temporary refusal of any I/O and subsequent missing information provided by UDisks.

Known values include:

live	Controller is up and running.
new
resetting
connecting
deleting
deleting (no IO)
dead

Since 2.10.0

The "ControllerID" property

ControllerID  readable   q

The NVM subsystem unique controller identifier.

Since 2.10.0

The "SubsystemNQN" property

SubsystemNQN  readable   ay

The NVM Subsystem NVMe Qualified Name.

Since 2.10.0

The "FGUID" property

FGUID  readable   s

The FRU Globally Unique Identifier.

Field-Replaceable Unit (FRU) is a physical component, device, or assembly that is able to be removed and replaced without having to replace the entire system.

The FRU Globally Unique Identifier is a 128-bit value that is globally unique for a given Field Replaceable Unit (FRU). Value of 0 indicates this feature is not supported.

Since 2.10.0

The "NVMeRevision" property

NVMeRevision  readable   s

The major, minor, and micro version of the NVM Express base specification that the controller implementation supports. Note that some older devices (typically NVMe rev. lower than 1.2) may not always report this value.

Since 2.10.0

The "UnallocatedCapacity" property

UnallocatedCapacity  readable   t

The unallocated NVM capacity that is accessible by the controller.

Since 2.10.0

The "SmartUpdated" property

SmartUpdated  readable   t

The point in time (seconds since the Unix Epoch) that the SMART/Health Information was updated or 0 if never updated.

The value of the other properties related to SMART are not meaningful if this property is 0.

Since 2.10.0

The "SmartCriticalWarning" property

SmartCriticalWarning  readable   as

Critical warnings issued for the current state of the controller. An empty array indicates a healthy state. This is the primary health assesment property to watch for.

Known values include:

spare	The available spare capacity has fallen below the threshold.
temperature	A temperature is either greater than or equal to an over temperature threshold; or less than or equal to an under temperature threshold.
degraded	The NVM subsystem reliability has been degraded due to significant media related errors or any internal error that degrades NVM subsystem reliability.
readonly	All of the media has been placed in read only mode. Unrelated to the write protection state of a namespace.
volatile_mem	The volatile memory backup device has failed. Only valid if the controller has a volatile memory backup solution.
pmr_readonly	Persistent Memory Region has become read-only or unreliable.

Since 2.10.0

The "SmartPowerOnHours" property

SmartPowerOnHours  readable   t

The amount of time the disk has been powered on (according to SMART data) or 0 if unknown.

Since 2.10.0

The "SmartTemperature" property

SmartTemperature  readable   q

The temperature (in Kelvin) that represents the current composite temperature of the controller and associated namespaces or 0 if unknown. Values of the particular temperature sensors are exposed via the SmartGetAttributes() method.

Since 2.10.0

The "SmartSelftestStatus" property

SmartSelftestStatus  readable   s

The status of the last self-test. Known values include:

success	Operation completed without error (or never ran).
aborted	Operation was aborted by a Device Self-test command.
ctrl_reset	Operation was aborted by a Controller Level Reset.
ns_removed	Operation was aborted due to a removal of a namespace from the namespace inventory.
aborted_format	Operation was aborted due to the processing of a Format NVM command.
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.
unknown_seg_fail	Operation completed with a segment that failed and the segment that failed is not known.
known_seg_fail	Operation completed with one or more failed segments.
aborted_unknown	Operation was aborted for unknown reason.
aborted_sanitize	Operation was aborted due to a sanitize operation.
inprogress	Self-test operation is currently in progress.

Since 2.10.0

The "SmartSelftestPercentRemaining" property

SmartSelftestPercentRemaining  readable   i

The percent remaining or -1 if unknown.

Since 2.10.0

The "SanitizeStatus" property

SanitizeStatus  readable   s

The information about the most recent sanitize operation. Known values include:

never_sanitized	The NVM subsystem has never been sanitized (or the status is unknown).
success	Operation completed successfully.
failure	The most recent sanitize operation failed.
inprogress	A sanitize operation is currently in progress.

Since 2.10.0

The "SanitizePercentRemaining" property

SanitizePercentRemaining  readable   i

The percent remaining or -1 if unknown.

Since 2.10.0