Understanding SCSI Asynchronous Event Handling

Edit online

A SCSI device driver can register a particular device instance for receiving asynchronous event status by calling the SCIOEVENT ioctl operation for the SCSI-adapter device driver. When an event covered by the SCIOEVENT ioctl operation is detected by the SCSI adapter device driver, it builds an sc_event_info structure and passes a pointer to the structure and to the asynchronous event-handler routine entry point, which was previously registered.

Note: This operation is not supported by all SCSI I/O controllers.

The fields in the structure are filled in by the SCSI adapter device driver as follows:

Item	Description
id	For initiator mode, this is set to the SCSI ID of the attached SCSI target device. For target mode, this is set to the SCSI ID of the attached SCSI initiator device.
lun	For initiator mode, this is set to the SCSI LUN of the attached SCSI target device. For target mode, this is set to 0).
mode	Identifies whether the initiator or target mode device is being reported. The following values are possible: `SC_IM_MODE` An initiator mode device is being reported. `SC_TM_MODE` A target mode device is being reported.
events	This field is set to indicate what event or events are being reported. The following values are possible, as defined in the /usr/include/sys/scsi.h file: `SC_FATAL_HDW_ERR` A fatal adapter hardware error occurred. `SC_ADAP_CMD_FAILED` An unrecoverable adapter command failure occurred. `SC_SCSI_RESET_EVENT` A SCSI bus reset was detected. `SC_BUFS_EXHAUSTED` In target-mode, a maximum buffer usage event has occurred.
adap_devno	This field is set to indicate the device major and minor numbers of the adapter on which the device is located.
async_correlator	This field is set to the value passed to the SCSI adapter device driver in the sc_event_struct structure. The SCSI device driver may optionally use this field to provide an efficient means of associating event status with the device instance it goes with. Alternatively, the SCSI device driver uses the combination of the `id`, `lun`, `mode`, and `adap_devno` fields to identify the device instance.

Note: Reserved fields should be set to 0 by the SCSI adapter device driver.

The information reported in the sc_event_info.events field does not queue to the SCSI device driver, but is instead reported as one or more flags as they occur. Because the data does not queue, the SCSI adapter device driver writer can use a single sc_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 SCSI device driver must copy the sc_event_info.events field into local space and must not modify the contents of the rest of the sc_event_info structure.

Because the event status is optional, the SCSI 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 SCSI device driver or application level program can take error recovery actions.