TMIOEVNT (Event) tmscsi Device Driver ioctl Operation

Purpose

Allows the caller to query the device driver for event status.

Description

The TMIOEVNT ioctl operation allows the caller to query the device driver for status on certain events. The arg parameter to the TMIOEVNT operation specifies the address of the tm_event_info structure defined in the /usr/include/sys/tmscsi.h file. This operation conveys status that is generally not tied to a specific application program subroutine and would not otherwise be known to the application. For example, failure of an adapter function not associated directly with a SCSI command is reported through this facility.

Although this operation can be used independently of other commands to the target-mode device driver, it is most effective when issued in conjunction with the select entry point POLLPRI option. For this device driver, the POLLPRI option indicates an event has occurred that is reported through the TMIOEVNT operation. This allows the caller to be asynchronously notified of events occurring to the device instance, which means the TMIOEVNT operation need only be issued when an event occurs. Without the select entry point, it would be necessary for the caller to issue the TMIOEVNT operation after every read or write subroutine to know when an event has occurred. The select entry point allows the caller to monitor events on one or more target or initiator devices.

Because the caller is not generally aware of which adapter a particular device is attached to, event information in the TMIOEVNT operation is maintained for each device instance. Application programs should not view any information from one device's TMIOEVNT operation as necessarily affecting other devices opened through this device driver. Rather, the application must base its error recovery for each device on that device's particular TMIOEVNT information.

Event information is reported through the events field of the tm_event_info structure and can have the following values:

Some of the events that can be reported apply to any SCSI device, whether they are initiator-mode or target-mode devices. These events include adapter fatal hardware failure, unrecoverable adapter command failure, and SCSI BUS Reset detected. The maximum buffer usage detected event applies only to the target mode device and is never reported for an initiator-mode device instance.

The adapter fatal hardware failure event is intended to indicate a fatal condition. This means no further commands are likely to complete successfully to or from this SCSI device, as the adapter it is attached to has failed. In this case, the application should end the session with the device.

The unrecoverable adapter command failure event is not necessarily a fatal condition but can indicate that the adapter is not functioning properly. The application program has these possible actions:

• End the session with the device in the near future.
• End the session after multiple (two or more) such events.
• Attempt to continue the session indefinitely.

The SCSI Bus Reset detection event is mainly intended as information only but can be used by the application to perform further actions, if necessary. The Reset information can also be conveyed to the application during command execution, but the Reset must occur during the SCSI command for this to occur.

The maximum buffer usage detected event only applies to a given target-mode device; it is not be reported for an initiator 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 subroutines 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 is restored when the application empties enough buffers to continue reasonable operations. The num_bufs attribute may need to be increased from the default value to help minimize this problem.

Return Values

Files