[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]
Kernel and Subsystems Technical Reference, 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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:
| 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.
[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]