Chris Cant - Writing Windows WDM Device Drivers

The DbpCancelIrp routine shown in Listing 14.8 is called if an IRP is cancelled. An I/O request is cancelled when a user mode application calls the Win32 CancelIO function. This technique is used by the DebugPrint Monitor application. The kernel will also cancel any outstanding IRPs if a process terminates unexpectedly or when the file handle is closed.

The I/O Manager uses its Cancel spin lock to ensure that cancel operations happen safely.

A cancel routine is always called at DISPATCH_LEVEL IRQL holding this Cancel spin lock. The DbpCancelIrp routine can simply release this straightaway.

DbpCancelIrp then goes on to acquire the DebugPrint device extension ReadIrpLock spin lock. It checks to see if the given IRP pointer matches the one in the queue. If it does, it clears the queue. Regardless of whether the given IRP matches the one in the list, DbpCancelIrp just cancels the IRP by calling CompleteIrp , passing a status of STATUS_CANCELLED.

Listing 14.8 DebugPrint driver cancel routine

VOID DbpCancelIrp(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

PDEBUG_PRINT_DEVICE_EXTENSION dx = (PDEBUGPRINT_DEVICE_EXTENSION)fdo->DeviceExtension;

IoReleaseCancelSpinLock(Irp->CancelIrql);

// If this is our queued read, then unqueue it

KIRQL irql ;

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

if (Irp==dx->ReadIrp) {

UnlockDevice(dx);

dx->ReadIrp = NULL;

}

KeReleaseSpinLock(&dx->ReadIrpLock,irql);

// Whatever Irp it is, just cancel it

CompleteIrp(Irp, STATUS_CANCELLED, 0);

}

The DebugPrint driver write routine DbpWrite , shown in Listing 14.9, at first sight looks pretty similar to the DebugPrintMsg routine described earlier. Its job is to insert the trace event data into an interlocked doubly-linked list. If there is a Read IRP queued up, DbpWrite goes on to satisfy this read request.

DbpWrite first gets the write parameters, and completes Write IRPs with a zero transfer length straightaway. The device file pointer is ignored.

As shown previously, the event list is stored in the device extension in field EventList, protected by spin lock EventListLock. Each event is stored in a DEBUGPRINT_EVENT structure.

DbpWrite determines the correct size for the DEBUGPRINT_EVENT structure and tries to allocate some memory for it from the nonpaged pool. It fails the IRP with STATUS_INSUFFICIENT_RESOURCES if no memory is available. Next, it copies the event data into the event and stores the data length, before calling ExInterlockedInsertTailList in the same way as before to insert the event safely into EventList.

DbpWrite now checks to see if there is a queued Read IRP. It must first grab the ReadIrpLock spin lock. If the ReadIrp field is not NULL, ReadEvent is called to complete the Read IRP and the ReadIrp field is reset to NULL.

Finally, DbpWrite completes its own Write IRP, returning STATUS_SUCCESS.

Listing 14.9 DebugPrint driver write routine

NTSTATUS DbpWrite(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);

PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

ULONG BytesTxd = 0;

// Check write len

ULONG WriteLen = IrpStack->Parameters.Write.Length;

if (WriteLen==0) {

UnlockDevice(dx);

return CompleteIrp(Irp, STATUS_SUCCESS, 0);

}

// Copy write data into an event

ULONG Len = sizeof(LIST_ENTRY)+sizeof(ULONG)+WriteLen;

PDEBUGPRINT_EVENT pEvent = (PDEBUGPRINT_EVENT)ExAllocatePool(NonPagedPool,Len);

if (pEvent==NULL) {

UnlockDevice(dx);

return CompleteIrp(Irp,STATUS_INSUFFICIENT_RESOURCES,0);

}

pEvent->Len = WriteLen;

RtlCopyMemory(pEvent->EventData, Irp->AssociatedIrp.SystemBuffer, WriteLen);

// Insert event into event list

ExInterlockedInsertTailList(&dx->EventList,&pEvent-> ListEntry,&dx->EventListLock);

// If read pending, then read it

KIRQL irql;

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

if (dx->ReadIrp!=NULL) if (ReadEvent(dx, dx->ReadIrp)) {

UnlockDevice(dx);

dx->ReadIrp = NULL;

}

KeReleaseSpinLock(&dx->ReadIrpLock,irql);

// Complete IRP

UnlockDevice(dx);

return CompleteIrp(Irp, STATUS_SUCCESS, WriteLen);

}

The ReadEvent routine shown in Listing 14.10 is called by the read and write dispatch routines. It is called while holding the ReadIrpLock spin lock. ReadEvent returns true if a trace event was found.

ReadEvent tries to remove an entry from the event list using ExInterlockedRemoveHeadList . If it finds an entry, it obtains a pointer to the DEBUGPRINT_EVENT structure using CONTAINING_RECORD. It now checks the event data length against the size of the Read IRP buffer and shortens the transfer count, if necessary. The event data is copied to the Read I/O buffer and the Read IRP is completed. Finally, the event buffer memory is freed.

Listing 14.10 DebugPrint driver ReadEvent routine

bool ReadEvent(PDEBUGPRINT_DEVICE_EXTENSION dx, PIRP Irp) {

// Try to remove Event from EventList

PLIST_ENTRY pListEntry = ExInterlockedRemoveHeadList(&dx->EventList, &dx->EventListLock);

if (pListEntry==NULL) return false;

// Get event as DEBUGPRINT_EVENT

PDEBUGPRINT_EVENT pEvent = CONTAINING_RECORD(pListEntry, DEBUGPRINT_EVENT, ListEntry);

// Get length of event data

ULONG EventDataLen = pEvent->Len;

// Get max read length acceptible

PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

ULONG ReadLen = IrpStack->Parameters.Read.Length;

// Shorten event length if necessary

if(EventDataLen>ReadLen) EventDataLen = ReadLen;

// Copy data to Irp and complete it

RtlCopyMemory(Irp->AssociatedIrp.SystemBuffer, pEvent->EventData, EventDataLen);

IoSetCancelRoutine(Irp, NULL);

CompleteIrp(Irp, STATUS_SUCCESS, EventDataLen);

// Free event memory

ExFreePool(pEvent);

return true;

}

The DebugPrint Monitor is a user mode application that keeps reading events from the DebugPrint driver and displays them to the user. The Monitor is a standard MFC application, so this chapter will not discuss all the code in detail. The source files can be found on the book software disk.

The Monitor program saves its current screen position and column widths in the registry. Consult the code to find out how this is done.