Chris Cant - Writing Windows WDM Device Drivers

A driver can use two main methods to access the user's buffer properly, either Buffered I/O or Direct I/O. When you create a device, you must set the DO_BUFFERED_IO bit in the Flags field of the new device object to use Buffered I/O. For Direct I/O, set the DO_DIRECT_IO bit in Flags.

If you use Buffered I/O, the kernel makes the user's buffer available in some nonpaged memory and stores a suitable pointer for you in the AssociatedIrp.SystemBuffer field of the IRP header. Simply read or write this memory in your driver.

This technique is the easiest one for driver writers to use. However, it is slightly slower overall, as the operating system usually will have to copy the user buffer into or out of non-paged memory.

It is faster to use a Memory Descriptor List (MDL). However, this is only available to hardware that can perform Direct Memory Access (DMA). DMA and MDLs are not explained in this book, although Chapter 24 lists the changes in W2000 for those of you who have used DMA in NT 4 and earlier.

The MDL of the user's buffer is put in the MdlAddress field of the IRP header.

A final and uncommon technique for accessing a user's buffer is to use neither Buffered I/O nor Direct I/O. In this case, the user's buffer pointer is simply put in the UserBuffer field of the IRP header. If you are certain that your driver is the first driver to receive a request, the dispatch routine can directly access the buffer, as the driver will be operating in the context of the user's thread. Be very careful if you try to use this technique.

DeviceIoControl requests can use a combination of these user buffer access techniques. Each IOCTL can use a different method, if need be. However, most drivers simply use Buffered I/O, as IOCTL buffers are usually fairly small. I shall show how to define IOCTLs shortly.

The TransferType portion of the actual IOCTL code indicates the buffer access technique. For Buffered I/O, specify METHOD_BUFFERED for TransferType. For Direct I/O, use either METHOD_IN_DIRECT or METHOD_OUT_DIRECT.

If you use METHOD_BUFFERED, AssociatedIrp.SystemBuffer is used for the input and output buffer. The buffer size is the maximum of the user's input and output buffer sizes. As the same memory is used for both input and output, make sure that you use (or copy) the input data before you start writing any output data.

For both METHOD_IN_DIRECT and METHOD_OUT_DIRECT the DeviceIoControl input data appears in buffered memory at Irp->AssociatedIrp.SystemBuffer. In both cases, an MDL for the DeviceIoControl output data is put in Irp->MdlAddress. The size of the read or write buffer is in Parameters.DeviceIoControl.OutputBufferLength.

Finally, for METHOD_NEITHER, the input buffer user space pointer is put in Parameters.DeviceIoControl.Type3InputBuffer in the stack. The user space output buffer pointer is put in the IRP header UserBuffer field.

Wdm1 Dispatch Routines

The dispatch routines for the Wdm1 driver are in the file Dispatch.cpp, which is available on the book CD-ROM. These routines all run at PASSIVE_LEVEL IRQL, so they can be put in paged memory. All the basic dispatch routines complete the IRP straightaway.

The dispatch routines include various DebugPrint trace calls in the code. If you use the checked build version of Wdm1, you can view the trace output using the DebugPrint Monitor application. Listing 7.1 shows the (slightly edited) DebugPrint output on Windows 2000. The Wdm1 driver was started at around 12:00 and the Wdm1Test program was run at 12:10. You can follow the program execution as each test in Wdm1Test is run. The DebugPrint output would be different in Windows 98 because the SetFilePointer function does not work for device files.

Listing 7.1 DebugPrint output in Windows 2000

Monitor 12:03:04 Version 1.02 starting to listen under Windows 2000 (5.0 build 1877)

DebugPrint 11:59:09 Version 1.02 started Wdm1 12:00:42 DebugPrint logging started

Wdm1 12:00:42 RegistryPath is \REGISTRY\Machine\System\ControlSet002\SERVICES\Wdml

Wdm1 12:00:42 DriverEntry completed

Wdm1 12:00:42 AddDevice

Wdm1 12:00:42 FDO is 80AAB020

Wdm1 12:00:42 Symbolic Link Name is \??\Root#UNKNOWN#0003#{c0cf0640…}

Wdm1 12:00:42 PnP IRP_MJ_PNP:IRP_MN_QUERY_CAPABILITIES

Wdm1 12:00:42 PnP IRP_MJ_PNP:IRP_MN_FILTER_RESOURCE_REQUIREMENTS

Wdm1 12:00:43 PnP IRP_MJ_PNP:IRP_MN_START_DEVICE

Wdm1 12:00:43 PnP IRP_MJ_PNP:IRP_MN_QUERY_CAPABILITIES

Wdm1 12:00:43 PnP IRP_MJ_PNP:IRP_MN_QUERY_PNP_DEVICE_STATE

Wdm1 12:00:43 PnP IRP_MJ_PNP:IRP_MN_QUERY_BUS_INFORMATION

Wdm1 12:00:43 PnP IRP_MJ_PNP:IRP_MN_QUERY_DEVICE_RELATIONS

Wdm1 12:10:14 Create File is

Wdm1 12:10:14 Read 4 bytes from file pointer 0

Wdm1 12:10:14 Read: 4 bytes returned

Wdm1 12:10:14 Write 4 bytes from file pointer 0

Wdm1 12:10:14 Write: 4 bytes written

Wdm1 12:10:14 Read 1 bytes from file pointer 3

Wdm1 12:10:14 Read: 1 bytes returned

Wdm1 12:10:14 Write 4 bytes from file pointer 3

Wdm1 12:10:14 Write: 4 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 0022200C InputLength 0 OutputLength 4

Wdm1 12:10:14 DeviceIoControl: 4 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222010 InputLength 0 OutputLength 7

Wdm1 12:10:14 DeviceIoControl: 7 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222010 InputLength 0 OutputLength 8

Wdm1 12:10:14 DeviceIoControl: 0 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222004 InputLength 0 OutputLength 0

Wdm1 12:10:14 DeviceIoControl: 0 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222010 InputLength 0 OutputLength 7

Wdm1 12:10:14 DeviceIoControl: 7 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222008 InputLength 0 OutputLength 0

Wdm1 12:10:14 DeviceIoControl: 0 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 0022200C InputLength 0 OutputLength 4

Wdm1 12:10:14 DeviceIoControl: 4 bytes written

Wdm1 12:10:14 DeviceIoControl: Control code 00222014 InputLength 0 OutputLength 0

Wdm1 12:10:14 DeviceIoControl: 0 bytes written

Wdm1 12:10:14 Write 4 bytes from file pointer 0

Wdm1 12:10:14 Write: 4 bytes written

Wdm1 12:10:14 Close

The Wdm1 create and close routines do nothing except complete the IRP successfully. A helper function, CompleteIrp , is used that sets the IRP header IoStatus fields to the given parameters and calls IoCompleteRequest.

The create routine shows how to access the current I/O stack location using IoGetCurrentIrpStackLocation . In the checked build version, it prints out the FileName field in the stack FileObject.

PIO_STACK_LOCATION IrpStack = IoGetCurrentlrpStackLocation(Irp);

DebugPrint("Create File is %T", &(IrpStack –>FileObject->FileName));