[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel Extensions and Device Support Programming Concepts

Required SCSI Adapter Device Driver ioctl Commands

Various ioctl operations must be performed for proper operation of the SCSI adapter device driver. The ioctl operations described here are the minimum set of commands the SCSI adapter device driver must implement to support SCSI device drivers. Other operations may be required in the SCSI adapter device driver to support, for example, system management facilities and diagnostics. SCSI device driver writers also need to understand these ioctl operations.

Every SCSI adapter device driver must support the IOCINFO ioctl operation. The structure to be returned to the caller is the devinfo structure, including the scsi union definition for the SCSI adapter, which can be found in the /usr/include/sys/devinfo.h file. The SCSI device driver should request the IOCINFO ioctl operation (probably during its open routine) to get the maximum transfer size of the adapter.

Note: The SCSI 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.

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.
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) may 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.

Target-Mode ioctl Commands

The following SCIOSTARTTGT and SCIOSTOPTGT operations must be sent by the SCSI device driver (for the open and close routines, respectively) for each target-mode device instance. This causes the SCSI adapter device driver to allocate and initialize internal resources, and, if necessary, prepare the hardware for operation.

Target-mode support in the SCSI device driver and SCSI adapter device driver is optional. A failing return code from these commands, in the absence of any programming error, indicates target mode is not supported. If the SCSI device driver requires target mode, it must check the return code to verify the SCSI adapter device driver supports it.

Only a kernel process or device driver can call these ioctls. If attempted by a user process, the ioctl will fail, and the errno global variable will be set to EPERM.

The following information is provided on the various target-mode ioctl operations:

SCIOSTARTTGT This operation opens a logical path to a SCSI initiator device. It allocates and initializes SCSI device-dependent information local to the SCSI adapter device driver. This is run by the SCSI device driver in its open routine. Subsequent SCIOSTARTTGT commands to the same ID (LUN is always 0) are unsuccessful unless an intervening SCIOSTOPTGT is issued. This command also causes the SCSI adapter device driver to allocate system buffer areas to hold data received from the initiator, and makes the adapter ready to receive data from the selected initiator.

The arg parameter to the SCIOSTARTTGT should be set to the address of an sc_strt_tgt structure, which is defined in the /usr/include/sys/scsi.h file. The following parameters are supported:

id The caller fills in the SCSI ID of the attached SCSI initiator.
lun The caller sets the LUN to 0, as the initiator LUN is ignored for received data.
buf_size The caller specifies size in bytes to be used for each receive buffer allocated for this host target instance.
num_bufs The caller specifies how many buffers to allocate for this target instance.
tm_correlator The caller optionally places a value in this field to be passed back in each tm_buf for this target instance.
recv_func The caller places in this field the address of a pinned routine the SCSI adapter device driver should call to pass tm_bufs received for this target instance.
free_func This is an output parameter the SCSI adapter device driver fills with the address of a pinned routine which the SCSI device driver calls to pass tm_bufs after they have been processed. The SCSI adapter device driver ignores the value passed as input.
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 SCIOSTARTTGT command has already been issued to this SCSI ID.

The passed SCSI ID is the same as that of the adapter.

The LUN ID field is not set to zero.

The buf_size is not valid. This is an adapter dependent value.

The num_bufs is not valid. This is an adapter dependent value.

The recv_func value, which cannot be null, is not valid.

EPERM Indicates the caller is not running in kernel mode, which is the only mode allowed to execute this operation.
ENOMEM Indicates that a memory allocation failure has occurred.
EIO Indicates an I/O error occurred, preventing the device driver from completing SCIOSTARTTGT processing.
SCIOSTOPTGT This operation closes a logical path to a SCSI initiator device. It causes the SCSI adapter device driver to deallocate device dependent information areas allocated in response to a SCIOSTARTTGT operation. It also causes the SCSI adapter device driver to deallocate system buffer areas used to hold data received from the initiator, and to disable the host adapter's ability to receive data from the selected initiator.

The arg parameter to the SCIOSTOPTGT ioctl should be set to the address of an sc_stop_tgt structure, which is defined in the /usr/include/sys/scsi.h file. The caller fills in the id field with the SCSI ID of the SCSI initiator, and sets the lun field to 0 as the initiator LUN is ignored for received data. Reserved fields should be set to 0 by the caller.

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

0 Indicates successful completion.
EINVAL An SCIOSTARTTGT command has not been previously issued to this SCSI ID.
EPERM Indicates the caller is not running in kernel mode, which is the only mode allowed to execute this operation.

Target- and Initiator-Mode ioctl Commands

For either target or initiator mode, the SCSI device driver may issue an SCIOEVENT ioctl operation to register for receiving asynchronous event status from the SCSI adapter device driver for a particular device instance. This is an optional call for the SCSI device driver, and is optionally supported for the SCSI adapter device driver. A failing return code from this command, in the absence of any programming error, indicates it is not supported. If the SCSI device driver requires this function, it must check the return code to verify the SCSI 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 SCIOEVENT ioctl operation is accepted after the device session is opened. Succeeding SCIOEVENT 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 SCIOEVENT ioctl operation should be set to the address of an sc_event_struct structure, which is defined in the /usr/include/sys/scsi.h file. The following parameters are supported:

id The caller sets id to the SCSI ID of the attached SCSI target device for initiator-mode. For target-mode, the caller sets the id to the SCSI ID of the attached SCSI initiator device.
lun The caller sets the lun field to the SCSI LUN of the attached SCSI target device for initiator-mode. For target-mode, the caller sets the lun field to 0.
mode Identifies whether the initiator- or target-mode device is being registered. These values are possible:
SC_IM_MODE This is an initiator mode device.
SC_TM_MODE This is a target mode device.
async_correlator The caller places a value in this optional field which is saved by the SCSI adapter device driver and returned when an event occurs in this field in the sc_event_info structure. This structure is defined in the /user/include/sys/scsi.h file.
async_func The caller fills in the address of a pinned routine which the SCSI adapter device driver calls whenever asynchronous event status is available. The SCSI adapter device driver passes a pointer to a sc_event_info structure to the caller's async_func routine.
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 Either an SCIOSTART or SCIOSTARTTGT 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.

Related Information

SCSI Subsystem Overview.

SCSI Error Recovery.

[ Previous | Next | Contents | Home | Search ]