SCIODIAG (Diagnostic) SCSI Adapter Device Driver ioctl Operation

Purpose

Provides the means to issue adapter diagnostic commands.

Description

The SCIODIAG operation allows the caller to issue various adapter diagnostic commands to the selected SCSI adapter. These diagnostic command options are:

An additional option allows the caller to resume the card Internal Diagnostics test from the point of a failure, which is indicated by the return value. The arg parameter for the SCIODIAG operation specifies the address of a sc_card_diag structure. This structure is defined in the /usr/include/sys/scsi.h file.

The actual adapter error-status information from each error reported by the card diagnostics is passed as returned parameters to the caller. Refer to the sc_card_diag structure defined in the /usr/include/sys/scsi.h file for the format of the returned data.

When the card diagnostics have completed (with previous errors), a value of ENOMSG is returned. At this point, no further SCIODIAG resume options are required, as the card internal diagnostics test has completed.

Adapter error status is always returned when a SCIODIAG operation results in an errno value of EFAULT. Because this error information is returned for each such volume, the final ENOMSG value returned for the card Internal Diagnostics test includes no error status information. Also, because this is a diagnostic command, these errors are not logged in the system error log.

Note: The SCSI adapter device driver performs no internal retries or other error-recovery procedures during execution of this operation. Error logging is also inhibited when running this command.

Return Values

When completed successfully, this operation returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to one of the following values:

Value Description
EFAULT Indicates that a bad copy between user and kernel space occurred.
EFAULT For the integrated SCSI adapter on the 7008 and 7011 system models, this return value also indicates that the SCSI adapter device driver detected an error while attempting to run the SCIODIAG operation. In this case, the returned adapter status information must be analyzed to discover the cause of the error. Because this is a diagnostic command, this error is not logged in the system error log.

For all other SCSI adapters, this value indicates that the card internal diagnostics have detected an error and paused. To continue, the caller must issue another SCIODIAG operation with the resume option. In response to this option, the card continues the diagnostics until either the end is reached or another error is detected. The caller must continue to issue SCIODIAG operations until the EFAULT error no longer returns.

EINVAL Indicates a bad input parameter.
EIO Indicates that the SCSI adapter device driver detected an error while attempting to run the SCIODIAG operation. In this case, the returned adapter status information must be analyzed to discover the cause of the error. Because this is a diagnostic command, this error is not logged in the system error log.
ENOMSG Indicates that the card Internal Diagnostics test has completed.
ENXIO Indicates that the operation or suboption selected is not supported on this adapter. This should not be treated as an error. The caller must check for this return value first (before checking for other errno values) to avoid mistaking this for a failing command.
ETIMEDOUT Indicates that the adapter did not respond with status before the passed command time-out value expired. The SCIODIAG operation is a diagnostic command, so its errors are not logged in the system error log.

Files

Item Description
/dev/scsi0, /dev/scsi1,..., /dev/scsin         Provide an interface to allow SCSI device drivers to access SCSI devices/adapters.