Technical Reference: Kernel and Subsystems, Volume 2

idedisk IDE Device Driver

Purpose

Supports the Integrated Device Electronics (IDE) fixed disk devices.

Syntax

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

Device-Dependent Subroutines

Typical fixed disk operations are implemented using the open, close, read, write, and ioctl subroutines.

open and close Subroutines

The standard open and close operations are supported by the idedisk device driver. The openx operation is not supported.

readx and writex Subroutines

The readx and writex subroutines provide additional parameters affecting the raw data transfer. These subroutines pass the ext parameter, which specifies request options. The options are constructed by logically ORing zero or more of the following values:

WRITEV

Indicates a request for write verification.

ioctl Subroutine

ioctl subroutine operations that are used for the idedisk device driver are:

Operation	Description
IOCINFO	Returns the devinfo structure defined in the /usr/include/sys/devinfo.h file. The IOCINFO operation is the only operation defined for all device drivers that use the ioctl subroutine. The remaining operations discussed in this article are all specific to IDE fixed disk devices.
DKFORMAT	The IDE disk device driver does not support low level formatting of an IDE disk. IDE disks are preformatted at the factory and should not be reformatted. Attempting to format an IDE disk will result in a -1 return code and errno set to EINVAL.

Device Requirements

IDE fixed disks must support the following ATA commands. The commands' hexadecimal opcodes are specified in the parenthesis:

Identify Device (EC)
Set Features (EF)
Initialize Drive Parameters (91)
Read Sector(s) without retry (21)
Read Sector(s) with retry (20)
Write Sector(s) with retry (30)
Read DMA with retry (C8)
Write DMA with retry (CA)
Read Verify with retry (40)
Idle Immediate (95)
Standby Immediate (94)

Error Conditions

Possible errno values for ioctl, open, read, and write subroutines when using the idedisk device driver include:

Value	Description
EFAULT	Indicates an illegal user address.
EINVAL	Indicates one of the following circumstances: The read or write subroutine supplied an nbyte parameter that is not an even multiple of the block size. An unsupported ioctl subroutine operation was attempted. An attempt was made to configure a device that is still open. An illegal configuration command was requested. The data buffer length exceeded the maximum defined for a strategy operation. The HWRELOC or UNSAFEREL bits of the writex ext parameter were set.
EIO	Indicates one of the following circumstances: The target device cannot be located or is not responding. The target device has indicated an unrecovered hardware error.
ENFILE	Indicates the system file table was full.
ENODEV	The specified fixed disk was not configured or does not exist.
ENXIO	Indicates one of the following circumstances: The specified fixed disk was not opened. The ioctl subroutine supplied an invalid parameter. A read or write operation was attempted beyond the end of the fixed disk.
EPERM	Indicates the attempted subroutine requires appropriate authority.
ETIMEDOUT	Indicates an I/O operation exceeded the given time-out value.
EWRPROTECT	Indicates one of the following circumstances: An open operation requesting read/write mode was attempted on read-only media. A write operation was attempted to read-only media.

Reliability and Serviceability Information

The following classes of errors are reported by the IDE disk device driver:

Class	Description
SOFTWARE ACCESS ERROR	Indicates that the fixed disk was not ready to receive a command or that an unsupported command was requested.
HARDWARE ERROR	Indicates an unrecoverable hardware failure occurred during command execution.
MEDIA ERROR	Indicates an unrecoverable media error was encountered during command execution. This class of error includes bad blocks, missing sector IDs, missing address marks, recalibration failures, and uncorrectable data errors.
RECOVERED ERROR	Indicates the command succeeded due to fixed disk or disk device driver retries.

Error Record Values for Media Errors

The fields defined in the error record template for fixed disk media errors are:

Field	Description
`Comment`	Indicates fixed disk media 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 Perm, which indicates a permanent failure.
`Err_Desc`	Equals a value of 1312, which indicates a disk operation failure.
`Prob_Causes`	Equals the following values: E855, which indicates a disk problem 6330, which indicates a disk drive electronics
`Fail_Causes`	Equals the following values: EA77, which indicates a bad block detected EA78, which indicates an uncorrectable data error EA79, which indicates a requested secotr's id or address mark not found EA7A, which indicates a track 0 not found
`Fail_Actions`	Equals the following values: EC1B, which indicates verify disk's master and slave jumpers are properly set 0301, which indicates check cables ant its connections 0000, which indicates problem-determination procedures should be performed
`Detail_Data`	Equals a value of 72, EC35, HEX. This value indicates hexadecimal format.

Note

The Detail_Data field in the err_rec structure contains the idedisk_error_rec structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The idedisk_error_rec structure is defined in the /usr/include/sys/ide.h file.

The idedisk_error_rec structure contains the following fields:

Field	Description
status_validity	Contains bit flags indicating validity of status and error fields.
b_error	Contains error value from buf structure.
b_flags	Contains flag value from buf structure.
b_addr	Contains buffer address from buf structure.
b_resid	Contains residual byte count from buf structure.
ata	Contains the IDE command that was sent to the IDE device. Also may contain command completion status.

Error Record Values for Physical Volume Software Access

The fields defined in the error record template for fixed disk physical volume software access are:

Field	Description
`Comment`	Indicates fixed disk encountered a physical volume software error.
`Class`	Equals a value of S, which indicates a software 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`	Equal to a value of FALSE, which indicates this error is notIDe alertable.
`Err_Type`	Equals a value of Perm, which indicates a permanent failure.
`Err_Desc`	Equals a value of 210F, which indicates a software error
`Prob_Causes`	Equals the following: EA00, which indicates a software error 6330, which indicates a disk drive electronics failure
`Fail_Causes`	Equals the following values: 109B, which indicates an invalid memory request size EA7B, which indicates an ATA status error
`Fail_Actions`	Equals the following values: EC1B, which indicates verify disk's master and slave jumpers are properly set 0301, which indicates check cables and its connections 0000, which indicates problem-determination procedures should be performed
`Detail_Data`	Equals a value of 72, EC35, HEX. This value indicates hexadecimal format.

Note

The idedisk_error_rec structure contains the following fields:

Field	Description
status_validity	Contains bit flags indicating validity of status and error fields.
b_error	Contains error value from buf structure.
b_flags	Contains flag value from buf structure.
b_addr	Contains buffer address from buf structure.
b_resid	Contains residual byte count from buf structure.
ata	Contains the IDE command that was sent to the IDE device. Also may contain command completion status.

Error Record Values for Physical Volume Hardware Error

The fields defined in the error record template for fixed disk physical volume hardware errors recovered errors are:

Field	Description
`Comment`	Indicates fixed disk physical volume hardware 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`	Equal to 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 1311, which indicates a physical volume operation failure
`Prob_Causes`	Equals a value of 6330, which indicates a disk drive electronics failure
`Fail_Causes`	Equals a value of EA7C, which indicates an invalid media-change status
`Fail_Actions`	Equals the following values: EC1B, which indicates verify disk's master and slave jumpers are properly set 0301, which indicates check cables and its connections 0000, which indicates problem-determination procedures should be performed 1804, which indicates replace device
`Detail_Data`	Equals a value of 72, EC35, HEX. This value indicates hexadecimal format.

Note

The idedisk_error_rec structure contains the following fields:

Field	Description
b_error	Contains error value from buf structure.
b_flags	Contains flag value from buf structure.
b_addr	Contains buffer address from buf structure.
b_resid	Contains residual byte count from buf structure.
ata	Contains the IDE command that was sent to the IDE device. Also may contain command completion status.

Error Record Values for Physical Volume Recovered Error

The fields defined in the error record template for fixed disk physical volume recovered errors are:

Field	Description
`Comment`	Indicates fixed disk physical volume recovered 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`	Equal to a value of FALSE, which indicates this error is not alertable.
`Err_Type`	Equals a value of Temp, which indicates the type of error is temporary.
`Err_Desc`	Equals a value of EC64, which indicates a disk failure recovered during retry.
`Prob_Causes`	Equals the following values: E855, which indicates an adapter failure 6330, which indicates a disk drive electronics failure EA00, which indicates a media failure
`Fail_Causes`	Equals the following values: 5000, which indicates a media failure EA7B, which indicates an IDE command error EA7C, which indicates an invalid media change
`Fail_Actions`	Equals a value of 0700, which indicates no action necessary
`Detail_Data`	Equals a value of 72, EC35, HEX. This value indicates hexadecimal format.

Note

The idedisk_error_rec structure contains the following fields:

Field	Description
b_error	Contains error value from buf structure.
b_flags	Contains flag value from buf structure.
b_addr	Contains buffer address from buf structure.
b_resid	Contains residual byte count from buf structure.
ata	Contains the IDE command that was sent to the IDE device. Also may contain command completion status.

Special Files

The idedisk IDE device driver uses raw and block special files in performing its functions.

Attention: Data corruption, loss of data, or loss of system integrity (system crash) will occur if devices supporting paging, logical volumes, or mounted file systems are accessed using block special files. Block special files are provided for logical volumes and disk devices and are solely for system use in managing file systems, paging devices, and logical volumes. These files should not be used for other purposes.

The special files used to access the idedisk device driver include these fixed disk devices:

Device	Description
/dev/rhdisk0, /dev/rhdisk1,..., /dev/rhdiskn	Provide an interface to allow character access (raw I/O access and control functions) to IDE fixed disks.
/dev/hdisk0, /dev/hdisk1,..., /dev/hdiskn	Provide an interface to allow block I/O access to IDE fixed disks.

Note

The prefix r on a special file name indicates the drive is accessed as a raw device rather than a block device. Performing raw I/O with a fixed disk drive requires that all data transfers be in multiples of the device block size. Also, all lseek subroutines that are made to the raw device driver must result in a file pointer value that is a multiple of the device block size.

Related Information

Special Files Overview in AIX 5L Version 5.2 Files Reference.

IDE Subsystem Overview in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.

A Typical IDE Driver Transaction Sequence in BkSym.PrgDevDrv;.

Required IDE Adapter Device Driver ioctl Commands in BkSym.PrgDevDrv;.

Understanding the Execution of Initiator I/O Requests in BkSym.PrgDevDrv;.

IDE Error Recovery in BkSym.PrgDevDrv;.

ataide_buf Structure in BkSym.PrgDevDrv;.

IDE Adapter Device Driver.

The close subroutine, ioctl or ioctlx subroutine, open, openx, create subroutine, read, readx, readv, or readvx subroutine, write, writex, writev, or writevx subroutine.

rhdisk Special File.