Various ioctl operations must be performed for proper operation of the FCP adapter device driver. The ioctl operations described here are the minimum set of commands the FCP adapter device driver must implement to support FCP device drivers. Other operations may be required in the FCP adapter device driver to support, for example, system management facilities and diagnostics. FCP device driver writers also need to understand these ioctl operations.
Every FCP adapter device driver must support the IOCINFO ioctl operation. The structure to be returned to the caller is the devinfo structure, including the FCP union definition for the FCP adapter, which can be found in the /usr/include/sys/devinfo.h file. The FCP device driver should request the IOCINFO ioctl operation (probably during its open routine) to get the maximum transfer size of the adapter.
Note: The FCP adapter device driver ioctl operations can only be called from the process level. They cannot be executed from a call on any more favored priority levels. Attempting to call them from a more favored priority level can result in a system crash.
The following SCIOLSTART and SCIOLSTOP operations must be sent by the FCP device driver (for the open and close routines, respectively) for each device. They cause the FCP adapter device driver to allocate and initialize internal resources. The SCIOLHALT ioctl operation is used to abort pending or running commands, usually after signal processing by the FCP device driver. This might be used by a FCP device driver to end an operation instead of waiting for completion or a time out. The SCIOLRESET operation is provided for clearing device hard errors and competing initiator reservations during open processing by the FCP device driver.
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 FCP LUN and the next least significant byte is the FCP 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 FCP transport layer operations for the ioctl operation requested.
The following information is provided on the various ioctl operations:
This operation allocates and initializes FCP device-dependent information local to the FCP adapter device driver. Run this operation only on the first open of an ID/LUN device. Subsequent SCIOLSTART commands to the same ID/LUN fail unless an intervening SCIOLSTOP command is issued.
For this operation an scsi_sciolst structure (The scsi_sciolst structure is defined in the /usr/include/sys/scsi_buf.h file.) must be used to specify the FCP device's SCSI id and LUN id. In addition, the scsi_sciolst structure can be used to specify an explicit FCP process login for this operation.
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. |
| 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. |
This operation deallocates resources local to the FCP adapter device driver for this FCP device. This should be run on the last close of an ID/LUN device. If an SCIOLSTART operation has not been previously issued, this command is unsuccessful. For this operation an scsi_sciolst structure (The scsi_sciolst structure is defined in the /usr/include/sys/scsi_buf.h file.) must be used to specify the FCP device's SCSI id and LUN id. In addition the scsi_sciolst structure can be used to specify an explicit FCP process login for this operation.
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 FCP ID and LUN have not been started. |
| ETIMEDOUT | Indicates that the command did not complete. |
This operation halts outstanding transactions to this ID/LUN device and causes the FCP adapter device driver to stop accepting transactions for this device. This situation remains in effect until the FCP device driver sends another transaction with the SC_RESUME flag set (in the scsi_buf.flags field) for this ID/LUN combination. The SCIOLHALT ioctl operation causes the FCP 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 scsi_buf.bufstruct.b_error field. If an SCIOLSTART operation has not been previously issued, this command fails. For this operation an scsi_sciolst structure (The scsi_sciolst structure is defined in the /usr/include/sys/scsi_buf.h file.) must be used to specify the FCP device's SCSI id and LUN id. In addition the scsi_sciolst structure can be used to specify an explicit FCP process login for this operation.
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 FCP ID and LUN have not been started. |
| ETIMEDOUT | Indicates that the command did not complete. |
This operation causes the FCP adapter device driver to send a FCP transport Device Reset (BDR) message to the selected FCP ID. For this operation, the FCP device driver should set the LUN in the arg parameter to the LUN ID of a LUN on this FCP ID, which has been successfully started using the SCIOLSTART operation. For this operation an scsi_sciolst structure (The scsi_sciolst structure is defined in the /usr/include/sys/scsi_buf.h file.) must be used to specify the FCP device's SCSI id and LUN id. In addition the scsi_sciolst structure can be used to specify an explicit FCP process login for this operation.
The FCP 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 FCP 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 FCP reservation another initiator (and, hence, another system) may have. If an SCIOLSTART 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 FCP ID and LUN have not been started. |
| ETIMEDOUT | Indicates that the command did not complete. |
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 values for the errno global variable are supported:
| 0 | Indicates successful completion. |
| 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. |
For initiator mode, the FCP device driver may issue an SCIOLEVENT ioctl operation to register for receiving asynchronous event status from the FCP adapter device driver for a particular device instance. This is an optional call for the FCP device driver, and is optionally supported for the FCP adapter device driver. A failing return code from this command, in the absence of any programming error, indicates it is not supported. If the FCP device driver requires this function, it must check the return code to verify the FCP adapter device driver supports it.
Only a kernel process or device driver can invoke these ioctls. If attempted by a user process, the ioctl will fail, and the errno global variable will be set to EPERM.
The event registration performed by this ioctl operation is allowed once per device session. Only the first SCIOLEVENT ioctl operation is accepted after the device session is opened. Succeeding SCIOLEVENT ioctl operations will fail, and the errno global variable will be set to EINVAL. The event registration is canceled automatically when the device session is closed.
The arg parameter to the SCIOLEVENT ioctl operation should be set to the address of an scsi_event_struct structure, which is defined in the /usr/include/sys/scsi_buf.h file. The following parameters are supported:
Note: All reserved fields should be set to 0 by the caller.
The following values for the errno global variable are supported:
| 0 | Indicates successful completion. |
| EINVAL | An SCIOLSTART has not been issued to this device instance, or this device is already registered for async events. |
| EPERM | Indicates the caller is not running in kernel mode, which is the only mode allowed to execute this operation. |
scdisk FCP Device Driver and FCP Adapter Device Driver in AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2.