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_CACHE_DISABLE	Overrides the write_caching attribute in the Object Data Manager (ODM) and disables write caching in the drive.
IDE_SINGLE	Places the selected device in the exclusive access mode. Only one process at a time can open a device in the exclusive access mode.
SC_DIAGNOSTIC	Places the selected device in the diagnostic mode. This mode is singularly entrant, that is, only one process at a time can open it. If the bit is set, write caching is disabled irrespective of the write_caching attribute read from ODM. Note: This flag is defined in the sys/scsi.h file.

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.

IDECDROM user modifiable attributes

Attributes	Detail
max_transfer	Indicates the maximum size of transactions, in bytes, that the disk driver will issue to the adapter driver. The adapter driver has its own maximum transfer size that is independent of the disk driver setting. You can also configure the maximum transfer size of the adapter driver based on the adapter attribute that determines DMA resources allocated to it. If the max_transfer value of the disk driver is larger than the maximum transfer size of the adapter driver, the maximum transfer size of the adapter takes precedence. The default value is `256KB(0x40000)`.
prevent_eject	Indicates if a drive's media is locked in the drive while the device is open. When this attribute is set to the `Yes` value, ejection of the media is prevented if the device is open, that is, a file system from the media is mounted. If the device is not open, then media ejection is permitted. This feature is primarily for eliminating the potential of data corruption that can occur if writable media is interchanged while the system is writing to the media. If writable media is used in the drive, you must set this attribute to `Yes`. When you set this attribute to `No`, the media can be removed even if the system is in the process of writing to the media. The default value is `Yes`.
write_caching	Enables or disables write caching feature. During write operations, the drive can use the write cache to store data that is to be written to the medium at a later time. This is called write caching. Setting this attribute to `yes` enables write caching and setting it to `no` disables write caching. The default value is `no`. Enabling the write cache improves overall data throughput as it reduces the access time to a disc's logical block during write operations. Note: Enabling write cache can lead to deferred errors or optical media becoming out of sync with the operating system or an application. If power loses, system crashes, or drive errors occur, while you are performing an action on this drive, then you must repeat the action.

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.

Operation	Description
IDEPASSTHRU	Issues any ATAPI command to the specified device when the device is successfully opened. The IDEPASSTHRU operation does not require an openx command with the ext parameter value set to 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_atapi_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_atapi_passthru structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL. The rsv0 field of the ide_atapi_passthru structure is used as the version field. The rsv0 field of the ide_atapi_passthru structure can be set to the value of IDE_PASSTHRU_VERSION01, and you can provide the following fields:

Field	Description
sense_data_length	Determines the length (in bytes) of the sense data buffer provided by the user.
ense_data	Pointer to buffer where sense data will be transferred. Sense data will only be transferred when a check condition occurs and valid sense data is obtained from the device.

Refer to the Small Computer System Interface (SCSI) for the format of the request-sense data for a particular device.

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.