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:

Item Description
WRITEV Indicates a request for write verification.

ioctl Subroutine

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

Operation Description
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.
IDEPASSTHRU Issues any ATAPI command to the specified device when the device has been successfully opened. The IDEPASSTHRU operation does not require an openx command with the ext argument of SC_DIAGNOSTIC. Because of this, an IDEPASSTHRU operation can be issued to devices that are in use by other operations.

The ATA status bytes and the ATA error bytes are returned through the arg parameter, which contains the address of an ide_ata_passthru structure (defined in the /usr/include/sys/ide.h file). If the IDEPASSTHRU operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. If this happens, the caller evaluates the returned status bytes to determine why the operation was unsuccessful and what recovery actions should be taken.

The device driver will perform limited error recovery if the IDEPASSTHRU operation fails. If this operation fails because a field in the ide_ata_passthru structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL.

On completion of the IDEPASSTHRU ioctl request, the residual field indicates the leftover data that the device does not fully satisfy this request. On a successful completion, the residual field indicates that the device does not have all of the data that is requested, or the device has less than the amount of data that is requested. On a failure completion, the residual field indicates the number bytes that the device failed to complete for this request.
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.

Device Requirements

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

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 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 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 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
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 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
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.