Kernel Extensions and Device Support Programming Concepts

Required FCP and iSCSI Adapter Device Driver ioctl Commands

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

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

Note

The 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 SCIOLSTART and SCIOLSTOP operations must be sent by the device driver (for the open and close routines, respectively) for each device. They cause the 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 device driver. This might be used by a 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 device driver.

The following information is provided on the various ioctl operations:

For more information on these ioctl operations, see FCP and iSCSI Adapter ioctl Operations.

Initiator-Mode ioctl Command used by FCP Device Drivers

SCIOLEVENT

For initiator mode, the FCP device driver can 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:

scsi_id

The caller sets id to the SCSI ID or SCSI ID alias of the attached target device for initiator-mode. For target-mode, the caller sets the id to the SCSI ID or SCSI ID alias of the attached initiator device.

lun_id

The caller sets the lun field to the LUN of the attached target device for initiator-mode. For target-mode, the caller sets the lun field to 0.

mode

Identifies whether the initiator-mode 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 in this optional field a value, which is saved by the FCP adapter device driver and returned when an event occurs in this field in the scsi_event_info structure. This structure is defined in the /user/include/sys/scsi_buf.h.

async_func

The caller fills in the address of a pinned routine which the FCP adapter device driver calls whenever asynchronous event status is available. The FCP adapter device driver passes a pointer to a scsi_event_info structure to the caller's async_func routine.

world_wide_name

For FCP devices, the caller sets the world_wide_name field to the World Wide Name of the attached target device for initiator-mode.

node_name

For FCP devices, the caller sets the node_name field to the Node Name of the attached target device for initiator-mode.

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.