[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2

SCIOTUR (Test Unit Ready) SCSI Adapter Device Driver ioctl Operation

Purpose

Sends a Test Unit Ready command to the selected SCSI device.

Description

The SCIOTUR operation allows the caller to issue a SCSI Test Unit Read (SCIOSTUNIT) command to a selected SCSI adapter. This command is used by system management routines to help configure SCSI devices.

The sc_ready structure allows the caller to specify the SCSI and the logical unit number (LUN) ID of the device on the SCSI adapter that is to receive the SCIOTUR operation. The SC_ASYNC flag (in the flag byte of the arg parameter block) must not be set during the initial attempt of this command. The sc_ready structure provides two output fields: status_validity and scsi_status . Using these two fields, the SCIOTUR operation returns the status to the caller. The arg parameter for the SCIOTUR operation specifies the address of the sc_ready structure, defined in the /usr/include/sys/scsi.h file.

When an errno value of EIO is received, the caller should evaluate the returned status in the status_validity and scsi_status fields. The status_validity field is set to the value SC_SCSI_ERROR to indicate that the scsi_status field has a valid SCSI bus status in it. The /usr/include/sys/scsi.h file contains typical values for the scsi_status field.

Following an SCIOSTUNIT operation, a calling program can tell by the SCSI bus status whether the device is ready. If an errno value of EIO is returned and the status_validity field is set to 0, an unrecovered error has occurred. If, on retry, the same result is obtained, the device should be skipped. If the status_validity field is set to SC_SCSI_ERROR and the scsi_status field indicates a Check Condition status, then another SCIOTUR command should be sent after a delay of several seconds.

After one or more attempts, the SCIOTUR operation should return a successful completion, indicating that the device was successfully started. If, after several seconds, the SCIOTUR operation still returns a scsi_status field set to a Check Condition status, the device should be skipped.

Note: The SCSI adapter device driver performs normal error-recovery procedures during execution of this command.

Return Values

When completed successfully, this operation returns a value of 0. For the SCIOTUR operation, this means the target device has been successfully started and is ready for data access. If unsuccessful, this operation returns a value of -1 and the errno global variable is set to one of the following values:

EFAULT Indicates that a bad copy between kernel and user space occurred.
EINVAL Indicates the SCIOSTART operation was not issued prior to this command.
EIO Indicates the adapter device driver was unable to complete the command due to an unrecoverable I/O error. If EIO is received, the caller should retry this command at least once, as the first command may have cleared an error condition with the device. Following an unrecovered I/O error, the adapter error status information is logged in the system error log.
ENOCONNECT Indicates a bus fault has occurred. The caller should retry after setting the SC_ASYNC flag in the flag byte of the passed parameters. If more than one retry is attempted, only the last retry should be made with the SC_ASYNC flag set. In general, the SCSI adapter device driver cannot determine which device caused the SCSI bus fault, so this error is not logged.
ENODEV Indicates no SCSI controller responded to the requested SCSI ID. This condition is not necessarily an error and is not logged.
ENOMEM Indicates insufficient memory is available to complete the command.
ETIMEDOUT Indicates the adapter did not respond with a status before the internal command time-out value expired. If this return value is received, the caller should retry this command at least once, as the first command may have cleared an error condition with the device. This error is logged in the system error log.

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/vscsim 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 rmt SCSI device driver, scdisk SCSI device driver, SCSI Adapter device driver.

[ Previous | Next | Contents | Home | Search ]