Note: This operation is not supported by all FCP I/O controllers.
A FCP device driver can register a particular device instance for receiving asynchronous event status by calling the SCIOLEVENT ioctl operation for the FCP-adapter device driver. When an event covered by the SCIOLEVENT ioctl operation is detected by the FCP adapter device driver, it builds an scsi_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 FCP adapter device driver as follows:
The information reported in the scsi_event_info.events field does not queue to the FCP device driver, but is instead reported as one or more flags as they occur. Since the data does not queue, the FCP adapter device driver writer can use a single scsi_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 FCP device driver must copy the scsi_event_info.events field into local space and must not modify the contents of the rest of the scsi_event_info structure.
Since the event status is optional, the FCP 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 FCP 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 FCP 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 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 FCP-device driver asynchronous event-handling routine is typically called directly from the hardware interrupt-handling routine for the FCP adapter device driver. The FCP device driver writer must be aware of how this affects the design of the FCP device driver.
Since the event handling routine is running on the hardware interrupt level, the FCP 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 FCP device driver must be careful to disable interrupts at the correct level in places where the FCP device driver's lower execution priority routines manipulate variables that are also modified by the event-handling routine. To allow the FCP device driver to disable at the correct level, the FCP 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 FCP device driver configuration method knows which attribute of the parent adapter to query. The FCP device driver configuration method should then pass this interrupt priority value to the FCP device driver along with other configuration data for the device instance.
The FCP 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 FCP device driver copies the information from the scsi_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 FCP adapter device driver.