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 variable infostruct.un.fcp.max_transfer and the card ID is contained in infostruct.un.fcp.scsi_id.
This operation opens a logical path to the FCP device and causes the FCP adapter device driver to allocate and initialize all of the data areas needed for the FCP 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 FCP process login for this operation.
A nonzero return value indicates an error has occurred and all operations to this SCSI/LUN pair should cease since 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 FCP device responded to the explicit process login at this SCSI ID. |
| ECONNREFUSED | Indicates that the FCP 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 FCP device and causes the FCP 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 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. |
This operation requires SCIOLSTART to be run first.
This operation allows a FCP device driver to register a particular device instance for receiving asynchronous event status by calling the SCIOLEVENT ioctl operation for the FCP-adapter device driver. When an event covered by the SCIOLEVENT ioctl operation is detected by the FCP 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 FCP device driver, but is instead reported as one or more flags as they occur. Since the data does not queue, the FCP 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 FCP 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.
Since the event status is optional, the FCP device driver writer determines what action is necessary to take upon receiving event status. The writer may decide to save the status and report it back to the calling application, or the FCP 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. |
This operation requires SCIOLSTART to be run first.
This operation issues an inquiry command to a FCP device and is used to aid in FCP 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 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 may 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 may 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. |
This operation requires SCIOLSTART to be run first.
This operation issues a start unit command to a FCP device and is used to aid in FCP 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 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 FCP bus. 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 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 since 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 may 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 may 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. |
This operation requires SCIOLSTART to be run first.
This operation issues a FCP Test Unit Ready command to an adapter and aids in FCP 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 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 may 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 may be successful. |
| ENODEV | The device is not responding and 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. |
This operation requires SCIOLSTART to be run first.
This operation issues an read command to a FCP device and is used to aid in FCP 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 and 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 may 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 may 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_readblk structure. In the case of multiple retries, this flag should be set only on the last retry. |
This operation requires SCIOLSTART to be run first.
This operation causes a FCP device to release all reservations, clear all current commands, and return to an initial state by issuing a Bus Device Reset (BDR) to all LUNs associated with the specified FCP ID. A FCP 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 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. |
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 FCP adapter sends a FCP abort message to the device and is usually used by the FCP 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 FCP adapter also performs normal error recovery procedures during this command which include issuing a FCP bus reset in response to a FCP bus hang. 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 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. |
This operation requires SCIOLSTART to be run first.
When the SCSI device has been successfully started (SCIOLSTART), this 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 and LUN 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 may 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 may be successful. |
| ENODEV | The device is not responding. |
| ETIMEDOUT | The operation did not complete before the time-out value was exceeded. |
This operation requires SCIOLSTART to be run first.
FCP Device Driver Routines can provide further information about specific FCP driver routines.
An introduction to the FCP subsystem is provided by Programming FCP Device Drivers.