Supports the Fibre Channel Protocol for SCSI (FCP) for sequential access bulk storage medium device driver.
#include <sys/devinfo.h>
#include <sys/scsi.h>
#include <sys/tape.h>
#include <sys/pcm.h>
#include <sys/mpio.h>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 open subroutine applies a reservation policy based on the ODM reserve_policy attribute.
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:
| Item | Description |
|---|---|
| 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 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 (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. |
FCP Options to the openx Subroutine in AIX® Version 7.1 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.
The following ioctl operations are only available for MPIO capable FC tape devices:
| Item | Description |
|---|---|
| STPATHIOCMD | The STPATHIOCMD command will take as input a pointer argument which points to a single sctape_pathiocmd structure. The STPATHIOCMD command will behave exactly like the STIOCMD command, except that the input path is used rather than normal path selection performed by the PCM. The STPATHIOCMD path is used for the STIOCMD command regardless of any path specified by a STPATHFORCE ioctl command. A path cannot be unconfigured while it is being forced. |
| STPATHFORCE | The STPATHFORCE command takes as input a ushort path ID. The path ID should correspond to one of the path IDs in the CuPath ODM. The path ID specifies a path to be used for all subsequent I/O commands, overriding any previous STPATHFORCE paths. A zero (0) argument specifies that path forcing is terminated and that normal MPIO path selection is to be resumed. The PCM KE keeps track of the forcing of I/O on a path. The Device Driver is unaware of this state. I/O commands sent in with STPATHIOCMD will override the STPATHFORCE option and send the I/O down the path specified in the st_pathiocmd structure. |
| STPATHPASSTHRU | The STPATHPASSTHRU command takes as input a pointer argument that points to a single sctape_pathiocmd structure. The STPATHPASSTHRU command will behave exactly like STIOCMD, except that the input path is used rather than normal path selection. |
| STPCMPASSTHRU | The STPCMPASSTHRU command takes as input a structure that is PCM-specific; it is not defined by AIX. The PCM-specific structure is passed to the PCM directly. This structure can be used to move information to or from a PCM. |
In addition to those errors listed, ioctl, open, read, and write subroutines against this device are unsuccessful in the following circumstances:
| Item | Description |
|---|---|
| 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 tape drive has been reset or that the tape has been changed. This error is returned on open if the previous operation to tape left the tape positioned beyond the beginning of the tape upon closing. |
| 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 an open operation was attempted for an adapter that already has the maximum permissible number of opened 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. |
Errors returned from tape devices are as follows:
| Item | Description |
|---|---|
| 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 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. This condition may be caused by a tape flaw or a dirty head. |
| NOT READY | Indicates the logical unit is offline. |
| 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. |
Medium, hardware, and aborted command errors from the preceding list are to be logged every time they occur. The ABORTED COMMAND error might 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.
Error Record Values for Tape Device Media Errors
The fields defined in the error record template for tape-device media errors are:
| Item | Description |
|---|---|
| Comment | Equal to tape media error. |
| Class | Equal to H, indicating 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 1332, which indicates a tape operation failure. |
| Prob_Causes | Equals a value of 5003, which indicates tape media. |
| User_Causes | Equals a value of 5100 and 7401, which indicates a cause originating with the tape and defective media, respectively. |
| User_Actions | Equal to 1601 and 0000, which indicates, 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, which indicates tape media. |
| Fail_Actions | Equal to 1601 and 0000, which indicates, 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.
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:
| Item | Description |
|---|---|
| Comment | Equal to a tape hardware or aborted command 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 1331, which indicates a tape drive failure. |
| Prob_Causes | Equals a value of 6314, which indicates 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.
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:
| Item | Description |
|---|---|
| Comment | Indicates the tape-recovered error threshold has been exceeded. |
| 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 1331, which indicates a tape drive failure. |
| Prob_Causes | Equal to 6314, which indicates the probable cause is the tape drive. |
| User_Causes | Equal to 5100 and 7401, which indicates that the media is defective and the read/write head is dirty, respectively. |
| User_Actions | Equal to 1601 and 0000, which indicates 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, which indicates the cause is the tape and tape drive, respectively. |
| Fail_Actions | Equals a value of 0000, which indicates 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. 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.
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:
| Item | Description |
|---|---|
| Comment | Equal to a tape FC adapter-detected 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 1331, which indicates a tape drive failure. |
| Prob_Causes | Equals values of 3300 and 6314, which indicates an adapter and tape drive failure, respectively. |
| User_Causes | None. |
| User_Actions | Equals a value of 0000, which indicates that problem determination procedures should be performed. |
| Inst_Causes | None. |
| Inst_Actions | None. |
| Fail_Causes | Equals values of 3300 and 6314, which indicates an adapter and tape drive failure, respectively. |
| Fail_Actions | Equals a value of 0000, which indicates problem-determination procedures should be performed. |
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.
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.
| Item | Description |
|---|---|
| Comment | Indicates that the tape drive needs cleaning. |
| 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 1332, which indicates a tape operation error. |
| Prob_Causes | Equals a value of 6314, which indicates that the probable cause is the tape drive. |
| User_Causes | Equal to 7401, which indicates a dirty read/write head. |
| User_Actions | Equals a value of 0000, which indicates that problem determination procedures should be performed. |
| Inst_Causes | None. |
| Inst_Actions | None. |
| Fail_Causes | Equals a value of 6314, which indicates that the cause is the tape drive. |
| Fail_Actions | Equals a value of 0000, which indicates problem-determination procedures should be performed. |
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.
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:
| Item | Description |
|---|---|
| Comment | Equal to a tape unknown error. |
| Class | Equal to all error classes. |
| 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 0xFE00, which indicates the error description is unknown. |
| Prob_Causes | Equals the following values:
|
| User_Causes | None. |
| User_Actions | None. |
| Inst_Causes | None. |
| Inst_Actions | None. |
| Fail_Causes | Equals a value of 0xFFFF, which indicates the failure causes are unknown. |
| Fail_Actions | Equals 0000, which indicates 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 Fibre Channel (FC) Specification for the applicable device for the format of the particular request-sense information.