SCIOLCMD

Edit online

After the SCSI device has been successfully started using SCIOLSTART, the SCIOLCMD ioctl operation provides the means for issuing any SCSI command to the specified device. The SAM adapter driver performs no error recovery or logging on failures of this ioctl operation.

The following is a typical call:


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

where adapter is a file descriptor and iocmd is a scsi_iocmd structure as defined in the /usr/include/sys/scsi_buf.h header file. The SCSI ID or iSCSI device's SCSI ID alias, and LUN ID should be placed in the scsi_iocmd parameter block.

The SCSI status byte and the adapter status bytes are returned using the scsi_iocmd structure. If the SCIOLCMD 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.

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:

Item	Description
`EIO`	A system error has occurred. Consider retrying the operation several (around three) 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 SCIOLCMD ioctl to recover the the sense data.
`EFAULT`	A user process copy has failed.
`EINVAL`	The device is not opened.
`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 might be successful.
`ENODEV`	The device is not responding.
`ETIMEDOUT`	The operation did not complete before the time-out value was exceeded.

For all transport types, the version field of the scsi_iocmd structure must be set to a minimum value of SCSI_VERSION_1, which is defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:

world_wide_name - The caller can set the world_wide_name field to the World Wide Name of the attached target device. If Dynamic Tracking of FC devices is enabled, the world_wide_name field must be set to ensure communication with the device because the scsi_id field of a device can change after dynamic tracking events.
node_name - The caller can set the node_name field to the Node Name of the attached target device. If the world_wide_name field and the version field are set to SCSI_VERSION_1 but the node_name field is not set, the scsi_id field is used for device lookup instead of the world_wide_name. If Dynamic Tracking of FC devices is enabled, the node_name field must be set to ensure communication with the device because the scsi_id field of a device can change after dynamic tracking events.

The version field of the scsi_iocmd structure can be set to the value of SCSI_VERSION_2, and the user can provide the following fields:

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

Note: The SAS transport type does not support the cdbs variable length.

When the SCIOLCMD 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 problem exists. If a valid SCSI problem exists, the residual field indicates the number of bytes by which the device failed to complete the request.

This operation requires SCIOLSTART to be run first.

If the FCP SCIOLCMD 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 contains the new scsi_id value.