[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Kernel and Subsystems, Volume 2
idecdrom IDE Device Driver
Purpose
Supports the Integrate Device Electronics (IDE) CD-ROM
devices.
Syntax
#include <sys/devinfo.h>
#include <sys/ide.h>
#include <sys/idecdrom.h>
Device-Dependent Subroutines
Typical CD-ROM drive operations are implemented using
the open, close, read, and ioctl subroutines.
open and close Subroutines
The openx subroutine is intended
primarily for use by the utilities.
The ext parameter passed to
the openx subroutine selects the operation to be used
for the target device. The /usr/include/sys/idecdrom.h file defines possible values for the ext parameter.
The ext parameter can contain
any combination of the following flag values logically ORed together:
| Flag Value |
Description |
|
IDE_SINGLE |
Places the selected device in exclusive access mode. Only one process
at a time can open a device in exclusive access mode. |
A device can be opened in exclusive access mode only
if the device is not currently open. If an attempt is made to open a device
in exclusive access mode and the device is already open, the subroutine returns
a value of -1 and sets the errno global variable to
a value of EBUSY.
ioctl Subroutine
ioctl subroutine operations that
are used for the idecdrom 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 CD-ROM devices. |
|
IDE_CDIORDSE |
Provides a means for issuing a read command
to the device and obtaining the target-device sense data when an error occurs.
If the IDE_CDIORDSE operation returns a value of -1
and the status_validity field has the ATA_ERROR bit set, valid sense data is returned. Otherwise, target sense
data is omitted. |
The IDE_CDIORDSE operation is
provided for diagnostic use. It allows the limited use of the target device
while operating in an active system environment. The arg parameter to the IDE_CDIOROSE operation contains
the address of an sc_rdwrt structure. This structure
is defined in the /usr/include/sys/scsi.h file.
The devinfo structure defines
the maximum transfer size for a read operation. If an attempt is made to transfer
more than the maximum, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. Refer to the ATA Packet Interface for CD-ROMS Specification for the
format of the request-sense data for a particular device.
Note
The IDE_CDIORDSE operation can be substituted
for the DKIORDSE operation when issuing a read command to obtain sense data from a CD-ROM device.
| Operation |
Description |
|
IDE_CDPMR |
Issues an IDE prevent media removal command when the device has been
successfully opened. This command prevents media from being ejected until
the device is closed, powered off and then back on, or until a IDE_CDAMR operation is issued. The arg parameter
for the IDE_CDPMR operation is null. If the IDE_CDPMR operation is successful, the subroutine returns a value of
0. If the IDE_CDPMR operation fails for any reason,
the subroutine returns a value of -1 and sets the errno
global variable to a value of EIO. |
|
IDE_CDAMR |
Issues an allow media removal command when the device has been successfully
opened. As a result media can be ejected using either the drive's eject button
or the IDE_CDEJECT operation. The arg parameter for this ioctl is null. If the IDE_CDAMR operation is successful, the subroutine returns a value of 0. For any
failure of this operation, the subroutine returns a value of -1 and sets the errno global variable to a value of EIO. |
|
IDE_CDEJECT |
Issues an eject media command to the drive when the device has been
successfully opened. The arg parameter for this operation
is null. If the IDE_CDEJECT operation is successful,
the subroutine returns a value of 0. For any failure of this operation, the
subroutine returns a value of -1 and sets the errno
variable to a value of EIO. |
|
IDE_CDAUDIO |
Issues play-audio commands to the specified device and controls the
volume on the device's output ports. Play audio commands include: play audio
MSF (play audio track index is not supported), pause, resume, stop, determine
the number of tracks, and determine the status of a current audio operation.
The IDE_CDAUDIO operation plays audio only through the
CD-ROM drive's output ports. The arg parameter of
this operation is the address of a cd_audio_cmd structure,
which is defined in the /usr/include/sys/scdisk.h file.
Exclusive access mode is required.
If IDE_CDAUDIO
operation is attempted when the device's audio-supported attribute is set
to no, the subroutine returns a value of -1 and sets the errno global variable to a value of EINVAL. If
the IDE_CDAUDIO operation fails, the subroutine returns
a value of -1 and sets the errno global variable to
a nonzero value. In this case, the caller should evaluate the returned status
bytes to determine why the operation failed and what recovery actions should
be taken. |
|
IDE_CDMODE |
Determines or changes the CD-ROM data mode for the specified device.
The CD-ROM data mode specifies what block size and special file are used for
data read across the IDE bus from the device.The IDE_CDMODE operation supports the following CD-ROM data modes:
- CD_ROM Data Mode
1
- 2048-byte block size through both raw (dev/rcd*)
and block special (/dev/cd*) files
- CD_ROM Data Mode
2 Form 1
- 2048-byte block size through both raw (dev/rcd*)
and block special (/dev/cd*) files
- CD_ROM Data Mode
2 Form 2
- 2336-byte block size through the raw (dev/rcd*)
special file only
- CD_DA (Compact Disc
Digital Audio)
- 2352-byte block size through the raw (dev/rcd*)
special file only
The IDE_CDMODE arg parameter contains the address of the mode_form_op structure defined in the /usr/include/sys/scdisk.h file. To have the IDE_CDMODE operation determine
or change the CD-ROM data mode, set the action field of the change_mode_form structure to one of the following values:
- CD_GET_MODE
- Returns the current CD-ROM data mode in the cd_mode_form field of the mode_form_op structure,
when the device has been successfully opened.
- CD_CHG_MODE
- Changes the CD-ROM data mode to the mode specified in the cd_mode_form field of the mode_form_op structure,
when the device has been successfully opened in the exclusive access mode.
|
If a CD-ROM has not been configured for different data
modes, and an attempt is made to change the CD-ROM data mode (by setting the
action field of the change_mode_form structure set to CD_CHG_MODE), the subroutine returns a value of -1 and sets
the errno global variable to a value of EINVAL.
If the IDE_CDMODE operation for CD_CHG_MODE is attempted when the device is not in exclusive
access mode, the subroutine returns a value of -1 and sets the errno global variable to a value of EACCES. For
any other failure of this operation, the subroutine returns a value of -1
and sets the errno global variable to a value of EIO.
Device Requirements
IDE CD-ROM drives have the following hardware requirements:
- IDE CD-ROM drive must support the IDE ATAPI_READ_CD command.
- If a IDE CD-ROM drive uses CD_ROM Data Mode 1, it must support a block size of 2048 bytes per block.
- If an IDE CD-ROM drive uses CD_ROM Data Mode 2 Form 1, it must support a block size of 2048 bytes
per block.
- If an IDE CD-ROM drive uses CD_ROM Data Mode 2 Form 2, it must support a block size of 2336 bytes
per block.
- If an IDE CD-ROM drive uses CD_DA mode, it must support a block size of 2352 bytes per block.
- To control volume using the IDE_CDAUDIO (play-audio) operation, the device must support mode data
page 0xE.
- To use the IDE_CDAUDIO
(play-audio) operation, the device must support the following optional commands:
- read sub-channel
- pause resume
- play audio MSF
- read TOC
Error Conditions
Possible errno values for ioctl, open, read, and write subroutines when using the idecdrom
device driver include:
| Value |
Description |
|
EACCES |
Indicates one of the following circumstances:
- An attempt was made to open a device currently open
exclusive access mode.
- An IDE_CDMODE ioctl subroutine
operation was attempted on a device not in exclusive access mode.
|
|
EBUSY |
An attempt was made to open a session in exclusive access mode on
a device already opened. |
|
EFAULT |
Indicates an illegal user address. |
|
EFORMAT |
Indicates the target device has unformatted media or media in an
incompatible format. |
|
EINPROGRESS |
Indicates a CD-ROM drive has a play-audio operation in progress. |
|
EINVAL |
Indicates one of the following circumstances:
- An IDE_CDAUDIO (play-audio)
operation was attempted for a device that is not configured to use the IDE
play-audio commands.
- The read subroutine supplied an nbyte parameter that is not an even multiple of the block size.
- A sense data buffer length of greater than 255 bytes
is not valid for a IDE_CDIORDSE ioctl subroutine operation.
- The data buffer length exceeded the maximum defined
in the devinfo structure for a IDE_CDIORDSE
ioctl subroutine operation.
- An unsupported ioctl subroutine
operation was attempted.
- An attempt was made to configure a device that is
still open.
- An illegal configuration command has been given.
- An IDE_CDPMR (Prevent Media
Removal), IDE_CDAMR (Allow Media Removal), or IDE_CDEJECT (Eject Media) command was sent to a device that does not
support removable media.
- An IDE_CDEJECT (Eject Media)
command was sent to a device that currently has its media locked in the drive.
- The data buffer length exceeded the maximum defined
for a strategy operation.
|
|
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.
|
|
EMEDIA |
Indicates one of the following circumstances:
- The target device has indicated an unrecovered media
error.
- The media was changed.
|
|
EMFILE |
Indicates an open operation was attempted for
an adapter that already has the maximum permissible number of opened devices. |
|
ENODEV |
Indicates one of the following circumstances:
- An attempt was made to access an undefined device.
- An attempt was made to close an undefined device.
|
|
ENOTREADY |
Indicates no media is in the drive. |
|
ENXIO |
Indicates one of the following circumstances:
- The ioctl subroutine supplied
an invalid parameter.
|
|
EPERM |
Indicates the attempted subroutine requires appropriate authority. |
|
ESTALE |
Indicates a read-only disk was ejected (without first being closed
by the user) and then either reinserted or replaced with a second disk. |
|
ETIMEDOUT |
Indicates an I/O operation has exceeded the
given timer 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
IDE CD-ROM drives return the following errors:
| Error |
Description |
|
ABORTED COMMAND |
Indicates the device ended the command. |
|
GOOD COMPLETION |
Indicates the command completed successfully. |
|
HARDWARE ERROR |
Indicates an unrecoverable hardware failure occurred during command
execution or during a self-test. |
|
ILLEGAL REQUEST |
Indicates an illegal command or command parameter. |
|
MEDIUM ERROR |
Indicates the command ended with an unrecovered media error condition. |
|
NOT READY |
Indicates the logical unit is offline or media is missing. |
|
RECOVERED ERROR |
Indicates the command was successful after some recovery was applied. |
|
UNIT ATTENTION |
Indicates the device has been reset or the power has been turned
on. |
Error Record Values for Media Errors
The fields defined in the error record template for
CD-ROM media errors are:
| Field |
Description |
|
Comment |
Indicates CD-ROM read 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 a value of 5000, which indicates media. |
|
User_Causes |
Equals a value of 5100, which indicates the media is defective. |
|
User_Actions |
Equals the following values:
- 0000, which indicates problem-determination procedures
should be performed
- 1601, which indicates the removable media should be
replaced and retried
|
|
Fail_Causes |
Equals the following values:
- 5000, which indicates a media failure
- 6310, which indicates a disk drive failure
|
|
Fail_Actions |
Equals the following values:
- 0000, which indicates problem-determination procedures
should be performed
- 1601, which indicates the removable media should be
replaced and retried
|
|
Detail_Data |
Equals a value of 156, 11, HEX. This value indicates hexadecimal
format. |
Note
The Detail_Data field in the err_rec structure contains the idecdrom_error_rec structure. The err_rec structure is defined in
the /usr/include/sys/errids.h file. The idecdrom_error_rec structure is defined in the /usr/include/sys/ide.h file.
The idecdrom_error_rec structure
contains the following fields:
| Field |
Description |
|
req_sense_data |
Contains the request-sense information from the particular device
that had the error, if it is valid. |
|
reserved2 |
Contains the segment count, which is the number of megabytes read
from the device at the time the error occurred. |
|
reserved3 |
Contains the number of bytes read since the segment count was last
increased. |
Refer to the ATA Packet Interface for CD-ROMs Specification
for the format of the request-sense data for a particular device.
Error Record Values for Hardware Errors
The fields defined in the error record template for
CD-ROM hardware errors, as well as hard-aborted command errors are:
| Field |
Description |
|
Comment |
Indicates CD-ROM 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 1312, which indicates a disk operation failure. |
|
Prob_Causes |
Equals a value of 6310, which indicates disk drive. |
|
Fail_Causes |
Equals the following values:
- 6310, which indicates a disk drive failure
- 6330, which indicates a disk drive electronics failure
|
|
Fail_Actions |
Equals a value of 0000, which indicates problem-determination procedures
should be performed. |
|
Detail_Data |
Equals a value of 156, 11, HEX. This value indicates hexadecimal
format. |
Note
he Detail_Data field in the err_rec structure contains the idecdrom_error_rec structure. The err_rec structure is defined in
the /usr/include/sys/errids.h file. The idecdrom_error_rec structure is defined in the /usr/include/sys/ide.h file.
The idecdrom_error_rec structure
contains the following fields:
| Field |
Description |
|
req_sense_data |
Contains the request-sense information from the particular device
that had the error, if it is valid. |
|
reserved2 |
Contains the segment count, which is the number of megabytes read
from the device at the time the error occurred. |
|
reserved3 |
Contains the number of bytes read since the segment count was last
increased. |
Refer to the ATA Packet Interface for CD-ROMs Specification
for the format of the request-sense data for a particular device.
Error Record Values for Recovered Errors
The fields defined in the error record template for
CD-ROM media errors recovered errors are:
| Field |
Description |
|
Comment |
Indicates CD-ROM 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 a temporary failure. |
|
Err_Desc |
Equals a value of 1312, which indicates a physical volume operation
failure. |
|
Prob_Causes |
Equals the following values:
- 5000, which indicates a media failure
- 6310, which indicates a disk drive failure
|
|
User_Causes |
Equals a value of 5100, which indicates media is defective. |
|
User_Actions |
Equals the following values:
- 0000, which indicates problem-determination procedures
should be performed
- 1601, which indicates the removable media should be
replaced and retried
|
|
Fail_Causes |
Equals the following values:
- 5000, which indicates a media failure
- 6310, which indicates a disk drive failure
|
|
Fail_Actions |
Equals the following values:
- 0000, which indicates problem-determination procedures
should be performed
- 1601, which indicates the removable media should be
replaced and retried
|
|
Detail_Data |
Equals a value of 156, 11, HEX. This value indicates hexadecimal
format. |
Note
The Detail_Data field in the err_rec structure contains the idecdrom_error_rec structure. The err_rec structure is defined in
the /usr/include/sys/errids.h file. The idecdrom_error_rec structure is defined in the /usr/include/sys/ide.h file.
The idecdrom_error_rec structure
contains the following fields:
| Field |
Description |
|
req_sense_data |
Contains the request-sense information from the particular device
that had the error, if it is valid. |
|
reserved2 |
Contains the segment count, which is the number of megabytes read
from the device at the time the error occurred. |
|
reserved3 |
Contains the number of bytes read since the segment count was last
increased. |
Refer to the ATA Packet Interface for CD-ROMs Specification
for the format of the request-sense data for a particular device.
Error Record Values for Unknown Errors
The fields defined in the error record template for
CD-ROM media errors unknown errors are:
| Field |
Description |
|
Comment |
Indicates CD-ROM unknown 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 |
Equal to a value of FALSE, which indicates this error is not alertable. |
|
Err_Type |
Equals a value of Unkn, which indicates the type of error is unknown. |
|
Err_Desc |
Equals a value of FE00, which indicates an undetermined error. |
|
Prob_Causes |
Equals the following values:
- 3300, which indicates an adapter failure
- 5000, which indicates a media failure
- 6310, which indicates a disk drive failure
|
|
Fail_Causes |
Equals a value of FFFF, which indicates the failure causes are unknown. |
|
Fail_Actions |
Equals the following values:
- 0000, which indicates problem-determination procedures
should be performed
- 1601, which indicates the removable media should be
replaced and retried
|
|
Detail_Data |
Equals a value of 156, 11, HEX. This value indicates hexadecimal
format. |
Note
The Detail_Data field in the err_rec structure contains the idecdrom_error_rec structure. The err_rec structure is defined in the /usr/include/sys/errids.h file. The idecdrom_error_rec structure is defined in the /usr/include/sys/ide.h file.
The idecdrom_error_rec structure
contains the following fields:
| Field |
Description |
|
req_sense_data |
Contains the request-sense information from the particular device
that had the error, if it is valid. |
|
reserved2 |
Contains the segment count, which is the number of megabytes read
from the device at the time the error occurred. |
|
reserved3 |
Contains the number of bytes read since the segment count was last
increased. |
Refer to the ATA Packet Interface for CD-ROMs Specification
for the format of the request-sense data for a particular device.
Special Files
The idecdrom 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 by the idecdrom, device driver
include the following:
| File |
Description |
|
/dev/rcd0, /dev/rcd1,..., /dev/rcdn |
Provide an interface to allow IDE device drivers character access
(raw I/O access and control functions) to IDE CD-ROM disks. |
|
/dev/cd0, /dev/cd1,..., /dev/cdn |
Provide an interface to allow IDE device drivers block I/O access
to IDE CD-ROM disks. |
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 CD-ROM 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
IDE Adapter Device Driver.
Special Files, and cd Special File in AIX 5L Version 5.2 Files Reference.
Integrated Device Electronics
(IDE) Subsystem, A Typical IDE Driver Transaction
Sequence, Required IDE Adapter Device Driver
ioctl Commands, Understanding the Execution of
Initiator I/O Requests, IDE Error Recovery,
and ataide_buf Structure in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
close Subroutine, ioctl, ioctlx, ioctl32, or ioctl32x Subroutine, and open, openx, open64, creat, or creat64 Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 1.
read, readx, readv, readvx, or pread Subroutine, and write, writex, writev, writevx or pwrite
Subroutines in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]