libatasmart plugin

An implementation proven for over a decade, being essentially a port of UDisks code. The libatasmart library is reasonably lightweight with minimal dependencies, light on I/O and consuming C API directly with clearly defined data types. However essentially no quirks or any drive database is present in the library (apart from a couple of very old laptop drives).

smartmontools plugin

In contrast to libatasmart, the smartmontools project is a feature-rich implementation supporting specialties like vendor-specific data blocks. It is a considerably heavier implementation I/O-wise due to device type detection and retrieval of more data blocks from the drive.

There's no C API at the moment and the plugin resorts to executing the smartctl command and parsing its JSON output, that is by nature loosely-defined. This presents challenges in data type conversions, interpretation of printed values and volatile JSON key presence. Besides, executing external commands always brings certain performance overhead and caution is advised when retrieving SMART data from multiple drives in parallel.

Attribute naming and value interpretation

Check BDSmartATAAttribute for the struct members overview first. The plugin public API provides both the implementation-specific attribute names/values as well as unified ('well-known', translated) interpretation that is preferred for general use.

The well_known_name property follows the libatasmart-style naming - e.g. 'power-on-hours'. Unknown or untrusted attributes are either provided in the form of 'attribute-123' or by NULL.

Similarly, value of an attribute is provided in variety of interpretations, subject to availability:

Both libblockdev plugins strive for best effort of providing accurate values, however there are often challenges ranging from string-to-number conversion, multiple values being unpacked from a single raw number or not having enough context provided by the underlying library for a trusted value interpretation.

Attribute validation

It may seem obvious to use numerical attribute ID as an authoritative attribute identifier, however in reality drive vendors tend not to stick with public specifications. Attributes are often reused for vendor-specific values and this differs from model to model even for a single vendor. This is more often the case with SSD drives than traditional HDDs.

Historically it brought confusion and false alarms on user's end and eventually led to some form of quirk database in most projects. Maintaining such database is a lifetime task and the only successful effort is the smartmontools' drivedb.h collection. Quirks are needed for about everything - meaning of a particular attribute (i.e. a 'well-known' name), interpretation of a raw value, all this filtered by drive model string and firmware revision.

However even there not everything is consistent and slight variations in a 'well-known' name can be found. Besides, the attribute naming syntax differs from our chosen libatasmart-style form.

For this reason an internal libblockdev translation table has been introduced to ensure a bit of consistency. The translation table is kept conservative, is by no means complete and may get extended in future libblockdev releases. As a result, some attributes may be reported as 'untrusted' or 'unknown'.

The translation table at this point doesn't handle 'moves' where a different attribute ID has been assigned for otherwise well defined attribute.

An experimental drivedb.h parser is provided for the libatasmart plugin as an additional tier of validation based on actual drive model + firmware match. Being a C header file, the drivedb.h definitions are compiled in the plugin. There's no support for loading external drivedb.h file though. This however only serves for validation. Providing backwards mapping to libatasmart-style of attributes is considered as a TODO.

Device type detection, multipath

There's a big difference in how a drive is accessed. While libatasmart performs only very basic device type detection based on parent subsystem as retrieved from the udev database, smartctl implements logic to determine which protocol to use, supporting variety of passthrough mechanisms and interface bridges. Such detection is not always reliable though, having known issues with dm-multipath for example.

For this case most plugin functions consume the extra argument allowing callers to specify arguments such as --device= for device type override. This is only supported by the smartmontools plugin and ignored by the libatasmart plugin.

As a well kept secret libatasmart has historically supported device type override via the ID_ATA_SMART_ACCESS udev property. There's no public C API for this and libblockdev generally tends to avoid any udev interaction, leaving the burden to callers.

Valid values for this property include:

A common example to override QEMU ATA device type, which often requires legacy IDE protocol:

1

KERNEL=="sd*", ENV{ID_VENDOR}=="ATA", ENV{ID_MODEL}=="QEMU_HARDDISK", ENV{ID_ATA}=="1", ENV{ID_ATA_SMART_ACCESS}="linux-ide"

An example of blacklisting a USB device, in case of errors caused by reading SMART data:

1

ATTRS{idVendor}=="152d", ATTRS{idProduct}=="2329", ENV{ID_ATA_SMART_ACCESS}="none"

bd_smart_check_deps ()

gboolean
bd_smart_check_deps (void);

bd_smart_close ()

void
bd_smart_close (void);

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

bd_smart_init ()

gboolean
bd_smart_init (void);

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

bd_smart_error_quark ()

GQuark
bd_smart_error_quark (void);

[skip]

bd_smart_is_tech_avail ()

gboolean
bd_smart_is_tech_avail (BDSmartTech tech,
                        guint64 mode,
                        GError **error);

bd_smart_ata_get_info ()

BDSmartATA *
bd_smart_ata_get_info (const gchar *device,
                       const BDExtraArg **extra,
                       GError **error);

Retrieve SMART information from the drive.

bd_smart_ata_get_info_from_data ()

BDSmartATA *
bd_smart_ata_get_info_from_data (const guint8 *data,
                                 gsize data_len,
                                 GError **error);

Retrieve SMART information from the supplied data.

bd_smart_ata_copy ()

BDSmartATA *
bd_smart_ata_copy (BDSmartATA *data);

Creates a new copy of data .

[skip]

bd_smart_ata_free ()

void
bd_smart_ata_free (BDSmartATA *data);

Frees data .

[skip]

bd_smart_ata_attribute_copy ()

BDSmartATAAttribute *
bd_smart_ata_attribute_copy (BDSmartATAAttribute *attr);

Creates a new copy of attr .

[skip]

bd_smart_ata_attribute_free ()

void
bd_smart_ata_attribute_free (BDSmartATAAttribute *attr);

Frees attr .

[skip]

bd_smart_scsi_get_info ()

BDSmartSCSI *
bd_smart_scsi_get_info (const gchar *device,
                        const BDExtraArg **extra,
                        GError **error);

Retrieve SMART information from SCSI or SAS-compliant drive.

bd_smart_scsi_free ()

void
bd_smart_scsi_free (BDSmartSCSI *data);

Frees data .

[skip]

bd_smart_scsi_copy ()

BDSmartSCSI *
bd_smart_scsi_copy (BDSmartSCSI *data);

Creates a new copy of data .

[skip]

bd_smart_set_enabled ()

gboolean
bd_smart_set_enabled (const gchar *device,
                      gboolean enabled,
                      const BDExtraArg **extra,
                      GError **error);

Enables or disables SMART functionality on device.

bd_smart_device_self_test ()

gboolean
bd_smart_device_self_test (const gchar *device,
                           BDSmartSelfTestOp operation,
                           const BDExtraArg **extra,
                           GError **error);

Executes or aborts device self-test.

BD_SMART_ERROR

#define             BD_SMART_ERROR

enum BDSmartError

enum BDSmartTech

enum BDSmartTechMode

BD_SMART_TYPE_ATA

#define BD_SMART_TYPE_ATA (bd_smart_ata_get_type ())

BD_SMART_TYPE_ATA_ATTRIBUTE

#define BD_SMART_TYPE_ATA_ATTRIBUTE (bd_smart_ata_attribute_get_type ())

BDSmartATAAttribute

typedef struct {
    guint8 id;
    gchar *name;
    gchar *well_known_name;
    gint value;
    gint worst;
    gint threshold;
    gboolean failed_past;
    gboolean failing_now;
    guint64 value_raw;
    guint16 flags;
    gint64 pretty_value;
    BDSmartATAAttributeUnit pretty_value_unit;
    gchar *pretty_value_string;
} BDSmartATAAttribute;

enum BDSmartATAAttributeUnit

enum BDSmartATAAttributeFlag

enum BDSmartATACapabilities

enum BDSmartATAOfflineDataCollectionCapabilities

enum BDSmartATAOfflineDataCollectionStatus

enum BDSmartATASelfTestStatus

BDSmartATA

typedef struct {
    gboolean smart_supported;
    gboolean smart_enabled;
    gboolean overall_status_passed;
    BDSmartATAOfflineDataCollectionStatus offline_data_collection_status;
    gboolean auto_offline_data_collection_enabled;
    gint offline_data_collection_completion;
    guint offline_data_collection_capabilities;
    BDSmartATASelfTestStatus self_test_status;
    gint self_test_percent_remaining;
    gint self_test_polling_short;
    gint self_test_polling_extended;
    gint self_test_polling_conveyance;
    guint smart_capabilities;
    BDSmartATAAttribute **attributes;
    guint power_on_time;
    guint64 power_cycle_count;
    guint temperature;
} BDSmartATA;

enum BDSmartSCSIInformationalException

enum BDSmartSCSIBackgroundScanStatus

BDSmartSCSI

typedef struct {
    gboolean smart_supported;
    gboolean smart_enabled;
    gboolean overall_status_passed;
    BDSmartSCSIInformationalException scsi_ie;
    guint8 scsi_ie_asc;
    guint8 scsi_ie_ascq;
    gchar *scsi_ie_string;
    BDSmartSCSIBackgroundScanStatus background_scan_status;
    gdouble background_scan_progress;
    guint background_scan_runs;
    guint background_medium_scan_runs;
    guint read_errors_corrected_eccfast;
    guint read_errors_corrected_eccdelayed;
    guint read_errors_corrected_rereads;
    guint read_errors_corrected_total;
    guint read_errors_uncorrected;
    guint64 read_processed_bytes;
    guint write_errors_corrected_eccfast;
    guint write_errors_corrected_eccdelayed;
    guint write_errors_corrected_rewrites;
    guint write_errors_corrected_total;
    guint write_errors_uncorrected;
    guint64 write_processed_bytes;
    guint start_stop_cycle_count;
    guint start_stop_cycle_lifetime;
    guint load_unload_cycle_count;
    guint load_unload_cycle_lifetime;
    guint scsi_grown_defect_list;
    guint power_on_time;
    gboolean temperature_warning_enabled;
    guint temperature;
    guint temperature_drive_trip;
} BDSmartSCSI;

enum BDSmartSelfTestOp