IDE Adapter Device Driver

Purpose

Supports the Integrated Device Electronics (IDE) adapter.

Syntax

#include </usr/include/sys/ide.h>
#include </usr/include/sys/devinfo.h>

Description

The /dev/iden special files provide interfaces to allow IDE device drivers to access IDE devices. These files manage the adapter resources so that multiple IDE device drivers can access devices on the same IDE adapter simultaneously. IDE adapters are accessed through the special files /dev/ide0, /dev/ide1, and similarly named files.

The /dev/iden special files provide interfaces for access to the IDE adapter. The host adapter is an initiator for access to devices such as disks, tapes, and CD-ROMs.

Device-Dependent Subroutines

The IDE adapter device driver supports only the open, close, and ioctl subroutines. The read and write subroutines are not supported.

open and close Subroutines

Note: The IDE Adapter device driver's open and close subroutines do not support diagnostic open. If such an open is attempted, the subroutine returns a value of -1 and the errno global value is set to EINVAL.

Any kernel process can open the IDE adapter device driver in normal mode. For normal mode the ext parameter is set to 0. However, a non-kernel process must have at least dev_config authority to open the IDE adapter device driver in normal mode. Attempting to execute a normal open subroutine without the proper authority causes the subroutine to return a value of -1, and set the errno global variable to a value of EPERM.

ioctl Subroutine

Along with the IOCINFO operation, the IDE device driver defines specific operations for devices.

The IOCINFO operation is defined for all device drivers that use the ioctl subroutine, as follows:

IDE ioctl Operations for Adapters

The operations are IDE adapter device driver functions, rather than general device driver facilities.

The following IDE operations are for adapters:

Operation Description
IDEIOGTHW Allows the caller to verify IDE adapter device driver support for gathered writes.
IDEIOINQU Provides the means to issue an inquire command to an ATAPI IDE device.
IDEIOIDENT Provides the means to issue an identify device command to an IDE device. An indicator is returned which identifies if the device is an ATA or ATAPI type device.
IDEIOREAD Sends a single block read command to the selected ATA IDE device, this is not supported for ATAPI type devices.
IDEIORESET Allows the caller to force an IDE device to clear all current commands and return to an initial state.
IDEIOSTART Opens a logical path to an IDE target device.
IDEIOSTOP Closes the logical path to an IDE target device.
IDEIOSTUNIT Provides the means to issue an IDE Start Unit command to a selected ATAPI IDE device.
IDEIOTUR Sends a Test Unit Ready command to the selected ATAPI IDE device.

Summary of IDE Error Conditions

Possible errno values for the adapter device driver are:

Value Description
EACCES Indicates that an openx subroutine was attempted while the adapter had one or more devices in use.
EBUSY Indicates that a delete operation was unsuccessful. The adapter is still open.
EFAULT Indicates that a copy between kernel and user space failed.
EINVAL Indicates an invalid parameter or that the device has not been opened.
EIO Indicates an invalid command. A IDEIOSTART operation must be executed prior to this command, or an invalid IDE master or slave was passed in.
EIO Indicates that the command has failed due to an error detected on the adapter or the IDE bus.
EIO Indicates that the device driver was unable to pin code.
EIO Indicates that a kernel service failed, or that an unrecoverable I/O error occurred.
ENOCONNECT Indicates that an IDE bus fault occurred.
ENODEV Indicates that the target device cannot be selected or is not responding.
ENOMEM Indicates that the command could not be completed due to an insufficient amount of memory.
ENXIO Indicates that the requested ioctl is not supported by this adapter.
EPERM Indicates that the caller did not have the required authority.
ETIMEDOUT Indicates that an IDE command has exceeded the time-out value.

Reliability and Serviceability Information

Errors detected by the adapter device driver may be one of the following:

Permanent errors are either errors that cannot be retried or errors not recovered before a prescribed number of retries has been exhausted. Temporary errors are either noncatastrophic errors that cannot be retried or retriable errors that are successfully recovered before a prescribed number of retries has been exhausted.

Error Record Values for Permanent Hardware Errors

The error record template for permanent hardware errors detected by the IDE adapter device driver is described below. Refer to the ataide_rc structure for the actual definition of the detail data. The ataide_rc structure is defined in the /usr/include/sys/ide.h file:

Field Description
Comment Indicates ATA/IDE controller reset failure.
Class Equals a value of H, which indicates a hardware error.
Report Equals a value of TRUE, which indicates this error should be included when an error report is generated.
Log Equals a value of TRUE, which indicates an error log entry should be created when this error occurs.
Alert Equals a value of FALSE, which indicates this error is not alertable.
Err_Type Equals a value of PERM, which indicates a permanent failure.
Err_Desc Equals a value of 0xE98A, which indicates an adapter reset failure.
Prob_Causes The following:
  • 0xE901, which indicates a configuration error
  • 0x3452, which indicates a storage device cable
  • 0x6310, which indicates a DASD device
  • 0xEA01, which indicates an adapter failure
Fail_Causes The following:
  • 0x3400, which indicates a cable loose or defective
  • 0x3303, which indicates a DASD adapter
Fail_Actions The following:
  • 0x0301, which indicates to check the cables and its connections.
  • 0x0000, which indicates to perform a problem determination procedure.
Detail_Data1 Equals a value of 56, EC35, and HEX

The error record template for DMA errors detected by the IDE adapter device driver follows:

Field Description
Comment Indicates IDE DMA transfer error.
Class Equals a value of H, which indicates a hardware error.
Report Equals a value of TRUE, which indicates this error should be included when an error report is generated.
Log Equals a value of TRUE, which indicates an error-log entry should be created when this error occurs.
Alert Equals a value of FALSE, which indicates this error is not alertable.
Err_Type Equals a value of TEMP, which indicates a temporary failure.
Err_Desc Equals a value of 0xEB75, which indicates DMA error.
Prob_Causes The following:
  • 0xE901, which indicates a configuration error
  • 0x3452, which indicates a storage device cable
  • 0x6310, which indicates a DASD device
  • 0xEA01, which indicates an adapter failure
Fail_Causes The following:
  • 0x3400, which indicates a cable loose or defective
  • 0x3303, which indicates a DASD adapter
Fail_Actions The following:
  • 0x0301, which indicates to check the cable and its connections.
  • 0x0000, which indicates to perform problem-determination procedure.
Detail_Data1 Equals a value of 56, EC35, HEX

Error Record Values for Temporary Unknown IDE Device Errors

The error-record template for unknown IDE adapter errors detected by the IDE adapter device driver follows:

Field Description
Comment Indicates IDE Device error
Class Equals a value of H, which indicates a hardware error.
Report Equals a value of TRUE, which indicates this error should be included when an error report is generated.
Log Equals a value of TRUE, which indicates an error log entry should be created when this error occurs.
Alert Equals a value of FALSE, which indicates this error is not alertable.
Err_Type Equals a value of TEMP, which indicates a temporary failure.
Err_Desc Equals a value of 0x1002, which indicates device error.
Prob_Causes The following:
  • 0xE901, which indicates configuration error
  • 0x3452, which indicates storage device cable
  • 0x6310, which indicates DASD device
  • 0xEA03, which indicates adapter error
Fail_Causes The following:
  • 0x3400, which indicates a cable loose or defective
  • 0x3303, which indicates DASD adapter
Fail_Actions The following:
  • 0x0301, which indicates to check the cable and its connections.
  • 0x0000, which indicates to perform problem-determination procedure.
Detail_Data1 Equals a value of 56, EC35, HEX.

Error Record Values for IDE Command Timeout Errors

The error-record template for IDE Command Timeout errors detected by the IDE adapter device driver follows:

Field Description
Comment Indicates IDE Interrupt timeout error.
Class Equals a value of H, which indicates a hardware error.
Report Equals a value of TRUE, which indicates this error should be included when an error report is generated.
Log Equals a value of TRUE, which indicates an error log entry should be created when this error occurs.
Alert Equals a value of FALSE, which indicates this error is not alertable.
Err_Type Equals a value of TEMP, which indicates a temporary failure.
Err_Desc Equals a value of 0xE96B, which indicates interrupt timed out.
Prob_Causes The following:
  • 0xE901, which indicates a configuration error
  • 0x3452, which indicates a storage device cable
  • 0x6310, which indicates a DASD device
  • 0xEA01, which indicates an adapter failure
Fail_Causes The following:
  • 0x3400, which indicates a cable loose or defective
  • 0x3303, which indicates DASD adapter
Fail_Actions The following:
  • 0x0301, which indicates to check the cable and its connections.
  • 0x0000, which indicates to perform problem-determination procedures.
Detail_Data1 Equals a value of 56, EC35, HEX.

Managing Dumps

The IDE adapter device driver is a target for the system dump facility. The DUMPINIT and DUMPSTART options to the dddump entry point support multiple or redundant calls. The DUMPQUERY option returns a minimum transfer size of 0 bytes and a maximum transfer size equal to the maximum transfer size supported by the IDE adapter device driver.

To be processed, calls to the IDE adapter device driver DUMPWRITE option should use the arg parameter as a pointer to the ataide_buf structure. Using this interface, a IDE write command can be run on a previously started (opened) target device. The uiop parameter is ignored by the IDE adapter device driver. Spanned or consolidated commands are not supported using DUMPWRITE.

Note: The various ataide_buf status fields, including the b_error field, are not set at completion of the DUMPWRITE. Error logging is, of necessity, not supported during the dump.

Successful completion of the dddump entry point is indicated by a 0. If unsuccessful, the entry point returns one of the following:

Return Description
EINVAL Indicates that the adapter device driver was passed as a request that was invalid, such as attempting a DUMPSTART option before successfully executing a DUMPINIT option.
EIO Indicates that the adapter device driver was unable to complete the command due to a lack of required resources or an I/O error.
ETIMEDOUT Indicates that the adapter did not respond with status before the passed command time-out value expired.

Special Files

Item Description
/dev/ide0, /dev/ide1,..., /dev/iden Provides an interface to allow IDE device drivers to access IDE devices or adapters.