This section describes the following ioctl operations:
This operation allows a FCP device driver to obtain important information about a FCP adapter, including the adapter's SCSI ID, the maximum data transfer size in bytes, and the FC topology to which the adapter is connected. By knowing the maximum data transfer size, a FCP device driver can control several different devices on several different adapters. This operation returns a devinfo structure as defined in the sys/devinfo.h header file with the device type DD_BUS and subtype DS_FCP. The following is an example of a call to obtain the information:
rc = fp_ioctl(fp, IOCINFO, &infostruct, NULL);
where fp is a pointer to a file structure and infostruct is a devinfo structure. A non-zero rc value indicates an error. Note that the devinfo structure is a union of several structures and that fcp is the structure that applies to the adapter. For example, the maximum transfer size value is contained in the infostruct.un.fcp.max_transfer variable and the card ID is contained in infostruct.un.fcp.scsi_id.
This operation allows an iSCSI device driver to obtain important information about an iSCSI adapter, including the adapter's maximum data transfer size in bytes. By knowing the maximum data transfer size, an iSCSI device driver can control several different devices on several different adapters. This operation returns a devinfo structure as defined in the sys/devinfo.h header file with the device type DD_BUS and subtype DS_ISCSI. The following is an example of a call to obtain the information:
rc = fp_ioctl(fp, IOCINFO, &infostruct, NULL);
where fp is a pointer to a file structure and infostruct is a devinfo structure. A non-zero rc value indicates an error. Note that the devinfo structure is a union of several structures and that iscsi is the structure that applies to the adapter. For example, the maximum transfer size value is contained in the infostruct.un.iscsi.max_transfer variable.
This operation opens a logical path to the device and causes the adapter device driver to allocate and initialize all of the data areas needed for the device. The SCIOLSTOP operation should be issued when those data areas are no longer needed. This operation should be issued before any nondiagnostic operation except for IOCINFO. The following is a typical call:
rc = fp_ioctl(fp, SCIOLSTART, &sciolst);
where fp is a pointer to a file structure and sciolst is a scsi_sciolst structure (defined in /usr/include/sys/scsi_buf.h) that contains the SCSI and Logical Unit Number (LUN) ID values of the device to be started. In addition, the scsi_sciolst structure can be used to specify an explicit login for this operation.
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
If a World Wide Name or Node Name is provided and it does not match the World Wide Name or Node Name that was detected for the target, an error log will be generated and the SCIOLSTART operation will fail with an errno of ENXIO.
Upon successfuly return from an SCIOLSTART operation, both the world_wide_name field and the node_name field are set to the World Wide Name and Node Name of this device. These values are inspected to ensure that the SCIOLSTART operation was delivered to the intended device.
For iSCSI adapters, this version field of the scsi_sciolst must be set to the value of SCSI_VERSION_1 (defined in the /usr/include/sys/scsi_buf.h file). In addition, iSCSI adapters require the caller to set the following fields:
If the iSCSI SCIOLSTART ioctl operation completes successfully, then the adap_set_flags field should have the SCIOL_RET_ID_ALIAS flag set and the scsi_id field set to a SCSI ID alias that can be used for subsequent non-SCIOLSTART ioctls to this device.
If the caller of the iSCSI or FCP SCIOLSTART is a kernel extention, then the SCIOL_RET_HANDLE flag can be set in the adap_set_flags field along with the kernext_handle field. In this case the kernext_handle field can be used for scsi_buf structures issued to the adapter driver for this device.
A nonzero return value indicates an error has occurred and all operations to this SCSI/LUN pair should cease because the device is either already started or failed the start operation. Possible errno values are:
| EIO | The command could not complete due to a system error. |
| EINVAL | Either the Logical Unit Number (LUN) ID or SCSI ID is invalid, or the adapter is already open. |
| ENOMEM | Indicates that system resources are not available to start this device. |
| ETIMEDOUT | Indicates that the command did not complete. |
| ENODEV | Indicates that no device responded to the explicit process login at this SCSI ID. |
| ECONNREFUSED | Indicates that the device at this SCSI ID rejected explicit process login. This could be due to the device rejecting the security password or the device does not support FCP. |
| EACCES | The adapter is not in normal mode. |
This operation closes a logical path to the device and causes the adapter device driver to deallocate all data areas that were allocated by the SCIOLSTART operation. This operation should only be issued after a successful SCIOLSTART operation to a device. The following is a typical call:
rc = fp_ioctl(fp, SCIOLSTOP, &sciolst);
where fp is a pointer to a file structure and sciolst is a scsi_sciolst structure (defined in /usr/include/sys/scsi_buf.h) that contains the SCSI or iSCSI device's SCSI ID alias, and Logical Unit Number (LUN) ID values of the device to be started.
A non-zero return value indicates an error has occurred. Possible errno values are:
| EIO | An unrecoverable system error has occurred. |
| EINVAL | The adapter was not in open mode. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation allows a device driver to register a particular device instance for receiving asynchronous event status by calling the SCIOLEVENT ioctl operation for the adapter device driver. When an event covered by the SCIOLEVENT ioctl operation is detected by the adapter device driver, it builds an scsi_event_info structure and passes a pointer to the structure and to the asynchronous event-handler routine entry point, which was previously registered.
The information reported in the scsi_event_info.events field does not queue to the device driver, but is instead reported as one or more flags as they occur. Because the data does not queue, the adapter device driver writer can use a single scsi_event_info structure and pass it one at a time, by pointer, to each asynchronous event handler routine for the appropriate device instance. After determining for which device the events are being reported, the device driver must copy the scsi_event_info.events field into local space and must not modify the contents of the rest of the scsi_event_info structure.
Because the event status is optional, the device driver writer determines what action is necessary to take upon receiving event status. The writer might decide to save the status and report it back to the calling application, or the device driver or application level program can take error recovery actions.
This operation should only be issued after a successful SCIOLSTART operation to a device. The following is a typical call:
rc = fp_ioctl(fp, SCIOLEVENT, &scevent);
where fp is a pointer to a file structure and scevent is a scsi_event_struct structure (defined in /usr/include/sys/scsi_buf.h) that contains the SCSI and Logical Unit Number (LUN) ID values of the device to be started.
A non-zero return value indicates an error has occurred. Possible errno values are:
| EIO | An unrecoverable system error has occurred. |
| EINVAL | The adapter was not in open mode. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation issues an inquiry command to an device and is used to aid in device configuration. The following is a typical call:
rc = ioctl(adapter, SCIOLINQU, &inquiry_block);
where adapter is a file descriptor and inquiry_block is a scsi_inquiry structure as defined in the /usr/include/sys/scsi_buf.h header file. The FCP ID or iSCSI device's SCSI ID alias, and LUN should be placed in the scsi_inquiry parameter block. The SC_ASYNC flag should not be set on the first call to this operation and should only be set if a bus fault has occurred. Possible errno values are:
| EIO | A system error has occurred. Consider retrying the operation several times, because another attempt might be successful. |
| 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. Possibly no LUNs exist on the present FCP ID. |
| ENOCONNECT | A bus fault has occurred and the operation should be retried with the SC_ASYNC flag set in the scsi_inquiry structure. In the case of multiple retries, this flag should be set only on the last retry. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation issues a start unit command to an device and is used to aid in device configuration. The following is a typical call:
rc = ioctl(adapter, SCIOLSTUNIT, &start_block);
where adapter is a file descriptor and start_block is a scsi_startunit structure as defined in the /usr/include/sys/scsi_buf.h header file. The FCP ID or iSCSI device's SCSI ID alias, and LUN should be placed in the scsi_startunit parameter block. The start_flag field designates the start option, which when set to true, makes the device available for use. When this field is set to false, the device is stopped.
The SC_ASYNC flag should not be set on the first call to this operation and should only be set if a bus fault has occurred. The immed_flag field allows overlapping start operations to several devices on the adapter. When this field is set to false, status is returned only when the operation has completed. When this field is set to true, status is returned as soon as the device receives the command. The SCIOLTUR operation can then be issued to check on completion of the operation on a particular device.
Note that when the FCP or iSCSI adapter is allowed to issue simultaneous start operations, it is important that a delay of 10 seconds be allowed between successive SCIOLSTUNIT operations to devices sharing a common power supply because damage to the system or devices can occur if this precaution is not followed. Possible errno values are:
| EIO | A system error has occurred. Consider retrying the operation several times, because another attempt might be successful. |
| 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. Possibly no LUNs exist on the present FCP ID. |
| ENOCONNECT | A bus fault has occurred. Try the operation again with the SC_ASYNC flag set in the scsi_inquiry structure. In the case of multiple retries, this flag should be set only on the last retry. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation issues a Test Unit Ready command to an adapter and aids in device configuration. The following is a typical call:
rc = ioctl(adapter, SCIOLTUR, &ready_struct);
where adapter is a file descriptor and ready_struct is a scsi_ready structure as defined in the /usr/include/sys/scsi_buf.h header file. The FCP ID or iSCSI device's SCSI ID alias, and LUN should be placed in the scsi_ready parameter block. The SC_ASYNC flag should not be set on the first call to this operation and should only be set if a bus fault has occurred. The status of the device can be determined by evaluating the two output fields: status_validity and scsi_status. Possible errno values are:
| 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_FCP_ERROR, then the scsi_status field has a valid value and should be inspected.
If the status_validit 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_FCP_ERROR and the scsi_status field contains a Check Condition status, then the SCIOLTUR operation should be retried after several seconds. If after successive retries, the Check Condition status remains, the device should be considered inoperable. |
| 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 and possibly no LUNs exist on the present target. |
| ENOCONNECT | A bus fault has occurred and the operation should be retried with the SC_ASYNC flag set in the scsi_inquiry structure. In the case of multiple retries, this flag should be set only on the last retry. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation issues an read command to an device and is used to aid in device configuration. The following is a typical call:
rc = ioctl(adapter, SCIOLREAD, &readblk);
where adapter is a file descriptor and readblk is a scsi_readblk structure as defined in the /usr/include/sys/scsi_buf.h header file. The FCP ID or iSCSI device's SCSI ID alias, and the LUN should be placed in the scsi_readblk parameter block. The SC_ASYNC flag should not be set on the first call to this operation and should only be set if a bus fault has occurred. Possible errno values are:
| EIO | A system error has occurred. Consider retrying the operation several times, because another attempt might be successful. |
| 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. Possibly no LUNs exist on the present target. |
| ENOCONNECT | A bus fault has occurred and the operation should be retried with the SC_ASYNC flag set in the scsi_readblk structure. In the case of multiple retries, this flag should be set only on the last retry. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
If the SCIOLRESET_LUN_RESET flag is not set in the flags field of the scsi_sciolst, then this operation causes a device to release all reservations, clear all current commands, and return to an initial state by issuing a Target Reset, which resets all LUNs associated with the specified FCP ID or iSCSI device's SCSI ID alias. If the SCIOLRESET_LUN_RESET flag is set in the flags field of the scsi_sciolst, then this operation causes an FCP device to release all reservations, clear all current commands, and return to an initial state by issuing a Lun Reset, which resets just the specified LUN associated with the specified FCP ID or iSCSI device's SCSI ID alias.
An reserve command should be issued after the SCIOLRESET operation to prevent other initiators from claiming the device. Note that because a certain amount of time exists between a reset and reserve command, it is still possible for another initiator to successfully reserve a particular device. The following is a typical call:
rc = fp_ioctl(fp, SCIOLRESET, &sciolst);
where fp is a pointer to a file structure and sciolst is a scsi_sciolst structure (defined in /usr/include/sys/scsi_buf.h) that contains the SCSI ID or iSCSI device's SCSI ID alias, and Logical Unit Number (LUN) ID values of the device to be started.
A nonzero return value indicates an error has occurred. Possible errno values are:
| EIO | An unrecoverable system error has occurred. |
| EINVAL | The device is not opened. |
| EACCES | The adapter is in diagnostics mode. |
| ETIMEDOUT | The operation did not complete before the time-out value was exceeded. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation stops the current command of the selected device, clears the command queue of any pending commands, and brings the device to a halted state. The adapter sends an abort message to the device and is usually used by the device driver to abort the current operation instead of allowing it to complete or time out.
After the SCIOLHALT operation is sent, the device driver must set the SC_RESUME flag in the next scsi_buf structure sent to the adapter device driver, or all subsequent scsi_buf structures sent are ignored.
The adapter also performs normal error recovery procedures during this command. The following is a typical call:
rc = fp_ioctl(fp, SCIOLHALT, &sciolst);
where fp is a pointer to a file structure and sciolst is a scsi_sciolst structure (defined in /usr/include/sys/scsi_buf.h) that contains the SCSI ID or iSCSI device's SCSI ID alias, and Logical Unit Number (LUN) ID values of the device to be started.
A nonzero return value indicates an error has occurred. Possible errno values are:
| EIO | An unrecoverable system error has occurred. |
| EINVAL | The device is not opened. |
| EACCES | The adapter is in diagnostics mode. |
| ETIMEDOUT | The operation did not complete before the time-out value was exceeded. |
For FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
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 SCSI 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 via the scsi_iocmd structure. If the SCIOLCMD operation returns a value of -1 and theerrno 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:
| 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 via 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 FCP adapters, the version field of the scsi_sciolst structure must be set to the value of SCSI_VERSION_1, which id defined in the /usr/include/sys/scsi_buf.h file. In addition, the following fields can be set:
This operation requires SCIOLSTART to be run first.
This operation issues a query name server request to find all SCSI devices and is used to aid in SCSI device configuration. The following is a typical call:
rc = ioctl(adapter, SCIOLNMSRV, &nmserv);
where adapter is a file descriptor and nmserv is a scsi_nmserv structure as defined in the /usr/include/sys/scsi_buf.h header file. The caller of this ioctl, must allocate a buffer be referenced by the scsi_id_list field. In addition the caller must set the list_len field to indicate the size of the buffer in bytes.
On sucessful completion, the num_ids field indicates the number of SCSI IDs returned in the current list. If the more ids were found then could be placed in the list, then the adapter driver will update the list_len field to indicate the length of buffer needed to receive all SCSI IDs.
Possible errno values are:
| EIO | A system error has occurred. Consider retrying the operation several times, because another attempt may be successful. |
| EFAULT | A user process copy has failed. |
| EINVAL | The physical configuration does not support this request. |
| 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. Possibly no LUNs exist on the present target. |
This operation issues a request to find the SCSI id of a device for the specified world wide name.The following is a typical call:
rc = ioctl(adapter, SCIOLQWWN, &qrywwn);
where adapter is a file descriptor and qrywwn is a scsi_qry_wwn structure as defined in the /usr/include/sys/scsi_buf.h header file. The caller of this ioctl, must specify the device's world wide name in the world_wide_name field. On successful completion, the scsi_id field will be returned with the SCSI ID of the device with this world wide name.
Possible errno values are:
| EIO | A system error has occurred. Consider retrying the operation several times, because another attempt may be successful. |
| EFAULT | A user process copy has failed. |
| EINVAL | The physical configuration does not support this request. |
| 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. Possibly no LUNs exist on the present FCP ID. |
This operation provides the means for issuing a transport payload to the specified device. The SCSI adapter driver performs no error recovery or logging on failures of this ioctl operation. The following is a typical call:
rc = ioctl(adapter, SCIOLPAYLD, &payld);
where adapter is a file descriptor and payld is a scsi_trans_payld structure as defined in the /usr/include/sys/scsi_buf.h header file. The SCSI ID or SCSI ID alias should be placed in the scsi_trans_payld. In addition the user must allocate a payload buffer referenced by the payld_bufferfield and a response buffer referenced by the response_buffer field. The fields payld_size and response_size specify the size in bytes of the payload buffer and response buffer, respectively. In addition the caller may also set payld_type (for FC this is the FC-4 type), and payld_ctl (for FC this is the router control field),.
If the SCIOLPAYLD 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.
Possible errno values are:
| EIO | A system error has occurred. |
| EFAULT | A user process copy has failed. |
| EINVAL | Payload and or response buffer are too large. For FCP and iSCSI the maximum size is 4096 bytes. |
| 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 time-out value was exceeded. |
When the device has been successfully opened, the SCIOLCHBA operation provides the means for issuing one or more common HBA API commands to the adapter. The FC adapter driver will perform full error recovery on failures of this operation.
The arg parameter contains the address of a scsi_chba structure, which is defined in the /usr/include/sys/scsi_buf.h file.
The cmd field in the scsi_chba structure will determine the common HBA API operation that is performed.
If the SCIOLCHBA operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller should evaluate the returned status bytes to determine why the operation was unsuccessful and what recovery actions should be taken.
If a SCIOLCHBA operation fails because a field in the scsi_chba structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL.
When the device has been successfully opened, the SCIOLPASSTHRUHBA operation provides the means for issuing passthru commands to the adapter. The FC adapter driver will perform full error recovery on failures of this operation.
The arg parameter contains the address of a scsi_passthru_hba structure, which is defined in the /usr/include/sys/scsi_buf.h file.
The cmd field in the scsi_passthru_hba structure will determine the type of passthru operation to be performed.
If the SCIOPASSTHRUHBA operation fails, the subroutine returns a value of -1 and sets the errno global variable to a nonzero value. In this case, the caller should evaluate the returned status bytes to determine why the operation was unsuccessful and what recovery actions should be taken.
If a SCIOLPASSTHRUHBA operation fails because a field in the scsi_passthru_hba structure has an invalid value, the subroutine will return a value of -1 and set the errno global variable to EINVAL.