[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Kernel and Subsystems Technical Reference, Volume 2

SCSI Adapter Device Driver

Purpose

Supports the SCSI adapter.

Syntax


<#include /usr/include/sys/scsi.h>
<#include /usr/include/sys/devinfo.h>

Description

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.

Device-Dependent Subroutines

The SCSI adapter device driver supports only the open, close, and ioctl subroutines. The read and write subroutines are not supported.

open and close Subroutines

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.

ioctl Subroutine

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:

SCSI ioctl Operations for Adapters in Non-Diagnostic mode

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.
SCSI ioctl Operations for Adapters in Diagnostic Mode

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.

Summary of SCSI Error Conditions

Possible errno values for the adapter device driver are:

EACCES Indicates that an openx subroutine was attempted while the adapter had one or more devices in use.
EACCES Indicates that a subroutine other than ioctl or close was attempted while the adapter was in Diagnostic mode.
EACCES Indicates that a call to the SCIODIAG command was attempted while the adapter was not in Diagnostic mode.
EBUSY Indicates that a delete operation was unsuccessful. The adapter is still open.
EFAULT Indicates that the adapter is registering a diagnostic error in response to the SCIODIAG command. The SCIODIAG resume option must be issued to continue processing.
EFAULT Indicates that a severe I/O error has occurred during an SCIODNLD command. Discontinue operations to this card.
EFAULT Indicates that a copy between kernel and user space failed.
EINVAL Indicates an invalid parameter or that the device has not been opened.
EIO Indicates an invalid command. A SCIOSTART operation must be executed prior to this command, or an invalid SCSI ID and LUN combination must be passed in.
EIO Indicates that the command has failed due to an error detected on the adapter or the SCSI bus.
EIO Indicates that the device driver was unable to pin code.
EIO Indicates that a kernel service failed, or that an unrecoverable I/O error occurred.
ENOCONNECT Indicates that a SCSI bus fault occurred.
ENODEV Indicates that the target device cannot be selected or is not responding.
ENOMEM Indicates that the command could not be completed due to an insufficient amount of memory.
ENXIO Indicates that the requested ioctl is not supported by this adapter.
EPERM Indicates that the caller did not have the required authority.
ETIMEDOUT Indicates that a SCSI command or adapter command has exceeded the time-out value.

Reliability and Serviceability Information

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.

Error-Record Values for Permanent Hardware Errors

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:

SCSI_ERR1:

Comment Permanent 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 PERM, indicating a permanent failure.
Err_Desc 0x1010, indicating an adapter error.
Prob_Causes The following:
0x3330 Adapter hardware
0x3400 Cable
0x3461 Cable terminator
0x6000 Device
Fail_Causes The following:
0x3300 Adapter
0x3400 Cable loose or defective
0x6000 Device
Fail_Actions The following:
0x000 Perform problem determination procedures.
0x0301 Check the cable and its connections.
Detail_Data1 108, 11, and HEX

Error-Record Values for Temporary Hardware Errors

The error record template for temporary hardware errors detected by the SCSI adapter device driver follows:

SCSI_ERR2:

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
0x6000 Device
Fail_Causes The following:
0x3300 Adapter
0x3400 Cable loose or defective
0x6000 Device
Fail_Actions The following:
0x000 Perform problem-determination procedures.
0x0301 Check the cable and its connections.
Detail_Data1 108, 11, and HEX

Error-Record Values for Permanent Unknown Adapter Microcode Errors

The error-record template for permanent unknown SCSI adapter microcode errors detected by the SCSI adapter device driver follows:

SCSI_ERR3:

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.
0x3301 If the problem persists (0x3000) contact the appropriate service representatives.
Detail_Data1 108, 11 and HEX

Error-Record Values for Temporary Unknown Adapter Microcode Errors

The error-record template for temporary unknown SCSI adapter microcode errors detected by the SCSI adapter device driver follows:

SCSI_ERR4:

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.
0x3301 If the problem persists then (0x3000) contact the appropriate service representatives.
Detail_Data1 108, 11, and HEX

Error-Record Values for Permanent Unknown Adapter Device Driver Errors

The error-record template for permanent unknown SCSI adapter device driver errors detected by the SCSI adapter device driver follows:

SCSI_ERR5:

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

Error-Record Values for Temporary Unknown Adapter Device Driver Errors

The error-record template for temporary unknown SCSI adapter device driver errors detected by the SCSI adapter device driver follows:

SCSI_ERR6:

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

Error-Record Values for Permanent Unknown System Errors

The error-record template for permanent unknown system errors detected by the SCSI adapter device driver follows:

SCSI_ERR7:

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

Error-Record Values for Temporary Unknown System Errors

The error-record template for temporary unknown system errors detected by the SCSI adapter device driver follows:

SCSI_ERR8:

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

Error-Record Values for Temporary SCSI Bus Errors

The error-record template for temporary SCSI bus errors by the SCSI adapter device driver follows:

SCSI_ERR10:

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
0x3300 Adapter Hardware
Fail_Causes The following:
0x3400 Cable loose or defective
0x6000 Device
0x3300 Adapter
Fail_Actions The following:
0x000 Perform problem determination procedures.
0x0301 Check the cable and its connections.
Detail_Data 108, 11, and HEX.

Managing Dumps

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.

Files

/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.

Related Information

The scdisk SCSI device driver, rmt SCSI device driver, tmscsi SCSI device driver.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]