## 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

`since`: 2.10.0

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 |

### The "ControllerID" property

    ControllerID  readable   q

`since`: 2.10.0

The NVM subsystem unique controller identifier.

### The "SubsystemNQN" property

    SubsystemNQN  readable   ay

`since`: 2.10.0

The NVM Subsystem NVMe Qualified Name.

### The "FGUID" property

    FGUID  readable   s

`since`: 2.10.0

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.

### The "NVMeRevision" property

    NVMeRevision  readable   s

`since`: 2.10.0

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.

### The "UnallocatedCapacity" property

    UnallocatedCapacity  readable   t

`since`: 2.10.0

The unallocated NVM capacity that is accessible by the controller.

### The "SmartUpdated" property

    SmartUpdated  readable   t

`since`: 2.10.0

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.

### The "SmartCriticalWarning" property

    SmartCriticalWarning  readable   as

`since`: 2.10.0

Critical warnings issued for the current state of the controller. An empty array indicates a healthy state. This is the primary health assessment 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.

### The "SmartPowerOnHours" property

    SmartPowerOnHours  readable   t

`since`: 2.10.0

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

### The "SmartTemperature" property

    SmartTemperature  readable   q

`since`: 2.10.0

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.

### The "SmartSelftestStatus" property

    SmartSelftestStatus  readable   s

`since`: 2.10.0

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.

### The "SmartSelftestPercentRemaining" property

    SmartSelftestPercentRemaining  readable   i

The percent remaining or -1 if unknown.

Since 2.10.0

### The "SanitizeStatus" property

    SanitizeStatus  readable   s

`since`: 2.10.0

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.

### The "SanitizePercentRemaining" property

    SanitizePercentRemaining  readable   i

The percent remaining or -1 if unknown.

Since 2.10.0