Chris Cant - Writing Windows WDM Device Drivers

Table 6.2 Common bugchecks

How do you work out what code caused the bugcheck? By analyzing the linker map for a driver, you can work out which routine caused the problem. A source-level debugger is required if you are still having problems.

You build a linker map by adding a line like the following to your SOURCES file.

LINKER_FLAGS=-MAP:Wdm2.map

What routine caused the following access violation?

*** STOP: 0x0000001E (0xC0000005,0xF764C5F1,0x00000000,0x00000010)

KMODE_EXCEPTION_NOT_HANDLED

*** Address 0xF764C5F1 base at 0xF764A000 Datestamp 3653e5fb – Wdm2.sys

The first thing to note is that the access violation occurs at a very low address, 0x10. This suggests that the code had a NULL pointer to a structure and was trying to access a field at offset 0x10 in this structure. This turned out to be the case.

The problem seems to be in the Wdm2 driver. The offset into the executable image is 0xF764C5F1-0xF764A000 (i.e., 0x25F1).

Listing 6.2 shows part of the linker map for this build of the Wdm2 driver. The initial section shows that the load address is 0x00010000. The map then lists the segments that make up the executable image. However, the information of interest is buried in the next section, which lists each code and data object.

The entry for PnpDefaultHandler in Pnp.cpp has an Rva+Base of 0x00012512. If the load address is taken off, this shows that PnpDefaul tHandler starts at offset 0x2512. The next line shows that the ForwardAndWait routine starts at 0x2611. Therefore, the access violation at offset 0x25Fl occurred towards the end of the PnpDefaultHandler routine.

Listing 6.2 Wdm2 linker map excerpt

Wdm2

Timestamp is 3653e5fb (Thu Nov 19 09:33:47 1998) Preferred load address is 00010000

Start Length Name Class

0001:00000000 0000152cH .text CODE

0002:00000000 000000a0H .idata$5 DATA

0002:000000a0 00000632H .rdata DATA

0003:00000000 00000119H .data DATA

0003:00000120 00000042H .bss DATA

0004:00000000 00000c1aH PAGE CODE

0005:00000000 000000eeH INIT CODE

0005:000000f0 00000028H .idata$2 CODE

0005:00000118 00000014H .idata$3 CODE

0005:0000012c 000000a0H .fdata$4 CODE

0005:000001cc 00000344H .idata$6 CODE

0006:00000000 00000058H .rsrc$01 DATA

0006:00000060 00000338H .rsrc$02 DATA

Address Publics by Value Rva+Base Lib:Object

0001:00000012 ?Wdm1Create@@YGJPAU_DEVICE_OBJECT@@PAU_IRP@@@Z 000102f2 f dispatch.obj

0001:00000056 ?Wdm1Close@@YGJPAU_DEVICE_OBJECT@@PAU_IRP@@@Z 00010336 f dispatch.obj

…

0004:00000492 ?PnpDefaultHandler@@YGJPAU_DEVICE_OBJECT@@PAU_IRP@@@Z 00012512 f pnp.obj

0004:00000591 ?ForwardAndWait@@YGJPAU_DEVICE_OBJECT@@PAU_IRP@@@Z 00012611 f pnp.obj

Please test your driver well before releasing it. You must check that your driver works on a variety of computers. It must cope with user mode program aborts.

Debugging drivers is harder than user mode applications. In the worst case, a bugcheck occurs that tells you roughly what went wrong. Resource leaks and timing problems are more difficult to sort out.

The DebugPrint software lets you insert "print" statements into your driver code. You can do source-level debugging between two computers using WinDbg, or on a single computer using the NuMega SoftICE product.

The next chapter looks at the dispatch routines in the Wdm1 device driver.

This chapter looks at how to write driver dispatch routines that process I/O Request Packets (IRPs). Dispatch routines are used to handle requests from Win32 applications. It is crucial that you understand everything in this chapter clearly. If necessary, refer to Chapter 3 where IRPs are first introduced.

The dispatch routines for the Wdm1 driver are explained in full. These handle open, close, read, write, and IOCTL requests. The Wdm1 driver implements a global memory buffer that is shared by all Wdm1 devices.

This chapter takes a good hard look at I/O Request Packets (IRPs). It is worth reading this chapter carefully, as a good understanding of IRPs will ease your passage through the rest of the book.

Table 7.1 lists the most common Win32 functions that are used to access devices. A CreateFile call to your device ends up as a Create IRP, an I/O Request Packet with a major function code of IRP_MJ_CREATE. The driver routine to handle this IRP can have any name. However, I use a generic name for the Create IRP handler of Create. In your driver, you would usually put a short name or acronym in front of this base name. The Wdm1 device driver's Create IRP handler is called Wdm1Create .

Table 7.1 is not an exhaustive list of Win32 functions and their matching IRPs. For example, ReadFile has several variants, such as ReadFileEx , but they all end up as IRP_MJ_READ requests. IRPs can also be issued by Windows on behalf of the user program. For example, if an application terminates unexpectedly, the operating system will try to tidy any open files by issuing an IRP_MJ_CLOSE IRP to each file.

Table 7.1 Common dispatch routines

A driver need not handle all these IRPs, though handling Create and Close IRPs is an obvious minimum. Its DriverEntry routine sets up the entry points that are valid. If an entry point is not set, then the I/O Manager fails the Win32 request and GetLastError returns 1.

The following line in DriverEntry sets the Wdm1Read routine as the handler for Read IRPs.

DriverObject->MajorFunction[IRP_MJ_READ] = Wdm1Read;

All dispatch routines have the same function prototype. The function is passed a pointer to your device object and the IRP. The function must return a suitable NTSTATUS value (e.g., STATUS_SUCCESS).