org.freedesktop.UDisks2.Drive.Ata: UDisks Reference Manual

org.freedesktop.UDisks2.Drive.Ata

org.freedesktop.UDisks2.Drive.Ata — Disk drives using the ATA command-set

Methods

SmartUpdate        (IN  a{sv}            options);
SmartGetAttributes (IN  a{sv}            options,
                    OUT a(ysqiiixia{sv}) attributes);
SmartSelftestStart (IN  s                type,
                    IN  a{sv}            options);
SmartSelftestAbort (IN  a{sv}            options);
SmartSetEnabled    (IN  b                value,
                    IN  a{sv}            options);
PmGetState         (IN  a{sv}            options,
                    OUT y                state);
PmStandby          (IN  a{sv}            options);
PmWakeup           (IN  a{sv}            options);
SecurityEraseUnit  (IN  a{sv}            options);

Properties

SmartSupported                     readable   b
SmartEnabled                       readable   b
SmartUpdated                       readable   t
SmartFailing                       readable   b
SmartPowerOnSeconds                readable   t
SmartTemperature                   readable   d
SmartNumAttributesFailing          readable   i
SmartNumAttributesFailedInThePast  readable   i
SmartNumBadSectors                 readable   x
SmartSelftestStatus                readable   s
SmartSelftestPercentRemaining      readable   i
PmSupported                        readable   b
PmEnabled                          readable   b
ApmSupported                       readable   b
ApmEnabled                         readable   b
AamSupported                       readable   b
AamEnabled                         readable   b
AamVendorRecommendedValue          readable   i
WriteCacheSupported                readable   b
WriteCacheEnabled                  readable   b
ReadLookaheadSupported             readable   b
ReadLookaheadEnabled               readable   b
SecurityEraseUnitMinutes           readable   i
SecurityEnhancedEraseUnitMinutes   readable   i
SecurityFrozen                     readable   b

Description

Objects implementing this interface also implement the org.freedesktop.UDisks2.Drive interface.

Method Details

The SmartUpdate() method

SmartUpdate (IN  a{sv} options);

Reads SMART data from the drive and update relevant properties.

If the option nowakeup is given and the disk is in a sleeping state, the error org.freedesktop.UDisks2.Error.WouldWakeup is returned.

The option atasmart_blob (of type 's' representing a path to the blob file) can be used to inject libatasmart-compatible blobs for testing how clients react to different kinds of SMART data. Only valid when backed with the libblockdev_libatasmart plugin. This option may be removed in the future without it being considered an ABI break. Deprecated since 2.11.0.

IN a{sv} options:

Options - known options (in addition to standard options) includes nowakeup (of type 'b').

The SmartGetAttributes() method

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

Get the SMART attributes. Each attribute is a struct with the following members:

id (type 'y')	Attribute Identifier
name (type 's')	The identifier as a string.
flags (type 'q')	16-bit attribute flags (bit 0 is prefail/oldage, bit 1 is online/offline).
value (type 'i')	The current value or -1 if unknown.
worst (type 'i')	The worst value of -1 if unknown.
threshold (type 'i')	The threshold or -1 if unknown.
pretty (type 'x')	An interpretation of the value - must be ignored if `pretty_unit` is 0.
pretty_unit (type 'i')	The unit of the `pretty` value - the following units are known: 0 (unknown), 1 (dimensionless), 2 (milliseconds), 3 (sectors), 4 (millikelvin).
expansion (type 'a{sv}')	Currently unused. Intended for future expansion.

The name parameter should be used as the authoritative identifier for the attribute since it is derived from the numerical id and the disk's IDENTIFY data and thus handles ID collisions between drives of different make and model.

`IN a{sv} options`:	Options - known options (in addition to standard options) includes `nowakeup` (of type 'b').
`OUT a(ysqiiixia{sv}) attributes`:	The SMART attributes.

The SmartSelftestStart() method

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

Starts a SMART selftest. The type parameter is for the type of test to start - valid values are short, extended, conveyance and offline (since 2.11.0).

Note that the method returns immediately after the test has been started successfully.

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

The SmartSelftestAbort() method

SmartSelftestAbort (IN  a{sv} options);

Aborts a running SMART selftest.

IN a{sv} options:

Options (currently unused except for standard options).

The SmartSetEnabled() method

SmartSetEnabled (IN  b     value,
                 IN  a{sv} options);

Sets whether SMART is enabled for the drive. This setting is stored in the non-volatile memory in the drive itself and does not need to be refreshed every time the drive is powered on or connected.

Since this may require authentication and thus may fail, it is implemented this way instead of the "SmartEnabled" property being writable.

`IN b value`:	`TRUE` to enable SMART, `FALSE` to disable SMART.
`IN a{sv} options`:	Options (currently unused except for standard options).

Since 2.0.0

The PmGetState() method

PmGetState (IN  a{sv} options,
            OUT y     state);

Get the current power mode status. This is implemented as a method call as it involves sending a command from the host to the drive and no change notification is available.

The format of state is the result obtained from sending the ATA command “CHECK POWER MODE” to the drive. Known values include

0x00	Standby
0x80	Idle
0xff	Active/Idle

Typically user interfaces will report "Drive is spun down" if state is 0x00 and "Drive is spun up" otherwise.

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT y state`:	The current power state.

The PmStandby() method

PmStandby (IN  a{sv} options);

Force the drive to immediately enter the low power consumption standby mode, usually causing it to spin down. This is done by sending the ATA command “STANDBY IMMEDIATE” to the drive.

IN a{sv} options:

Options (currently unused except for standard options).

The PmWakeup() method

PmWakeup (IN  a{sv} options);

Force the drive to immediately wake up (exiting the low power consumption standby mode), usually causing it to spin up. This is done by reading data from the disk.

IN a{sv} options:

Options (currently unused except for standard options).

The SecurityEraseUnit() method

SecurityEraseUnit (IN  a{sv} options);

Does all the necessary checks and preparations and then sends the “SECURITY ERASE UNIT” command to the drive. If the option enhanced is set to TRUE an enhanced secure erase is requested.

All data on the drive will be irrevocably erased.

This operation takes either "SecurityEraseUnitMinutes" or "SecurityEnhancedEraseUnitMinutes" minutes to complete depending on whether the enhanced option is TRUE.

IN a{sv} options:

Options - known options (in addition to standard options) includes enhanced (of type 'b').

Property Details

The "SmartSupported" property

SmartSupported  readable   b

Whether the drive supports SMART.

The "SmartEnabled" property

SmartEnabled  readable   b

Whether SMART is enabled.

The "SmartUpdated" property

SmartUpdated  readable   t

The point in time (seconds since the Unix Epoch) that the SMART status 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 "SmartFailing" property

SmartFailing  readable   b

Set to TRUE if disk is about to fail.

This value is read from the disk itself and does not include any interpretation.

The "SmartPowerOnSeconds" property

SmartPowerOnSeconds  readable   t

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

The "SmartTemperature" property

SmartTemperature  readable   d

The temperature (in Kelvin) of the disk according to SMART data or 0 if unknown.

The "SmartNumAttributesFailing" property

SmartNumAttributesFailing  readable   i

The number of attributes failing right now or -1 if unknown.

The "SmartNumAttributesFailedInThePast" property

SmartNumAttributesFailedInThePast  readable   i

The number of attributes that have failed in the past or -1 if unknown.

The "SmartNumBadSectors" property

SmartNumBadSectors  readable   x

The number of bad sectors (ie. pending and reallocated) or -1 if unknown.

The "SmartSelftestStatus" property

SmartSelftestStatus  readable   s

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

success	Last self-test was a success (or never ran).
aborted	Last self-test was aborted.
interrupted	Last self-test was interrupted.
fatal	Last self-test did not complete.
error_unknown	Last self-test failed (Unknown).
error_electrical	Last self-test failed (Electrical).
error_servo	Last self-test failed (Servo).
error_read	Last self-test failed (Read).
error_handling	Last self-test failed (Damage).
inprogress	Self-test is currently in progress.

The "SmartSelftestPercentRemaining" property

SmartSelftestPercentRemaining  readable   i

The percent remaining or -1 if unknown.

The "PmSupported" property

PmSupported  readable   b

Whether the drive supports power management.

The "PmEnabled" property

PmEnabled  readable   b

Whether power management is enabled.

The "ApmSupported" property

ApmSupported  readable   b

Whether the drive supports Advanced Power Management (APM).

The "ApmEnabled" property

ApmEnabled  readable   b

Whether Advanced Power Management (APM) is enabled.

The "AamSupported" property

AamSupported  readable   b

Whether the drive supports Automatic Acoustic Management (AAM).

The "AamEnabled" property

AamEnabled  readable   b

Whether Automatic Acoustic Management (AAM) is enabled.

The "AamVendorRecommendedValue" property

AamVendorRecommendedValue  readable   i

The vendor-recommended AAM value (or 0 if AAM is not supported).

The "WriteCacheSupported" property

WriteCacheSupported  readable   b

since: 2.0.0 Whether the drive supports configuring the write cache.

The "WriteCacheEnabled" property

WriteCacheEnabled  readable   b

since: 2.0.0 Whether the write-cache is enabled (or FALSE if not supported).

The "ReadLookaheadSupported" property

ReadLookaheadSupported  readable   b

since: 2.1.7 Whether the drive supports configuring the read look-ahead.

The "ReadLookaheadEnabled" property

ReadLookaheadEnabled  readable   b

since: 2.1.7 Whether the read look-ahead is enabled (or FALSE if not supported).

The "SecurityEraseUnitMinutes" property

SecurityEraseUnitMinutes  readable   i

The estimated amount of minutes it takes to complete the “SECURITY ERASE UNIT” command or 0 if this command is not available.

If set to 510 it means that it takes at least 508 minutes to complete the operation.

The "SecurityEnhancedEraseUnitMinutes" property

SecurityEnhancedEraseUnitMinutes  readable   i

The estimated amount of minutes it takes to complete the “SECURITY ERASE UNIT” command with enhanced mode specified or 0 if enhanced erase is not available.

If set to 510 it means that it takes at least 508 minutes to complete the operation.

The "SecurityFrozen" property

SecurityFrozen  readable   b

If set to TRUE the unit is frozen.