Note: This operation is not supported by all SCSI I/O controllers.
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. The fields in the structure are filled in by the SCSI adapter device driver as follows:
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. Since 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.
Since 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.
The adapter fatal hardware failure event is intended to indicate that no further commands to or from this SCSI device are likely to succeed, since the adapter it is attached to has failed. It is recommended that the application end the session with the device.
The unrecoverable adapter command failure event is not necessarily a fatal condition, but it can indicate that the adapter is not functioning properly. Possible actions by the application program include:
The SCSI Bus Reset detection event is mainly intended as information only, but may be used by the application to perform further actions, if necessary.
The maximum buffer usage detected event only applies to a given target-mode device; it will not be reported for an initiator-mode device. This event indicates to the application that this particular target-mode device instance has filled its maximum allotted buffer space. The application should perform read system calls fast enough to prevent this condition. If this event occurs, data is not lost, but it is delayed to prevent further buffer usage. Data reception will be restored when the application empties enough buffers to continue reasonable operations. The num_bufs attribute may need to be increased to help minimize this problem. Also, it is possible that regardless of the number of buffers, the application simply is not processing received data fast enough. This may require some fine tuning of the application's data processing routines.
The SCSI-device driver asynchronous event-handling routine is typically called directly from the hardware interrupt-handling routine for the SCSI adapter device driver. The SCSI device driver writer must be aware of how this affects the design of the SCSI device driver.
Since the event handling routine is running on the hardware interrupt level, the SCSI device driver must be careful to limit operations in that routine. Processing should be kept to a minimum. In particular, if any error recovery actions are performed, it is recommended that the event-handling routine set state or status flags only and allow a process level routine to perform the actual operations.
The SCSI device driver must be careful to disable interrupts at the correct level in places where the SCSI device driver's lower execution priority routines manipulate variables that are also modified by the event-handling routine. To allow the SCSI device driver to disable at the correct level, the SCSI adapter device driver writer must provide a configuration database attribute that defines the interrupt class, or priority, it runs on. This attribute must be named intr_priority so that the SCSI device driver configuration method knows which attribute of the parent adapter to query. The SCSI device driver configuration method should then pass this interrupt priority value to the SCSI device driver along with other configuration data for the device instance.
The SCSI device driver writer must follow any other general system rules for writing a routine which must execute in an interrupt environment. For example, the routine must not attempt to sleep or wait on I/O operations. It can perform wakeups to allow the process level to handle those operations.
Since the SCSI device driver copies the information from the sc_event_info.events field on each call to its asynchronous event-handling routine, there is no resource to free or any information which must be passed back later to the SCSI adapter device driver.