Initiator-Mode ioctl Commands

The following SCIOSTART and SCIOSTOP operations must be sent by the SCSI device driver (for the open and close routines, respectively) for each device. They cause the SCSI adapter device driver to allocate and initialize internal resources.

The SCIOHALT ioctl operation is used to abort pending or running commands, usually after signal processing by the SCSI device driver. This might be used by a SCSI device driver to end an operation instead of waiting for completion or a time out. The SCIORESET operation is provided for clearing device hard errors and competing initiator reservations during open processing by the SCSI device driver. The SCIOGTHW operation is supported by SCSI adapter device drivers that support gathered write commands to target devices.

Except where noted otherwise, the arg parameter for each of the ioctl operations described here must contain a long integer. In this field, the least significant byte is the SCSI LUN and the next least significant byte is the SCSI ID value. (The upper two bytes are reserved and should be set to 0.) This provides the information required to allocate or deallocate resources and perform SCSI bus operations for the ioctl operation requested.

The following information is provided on the various ioctl operations:

SCIOSTART

This operation allocates and initializes SCSI device-dependent information local to the SCSI adapter device driver. Run this operation only on the first open of an ID/LUN device. Subsequent SCIOSTART commands to the same ID/LUN fail unless an intervening SCIOSTOP command is issued.

The following values for the errno global variable are supported:

0

Indicates successful completion.

EIO

Indicates lack of resources or other error-preventing device allocation.

EINVAL

Indicates that the selected SCSI ID and LUN are already in use, or the SCSI ID matches the adapter ID.

ETIMEDOUT

Indicates that the command did not complete.

SCIOSTOP

This operation deallocates resources local to the SCSI adapter device driver for this SCSI device. This should be run on the last close of an ID/LUN device. If an SCIOSTART operation has not been previously issued, this command is unsuccessful.

The following values for the errno global variable should be supported:

0

Indicates successful completion.

EIO

Indicates error preventing device deallocation.

EINVAL

Indicates that the selected SCSI ID and LUN have not been started.

ETIMEDOUT

Indicates that the command did not complete.

SCIOCMD

The SCIOCMD SCSI Adapter Device Driver ioctl Operation provides the means for issuing any SCSI command to the specified device after the SCSI device has been successfully started (SCIOSTART). The SCSI adapter driver performs no error recovery other then issuing a request sense for a SCSI check condition error. If the caller allocated an autosense buffer, then the request sense data is returned in that buffer. The SCSI adapter driver will not log any errors in the system error log for failures on a SCIOCMD operation. The following is a typical call:

rc = ioctl(adapter, SCIOCMD, &iocmd);

where adapter is a file descriptor and iocmd is an sc_passthru structure as defined in the /usr/include/sys/scsi.h header file. The SCSI ID and LUN should be placed in the sc_passthru parameter block.

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. In this case, the caller should evaluate the returned status bytes to determine why the operation failed and what recovery actions should be taken.

If a SCIOCMD operation fails because a field in the sc_passthru structure has an invalid value, then the subroutine will return a value of -1 and set the errno global variable to EINVAL. In addition 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 on the failure is available.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum, a value of -1 is returned and the errno global variable set to a value of EINVAL. Refer to the Small Computer System Interface (SCSI) Specification for the applicable device to get request sense information.

Possible errno values are:

EIO

A system error has occurred. Consider retrying the operation several (three or more) times, because another attempt might be successful. If an EIO error occurs and the status_validity field is set to SC_SCSI_ERROR, then 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, then an unrecoverable error has occurred with the device.

If the status_validity field is SC_SCSI_ERROR and the scsi_status field contains a Check Condition status, then a SCSI request sense should be issued using the SCIOCMD ioctl to recover the 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, which indicates the operation did not complete before the time-out value was exceeded. Consider retrying the operation.

ENODEV

The device is not responding.

Note: This operation requires the SCIOSTART operation to be run first.

If the FCP SCIOCMD ioctl operation completes successfully, then the adap_set_flags field might have the SC_RET_ID flag set. This field is set only if the world_wide_name and node_ name fields were provided in the ioctl call and the FC adapter driver detects that the scsi_id field of this device has changed. The scsi_id field will contain the new scsi_id value.

The version field of the scsi_passthru structure can be set to the value of SC_VERSION_2 in /usr/include/sys/scsi.h or SCSI_VERSION_2 in /usrinclude/sys/scsi_buf.h, and the user can provide the following fields:

• variable_cdb_ptr - pointer to a buffer that contains the SCSI cdb variable.
• variable_cdb_length - the length of the variable cdb to which the variable_cdb_ptr points.

When the SCIOCMD ioctl request with the version field set to SCSI_VERSION_2 completes and the device did not fully satisfy the request, the residual field indicates left over data. If the request completes successfully, the residual field indicates the device does not have all the requested data. If the request did not complete successfully, check the status_validity to see whether a valid SCSI bus problem exists. If a valid SCSI bus problem exists, the residual field indicates the number of bytes by which the device failed to complete the request.

SCIOHALT

This operation halts outstanding transactions to this ID/LUN device and causes the SCSI adapter device driver to stop accepting transactions for this device. This situation remains in effect until the SCSI device driver sends another transaction with the SC_RESUME flag set (in the sc_buf.flags field) for this ID/LUN combination. The SCIOHALT ioctl operation causes the SCSI adapter device driver to fail the command in progress, if any, as well as all queued commands for the device with a return value of ENXIO in the sc_buf.bufstruct.b_error field. If an SCIOSTART operation has not been previously issued, this command fails.

The following values for the errno global variable are supported:

0

Indicates successful completion.

EIO

Indicates an unrecovered I/O error occurred.

EINVAL

Indicates that the selected SCSI ID and LUN have not been started.

ETIMEDOUT

Indicates that the command did not complete.

SCIORESET

This operation causes the SCSI adapter device driver to send a SCSI Bus Device Reset (BDR) message to the selected SCSI ID. For this operation, the SCSI device driver should set the LUN in the arg parameter to the LUN ID of a LUN on this SCSI ID, which has been successfully started using the SCIOSTART operation.

The SCSI device driver should use this command only when directed to do a forced open. This occurs in two possible situations: one, when it is desirable to force the device to drop a SCSI reservation; two, when the device needs to be reset to clear an error condition (for example, when running diagnostics on this device).

Note: In normal system operation, this command should not be issued, as it would force the device to drop a SCSI reservation another initiator (and, hence, another system) might have. If an SCIOSTART operation has not been previously issued, this command is unsuccessful.

The following values for the errno global variable are supported:

0

Indicates successful completion.

EIO

Indicates an unrecovered I/O error occurred.

EINVAL

Indicates that the selected SCSI ID and LUN have not been started.

ETIMEDOUT

Indicates that the command did not complete.

SCIOGTHW

This operation is only supported by SCSI adapter device drivers that support gathered write commands. The purpose of the operation is to indicate support for gathered writes to SCSI device drivers that intend to use this facility. If the SCSI adapter device driver does not support gathered write commands, it must fail the operation. The SCSI device driver should call this operation from its open routine for a particular device instance. If the operation is unsuccessful, the SCSI device driver should not attempt to run a gathered write command.

The arg parameter to the SCIOGTHW is set to null by the caller to indicate that no input parameter is passed:

The following values for the errno global variable are supported:

0

Indicates successful completion and in particular that the adapter driver supports gathered writes.

EINVAL

Indicates that the SCSI adapter device driver does not support gathered writes.