Chris Cant - Writing Windows WDM Device Drivers

&fdo);

If you try to create a second DebugPrint device, the same kernel device name is passed to IoCreateDevice . As this device name is already being used, the call will fail. This problem does not occur if you pass NULL for the device name, as in earlier examples. If you definitely need more than one named kernel device, you must keep a (zero-based) count of devices and append it as a device number to the kernel device name.

No special processing is required when you remove a device with a kernel device name.

The Read IRP queue is implemented using variables in the device extension, shown in Listing 14.6. If ReadIrp is NULL, no IRP is queued. Otherwise, it contains a pointer to the queued IRP. A spin lock called ReadIrpLock is used to protect access to the read queue. These fields are initialized as follows in the DbpAddDevice routine in Pnp.cpp.

// Initialise "read queue"

KeInitializeSpinLock(&dx->ReadIrpLock);

dx->ReadIrp = NULL;

Listing 14.6 DebugPrint driver device extension

typedef struct _DEBUGPRINT_DEVICE_EXTENSION {

PDEVICE_OBJECT fdo;

PDEVICE_OBJECT NextStackDevice;

UNICODE_STRING ifSymLinkName;

bool GotResources; // Not stopped

bool Paused; // Stop or remove pending

bool IODisabled; // Paused or stopped

LONG OpenHandleCount; // Count of open handles

LONG UsageCount; // Pending I/O Count

bool Stopping; // In process of stopping

KEVENT StoppingEvent; // Set when all pending I/O complete

PIRP ReadIrp; // "Read queue" of 1 IRP

KSPIN_LOCK ReadIrpLock; // Spin lock to guard access to ReadIrp

LIST_ENTRY EventList; // Doubly-linked list of written Events

KSPIN_LOCK EventListLock; // Spin lock to guard access to EventList

} DEBUGPRINT_DEVICE_EXTENSION, *PDEBUGPRINT_DEVICE_EXTENSION;

Listing 14.7 shows the complete Read IRP handler. Its first job is to acquire the ReadIrpLock spin lock. If the ReadIrp field is not NULL, it means another Read IRP has been queued. The IRP is failed, not forgetting to release the spin lock first. Even though the Monitor program will never issue more than one read IRP, it is best to be on the safe side.

The ReadEvent routine is then called. If there are any trace events available straightaway, ReadEvent returns the event data in the IRP, completes the IRP, and returns true. If this happens, the read routine can just return straightaway without queuing the IRP.

If there are no trace events available, the IRP is queued. This simply means storing the IRP pointer in ReadIrp. The final job is to mark the IRP as pending using IoMarkIrpPending and set its cancel routine using IoSetCancelRoutine . The read routine must return STATUS_PENDING because it has queued its IRP.

IRPs that are not cancelled must remove their cancel routine using IoSetCancelRoutine before completing the IRP.

Listing 14.7 DebugPrint driver read dispatch routine

NTSTATUS DbpRead(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

PDEBUGPRINT_DEVICE_EXTENSION dx = (PDEBUGPRINT_DEVICE_EXTENSION)fdo->DeviceExtension;

if (!dx->IODisabled) return CompleteIrp(Irp, STATUS_DEVICE_NOT_CONNECTED, 0);

if (!LockDevice(dx)) return CompleteIrp(Irp, STATUS_DELETE_PENDING, 0);

// Get access to our Read IRP queue

KIRQL irql;

KeAcquireSpinLock(&dx->ReadIrpLock,&irql);

// Only one listening read allowed at a time.

if (dx->ReadIrp!=NULL) {

KeReleaseSpinLock(&dx->ReadIrpLock,irql);

UnlockDevice(dx);

return CompleteIrp(Irp, STATUS_UNSUCCESSFUL, 0);

}

// See if there's data available

if (ReadEvent(dx, Irp)) {

KeReleaseSpinLock(&dx->ReadIrpLock,irql);

UnlockDevice(dx);

return STATUS_SUCCESS;

}

// No event is available, queue this read Irp

dx->ReadIrp = Irp;

KeReleaseSpinLock(&dx->ReadIrpLock,irql);

// Mark Irp as pending and set Cancel routine

Irp->IoStatus.Information = 0;

IoMarkIrpPending(Irp);

IoSetCancelRoutine(Irp.DbpCancelIrp);

return STATUS_PENDING;

}

Any IRPs that are queued must have a cancel routine. A driver ought to also handle the IRP_MJ_CLEANUP Cleanup IRP.

Cancel and Cleanup Circumstances

First, let's be clear when IRP cancel routines are called and when the Cleanup IRP is sent.

Case 1is a situation in which a user application calls the CancelIo Win32 function on a file handle. All IRPs with cancel routines have their cancel routine called. Only IRPs that have been issued by the current thread are effected.

Case 2covers these three situations:

• a user mode program crashes with IRPs pending,

• it exits with overlapped I/O requests pending and without closing its file handle, and

• if Ctrl+C is pressed in console applications.

In this case, all IRPs with cancel routines have their cancel routines called first. If there are outstanding IRPs without cancel routines, the I/O Manager simply sets the IRPs' Cancel flag and waits until the IRPs complete. Finally, the Cleanup IRP is sent.

If an uncancellable IRP does not complete within five minutes, the IRP is forcibly detached from the user process so that it can terminate. However, the IRP is still left uncompleted. You will not be able to reinstall the driver, so a reboot will be necessary to try the fixed version of your driver.

Issuing the Cleanup IRP seems to perform no useful function in this case.

Case 3is a situation in which a user mode programs closes its file handle with overlapped I/O requests pending

In this case, IRPs with cancel routines do not have their cancel routines called. Instead, the Cleanup IRP is issued to cancel all pending IRPs.

The Implications

If you give each queued IRP a cancel routine, most normal cases are covered (i.e., the afore-mentioned Cases 1 and 2). To be thorough, however, you ought to provide a Cleanup handler to cover Case 3. As you well know, programmers are bound to forget to close a file handle sometime or other.

If you do not provide a cancel routine for IRPs but do provide a Cleanup handler, only Case 3 is handled correctly. This is an unsatisfactory solution. In addition, user mode applications will not be able to cancel IRPs with CancelIo .

Some drivers work by providing a cancel routine only for an IRP while it is queued. Once the IRP actually begins processing, the cancel routine is removed. If you use this technique, be sure to provide a reasonable timeout for real IRP processing. Otherwise, crashed programs will not be able to exit.

DebugPrint IRP Cancelling

Full Cancel and Cleanup support can be quite complicated. This is particularly the case for IRPs put in the device queue for processing in a StartIo routine. A full example for this case is given in Chapter 16.

The DebugPrint driver uses just a cancel routine for its one queued IRP. It does not handle the Cleanup IRP.