[ Previous |
Next |
Contents |
Home |
Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2
rmt SCSI Device Driver
Purpose
Supports the sequential access bulk storage
medium device driver.
Syntax
#include <sys/devinfo.h>
#include <sys/scsi.h>
#include <sys/tape.h>
Note: The /dev/rmt0 through
/dev/rmt255 special files provide access to magnetic tapes. Magnetic tapes are
used primarily for backup, file archives, and other offline storage.
Device-Dependent Subroutines
Most tape operations are implemented using the
open, read, write, and close subroutines. However,
the openx subroutine must
be used if the device is to be opened in Diagnostic mode.
open and close Subroutines
The openx subroutine is intended for use
by the diagnostic commands and utilities. Appropriate authority is required for
execution. Attempting to execute this subroutine without the proper authority causes
the subroutine to return a value of -1 and sets the errno global variable to
EPERM.
The openx subroutine allows the device driver
to enter Diagnostic mode and disables command-retry logic. This action allows for
execution of ioctl operations that perform special functions associated with
diagnostic processing. Other openx capabilities, such as forced opens and
retained reservations, are also available.
The ext parameter passed to the openx
subroutine selects the operation to be used for the target device. The ext parameter is defined in the /usr/include/sys/scsi.h file. This 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. 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 operations are accepted. All other
device-supported subroutines return a value of -1, with the errno global
variable set 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, a value of -1 is returned and
the errno global variable is set to EACCES. |
| SC_FORCED_OPEN |
Forces a bus device reset (BDR) regardless of whether another initiator
has the device reserved. The SCSI bus device reset is sent to the device before
the open sequence begins. Otherwise, the open operation executes
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. |
"SCSI Options to the openx
Subroutine" in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts gives more specific information on the open
operations.
ioctl Subroutine
The STIOCMD ioctl operation provides the
means for sending SCSI commands directly to a tape device. This allows an application
to issue specific SCSI commands that are not directly supported by the tape device
driver.
To use the STIOCMD operation, the device must
be opened in Diagnostic mode. If this command is attempted while the device is not in
Diagnostic mode, a value of -1 is returned and the errno global variable is
set to a value of EACCES. The STIOCMD operation passes the address of a
sc_iocmd structure. This structure is defined in the
/usr/include/sys/scsi.h file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for information on issuing the
parameters.
Error Conditions
In addition to those errors listed, ioctl,
open, read, and write subroutines against this device are
unsuccessful in the following circumstances:
| EACCES |
Indicates that a diagnostic command was issued to a device not in
Diagnostic mode. |
| EAGAIN |
Indicates that an attempt was made to open a device that was already
open. |
| EBUSY |
Indicates that the target device is reserved by another initiator. |
| EINVAL |
Indicates that a value of O_APPEND is supplied as the mode in which
to open. |
| EINVAL |
Indicates that the nbyte parameter supplied by a read or
write operation is not a multiple of the block size. |
| EINVAL |
Indicates that a parameter to an ioctl operation is not valid. |
| EINVAL |
Indicates that the requested ioctl operation is not supported on the
current device. |
| EIO |
Indicates that the device could not space forward or reverse the number of
records specified by the st_count
field before encountering an EOM (end
of media) or a file mark. |
| EMEDIA |
Indicates that the tape device has encountered an unrecoverable media
error. |
| EMFILE |
Indicates that an open operation was attempted for a SCSI adapter
that already has the maximum permissible number of open devices. |
| ENOTREADY |
Indicates that there is no tape in the drive or the drive is not
ready. |
| ENXIO |
Indicates that there was an attempt to write to a tape that is at
EOM. |
| EPERM |
Indicates that this subroutine requires appropriate authority. |
| ETIMEDOUT |
Indicates a command has timed out. |
| EWRPROTECT |
Indicates an open operation requesting read/write mode was
attempted on a read-only tape. |
| EWRPROTECT |
Indicates that an ioctl operation that affects the media was attempted on
a read-only tape. |
Reliability and Serviceability Information
Errors returned from tape devices are as
follows:
| ABORTED COMMAND |
Indicates the device ended the command. |
| BLANK CHECK |
Indicates that a read command encountered a blank tape. |
| DATA PROTECT |
Indicates that a write was attempted on a write-protected tape. |
| GOOD COMPLETION |
Indicates that the command completed successfully. |
| HARDWARE ERROR |
Indicates that 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 that the command terminated with a unrecovered media error
condition. This condition may be caused by a tape flaw or a dirty head. |
| NOT READY |
Indicates that the logical unit is offline. |
| RECOVERED ERROR |
Indicates that the command was successful after some recovery was applied. |
| UNIT ATTENTION |
Indicates the device has been reset or powered on. |
Medium, hardware, and aborted command errors from the
above list are to be logged every time they occur. The ABORTED COMMAND error
may be recoverable, but the error is logged if recovery fails. For the RECOVERED
ERROR and recovered ABORTED COMMAND error types, thresholds are
maintained; when they are exceeded, an error is logged. The thresholds are then
cleared.
Note: There are device-related adapter
errors that are logged every time they occur.
Error Record Values for Tape Device Media Errors
The fields defined in the error record template for
tape-device media errors are:
| Comment |
Equal to tape media error. |
| Class |
Equal to H, indicating a hardware error. |
| Report |
Equal to TRUE, indicating this error should be included when an error
report is generated. |
| Log |
Equal to TRUE, indicating an error log entry should be created when this
error occurs. |
| Alert |
Equal to FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to PERM, indicating a permanent failure. |
| Err_Desc |
Equal to 1332, indicating a tape operation failure. |
| Prob_Causes |
Equal to 5003, indicating tape media. |
| User_Causes |
Equal to 5100 and 7401, indicating a cause originating with the tape and
defective media, respectively. |
| User_Actions |
Equal to 1601 and 0000, indicating respectively that the removable media
should be replaced and the operation retried,and that problem determination
procedures should be performed. |
| Inst_Causes |
None. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 5003, indicating tape media. |
| Fail_Actions |
Equal to 1601 and 0000, indicating respectively that the removable media
should be replaced and the operation retried and that problem determination
procedures should be performed. |
The Detail_Data
field contains the
command type, device and adapter status, and the request-sense information from the
particular device in error. The Detail_Data
field is contained in the
err_rec structure. This structure is defined in the
/usr/include/sys/errids.h file. The sc_error_log_df structure, which
describes information contained in the Detail_Data
field, is defined in
the /usr/include/sys/scsi.h file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Error-Record Values for Tape or Hardware Aborted Command
Errors
The fields in the err_hdr structure, as
defined in the /usr/include/sys/erec.h file for hardware errors and aborted
command errors, are:
| Comment |
Equal to a tape hardware or aborted command error. |
| Class |
Equal to H, indicating a hardware error. |
| Report |
Equal to TRUE, indicating this error should be included when an error
report is generated. |
| Log |
Equal to TRUE, indicating an error log entry should be created when this
error occurs. |
| Alert |
FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to PERM, indicating a permanent failure. |
| Err_Desc |
Equal to 1331, indicating a tape drive failure. |
| Prob_Causes |
Equal to 6314, indicating a tape drive error. |
| User_Causes |
None. |
| User_Actions |
Equal to 0000, indicating that problem determination procedures should be
performed. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 5003 and 6314, indicating the failure cause is the tape and the
tape drive, respectively. |
| Fail_Actions |
Equal to 0000 to perform problem determination procedures. |
The Detail_Data
field contains the
command type, device and adapter status, and the request-sense information from the
particular device in error. The Detail_Data
field is contained in the
err_rec structure. This structure is defined in the
/usr/include/sys/errids.h file. The sc_error_log_df structure, which
describes information contained in the Detail_Data
field, is defined in
the /usr/include/sys/scsi.h file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Error-Record Values for Tape-Recovered Error Threshold
Exceeded
The fields defined in the err_hdr
structure, as defined in the /usr/include/sys/erec.h file for recovered errors
that have exceeded the threshold counter, are:
| Comment |
Indicates the tape-recovered error threshold has been exceeded. |
| Class |
Equal to H, indicating a hardware error. |
| Report |
Equal to TRUE, indicating this error should be included when an error
report is generated. |
| Log |
Equal to TRUE, indicating an error log entry should be created when this
error occurs. |
| Alert |
Equal to FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to PERM, indicating a permanent failure. |
| Err_Desc |
Equal to 1331, indicating a tape drive failure. |
| Prob_Causes |
Equal to 5003 and 6314, indicating the probable cause is the tape and tape
drive, respectively. |
| User_Causes |
Equal to 5100 and 7401, indicating that the media is defective and the
read/write head is dirty, respectively. |
| User_Actions |
Equal to 1601 and 0000, indicating that removable media should be replaced
and the operation retried and that problem-determination procedures should be
performed, respectively. |
| Inst_Causes |
None. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 5003 and 6314, indicating the cause is the tape and tape drive,
respectively. |
| Fail_Actions |
Equal to 0000, to perform problem determination procedures. |
The Detail_Data
field contains the
command type, device and adapter status, and the request-sense information from the
particular device in error. This field is contained in the err_rec structure.
The err_rec structure is defined in the /usr/include/sys/errids.h file.
The Detail_Data
field also specifies the error type of the threshold
exceeded. The sc_error_log_df structure, which describes information contained
in the Detail_Data
field, is defined in the
/usr/include/sys/scsi.h file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Error Record Values for Tape SCSI Adapter-Detected
Errors
The fields in the err_hdr structure, as
defined in the /usr/include/sys/erec.h file for adapter-detected errors, are:
| Comment |
Equal to a tape SCSI adapter-detected error. |
| Class |
Equal to H, indicating a hardware error. |
| Report |
Equal to TRUE, indicating this error should be
included when an error report is generated. |
| Log |
Equal to TRUE, indicating an error
log entry should be created when this error occurs. |
| Alert |
Equal to FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to PERM, indicating a permanent failure. |
| Err_Desc |
Equal to 1331, indicating a tape drive failure. |
| Prob_Causes |
Equal to 3300 and 6314, indicating an adapter and tape drive failure, respectively. |
| User_Causes |
None. |
| User_Actions |
Equal to 0000, indicating that problem
determination procedures should be performed. |
| Inst_Causes |
None. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 3300 and 6314, indicating an adapter and tape drive failure, respectively. |
| Fail_Actions |
Equal to 0000, to perform problem-determination
procedures. |
The Detail_Data
field contains the
command type and adapter status. This field is contained in the err_rec
structure, which is defined by the /usr/include/sys/err_rec.h file.
Request-sense information is not available with this type of error. The
sc_error_log_df structure describes information contained in the
Detail_Data
field and is defined in the /usr/include/sys/scsi.h
file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Error-Record Values for Tape Drive Cleaning Errors
Some tape drives return errors when they need
cleaning. Errors that occur when the drive needs cleaning are grouped under this
class.
| Comment |
Indicates that the tape drive needs cleaning. |
| Class |
Equal to H, indicating a hardware error. |
| Report |
Equal to TRUE, indicating that this error should be included when an error
report is generated. |
| Log |
Equal to TRUE, indicating that an error-log entry should be created when
this error occurs. |
| Alert |
Equal to FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to TEMP, indicating a temporary failure. |
| Err_Desc |
Equal to 1332, indicating a tape operation error. |
| Prob_Causes |
Equal to 6314, indicating that the probable cause is the tape drive. |
| User_Causes |
Equal to 7401, indicating a dirty read/write head. |
| User_Actions |
Equal to 0000, indicating that problem determination procedures should be
performed. |
| Inst_Causes |
None. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 6314, indicating that the cause is the tape drive. |
| Fail_Actions |
Equal to 0000, indicating to perform problem-determination
procedures. |
The Detail_Data
field contains the
command type and adapter status and also the request-sense information from the
particular device in error. This field is contained in the err_rec structure,
which is defined by the /usr/include/sys/errids.h file. The
sc_error_log_df structure describes information contained in the
Detail_Data
field and is defined in the /usr/include/sys/scsi.h file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Error-Record Values for Unknown Errors
Errors that occur for unknown reasons are
grouped in this class. Data-protect errors fall into this class. These errors,
detected by the tape device driver, are never seen at the tape drive.
The err_hdr structure for unknown errors
describes the following fields:
| Comment |
Equal to tape unknown error. |
| Class |
Equal to all error classes. |
| Report |
Equal to TRUE, indicating this error should be included when an error
report is generated. |
| Log |
Equal to TRUE, indicating an error-log entry should be created when this
error occurs. |
| Alert |
Equal to FALSE, indicating this error is not alertable. |
| Err_Type |
Equal to UNKN, indicating the error type is unknown. |
| Err_Desc |
Equal to 0xFE00, indicating the error description is unknown. |
| Prob_Causes |
None. |
| User_Causes |
None. |
| User_Actions |
None. |
| Inst_Causes |
None. |
| Inst_Actions |
None. |
| Fail_Causes |
Equal to 0xFFFF, indicating the failure cause is unknown. |
| Fail_Actions |
Equal to 0000, indicating that problem-determination procedures should be
performed. |
The Detail_Data
field contains the
command type and adapter status, and the request- sense information from the
particular device in error. The Detail_Data
field is contained in the
err_rec structure. This field is contained in the /usr/include/sys/errids.h file. The sc_error_log_df structure describes information contained in the
Detail_Data
field and is defined in the /usr/include/sys/scsi.h
file.
Refer to the Small Computer System Interface
(SCSI) Specification for the applicable device for the format of the particular
request-sense information.
Files
/dev/rmt0, /dev/rmt0.1, /dev/rmt0.2, ...,
/dev/rmt0.7,
/dev/rmt1, /dev/rmt1.1, /dev/rmt1.2, ...,
/dev/rmt1.7,...,
| /dev/rmt255, /dev/rmt255.1,
/dev/rmt255.2, ..., /dev/rmt255.7 |
Provide an interface to allow SCSI device drivers to access SCSI tape drives. |
Related Information
The rhdisk special file, rmt special file.
The close subroutine, ioctl subroutine, open subroutine, openx subroutine, read subroutine, write subroutine.
A Typical Initiator-Mode SCSI
Driver Transaction Sequence in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
Required SCSI Adapter Device
Driver ioctl Commands in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
Understanding the Execution
of Initiator I/O Requests in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
SCSI Error Recovery in
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
Understanding the sc_buf
Structure in AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts.
SCSI Adapter Device
Driver.
[ Previous |
Next |
Contents |
Home |
Search ]