A driver can never assume that an expected device interrupt will arrive. The device might be offline; it might be waiting for some kind of operator intervention; or, perhaps it's just broken. This section explains how to use I/O Timer routines to detect unresponsive devices.
How I/O Timer Routines Work
An I/O Timer routine is a (somewhat) optional piece of driver code that an AddDevice routine attaches to a specific Device object. After the timer is started, the I/O Manager begins calling the I/O Timer routine once every second. These calls continue until the timer is explicitly stopped. Table 11.1 lists the functions available for working with I/O timers.
Table 11.2 shows the prototype for the I/O Timer routine itself. When this callback executes, it receives a pointer to the associated Device object and the context argument that was specified in the call to IoInitializeTimer. As always, the address of the Device Extension is a good choice for context.
How to Catch Device Timeout Conditions
In general terms, a driver that wants to catch device timeouts should do the following:
-
In AddDevice, call IoInitializeTimer to associate an I/O Timer routine with a specific device.
-
When a handle is associated with the device (e.g., when a user-mode program calls CreateFile), the driver's Dispatch routine for IRP_MJ_ CREATE calls IoStartTimer. As long as the device handle remains open, the device receives I/O Timer calls.
-
If the driver needs a longer timeout than one second (and it probably does), a separate counter value must bemaintained. This counter is initialized in the Start I/O routine to the maximum number of seconds the driver is willing to wait for an interrupt.
-
The ISR resets or cancels the timer, depending on whether additional device interrupts are expected.
-
Each time the driver's I/O Timer routine is called, the timer counter is decremented and checked. If the counter reaches zero before an interrupt arrives, the I/O Timer routine stops the device, clears the timeout counter, and processes the request as a timed-out operation.
-
When the user-mode program calls CloseHandle, the Dispatch routine for IRP_MJ_CLOSE calls IoStopTimer, which disables I/O timer callbacks for the device.
Notice that the Start I/O and I/O Timer routines (running at DISPATCH_ LEVEL IRQL), and the ISR (running at DIRQL) all have access to the timeout counter in the Device Extension. These independent code paths must synchronize their access to the timeout counter. The code example that appears later in this chapter demonstrates such synchronization.
Table 11.1. I/O Timer Routineys
| Function | Purpose | IRQLM |
| IoInitializeTimer | Attach a timer to a device | PASSIVE_LEVEL |
| IoStartTimer | Start receiving callbacks | <= DISPATCH_LEVEL |
| IoStopTimer | Stop receiving callbacks | <= DISPATCH_LEVEL |
Table 11.2. Function Prototype for IoTimer Callback
| VOID IoTimer | IRQL == DISPATCH_LEVEL |
| Parameter | Description |
| IN PDEVICE_OBJECT pDeviceObject | Pointer to device object whose timer just fired |
| IN PVOID pContext | Context argument passed with IoInitializeTimer |
| Return value | - void - |
Of course, a driver can choose to use IoStartTimer and IoStopTimer outside of Dispatch routines. Since the timer callback interval is one second, disregarding unneeded callbacks does not incur significant overhead. For example, a driver could call IoStartTimer in AddDevice and just let the routine continually fire.
Once it is determined that a device operation has timed out, a driver may do any of the following:
-
Retry the device operation a fixed number of times before failing the IRP that generated it.
-
Fail the IRP by calling IoCompleteRequest with an appropriate final status value. Do not use STATUS_IO_TIMEOUT as the final status for the failed IRP. This status code maps onto the ERROR_ SEM_TIMEOUT Win32 error message, signifying a semaphore timeout.
-
Log a timeout error for the device in the system event log. This can help system administrators track down failing hardware.
[oR]