[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Kernel and Subsystems, Volume 2
scdisk SCSI Device Driver
Purpose
Supports the small computer system interface (SCSI) fixed disk, CD-ROM
(compact disk read only memory), and read/write optical (optical memory) devices.
Syntax
#include <sys/devinfo.h>
#include <sys/scsi.h>
#include <sys/scdisk.h>
Device-Dependent Subroutines
Typical fixed disk, CD-ROM, and read/write optical drive operations are
implemented using the open, close, read, write, and ioctl subroutines.
open and close Subroutines
The openx subroutine is intended primarily for use
by diagnostic commands and utilities. Appropriate authority is required for
execution. If an attempt is made to run the open subroutine
without the proper authority, the subroutine returns a value of -1 and sets
the errno global variable to a value of EPERM.
The ext parameter passed to the openx subroutine selects the operation to be used for the target device.
The /usr/include/sys/scsi.h file defines possible values
for the ext parameter.
The ext parameter can contain any combination of
the following flag values logically ORed together:
SC_DIAGNOSTIC |
Places the selected device in Diagnostic mode. This mode is singularly
entrant; that is, only one process at a time can open it. When a device is
in Diagnostic mode, SCSI operations are performed during open or close operations, and error logging is
disabled. In Diagnostic mode, only the close and ioctl subroutine operations are accepted. All other device-supported
subroutines return a value of -1 and set the errno global variable to a value
of EACCES.
A device can be opened in Diagnostic mode
only if the target device is not currently opened. If an attempt is made to
open a device in Diagnostic mode and the target device is already open, the
subroutine returns a value of -1 and sets the errno global variable to a value
of EACCES. |
SC_FORCED_OPEN |
Forces a bus device reset, regardless of whether another initiator
has the device reserved. The SCSI bus device reset is sent to the device before
the open sequence begins. In other respects, the open operation runs normally. |
SC_RETAIN_RESERVATION |
Retains the reservation of the device after a close operation by not issuing the release. This flag prevents other initiators
from using the device unless they break the host machine's reservation. |
SC_NO_RESERVE |
Prevents the reservation of a device during an openx subroutine call to that device. This operation is provided so a device
can be controlled by two processors that synchronize their activity by their
own software means. |
SC_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. If the SC_DIAGNOSTIC flag is specified along with the SC_SINGLE flag, the device is placed in Diagnostic mode. |
SCSI Options
to the openx Subroutine in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts gives more specific
information on the open operations.
readx and writex Subroutines
The readx and writex subroutines provide additional parameters which affect 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:
HWRELOC |
Indicates a request for hardware relocation (safe relocation only) |
UNSAFEREL |
Indicates a request for unsafe hardware relocation |
WRITEV |
Indicates a request for write verification |
ioctl Subroutine
ioctl subroutine operations that are used for the scdisk device driver are specific to the following categories:
- Fixed disk and read/write optical devices only
- CD-ROM devices only
- Fixed disk, CD-ROM, and read/write optical devices
Fixed Disk and Read/Write Optical Devices
The following ioctl operation
is available for fixed disk and read/write optical devices only:
DKIOWRSE |
Provides a means for issuing a write command
to the device and obtaining the target-device sense data when an error occurs.
If the DKIOWRSE operation returns a value of -1 and
the status_validity field is set to a value of sc_valid_sense, valid sense data is returned. Otherwise,
target sense data is omitted.
The DKIOWRSE 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 DKIOWRSE 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 write 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 Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device. |
CD-ROM Devices Only
The following ioctl operation
is available for CD-ROM devices only:
CDIOCMD |
Allows SCSI commands to be issued directly to the attached CD-ROM
device. The CDIOCMD operation preserves binary compatibility
for CD-ROM applications that were compiled on earlier releases of the operating
system. It is recommended that newly written CD-ROM applications use the DKIOCMD operation instead. For the CDIOCMD operation, the device must be opened in Diagnostic mode. The CDIOCMD operation parameter specifies the address of a sc_iocmd structure. This structure is defined in the /usr/include/sys/scsi.h file.
If this operation is attempted on a
device other than CD-ROM, it is interpreted as a DKIORDSE operation. In this case, the arg parameter is
treated as an sc_rdwrt structure.
If the CDIOCMD operation is attempted on a device not
in Diagnostic mode, the subroutine returns a value of -1 and sets the errno
global variable to a value of EACCES. Refer to the Small Computer System Interface (SCSI) Specification for
the format of the request-sense data for a particular device.
Note
Diagnostic mode is required only for the CDIOCMD and DKIOCMD operations. |
Fixed Disk, CD-ROM, and Read/Write Optical Devices
The following ioctl operations
are available for fixed disk, CD-ROM, and read/write optical devices:
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 fixed disk, CD-ROM, and read/write
optical devices. |
DKIORDSE |
Provides a means for issuing a read command
to the device and obtaining the target-device sense data when an error occurs.
If the DKIORDSE operation returns a value of -1 and
the status_validity field is set to a value of sc_valid_sense, valid sense data is returned. Otherwise,
target sense data is omitted.
The DKIORDSE 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 DKIORDSE 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 Small Computer System Interface
(SCSI) Specification for the format of the request-sense data for a
particular device.
Note
The CDIORDSE operation
may be substituted for the DKIORDSE operation when
issuing a read command to and obtaining sense data
from a CD-ROM device. DKIORDSE is the recommended operation. |
DKIOCMD |
When the device has been successfully opened in the Diagnostic mode,
the DKIOCMD operation provides the means for issuing
any SCSI command to the specified device. If the DKIOCMD operation is issued when the device is not in Diagnostic mode, the
subroutine returns a value of -1 and sets the errno global variable to a
value of EACCES. The device driver performs no error
recovery or logging on failures of this operation.
The SCSI status byte
and the adapter status bytes are returned through the arg parameter, which contains the address of a sc_iocmd structure (defined in the /usr/include/sys/scsi.h file). If the DKIOCMD 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 was unsuccessful and what recovery actions should be taken.
The devinfo structure defines
the maximum transfer size for the command. 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 Small Computer System Interface (SCSI) Specification for the format of the request-sense data for a particular device.
Note
Diagnostic mode is required only for the CDIOCMD and DKIOCMD operations. |
DKPMR |
Issues a SCSI 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 back on, or until a DKAMR operation is issued. The arg parameter
for the DKPMR operation is null. If the DKPMR operation is successful, the subroutine returns a value of 0.
If the device is a SCSI fixed disk, the DKPMR operation
fails, and the subroutine returns a value of -1 and sets the errno global
variable to a value of EINVAL. If the DKPMR operation fails for any other reason, the subroutine returns a
value of -1 and sets the errno global variable to a value of EIO. |
DKAMR |
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 DKEJECT operation. The arg parameter for this ioctl is null. If the DKAMR operation
is successful, the subroutine returns a value of 0. If the device is a SCSI
fixed disk, the DKAMR operation fails, and the subroutine
returns a value of -1 and sets the errno global variable to a value of EINVAL. 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. |
DKEJECT |
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 DKEJECT operation is successful, the
subroutine returns a value of 0. If the device is a SCSI fixed disk, the DKEJECT operation fails, and the subroutine returns a value
of -1 and sets the errno global variable to a value of EINVAL. 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. |
DKFORMAT |
Issues a format unit command to the specified device when the device
has been successfully opened.
If the arg parameter
for this operation is null, the format unit sets the format options valid
(FOV) bit to 0 (that is, it uses the drive's default setting). If the arg parameter for the DKFORMAT operation
is not null, the first byte of the defect list header is set to the value
specified in the first byte addressed by the arg parameter.
This allows the creation of applications to format a particular type of read/write
optical media uniquely.
The driver initially tries to set the FmtData
and CmpLst bits to 0. If that fails, the driver tries the remaining three
permutations of these bits. If all four permutations fail, this operation
fails, and the subroutine sets the errno global variable to a value of EIO.
If the DKFORMAT operation
is specified for a fixed disk, the subroutine returns a value of -1 and sets
the errno global variable to a value of EINVAL. If
the DKFORMAT operation 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.
If the media is write-protected, the subroutine returns a value of -1 and
sets the errno global variable to a value of EWRPROTECT. If the format unit exceeds its timeout value, the subroutine returns
a value of -1 and sets the errno global variable to a value of ETIMEDOUT. 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. |
DKAUDIO |
Issues play audio commands to the specified device and controls the
volume on the device's output ports. Play audio commands include: play, pause,
resume, stop, determine the number of tracks, and determine the status of
a current audio operation. The DKAUDIO 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_cmds structure, which is defined in the /usr/include/sys/scdisk.h file. Exclusive Access mode is required.
If DKAUDIO 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 DKAUDIO 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. |
DK_CD_MODE |
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 SCSI bus from the device. The DK_CD_MODE operation supports the following CD-ROM data modes:
- CD-ROM Data Mode 1
- 512-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
- DVD-ROM
- 2048-byte block size through both raw (/dev/rcd*)
and block special (/dev/cd*) files
- DVD-RAM
- 2048-byte block size through both raw (/dev/rcd*)
and block special (/dev/cd*) files
- DVD-RW
- 2048-byte block size through both raw (/dev/rcd*)
and block special (/dev/cd*) files
The DK_CD_MODE arg parameter contains the address of the mode_form_op structure defined in the /usr/include/sys/scdisk.h file. To have the DK_CD_MODE 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 (via mode-select density codes), 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. Attempts to change the CD-ROM mode to any of the DVD modes will
also result in a return value of -1 and the errno global
variable set to EINVAL.
If the DK_CD_MODE 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. |
DK_PASSTHRU |
When the device has been successfully opened, the DK_PASSTHRU operation provides the means for issuing any
SCSI command to the specified device. The device driver will perform limited
error recovery if this operation fails. The DK_PASSTHRU operation
differs from the DKIOCMD operation in that it does not
require an openx command with the ext argument of SC_DIAGNOSTIC. Because of this,
a DK_PASSTHRU operation can be issued to devices that
are in use by other operations.
The SCSI status byte and the adapter status
bytes are returned through the arg parameter, which
contains the address of a sc_passthru structure (defined
in the /usr/include/sys/scsi.h file). If the DK_PASSTHRU operation fails, the subroutine returns a value of -1 and
sets the errno global variable to a nonzero value. If this happens the caller
should evaluate the returned status bytes to determine why the operation was
unsuccessful and what recovery actions should be taken.
If a DK_PASSTHRU operation fails because a field in the sc_passthru structure has an invalid value, the subroutine will return
a value of -1 and set the errno global variable to EINVAL. The einval_arg field will be set to the field
number (starting with 1 for the version field) of the field that had an invalid
value. A value of 0 for the einval_arg field indicates
no additional information on the failure is available.
DK_PASSTHRU operations are further subdivided into requests which quiesce
other I/O prior to issuing the request and requests that do not quiesce I/O.
These subdivisions are based on the devflags field of
the sc_passthru structure. When the devflags field of the sc_passthru structure has
a value of SC_MIX_IO, the DK_PASSTHRU operation will be mixed with other I/O requests. SC_MIX_IO requests that write data to devices are prohibited and will fail. When
this happens -1 is returned, and the errno global variable is set to EINVAL. When the devflags field of the sc_passthru structure has a value of SC_QUIESCE_IO,
all other I/O requests will be quiesced before the DK_PASSTHRU request is issued to the device. If an SC_QUIESCE_IO request has its timeout_value field set to 0,
the DK_PASSTHRU request will be failed with a return
code of -1, the errno global variable will be set to EINVAL, and the einval_arg field will be set to a value
of SC_PASSTHRU_INV_TO (defined in the /usr/include/sys/scsi.h file). If an SC_QUIESCE_IO request
has a nonzero timeout value that is too large for the device, the DK_PASSTHRU request will be failed with a return code of -1, the errno
global variable will be set to EINVAL, the einval_arg field will be set to a value of SC_PASSTHRU_INV_TO (defined in the /usr/include/sys/scsi.h file),
and the timeout_value will be set to the largest allowed
value.
The devinfo structure defines the maximum
transfer size for the command. If an attempt is made to transfer more than
the maximum transfer size, the subroutine returns a value of -1, sets the
errno global variable to a value of EINVAL, and sets
the einval_arg field to a value of SC_PASSTHRU_INV_D_LEN (defined in the /usr/include/sys/scsi.h file).
Refer to the Small Computer System Interface
(SCSI) Specification for the format of the request-sense data for a particular
device. |
DK_RWBUFFER |
When the device has been successfully opened, the DK_RWBUFFER operation provides the means for issuing one or more SCSI
Write Buffer commands to the specified device. The device driver will perform
full error recovery upon failures of this operation. The DK_RWBUFFER operation differs from the DKIOCMD operation
in that it does not require an exclusive open of the device (for example, openx with the ext argument of SC_DIAGNOSTIC). Thus, a DK_RWBUFFER operation
can be issued to devices that are in use by others. It can be used in conjunction
with the DK_PASSTHRU ioctl, which (like DK_RWBUFFER) does not require an exclusive open of the device.
The arg parameter contains the address of a sc_rwbuffer structure (defined in the /usr/include/sys/scsi.h file). Before the DK_RWBUFFER ioctl is invoked,
the fields of this structure should be set according to the desired behavior.
The mode field corresponds to the mode field of the SCSI Command Descriptor Block (CDB) as defined in the SCSI Primary Commands (SPC) Specification. Supported modes
are listed in the header file /usr/include/sys/scsi.h.
The device driver will quiesce all other I/O from the initiator issuing
the Write Buffer ioctl until the entire operation completes. Once the Write
Buffer ioctl completes, all quiesced I/O will be resumed.
The SCSI status
byte and the adapter status bytes are returned through the arg parameter, which contains the address of a sc_rwbuffer structure (defined in the /usr/include/sys/scsi.h file).
If the DK_RWBUFFER 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 was unsuccessful and what recovery actions
should be taken.
If a DK_RWBUFFER operation fails
because a field in the sc_rwbuffer structure has an
invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL.
The DK_RWBUFFER ioctl allows the user to issue multiple SCSI
Write Buffer commands (CDBs) to the device through a single ioctl invocation.
This is useful for applications such as microcode download where the user
provides a pointer to the entire microcode image, but, due to size restrictions
of the device buffer(s), desires that the images be sent in fragments until
the entire download is complete.
If the DK_RWBUFFER ioctl is invoked with the fragment_size member
of the sc_rwbuffer struct equal to data_length, a single Write Buffer command will be issued to the device
with the buffer_offset and buffer_ID of the SCSI CDB set to the values provided in the sc_rwbuffer struct.
If data_length is greater
than fragment_size and fragment_size is a nonzero value, multiple Write Buffer commands will be issued to
the device. The number of Write Buffer commands (SCSI CDBs) issued will be
calculated by dividing the data_length by the desired fragment_size. This value will be incremented by 1 if the data_length is not an even multiple of fragment_size, and the final data transfer will be the size of this residual
amount. For each Write Buffer command issued, the buffer_offset will be set to the value provided in the sc_rwbuffer struct (microcode downloads to SCSD devices requires this to be set
to 0). For the first command issued, the buffer_ID will
be set to the value provided in the sc_rwbuffer struct.
For each subsequent Write Buffer command issued, the buffer_ID will be incremented by 1 until all fragments have been sent. Writing
to noncontiguous buffer_IDs through a single DK_RWBUFFER ioctl is not supported. If this functionality is desired,
multiple DK_RWBUFFER ioctls must be issued with the buffer_ID set appropriately for each invocation.
Note
No I/O is quiesced between ioctl invocations.
If fragment_size is set to zero, an errno of EINVAL will be returned. If the desire is to
send the entire buffer with one SCSI Write buffer command, this field should
be set equal to data_length. An error of EINVAL will also be returned if the fragment_size is
greater than the data_length.
The Parameter List
Length (fragment_size) plus the Buffer Offset can not
exceed the capacity of the specified buffer of the device. It is the responsibility
of the caller of the Write Buffer ioctl to ensure that the fragment_size setting satisfies this requirement. A fragment_size larger than the device can accommodate will result in a
SCSI error at the device, and the Write Buffer ioctl will simply report this
error but take no action to recover.
The devinfo structure
defines the maximum transfer size for the command. If an attempt is made to
transfer more than the maximum transfer size, the subroutine returns a value
of -1 and sets the errno global variable to a value
of EINVAL. Refer to the Small Computer
System Interface (SCSI) Specification for the format of the request sense
data for a particular device. |
Device Requirements
SCSI fixed disk, CD-ROM, and read/write optical drives
have the following hardware requirements:
- SCSI fixed disks and read/write optical drives must support a block size
of 512 bytes per block.
- If mode sense is supported, the write-protection (WP) bit must also be
supported for SCSI fixed disks and read/write optical drives.
- SCSI fixed disks and read/write optical drives must report the hardware
retry count in bytes 16 and 17 of the request sense data for recovered errors.
If the fixed disk or read/write optical drive does not support this, the
system error log may indicate premature drive failure.
- SCSI CD-ROM and read/write optical drives must support the 10-byte SCSI
read command.
- SCSI fixed disks and read/write optical drives must support the SCSI
write and verify command and the 6-byte SCSI write command.
- To use the format command operation on read/write
optical media, the drive must support setting the format options valid (FOV)
bit to 0 for the defect list header of the SCSI format unit command. If the
drive does not support this, the user can write an application for the drive
so that it formats media using the DKFORMAT operation.
- If a SCSI CD-ROM drive uses CD_ROM Data Mode 1,
it must support a block size of 512 bytes per block.
- If a SCSI CD-ROM drive uses CD_ROM data Mode 2 Form
1, it must support a block size of 2048 bytes per block.
- If a SCSI CD-ROM drive uses CD_ROM data Mode 2 Form
2, it must support a block size of 2336 bytes per block.
- If a SCSI CD-ROM drive uses CD_DA mode, it must
support a block size of 2352 bytes per block.
- To control volume using the DKAUDIO (play audio)
operation, the device must support SCSI-2 mode data page 0xE.
- To use the DKAUDIO (play audio) operation, the
device must support the following SCSI-2 optional commands:
- read sub-channel
- pause resume
- play audio MSF
- play audio track index
- read TOC
Error Conditions
Possible errno values for ioctl, open, read, and write subroutines when using the scdisk device driver include:
EACCES |
Indicates one of the following circumstances:
- An attempt was made to open a device currently open
in Diagnostic or Exclusive Access mode.
- An attempt was made to open a Diagnostic mode session
on a device already open.
- The user attempted a subroutine other than an ioctl or close subroutine while in
Diagnostic mode.
- A DKIOCMD or CDIOCMD operation was attempted on a device not in Diagnostic mode.
- A DK_CD_MODE ioctl subroutine
operation was attempted on a device not in Exclusive Access mode.
- A DKFORMAT operation was attempted
on a device not in Exclusive Access mode.
|
EBUSY |
Indicates one of the following circumstances:
- An attempt was made to open a session in Exclusive
Access mode on a device already opened.
- The target device is reserved by another initiator.
|
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:
- A DKAUDIO (play-audio) operation
was attempted for a device that is not configured to use the SCSI-2 play-audio
commands.
- The read or write 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 CDIORDSE, DKIOWRSE, or DKIORDSE ioctl subroutine
operation.
- The data buffer length exceeded the maximum defined
in the devinfo structure for a CDIORDSE, CDIOCMD, DKIORDSE, DKIOWRSE, or DKIOCMD ioctl subroutine
operation.
- An unsupported ioctl subroutine
operation was attempted.
- A data buffer length greater than that allowed by
the CD-ROM drive is not valid for a CDIOCMD ioctl subroutine
operation.
- An attempt was made to configure a device that is
still open.
- An illegal configuration command has been given.
- A DKPMR (Prevent Media Removal), DKAMR (Allow Media Removal), or DKEJECT (Eject Media) command was sent to a device that does not support removable
media.
- A DKEJECT (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 unrecoverable
hardware error.
|
EMEDIA |
Indicates one of the following circumstances:
- The target device has indicated an unrecoverable
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.
- A read or write operation was attempted beyond the end of the fixed disk.
|
EPERM |
Indicates the attempted subroutine requires appropriate authority. |
ESTALE |
Indicates a read-only optical disk was ejected (without first being
closed by the user) and then either reinserted or replaced with a second
optical 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
SCSI fixed disk devices, CD-ROM drives, and read/write
optical drives return the following errors:
ABORTED COMMAND |
Indicates the device ended the command |
ADAPTER ERRORS |
Indicates the adapter returned an error |
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 unrecoverable 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
fixed disk, CD-ROM, and read/write optical media errors are:
Comment |
Indicates fixed disk, CD-ROM, or read/write optical 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
|
Inst_Causes |
None. |
Inst_Actions |
None. |
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 sc_error_log_df structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.
The sc_error_log_df structure
contains the following fields:
- 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 Small Computer System
Interface (SCSI) 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
fixed disk, CD-ROM, and read/write optical hardware errors, as well as hard-aborted
command errors are:
Comment |
Indicates fixed disk, CD-ROM, or read/write optical 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. |
User_Causes |
None. |
User_Actions |
None. |
Inst_Causes |
None. |
Inst_Actions |
None. |
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:
- The Detail_Data field in the err_rec structure contains the sc_error_log_df structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.
The sc_error_log_df structure
contains the following fields:
- 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 Small Computer System
Interface (SCSI) Specification for the format of the request-sense data
for a particular device.
Error Record Values for Adapter-Detected Hardware Failures
The fields defined in the error record template for
fixed disk, CD-ROM, and read/write optical media errors adapter-detected
hardware errors are:
Comment |
Indicates adapter-detected fixed disk, CD-ROM, or read/write optical
hardware 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 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:
- 3452, which indicates a device cable failure
- 6310, which indicates a disk drive failure
|
User_Causes |
None. |
User_Actions |
None. |
Inst_Causes |
None. |
Inst_Actions |
None. |
Fail_Causes |
Equals the following values:
- 3452, which indicates a storage device cable failure
- 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:
- The Detail_Data field in the err_rec structure contains the sc_error_log_df structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.
The sc_error_log_df structure
contains the following fields:
- 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 Small Computer System
Interface (SCSI) 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
fixed disk, CD-ROM, and read/write optical media errors recovered errors
are:
Comment |
Indicates fixed disk, CD-ROM, or read/write optical 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
|
Inst_Causes |
None. |
Inst_Actions |
None. |
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 sc_error_log_df structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.
The sc_error_log_df structure
contains the following fields:
- 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 Small Computer System
Interface (SCSI) 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
fixed disk, CD-ROM, and read/write optical media errors unknown errors are:
Comment |
Indicates fixed disk, CD-ROM, or read/write optical 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
|
User_Causes |
None. |
User_Actions |
None. |
Inst_Causes |
None. |
Inst_Actions |
None. |
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 sc_error_log_df structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file. The sc_error_log_df structure is defined in the /usr/include/sys/scsi.h file.
The sc_error_log_df structure
contains the following fields:
- 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 Small Computer System
Interface (SCSI) Specification for the format of the request-sense data
for a particular device.
Special Files
The scdisk SCSI 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 scdisk device driver include the following (listed by type of device):
- Fixed disk devices:
/dev/rhdisk0, /dev/rhdisk1,..., /dev/rhdiskn |
Provides an interface to allow SCSI device drivers character access
(raw I/O access and control functions) to SCSI fixed disks. |
/dev/hdisk0, /dev/hdisk1,..., /dev/hdiskn |
Provides an interface to allow SCSI device drivers block I/O access
to SCSI fixed disks. |
- CD-ROM devices:
/dev/rcd0, /dev/rcd1,..., /dev/rcdn |
Provides an interface to allow SCSI device drivers character access(raw
I/O access and control functions) to SCSI CD-ROM disks. |
/dev/cd0, /dev/cd1,..., /dev/cdn |
Provides an interface to allow SCSI device drivers block I/O access
to SCSI CD-ROM disks. |
- Read/write optical devices:
/dev/romd0, /dev/romd1,..., /dev/romdn |
Provides an interface to allow SCSI device drivers character access
(raw I/O access and control functions) to SCSI read/write optical devices. |
/dev/omd0, /dev/omd1,..., /dev/omdn |
Provides an interface to allow SCSI device drivers block I/O access
to SCSI read/write optical devices. |
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, CD-ROM, or read/write optical
drive requires that all data transfers be in multiples of the device block
size. 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.
SCSI Subsystem Overview
in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
A Typical Initiator-Mode SCSI
Driver Transaction Sequence in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
Required SCSI Adapter Device
Driver ioctl Commands in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
Understanding the Execution
of Initiator I/O Requests in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
SCSI Error Recovery in
AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
Understanding the sc_buf Structure in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.
SCSI Adapter Device Driver.
The close subroutine, ioctl or ioctlx subroutine, open, openx,
or creat subroutine, read,
readx, readv, or readvx subroutine, write, writex, writev, or writevx subroutine.
The cd Special
File, omd Special File, rhdisk Special File.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]