ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOATASMARTInterface

Declared In:

Overview

Self-Monitoring, Analysis, and Reporting Technology Interface.

Discussion

See section 6.14 and section 8.54 of T13:1410D ATA/ATAPI-6 for details on Self-Monitoring, Analysis, and Reporting Technology feature set.

Groups

Optional API support

Group members:

GetATAIdentifyData

Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command.

SMARTExecuteOffLineImmediate

Immediately initiates collection of SMART data.

SMARTReadData

Retrieves 512 byte device SMART data structure.

SMARTReadDataThresholds

Retrieves 512 byte device SMART data thresholds structure.

SMARTReadLogAtAddress

Reads the 512-byte log at the specified logOffset in the log.

SMARTReadLogDirectory

Reads the 512-byte log directory.

SMARTValidateReadData

Tests the integrity of the device SMART data structure.

SMARTWriteLogAtAddress

Writes to the 512-byte log at the specified logOffset in the log.

Mandatory API support

Group members:

SMARTEnableDisableAutosave

Toggles SMART Autosave.

SMARTEnableDisableOperations

Toggles SMART Operations.

SMARTReturnStatus

Sees if device has detected a threshold-exceeded condition.

Functions

GetATAIdentifyData: Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command.
SMARTEnableDisableAutosave: Toggles SMART Autosave.
SMARTEnableDisableOperations: Toggles SMART Operations.
SMARTExecuteOffLineImmediate: Immediately initiates collection of SMART data.
SMARTReadData: Retrieves 512 byte device SMART data structure.
SMARTReadDataThresholds: Retrieves 512 byte device SMART data thresholds structure.
SMARTReadLogAtAddress: Reads the 512-byte log at the specified logOffset in the log.
SMARTReadLogDirectory: Reads the 512-byte log directory.
SMARTReturnStatus: Sees if device has detected a threshold-exceeded condition.
SMARTValidateReadData: Tests the integrity of the device SMART data structure.
SMARTWriteLogAtAddress: Writes to the 512-byte log at the specified logOffset in the log.

GetATAIdentifyData

Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command.

IOReturn ( *GetATAIdentifyData ) (
    void *interface, 
    void *buffer, 
    UInt32 inSize, 
    UInt32 *outSize );

Parameters

interface: A valid IOATASMARTInterface**.
buffer: A valid buffer.
inSize: The number of bytes to place in the buffer.
outSize: The number of bytes placed in the buffer. Can be NULL if the information is not required by the caller.

Return Value

Returns an IOReturn result code. If inSize is greater than 512 or less than 1, kIOReturnBadArgument is returned.

Discussion

Reads the 512-byte data provided by the drive in response to the ATA IDENTIFY DEVICE command. See section 8.15 of ATA/ATAPI-6. The data placed in buffer is guaranteed to be in native endian form on return (i.e. it will be byte swapped on big endian platforms, so the caller need not do anything).

SMARTEnableDisableAutosave

Toggles SMART Autosave.

IOReturn ( *SMARTEnableDisableAutosave ) (
    void *interface, 
    Boolean enable );

Parameters

interface: Pointer to an IOATASMARTInterface.
enable: Passing true will ENABLE SMART Autosave, false will DISABLE SMART Autosave.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client.

Discussion

See section 8.54.2 of ATA/ATAPI-6.

SMARTEnableDisableOperations

Toggles SMART Operations.

IOReturn ( *SMARTEnableDisableOperations ) (
    void *interface, 
    Boolean enable );

Parameters

interface: Pointer to an IOATASMARTInterface.
enable: Passing true will ENABLE SMART operations, false will DISABLE SMART operations.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client.

Discussion

See section 8.54.1 and 8.54.3 of ATA/ATAPI-6.

SMARTExecuteOffLineImmediate

Immediately initiates collection of SMART data.

IOReturn ( *SMARTExecuteOffLineImmediate ) (
    void *interface, 
    Boolean extendedTest );

Parameters

interface: Pointer to an IOATASMARTInterface.
extendedTest: Passing true will collect "off-line" extended test, false short test.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client.

Discussion

See section 8.54.4 of ATA/ATAPI-6.

SMARTReadData

Retrieves 512 byte device SMART data structure.

IOReturn ( *SMARTReadData ) (
    void *interface,
    ATASMARTData *data );

Parameters

interface: Pointer to an IOATASMARTInterface.
data: Pointer to an ATASMARTData data structure to hold the device's SMART data.

Discussion

See section 8.54.5 of ATA/ATAPI-6. Will return an appropriate error if command can not be completed.

SMARTReadDataThresholds

Retrieves 512 byte device SMART data thresholds structure.

IOReturn ( *SMARTReadDataThresholds ) (
    void *interface, 
    ATASMARTDataThresholds *dataThresholds );

Parameters

interface: Pointer to an IOATASMARTInterface.
dataThresholds: Pointer to an ATASMARTDataThresholds data structure to hold the device's SMART data thresholds structure.

Discussion

Retrieves 512 byte device SMART data thresholds structure. This command is not defined as part of ATA/ATAPI-6, but is implemented by a large variety of manufacturers. Will return an appropriate error if command can not be completed.

SMARTReadLogAtAddress

Reads the 512-byte log at the specified logOffset in the log.

IOReturn ( *SMARTReadLogAtAddress ) (
    void *interface, 
    UInt32 logOffset, 
    void *buffer, 
    UInt32 size );

Parameters

interface: Pointer to an IOATASMARTInterface.
logOffset: Integer representing the offset in the log at which to begin reading.
buffer: Pointer to the log buffer.
size: Integer representing the size of the log.

Discussion

Reads the 512-byte log at the specified logOffset in the log. See section 8.54.6.4 of ATA/ATAPI-6.

SMARTReadLogDirectory

Reads the 512-byte log directory.

IOReturn ( *SMARTReadLogDirectory ) (
    void *interface, 
    ATASMARTLogDirectory *logData );

Parameters

interface: Pointer to an IOATASMARTInterface.
logData: Pointer to an ATASMARTLogDirectory.

Discussion

The log directory is a directory of all possible SMART logs available from the drive.

SMARTReturnStatus

Sees if device has detected a threshold-exceeded condition.

IOReturn ( *SMARTReturnStatus ) (
    void *interface, 
    Boolean *exceededCondition );

Parameters

interface: Pointer to an IOATASMARTInterface.
exceededCondition: If this is non-zero the device threshold exceeded condition.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService, kIOReturnExclusiveAccess if it is already opened by another client.

Discussion

The caller will poll this function and if exceededCondition is non-zero and we returned kIOReturnSuccess the device threshold exceeded condition. This would prompt the caller to call ATASMARTReadData to get more information. See section 8.54.7 of ATA/ATAPI-6.

SMARTValidateReadData

Tests the integrity of the device SMART data structure.

IOReturn ( *SMARTValidateReadData ) (
    void *interface, 
    const ATASMARTData * data );

Parameters

interface: Pointer to an IOATASMARTInterface.
data: Constant pointer to an ATASMARTData data structure to test.

Discussion

The data structure checksum is the two's complement of the sum of the first 511 bytes in the data structure. The sum of all 512 bytes will be zero when the checksum is correct. See section 8.54.5.8.7 of ATA/ATAPI-6. Will return an error if checksum fails.

SMARTWriteLogAtAddress

Writes to the 512-byte log at the specified logOffset in the log.

IOReturn ( *SMARTWriteLogAtAddress ) (
    void *interface, 
    UInt32 logOffset, 
    const void * buffer, 
    UInt32 size );

Parameters

interface: Pointer to an IOATASMARTInterface.
logOffset: Integer representing the offset in the log at which to begin writing.
buffer: Pointer to the log buffer.
size: Integer representing the size of the data to write.

Discussion

Writes to the 512-byte log at the specified logOffset in the log. See section 8.54.8.4 of ATA/ATAPI-6.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2009-02-23