<#include /usr/include/sys/scsi.h> <#include /usr/include/sys/devinfo.h>
The /dev/scsin and /dev/vscsin special files provide interfaces to allow SCSI device drivers to access SCSI devices. These files manage the adapter resources so that multiple SCSI device drivers can access devices on the same SCSI adapter simultaneously. The /dev/vscsin special file provides the interface for the SCSI-2 Fast/Wide Adapter/A and SCSI-2 Differential Fast/Wide Adapter/A, while the /dev/scsin special file provides the interface for the other SCSI adapters. SCSI adapters are accessed through the special files /dev/scsi0, /dev/scsi1, .... and /dev/vscsi0, /dev/vscsi1, ....
The /dev/scsin and /dev/vscsin special files provide interfaces for access for both initiator and target mode device instances. The host adapter is an initiator for access to devices such as disks, tapes, and CD-ROMs. The adapter is a target when accessed from devices such as computer systems, or other devices that can act as SCSI initiators.
The SCSI adapter device driver supports only the open, close, and ioctl subroutines. The read and write subroutines are not supported.
The openx subroutine provides an adapter diagnostic capability. The openx subroutine provides an ext parameter. This parameter selects the adapter mode and accepts the SC_DIAGNOSTIC value. This value is defined in the /usr/include/sys/scsi.h file and places the adapter in Diagnostic mode.
Note: Some of the SCSI adapter device driver's open and close subroutines do not support the diagnostic mode ext parameter. (SC_DIAGNOSTIC). If such an open is attempted, the subroutine returns a value of -1 and the errno global value is set to EINVAL. The standalone diagnostic package provides all diagnostic capability.
In Diagnostic mode, only the close subroutine and ioctl operations are accepted. All other valid subroutines to the adapter return a value of -1 and set the errno global variable to a value of EACCES. In Diagnostic mode, the SCSI adapter device driver can accept the following requests:
The openx subroutine requires appropriate authority to run. Attempting to run this subroutine without the proper authority causes the subroutine to return a value of -1, and set the errno global variable value to EPERM. Attempting to open a device already opened for normal operation, or when another openx subroutine is in progress, causes the subroutine to return a value of -1, and set the errno global variable to a value of EACCES.
Any kernel process can open the SCSI adapter device driver in Normal mode. For Normal mode the ext parameter is set to 0. However, a non-kernel process must have at least dev_config authority to open the SCSI adapter device driver in Normal mode. Attempting to execute a normal open subroutine without the proper authority causes the subroutine to return a value of -1, and set the errno global variable to a value of EPERM.
Along with the IOCINFO operation, the SCSI device driver defines specific operations for devices in non-diagnostic and diagnostic mode.
The IOCINFO operation is defined for all device drivers that use the ioctl subroutine, as follows:
The non-diagnostic operations are SCSI adapter device driver functions, rather than general device driver facilities. SCSI adapter device driver ioctl operations require that the adapter device driver is not in diagnostic mode. If these operations are attempted while the adapter is in diagnostic mode, a value of -1 is returned and the errno global variable is set to a value of EACCES.
The following SCSI operations are for adapters in non-diagnostic mode:
SCIODNLD | Provides the means to download microcode to the adapter. The IBM SCSI-2 Fast/Wide Adapter/A device driver does not support this operation. Microcode download for the Fast/Wide adapter is supported in the standalone diagnostics package only. |
SCIOEVENT | Registers the selected SCSI device instance to receive asynchronous event notification. |
SCIOGTHW | Allows the caller to verify SCSI adapter device driver support for gathered writes. |
SCIOHALT | Aborts the current command (if there is one), clears the queue of any pending commands, and places the device queue in a halted state for a particular device. |
SCIOINQU | Provides the means to issue an inquire command to a SCSI device. |
SCIOREAD | Sends a single block read command to the selected SCSI device. |
SCIORESET | Allows the caller to force a SCSI device to release all current reservations, clear all current commands, and return to an initial state. |
SCIOSTART | Opens a logical path to a SCSI target device. The host SCSI adapter acts as an initiator. |
SCIOSTARTTGT | Opens a logical path to a SCSI initiator device. The host SCSI adapter acts as a target. |
SCIOSTOP | Closes the logical path to a SCSI target device, where the SCSI adapter acts as an initiator. |
SCIOSTOPTGT | Closes the logical path to a SCSI initiator device, where the host SCSI adapter was acting as a target. |
SCIOSTUNIT | Provides the means to issue a SCSI Start Unit command to a selected SCSI device. |
SCIOTUR | Sends a Test Unit Ready command to the selected SCSI device. |
The following operations for the ioctl subroutine are allowed only when the adapter has been successfully opened in Diagnostic mode. If these commands are attempted for an adapter not in Diagnostic mode, a value of -1 is returned and the errno global variable is set to a value of EACCES.
SCIODIAG | Provides the means to issue adapter diagnostic commands. |
SCIODNLD | Provides the means to download microcode to the adapter. |
SCIOTRAM | Provides the means to issue various adapter commands to test the card DMA interface and buffer RAM. |
Note: Some of the SCSI adapter device drivers do not support the diagnostic mode ioctl operations.
To allow these operations to be run on multiple SCSI adapter card interfaces, a special return value is defined. A return value of -1 with an errno value of ENXIO indicates that the requested ioctl subroutine is not applicable to the current adapter card. This return value should not be considered an error for commands that require Diagnostic mode for execution.
Possible errno values for the adapter device driver are:
Errors detected by the adapter device driver may be one of the following:
Permanent errors are either errors that cannot be retried or errors not recovered before a prescribed number of retries has been exhausted. Temporary errors are either noncatastrophic errors that cannot be retried or retriable errors that are successfully recovered before a prescribed number of retries has been exhausted.
The error record template for permanent hardware errors detected by the SCSI adapter device driver is described below. Refer to the rc structure for the actual definition of the detail data. The rc structure is defined in the /usr/include/sys/scsi.h file:
The error record template for temporary hardware errors detected by the SCSI adapter device driver follows:
Comment | Temporary SCSI adapter hardware error. | ||
Class | H, indicating a hardware error. | ||
Report | TRUE, indicating this error should be included when an error report is generated. | ||
Log | TRUE, indicating an error-log entry should be created when this error occurs. | ||
Alert | FALSE, indicating this error is not alertable. | ||
Err_Type | TEMP, indicating a temporary failure. | ||
Err_Desc | 0x1010, indicating an adapter error. | ||
Prob_Causes | The following: | ||
0x3330 | Adapter hardware | ||
0x3400 | Cable | ||
0x3461 | Cable terminator
| ||
Fail_Causes | The following: | ||
0x3300 | Adapter | ||
0x3400 | Cable loose or defective
| ||
Fail_Actions | The following: | ||
0x000 | Perform problem-determination procedures.
| ||
Detail_Data1 | 108, 11, and HEX |
The error-record template for permanent unknown SCSI adapter microcode errors detected by the SCSI adapter device driver follows:
Comment | Permanent SCSI adapter software error. | ||
Class | H, indicating a hardware error. | ||
Report | TRUE, indicating this error should be included when an error report is generated. | ||
Log | TRUE, indicating an error log entry should be created when this error occurs. | ||
Alert | FALSE, indicating this error is not alertable. | ||
Err_Type | PERM, indicating a permanent failure. | ||
Err_Desc | 0x6100, indicating an adapter error. | ||
Prob_Causes | 0x3331, indicating an adapter microcode. | ||
Fail_Causes | 0x3300, indicating the adapter. | ||
Fail_Actions | The following: | ||
0x000 | Perform problem determination procedures.
| ||
Detail_Data1 | 108, 11 and HEX |
The error-record template for temporary unknown SCSI adapter microcode errors detected by the SCSI adapter device driver follows:
Comment | Temporary unknown SCSI adapter software error. | ||
Class | H. | ||
Report | TRUE, indicating this error should be included when an error report is generated. | ||
Log | TRUE, indicating an error log entry should be created when this error occurs. | ||
Alert | FALSE, indicating this error is not alertable. | ||
Err_Type | TEMP, indicating a temporary failure. | ||
Err_Desc | Equal to 0x6100, indicating a microcode program error. | ||
Prob_Causes | 3331, indicating adapter microcode. | ||
Fail_Causes | 3300, indicating the adapter. | ||
Fail_Actions | The following: | ||
0x000 | Perform problem determination procedures.
| ||
Detail_Data1 | 108, 11, and HEX |
The error-record template for permanent unknown SCSI adapter device driver errors detected by the SCSI adapter device driver follows:
Comment | Permanent unknown driver error. |
Class | S. |
Report | TRUE, indicating this error should be included when an error report is generated. |
Log | TRUE, indicating an error log entry should be created when this error occurs. |
Alert | FALSE, indicating this error is not alertable. |
Err_Type | PERM, indicating a permanent failure. |
Err_Desc | 0x2100, indicating a software program error. |
Prob_Causes | 0X1000, indicating a software program. |
Fail_Causes | 0X1000, indicating a software program. |
Fail_Actions | 0x3301, indicating that if the problem persists, then (0x3000) contact the appropriate service representatives. |
Detail_Data1 | 108, 11, and HEX |
The error-record template for temporary unknown SCSI adapter device driver errors detected by the SCSI adapter device driver follows:
Comment | Temporary unknown driver error. |
Class | S. |
Report | TRUE, indicating this error should be included when an error report is generated. |
Log | TRUE, indicating an error log entry should be created when this error occurs. |
Alert | FALSE, indicating this error is not alertable. |
Err_Type | TEMP, indicating a temporary failure. |
Err_Desc | 0x2100, indicating a software program error. |
Prob_Causes | 0X1000, indicating a software program. |
Fail_Causes | 0X1000, indicating a software program. |
Fail_Actions | 0x3301, indicating that if the problem persists then (0x3000) contact the appropriate service representatives. |
Detail_Data1 | 108, 11, and HEX |
The error-record template for permanent unknown system errors detected by the SCSI adapter device driver follows:
Comment | Permanent unknown system error. |
Class | H. |
Report | TRUE, indicating this error should be included when an error report is generated. |
Log | TRUE, indicating an error log entry should be created when this error occurs. |
Alert | FALSE, indicating this error is not alertable. |
Err_Type | UNKN, indicating an unknown error. |
Err_Desc | 0xFE00, indicating an undetermined error. |
Prob_Causes | 0X1000, indicating a software program. |
Fail_Causes | 0X1000, indicating a software program. |
Fail_Actions | 0x0000 and 0x3301, indicating that problem-determination procedures should be performed; if the problem persists, then (0x3000) contact the appropriate service representatives. |
Detail_Data1 | 108, 11, and HEX |
The error-record template for temporary unknown system errors detected by the SCSI adapter device driver follows:
Comment | Temporary unknown system error. |
Class | H. |
Report | TRUE, indicating this error should be included when an error report is generated. |
Log | TRUE, indicating an error log entry should be created when this error occurs. |
Alert | FALSE, indicating this error is not alertable. |
Err_Type | UNKN, indicating an unknown error. |
Err_Desc | 0xFE00, indicating an undetermined error. |
Prob_Causes | 0X1000, indicating a software program. |
Fail_Causes | 0X1000, indicating a software program. |
Fail_Actions | 0x0000 and 0x3301, indicating that problem-determination procedures should be performed; if the problem persists, then (0x3000) contact the appropriate service representatives. |
Detail_Data1 | 108, 11, and HEX |
The error-record template for temporary SCSI bus errors by the SCSI adapter device driver follows:
Comment | Temporary SCSI bus error. | ||
Class | H, indicating a hardware error. | ||
Report | True, indicating an error log entry should be created when this error occurs. | ||
Alert | FALSE, indicating this error is not alertable. | ||
Err_Type | TEMP, indicating a termporary failure. | ||
Err_Desc | 0x942, indicating a SCSI bus error. | ||
Prob_Causes | The following: | ||
0x3400 | Cable | ||
0x3461 | Cable terminator | ||
0x6000 | Device
| ||
Fail_Causes | The following: | ||
0x3400 | Cable loose or defective | ||
0x6000 | Device
| ||
Fail_Actions | The following: | ||
0x000 | Perform problem determination procedures.
| ||
Detail_Data | 108, 11, and HEX. |
The SCSI adapter device driver is a target for the system dump facility. The DUMPINIT and DUMPSTART options to the dddump entry point support multiple or redundant calls.
The DUMPQUERY option returns a minimum transfer size of 0 bytes and a maximum transfer size equal to the maximum transfer size supported by the SCSI adapter device driver.
To be processed, calls to the SCSI adapter device driver DUMPWRITE option should use the arg parameter as a pointer to the sc_buf structure. Using this interface, a SCSI write command can be run on a previously started (opened) target device. The uiop parameter is ignored by the SCSI adapter device driver. Spanned, or consolidated, commands are not supported using DUMPWRITE.
Note: The various sc_buf status fields, including the b_error field, are not set at completion of the DUMPWRITE. Error logging is, of necessity, not supported during the dump.
Successful completion of the dddump entry point is indicated by a 0. If unsuccessful, the entry point returns one of the following:
EINVAL | Indicates that the adapter device driver was passed a request that was not valid, such as attempting a DUMPSTART option before successfully executing a DUMPINIT option. |
EIO | Indicates that the adapter device driver was unable to complete the command due to a lack of required resources or due to an I/O error. |
ETIMEDOUT | Indicates that the adapter did not respond with status before the passed command time-out value expired. |
/dev/scsi0, /dev/scsi1,..., /dev/scsin | Provide an interface to allow SCSI device drivers to access SCSI devices or adapters. |
/dev/vscsi0, /dev/vscsi1,..., /dev/vscsin | Provide an interface to allow SCSI-2 Fast/Wide Adapter/A and SCSI-2 Differential Fast/Wide Adapter/A device drivers to access SCSI devices or adapters. |
The scdisk SCSI device driver, rmt SCSI device driver, tmscsi SCSI device driver.