Parallel 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:

Run various adapter diagnostic tests.
Download adapter microcode.

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:

The operation returns a devinfo structure. This structure is defined in the /usr/include/sys/devinfo.h file. The device type in this structure is DD_BUS, and the subtype is DS_SCSI. The flags field is not used and is set to 0. Diagnostic mode is not required for this operation.
The devinfo structure includes unique data such as the card SCSI ID and the maximum initiator mode data transfer size allowed (in bytes). A calling SCSI device driver uses this information to learn the maximum transfer size allowed for a device it controls on the SCSI adapter. In this way, the SCSI device driver can control devices across various SCSI adapters, with each device possibly having a different maximum initiator mode transfer size.

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:

Operation	Description
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.

Operation	Description
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:

Value	Description
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 adapter or system hardware errors
Temporary adapter or system hardware errors
Permanent unknown adapter microcode errors
Temporary unknown adapter microcode errors
Permanent unknown adapter device driver errors
Temporary unknown adapter device driver errors
Permanent unknown system errors
Temporary unknown system errors
Temporary SCSI bus errors

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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Field	Description
`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:

Value	Description
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

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