SCIOCMD SCSI Adapter Device Driver ioctl Operation

Purpose

Provides a means to issue any SCSI command to a SCSI device.

Description

The SCIOCMD operation allows the caller to issue a SCSI command to a selected adapter. This command can be used by system management routines to aid in the configuration of SCSI devices.

The arg parameter for the SCIOCMD operation is the address of a sc_passthru structure, which is defined in the /usr/include/sys/scsi.h field. The sc_passthru parameter allows the caller to select which SCSI and LUN IDS to send the command.

The SCSI status byte and the adapter status bytes are returned through the sc_passthru structure. If the SCIOCMD operation returns a value of -1 and the errno global variable is set to a nonzero value, the requested operation has failed. If this happens, the caller should evaluate the returned status bytes to determine why the operation failed and what recovery actions should be taken.

If the SCIOCMD operation fails because a field in the sc_passthru structure has an invalid value, the subroutine will return a value of -1, the errno global variable will be set to EINVAL, and the einval_arg field will be set to the field number (starting with 1 for the version field) of the field that had an invalid value. A value of 0 for the einval_arg field indicates no additional information is available.

Note: The following two paragraphs pertain only to AIX 5L™ with 5200-03 and later.

The version field of the sc_passthru structure can be set to the value of SC_VERSION_2 in the /usr/include/sys/scsi.h file, and the user can provide the following fields:

variable_cdb_ptr is a pointer to a buffer that contains the Variable SCSI cdb.
variable_cdb_length determines the length of the cdb variable to which the variable_cdb_ptr field points.

On completion of the SCIOCMD ioctl request, the residual field will indicate the leftover data that device did not fully satify for this request. On a successful completion, the residual field would indicate the device does not have the all data that is requested or the device has less then the amount of data that is requested. On a failure completion, the user needs to check the status_validity field to determine if a valid SCSI bus problem exists. In this case, the residual field would indicate the number bytes that the device failed to complete for this request.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum transfer size, the subroutine returns a value of -1, sets the errno global variable to a value of EINVAL, and sets the einval_arg field to a value of 18.

Refer to the Small Computer System Interface (SCSI) Specification to find out the format of the request-sense data for a particular device.

Return Values

The SCIOCMD operation returns a value of 0 when successfully completed. If unsuccessful, a value of -1 is returned, and the errno global variable is set to one of the following values:

Item	Description
EIO	A system error has occurred. Consider retrying the operation several (three) times, because another attempt may be successful. If an EIO error occurs and the status_validity field is set to SC_SCSI_ERROR, the scsi_status field has a valid value and should be inspected. If the status_validity field is zero and remains so on successive retries, an unrecoverable error has occurred. If the status_validity field is SC_SCSI_ERROR and the scsi_status field contains a Check Condition status, a SCSI request sense should be issued using the SCIOCMD ioctl to recover the sense data.
EFAULT	A user process copy has failed.
EINVAL	The device is not opened, or the caller has set a field in the sc_passthru structure to an invalid value.
EACCES	The adapter is in diagnostics mode.
ENOMEM	A memory request has failed.
ETIMEDOUT	The command has timed out. Consider retrying the operation several times, because another attempt may be successful.
ENODEV	The device is not responding.
ETIMEDOUT	The operation did not complete before the timeout value was exceeded.

Files

Item	Description
/dev/scsi0, /dev/scsi1, ... /dev/scsin	Provides an interface for all SCSI device drivers to access SCSI devices or adapters.