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 might 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.

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.

SCIOCMD

The SCIOCMD operation provides the means for issuing any SCSI command to the specified device after the SCSI device has been successfully started (SCIOSTART). The SCSI adapter driver performs no error recovery other then issuing a request sense for a SCSI check condition error. If the caller allocated an autosense buffer, then the request sense data is returned in that buffer. The SCSI adapter driver will not log any errors in the system error log for failures on a SCIOCMD operation. The following is a typical call:

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

where adapter is a file descriptor and iocmd is an sc_passthru structure as defined in the /usr/include/sys/scsi.h header file. The SCSI ID and LUN should be placed in the sc_passthru parameter block.

The SCSI status byte and the adapter status bytes are returned through the sc_passthru structure. If the SCIOCMD 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.

If a SCIOCMD operation fails because a field in the sc_passthru structure has an invalid value, then the subroutine will return a value of -1 and set the errno global variable to EINVAL. In addition the einval_arg field will be set to the field number (starting with 1 for the version field) of the field that had an invalid value. A value of 0 for the einval_arg field indicates no additional information on the failure is available.

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 (three or more) 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 SCIOCMD ioctl to recover the the sense data.

EFAULT

A user process copy has failed.

EINVAL

The device is not opened or the caller has set a field in the sc_passthru structure to an invalid value.

EACCES

The adapter is in diagnostics mode.

ENOMEM

A memory request has failed.

ETIMEDOUT

The command has timed out, which indicates the operation did not complete before the time-out value was exceeded. Consider retrying the operation.

ENODEV

The device is not responding.

Note

This operation requires SCIOSTART to be run first.

For more information, see SCIOCMD SCSI Adapter Device Driver ioctl Operation in AIX 5L Version 5.2 Technical Reference: Kernel and Subsystems Volume 2.

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) might 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 that 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 run 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 run this operation.

Target- and Initiator-Mode ioctl Commands

For either target or initiator mode, the SCSI device driver can 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:

The following values for the errno global variable are supported: