Technical Reference: Kernel and Subsystems, Volume 2

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:

The operation returns a devinfo structure. This structure is defined in the /usr/include/sys/devinfo.h file. The device type in this structure is DD_BUS, and the subtype is DS_IDE. The flags field is not used and is set to 0.
The devinfo structure includes unique data such as the maximum data transfer size allowed (in bytes). A calling IDE device driver uses this information to learn the maximum transfer size allowed for a device it controls on the IDE adapter. In this way, the IDE device driver can control devices across various IDE adapters, with each device possibly having a different maximum transfer size.

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 adapter or system hardware errors
Temporary DMA error
Temporary unknown adapter device driver errors
Temporary error for command timeout

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

/dev/ide0, /dev/ide1,..., /dev/iden

Provides an interface to allow IDE device drivers to access IDE devices or adapters.

Related Information

idedisk IDE device driver or idecdrom IDE device driver.