In this book, I will tell you how to write some types of device driver for Windows. I will primarily describe the Windows Driver Model for Windows 98 and Windows 2000. Additionally, I will cover device drivers that also run in Windows NT 3.51 and NT 4, which I call "NT style" drivers.

A device driver provides a software interface to hardware connected to a computer. It is a trusted part of the operating system. User application programs can access hardware in a well-defined manner, without having to worry about how the hardware must be controlled. For example, a disk driver might hide the fact that data must be written in 512-byte chunks. A driver is a piece of software that becomes part of the operating system kernel when it is loaded. A driver makes one or more devices available to the user mode programmer, each representing a physical or logical piece of hardware. For example, one physical hard disk may be viewed as two logical disks called C: and D:.

In Windows, a driver always makes a device look like a file. A handle to the device can be opened. An application program can then issue read and write requests to the driver, before the device handle is finally closed.

Clearly, there are many pieces of hardware that are essentially alike, because they share a bus or do similar tasks. Microsoft provides several generic drivers that perform these common tasks. Device drivers can use the facilities of these standard drivers. This approach makes it easier to share a common bus, and makes it simpler to write new drivers.

The task of writing a new driver, therefore, often starts by identifying which generic drivers can be used. A stack of drivers, layered one on top of each other, processes user requests in stages. A low-level bus driver might be used to handle all the basic communication with hardware. An intermediate class driver might provide the facilities that are common to a whole category of devices.

In Windows 98 and Windows 2000, device drivers must be designed according to the Windows Driver Model (WDM), which I describe in the following section. WDM is based on the device driver model used in Windows NT 4 and NT 3.51.

The Windows Driver Model

The Windows Driver Model has two separate but equally important aspects. First, the core model describes the standard structure for device drivers. Second, Microsoft provides a series of bus and class drivers for common types of devices.

The core WDM model describes how device drivers are installed and started, and how they should service user requests and interact with hardware. A WDM device driver must fit into the Plug and Play (PnP) system that lets users plug in devices that can be configured in software.

Microsoft provides a series of system drivers that have all the basic functionality needed to service many standard types of device. The first type of system driver supports different types of bus, such as the Universal Serial Bus (USB), IEEE 1394 (FireWire) and Audio port devices. Other class drivers implement standard Windows facilities such as Human Input Devices (HID) and kernel streaming. Finally, the Still Image Architecture (STI) provides a framework for handling still images, scanners, etc.

These system class drivers can make it significantly easier to write some types of device driver. For example, the USB system drivers handle all the low-level communications across this bus. A well defined interface is made available to other drivers. This makes it fairly straightforward to issue requests to the USB bus.

Source and Binary Compatibility

Originally Microsoft stated that WDM drivers would be binary compatible between Windows 98 and Windows 2000 x86, and source code compatible to Windows 2000 Alpha platforms. However, it now seems as though binary compatibility is not assured, even though the DDKs are unclear on the subject.

I have erred on the safe side, only installing drivers that have been built for the right operating system. That is, the Windows 98 Driver Development Kit (DDK) is used when building drivers for Windows 98, and the W2000 DDK for W2000.

If you use some WDM facilities that only appear in Windows 2000, then you may not achieve source code compatibility. For example, the W2000 USB system drivers support some features that are not available to W98 drivers.

I will look first at the core WDM functionality as a simple device driver is developed. Next, I will deal with drivers that have to use hardware resources such as accessing memory and handling interrupts. Finally, I will cover the USB and HID system drivers. Use the kernel routine IoIsWdmVersionAvailable to determine whether the required version WDM version is available. The DDK header files define two constants, WDM_MAJORVERSION and WDM_MINORVERSION. For Windows 98, these constants are 1 and 0. For Windows 2000, these are 1 and 0x10.

WDM vs. NT Style Drivers

Figure 1.1 gives a rough indication of the differences between WDM and NT style drivers.

The rest of this book explains all the features mentioned in the figure.

The overlap between the two types of driver is considerable. Indeed, writing WDM and NT style drivers is essentially the same job. The main difference in the driver code is how devices are created.

In a WDM driver, the Plug and Play Manager tells you when a device is added or removed from the system. The PnP Manager uses installation INF files to find the correct driver for a new device. In contrast, an NT style driver has to find its own devices, usually in its initialisation routine. NT style drivers are usually installed using a special installation program.

The new bus and class drivers are only available to WDM device drivers. New WDM and NT style drivers should support the Power Management and the Windows Management Instrumentation features.

Figure 1.1 WDM and NT style device drivers

Ready-to-Use Drivers

If you start writing a driver from scratch, it seems as though most of your code has nothing to do with talking to your device. There is much "infrastructure" to set up before you can perform some real Input and Output (I/O). This book should help you get started as I have tried to use some real, useful drivers as examples. Some drivers can be used directly, while others can form the basis of your own drivers.

A virtual device driver is used to explain the core WDM functionality. A virtual device does not use any real hardware. Three drivers, called Wdm1, Wdm2, and Wdm3, gradually implement more features. From the start, they provide a shared memory buffer so they could form the basis for other useful drivers. Indeed, the Wdm2 driver was used as the base for several other drivers in the book, including drivers that use the system drivers.

The DebugPrint software is used throughout the book to provide trace debugging output from drivers. The DebugPrint driver is examined in full in Chapter 14. You can use DebugPrint in your own device drivers.

WdmIo and PHDIo are general purpose drivers that can be used straightaway to provide access to simple hardware devices. A controlling Win32 program can use a simple but powerful command set to talk to the hardware. These drivers support interrupt-driven I/O. The example applications show how these generic drivers are used to talk to the parallel port.

The UsbKbd and HidKbd drivers both talk to a keyboard attached to the USB bus. The drivers illustrate the techniques required to use the USB and HID class drivers. Finally, the Win32 application HidKbdUser shows how a user mode application can find and talk to a HID device.

Book CD-ROM

The accompanying CD contains all the drivers mentioned previously. The full source of the drivers is included, along with the compiled executables. Each driver has at least one test Win32 program that puts it through its paces. In addition, the book has some other useful Win32 utility programs that aid device driver development. Chapter 4 has full instructions for installing the book software. Most of the test Win32 programs are console applications to make them easy to write and understand; there is no reason why the code should not be in fully fledged windowing or MFC applications.

To obtain the full benefit of the book, you should install all the example drivers and run the Win32 test program. All the drivers include trace debugging statements. If the DebugPrint software is installed, you can see the trace output in the DebugPrint Monitor application.

A full inspection of the source code of each example will bear much fruit. In practice, one learns only by writing real code. Use these example drivers as a starting point, and add features to develop your understanding.

Device Driver Software Tools

There are two types of software available to help you with your device driver requirement as shown in Table 1.1. Driver classes are source code C++ class wrappers that provide much of the default functionality needed by drivers. Generic drivers can be tailored from user mode to talk to many straightforward types of device. OSR have a debugging aid called OSRDDK. Chapter 4 discusses other tools that will be useful to you while developing device drivers.

Table 1.1 Device driver software tools

Company	Web site	Driver classes	Generic driver
Blue Water Systems	www.bluewatersystems.com	WinDK	WinRT
KRF Tech	www.krftech.com		WinDriver
Compuware Numega	www.vireo.com	DriverWorks	DriverAgent
Open Systems Research	www.osr.com

In some cases, a new device driver may not be needed for new hardware. There are off-the-shelf generic products that handle simple I/O, be it memory mapped or in I/O space. Indeed, these may be a better option as NT and Windows 95 may be supported using the same interface, making your code portable. Even a simple NT device driver or Windows 95 VxD is no easy task. These generic drivers may be script-driven. Interrupt latency may be a problem if scripts have to be run when a user mode thread is scheduled. The WdmIo and PHDIo examples in the book are simple generic device drivers.

You may think that you need to write a new device driver to handle a special device attached to a parallel port. Check that you cannot achieve the desired effect using the full Win32 API interface. Perhaps issue asynchronous read or write calls and check for time-outs.

Driver Types Not Covered

This book does not cover writing VxDs for Windows 95 or Windows 98. None of the drivers in this book will run in Windows 95. Windows CE software is not described. This book does not cover printer drivers or virtual DOS drivers.

The device driver model described in this book is the basis of many types of drivers. The details of the following driver types are not covered: file system drivers, video drivers, network drivers, and SCSI drivers.

As mentioned previously, only the USB and HID system drivers are described in detail.

The drivers in this book should run in non-x86 systems. However, they have not been tested there.

A New Frame of Mind

If you have "only" written Win32 application programs, you will find that writing device drivers requires a new frame of mind. There are no windows and messages to manipulate. You do not have the protective arms of Windows to stop you from trampling over other processes and the operating system. Source level debugging is more difficult to set up. Most support libraries are not available — not even the C standard library and the C++ new operator. You even have to use makefiles to build drivers, though it is easy to control the build process from a development tool such as Visual Studio.

As a device driver is a trusted part of the operating system, you can crash the system easily. (I can assure you that you will crash the system during your driver development.) Therefore, it is your responsibility to write safe and dependable code. Comment and test your code well. Check for error return values from every kernel call you make.

Device driver problems are a constant source of difficulty for users and support staff. Please insist that your driver is fully tested before release on an unsuspecting world. Test the driver on a variety of machines.

Device Driver Environment

A device driver works in a demanding environment. More than one user application may be bombarding a driver with requests. A user program with open I/O requests may terminate suddenly. A driver may be running in a multiprocessor PC, with different pieces of the driver running on different processors. In fact, two read requests can be processed simultaneously by the same piece of driver code on two separate processors.

Low-level device drivers have to cope with hardware interrupts that may arrive at any moment. Only one part of a driver should access hardware electronics at a time. You may have to use Direct Memory Access (DMA) to transfer data from your device into memory, or vice versa.

Supporting configurable and hot-pluggable buses also adds to the burden of device driver writers. For example, a Plug and Play device might be removed by the user at any time. Also, the kernel can decide at any time that it needs to stop your device so that it can reassign all the hardware resources.

However, as mentioned previously, using the standard WDM bus and class drivers helps to reduce the amount of effort required to write drivers for certain categories of device.

Terminology and Resources

Device driver writers come face to face with a huge range of terminology. Good specification documents will help hardware and software engineers work together to achieve a common goal.

You will need to understand how your device works. While you may not need to understand the details of its electronic implementation, it certainly helps if you have a working knowledge of its technology. For example, the Universal Serial Bus places certain restrictions on maximum packet sizes. You may need to split up data transfers to meet these requirements.

The Windows Driver Model itself uses many technical terms to describe its operation. I will gradually introduce you to all the structures and concepts needed for writing device drivers.

Each technology has its own specialized terminology. For example, the USB bus refers to interrupt transfers. These bear no relation to hardware interrupts. However, as this is how the USB specification describes its operation, I will stick to using the correct terms. Whenever a new and important piece of terminology is introduced, it is highlighted in italic.

A possible source of confusion is the word "class". Windows class drivers are standard drivers that you can use to access particular types of devices, such USB, HID, or IEEE 1394. In contrast, USB devices are categorized into various device classes. There is one USB device class for printers, another for audio appliances, etc. (Thank goodness I do not use C++ classes in the source code.)

To get you started in the device driver world, Chapter 24 lists many information resources, books, newsgroups, and mailing lists that may be of help. Chapter 24 gives a summary of the PC 99 specification — the hardware and software that should be provided on new Windows computers. Finally, the Glossary explains some of the many acronyms you come across when writing drivers.

Win32 Program Interface

Before I go any further, it is worth looking at how Win32 programs call a device driver. The Win32 specification has various implications for driver writers.

Basic I/O

To Win32 programmers, a device is accessed as if it were a file, using the functions listed in Table 1.2. As well as open, read, write, and close routines, DeviceIoControl provides a driver with the option of providing any special functionality. Consult your Win32 documentation for full details of these functions.

Table 1.2 Win32 Program Interface

Win32 function	Action
CreateFile	Open device file
CloseHandle	Close device file
ReadFile ReadFileEx ReadFileScatter ReadFileVlm	Read
WriteFile WriteFileEx WriteFileGather WriteFileVlm	Write
DeviceIoControl	IOCTL
CancelIo FlushFileBuffers	Cancel any overlapped operations

A device driver provides one or more named devices to the Win32 programmer. If writing a device driver for a dongle that can be attached to any parallel port, the devices might be named "DongLpt1", "DongLpt2", etc. To the Win32 programmer these appear as \\.\DongLpt1, etc. (i.e., with \\.\ at the beginning). Note that when written as a C string this last device name appears as "\\\\.\\DongLpt1".

The CreateFile Win32 function is used to open or create a connection to a device. After the device filename, the next two parameters specify the read and write access mode and whether the file can be shared. CloseHandle is used to close the file handle when you have finished using the device file.

The ReadFile and WriteFile series of functions are used to issue read or write requests to the device file.

DeviceIoControl is used to issue special requests that can send data to a driver and read data back, all in one call. There are many predefined IOCTL codes that can be sent to standard drivers, but you can also make up your own for your driver.

When a process finishes, Win32 ensures that all handles are closed and it cancels any outstanding I/O requests.

One large set of functions deals with file systems. Similarly, serial port communication has its own set of specialised functions. Other operations, such as unloading the device driver or shutting down the system, can also result in your device driver being called.

Overlapped Asynchronous Requests

Win32 supports asynchronous overlapped I/O calls, in which a program issues a read or write request and then gets on with another task. This feature has no impact on a device driver as any user request may be processed asynchronously from the Win32 process. In Windows 98, overlapped I/O requests cannot be issued to disk file systems, but can be issued to ordinary device drivers. Chapter 14 shows how to issue Win32 overlapped I/O requests.

Environment

Any number of Win32 threads could access your device at the same time, so your driver should expect this and cope correctly, even if the action is just to allow exclusive access by one thread. The kernel I/O Manager helps considerably by providing a mechanism for processing your read and write requests one at a time.

Your driver should be prepared to run on a multiprocessor system. Many of your driver routines need to be reentrant to cope with this situation. You have to ensure that your driver can cope with being run on two different processors at the same time, usually in different parts of the driver and possibly at different interrupt levels. Techniques for achieving these goals are described in this book.

Ideally, you should provide a version of your driver for each available CPU platform. This means compiling a DEC Alpha version as well as 80x86.

The end user may not be using English. For most I/O, this is not a problem for a driver.

However, if you log messages to the event log, it is nice to provide messages in a language that matches the administrator's locale. It should be easy to localize any support utilities that you provide.

Finally, your driver can determine whether Windows 2000 is running as a server or as a personal workstation. Server systems might have more memory and do more I/O.

Device Specific Restrictions

In particular cases in which you are writing both the device driver and the user mode code, you may find it useful to put more restrictions on the type of access with which your driver can cope.

For instance, if implementing a particular protocol, you might dictate that a command has to be written first using WriteFile and the results read back using ReadFile. Alternatively, you could ignore WriteFile and ReadFile completely and just use DeviceIoControl with your own IOCTL codes.

Whatever approach you use, make sure that you follow a specification. If you are interfacing your hardware to a system class driver, you will have to work to a specification laid down in the Microsoft Driver Development Kit (DDK). Otherwise, you will have to create a specification for your API that your Win32 colleagues will have to follow.

Other Win32 Access to Drivers

The file metaphor is used for most device driver interactions in Win32 programs. However, Windows calls drivers in other situations. For example, keyboard keypresses arrive in programs as Windows messages. These keypresses come from a device driver. Internally, Windows calls the system keyboard driver using the file metaphor.

Many other specialised aspects of Win32 also use device drivers, DirectInput and DirectDraw to mention two. As another example, Human Input Device (HID) user mode clients use various routines, such as HidD_SetFeature, that end up as a driver call.

All these different ways of accessing drivers from Win32 end up as calls using the file metaphor. Therefore, all WDM and NT style device drivers have the same basic structure as they process the same sorts of calls.

Conclusion

In this book, I will explain the Windows Driver Model, including how to write device drivers that work in Windows 98 and Windows 2000. I will also cover NT style drivers that work in Windows NT 3.51 and NT 4.

A driver writer has a job completely different from a standard Windows programmer. There is much terminology to learn and each type of device has its own detailed hardware and software specifications. However, in the end, a device must be made available to Win32 programs and users.

Before writing a device driver in earnest, the next couple of chapters look at the big picture: device driver design and the crucial concepts and structures needed in the driver model.

If you are itching for something to do, order your MSDN Professional subscription. Install the MSDN library, the DDKs, and the Platform SDK. If you are writing a driver for both Windows 98 and Windows 2000, either set up a dual boot machine or get another test computer to hand.

A device driver has many jobs to do, some mandatory and others optional. In this chapter, I will give an overview of these jobs, so you know what tasks your driver will have to implement. I will also describe the big picture to show the different types of device drivers and the environment in which drivers run. If possible, you should consider writing a driver that uses one of the Windows Driver Model system drivers, as it simplifies your work and makes it fit in.

Choosing how to implement your driver is one of the most crucial decisions you will need to make. You need to know which jobs it must perform and which tasks it can offload to a class driver. If you are writing a driver for a Universal Serial Bus (USB) device, it soon becomes obvious that you should use the USB class driver. However, if you are going to support Power Management, it is best to decide this at the start as it may well effect the rest of your design.

Device Driver Components

Here are some of the jobs that a device driver can do:

• Initialize itself

• Create and delete devices

• Process Win32 requests to open and close a file handle

• Process Win32 Input/Output (I/O) requests

• Serialize access to hardware

• Talk to hardware

• Call other drivers

• Cancel I/O requests

• Time-out I/O requests

• Cope if a hot-pluggable device is added or removed

• Handle Power Management requests

• Report to administrators using Windows Management Instrumentation and NT events

Figure 2.1 Device driver components

Figure 2.1 shows how I have divided up a device driver's functionality into different modules. The figure also shows the filenames that I have used for the modules in this book.

Strictly speaking, only the Initialization module is mandatory. In practice, all drivers have dispatch routines to handle user I/O requests. A WDM device driver needs a Plug and Play module, along with an installation INF file. NT style drivers will usually create their devices in their Initialization routine and delete them in an Unload routine. All other modules are optional, though in WDM drivers it is best to write minimal Power Management and Windows Management Instrumentation modules, simply to pass any requests to lower drivers.

Obviously, there will be many interactions between these different modules. Some of these interactions will be direct function calls. However, a lot of information will be passed in data structures. For example, a "device object" data structure stores information about each device.

If writing your first driver, you will no doubt be keen to know how to process reads and 1 writes. As the figure shows, the module that handles these basic I/O requests is a depressingly small part of the whole device driver. The only consolation I can offer is this: if you base your driver on one of the examples in this book, you should be able to concentrate on your device's functionality. However, you cannot ignore what is going on in all the other modules.

Driver Entry Points and Callbacks

The kernel usually runs code in your driver by sending I/O Request Packets (IRPs). For example, a Win32 ReadFile call arrives in a device driver as a Read IRP. The size and location of the read buffer are specified as parameters within the IRP structure. The IRP structure is fundamental to device drivers. I shall be looking at IRPs more in the next chapter, and throughout the rest of the book.

A driver has one main initialization entry point — a routine that you must call DriverEntry. It has a standard function prototype. The kernel calls your DriverEntry routine when your driver is loaded, as is shown in Chapter 4.

Subsequently, the kernel may call many other routines in your driver. These routines are given the general name of callbacks. You tell the kernel the name of the routine and later on the kernel calls the routine back in the right circumstances. For example, if you want to handle interrupts, you must tell the kernel the name of your Interrupt Service Routine (ISR) callback. Each callback has a standard function prototype, appropriate for the circumstance in which it is called.

Table 2.1 lists all the driver entry points and callbacks. I will briefly describe these routines in this chapter and fully explain them later in the book, so do not worry about the details yet. New drivers can also provide a Common Object Model (COM) interface to the kernel, a defined series of routines that the driver implements.

Table 2.1 Standard driver entry points and callback routines

DriverEntry	Initial driver entry point. Sets up main callbacks.
I/O Request Packet (IRP) handlers	Called to process the IRPs that you wish to handle.
Unload	Unload the driver.
AddDevice	A new Plug and Play device has been added.
StartIo	A callback to handle IRPs serially.
Interrupt Service Routine (ISR)	Called to handle a hardware interrupt. Usually schedules a Deferred Procedure Call to do most interrupt servicing.
DpcForIsr	Deferred Procedure Call routine. Starts off another interrupt-driven transfer or completes an I/O request.
Critical section routine	Called to synchronize execution on one processor with no interrupts. Called by low IRQL tasks to interact with hardware
Cancel	Called to cancel an IRP
Completion	Called when a lower-level driver has completed processing an IRP. This lets the current driver do more work.
AdapterControl	Called when a DMA adapter channel is available.
ControllerControl	Called when a controller becomes free. NT and W2000 only.
Timer	A one-second timer callback.
CustomTimerDpc	For time-outs of less than one second.
CustomDpc	Usually used to handle work queues.
Reinitialize	Called if a driver takes a long time to initialize itself.
ConfigCallback	Query device hardware description callback. NT and W2000 only.
Plug and Play Notification	Called to notify you when devices have arrived, when the hardware profile changes, or when a device is being removed.
Callback	W2000 callback object handler

Dispatch Routines

A driver's DriverEntry routine must set up a series of callbacks for processing IRPs. It also sets the Unload, AddDevice, and StartIo routine callbacks, if these are needed. Table 2.2 shows the common Win32 device I/O functions and their corresponding IRPs. For example, a call to CreateFileends up as a create irp sent to your driver.

Table 2.2 Dispatch routine IRPs

Win32 function	IRP
CreateFile	Create IRP
CloseHandle	Close IRP
ReadFile, etc.	Read IRP
WriteFile, etc.	Write IRP
DeviceIoControl	IOCTL IRP
	Internal IOCTL IRP

One common IRP cannot be generated from user mode code^[1]. The Internal IOCTL IRP can only be generated from within the kernel. This allows drivers to expose an interface that cannot be used from Win32. These Internal IOCTLs are often made available by generic drivers. For example, the Universal Serial Bus (USB) class drivers only accept commands in Internal IOCTLs; they do not support ordinary reads and writes.

The handlers of the Create, Close, Read, Write, IOCTL, and Internal IOCTL IRPs are commonly called dispatch routines because they often perform only some initial processing of the IRP, such as checking that all the parameters are valid. They then dispatch the IRP for processing elsewhere within the driver. Quite often, IRPs need to be processed serially so that the driver interacts with hardware in a safe way.

Processing in these basic routines is not quite as straightforward as you might think. Two or more IRP dispatch routines may be running "simultaneously". The problem is particularly acute in multiprocessor systems, but can easily happen when there is just one processor. For example, a dispatch routine on a single processor may block waiting for a call to a lower driver to complete. Or the dispatch routine's thread may run out of time in its execution slot. In both cases, another IRP dispatch routine may called. In due course, this second IRP will block or be completed, and work will continue on the first IRP. This is a common scenario and much of the difficult work of a driver is coping correctly with synchronization issues.

Creating Devices

How do devices come to exist in the first place? Quite simply, you have to create them, either in your DriverEntry routine or when the Plug and Play (PnP) Manager tells you to. In due course, you will delete the devices when your driver unloads or when the PnP Manager tells you that the device has been removed.

Most WDM device objects are created when the PnP Manager calls your AddDevice entry point. This routine is called when a new device has been inserted and the installation INF files indicate that your driver is the one to run. After this, a series of PnP IRPs are sent to your driver to indicate when the device should be started and to query its capabilities. Finally a Remove Device PnP IRP indicates that the device has been removed, so your device object must be deleted.

NT style drivers create their devices when they want to. Usually their DriverEntry routine roots around to find any hardware that can be represented as a device. For example, the system parallel port driver finds out how many parallel ports have been detected and creates an appropriate kernel device object for each one. The driver's unload routine is usually responsible for deleting any device objects.

How do user mode programs know what devices exist? You must make a symbolic link for each device object that is visible to Win32. There are two different techniques for making these symbolic links. The first is to use an explicit "hard-coded" symbolic link name. The user mode program must similarly have the device name hard-coded into its source^[2]. The alternative is to use device interfaces, in which each device interface is identified by a Globally Unique Identifier (GUID). Registering your device as having a particular device interface creates a symbolic link. A user mode program can search for all devices that have a particular GUID.

Hardware Resource Assignments

Low-level drivers need to know what hardware resources have been assigned to them. The most common hardware resources are I/O ports, memory addresses, interrupts, and DMA lines. You cannot just jump straight in and access an I/O port, for example. You must be told that it is safe to use this port.

WDM drivers that handle Plug and Play (PnP) IRPs are informed of a device's resources when the Start Device PnP IRP is received. An NT style driver must find what resources each device needs and request use of them.

A significant number of drivers will not need any low-level hardware resources. For example, a USB client driver does not need any hardware resources. The USB bus driver does all the nitty-gritty work of talking to hardware, so only it has to know about the hardware resources that the electronics use. A USB client driver simply has to issue requests to the bus driver. The USB bus driver talks to the hardware to do your job.

Calling Other Drivers

WDM drivers spend a lot of time talking to other drivers. A Plug and Play device is in a stack of device objects. It is very common to pass IRPs to the next device down the stack.

Some types of IRP, such as Plug and Play, Power Management, and Windows Management Instrumentation IRPs, are often passed immediately to the next device. Only minimal processing is required in a driver.

In other cases, a driver's main job is achieved by calling the next device down the stack. A USB client driver often calls the USB bus drivers by passing an IRP down the stack. Indeed, a driver often creates new IRPs to do this same job. For example, it is quite common for a Read IRP handler in a USB driver to do its job by issuing many Internal IOCTL IRP requests to the USB bus drivers.

Serializing Access to Hardware

Any device that accesses hardware has to use some mechanism to ensure that different parts of the driver do not access the hardware at the same time. In a multiprocessor system, the Write IRP handler could be running at the same time on two different processors. If they both try to access hardware then very unpredictable results will occur. Similarly, if an interrupt occurs while a Write IRP handler is trying to access hardware, it is quite likely that both tasks will go seriously wrong.

There are two different mechanisms to sort out these sources of conflict. First, Critical section routines are used to ensure that code cannot be interrupted by an interrupt handler, even on another processor.

Second, you should use StartIo routines to serialize the processing of IRPs. Each device object has a built in IRP queue. A driver's dispatch routines insert the IRPs into this device queue. The kernel I/O Manager takes IRPs out of this queue one by one, and passes them to the driver's StartIo routine. The StartIo routine, therefore, processes IRPs serially, ensuring no conflict with other IRP handlers. The StartIo routine will still need to use Critical section routines to avoids conflicts with hardware interrupts.

If you hold an IRP in any sort of queue, you must be prepared to cancel it if the user thread aborts suddenly or it calls the Win32 CancelIo function. You do this by attaching a cancel callback routine to each IRP that you queue. Cancelling can be tricky, as you have to cope if the IRP has been dequeued and is being processed in your StartIo routine.

If the user mode application closes its file handle to your device with overlapped requests outstanding, you must handle the Cleanup IRP. The Cleanup IRP asks you to cancel all IRPs associated with a file handle.

Talking to Hardware

Once you have an address for an I/O Port or memory, it is straightforward to read and write hardware registers and the like. You should not hog the processor for more than 50 microseconds. Consider using system threads or system worker threads, described later, if you need prolonged access to hardware.

Handling interrupts is slightly more complicated. As mentioned earlier, you have to register your Interrupt Service Routine. This must check whether your device caused the interrupt and act on it as soon as possible.

However, this is where is gets complicated. It is not safe for an interrupt handler to call most kernel functions. If an interrupt signals that the last part of a Write request has completed, you will want to tell the I/O Manager that you have completed processing the IRP. However, interrupt handlers cannot do this job. Instead, interrupt handlers must ask for your driver's Deferred Procedure Call (DPC) routine to be run in due course. Your DPC routine can use most kernel functions, thus letting it complete IRPs, etc.

Some drivers must set up Direct Memory Access (DMA) transfers of large amounts of data from devices into memory, or vice versa. DMA is usually done using the shared system DMA controllers. However, some new devices have a built-in bus mastering capability that lets them use DMA themselves. I will not explain how to set up DMA transfers. However, Chapter 24 describes the new DMA routines for the benefit of NT 4 driver writers.

Hardware Problems

As we all know, hardware is bound to go wrong (unlike our software:-). You should be able predict the common ways in which hardware problems arise: interrupts will not arrive, buffers will overrun, printers will run out paper, and cables will be disconnected. Some of these problems are timing related. You will have to ensure, as far as possible, that your driver is available at all times to process fast I/O events.

Make sure that you check all hardware status bits (e.g., the out-of-paper indication). Further, ensure that a valid error message gets back to the user mode application.

If things go wrong, make sure you implement time-outs and retry the transfer, if appropriate. The I/O Manager provides an easy way to check time-outs with a granularity of one second. However, it is straightforward to implement a timer for smaller intervals. If a transfer still fails after a few retries, you will have to abort the IRP and signal an appropriate error.

Power Management

If a device's power consumption can be controlled, its driver should support Power Management in W98 and W2000. This applies to both WDM and NT style devices. Power Management conserves battery power in portables and reduces energy consumption and wear in desktop systems. Conversely, some people will have a sleeping or hibernating system on all the time so that it can start up again quickly.

Power Management happens on a system-wide and device-specific scale. The Power Manager can request that the whole system powers down. There are six system power states, including fully on and off, with three sleeping and one hibernating state in between. At a device level, there are four device power states, with two sleeping states in between fully on and off. A device can power itself down even if the rest of the system is running at full speed.

Drivers support Power Management by handling the Power IRP. Quite a few drivers will just pass the Power IRP down the stack of devices. However, your driver will probably be the only one that knows how to change the power usage of your device, so you will have to support the Power IRP correctly.

Windows Management Instrumentation

If possible, a driver should implement the Windows Management Instrumentation (WMI) extensions for WDM. This reports diagnostic and performance information to engineers and management. Drivers make data sets available on request and can fire events when they want. Driver methods can be invoked on demand.

Drivers support WMI by handling the System Control IRP. Again, some drivers will just pass this IRP down the device stack.

You can either use standard WMI data or event blocks or you can define your own new ones in MOF format. These must be compiled and included as a resource in your driver.

NT Event Reporting

The system event log is available in NT and Windows 2000. This is the traditional way of reporting driver problems and should still be supported, if possible. Drivers build an error log entry with an event number and possibly some strings and data. The system event log combines the event number with message strings included in a driver's resources.

System Threads

A system thread lets you do some work "in the background". A system thread could talk to very slow devices, or do some lower priority post-processing of data. Alternatively, existing system worker threads let you queue a work item for execution at lower priority.

Types of Device Driver

This section gives a picture of where device drivers fit in the general scheme of things, and the different types of driver that exist.

Windows Overview

Figure 2.2 shows a general driver schematic of Windows. User mode programs usually run in Win32 or the Virtual DOS Machine provided for DOS and Win 16 applications. NT and W2000 also support other subsystems, such as OS/2 and Posix, but I think these are little used. Most user mode calls end up as requests to kernel mode.

The kernel mode executive services do any security and parameter checking that is appropriate before passing the request onto other parts of the kernel. In NT and W2000, a portion of the Win32 functionality is implemented in the kernel to achieve good performance. In particular, this Win32k.sys driver includes the Graphics Display Interface (GDI) engine. Print and display drivers live in here; these drivers are not covered by this book. Video requests are then processed by a generic video port driver. This port driver uses video miniport drivers to talk to specific display adapters.

Windows 95 and Windows 98 use Virtual Device Drivers (VxDs) to talk to hardware. These are not covered by this book. Windows NT, Windows 2000 and Windows 98 use WDM or NT style device drivers to talk to hardware. In NT and W2000, a Hardware Abstraction Layer (HAL) provides a portable interface to actual hardware.

Figure 2.2 Windows systems

I/O Request Processing

Figure 2.3 shows how an action by a user ends up being processed by device drivers. An application program makes a Win32 call for device I/O. This is received by the I/O System Services. The I/O Manager builds a suitable I/O Request Packet (IRP) out of the request.

In the simplest case, the I/O Manager just passes the IRP to one device driver. This interacts with hardware and, in due course, completes work on the IRP. The I/O Manager returns the data and results to Win32 and the user application.

It is very common now for an IRP to be processed by a stack of layered device drivers. Each driver breaks down the request into simpler requests. Highest level drivers, such as file system drivers, know how files are represented on disk, but not the details of how to get at the data. Intermediate level drivers process requests further (e.g., by breaking down a large request into a series of manageable chunks). Finally, lowest-level drivers actually interact with the hardware.

Wherever possible, drivers have been designed to be as generic as possible. For example, the SCSI port driver knows how to translate disk data requests into SCSI requests. However, it delegates the issuing of SCSI requests to SCSI miniport drivers that know how to talk to individual types of SCSI adapter.

One useful type of intermediate driver is a filter driver. A filter driver slips in between other driver layers to add functionality without effecting the higher or lower drivers. For example, a filter driver can be used to provide fault-tolerant disk access in which data is written to two separate physical disks to ensure that no data is lost.

Figure 2.3 Device driver calls

Plug and Play Device Stacks

The Windows Driver Model (WDM) redefines driver layering to fit in with the Plug and Play system. A device stack represents the layers of drivers that process requests, as shown in Figure 2.4. A bus driver controls access to all devices on their bus. For example, you must use the USB bus drivers if you want to talk to a USB device.

The bus driver is responsible for enumerating its bus. This means finding all devices on the bus and detecting when devices are added or removed. The bus driver creates a Physical Device Object (PDO) to represent the device it has found. Some bus drivers simply control access to the bus; you can do what you want with the bus once you have control. In other cases, the bus driver handles all transactions on the bus for you.

A function driver that does know how to control a device's main features is layered above the bus driver. A function driver creates a Function Device Object (FDO) that is put in the device stack. In the USB case, the function driver must use the USB class driver to talk to its device. However, in other cases, once the bus driver has given the go ahead, the function driver can access hardware directly.

It is quite possible for more function drivers to be layered on top of the first function driver. An example of this is given shortly.

Various types of filter drivers can be slipped into the device stack. Bus driver filters are added above the bus driver for all devices on the bus. Class filter drivers are added for all function drivers of a specific class. Device filter drivers are added only for a particular device. Upper-level filter drivers go above the function driver, while lower-level drivers go below.

It is important to realize that user requests always enter at the top of a device stack. Suppose a user program has identified a function device to which it wants to talk. The I/O Manager ensures that all its requests are sent to the top of the device stack, so that any higher filter or function drivers get a chance to process the requests first.

Figure 2.4 Generic WDM driver stack

Standard Bus and Class Drivers

Figure 2.5 shows the main class and bus drivers that are provided with Windows. These are general purpose drivers that can act as bus drivers and as function drivers. In most cases, the main system driver is accompanied by another driver that interfaces with hardware or another class driver. These helper drivers are usually called minidrivers but can be called miniclass or miniport drivers. For example, the Human Input Device (HID) class driver uses minidrivers to talk to hardware. One minidriver is provided to talk to HID devices on the USB bus. This HID minidriver translates requests from the HID class driver into requests to the USB bus driver.

I will discuss only the HID and USB class drivers in detail. Please consult the Driver Development Kit (DDK) documentation for details of the other system class and bus drivers. Any driver that uses a bus or class driver is often called a client driver.

Figure 2.5 Bus and class drivers

The Advanced Configuration and Power Interface (ACPI) bus driver interacts with the PC ACPI BIOS to enumerate the devices in the system and control their power use. The Peripheral Component Interconnect (PCI) bus driver enumerates and configures devices on the PCI bus. The PnPISA bus driver does a similar job for Industry Standard Architecture (ISA) devices that are configurable using Plug and Play.

The Stream class driver provides a basis for processing high bandwidth, time critical, and video and audio data. The stream class driver uses minidrivers to interface to actual hardware. Filter drivers can be written to transform data. In addition, a USB Camera helper minidriver is provided to make it easier to manage USB video and audio isochronous data streams.

The Stream class makes it easier to expose the different aspects of a piece of hardware as different subdevices. The audio Port class driver helps this further by using COM to identify the subdevices. Audio port and miniport are used to control the actual hardware.

The IEEE 1394 bus driver enumerates and controls the IEEE 1394 (Firewire) high speed bus. This bus driver uses port drivers to talk to the IEEE 1394 control electronics. IEEE 1394 client drivers issue IEEE 1394 Request Blocks (IRBs) to control their device.

The Universal Serial Bus (USB) bus driver enumerates and controls the lower-speed USB bus. Host controller drivers are provided as standard to talk to the two main types of USB host controller. USB client drivers use various IOCTLs to talk to their device via the USB class driver. The most important IOCTL lets clients issue USB Request Blocks (URBs) to control their device.

The SCSI and CDROM/DVD drivers are used to access hard disks, floppies, CDs, and DVDs. As usual, a variety of port and miniport drivers are used to talk to hardware. For example, requests to a CD-ROM on the IEEE 1394 bus would be routed to the IEEE 1394 bus driver.

The Human Input Device (HID) class driver provides an abstract view of input devices. The actual input hardware can be connected in different ways that are shielded by HID minidrivers. Quite a few HID devices are on the USB bus, so a HID minidriver for the USB bus is provided as standard. HID clients can either be user mode applications or, if need be, kernel mode drivers. Standard parsing routines are available to make sense of HID input and output reports.

Finally, the Still Image Architecture (STI) is not a driver at all, but a means of obtaining scanner and still image camera using minidrivers. STI currently supports SCSI, serial, parallel, and USB devices.

Example Driver Stack

With all these different types of drivers lurking around, it is worth while having a look at one real example to see how it all fits together. You do not need to know the detailed terminology yet.

Figure 2.6 shows the hardware and software components that are involved in the handling of a HID keyboard attached to the USB bus. On power up, the PCI bus driver finds the USB controller and so loads the USB class drivers. In this case, the USB OpenHCI host controller driver is used to talk directly to the hardware.

The USB host controller electronics detects when the keyboard is plugged in. The USB root hub bus driver is informed. It tells the Plug and Play Manager that a new device has arrived. The keyboard Hardware ID is used to find the correct installation INF file. In this case, the HID class driver and its USB minidriver are loaded, along with the standard HID keyboard client driver.

The HID keyboard driver uses Read IRPs to request keyboard data. The HID class driver asks the USB minidriver to retrieve any HID input reports. The minidriver uses an Internal IOCTL to submit URBs to the USB class drivers to read data. The USB class drivers talk directly to USB host controller electronics to get any available data. The electronics finally generates the correct signals on the USB bus. These are interpreted by the USB keyboard and it returns any keypress information. The results percolate up the device stack and will eventually reach a Win32 program in message form.

Figure 2.6 also shows that a user mode HID client can access the HID keyboard using standard Win32 ReadFile and WriteFile requests.

Figure 2.6 HID USB keyboard example

Driver Choices

You need to evaluate all the information in this chapter so you can decide at the outset what sort of driver to write for your device. There are various factors and choices that will influence your decisions.

Off-the-Shelf Drivers

The simplest approach is to buy an off-the-shelf driver that handles your device directly. Such drivers might not be available. However, there are various commercial general purpose drivers available, as described earlier. These can be tailored with scripts or the like to interact with many simple devices. The PHDIo and WDMIo drivers described later in this book can be used to talk to devices with I/O ports and a simple interrupt handling requirement.

Use Standard Drivers

If at all possible, you should use one of the standard bus or class drivers, as these will usually have implemented a large amount of the functionality that you need. Indeed, for many types of devices, using the system driver is the only way to access it. The only drawback is that you will have to study the detailed documentation in the DDK for the class of device that you are using. However, I can assure you that it is a darn sight easier to write a USB client than having to write a huge monolithic USB driver from scratch.

Operating System

If using a standard bus or class driver, you will usually be writing a driver that supports Plug and Play. Your driver should usually, therefore, run in W98 and W2000.

Most of the standard bus and class drivers are not available in NT 4 and earlier. In fact, any driver that supports NT 4 or earlier must be an NT style driver. In some cases, it still makes sense to write an NT style driver for W98 and W2000.

Layered Device Drivers

Plug and Play drivers are always layered drivers, as they always form a layer in a device stack. However, NT style drivers can also layer themselves over other drivers. Drivers in a device stack will receive IRPs sent to any of the devices in the stack.

It is quite possible for a driver to use a device stack but not include itself in the stack. For example, drivers that use Plug and Play Notification are usually NT style drivers. Whenever a suitable device is inserted, such a driver will want to use the device. It can layer itself into the device stack, and so receive all IRPs sent to the device stack. Alternatively, it can just store a pointer to the device object at the top of the device stack. This way, it can issue requests to the device without receiving unwanted requests from above. The HID client driver described in Chapter 23 shows how to use this technique.

Monolithic Drivers

It will soon become evident that in some cases, you need to write a low-level driver to talk to your device. The question now is whether yours is a general purpose device or not. If it is has just one specialized use, then writing a monolithic driver to handle all device requests may well be the simplest solution.

However if you want your device to interface into Windows smoothly, you will usually [ need to write a suitable minidriver, miniclass, or miniport driver. The DDK and supporting documentation must be used to determine the exact requirements for these types of drivers. In extreme cases, you may decide to write a whole new class driver, but I would not recommend it.

Recommended and Optional Features

As mentioned earlier, your driver should support Power Management, Windows Management Instrumentation (WMI), and NT event reporting. It is best to build in Power Management support from the beginning. It is possible to bolt on the other two aspects later. However, if you wish to collect performance information for your WMI reporting, it is best to design this in from the start.

WDM Rationale

I am willing to hazard a few comments about the Windows Driver Model (WDM) design to give you my ideas of how well it achieves its goals.

It is the role of device drivers to interface the operating system to hardware devices. They must eventually support the information flows that users and their applications require. In Windows, the specification of Win32, with multiple processes and threads, has implications for device drivers. And a user requirement for fast processing of video and audio data means that device drivers now have to do much more than just receive and send data.

One Core Model

Device drivers have to process a wide variety of data. The simplest example of input data is a keyboard keypress. Keypresses do not happen very often, but they do need to get to an application with visual feedback provided quickly. The next important type of data is the blocks of data that make up file systems. Speed and data integrity are the crucial issues here. Finally, for isochronous data, being able to keep up with the data is the most important factor, even if it means dropping some samples.

The Windows Driver Model defines one basic model to handle all these types of data. In effect, the model is extended for each type of device. For example, the USB class drivers provide an abstract model for all USB devices, with a defined interface that is used by all client drivers. Having a core driver model that is common to all device types makes it easier for driver writers to move from one type of device to another. And it also means that the kernel implementation of the driver model is more likely to be solid. Having a different model for each type of device would almost certainly make life harder for us.

Is this extensible core model too complicated? If you are writing a monolithic simple low-level driver, I think that IRPs will appear to you as quite difficult beasts. Supporting Plug and Play properly is a task too onerous for simple drivers, as described in the following text.

Complexity

Any discussion of device drivers can be fairly "heavy". By their very nature, you have to interact with complicated hardware systems that may have exacting timing constraints. Any operating system interface to hardware will have a complicated job to do. Another factor is that each type of device is different, so you need to know about the details of its technology, including its hardware implementation. For example, the network device drivers field is a subject that can easily fill a whole book. All this means that any aspiring device driver writer will have a steep learning curve.

Plug and Play and Layers

When Plug and Play is first described to you, it will probably sound fairly straightforward. You are told when a device arrives. You are told when it leaves. However, some of the follow-on implications are hard work for device drivers. In a brief look, I am not convinced that any of Microsoft examples do the job fully.

The first problem is that the sudden removal of a device will interrupt a whole host of activities that your driver may be doing. However, I guess that there is no easy way round this.

A stickier problem occurs when the Plug and Play (PnP) Manager tries to juggle the system resources when a new device is inserted. The PnP Manager can ask to "stop" your device (i.e., pause it while your resource assignments are changed). Again, this may interrupt the current flow of operations. However, more importantly, you are supposed to queue up any received IRPs while your device is stopped^[3]. At worst, the user is only supposed to experience a tiny delay in the functioning of a device that is paused temporarily. However, implementing an IRP queue is not a trivial exercise, especially as you have to be prepared for the worst. For example, if a device is removed while stopped, you will have to chug through all the queued IRPs completing them with an appropriate error status. (The Ks… series of Kernel Streaming IRP handling routines might provide all this functionality.)

Another potential criticism of the Plug and Play system is that too many layers of drivers are involved. Passing requests between layers can take some time. If a request has to pass through many layers of filter drivers, it could have a noticeable effect on performance.

Range of Functionality

For good reasons, device drivers cannot use many standard C or C++ functions. This makes it more complicated for driver writers as they have to learn what routines to use instead. I find the Unicode string handling routines particularly unwieldy.

I understand that Microsoft is trying remove some older areas of functionality. For example, WMI is effectively going to replace NT events. However, you have to support both in the mean time, which is more effort.

Development Environment

There is plenty of documentation available in the various DDKs. However, it is slightly confusing to have Windows 98 and Windows 2000 DDKs covering the same subject. As is usual, the documentation lags a few months behind when any new developments arise, which can be frustrating. It is worth while checking the relevant Microsoft websites regularly for appropriate articles.

The provision of lots of example source in the DDKs is great. Give us more! These show how real drivers work and show us how to use various kernel calls and techniques.

The driver build environment is still essentially command line. Although it is easy enough to provide a Visual Studio wrapper for this build environment, a fully integrated system would be appreciated. The provision of a nice debugger that can be run on the same computer as the driver you are testing would be a boon.

Developer Support

You will have to make do with the DDK documentation and any colleagues that you can find to help out. First, scour the DDKs, the DDK source, documents in the DDK source, the Microsoft website, and the Platform SDK. Your next port of call might well be the newsgroups and mailing lists. Finally, you can pay Microsoft for help.

Conclusion

In this chapter, I have tried to give the device driver big picture, showing what components your driver will need and how it fits into the general scheme of things. There are different types of device driver and different ways of implementing the same driver functionality. Some driver components are not compulsory, but it is certainly recommended that you support Plug and Play, Power Management, and Windows Management Instrumentation, if possible.

A crucial part of the Windows Driver Model is the provision of several bus and class drivers. These make it considerably easier to write many types of driver.

In the next chapter, I will look at the crucial background concepts that are needed before device driver development in earnest.

Introduction

This chapter introduces the basic concepts and structures that you will need to write drivers. Some ideas are sufficiently important and deserve to be mentioned now. All the other techniques, routines, and objects are covered in the following chapters.

Windows uses a layered design for passing requests from the end user to a driver stack and eventually to the hardware. As a trusted part of the operating system, a driver must be written well to fit into the kernel. It should use the kernel's abstract model of the processor and use memory carefully. Wherever possible, a driver should use the recommended techniques, routines, and structures.

Driver Design Guide

A good device driver needs to be well written. Remember that it is a trusted part of the operating system. The PC will not get the protection that a normal Win32 application has. If anything goes wrong, it is likely that the system will crash, or worse — destroy valuable data before crashing.

For important projects, my ultimate design philosophy is to design code three times. At the outset, it is definitely worth while knowing where I am going and what features I am going to implement. I then prefer an incremental approach, in which each individual section of code is designed as I go along. However, as with many programs, it often only when I have finished a first-cut prototype of the whole driver that I really understand what is going on.

Doing some real hardware interactions might invalidate some of my initial design decisions. Similarly, I might decide to expose an IOCTL interface instead of reads and writes. In the end, it might be best to scrap some sections of code and start again^[4].

Documentation

It is particularly important that you document your driver well and provide ample comments in your code. Device drivers are complicated enough at the best of times. Having to look at someone else's code without any explanation of what is going on can be difficult.

Your hardware and firmware engineering colleagues should have provided you with a suitable interface specification for the device you have to control. You will bring these requirements together with the specification of any bus or class drivers you intend to use. At the end of the day you will have specified your driver's lower edge — the hardware and software interactions that you use to get your job done.

Similarly, you should define your upper edge. This is the interface that your driver presents to user mode applications or higher-level drivers. You need to define what devices you make available and which Win32 functions can be used to access the devices. Specify the parameters in detail and the contents of all buffers. Give your Win32 colleagues a suitable header file.

Good Design

Whatever your approach, a good design needs to be configurable, portable, preemptive, interruptible, and multiprocessor-safe.

A driver should be as configurable as possible — at least as configurable as the hardware allows. A device on a configurable bus ought to have a Plug and Play driver. Use the registry and the control panel to control how a driver runs.

Making a driver portable between platforms is usually fairly straightforward. Drivers should be easily recompiled to support non-x86 processors. WDM drivers need to run on W98 and W2000. Make sure that you only use routines that are available on both platforms. Write the driver in C or C++ and avoid using assembly language. Use the appropriate kernel routines to access hardware. Beware of data types that have different sizes on different processors. Other processors may have different virtual memory page sizes.

When your driver is running at a low interrupt level (see the following text), the operating system may perform a context switch at any time. Remember that higher priority interrupts can occur at any time, so your driver must bear this in mind. Even your ISR can be interrupted.

In an NT/W2000 multiprocessor system, your driver could be called simultaneously on different processors, so the code needs to be reentrant. As NT/W2000 supports symmetric multiprocessing, an interrupt may be handled on any processor. Even on a single processor system, your code needs to be reentrant. Your code could block while processing one IRP, or a context switch could occur. This could allow another IRP to start processing before the first IRP has completed.

Various techniques and routines are used to handle interrupts and multiprocessor systems. For example, critical sections ensure that a device operation is not interrupted. Spin lock tokens can guard access to work queues. Various dispatcher objects (events, Mutexes, semaphores, timers, and threads) can be used to signal conditions and synchronize with the other parts of your driver.

The kernel also provides mechanisms to arbitrate access to shared hardware devices such as the system DMA controllers. In NT7W2000, if your own hardware has a controller that is shared between devices, use the Controller object to arbitrate access, rather than rolling your own.

Look to see if the kernel already provides you with a feature (e.g., string manipulation facilities and management of a pool of memory blocks). These facilities are discussed as appropriate throughout the book.

A good driver checks each and every return value from any routines that it uses (e.g., in the kernel or other drivers). If an error occurs, make sure you rollback your transaction correctly before returning the error.

The layered device driver design

By now you will, of course, be writing Y2K-compliant code. However, this problem may not occur all that often in drivers. If appropriate, your driver should include accessibility options for people who have difficulty performing certain tasks. Bear in mind that many of your users may not use English as their first language, so internationalize as necessary. For example, provide different language event messages. Note that the strings that drivers must use are in Unicode.

Finally, it is best if you follow the driver routine naming conventions described later. Document and test your work as you go along. At the end, go through all the comments and make sure they are up to date.

Kernel Calls

Device drivers cannot access any standard C, C++, or Win32 functions. You cannot use the C++ new and delete operators. Instead, you must make use of a large number of kernel routines. The main categories of kernel routines are shown in Table 3.1.

The book describes each kernel routine when it is first used. However, I decided not to provide a full list of each function's parameters because it would take up too much room. You may find it useful to have the Driver Development Kit (DDK) documentation to hand. However, I hope that you can follow the thread of the argument without having to sit beside your computer.

If you are using one of the proprietary toolkits listed in Chapter 1, these will provide a set of classes that make drivers easier to write. This includes routines that make it easier to call the kernel. For example, drivers must use Unicode strings when talking to the rest of the kernel. The kernel routines that manipulate Unicode strings are fairly laborious to use. Most proprietary toolkits provide a class wrapper for Unicode strings that makes them easier to use.

There are various Win32 function calls that are used only in connection with device drivers. In particular, the SetupDi… routines are used to find devices that implement a specified device interface.

Table 3.1 Kernel Mode Routines available to drivers

Ex…	Executive Support
Hal…	Hardware Abstraction Layer (NT/W2000 only)
Io…	I/O Manager (including Plug and Play routines)
Ke…	Kernel
Ks…	Kernel stream IRP management routines
Mm…	Memory Manager
Ob…	Object Manager
Po…	Power Management
Ps…	Process Structure
Rtl…	Runtime Library
Se…	Security Reference Monitor
Zw…	Other Routines

Table 3.2 shows routines that are used only by specific types of driver. Most of these are provided for miniclass drivers, miniport drivers, and minidrivers. Others, such as the Hid… and Usb… functions are used by client drivers.

In addition to those routines listed, audio miniport drivers define several standard interfaces. The IEEE 1394 bus driver makes many routines available, with no common initial name.

Table 3.2 Bus driver and class specific routines

BatteryClass…	Battery class routines for miniclass drivers
Hid…	Human Input Device routines
Pc…	Port class driver routines
ScsiPort…	SCSI port driver routines for miniport drivers
StreamClass…	Stream class driver functions for stream minidrivers
TapeClass…	SCSI Tape class routines for miniclass drivers
Usb…	Universal Serial Bus Driver Interface routines for USB client drivers

Kernel Macros

If you look in the DDK header files, you will find that a few of the kernel functions are implemented as macros. The definition of one or two of these macros is quite poor. For example, RemoveHeadList is defined as follows:

#define RemoveHeadList(ListHead) (ListHead)->Flink; {RemoveEntryList((ListHead)->Flink);}

If you call RemoveHeadList in the following way, the wrong code is compiled.

if (SomethingInList) Entry = RemoveHeadList(list);

The only way to make this safe is to use braces.

if (SomethinglnList) {

 Entry = RemoveHeadList(list);

}

Therefore, to be on the safe side, it is best to use braces in all if, for, and while statements, etc.

Kernel Objects

The DDK documentation makes much use of the word object when describing kernel structures. This does not mean object in the C++ sense of the word. However, it means the same in principle. In the purest definition, a kernel object should only be accessed using kernel function calls. In practice, each kernel structure usually has many fields that can be accessed directly. However, it is definitely true that some fields should be considered private and not touched by your driver. This book describes which fields can be used safely in each kernel object.

Driver Routine Names

There is a useful convention for naming driver routines, similar to the kernel API naming scheme. Each routine name should have a small prefix based on the driver's name (e.g. Par for a Parallel port driver). This prefix should be followed by verbs or nouns as necessary. This naming scheme makes it easier to identify a driver when looking at a debugger trace. A driver initially has just one exposed routine that must be called DriverEntry so it can found.

Many driver routines have standard names that most people use. For example, the Create IRP handler in the Wdm1 driver is called Wdm1Create; the Read IRP is handled in Wdm1Read, etc.

Processor Model

Windows 98, NT, and Windows 2000 all primarily run in x86 systems. However, NT and W2000 can also run on Alpha processors. To handle any differences, WDM uses a model of a general processor and provides an abstract view of the resources available on the supported processors.

Always use kernel routines to access hardware. For some types of drivers, you do not need to talk to hardware directly. Instead, make the appropriate calls to the relevant bus driver to get it to perform the low-level I/O for you.

Processor Modes

The operating system requires that the processor support only two modes: a user mode for one or more applications to run in and a kernel mode for the bulk of the operating system. User mode programs are protected so that they cannot easily damage each other or the kernel. Conversely, the kernel can do anything it wants to and can access all memory.

Interrupts and exceptions are ways of stopping the processor from doing something and asking it to do something else. A hardware interrupt is an input signal to the processor from external hardware. Software interrupts are instructions that interrupt the processor to switch it to kernel mode. Exceptions are interrupts generated by the processor, usually when something goes wrong.

User programs make kernel function calls using software interrupts. In fact, a Win32 call initially goes to a user mode Win32 subsystem DLL. If appropriate, this then calls the main operating system in kernel mode.

The kernel uses a regular timer hardware interrupt to switch between the available user program threads of execution. This makes it appear that the threads are running simultaneously. On multiprocessor systems, the threads really can be running simultaneously. The kernel can also have its own threads running, which are switched in the same way as user threads.

The result is that drivers can be called in several ways. A user application can issue a Win32 device I/O request. Eventually, a driver is called to process this call. The driver might then start its hardware. If its hardware generates an interrupt, then the driver is called to process it (i.e., stop the interrupt), flag that it has happened, and, if necessary, start another operation. In both these cases, the driver does not necessarily operate in the context of the user application that called it.

Drivers can also be called in the context of a kernel thread. For example, the Plug and Play calls to a driver are usually called in the context of a system thread. As will be shown, this gives the driver more scope to do things. Finally drivers can set up their own kernel mode threads that can run as long as needed, getting their own share of the processor time.

Interrupt Levels

Hardware or software interrupts stop the processor from doing one task and force it to run some interrupt handling code. A processor prioritizes interrupts so that lower priority interrupts can themselves be interrupted by higher priority interrupts. This makes sure that very important tasks are not interrupted by jobs that can be done at a later stage.

Table 3.3 Abstract Processor Interrupt Levels

	IRQL	Description
No interrupts	PASSIVE_LEVEL	Normal thread execution
Software interrupts	APC_LEVEL	Asynchronous Procedure Call execution
	DISPATCH_LEVEL	Thread scheduling Deferred Procedure Call execution
Hardware interrupts	DIRQLs	Device Interrupt Request Level handler execution
	PROFILE_LEVEL	Profiling timer
	CLOCK2_LEVEL	Clock
	SYNCH_LEVEL	Synchronization level
	IPI_LEVEL	Interprocessor interrupt level
	POWER_LEVEL	Power failure level

Table 3.3 shows the interrupt levels that Windows uses to provide an abstract view of the actual processor interrupt levels. The lowest priority interrupt levels are at the top. Hardware-generated interrupts always take priority over software interrupts.

Drivers only use three of these interrupt levels. Somewhat confusingly, driver dispatch routines are called at PASSIVE_LEVEL^[5] (i.e., with no interrupts). Many driver callbacks run at DISPATCH_LEVEL. Finally, driver hardware interrupt service routines operate at Device Interrupt Request Level (DIRQL).

The DIRQLs level in fact represents the many hardware interrupt levels that are available on the specific processor. A disk hardware interrupt level may well have higher priority than a parallel port hardware interrupt, so the disk may interrupt a parallel port interrupt. Usually a driver has just one DIRQL, though there is no reason why it cannot support more, if that is how its hardware works. The relevant driver interrupt level is referred to as its DIRQL.

The interrupt level at which a driver is operating is very important, as it determines the types of operation that can be undertaken. For example, driver hardware interrupt service routines cannot access memory that might be paged out to a swap file.

A driver has to be aware that it could be interrupted by a higher priority task at any stage. This means that its own interrupt service routine could run in the middle of its own dispatch routines. For this reason, if a normal driver routine is about to interact with its own hardware, it uses a kernel function to raise its interrupt level temporarily to its DIRQL. This stops its own interrupt handler from running at the same time. In addition, in a multiprocessor system, another driver routine might be attempting the same task on another processor. The KeSynchronizeExecution routine is used to run such critical sections in a multiprocessor-safe way.

Runtime Priorities

The Interrupt Level should not be confused with the scheduling priority. All threads normally run at the lowest interrupt level, PASSIVE_LEVEL. The scheduler uses the priority values to determine which thread to run next. Any other interrupt takes priority over a thread.

Drivers need to be aware of scheduling priorities. When it completes an IRP, it can give the calling thread a temporary priority boost so that, for example, programs that interact with the mouse can continue their run more quickly. This technique generally improves the perceived responsiveness of the system.

Deferred Procedure Calls

Any routine servicing a hardware interrupt stops normal program execution. For this reason, it is best to make an interrupt service routine as quickly as possible.

Any nonessential interrupt processing should be deferred until later. Windows lets driver writers use Deferred Procedure Call (DPC) routines, which are called at DISPATCH_LEVEL. The interrupt routine requests that the driver's DPC post-interrupt routine (DpcForIsr) is called when things have calmed down. A typical job in this routine is to indicate that the current I/O request is complete; the relevant kernel call can only be carried out at DISPATCH_LEVEL

When writing your driver, be careful to comment the interrupt level at which each routine can be called. Similarly, make only kernel calls that are appropriate for the current interrupt level.

Using Memory

A device driver has to be very careful when allocating or accessing memory. However, it is not as gruesome to access memory as some other types of driver. For example, you do not need to worry about the murky x86 world of segments and selectors, as the kernel handles all this stuff.

Pool Memory

Windows implements virtual memory, where the system pretends that it has more memory than it really has. This allows more applications (and the kernel) to keep running than would otherwise be the case.

Virtual memory is implemented by breaking each application's potential address space into fixed size chunks called pages. (x86 processors have a 4KB-page size, while Alpha processors use 8KB.) A page can either be resident in physical memory, or not present and so swapped to hard disk.

Drivers can allocate memory that can be paged out, called paged memory. Alternatively, it can allocate memory that is permanently resident, called nonpaged memory. If you try to access paged memory at DISPATCH_LEVEL or above, you will cause a page fault and the kernel will crash. If you access nonresident paged memory at PASSIVE_LEVEL, the kernel will block your thread until the memory manager loads the page back into memory.

Please do not make extravagant use of nonpaged memory. However, you will find that most of the memory your driver uses will be in nonpaged memory. You must use nonpaged memory if it is going to be accessed at DISPATCH_LEVEL or above. Your driver StartIo and ISRs, for example, can access only nonpaged memory.

Table 3.4 shows how to allocate both paged and nonpaged memory using the kernel ExAllocatePool function. The table uses the DDK convention of listing IN or OUT before each parameter. IN parameters contain information that is passed to the function, and vice versa. Instances of IN and OUT in DDK header files are removed using macros.

Specify the ExAllocatePool PoolType parameter as PagedPool if you want to allocate paged memory or NonPagedPool if you want to allocate nonpaged memory. The other PoolType values are rarely used. Do not forget to check whether a NULL error value was returned by ExAllocatePool. The ExAllocatePool return type is PVOID, so you will usually need to cast the return value to the correct type.

When you are finished using the memory, you must release it using ExFreePool, passing the pointer you obtained from ExAllocatePool. Use ExFreePool for all types of memory. If you forget to free memory, it will be lost forever, as the kernel does not pick up the pieces after your driver has unloaded.

The ExAllocatePoolWithTag function associates a four-letter tag with the allocated memory. This makes it easier to analyze memory allocation in a debugger or in a crash dump.

Table 3.4 ExAllocatePool function

PVOID ExAllocatePool	(IRQL<=DISPATCH_LEVEL) If at DISPATCH_LEVEL, use one of the NonPagedXxx values
Parameter	Description
IN POOL_TYPE PoolType	PagedPool PagePoolCacheAligned NonPagedPool NonPagedPoolMustSucceed NonPagedPoolCacheAligned NonPagedPoolCacheAlignedMustS
IN ULONG NumberOfBytes	Number of bytes to allocate
Returns	Pointer to allocated memory or NULL

Lookaside Lists

If your driver keeps on allocating and deallocating small amounts of pool memory then it will be inefficient and the available heap will fragment. The kernel helps in this case by providing lookaside lists^[6] for fixed-size chunks of memory. A lookaside list still gets memory from the pool. However, when you free a chunk of memory, it is not necessarily returned to the pool. Instead, some chunks are kept in the lookaside list, ready to satisfy the next allocation request. The number of chunks kept is determined by the kernel memory manager.

Lookaside lists can contain either paged or nonpaged memory. Use ExInitializeNPagedLookasideList to initialize a lookaside list for nonpaged memory and ExDeleteNPaged-LookasideList to delete the lookaside list. When you want to allocate a chunk of memory, call ExAliocateFromNPagedLookasideList. To free a chunk, call ExFreeToNPaged-LookasideList. A similar set of functions is used for paged memory. Consult the DDK for full details of these functions.

Other Memory Considerations

The kernel stack is nonpaged memory for local variables^[7]. There is not room for huge data structures on the kernel stack because it is only 8KB-12KB long.

Drivers need to be reentrant, so they can be called simultaneously on different processors. The use of global variables is, therefore, strongly discouraged. However, you might read in some registry settings into globals, as they are effectively constant for all the code. Local static variables should also not normally be used for the same reason.

Finally, you can reduce your driver's memory usage in other ways. Once the driver initialization routines have completed, they will not be needed again, so they can be discarded. Similarly, some routines may be put into a pageable code segment. However, routines running at DISPATCH_LEVEL or above need to be in nonpageable nondiscardable memory.

Accessing User Application Memory

There are two main techniques for accessing user data buffers. If you use Buffered I/O, the I/O Manager lets you use a nonpaged buffer visible in system memory for I/O operations. The I/O Manager copies write data into this buffer before your driver is run, and copies back read data into user space when the request has completed.

The alternative technique, Direct I/O, is preferable, as it involves less copying of data. However, it is slightly harder to use and is usually only used by DMA drivers that transfer large amounts of data. The I/O Manager passes a Memory Descriptor List (MDL) that describes the user space buffer. While a driver can make the user buffer visible in the system address space, the MDL is usually passed to the DMA handling kernel routines.

DMA

Direct Memory Access (DMA) hardware controllers perform I/O data transfers direct from a device to main memory (or vice versa) without going through the processor. The first implication is that DMA memory cannot be paged. Secondly, the DMA controller has to be programmed with a physical memory address, not a processor virtual address. The kernel provides routines to help with both these tasks.

IRP Processing

I/O Request Packets (IRPs) are central to the operation of drivers. It is helpful to look at them briefly at this point, but they are described in full later. In particular, this section looks at how IRP parameters are stored and how the IRP stack lets an irp be processed by a stack of drivers.

An IRP is a kernel "object", a predefined data structure with a set of I/O Manager routines that operate on it. The I/O Manager receives an I/O request and then allocates and initializes an IRP before passing it to the highest driver in the appropriate driver stack.

An IRP has a fixed header part and a variable number of IRP stack location blocks, as shown in Figure 3.1. Each I/O request has a major function code (such as IRP_MJ_CREATE corresponding to a file open) and possibly a minor function code. For example, the IRP_MJ_PNP Plug and Play IRP has several minor functions (e.g., IRP_MN_START_DEVICE). Table 3.5 lists the common IRP major function codes.

Table 3.5 Common IRP Major Function Codes

IRP_MJ_CREATE	Create or open device file
IRP_MJ_CLOSE	Close handle
IRP_MJ_READ	Read
IRP_MJ_WRITE	Write
IRP_MJ_CLEANUP	Cancel any pending IRPs on a file handle
IRP_MJ_DEVICE_CONTROL	Device I/O control
IRP_MJ_INTERNAL_DEVICE_CONTROL This is also called IRP_MJ_SCSI	Device I/O control from a higher driver
IRP_MJ_SYSTEM_CONTROL	Windows Management Instrumentation
IRP_MJ_POWER	Power Management request
IRP_MJ_PNP	Plug and Play message
IRP_MJ_SHUTDOWN	Shutdown notification

The fixed part of an IRP (the IRP structure itself) contains fixed attributes of the IRP. Each stack location — an IO_STACK_LOCATION structure — in fact contains most of the pertinent IRP parameters.

More than one IRP stack location is used when an IRP might be processed by more than one driver. Each driver gets its irp parameters from the current IRP stack location. If you pass an irp down the stack of drivers for the current device, you must set up the next stack location with the correct parameters. The parameters that you pass down may be different from the ones you are working with.

Figure 3.1 IRP Overview

IRP Parameters

When a write I/O request is made into an IRP, the I/O Manager fills in the main IRP header and builds the first IRP stack location. For a write, the IRP header contains the user buffer information. If you use Buffered I/O, the IRP AssociatedIrp.SystemBuffer field contains a pointer to the nonpaged copy of the user's buffer. For Direct I/O, the IRP MdlAddress field has a pointer to the user buffer MDL.

The IRP stack location has the main write request parameters. The stack MajorFunction field has the IRP_MJ_WRITE major function code that indicates that a write has been requested. The Parameters.Write.Length field has the byte transfer count and Parameters.Write.ByteOffset has the file pointer. The stack also has other important fields that are described later.

As I said earlier, you have to set up the next stack location if you call another driver. This means that you can theoretically change the IRP major function code to something else. While this might work in some cases, it is generally not a good idea, as the parameters in the fixed part of the IRP might not be correct.

However, it might be appropriate to change the number of bytes to transfer and the file pointer. You might do this if you know that the lower driver can only handle short transfers. To handle a large transfer, you might, therefore, send the IRP down several times. Each transfer request you send down will be within the capabilities of the lower driver.

Processing IRPs in a Driver Stack

In practice, the I/O stack locations are not usually used to alter these fundamental IRP parameters. Instead, the IRP stack is normally used to let an IRP be processed by all the drivers in a device stack.

Figure 3.2 shows how an IRP might be processed by four drivers in the device stack. The first IRP arrives at the highest driver, Driver 1. This uses the function IoGetCurrentlrpStack-Location to obtain a pointer to the current stack location. The figure shows that this returns the topmost IRP stack location.

Driver 1 decides that it needs to pass the IRP down the stack for processing. The IRP might be a Power Management IRP that the lowest bus driver needs to see. Driver 1 might not do anything with this IRP, but it still needs to pass the IRP down the stack.

Driver 1 therefore sets up the stack location for the next driver. In many cases, it simply copies the current stack location to the next using the IoCopyCurrentlrpStackLocation-ToNext or IoSkipCurrentlrpStackLocation functions. If you need to alter the next stack location, then use IoGetNextlrpStackLocation to get a pointer to it.

Driver 1 then calls the next driver down the stack using the IoCallDriver function. The I/O Manager now changes the "current IRP stack location" pointer so that Driver 2 sees the second IRP stack location down (the one that Driver 1 set up for it). This process continues until the lowest driver, Driver 4, receives the IRP.

Driver 4 now processes the IRP. When it has finished with the IRP, Driver 4 calls IoCompleteRequest to indicate that it has finished processing the IRP. The IRP travels back up the device stack until it eventually pops out the top and is returned to the user.

Each of the drivers in the stack is given an opportunity to work with the IRP again as it travels up the stack, if they wish to do so. To do this, a driver must attach a completion routine to an IRP using the IoSetCompletionRoutine function. The completion routine information is stored in each driver's IRP stack location. This lets each of the drivers numbered 1 to 3 work on the IRP as it travels back up the stack in the order: Driver 3, Driver 2, and then Driver 1. A driver does not need to attach a completion routine. In this case, the I/O Manager does not call the driver as the IRP passes up the stack.

Figure 3.2 How all drivers in a stack process an IRP

A driver does not have to pass an IRP down the stack. If it detects an error in a parameter, or is able to process the IRP itself, then it should do its job and complete the IRP with IoCompleteRequest.

When a driver processes an IRP as it travels back up the device stack, it does not necessarily let the IRP progress further up the stack straightaway. If Driver 2 for example, splits Write IRPs into small chunks that Driver 3 can digest, then it may send the IRP back down the stack again, with changed parameters.

A further possibility is that a driver can build a new IRP and send it down the stack. Driver 2 might be processing a read request. To satisfy this request, it has to send an IOCTL request to the lower drivers. When the IOCTL request returns, Driver 2 checks that it worked satisfactorily and carries on processing its Read IRP.

To reiterate, an IRP includes a stack of I/O request operations. A driver only looks at the current IRP stack location and does not have to worry if there are higher-level drivers above.

Conclusion

Windows provides a well-defined hierarchy and structure for drivers. Go with the grain and learn how to fit in nicely with the rest of the operating system. Do not forget to cope with multiprocessor machines.

Windows provides a generic model of different processors that may be running. Drivers have routines that run at PASSIVE_LEVEL, DISPATCH_LEVEL, and DIRQL interrupt levels. Use system memory carefully and access user memory using the relevant kernel routines.

The kernel calls a driver in many ways. Most driver processing is in response to I/O Request Packets (IRPs). Conversely, a driver can make use of a whole host of kernel routines. Many system drivers have specific interfaces defined to handle particular I/O control codes. Drivers should use these interfaces wherever possible.

Enough prevarication, let's start on the first real device driver. The following chapters describe the Wdm1 virtual device driver in detail, how it is implemented and used, and how to test and debug drivers.

This chapter writes a simple WDM device driver, called Wdm1. It shows how Wdm1 is built and installed in Windows 98 and Windows 2000. The basics of the driver are explained, but a full explanation of the guts has to wait until the following chapters.

The Wdm1 driver is for a virtual WDM device that does not correspond to any real hardware. For now, the Plug and Play and Power Management support is minimal. The Wdm1 driver implements a shared memory buffer for all Wdm1 devices.

First, I describe how to set up your computer for WDM driver development by installing the various development kits and by setting up Visual Studio. I describe the other useful tools that you will need.

The book software provides a Visual Studio workspace called WDM Book that you can use to compile the drivers and any associated user mode Win32 applications. Be careful if editing within this workspace as the different projects in this workspace often have files of the same name.

System Set Up

The section details what you will have to do to set up your development computer or computers for WDM driver development. This task is laborious, especially as you have to do it at least twice, once for Windows 2000 and once for Windows 98.

You will have to be an Administrative user to install the W2000 Driver Development Kit (DDK) and drivers in Windows 2000.

These instructions assume that you are using Visual C++ for development. While other compilers can almost certainly do the job, most Windows driver writers will be firmly in the Visual Studio camp. Visual C++ also has various useful tools that you will need such as rebase and guidgen. I used VC++ version 5.

You will need a Microsoft Developer Network (MSDN) Professional (or Universal) subscription to get the necessary development kits. While some of these kits are available free online, it is best to get an MSDN subscription to ensure that you receive the most recent releases and beta versions. The Installable File System (IFS) DDK costs extra and is only available currently in the USA and Canada.

DDKs

Install the W98 DDK in Windows 98. Install the W2000 DDK in Windows 2000. Install the Platform Software Development Kit (SDK) and MSDN Library in both versions of Windows. The Platform SDK is not vital, but it has quite a few useful tools.

The DDK tools and documentation are listed in the Start+Programs+Development kits menu. The Platform SDK tools are listed in the Start+Programs+Platform SDK menu.

The SETENV.BAT file in the DDK bin directory is used to set the environment variables for the build process^[8]. Shortcuts to this batch file are set up in the Start menu. It calls other batch files in the bin directory. The current batch files install DosKey; I decided to comment these lines out as I already have a similar command processor installed.

The Platform SDK may have more up to date tools than are supplied with VC++ (e.g., the rebase utility). Put the MSSDK bin directory before the Visual Studio directories on your path.

You may need to add the DDK bin directory to the directories list in VC++.

Currently, the documentation is released in HTML Help format. Each help file is viewed in its own incarnation of the HTML Help viewer, and is not merged into the Visual Studio 97 documentation. The help files are probably merged together in Visual Studio 6.

Each function found in the W2000 DDK states which header files you can use. If wdm.h is listed, the routine can be used in a WDM driver for Windows 98 or Windows 2000. There are some routines that compile correctly in Windows 98 but have no effect, such as the event log writing routines. If the W2000 DDK lists only ntddk.h for a routine, it can be used only in Windows 2000 drivers, not Windows 98. The W98 DDK lists only routines that run in Windows 98.

The W98 DDK and the W2000 DDK are largely the same for WDM drivers. At the time of writing, the W98 DDK does not include the Windows Management Instrumentation libraries. Some header files are also different (e.g., SETUPAPI.H). For some reason, the checked build produced by W2000 seems quite a bit smaller than that produced by the W98 DDK.

Book Software Installation

The source code for the Wdm1 driver is supplied on the book's accompanying disk. Copy the source code directory tree to a fresh directory on your hard disk. These instructions assume that you have installed the software to C:\WDMBook. However, you can change the directory if you wish. If you use a different drive, you will need to alter the settings of every VC++ project, so it will be much easier for you if you can install the software on drive C:.

The WDM Book Visual Studio workspace in the book software base directory contains projects for each of the drivers in the book.

Three steps are needed before the book software drivers can be compiled.

• Ensure that the DDKROOT environment variable is set to the W2000 DDK or W98 DDK base directory.

• Set up an environment variable called WDMBOOK to point to the book software base directory (e.g., C:\WDMBook). In Windows 98, set environment variables by adding them to AUTOEXEC.BAT. You will probably need to reboot for the new definitions to come into effect. In Windows 2000, set environment variables in the Control Panel System proper ties applet "Advanced tab" Environment variables editor. You will need to restart Visual Studio and any DOS boxes for these changes to take effect.

• Ensure that the MakeDrvr.bat batch file in the book software base directory is available to be run by Visual Studio, as it is used to invoke the build make process. Either add MakeDrvr.bat to a directory that is on your path, or add the book software base directory to the list of "Executable files" directories in the Visual Studio Tools+Options Directories tab.

Recompiling the Book Software

You can check that you have installed the development kits and book software correctly by compiling the book software drivers^[9]. From the Start+Programs+Dуvelopment Kits+Windows XX DDK menu, select either the free or checked build environment. Then move to the book software base directory and enter build –nmake /a. If you want to recompile the Win32 applications, you will have to do this in the Visual Studio workspace.

Check that the drivers are actually updated. In the worst case, it will appear as if the files have compiled but nothing will in fact have been done. If the example drivers do not compile, then there are two usual causes. The first possible problem is that the environment variables have not been set up correctly.

The second problem is that some of the source code explicitly includes header files from the Windows 98 DDK, which I assume has been installed in the C: \98DDK directory. Some of the linker settings have been also been set up to refer to this same directory. If you have used a different directory, or have only installed the Windows 2000 DDK, you will need to change each instance where C:\98DDK is mentioned, either in the source code or in the SOURCES file.

The Wdm3 example specifically refers to a library in the W2000 DDK in its SOURCES files. I assume that this DDK is installed in C:\NTDDK, so change this if need be.

The Wdm2Power Win32 application may need some special project settings before it will compile. See Chapter 10 for details.

Shortcuts

I find it useful to have shortcuts to common tools available, more quickly than through the Start menu.

One possible place for these shortcuts is in the Visual Studio Tools menu. Another option is to place the shortcuts in the Quick Launch folder on the Taskbar.

The option I prefer is to use the free QuickStart utility, available from my company, PHD Computer Consultants Ltd., website at www.phdcc.com. This displays an icon in the Taskbar tray. Clicking this icon shows a menu of various useful options, including submenus for each Desktop folder that you have. Make sure that you put QuickStart in the Startup folder so that it runs from start up.

I therefore suggest making a Tools Desktop folder with shortcuts copied from the Start menu. Table 4.1 shows the most useful tools that I put in this folder.

Table 4.1 Useful Tools

Command line prompt	cmd or command (or equivalent, e.g. 4NT)
Free build environment	DOS box set up for driver free builds
Checked build environment	DOS box set up for driver checked builds
Registry Editor	%windir%\regedit.exe
W2000 Registry Editor	%windir%\System32\regedt32.exe	NT and W2000
WinObj	C:\MSSDK\bin\winnt\Winobj.Exe	NT and W2000
Computer Management	%SystemRoot%\system32\compmgmt.msc /s (from Start+Programs+Administrative tools)	W2000 only
Servicer	%WDMBOOK%\Servicer\Release\Servicer.exe	NT and W2000
WBEM Object Browser	<WBEM>\Applications\browser.htm
DebugPrint Monitor	%WDMBOOK%\DebugPrint\exe\Release\DebugPrintMonitor.exe
Wdm2Power	%WDMBOOK%\Wdm2\Power\Release\Wdm2Power.exe
Driver Verifier	Start+Programs+Development Kits+Windows 2000 DDK+Driver Verifier	W2000 only

You might find a Documentation Desktop folder useful for all the DDK and SDK help shortcuts.

Utilities

This section gives a brief overview of the most useful tools for driver development and how they might best be used. Their detailed use will be covered later.

DOS Boxes

Although you can do most of your development work in Visual Studio, you will occasionally need to work at a command line prompt.

The supplied DDK build tool runs at a command prompt. The environment variables have to be set up appropriately as free or checked driver development. The DDKs provide two shortcuts to get these command prompt boxes.

Computer Management Console

The Windows 2000 Computer Management Console (from Start+Programs+Administrative tools) has a useful System Tools section with Event Viewer and Device Manager tools.

The Event Viewer displays the Windows 2000 events. Drivers should write to the System Log to inform administrators of informational, warning, or error events.

The Device Manager shows all your Windows 98 or Windows 2000 devices and lets you change their properties (e.g., change port settings and reallocate resources). You can change (i.e., update) the driver for a device, and uninstall a device. The Device Manager is also available in the Control Panel System applet.

NT Devices Applet

In NT 4 and NT 3.51, the Control Panel Devices applet lets you see what drivers are running. You can stop or start drivers and change their start up characteristics. In W2000, the Device Manager does not initially list the non-WDM drivers. Selecting the "Show hidden devices" checkbox brings up a list of these drivers. You can start or stop them and change their startup characteristics. The book Servicer program also lets you do some of these functions.

Hardware Wizard

Some drivers are loaded automatically when Windows detects a new device in the system. For others, you need to use the Control Panel Add New Hardware wizard to prompt the loading of the driver.

Registry Editors

You will probably need to inspect the registry at some point during driver development. The basic Registry Editor regedit is useful for most jobs, particularly as it can search the registry. However, for some jobs in NT and Windows 2000, you will need to use RedEdt32, as it can handle all the registry types, such as REG_MULTI_SZ strings.

This book assumes that you have a reasonable working knowledge of the registry. HKLM is used as abbreviation for HKEY_LOCAL_MACHINE. The DDKs sometimes refer to HKLM as Registry\MACHINE.

INF Editor

The InfEdit tool can be used (in Windows 98 only) to create and edit INF files. However, it seems to clobber some INF file information and does not display Windows 2000 specific sections correctly.

WBEM

The WBEM SDK includes the WBEM Object Browser. Use this to inspect the Windows Management Instrumentation data that drivers produce.

Debuggers

There are various tools available to help you test and debug drivers. Unfortunately, the Visual Studio debugger cannot be used on kernel mode code. The Microsoft WinDbg kernel mode debugger must be used between two NT or W2000 computers.

NuMega Compuware sells the SoftICE debugger, which can run on the same PC as the driver under test. Use the NuMega utility nmsym utility to build the necessary symbols for SoftICE.

Finally, some tools let you include trace statements in your driver code that can be viewed in a user mode application on the same PC. The Compuware Numega DriverWorks software includes its Driver Monitor tool for this job. The DebugPrint software from PHD Computer Consultants Ltd. provides a similar facility. DebugPrint is used extensively in this book and its innards are described in detail as an example of a fully working driver. The OSR DDK software from Open Systems Resources logs all your DDK function calls so that they can be viewed by their OSRTracer tool.

NT and Windows 2000 Utilities

WinObj is an NT and W2000 utility that displays various Windows objects, including device names and symbolic links.

The \device branch displays the device names. These device names are not directly visible to user applications. Non-WDM kernel mode device drivers must provide a symbolic link between a Win32 visible name and the underlying device name. The \?? branch displays these symbolic links. Double-clicking on \??\COM1 shows that it is a symbolic link to the underlying device \Device\Serial1. (The \?? branch used to be called \DosDevices, so this name appears in some of the DDK documentation).

Double-clicking most other WinObj entries yields no useful information.

ObjDir is a command line version of WinObj.

Drivers is a command line utility that lists all drivers and their memory usage.

Book Software Tools

DebugPrint

The DebugPrint software is used by test drivers to produce formatted print statements. The trace messages are viewed in the DebugPrint Monitor Win32 application. This tool is explained in full in Chapter 6, because the book software makes extensive use of this debugging technique. Chapter 14 describes the source for the DebugPrint driver.

Wdm2Power

The Wdm2Power tool firstly lets you inspect the AC and battery status of your system. It also displays any system power events. Finally, it lets you suspend or hibernate your computer.

MakeDrvr

This batch file is used from Visual Studio to initiate each build, as described in the following text.

Servicer

The Servicer utility lets you inspect the status of any running Windows 2000 service, including drivers. You can see if a driver is running or not, and attempt to start or stop it.

Driver Targets

Drivers can be built in free or checked versions, and in NT and Windows 2000 for different processors.

The free target is the final release retail version, optimized as necessary with all debug symbols removed.

The checked target is an unoptimised debug version that includes symbols to make debugging easier.

NT and Windows 2000 come in free and checked versions. If you use the Microsoft WinDbg debugger then you need two computers running NT or W2000. The development PC should be the faster computer running the free version of Windows. The driver should be running under test on the other target PC that is running the checked build. The fact that there are fewer resources available on the target system is good as it makes it easier to check that your driver will work in stressful situations.

Windows 2000 also runs on the Dec Alpha platform, so you can also build for the Alpha platform free and checked targets. This book only discusses the x86 platform.

In this book, the emphasis is on writing drivers that work in both Windows 98 and Windows 2000. However, a few features are present in only one operating system. The following preprocessor directives can be used to determine whether you are using the W2000 DDK or the W98 DDK. If you have separate versions of your driver, the installation files will have to be slightly different. As Chapter 11 shows, a single installation INF file can include separate instructions for W2000 and W98.

#if _WIN32_WINNT>=0x0500

 // W2000+ code

#else

// W98 code

#endif

Driver Language and Libraries

A driver is a Dynamic Link Library (DLL) with the file extension .sys. It is usually written in C or C++ and can include resources, such as a version block, event messages, and Windows Management Instrumentation (WMI) class definitions. In Windows 98, a driver executable must have an 8.3 filename.

Although drivers were traditionally written just in C, it is quite straightforward to use C++. The main requirement is to use the extern "C" directive in a couple of important places. However, do not use the new keyword in C++. The new keyword may be implemented using malloc, which is not available to kernel mode drivers.

In fact, most standard libraries and classes are not available to driver writers in either language, because they make inappropriate use of memory. If you are using one of the proprietary driver development kits, these provide various useful classes, including safe memory allocators.

Instead, you can use any of the routines provided by the operating system to kernel mode devices, as described in Chapter 3. While these are useful, it takes a while to get used to the different set of routines that are available.

Assembly code can be used if absolutely necessary. Obviously, this makes for more work if you port the driver to the Windows 2000 Alpha platform.

Resources

A resource .rc file should include a standard version block. Increment the version numbers as new builds are released. Make sure that you keep a full source backup of each version you release. Many version control packages can help you manage this task.

If you generate NT or Windows 2000 events, you should write these in an .mc file that is compiled using the mc utility and included in a driver's resource file. More details of this process are in Chapter 13.

Similarly, if you generate custom WMI classes, you need to write a .mof file that is compiled using the mofcomp tool and included in the driver's resource file. See Chapter 12 for more information.

A sophisticated driver might need to download microcode to its device and so would include the microcode as a binary resource in its executable.

Good Code

A driver is an integral part of the operating system, so it can easily crash Windows if it goes wrong. You do not have the protection of a Win32 address space to stop you from overwriting memory that does not belong to you.

Please be especially careful when you write your driver. Keep it as simple as possible and document it well.

Treat all compiler warnings as errors that need to be fixed. For example, whether an integer is signed or not can make all the difference.

Make sure that you check the return values of all kernel functions that you call, and act on them accordingly. For example, if you get an error after you create a device, make sure that the clean-up code deletes the device.

Make sure that you use the kernel resources carefully, particularly memory. Some resources are scarce and overuse may degrade system functioning.

build Utility

The DDK build command line utility is the primary tool for building drivers. It invokes the nmake make utility to build your driver using the correct compiler and linker settings. If necessary, build can be used to build standard user mode Win32 executables, etc.

The next section describes how to invoke build from within Visual Studio. However, you must still set up build so that it can be run at the command line. As well as your source code, you must specify a SOURCES file, a standard makefile, the directory structure, and optionally a makefile.inc file and a dirs file. All these steps are described in the following text.

build displays progress details and error results to its standard output. In addition, it lists the errors in a file called build.err, the warnings in build.wrn, and a log in build.log. In W2000 there are free and checked build versions of each of these files, i.e., buildfre.log, buildchk.log, etc.

makefiles

Younger readers may not have come across makefiles. In the days before Integrated Development Environments (IDEs) such as Visual Studio, you had to use makefiles to determine which files in a project needed recompiling. If you changed only one module in a project consisting of eight modules, you want to recompile only that one module and then link the whole lot together.

The nmake utility uses instructions in a file called makefile to determine what commands to run to update a project. The following makefile shows that if haggis.cpp has been updated, it is compiled into haggis.obj using the cl compiler. haggis.obj is linked to make haggis.exe using the link tool.

haggis.exe: haggis.obj

            link –o haggis.exe haggis.obj

haggis.obj: haggis.cpp

            cl haggis

Most makefiles are a good deal more complicated than this, which is why they were happily forgotten when IDEs came along. However, setting up the compiler and linker settings for drivers is quite a complicated task. Therefore, Microsoft has stuck with makefiles. See the Visual Studio nmake documentation for more details of makefiles.

SOURCES

build looks for an nmake macro file called SOURCES in the current directory for details of what to build.

Listing 4.1 shows the SOURCES file for the Wdm1 project. It specifies that the driver target name is Wdm1.sys, that it is a WDM driver, and that it should be built in the OBJ subdirectory. Source browser information should be generated. The DDK inc directory is added to the search list for header files. The SOURCES macro specifies a list of files to compile. NTTARGETFILES specifies some post build steps, as described in the following text.

Other less common SOURCES macro definitions can be found in the DDK documentation. Note that there must be no spaces between the SOURCES macro and its equal sign.

Listing 4.1 Wdm1 project SOURCES file

TARGETNAME=Wdm1

TARGETTYPE=DRIVER

DRIVERTYPE=WDM

TARGETPATH=OBJ

BROWSER_INFO=1

INCLUDES=$(BASEDIR)\inc;

SOURCES=init.cpp \

        dispatch.cpp \

        pnp.cpp \

        DebugPrint.c \

        version.rc

NTTARGETFILES=PostBuildSteps

makefile File

You must provide a standard file called makefile as shown in Listing 4.2. This invokes the standard make file makefile.def in the DDK inc directory.

As it says, do not edit this file at all. If you want to add to the list of files to compile, add them to the SOURCES macro in the SOURCES file.

Listing 4.2 Wdm1 project makefile

#

# DO NOT EDIT THIS FILE!!! Edit .\sources. if you want to add a new source

# file to this component. This file merely indirects to the real make file

# that is shared by all the driver components of the Windows NT DDK

#

!INCLUDE ${NTMAKEENV)\makefile.def

build Directories

Windows 98 and NT

build always puts the compiled object files in the OBJ\i386 subdirectory (for x86 targets). The SOURCES TARGETPATH macro specifies where the final executables go. If you specify OBJ for this, then the driver executables go in the OBJ\i386\free and OBJ\i386\checked subdirectories. There is a long-standing bug in build that means that you have to create these last two directories by hand for build. if you were making Wdm1 from scratch, then you would have to make subdirectories OBJ\i386\free and OBJ\i386\checked.

Both the free and checked builds put their object files in the same directory. If you switch between these build types, make sure that you rebuild all the files in the project (by putting "-nmake /a" on the build command line).

The checked build output file OBJ\i386\checked\Wdm1.sys contains the debug symbols.

The build process also generates a file called Wdm1.dbg with the debug symbols in the OBJ\i386\free directory.

Windows 2000

In W2000, build keeps the free and checked build object files separate. If the TARGETPATH is OBJ, the free build x86 object files and the final driver go in the OBJFRE\i386 directory. The checked build object files and driver go in the OBJCHK\i386 directory.

Wdm1 Directories

The end result is the following series of subdirectories for Wdm1.

Directory	Contents
OBJ	Has build list of files to build in _objects.mac
OBJ\i386	W98 Compiled object files
OBJ\i386\free	W98 Free build Wdm1.sys
OBJ\i386\checked	W98 Checked build Wdm1.sys
OBJFRE\i386	W2000 Free build objects and Wdm1.sys
OBJCHK\i386	W2000 Checked build objects and Wdm1.sys

Other build Steps

Another makefile called makefile.inc is invoked if you use certain optional macros in the SOURCES file. Table 4.2 shows the macro name and when the make target is invoked.

Table 4.2 SOURCES optional macros

SOURCES macro name	When invoked
NTTARGETFILE0	after dependency scan
NTTARGETFILE1	before linking
NTTARGETFILES	during link

Listing 4.3 shows the standard makefile.inc that is used in all the book software projects.

Listing 4.3 Book software projects makefile.inc

PostBuildSteps: $(TARGET)

!if "$(DDKBUlLDENV)"="free"

 rebase –B 0x10000 –X . $(TARGET)

!endif

 copy $(TARGET) $(WINDIR)\system32\drivers

The line in the Wdm1 SOURCES file that says NTTARGETFILES=PostBuildSteps ensures that the target PostBuildSteps is built during the link process. As the PostBuildSteps target depends on $(TARGET) — the driver executable — the build commands for PostBuildSteps are carried out after the driver is built. The PostBuildSteps output is displayed in the build.log file. Note that problems in PostBuildSteps may not evident unless you inspect this file.

The actual post-build steps in makefile.inc do two jobs. First, the rebase utility is run on the driver executable for free builds, and the driver is copied to the Windows system32\drivers directory. Copying the driver does not mean that it is installed.

rebase strips any remaining debug symbols that are left, even in the free driver executable. The base load address is kept at 0x10000 and the symbols are put in the .dbg file in the current directory.

DIRS File

The final main feature of build is that it can recursively build files in other directories. If a DIRS file is present, build looks at the DIRS directive in there for a list of directories to build. These directories may themselves contain further DIRS files.

The book software base directory has a DIRS file with the following line:

DIRS=Wdm1 Wdm2 WdmIo UsbKbd HidKbd DebugPrint PassThru

Running build in the book software base directory will compile the drivers in all these directories. The companion Win32 user mode applications are not built by this process.

The directories listed in the DIRS directive must be only one level below the current directory. Therefore, the Wdm1 directory has a DIRS file that instructs build to go to the SYS subdirectory.

VC++ Projects

You can set up VC++ to build drivers from within Visual Studio. It is possible to configure a project's settings so that Visual Studio can compile your driver directly. However, it is laborious changing all the settings and is error prone. The final problem is that Microsoft might change driver compile or link requirements in the DDK standard makefile. Such changes would not be reflected automatically in your settings.

The best way therefore is to use a Makefile project. This invokes a command line utility to build the driver. The downside of this approach is that some common tasks, such as adding a file to the compile list, have to be done in a different way, as described in the following text.

The book software projects are set up already to use the Makefile technique. This eventually invokes the build command as described previously. All the necessary build files must be set up correctly: SOURCES, makefile, the target directories, and possibly the makefile.inc and DIRS files.

You might find it useful to select the Visual Studio Tools+Options menu Editor tab "Automatic reload of externally modified files" checkbox so that changes to the build log files are loaded with no fuss.

Makefile Build Environment

When you make a new Makefile project, Visual Studio gives you two build configurations by default, "Win32 Debug" and "Win32 Release". I prefer to use the Build+Configurations menu to remove these and have configurations named "Win32 Checked" and "Win32 Free", instead.

For the free configuration, set the project settings as shown in Table 4.3. For the checked build, change "free" to "checked" in the build command line and the browse info filename.

If you installed the book software to a driver other than C: you will need to change the drive letter in the build command line.

The build command line runs the MakeDrvr.bat batch file, using the DDKROOT and WDMBOOK environment variables. The options –nmake /a are added to this command line if you request a complete rebuild in Visual Studio. The output filename is set so that the correct name is displayed in the build menu.

Table 4.3 Win32 Free configuration settings

Build command line	MakeDrvr %DDKR00T% c: %WuMBook%\wdm1\sys free
Rebuild all options	-nmake /a
Output file name	Wdm1.sys
Browse info file name	obj\i386\free\Wdm1.bsc (W98/NT) objfre\i386\Wdm1.bsc (W2000)

MakeDrvr

When you ask Visual Studio to build your driver, the batch file MakeDrvr.bat, listed in Listing 4.4, is run. This is always passed at least four parameters: the DDK base directory, the source drive, the source directory, and the build type ("free" or "checked"). Any further arguments are passed straight to build.

MakeDrvr first does some basic checks on the parameters that are passed. It then calls the DDK setenv command to set up the environment variables correctly for the build target, changes directory to the source drive and directory, and finally calls build. The –b build option ensures that the full error text is displayed. The –w option ensures that the warnings appear on the screen output, so that Visual Studio can find them in the build Output window.

The screen output of the MakeDrvr command file appears in the Visual Studio Output window. You can then use F4 as usual to go the next error or warning.

Listing 4.4 MakeDrvr.bat

@echo off

if "%1"=="" goto usage

if "%3"=="" goto usage

if not exist %1\bin\setenv.bat goto usage

call %1\bin\setenv %1 %4

%2

cd %3

build –b –w %5 %6 %7 %8 %9

goto exit

:usage

echo usage MakeDrvr DDK_dir Driver_Drive Driver_Dir free/checked [build_options]

echo eg MakeDrvr %%DDKROOT%% C: %%WDMBOOK%% free –cef

:exit

Directories

The build output goes into the OBJ, OBJFRE, or OBJCHK subdirectories.

In Windows 98, the free driver is in OBJ\i386\free\Wdm1.sys, with debug symbols in OBJ\ i386\free\Wdm1.dbg. The checked build products are in 0BJ\i386\checked. The intermediate object files for both builds are in the OBJ\i386 directory. If you change from the free to checked targets, make sure that you do a "Rebuild all" to recompile all the source files with the correct debug preprocessor defines.

In Windows 2000, the free build object files and driver are in OBJFRE\i386 and the checked build products are in OBJCHK\i386. A complete rebuild is not required if you switch between free and checked builds.

Common Tasks

As you are using a Visual Studio Makefile project, these common tasks must be done is a different way.

Add File to Project

If you add a file to your project, you must add it to the SOURCES file for it to be built.

Make Browse Information

Source browser information is generated alongside the target executable if the SOURCES file contains this line.

BROWSER_INFO=1

Build Steps

Various additional build steps can be defined in a makefile.inc file if the SOURCES file contains one or more of the NTTARGETFILE0, NTTARGETFILE1, or NTTARGETFILES macros.

The results of any additional build steps are not shown in the Visual Studio output window, but only in the build.log file. The build does not necessarily stop if one of these steps fail.

You could also alter MakeDrvr.bat to do tasks that are common to all your driver projects.

Compiling a Single File

You cannot compile a single file in Makefile projects.

The Wdm1 Driver Code

Table 4.4 lists all the source files used by the first driver called Wdm1. Table 4.5 lists all the build files that have already been described. In W2000 the build output files have slightly different names. These files are on the book CD-ROM.

This chapter looks at only some of the source files. As far as possible, the minimum possible functionality has been implemented in Wdm1. For example, a stub function has been written to handle Win32 create file requests. These stub functions usually make each request succeed.

If you were to put this Wdm1 driver to the test, it would not work in some circumstances. The succeeding chapters explain how the driver works and how its functionality has been enhanced to make it work better, as well as showing how to call the driver from Win32 code.

Table 4.4 Wdm1 source files

Wdm1.h	Driver header
Init.cpp	Entry and unload code
Pnp.cpp	Plug and Play and Power handling code
Dispatch.cpp	Main IRP dispatch routines
DebugPrint.c	DebugPrint code
DebugPrint.h	DebugPrint header
Wdm1.rc	Version resource
GUIDs.h	GUID definition
Ioctl.h	IOCTL definition
resource.h	Visual Studio resource editor header
Wdm1free.inf	Free build installation instructions
Wdm1checked.inf	Checked build installation instructions

Table 4.5 Wdm1 build files

SOURCES	build instructions
makefile.inc	Post build steps for makefile
makefile	Standard makefile
MakeDrvr.bat	Makefile project batch file
build.log	build results log output
build.err	build errors output
build.wrn	build warnings output

Compiler Options

The code includes some directives to the compiler that need some explaining.

The extern "C" directive is used to ensure that the compiler uses the correct linkage to reference kernel routines. The driver entry point, DriverEntry, must have extern "C" to ensure it is found.

The #pragma code_seg preprocessor directive is used to force routines into certain code segments. The INIT code segment is discarded after the driver has initialized itself, and the PAGE segment contains code that can be paged out of kernel memory. Using segments helps to lower a driver's memory usage.

Only routines that run at PASSIVE_LEVEL IRQL can be paged from memory. All the dispatch routines in the Wdm1 driver operate at PASSIVE_LEVEL so they can be put in the PAGE segment. Routines that are not given a segment are never paged from memory.

If writing C code, you can use the alloc_text pragma instead to set the code segment of named routines.

Header Files

The Wdm1.h header file is included in all the source files. Wdm1.h first includes the main DDK header file for WDM projects, wdm.h. If you were writing NT style drivers, you would use the similar ntddk.h. You may find that you need to include some other DDK header files for particular types of drivers.

Next, a device extension structure is defined. This structure is where a driver can hold any information it needs about a device (more on this later).

The GUIDs.H header defines a Globally Unique Identifier (GUID) for the Wdm1 device interface. The next chapter shows how this GUID is used by Win32 user mode applications to find Wdm1 devices. I used the guidgen utility to generate this GUID in the DEFINE_GUID format. I defined several consecutive GUIDs at once for all the examples in this book.

Finally, the IOCTL.H header defines the IOCTL codes that Wdm1 supports. These are explained in Chapter 7.

Driver Entry Module

Init.cpp contains the driver entry point. Listing 4.5 shows this routine, which must be called DriverEntry and use C linkage.

The Plug and Play Manager locates the correct driver and calls DriverEntry to initialize the driver (at PASSIVE_IRQL). In DriverEntry, the main job is to store a series of call back routine pointers in the passed DriverObject. This DRIVER_OBJECT structure is used by the operating system to store any information relevant to the driver. A separate structure is used later to store information about each device.

In Wdm1, DriverEntry sets a whole series of callback routines. These routines are called by the kernel when a device is added and when IRPs need to be sent to the driver. The WdmUnload routine, later in Init.cpp, does nothing at this stage.

Finally, DriverEntry returns an NTSTATUS value of STATUS_SUCCESS. Almost all driver routines have to return a NTSTATUS value, from the list in the NTSTATUS.H DDK header file. Note that these error codes do not correspond to Win32 error codes. The kernel does the necessary mapping between the two types of error code.

Listing 4.5 DriverEntry routine

extern "C"

NTSTATUS DriverEntry(IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath) {

 NTSTATUS status = STATUS_SUCCESS;

 //…

 // Export other driver entry points…

 DriverObject->DriverExtension->AddDevice = Wdm1AddDevice;

 DriverObject->DriverUnload = Wdm1Unload;

 DriverObject->MajorFunction[IRP_MJ_CREATE] = Wdm1Create;

 DriverObject->MajorFunction[IRP_MJ_CLOSE] = Wdm1Close;

 DriverObject->MajorFunction[IRP_MJ_PNP] = Wdm1Pnp;

 DriverObject->MajorFunction[IRP_MJ_POWER] = Wdm1Power;

 DriverObject->MajorFunction[IRP_MJ_READ] = Wdm1Read;

 DriverObject->MajorFunction[IRP_MJ_WRITE] = Wdm1Write;

 DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = Wdm1DeviceControl;

 DriverObject->MajorFunction[IRP_MJ_SYSTEM_CONTROL] = Wdm1SystemControl;

 // …

 return status;

}

Version Resource

Wdm1.rc simply defines a version resource block with version and copyright information.

Accessing the Registry

The RegistryPath parameter to DriverEntry contains the registry key of the driver. The Wdm1 code does not currently use its RegistryPath parameter. However, it is common for drivers to use its registry key to store parameters for the whole driver. Therefore, I present the ReadReg routine shown in Listing 4.6. This reads two values from the driver's registry path Parameters subkey. The first value is a ULONG obtained from the value named UlongValue. The second value is a string obtained from the default value for the Parameters key.

Eventually ReadReg needs to call the RtlQueryRegistryValues kernel routine to read both the registry values in one fell swoop. One of the parameters is the absolute registry path, as a NULL-terminated wide string. The driver registry path is supplied in a UNICODE_STRING structure. Although this contains a wide string buffer, it may not necessarily be NULL-terminated. Unfortunately, this means that we have to laboriously make a copy of the string, simply to add on that dratted NULL-terminating character.

The first section of ReadReg does this job. It works out the length of buffer required and uses ExAllocatePool to allocate the memory from the paged pool. The RtlCopyMemory function is used to copy the bulk of the string over and RtlZeroMemory zeroes that all-important last character. You can do the copy and zero by hand if you want, though it should be more efficient to call the kernel functions.

Listing 4.6 ReadReg

void ReadReg(IN PUNICODE_STRING DriverRegistryPath) {

 // Make zero terminated copy of driver registry path

 USHORT FromLen = DriverRegistryPath->Length;

 PUCHAR wstrDriverRegistryPath = (PUCHAR)ExAnocatePool(PagedPool, FromLen+sizeof(WCHAR));

 if( wstrDriverRegistryPath==NULL) return;

 RtlCopyMemory(wstrDriverRegistryPath, DriverRegistryPath->Buffer, FromLen);

 RtlZeroMemory(wstrDriverRegistryPath+FromLen, sizeof(WCHAR));

 // Initialise our ULONG and UNICODE_STRING values

 ULONG UlongValue = –1;

 UNICODE_STRING UnicodeString;

 UnicodeString.Buffer = NULL;

 UnicodeString.MaximumLength = 0;

 UnicodeString.Length = 0;

 // Build up our registry query table

 RTL_QUERY_REGISTRY_TABLE QueryTable[4];

 RtlZeroMemory(QueryTable, sizeof(QueryTable));

 QueryTable[0].Name = L"Parameters";

 QueryTable[0].Flags = RTL_QUERY_REGISTRY_SUBKEY;

 QueryTable[0].EntryContext = NULL;

 QueryTable[1].Name = L"UlongValue";

 QueryTable[1].Flags = RTL_QUERY_REGISTRY_DIRECT;

 OueryTable[1].EntryContext = &UlongValue;

 QueryTable[2].Name = L""; // Default value

 QueryTable[2].Flags = RTL_QUERY_REGISTRY_DIRECT;

 QueryTable[2].EntryContext = &UnicodeString;

 // Issue query

 NTSTATUS status = RtlQueryRegistryValues(RTL_REGISTRY_ABSOLUTE, (PWSTR)wstrDriverRegistryPath, QueryTable, NULL, NULL);

 // Print results

 DebugPrint("ReadReg %x: UlongValue %x UnicodeString %T", status.UlongValue, &UnicodeString);

 // Do not forget to free buffers

 if (UnicodeString.Buffer!=NULL) ExFreePool(UnicodeString.Buffer);

 ExFreePool(wstrDriverRegistryPath);

}

The UNICODE_STRING Structure

This is how the UNICODE_STRING type is defined.

typedef struct _UNICODE_STRING {

 USHORT Length;

 USHORT MaximumLength;

 PWSTR Buffer;

} UNICODE_STRING, *PUNICODE_STRING;

The Buffer field points to a wide 16-bit character buffer. The character string is not usually NULL-terminated. Instead, the Length field gives the current size of the string in bytes. The MaximumLength field gives the maximum size of the string that can fit in the buffer in bytes. This design is used to avoid reallocating string buffers too often. However, it does make manipulating Unicode strings a bit awkward. Table 4.6 shows all the kernel routines that you can use with Unicode strings.

Just in case you were interested, you do not have to use these kernel routines to access Unicode strings. You can fiddle with a string structure however you like, as long as it is in a valid format when passed to the kernel.

Table 4.6 UNICODE_STRING functions

RtlAnsiStringToUnicodeString	Converts an ANSI string to a Unicode string, optionally allocating a buffer.
RtlAppendUnicodeStringToString	Append one Unicode string to another, up to the length ofthe destination buffer.
RtlAppendUnicodeToString	Append a wide string to a Unicode string, up to the length of the destination buffer.
RtlCompareUnicodeString	Compares two Unicode strings, optionally case-insensitive.
RtlCopyUnicodeString	Copies one Unicode string to another, up to the length of the destination buffer.
RtlEqualUnicodeString	Returns TRUE if the two Unicode strings are equal, optionally case-insensitive.
RtlFreeUnicodeString	Frees the Unicode string buffer memory from the pool.
RtlInitUnicodeString	Sets the Unicode string buffer to point to the given wide string, and sets the length fields to match.
RtlIntegerToUnicodeString	Converts a ULONG value to a Unicode string in the specified base. The string buffer must have been initialized beforehand.
RtlPrefixUnicodeString†	Sees if one Unicode string is a prefix of another, optionally case-insensitive.
RtlUnicodeStringToAnsiString	Converts a Unicode string into ANSI. If you ask for the destination ANSI buffer to be allocated, free it eventually with RtlFreeAnsiString.
RtlUnicodeStringToInteger	Converts a Unicode string to an integer.
RtlUpcaseUnicodeString†	Converts a Unicode string into uppercase, optionally allocating a buffer.

†NT/W2000 only

ReadReg declares the variables that will receive the values from the registry. For a UNICODE_STRING, its Buffer, Length, and MaximumLength fields have to be initialized. In this case, these fields are initialized to NULL and zero. The call to RtlQueryRegistryValues will allocate a Buffer and set the length fields.

In most cases, a UNICODE_STRING's buffer needs to be set up correctly. If you want to store an unchanging wide string value in a Unicode string, use the RtlInitUnicodeString function. The Unicode string Buffer is set to point to the passed string and the Length and Maximum-Length strings are set to the length of the string^[10].

RtlInitUnicodeString(&UnicodeString, L"\\Device\\Wdm1");

If you wish to work with the contents of a Unicode string, you need to provide the wide string buffer. Use code like this.

const int MAX_CHARS = 30;

UNICODE_STRING UnicodeString;

WCHAR UnicodeStringBuffer[MAX_CHARS];

UnicodeString.Buffer = UnicodeStringBuffer;

UnicodeString.MaximumLength = MAX_CHARS*2;

UnicodeString.Length = 0;

In this case, the buffer is on the stack. If you want to use the Unicode string after this routine has completed, you must allocate the buffer from pool memory. Do not forget to free this memory once you have finished using the string.

Calling RtlQueryRegistryValues

You must send a query table array to RtlQueryRegistryValues. This array details the actions that you want to do. The last entry in the query table must be zeroed to indicate the end of the list. This is achieved when the entire query table is zeroed using RtlZeroMemory in ReadReg.

There is a wide range of options available when querying the registry. The Flags field in each query table element indicates the action you want to do. The first query listed previously uses RTL_QUERY_REGISTRY_SUBKEY, which means that the Name field contains the subkey for subsequent queries.

The following queries both set the Flags field to RTL_QUERY_REGISTRY_DI RECT. In this case, the Name field contains the registry value name, and the EntryContext field contains a pointer to the variable to receive the value. You have to trust that no one has fiddled with the value types so that a string is returned when you were expecting a ULONG.

A safer approach (not used here) is to pass the name of a callback routine in the QueryRoutine field and set the Flags field to zero. Your routine is called for each value found, and indicates the type of the found value.

The remaining parameters to RtlQueryRegistryValues give even more flexibility. RTL_REGISTRY_ABSOLUTE indicates that the Path parameter is an absolute registry path. Various other useful options can be given (e.g., if the Path is relative to the HKLM\Systcm\CurrentControlSet\Services key).

RtlQueryRegistryValues only returns STATUS_SUCCESS if all the queries were processed correctly and all the registry values were found. The code in ReadReg simply displays the return status and the values retrieved. If using this routine for real, you will probably want to store the values in global variables.

Operating system version

You can use a registry setting to determine at run time whether you are running in W98 or not. In NT and W2000 the following registry value is available, HKLM\System\CurrentControlSet\Control\ProductOptions\ProductType. The value is "WinNT" for the Workstation/Professional Windows version and either "LanmanNT" or "ServerNT" for the Server/Enterprise version. In W98 this registry value should not be available.

Installing Wdm1

That's enough on the Wdm1 code so far. The compiled driver, Wdm1.sys, is provided on the CD in free and checked build versions. However, you can recompile it if you wish.

Normally, Windows detects when a device is installed and prompts for the necessary drivers if they cannot be found already in the system. Full details of the driver selection process are given later.

For the virtual Wdm1 device, use the Control Panel "Add New Hardware" applet wizard. The process is basically the same for Windows 98 and Windows 2000.

Click Next two times, select "No, I want to select hardware from a list" and click Next. Select "Other devices" and click Next. Click "Have Disk…" and browse to the path of the Wdm1 driver (e.g., C:\WDMBook\Wdm1\Sys) and click "OK".

Two models are listed from the found installation INF files, one for the Wdm1 checked build and one for the free build. Select the model you want to install and select Next. Select "Finish" to complete installation.

The installation process does whatever the INF file specifies. The Wdm1 INF files copy the relevant driver to the Windows system32\drivers directory, adds registry settings, etc.

Windows should now have created a Wdm1 device for you. Check that it appears in the Device Manager "Other devices" category (e.g., named "WDM Book: WDM1 Example, free build"). The next chapter describes a Win32 user mode program that you can use to test that the driver is working.

In the Wdm1 code, the DriverEntry routine has been called along with various other Plug and Play callback routines, as described later.

Installation Details

You may be interested to know precisely what happens as a result of installing the Wdm1 driver and one Wdm1 device.

INF Files

Windows 98

Windows 98 copies the INF file to the Windows INF\OTHER directory. The INF file is renamed, after the manufacturer name, to "WDM BookWDM1.INF".

Windows 98 remembers that the INF file has been installed in the registry. The HKLM\ Software\Microsoft\Windows\CurrentVersion\Setup\SetupX\INF\OFM Name key has a value C:\W98\INF\OTHER\WDM BookWDM1.INF set to "WDM BookWDM1.INF". This entry is not deleted if you remove the Wdm1 device.

Windows 98 also keeps a note of the most recently used install locations in the registry.

Windows 2000

Windows 2000 copies the INF file and renames it to the next available OEM filename in the Windows INF directory. For example, WDM1.INF might be copied and renamed as C:\WINNT\INF\OEM1.INF.

Windows 2000 also remembers install locations in the registry.

Registry

The device interface for Wdm1 devices has a registry key at HKLM\System\CurrentControlSet\ Control\DeviceClasses\{C0CF0640-5F6E-11d2-B677-00C0DFE4C1F3) along with a series of subkeys for each device and their associated symbolic link(s). This key includes the WDM1_GUID {C0CF0640…}.

Windows 98

The HKLM\Enum\Root\Unknown\0000 key is the entry for the Wdm1 device. The digits 0000 will increment for each Unknown device. The HKLM\System\CurrentControlSet\Services\Class\Unknown\0000 key is the entry for the Wdm1 driver. This key is passed to DriverEntry in the RegistryPath string.

These entries are removed if you remove the Wdm1 device.

The ClassGUID value in the Wdm1 device key is {4D36E97E…} for "Unknown" type devices. This has a registry entry at HKLM\System\CurrentControlSet\Services\Class\{4D36E97E…}.

Windows 2000

The HKLM\System\CurrentControlSet\Control\Class\{4D36E97E…}\0000 key is the entry for the Wdm1 device. {4D36E97E…} is the GUID for "Unknown" type devices.

The driver service entry key is HKLM\System\CurrentControlSet\Services\Wdm1. This key is passed to DriverEntry in the RegistryPath string. The Enum subkey has values named 0 onwards such as Root\UNKNOWN\0000 for each device instance.

Windows 2000 Objects

The winobj program lets you see what Windows 2000 objects are present for the driver and the device.

The driver has an entry \driver\wdm1.

There is a symbolic link object \??\Root#UNKNOWN#0000#{C0CF0640…}. If you double-click this, you will see that this links to one of the listed devices (e.g., to \device\004059). Symbolic links are covered in the next chapter.

Managing Devices and Drivers

Having installed Wdm1, there are various device and driver management jobs that you can perform.

Add Another Device

You can open another device with the same driver using the Add New Hardware wizard again. Windows made a copy of the INF file so you can select the device from the list without having to specify your driver location. Additional entries are made in the registry for the second Wdm1 device and the device interface to it.

Removing a Device

In the Device Manager, select the device you want to remove. Click Uninstall or Remove.

Most of the device and driver registry entries are removed if the Wdm1 device is removed. However, the registry entry for the device interface and the Windows 2000 Services entry persist after a device is removed.

When you remove a device, the INF file is not removed from the Windows INF directory structure. Similarly, the Wdm1.sys driver file remains in place in the System32\Drivers directory. This makes it easy to reinstall a Wdm1 device.

If all the driver's devices have been removed, the driver is unloaded from memory. At this stage, if you update the driver in the Windows System32\drivers directory and reinstall the device, the new driver is used.

Updating the Driver

The simplest way to update a driver is to use the Update/Change driver option in the Device Manager properties for a device. The book software projects always make a copy of the latest build of a driver in the Windows System32\Drivers directory so you can reinstall a new driver without having to select the Have disk option. W2000 uses the files in this directory while W98 requires you to specify the location of the new files.

Alternatively, remove all devices and invoke the Add New Hardware wizard again.

NT Style Drivers

NT style (non-Plug and Play) drivers must use a special installation process, as described in Chapter 11.

Updating an NT style driver happens in a different way, as well. First, you must get your driver into the Windows System32\drivers directory.

In NT 3.51 and NT 4, run the Control Panel Devices applet. Find your driver, stop it, and start it again. In Windows 2000 you must opt to show hidden devices in the Device Manager before you can start or stop NT style drivers. Alternatively, you can run the book software Servicer program; type in the name of your driver; press Stop and then Start. If you run an NT style driver in W98, you must reboot the computer to use an updated driver.

Conclusion

This chapter has shown how to set up a development computer for device driver development. A very basic WDM driver has been written and installed in Windows 98 and Windows 2000.

The following chapters explain how to access this driver from a user program and enhance this driver to implement the correct Plug and Play and Power Management handling.

Listing 4.7 Wdm1.h

///////////////////////////////////////////////////////////////////////

//Copyright © 1998 Chris Cant, PHD Computer Consultants Ltd

//WDM Book for R&D Books, Miller Freeman Inc

//

//Wdm1 example

///////////////////////////////////////////////////////////////////////

//wdm1.hCommon header

///////////////////////////////////////////////////////////////////////

//Version history

//27-Apr-991.0.0CCcreation

///////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////

//Include WDM standard header with C linkage

#ifdef __cplusplus

extern "C" {

#endif

#include "wdm.h"

#ifdef __cplusplus

}

#endif

///////////////////////////////////////////////////////////////////////

//DebugPrint and Guid headers

#include "DebugPrint.h"

#include "GUIDs.h"

///////////////////////////////////////////////////////////////////////

//Spin lock to protect access to shared memory buffer

extern KSPIN_LOCK BufferLock;

extern PUCHAR Buffer;

///////////////////////////////////////////////////////////////////////

//Our device extension

typedef struct _WDM1_DEVICE_EXTENSION {

 PDEVICE_OBJECT fdo;

 PDEVICE_OBJECT NextStackDevice;

 UNICODE_STRIN GifSymLinkName;

} WDM1_DEVICE_EXTENSION, *PWDM1_DEVICE_EXTENSION;

///////////////////////////////////////////////////////////////////////

// Forward declarations of global functions

VOID Wdm1Unload(IN PDRIVER_OBJECT DriverObject);

NTSTATUS Wdm1Power(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1Pnp(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1AddDevice(IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT pdo);

NTSTATUS Wdm1Create(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1Close(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1Write(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1Read(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1DeviceControl(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

NTSTATUS Wdm1SystemControl(IN PDEVICE_OBJECT fdo, IN PIRP Irp);

///////////////////////////////////////////////////////////////////////

// NTSTATUS CompleteIrp(PIRP Irp, NTSTATUS status, ULONG info);

///////////////////////////////////////////////////////////////////////

Listing 4.8 Init.cpp

///////////////////////////////////////////////////////////////////////

//Copyright © 1998 Chris Cant, PHD Computer Consultants Ltd

//WDM Book for R&D Books, Miller Freeman Inc

//

//Wdm1 example

///////////////////////////////////////////////////////////////////////

//init.cpp:Driver initialization code

///////////////////////////////////////////////////////////////////////

//DriverEntryInitialisation entry point

//Wdm1UnloadUnload driver routine

///////////////////////////////////////////////////////////////////////

//Version history //27-Apr-991.0.0CCcreation

///////////////////////////////////////////////////////////////////////

#include "wdm1.h"

#pragma code_seg("INIT") // start INIT section

///////////////////////////////////////////////////////////////////////

//DriverEntry:

//

//Description:

//This function initializes the driver, and creates

//any objects needed to process I/O requests.

//

//Arguments:

//Pointer to the Driver object

//Registry path string for driver service key

//

//Return Value:

//This function returns STATUS_XXX

extern "C"

NTSTATUS DriverEntry(IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath) {

 NTSTATUS status = STATUS_SUCCESS;

#if DBG

 DebugPrint Init("Wdm1 checked");

#else

 DebugPrintInit("Wdm1 free");

#endif

 DebugPrint("RegistryPath is %T", RegistryPath);

 // Export other driver entry points…

 DriverObject->DriverExtension->AddDevice = Wdm1AddDevice;

 DriverObject->DriverUnload = Wdm1Unload;

 OriverObject->MajorFunction[IRP_MJ_CREATE] = Wdm1Create;

 DriverObject->MajorFunction[IRP_MJ_CLOSE] = Wdm1Close;

 DriverObject->MajorFunction[IRP_MJ_PNP] = Wdm1Pnp;

 DriverObject->MajorFunction[IRP_MJ_POWER] = Wdm1Power;

 DriverObject->MajorFunction[IRP_MJ_READ] = Wdm1Read;

 DriverObject->MajorFunction[IRP_MJ_WRITE] = Wdm1Write;

 DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = Wdm1DeviceControl;

 DriverObject->MajorFunction[IRP_MJ_SYSTEM_CONTROl] = Wdm1SystemControl;

 //Initialise spin lock which protects access to shared memory buffer

 KeInitializeSpinLock(&BufferLock);

 DebugPrintMsg("DriverEntry completed");

 return status;

}

#pragma code_seg() // end INIT section

///////////////////////////////////////////////////////////////////////

//Wdm1Unload

//

//Description:

//Unload the driver by removing any remaining objects, etc.

//

//Arguments:

//Pointer to the Driver object

//

//Return Value:

//None

#pragma code_seg("PAGE") // start PAGE section

VOID Wdm1Unload(IN PDRIVER_OBJECT DriverObject) {

 // Free buffer (do not need to acquire spin lock)

 if (Buffer!=NULL) ExFreePool(Buffer);

 DebugPrintMsg("WdmlUnload");

 DebugPrintClose();

}

///////////////////////////////////////////////////////////////////////

#pragma code_seg() // end PAGE section

Listing 4.9 Pnp.cpp

///////////////////////////////////////////////////////////////////////

//Copyright © 1998 Chris Cant, PHD Computer Consultants Ltd

//WDM Book for R&D Books, Miller Freeman Inc

//

//Wdm1 example

///////////////////////////////////////////////////////////////////////

//pnp.cpp:Plug and Play and Power IRP handlers

///////////////////////////////////////////////////////////////////////

//Wdm1AddDeviceAdd device routine

//Wdm1PnpPNP IRP dispatcher

//Wdm1PowerPOWER IRP dispatcher

///////////////////////////////////////////////////////////////////////

//Version history //27-Apr-991.0.0CCcreation

///////////////////////////////////////////////////////////////////////

#define INITGUID// initialize WDM1_GUID in this module

#include "wdm1.h"

#pragma code_seg("PAGE")// start PAGE section

///////////////////////////////////////////////////////////////////////

//Wdm1AddDevice:

//

//Description:

//Cope with a new Pnp device being added here.

//Usually just attach to the top of the driver stack.

//Do not talk to device here!

//

//Arguments:

//Pointer to the Driver object

//Pointer to Physical Device Object

//

//Return Value:

//This function returns STATUS_XXX

NTSTATUS WdmlAddDevice(IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT pdo) {

 DebugPrint("AddDevice");

 NTSTATUS status;

 PDEVICE_OBJECT fdo;

 // Create our Functional Device Object in fdo

 status = IoCreateDevice(DriverObject, sizeof(WDM1_DEVICE_EXTENSION),

  NULL,// No Name

  FILE_DEVICE_UNKNOWN, 0,

  FALSE,// Not exclusive

  &fdo);

 if (!NT_SUCCESS(status)) return status;

 // Remember fdo in our device extension

 PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

 dx->fdo = fdo;

 DebugPrint("FDO is %x",fdo);

 // Register and enable our device interface

 status = IoRegisterDeviceInterface(pdo, &WDM1_GUID, NULL, &dx->ifSymLinkName);

 if (!NT_SUCCESS(status)) {

  IoDeleteDevice(fdo);

  return status;

 }

 IoSetDeviceInterfaceState(&dx->ifSymLinkName, TRUE);

 DebugPrint("Symbolic Link Name is %T", &dx->ifSymLinkName);

 // Attach to the driver stack below us

 dx->NextStackDevice = IoAttachDeviceToDeviceStack(fdo.pdo);

 // Set fdo flags appropriately

 fdo->Flags &= ~DO_DEVICE_INITIALIZING;

 fdo->Flags |= DO_BUFFERED_IO;

 return STATUS_SUCCESS;

}

///////////////////////////////////////////////////////////////////////

//Wdm1Pnp:

//

//Description:

//Handle IRP_MJ_PNP requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//Various minor codes

//IrpStack->Parameters.QueryDeviceRelations

//IrpStack->Parameters.QueryInterface

//IrpStack->Parameters.DeviceCapabilities

//IrpStack->Parameters.FilterResourceRequirements

//IrpStack->Parameters.ReadWriteConfig

//IrpStack->Parameters.SetLock

//IrpStack->Parameters.QueryId

//IrpStack->Parameters.QueryDeviceText

//IrpStack->Parameters.UsageNotification

//

//Return Value:

//This function returns STATUS_XXX

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

 DebugPrint("PnP %I", Irp);

 PWDM1_DEVICE_EXTENSION dx=(PWDMl_DEVICE_EXTENSION)fdo->DeviceExtension;

 // Remember minor function

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 ULONG MinorFunction = IrpStack->MinorFunction;

 // Just pass to lower driver

 IoSkipCurrentIrpStackLocation(Irp);

 NTSTATUS status = IoCallDriver(dx->NextStackDevice, Irp);

 // Device removed

 if (MinorFunction==IRP_MN_REMOVE_DEVICE) {

  DebugPrint("PnP RemoveDevice");

  // disable device interface

  IoSetDeviceInterfaceState(&dx->ifSymLinkName, FALSE);

  RtlFreeUnicodeString(&dx->ifSymLinkName);

  // unattach from stack

  if (dx->NextStackDevice) IoDetachDevice(dx->NextStackDevice);

  // delete our fdo IoDeleteDevice(fdo);

 }

 return status;

}

///////////////////////////////////////////////////////////////////////

//Wdm1Power:

//

//Description:

//Handle IRP_MJ_POWER requests

//

//Arguments:

//Pointer to the FDO

//Pointer to the IRP

//IRP_MN_WAIT_WAKE:IrpStack->Parameters.WaitWake.Xxx

//IRP_MN_POWER_SEOUENCE:IrpStack->Parameters.PowerSequence.Xxx

//IRP_MN_SET_POWER:

//IRP_MN_QUERY_POWER:IrpStack->Parameters.Power.Xxx

//

//Return Value:

//This function returns STATUS_XXX

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

 DebugPrint("Power %I",Irp);

 PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

 // Just pass to lower driver

 PoStartNextPowerIrp(Irp);

 IoSkipCurrentIrpStackLocation(Irp);

 return PoCallDriver(dx->NextStackDevice, Irp);

}

#pragma code_seg()// end PAGE section

Listing 4.10 Dispatch.cpp

///////////////////////////////////////////////////////////////////////

//Copyright © 1998 Chris Cant, PHD Computer Consultants Ltd

//WDM Book for R&D Books, Miller Freeman Inc

//

//Wdm1 example

///////////////////////////////////////////////////////////////////////

//dispatch.cpp:Other IRP handlers

///////////////////////////////////////////////////////////////////////

//Wdm1CreateHandle Create/Open file IRP

//Wdm1CloseHandle Close file IRPs

//Wdm1ReadHandle Read IRPs

//Wdm1WriteHandle Write IRPs

//Wdm1DeviceControlHandle DeviceIoControl IRPs

//Wdm1SystemControlHandle WMI IRPs

///////////////////////////////////////////////////////////////////////

//Version history

//27-Apr-991.0.0CCcreation

///////////////////////////////////////////////////////////////////////

#include "wdm1.h"

#include "Ioctl.h"

///////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////

//Buffer and BufferSize and guarding spin lock globals (in unpaged memory)

KSPIN_LOCK BufferLock;

PUCHARBuffer = NULL;

ULONGBufferSize = 0;

///////////////////////////////////////////////////////////////////////

//Wdm1Create:

//

//Description:

//Handle IRP_MJ_CREATE requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//IrpStack->Parameters.Create.xxx has create parameters

//IrpStack->FileObject->FileName has file name of device

//

//Return Value:

//This function returns STATUS_XXX

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

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

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

 // Complete successfully

 return CompleteIrp(Irp,STATUS_SUCCESS,0);

}

///////////////////////////////////////////////////////////////////////

//Wdm1Close:

//

//Description:

//Handle IRP_MJ_CLOSE requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//

//Return Value:

//This function returns STATUS_XXX

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

 DebugPrintMsg("Close");

 // Complete successfully

 return CompleteIrp(Irp,STATUS_SUCCESS,0);

}

///////////////////////////////////////////////////////////////////////

//Wdm1Read:

//

//Description:

//Handle IRP_MJ_READ requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//IrpStack->Parameters.Read.xxx has read parameters

//User buffer at:AssociatedIrp.SystemBuffer(buffered I/O)

//MdlAddress(direct I/O)

//

//Return Value:

//This function returns STATUS_XXX

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

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 NTSTATUS status = STATUS_SUCCESS;

 LONG BytesTxd = 0;

 // Get call parameters

 LONGLONG FilePointer = IrpStack->Parameters.Read.ByteOffset.QuadPart;

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

 DebugPrint("Read %d bytes from file pointer %d",(int)ReadLen,(int)FilePointer);

 // Get access to the shared buffer

 KIRQL irql;

 KeAcquireSpinLock(&BufferLock,&irql);

 // Check file pointer

 if (FilePointer<0) status = STATUS_INVALID_PARAMETER;

 if (FilePointer>=(LONGLONG)BufferSize) status = STATUS_END_OF_FILE;

 if (status==STATUS_SUCCESS) {

  // Get transfer count

  if ( ((ULONG)FilePointer)+ReadLen>BufferSize) {

   BytesTxd = BufferSize – (ULONG)FilePointer;

   if (BytesTxd<0) BytesTxd = 0;

  } else BytesTxd = ReadLen;

  // Read from shared buffer

  if (BytesTxd>0 && Buffer!=NULL) RtlCopyMemory(Irp->AssociatedIrp.SystemBuffer, Buffer+FilePointer, BytesTxd);

 }

 // Release shared buffer

 KeReleaseSpinlock(&BufferLock,irql);

 DebugPrint("Read: %d bytes returned",(int)BytesTxd);

 // Complete IRP

 return Completelrp(Irp.status.BytesTxd);

}

///////////////////////////////////////////////////////////////////////

//Wdm1Write: //

//Description:

//Handle IRP_MJ_WRITE requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//IrpStack->Parameters.Write.xxx has write parameters

//User buffer at:AssociatedIrp.SystemBuffer(buffered I/O)

//MdlAddress(direct I/O)

//

//Return Value:

//This function returns STATUS_XXX

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

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 NTSTATUS status = STATUS_SUCCESS;

 LONG BytesTxd = 0;

 // Get call parameters

 LONGLONG FilePointer = IrpStack->Parameters.Write.ByteOffset.QuadPart;

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

 DebugPrint("Write %d bytes from file pointer %d",(int)WriteLen,(int)FilePointer);

 if (FilePointer<0) status = STATUS_INVALID_PARAMETER;

 else {

  // Get access to the shared buffer

  KIRQL irql;

  KeAcquireSpinLock(&BufferLock,&irql);

  BytesTxd = WriteLen;

  // (Re)allocate buffer if necessary

  if ( ((ULONG)FilePointer)+WriteLen>BufferSize) {

   ULONG NewBufferSize = ((ULONG)FilePointer)+WriteLen;

   PVOID NewBuffer = ExAllocatePool(NonPagedPool.NewBufferSize);

   if (NewBuffer==NULL) {

    BytesTxd = BufferSize – (ULONG)FilePointer;

    if (BytesTxd<0) BytesTxd = 0;

   } else {

    RtlZeroMemory(NewBuffer,NewBufferSize);

    if (Buffer==NULL) {

     RtlCopyMemory(NewBuffer,Buffer,BufferSize);

     ExFreePool(Buffer);

    }

    Buffer = (PUCHAR)NewBuffer;

    BufferSize = NewBufferSize;

   }

  }

  // Write to shared memory

  if (BytesTxd>0 && Buffer!=NULL) RtlCopyMemory(Buffer+FilePointer, Irp->AssociatedIrp.SystemBuffer, BytesTxd);

  // Release shared buffer

  KeReleaseSpinLock(&BufferLock,irq1);

 }

 DebugPrint("Write: %d bytes written", (int)BytesTxd);

 // Complete IRP

 return CompleteIrp(Irp,status,BytesTxd);

}

///////////////////////////////////////////////////////////////////////

//WdmlDeviceControl:

//

//Description:

//Handle IRP_MJ_DEVICE_CONTROL requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//Buffered:AssociatedIrp.SystemBuffer (and IrpStack-Parameters.DeviceIoControl.Type3InputBuffer)

//Direct:MdlAddress

//

//IrpStack->Parameters.DeviceIoControl.InputBufferLength

//IrpStack->Parameters.DeviceIoControl.OutputBufferLength

//

//Return Value:

//This function returns STATUS_XXX

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

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 NTSTATUS status – STATUS_SUCCESS;

 ULONG BytesTxd = 0;

 ULONG ControlCode = IrpStack->Parameters.DeviceIoControl.IoControlCode;

 ULONG InputLength = IrpStack->Parameters.DeviceIoControl.InputBufferLength;

 ULONG OutputLength = IrpStack->Parameters.DeviceIoControl.OutputBufferLength;

 DebugPrint("DeviceIoControl: Control code %x InputLength %d OutputLength %d", ControlCode, InputLength, OutputLength);

 // Get access to the shared buffer KIRQL irql ;

 KeAcquireSpinLock(&BufferLock,&irql);

 switch (ControlCode) {

 ///////Zero Buffer

 case IOCTL_WDM1_ZERO_BUFFER:

  // Zero the buffer

  if (Buffer!=NULL && BufferSize>0) RtlZeroMemory(Buffer,BufferSize);

  break;

 ///////Remove Buffer

 case IOCTL_WDM1_REMOVE_BUFFER:

  if (Buffer!=NULL) {

   ExFreePool(Buffer);

   Buffer = NULL;

   BufferSize = 0;

  }

  break;

 ///////Get Buffer Size as ULONG

 case IOCTL_WDM1_GET_BUFFER_SIZE:

  if (OutputLength<sizeof(ULONG)) status = STATUS_INVALID_PARAMETER;

  else {

   BytesTxd = sizeof(ULONG);

   RtlCopyMemory(Irp->AssociatedIrp.SystemBuffer,&BufferSize,sizeof(ULONG));

  }

  break;

 ///////Get Buffer

 case IOCTL_WDM1_GET_BUFFER:

  if (OutputLength>BufferSize) status = STATUS_INVALID_PARAMETER;

  else {

   BytesTxd = OutputLength;

   RtlCopyMemory(Irp->AssociatedIrp.SystemBuffer,Buffer,BytesTxd);

  }

  break;

 ///////Invalid request

 default:

  status = STATUS_INVALID_DEVICE_REQUEST;

 }

 // Release shared buffer

 KeReleaseSpinlock(&BufferLock,irql);

 DebugPrint("DeviceIoControl: %d bytes written", (int)BytesTxd);

 // Complete IRP

 return CompleteIrp(Irp,status.BytesTxd);

}

///////////////////////////////////////////////////////////////////////

//Wdm1SystemControl:

//

//Description:

//Handle IRP_MJ_SYSTEM_C0NTROL requests

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//Various minor parameters

//IrpStack->Parameters.WMI.xxx has WMI parameters

//

//Return Value:

//This function returns STATUS_XXX

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

 DebugPrintMsg("SystemControl");

 // Just pass to lower driver

 IoSkipCurrentIrpStackLocation(Irp);

 PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

 return IoCallDriver(dx->NextStackDevice, Irp);

}

///////////////////////////////////////////////////////////////////////

//Wdm1Cleanup:

//

//Description:

//Handle IRP_MJ_CLEANUP requests

//Cancel queued IRPs which match given FileObject

//

//Arguments:

//Pointer to our FDO

//Pointer to the IRP

//IrpStack->FileObject has handle to file

//

//Return Value:

//This function returns STATUS_XXX

//Not needed for Wdm1

///////////////////////////////////////////////////////////////////////

//CompleteIrp:Sets IoStatus and completes the IRP

NTSTATUS CompleteIrp(PIRP Irp, NTSTATUS status, ULONG info) {

 Irp->IoStatus.Status = status;

 Irp->IoStatus.Information = info;

 IoCompleteRequest(Irp,IO_NO_INCREMENT);

 return status;

}

///////////////////////////////////////////////////////////////////////

Listing 4.11 Wdm1.rc

//Microsoft Developer Studio generated resource script.

//

#include "resource.h"

#define APSTUDIO_READONLY_SYMBOLS

///////////////////////////////////////////////////////////////////////

//

// Generated from the TEXTINCLUDE 2 resource.

//

#include "afxres.h"

///////////////////////////////////////////////////////////////////////

#undef APSTUDIO_READONLY_SYMBOLS

///////////////////////////////////////////////////////////////////////

// English (U.S.) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENU)

#ifdef _WIN32

LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US

#pragma code_page(1252)

#endif //_WIN32

#ifndef _MAC

///////////////////////////////////////////////////////////////////////

//

// Version

//

VS_VERSION_INFO VERSIONINFO

 FILEVERSION 1,0,5,0

 PRODUCTVERSION 1,0,0,0

 FILEFLAGSMASK 0x3fL

#ifdef _DEBUG

 FILEFLAGS 0x1L

#else

 FILEFLAGS 0x0L

#endif

 FILEOS 0x4L

 FILETYPE 0x2L

 FILESUBTYPE 0x0L

BEGIN

 BLOCK "StringFileInfo"

 BEGIN

  BLOCK "080904b0"

  BEGIN

   VALUE "Comments", "Chris Cant\0"

   VALUE "CompanyName", "PHD Computer Consultants Ltd\0"

   VALUE "FileDescription", "Wdm1\0"

   VALUE "FileVersion", "1, 0, 5, 0\0"

   VALUE "InternalName", "Wdm1 driver\0"

   VALUE "LegalCopyright", "Copyright © 1998,1999 PHD Computer Consultants Ltd\0"

   VALUE "OriginalFilename", "Wdm1.sys\0"

   VALUE "ProductName", "WDM Book\0"

   VALUE "ProductVersion", "1, 0, 0, 0\0"

  END

 END

 BLOCK "VarFileInfo"

 BEGIN

  VALUE "Translation", 0x809, 1200

 END

END

#endif // !_MAC

#endif // English (U.S.) resources

///////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////

// English (U.K.) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENG)

#ifdef _WIN32

LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_UK

#pragma codepage(1252)

#endif //_WIN32

#ifdef APSTUDIO_INVOKED

///////////////////////////////////////////////////////////////////////

//

// TEXTINCLUDE

//

1 TEXTINCLUDE DISCARDABLE

BEGIN

 "resource.h\0"

END

2 TEXTINCLUDE DISCARDABLE

BEGIN

 "#include ""afxres.h""\r\n" "\0"

END

3 TEXTINCLUDE DISCARDABLE

BEGIN

 "\r\n" "\0"

END

#endif // APSTUDIO_INVOKED

#endif // English (U.K.) resources

///////////////////////////////////////////////////////////////////////

#ifndef APSTUDIO_INVOKED

///////////////////////////////////////////////////////////////////////

//

// Generated from the TEXTINCLUDE 3 resource.

//

///////////////////////////////////////////////////////////////////////

#endif // not APSTUDIO_INVOKED

Listing 4.12 Ioctl.h

//DeviceIoControl IOCTL codes supported by Wdm1

#define IOCTL_WDM1_ZERO_BUFFER CTL_CODE(\

 FILE_DEVICE_UNKNOWN,\

 0x801,\

 METHOD_BUFFERED,\

 FILE_ANY_ACCESS)

#define IOCTL_WDM1_REMOVE_BUFFER CTL_CODE(\

 FILE_DEVICE_UNKNOWN,\

 0x802,\

 METHOD_BUFFERED,\

 FILE_ANY_ACCESS)

#define IOCTL_WDM1_GET_BUFFER_SIZE CTL_CODE(\

 FILE_DEVICE_UNKNOWN,\

 0x803, \

 METHOD_BUFFERED,\

 FILE_ANY_ACCESS)

#define IOCTL_WDM1_GET_BUFFER CTL_CODE(\

 FILE_DEVICE_UNKNOWN,\

 0x804,\

 METHOD_BUFFERED,\

 FILE_ANY_ACCESS)

#define IOCTL_WDM1_UNRECOGNISED CTL_CODE(\

 FILE_DEVICE_UNKNOWN,\

 0x805,\

 METHOD_BUFFERED,\

 FILE_ANY_ACCESS)

Listing 4.13 GUIDs.h

///////////////////////////////////////////////////////////////////////

//Wdm1 device interface GUID

// {C0CF0640-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(WDM1_GUID, 0xc0cf0640, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

///////////////////////////////////////////////////////////////////////

//Wdm2 device interface GUID

// {C0CF0641-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(WDM2_GUID, 0xc0cf0641, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xd, 0xf3);

///////////////////////////////////////////////////////////////////////

//Wdm3 device interface GUID

// {C0CF0642-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(WDM3_GUID, 0xc0cf0642, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xd, 0xf3);

///////////////////////////////////////////////////////////////////////

//Wdm3 WMI data block GUID

// {C0CF0643-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(WDM3_WMI_GUID, 0xc0cf0643, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

///////////////////////////////////////////////////////////////////////

//Wdm3 WMI event block GUID

// {C0CF0644-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(WDM3_WMI_EVENT_GUID, 0xc0cf0644, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0, 0xdf, 0xe4, 0xc1, 0xf3);

/*

// {C0CF0645-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(<<name>>,

0xc0cf0645, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

// {C0CF0646-5F6E-11d2-B677-00C0DFE4C1F31

DEFINE_GUID(<<name>>,

0xc0cf0646, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

// {C0CF0647-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE GUID(<<name>>,

0xc0cf0647, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

// {C0CF0648-5F6E-11d2-B677-00C0DFE4C1F3}

DEFINE_GUID(<<name>>,

0xc0cf0648, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

*/

///////////////////////////////////////////////////////////////////////

Listing 4.14 resource.h

//{{NO_DEPENDENCIES}}

// Microsoft Developer Studio generated include file.

// Used by Wdm1.rc

//

// Next default values for new objects

//

#ifdef APSTUDIO_INVOKED

#ifndef APSTUDIO_READONLY_SYMBOLS

#define _APS_NO_MFC              1

#define _APS_NEXT_RESOURCE_VALUE 101

#define _APS_NEXT_COMMAND_VALUE  40001

#define _APS_NEXT_CONTROL_VALUE  1000

#define _APS_NEXT_SYMED_VALUE    101

#endif

#endif

Listing 4.15 Wdm1free.inf

; Wdm1free.Inf – install information file

; Copyright © 1998,1999 Chris Cant, PHD Computer Consultants Ltd

[Version]

Signature="$Chicago$"

Class=Unknown

Provider=%WDMBook%

DriverVer=04/26/1999,1.0.5.0

[Manufacturer]

%WDMRook% = WDM.Book

[WDM.Book]

%Wdm1%=Wdm1.Install, *wdmBook\Wdm1

[DestinationDirs]

Wdm1.Files.Driver=10,System32\Drivers

Wdm1.Files.Driver.NTx86=10,System32\Drivers

[SourceDisksNames]

1="Wdm1 build directory",,,

[SourceDisksFiles]

Wdm1.sys=1,obj\i386\free

[SourceDisksFiles.x86] Wdm1.sys=1,objfre\i386

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Windows 98

[Wdm1.Install]

CopyFiles=Wdm1.Files.Driver

AddReg=Wdm1.AddReg

[Wdm1.AddReg]

HKR,,DevLoader,,*ntkern

HKR,,NTMPDriver,,Wdm1.sys

[Wdm1.Files.Driver]

Wdm1.sys

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Windows 2000

[Wdm1.Install.NTx86]

CopyFiles=Wdm1.Files.Driver.NTx86

[Wdm1.Files.Driver.NTx86]

Wdm1.sys,,,%COPYFLG_NOSKIP%

[Wdm1.Install.NTx86.Services]

AddService = Wdm1, %SPSVCINST_ASSOCSERVICE%, Wdm1.Service

[Wdm1.Service]

DisplayName = %Wdm1.ServiceName%

ServiceType = %SERVICE_KERNEL_DRIVER%

StartType = %SERVICE_DEMAND_START%

ErrorControl = %SERVICE_ERROR_NORMAL%

ServiceBinary = %10%\System32\Drivers\Wdm1.sys

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

; Strings

[Strings]

WDMBook="WDM Book"

Wdm1="WDM Book: Wdm1 Example, free build"

Wdm1.ServiceName="WDM Book Wdm1 Driver"

SPSVCINST_ASSOCSERVICE=0x00000002; Driver service is associated with device being installed

COPYFLG_NOSKIP=2; Do not allow user to skip file

SERVICE_KERNEL_DRIVER=1

SERVICE_AUTO_START=2

SERVICE_DEMAND_START=3

SERVICE_ERROR_NORMAL=1

Listing 4.16 SOURCES

TARGETNAME=Wdm1

TARGETTYPE=DRIVER

DRIVERTYPE=WDM

TARGETPATH=OBJ

INCLUDES=$(BASEDIR)\inc;

SOURCES=init.cpp \

 dispatch.cpp \

 pnp.cpp \

 DebugPrint.c \

 Wdm1.rc

NTTARGETFILES=PostBuildSteps

Listing 4.17 makefile.inc

PostBuildSteps: $(TARGET)

!if "$(DDKBUILDENV)"="free"

 rebase –B 0x10000 –X . $(TARGET)

!endif

 copy $(TARGET) $(WINDIR)\system32\drivers

Listing 4.18 makefile

#

# DO NOT EDIT THIS FILE!!! Edit .\sources. if you want to add a new. source

# file to this component. This file merely indirects to the real make file

# that is shared by all the driver components of the Windows NT DDK

#

!INCLUDE $(NTMAKEENV)\makefile.def

Listing 4.19 MakeDrvr.bat

@echo off

if "%1"=="" goto usage

if "%3"=="" goto usage

if not exist %1\bin\setenv.bat goto usage

call %1\bin\setenv %1 %4

%2

cd %3

build –b –w %5 %6 %1 %8 %9

goto exit

:usage

echo usage MakeDrvr DDK_dir Driver_Drive Driver_Dir free/checked [build_options]

echo eg MakeDrvr %%DDKROOT%% C: %%WDMBOOK%% free –cef

:exit

This chapter explains how to use device interfaces to make a driver available to the kernel and Win32 user-mode applications. The device interface code in the Wdm1 driver is described. The example Wdm1Test user-mode program shows how to use the Win32 functions to find device interfaces. Wdm1Test then sends some basic I/O requests to the Wdm1 driver.

Devices

A driver implements one or more devices. Each device represents an instance of a piece of real or virtual hardware. User-mode programs and the kernel access a driver's device through a device object.

Once a WDM driver's DriverEntry routine has completed, the driver has usually not created any devices. Instead, it has provided the kernel with various callback routine pointers. The Plug and Play (PnP) Manager calls the driver AddDevice callback routine each time the driver should create a device. The PnP Manager makes further calls to configure the device using the PnP IRP, as described in Chapter 8.

This chapter considers only two Plug and Play messages: when a device is added using AddDevice, and when it is removed. The Remove Device message is a PnP IRP with a minor function code of IRP_MN_REMOVE_DEVICE.

Device Access

User mode programs access drivers using the Win32 CreateFile function, passing a string in the lpFileName parameter. This routine is normally used to access files on disk. However, it can also be used to access a variety of other devices, such as pipes, mailslots, communication resources, or the console. At the simplest level, specifying C0M1 opens the first serial port.

To access other devices, use \\.\ at the start of the lpFileName string. The following characters specify the device to open. For example, COM1 can also be opened as \\.\COM1. This form allows devices beyond COM9 to be opened. For example, opening C0M10 will not work but \\.\COM10 will work (assuming such a device exists).

To access a device created by a driver, you must know the symbolic link name of the device. A symbolic link name is simply the name of the device exposed by the driver. Creating these names is described later.

Suppose a driver called Dongle has created a device with a symbolic link of Dongle1. A Win32 program could open it using \\.\Dongle1 as the filename parameter passed to CreateFile.

There are two aspects to opening files that are important to understand. The first is that a device can be opened more than once, either in the same process or by different processes or threads. A driver can state that a Win32 thread gets exclusive access to the device until the handle is closed. Or the Win32 program can request exclusive access by setting the CreateFile dwShareMode parameter to zero. Alternative settings of dwShareMode permit other open requests if they specify read and/or write access. Even if a Win32 thread has exclusive access to a device, it can use overlapped I/O to issue more than one request to a driver at the same time.

Your device should cope with access through multiple handles, if it permits nonexclusive access. For example, if your device supports the notion of a file pointer, it has to survive "simultaneous" read or write requests at the same file pointer location. The usual technique is to serialize all requests so that they are processed in full, one by one, as described in Chapter 16.

The second important aspect of opening a device is that Win32 programs can use file or directory names after the device name. A driver must decide whether it supports the concept of "files" when a process opens a device handle. For example, \\.\Dongle1\dir1\file1 could be used in the call to CreateFile. It is up to you whether your driver interprets such information.

Figure 5.1 illustrates a possible device access situation. The Dongle driver has created two devices, called "Dongle1" and "Dongle2". Process A has opened handles to each of the Dongle devices. Process B has opened a handle to "file" on the "Dongle2" device.

Figure 5.1 Device access

Subsequent I/O

Once a user mode program has opened a handle to your device, it can use various Win32 routines to access it, such as ReadFile, WriteFile, DeviceIoControl, and CloseHandle. Each of these calls results in a request being passed to your driver in the form of an I/O Request Packet (IRP). If a Win32 program terminates abruptly and finishes without calling CloseHandle, Windows ensures that this call is made (after cleaning up any pending I/O requests).

The Wdm1 handlers for these IRPs are described later, along with an introduction to the AddDevice and IRP_MJ_PNP handlers.

Device Objects and Device Extensions

The kernel stores information about devices in device objects, DEVICE_OBJECT structures. The relevant DEVICE_OBJECT is passed to your driver callback routines for each interaction with a device.

For example, a Win32 call to ReadFile results in a Read IRP (i.e., with major function code IRP_MJ_READ) being sent to your device. The DriverEntry routine must set up a handler for the relevant callback. In the Wdm1 driver, this routine, Wdm1Read, is passed a pointer to the relevant device object and a pointer to the IRP.

The device object is "owned" by the kernel, but has a few fields that should be used by a device driver, as described later. However, a driver can define a block of memory called a device extension, which it can use for whatever it wants. The device extension structure for each Wdm1 device is defined in Wdm1.h as shown in Listing 5.1. Your device extension structures will probably start with the same fields as Wdm1.

Listing 5.1 Wdm1 Device Extension definition

typedef struct _WDM1_DEVICE_EXTENSION {

 PDEVICE_OBJECT fdo;

 PDEVICE_OBJECT NextStackDevice;

 UNICODE_STRING ifSymlinkName;

} WDM1_DEVICE_EXTENSION, *PWDM1_DEVICE_EXTENSION;

A device is created using the IoCreateDevice kernel call. The DeviceExtensionSize parameter gives the size of the device extension required. IoCreateDevice allocates the memory for you from the nonpaged pool. Access the device extension through the device object DeviceExtension field. For example, Wdm1 accesses the its device extension using the following code.

PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

A device object is deleted using IoDeleteDevice. This routine deallocates the device extension memory. Make sure that you clean up all your device-related objects before calling IoDeleteDevice.

Creating and Deleting Device Objects

Wdm1 creates and deletes devices in the Pnp.cpp module as shown in Listing 5.2. The chapter on Plug and Play explains when the Wdm1AddDevice and Wdm1Pnp routines are called.

The NT_SUCCESS macro is used to test whether the IoCreateDevice kernel call has completed. Do not forget to check that all calls to the kernel succeed. The NT_ERROR macro is not equivalent to !NT_SUCCESS. It is better to use !NT_SUCCESS, as it catches warning status values as well as errors.

Listing 5.2 Wdm1 Pnp.cpp Create and Delete device code

NTSTATUS Wdm1AddDevice(IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT pdo) {

 …

 NTSTATUS status;

 PDEVICE_OBJECT fdo;

 // Create our Functional Device Object in fdo

 status = IoCreateDevice(DriverObject, sizeof(WDM1_DEVICE_EXTENSION),

  NULL, // No Name

  FILE_DEVICE_UNKNOWN, 0,

  FALSE, // Not exclusive

  &fdo);

 if (!NT_SUCCESS(status)) return status;

 // Remember fdo in our device extension

 PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

 dx->fdo = fdo;

 …

 // Attach to the driver stack below us

 dx->NextStackDevice = IoAttachDeviceToDeviceStack{fdo,pdo);

 // Set fdo flags appropriately

 fdo->Flags &= ~DO_DEVICE_INITIALIZING;

 fdo->Flags |= DO_BUFFERED_IO;

 …

}

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

 …

 // Device removed

 if (MinorFunction==IRP_MN_REMOVE_DEVICE) {

  // unattach from stack if (dx->NextStackDevice)

  IoDetachDevice(dx->NextStackDevice);

  // delete our fdo

  IoDeleteDevice(fdo);

 }

 return status;

}

Creating Devices

Wdm1AddDevice is called with two parameters, a pointer to the driver object and a pointer to a device object called the Physical Device Object (PDO).

Wdm1AddDevice calls IoCreateDevice to create the Wdm1 device using the parameters described in Table 5.2. The DeviceName parameter can be used to give a name to the device. However, as Wdm1 uses device interfaces, no name needs to be given, so NULL is passed here. Wdm1 devices do not correspond to any of the hardware device types, so FILE_DEVICE_UNKNOWN is given for DeviceType.

Table 5.1 IoCreateDevice function

NTSTATUS IoCreateDevice	(IRQL==PASSIVE_LEVEL)
Parameter	Description
IN PDRIVER_OBJECT DriverObject	Driver object
IN ULONG DeviceExtensionSize	Size of device extension required
IN PUNICODE_STRING DeviceName	Name of device, or NULL
IN DEVICE_TYPE DeviceType	The type of the device: one of the FILE_DEVICE_xxx values listed in the standard header WDM.H or NTDDK.H
IN ULONG DeviceCharacteristics	Various constants ORed together to indicate removable media, read only, etc.
IN BOOLEAN Exclusive	TRUE if only a single thread can access the device at a time
OUT PDEVICE_OBJECT* DeviceObject	The returned device object.

Table 5.2 IoRegisterDeviceInterface function

NTSTATUS IoRegisterDeviceInterface	(IRQL==PASSIVE_LEVEL)
Parameter	Description
IN PDEVICE_OBJECT PhysicalDeviceObject	The device PDO
IN CONST GUID *InterfaceClassGuid	The GUID being registered
IN PUNICODE_STRING ReferenceString	Usually NULL. A reference string becomes part of the interface name and so can be used to distinguish between different interfaces to the same device.
OUT PUNICODE_STRING SymbolicLinkName	The output interface symbolic link name. Do not forget to free the Unicode string buffer using RtlFreeUnicodeString when finished with it.

If IoCreateDevice returns successfully, the DeviceObject parameter is set to point to the new device object. Wdm1 calls this its Functional Device Object (FDO). The Plug and Play chapter explains FDOs and PDOs in detail. Wdm1AddDevice returns an error if IoCreateDevice fails.

The Wdm1 device extension is now available through the FDO DeviceExtension field. Wdm1AddDevice stores a pointer to the FDO in its device extension.

Wdm1AddDevice now attaches the Wdm1 device to the device stack using IoAttachDeviceToDeviceStack, which must be called at PASSIVE_LEVEL^[11]. The FDO and the given PDO are passed to this function. It returns a pointer to yet another device object that is also stored in the Wdm1 device extension. All this shenanigans are explained in the Plug and Play chapters.

Finally, two bits in the FDO Flags field must be changed. AddDevice routines must clear the DO_DEVICE_INITIALIZING flag. You do not need to clear this flag if you call IoCreateDevice in your DriverEntry routine. The DO_BUFFERED_IO flag is set in the Flags field. Again, this is covered later.

Deleting Devices

The Wdm1 driver must delete its FDO if it receives a Remove Device request. This is an IRP_ MJ_PNP_IRP with an IRP_MN_REMOVE_DEVICE minor version code. The code in Wdm1Pnp first calls IoDetachDevice to detach the FDO from the device stack. Finally, IoDeleteDevice is called to delete the FDO and its device extension.

IoDetachDevice and IoDeleteDevice must be called at IRQL PASSIVE_LEVEL

Device Names

The Wdm1 AddDevice code calls IoCreateDevice to create a Wdm1 device object. There are two ways to provide a name that is available to Win32 programs. The old way is to provide an explicit symbolic link name. The newfangled approach is to use a device interface to identify the devices that support a defined API.

Symbolic Links

The IoCreateDevice call has a DeviceName parameter that you can use to give your device a name. This name identifies the device to the kernel, not to Win32.

You must create a symbolic link to make the kernel device name available to Win32. To do this the old way, call IoCreateSymbolicLink at IRQL PASSIVE_LEVEL, passing the desired symbolic link name and the kernel device name as parameters.

Explicit device names created using this technique usually have a device number at the end. By convention, kernel device name numbers increment from zero, while symbolic link names increment from one.

The best way to illustrate device naming is using the WinObj tool, which only runs in NT and Windows 2000. WinObj is supplied in the Platform SDK, not the W2000 DDK. The standard serial ports have kernel device names \device\Serial0, \device\Serial1, etc. In WinObj, these names appear in the \device folder.

Windows provides symbolic links "C0M1", "COM2", etc., to make these serial ports available to Win32. Symbolic links appear in the \?? folder in WinObj. You can double-click on each symbolic link to find out to which kernel device it refers. The screenshot in Figure 5.2 shows that COM3, \??\com3, is a symbolic link to kernel device Serial0.

The \?? folder used to be called \DosDevices, which you might come across in some old documentation.

Figure 5.2 WinObj tool screenshot

The Wdm1 driver could have given its first device object a kernel name of \device\ Wdm1device0 and called IoCreateSymbolicLink to create a symbolic link with the name \??\Wdm1dev1. A Win32 program would then have been able to open \\.\Wdm1dev1 using CreateFile.

Note that C strings represent each \ character as "\\", so you would have to pass " \\\\.\\Wdm1dev1" to CreateFile.

If this technique is used, you must keep track of how many devices are in use, so you can generate the correct names. If you use a global variable to keep the device count, you must use it carefully to ensure that simultaneous accesses do not corrupt its value. Achieve this using the InterlockedIncrement function that atomically increments a LONG value. This can be run at any IRQL and on paged memory. There are companion decrement, exchange, and compare functions.

Explicit kernel and symbolic link names are used most often in NT style drivers, which create devices in their DriverEntry routine. In this case, counting devices is easy, as you can be sure that no other part of your code will be trying to increment the device count.

You can use the QueryDosDevice Win32 function to get a list of all the symbolic link names currently available. For each symbolic link, you can call QueryDosDevice again to find the kernel name. QueryDosDevice is supposed to run in Windows 98, but I did not succeed in getting it to work. In NT and W2000, you can use the DefineDosDevice Win32 function to change symbolic links. You can experiment with both these commands using the dosdev utility in the W2000 DDK.

Device Interfaces

The Wdm1 driver uses a device interface to make its devices visible to Win32 programs. The idea is that each Wdm1 device makes a defined Application Programmer Interface (API) available. A Globally Unique Identifier (GUID) is used to identify this interface.

The device interface that each Wdm1 device exposes is the set of commands that a Win32 programmer can use to access the device. A Wdm1 device responds to Win32 CreateFile, ReadFile, WriteFile, DeviceIoControl, and CloseHandle calls in a defined way. For example, a Wdm1 device is nonexclusive, so more than one thread can open it at the same time.

The Wdm1 driver's job is to implement a memory buffer that is shared by all the Wdm1 devices. Any writes extend the buffer, if necessary. Reads do not extend the buffer. Four IOCTLs are supported: Zero buffer, remove buffer, get buffer size, and get buffer.

One benefit of device interfaces is that another driver could be written that also implements the Wdm1 API. As long as it does this faithfully, there is no reason why a Win32 program should notice the difference between the new driver and Wdm1.

While it seems unlikely that the Wdm1 device interface will be copied by others, this technique is very useful for other types of drivers. For example, audio miniport drivers should implement the IMiniport COM interface. This is identified using the IID_IMiniport GUID and means that the driver implements two functions, GetDescription and DataRangeIntersection.

Wdm1 Device Interface

Implementing a device interface for Wdm1 devices is straightforward. First, a new 16-byte GUID must be generated using the guidgen tool. Then, include code to register the Wdm1 device interface for each Wdm1 FDO device object.

Generating GUIDs

To get a suitable new GUID, run the guidgen tool in the Platform SDK or the VC++ executables directory. Figure 5.3 shows the window that appears. guidgen can generate GUIDs in formats suitable for four different uses. For driver header file definitions, choose the DEFINE_ GUID(…) option. Pressing the Copy button copies the necessary code to the clipboard. Paste it into your header and amend the text <<name>> to define your own identifier.

Microsoft says that all GUIDs that guidgen generates are unique.

If you need to allocate a series of identifiers, press the New GUID button as often as necessary and copy each one to the relevant header file. Each new GUID increments the last digit of the first eight characters of the GUID. For example, the next GUID after the one shown in the screenshot starts {F4886541… }. In this book, I often use the form {F4886540… } as an abbreviation for the full GUID {F4886540-749E-11d2-B677-00C0DFE4C1F3}.

Figure 5.3 guidgen tool

The definition of WDM1_GUID in GUIDs.h is shown in Listing 5.3. There is a final twist in the tail for GUID definitions. One of the driver modules, Pnp.cpp in Wdm1, must have the following preprocessor directive before including GUIDs.h to formally declare WDM1_GUID.^[12]

#define INITGUID

Listing 5.3 WDM1_GUID definition in GUIDs.h

// Wdm1 device interface GUID

// {C0CF0640-5F6E-11d2-B677-00C0DFE4C1F31

DEFINE_GUID(WDM1_GUID, 0xc0cf0640, 0x5f6e, 0x11d2, 0xb6, 0x77, 0x0, 0xc0, 0xdf, 0xe4, 0xc1, 0xf3);

Device Interface Registration

Wdm1 does not give a kernel device name to its device object and does not use IoCreateSymbolicLink to create a device name accessible to Win32 programs. Instead, the Wdm1 AddDevice routine calls IoRegisterDeviceInterface to register its interface as shown in Listing 5.4. It does this after creating its device but before attaching it to the device stack. IoRegisterDeviceInterface creates a Win32 symbolic link name connection to the Wdm1 device object. This is stored in the device extension ifSymLinkNamefield.

The Wdm1AddDevice code checks the return value from IoRegisterDeviceInterface. If this call fails, it tidies up properly by deleting the FDO and returning the status error code.

The final step is to enable the device interface by calling IoSetDeviceInterfaceState, at IRQL PASSIVE_LEVEL In subsequent drivers, the device interface is only enabled when the PnP Start Device message has been received.

Listing 5.4 Wdm1 Pnp.cpp Device Interface code

// Register and enable our device interface

status = IoRegisterDeviceInterface(pdo, &WDM1_GUID, NULL, &dx->ifSymLinkName);

if (!NT_SUCCESS(status)) {

 IoDeleteDevice(fdo);

 return status;

}

IoSetDeviceInterfaceState(&dx->ifSymLinkName, TRUE);

Table 5.3 IoRegisterDeviceInterface function

NTSTATUS IoRegisterDeviceInterface
Parameter	Description
IN PDEVICE_OBJECT PhysicalDeviceObject	The device PDO
IN CONST GUID *InterfaceClassGuid	The GUID being registered
IN PUNICODE_STRING ReferenceString	Usually NULL. A reference string becomes part of the interface name and so can be used to distinguish between different interfaces to the same device.
OUT PUNICODE_STRING SymbolicLinkName	The output interface symbolic link name. Do not forget to free the Unicode string buffer using RtlFreeUnicodeString when finished with it.

The code in Wdm1Pnp to handle device removal has to be altered, as well. First, the device interface has to be disabled. Then, it must free the memory buffer allocated for the interface symbolic link name. It does not have to Unregister the device interface.

IoSetDeviceInterfaceState(&dx->ifSymLinkName, FALSE);

RtlFreeUnicodeString(&dx->ifSytnLinkName);

Device Interface Notes

As mentioned in the last chapter, registering a device interface creates a registry entry in the HKLM\System\CurrentControlSet\Control\DeviceClasses key. A subkey named after the GUID and further subkeys for each device implements that GUID. Drivers can use IoOpenDeviceInterfaceRegistryKey to open a handle to this registry key. For example, you might want to add a FriendlyName value to this key using an INF file AddInterface section, as described in Chapter 11. Win32 applications can use SetupDiOpenDeviceInterfaceRegKey to open this same key and retrieve the friendly name.

Device interface registrations can be removed from user mode, if necessary.

A driver can register that a device supports more than one device interface if desired.

IoGetDeviceInterfaces can be used by a driver to find a list of symbolic links to devices that support a specific device interface.

Behind the scenes, Windows generates a kernel device name for your device. This might be something like \devi ce\004059. The symbolic link name generated by IoRegisterDeviceInterface looks like \DosDevices\000000000000001c#{c0cf0640…}. The WinObj entry for the symbolic link looks like \??\Root#UNKN0WN#0000#{C0CF0640…}.

Win32 Device Interface Access

We are ready — at last — to access a Wdm1 device. The Wdm1Test program opens a connection to the Wdm1 driver and puts it through its paces. Remember that all the calls in this section are to Win32 routines, not to the kernel.

The source code for the Wdm1Test program is in the Wdm1\exe directory. The book software has a Visual Studio WDM Book workspace, which includes a project for the Wdm1Test program. The Wdm1Test code in Wdm1Test.cpp is listed at the end of the chapter.

Wdm1Test is a standard Win32 console application. When run, it appears in a DOS box. As it is a standard Win32 program, you can debug it in Visual Studio as normal (e.g., step through the code).

There are two points to note about the Wdm1Test project. The first is that it includes the c:\98ddk\inc\win98\setupapi.h header file. The VC++ 5 version of this file is seriously out of date, so the code specifically includes the Windows 98 DDK version. The second special setting required is to ensure that c:\98ddk\lib\i386\free\setupapi.lib is listed in the Link property page Output/library modules section of the Project settings.

Getting a Device's Interface Name

The GetDeviceViaInterface routine in Wdm1Test.cpp opens a handle to a device, given the device interface's GUID, as shown in Listing 5.5. GetDeviceViaInterface has a second parameter, instance, which is the zero-based index into the count of available devices. The total number of devices cannot be determined in advance; simply call GetDeviceViaInterface until NULL is returned.

The Wdm1Test main function calls GetDeviceViaInterface with WDM1_GUID and 0 as parameters to open the first available Wdm1 device. Special steps must be taken again to ensure that WDM1_GUID is declared properly. In one module #include "initguid.h" before including the GUID header file.

Listing 5.5 GetDeviceViaInterface

HANDLE GetDeviceViaInterface(GUID* pGuid, DWORD instance) {

 // Get handle to relevant device information set

 HDEVINFO info = SetupDiGetClassDevs(pGuid, NULL, NULL, DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);

 if (info==INVALID_HANDLE_VALUE) {

  printf("No HDEVINFO available for this GUID\n");

  return NULL;

 }

 // Get interface data for the requested instance

 SP_INTERFACE_DEVICE_DATA ifdata;

 ifdata.cbSize = sizeof(ifdata);

 if (!SetupDiEnumDeviceInterfaces(info, NULL, pGuid, instance, &ifdata)) {

  printf("No SP_INTERFACE_DEVICE_DATA available for this GUID instance \n");

  SetupDiDestroyDeviceInfoList(info);

  return NULL;

 }

 // Get size of symbolic link name

 DWORD ReqLen;

 SetupDiGetDeviceInterfaceDetail(info, &ifdata, NULL, 0, &ReqLen, NULL);

 PSP_INTERFACE_DEVICE_DETAIL_DATA ifDetail = (PSP_INTERFACE_DEVICE_DETAIL_DATA)(new char[ReqLen]);

 if (ifDetail==NULL) {

  SetupDiDestroyDeviceInfoList(info);

  return NULL;

 }

 // Get symbolic link name

 ifDetail->cbSize = sizeof(SP_INTERFACE_DEVICE_DETAIL_DATA);

 if (!SetupDiGetDeviceInterfaceDetail(info, &ifdata, ifDetail, ReqLen, NULL, NULL)) {

  SetupDiDestroyDeviceInfoList(info);

  delete ifDetail;

  return NULL;

 }

 printf("Symbolic link is %s\n",ifDetail->DevicePath):

 // Open file

 HANDLE rv = CreateFile(ifDetail->DevicePath, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);

 delete ifDetail;

 SetupDiDestroyDevicelnfoList(info);

 return rv;

}

The Win32 call to SetupDiGetClassDevs opens a "device information set" about devices with the specified GUID. The DIGCF_PRESENT and DIGCF_INTERFACEDEVICE flags ensure that only devices that are present are found.

SetupDiEnumDeviceInterfaces is then called to retrieve a SP_INTERFACE_DEVICE_DATA context structure of information about the device instance in which you are interested. GetDeviceViaInterface tries to retrieve information about only one instance, but you might want to find all instances by incrementing the MemberIndex parameter from 0 until SetupDiEnumDeviceInterfaces fails and GetLastError returns ERROR_NO_MORE_ITEMS.

The next task is to obtain the symbolic link name for the instance that has been found. This string is in the PSP_INTERFACE_DEVICE_DETAIL_DATA ifDetail structure returned by a call to SetupDiGetDeviceInterfaceDetail. SetupDiGetDeviceInterfaceDetail must be called twice. The first call retrieves the required size for ifDetail, while the second actually gets the structure.

Eventually ifDetail->DevicePath contains the filename that is used to open a handle to the relevant Wdm1 device. This filename is passed to CreateFile and then ifDetail is deleted. Do not forget to call SetupDiDestroyDeviceInfoList on all paths to close the device information set.

The call to CreateFile in GetDeviceViaInterface uses a pretty standard set of parameters. As noted before, you can change the share and access modes, if necessary. Further, the device can be opened for overlapped nonblocking access. Overlapped access works for devices in Windows 98, NT, and Windows 2000 and lets an application issue an I/O request and get on with other work while the request is being processed. The detailed explanation of the DebugPrint Monitor program in Chapter 14 gives an example of this technique.

Running Wdm1Test

Simply run Wdm1Test.exe in the Wdm1\exe\Release directory. Make sure that the Wdm1 driver is installed. Wdm1Test is a console application running in a DOS box. Press the Enter key to exit the program.

If you run Wdm1Test in W2000, the output should look like that given in Listing 5.6. The first time round, Test 2 is designed to fail; subsequent tests should succeed. In Windows 98, the output is different, as it does not seem to support the SetFilePointer function on devices, such as Wdm1.

The rest of the Wdm1Test main function performs each of these tests in turn.

1. Open the first Wdm1 device.

2. Read the first DWORD stored in the shared memory buffer. This will fail first time round, as there will be nothing in the buffer.

3. Write 0x12345678 to the start of the buffer. 0x78 is written at file pointer zero, 0x56 at one, 0x34 at two, and 0x12 at three.

4. Set the file pointer to position 3.

5. Read one byte from the file. This should be 0x12.

6. Write 0x12345678 to the buffer starting at file position 3.

7. Use an IOCTL to get the buffer size, which should be 7 (i.e., 3+4).

8. Use an IOCTL to get the entire buffer. The first word is printed and should be 0x78345678.

9. Check that issuing an IOCTL with an invalid parameter fails. The IOCTL asks for the entire buffer with a request size that is too big.

10. Use an IOCTL to zero all the bytes in the buffer. Get the entire buffer again. The first word is printed which should be 0x00000000.

11. Use an IOCTL to remove the buffer. Check that the buffer size is now zero.

12. Try to issue an invalid IOCTL code. Confirm that this fails.

13. Write 0xabcdef01 to the start of the buffer. When Wdm1Test is run next, Test 2 should find this value.

Listing 5.6 Wdm1Test output on W2000

Test 1

Symbolic link is \\?\root#unknown#0003#{c0cf0640-5f6e-11d2-b677-00c0dfe4c1f3}

 Opened OK

Test 2

 Read successfully read stored value of 0xABC0EF01

Test 3

 Write 0x12345678 succeeded

Test 4

 SetFilePointer worked

Test 5

 Read successfully read stored value of 0x12

Test 6

 Write at new file pointer succeeded

Test 7

 Buffer size is 7 (4 bytes returned)

Test 8

 First DWORD of buffer is 78345678 (7 bytes returned)

Test 9

 Too big get buffer failed correctly 87

Test 10

 Zero buffer succeeded

 First DWORD of buffer is 00000000 (7 bytes returned)

Test 11

 Remove buffer succeeded

 Buffer size is 0 (4 bytes returned)

Test 12

 Unrecognised IOCTL correctly failed 1

Test 13

 SetFilePointer worked Write 0xabcdef01 succeeded

Test 14

 CloseHandle worked

 Press enter please

Wdm1Test exercises all the functions of the Wdm1 driver. It checks that things that should work do work, and things that should fail do fail.

Writing this test program showed that the Wdm1 device does behave differently in Windows 98 and Windows 2000. However, the problem does not lie in the driver itself, but is due to Windows 98 not supporting SetFilePointer for device files.

Conclusion

This chapter shows how to open a connection to a Wdm1 device using device interfaces. The Wdm1Test user mode program puts the Wdm1 driver through its paces.

Chapter 7 shows how Wdm1 implements the read, write, and IOCTL calls. However, before I continue looking at the driver, the next chapter describes how to test and debug drivers. It explains how this book uses the DebugPrint software to see what is going on in a driver.

Listing 5.7 Wdm1Test.cpp

///////////////////////////////////////////////////////////////////////

//Copyright © 1998 Chris Cant, PHD Computer Consultants Ltd

//WDM Book for R&D Books, Miller Freeman Inc

//

//Wdm1Test example

///////////////////////////////////////////////////////////////////////

//WdmlTest.cpp:Win32 console application to exercise Wdm1 devices

///////////////////////////////////////////////////////////////////////

//mainProgram main line

//GetDeviceVialnterfaceOpen a handle via a device interface

///////////////////////////////////////////////////////////////////////

//Version history

//27-Apr-991.0.0CCcreation

///////////////////////////////////////////////////////////////////////

#include "windows.h"

#include "C:\98ddk\inc\win98\setupapi.h"// VC++ 5 one is out of date

#include "stdio.h"

#include "initguid.h"

#include "..\sys\GUIDs.h"

#include "winioctl.h"

#include "..\sys\Ioctl.h"

HANDLE GetDeviceViaInterface(GUID* pGuid, DWORD instance);

int main(int argc, char* argv[]) {

 int TestNo = 1;

 //////////////////////////////////////////////////////////////////////

 // Open device

 printf("\nTest %d\n",TestNo++);

 HANDLE hWdm1 = GetDeviceViaInterface((LPGUID)&WDM1_GUID,0);

 if (hWdml==NULL) {

  printf("XXX Could not find open Wdm1 device\n");

  return 1;

 }

 printf(" Opened OK\n");

 //////////////////////////////////////////////////////////////////////

 // Read first ULONG that's left in buffer

 printf("\nTest %d\n",TestNo++);

 DWORD TxdBytes;

 ULONG Rvalue =0;

 if (!ReadFile(hWdm1, &Rvalue, 4, &TxdBytes, NULL)) printf("XXX Could not read value %d\n", GetLastError());

 else if(TxdBytes==4) printf(" Read successfully read stored value of 0x%X\n",Rvalue);

 else printf("XXX Wrong number of bytes read: %d\n",TxdBytes);

 //////////////////////////////////////////////////////////////////////

 // Write 0x12345678

 printf("\nTest M\n" ,TestNo++);

 ULONG Wvalue = 0x12345678;

 if (!WriteFile(hWdm1, &Wvalue, 4, &TxdBytes, NULL)) printf("XXX Could not write %X\n",Wvalue);

 else if (TxdBytes==4) printf(" Write 0x12345678 succeeded\n");

 else printf("XXX Wrong number of bytes written: %d\n",TxdBytes);

 //////////////////////////////////////////////////////////////////////

 // Set file pointer

 printf("\nTest %d\n",TestNo++);

 DWORD dwNewPtr = SetFilePointer(hWdrn1, 3, NULL, FILE_BEGIN);

 if (dwNewPtr==0xFFFFFFFF) printf("XXX SetFilePointer failed %d\n", GetLastError());

 else printf(" SetFilePointer worked\n");

 //////////////////////////////////////////////////////////////////////

 // Read

 printf("\nTest %d\n",TestNo++);

 Rvalue = 0;

 if (!ReadFile(hWdm1, &Rvalue, 1, &TxdBytes, NULL)) printf("XXX Could not read value\n");

 else if( TxdBytes==1) printf(" Read successfully read stored value of 0x%X\n",Rvalue);

 else printf("XXX Wrong number of bytes read: %d\n",TxdBytes);

 //////////////////////////////////////////////////////////////////////

 // Write

 printf("\nTest %d\n",TestNo++);

 if (!WriteFile(hWdm1, &Wvalue, 4, &TxdBytes, NULL)) printf("XXX Could not write %X\n" ,Wvalue);

 else if (TxdBytes==4) printf(" Write at new file pointer succeeded\n");

 else printf("XXX Wrong number of bytes written: %d\n",TxdBytes);

 //////////////////////////////////////////////////////////////////////

 // Get buffer size

 printf("\nTest %d\n",TestNo++);

 ULONG BufferSize;

 DWORD BytesReturned;

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_GET_BUFFER_SIZE,

  NULL, 0,// Input

  &BufferSize, sizeof(ULONG),// Output

  &BytesReturned, NULL)) printf("XXX Could not get buffer size\n");

 else printf(" Buffer size is %i (%d bytes returned)\n",BufferSize,BytesReturned);

 //////////////////////////////////////////////////////////////////////

 // Get buffer size

 printf("\nTest %d\n",TestNo++);

 char* Buffer = new char[BufferSize+1];

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_GET_BUFFER,

  NULL, 0,// Input

  Buffer, BufferSize,// Output

  &BytesReturned, NULL)) printf("XXX Could not get buffer\n");

 else printf(" First DWORD of buffer is %08X (%d bytes returned)\n",*((DWORD*)Buffer),Bytes Returned);

 ///////////////////////////////////////////////////////////////////////

 // Get too big a buffer size

 printf("\nTest %d\n",TestNo++);

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_GET_BUFFER,

  NULL, 0,// Input

  Buffer, BufferSize+1,// Output

  &BytesReturned, NULL)) printf(" Too big get buffer failed correctly %d\n",GetLastError());

 else printf("XXX Too big get buffer unexpectedly succeeded\n");

 ///////////////////////////////////////////////////////////////////////

 // Zero all buffer bytes

 printf("\nTest %d\n",TestNo++);

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_ZERO_BUFFER,

  NULL, 0,// Input

  NULL, 0,// Output

  &BytesReturned, NULL)) printf("XXX Zero buffer failed %d\n" ,GetLastError());

 else printf(" Zero buffer succeeded\n");

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_GET_BUFFER,

  NULL, 0,// Input

  Buffer, BufferSize,// Output

  &BytesReturned, NULL)) printf("XXX Could not get buffer\n");

 else printf(" First DWORD of buffer is %08X (%d bytes returned)\ n",*((DWORD*)Buffer),BytesReturned);

 ///////////////////////////////////////////////////////////////////////

 // Remove buffer

 printf("\nTest %d\n",TestNo++);

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_REMOVE_BUFFER,

  NULL, 0,// Input

  NULL, 0,// Output

  &BytesReturned, NULL)) printf("XXX Remove buffer failed %d\n",GetLastError());

 else printf(" Remove buffer succeeded\n");

 if (!DeviceloControl(hWdm1, IOCTL_WDM1_GET_BUFFER_SIZE,

  NULL, 0,// Input

  &BufferSize, sizeof(ULONG),// Output

  &BytesReturned, NULL)) printf("XXX Could not get buffer size\n");

 else printf(" Buffer size is %i (%d bytes returned)\n",BufferSize,BytesReturned);

 ///////////////////////////////////////////////////////////////////////

 // Unrecognised IOCTL

 printf("\nTest %d\n",TestNo++);

 if (!DeviceIoControl(hWdm1, IOCTL_WDM1_UNRECOGNISED,

  NULL, 0,// Input

  NULL, 0,1/ Output

  &BytesReturned, NULL)) printf(" Unrecognised IOCTL correctly failed %d\n",GetLastError());

 else printf("XXX Unrecognised IOCTL unexpectedly succeeded\n");

 ///////////////////////////////////////////////////////////////////////

 // Write 0xabcdef01 to start of buffer

 printf("\nTest %d\n",TestNo++);

 dwNewPtr = SetFilePointer(hWdm1, 0, NULL, FILE_BEGIN);

 if (dwNewPtr==0xFFFFFFFF) printf("XXX SetFilePointer failed %d\n",GetLastError());

 else printf(" SetFilePointer worked\n");

 Wvalue = 0xabcdef01;

 if (!WriteFile(hWdm1, &Wvalue, 4, &TxdBytes, NULL)) printf("XXX Could not write %X\n", Wvalue);

 else if( TxdBytes==4) printf(" Write 0xabcdef01 succeeded\n");

 else printf("XXX Wrong number of bytes written: %d\n",TxdBytes);

 /////////////////////////////////////////////////////////////////////////

 // Close device

 printf("\nTest %d\n",TestNo++);

 if (!CloseHandle(hWdm1)) printf("XXX CloseHandle failed %d\n", GetLastError());

 else printf(" CloseHandle worked\n");

 /////////////////////////////////////////////////////////////////////////

 delete Buffer;

 printf("\nPress enter please");

 char line[80];

 gets(line);

 return 0;

}

//////////////////////////////////////////////////////////////////////////

//GetDeviceViaInterface:Open a handle via a device interface

HANDLE GetDeviceViaInterface(GUID* pGuid, DWORD instance) {

 // Get handle to relevant device information set

 HDEVINFO info = SetupDiGetClassDevs(pGuid, NULL, NULL, DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);

 if (info==INVALID_HANDLE_VALUE) {

  printf("No HDEVINFO available for this GUID\n");

  return NULL;

 }

 // Get interface data for the requested instance

 SP_INTERFACE_DEVICE_DATA ifdata;

 ifdata.cbSize = sizeof(ifdata);

 if (!SetupDiEnumDeviceInterfaces(info, NULL, pGuid, instance, &ifdata)) {

  printf("No SP_INTERFACE_DEVICE_DATA available for this GUID instance\n");

  SetupDiDestroyDeviceInfoList(info);

  return NULL;

 }

 // Get size of symbolic link name

 DWORD ReqLen;

 SetupDiGetDeviceInterfaceDetail(info, &ifdata, NULL, 0, &ReqLen, NULL);

 PSP_INTERFACE_DEVICE_DETAIL_DATA ifDetail = (PSP_INTERFACE_DEVICE_DETAIL_DATA)(new char[ReqLen]);

 if (ifDetail==NULL) {

  SetupDiDestroyDeviceInfoList(info);

  return NULL;

 }

 // Get symbolic link name

 ifDetail->cbSize = sizeof(SP_INTERFACE_DEVICE_DETAIL_DATA);

 if (!SetupDiGetDeviceInterfaceDetail(info, &ifdata, ifDetail, ReqLen, NULL, NULL)) {

  SetupDiDestroyDeviceInfoList(info);

  delete ifDetail;

  return NULL;

 }

 printf("Symbolic link is %s\n", ifDetail–>DevicePath);

 // Open file

 HANDLE rv = CreateFile(ifDetail->DevicePath, GENERIC_READ | GENERIC_WRITE, FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);

 delete ifDetail;

 SetupDiDestroyDeviceInfoList(info);

 return rv;

}

///////////////////////////////////////////////////////////////////////

Before looking at other aspects of WDM drivers, it is worth while looking at how to test and debug drivers. This chapter explains how to use the DebugPrint tool that comes with the book software. This lets a driver "print" debug event messages to a Win32 application, the DebugPrint Monitor.

A later chapter looks in detail at how the DebugPrint software works.

Keep your driver as simple as possible to make it easier to test and debug.

Oh, and needless to say — but I will say it anyway — comment your driver very well. Document it well. Do not forget to update your comments and documentation as the driver develops.

Test, Test, Test

Developers usually want to start debugging only when they suspect something has gone wrong with their software. However, it is especially important to start work early with device drivers. Even if you think a driver is doing its job, check it thoroughly. Do not get a first cut working and ship it to customers immediately.

Here is an example of a situation where I did not test code properly. When developing the DebugPrint software, I needed to implement a formatted print function. I could not use sprintf, as this function might use facilities that are not available to kernel mode drivers.

To make things simple, I developed the routines in a Win32 program and got them working. I copied the source over to the DebugPrint driver. A quick test seemed to indicate that it worked OK. In fact, I had changed something and so my handling of ellipsis arguments went wrong (passing a variable number of arguments to a function). By a complete fluke, one of the simple tests I inserted did get the correct information from the stack. It took a while to realize the error of my ways.

Driver Tests

This section describes some of the testing issues that are particularly important for device drivers. The following debugging section highlights some of the typical ways that drivers fail. If you — and only you — are writing the user mode program that accesses your driver, you may be able to impose certain constraints on your driver. For example, you could dictate that only one request is ever issued at a time. This would make some of your routines slightly easier to implement. However, it is best to write your routines properly straightaway. It is quite possible for someone to later change the Win32 code without realizing that it might break your driver.

Test That All Functions Work

This may sounds obvious, but check that your driver works. This means writing a test program (or other driver) that exercises all of its functions.

As with any other program, check that all sorts of data work as expected. For example, check that invalid parameters are detected properly. Check that small and large amounts of data can be transferred. Check boundary conditions. For example, if you have a maximum request size of 1024 bytes, check that transfers of 0, 1, 1023, and 1024 bytes succeed and that transfers of 1025 bytes fail.

Check that all the features of the hardware you are driving are exercised. Do you have a strategy for coping with hardware updates? For example, leave some room for more function codes. Make sure that your new hardware firmware can be used by the old driver.

Check that a driver works in stress situations (e.g., in low memory computers or when being pummelled by lots of requests). Do this by repeatedly issuing I/O requests to your driver. Test with other processes doing the same job simultaneously. Another good test is to run your driver while copying a large file to a floppy disk; in Windows 98, this seems to stop most other activities dead in their tracks.

Check that a driver works when more than one of its devices are in use. Check that several user programs or threads can access the driver simultaneously.

Check that your driver works on a clean PC that has never seen your driver. Test on plain vanilla W2000 and W98 systems, without any of the development environment. Check that you installed any recent DLLs that are needed. For example, your user mode installation code may not run with an out-of-date version of SETUPAPI.DLL.

W2000 and W98

Do all your tests in Windows 2000 and Windows 98 if you are writing a driver that runs under both operating systems. If you provide a Dec Alpha W2000 version, check that it works as well.

In particular, check that a driver installs correctly in both operating systems. W2000 and W98 use different locations for some registry entries, though this should not effect most drivers.

Some facilities are only available in NT or W2000. For example, a driver can make calls to write events to the system log. In W98, these functions do nothing. Check that they work properly in NT and Windows 2000.

As long as you use the correct WDM.H header, you should not be making any kernel calls that work only in W2000. For example, I was going to use the ExSystemTimeToLocalTime kernel call in the DebugPrint driver. However, the documentation says that you must include NTDDK.H. This means that the call is not available in W98.

Multiprocessor

If possible, check that your driver works in a multiprocessor computer. Even if you do run it on such a computer, you may have difficulty deciding whether it has passed the test as the time-critical events may not happen very often. Stress testing the driver should force the issue.

Cancelling I/O

Win32 programs can issue asynchronous "overlapped" I/O requests, meaning that they can issue a request and get on with another job while the I/O is happening. Windows 98 programs cannot issue such requests for file I/O, but they can for device I/O.

Initially, there seems to be no difference as far as a device driver is concerned. Both synchronous "blocking" I/O requests and asynchronous I/O requests arrive at the driver in the same way, through the driver dispatch entry points.

However, asynchronous I/O requests can be cancelled. This can happen either when the CancelIo function^[13] is called, or if the file handle is closed with the I/O still pending.

Synchronous I/O requests are also cancelled if a process crashes. The operating system tries to cancel any requests and close any open file handles.

How a driver copes with cancelling I/O is covered in a later chapter. Ensure that your test program checks these situations.

Debugging

Win32 user mode programs run within the protective arms of the operating system. For example, it stops them accessing memory that is not in a task's address space. Windows 98 programs have some of the kernel mapped into its upper addresses, so user mode programs could trample on the kernel. The protection offered by NT and Windows 2000 is better. If a user mode application runs into problems, it is usually possible to stop the program and carry on with other work.

A device driver has none of this protection because it is part of the kernel. Be especially careful to test your driver fully or you may lose data. Be prepared for the worst on your own development computer by making regular backups.

Although problems with a driver can be a real pain, it can eventually give you a greater understanding of what you are doing. You have to inspect each call or section of code carefully. Rather than just following the instructions given here, you may eventually really know what is going on. Or even, heaven forbid, why the system was designed to work the way it does. You may have suggestions for how drivers or the system might be improved.

How Do Things Go Wrong?

Windows 98 and Windows 2000 sometimes react differently to errors in drivers.

Crashes

A fatal error in NT or W2000 causes the "blue screen of death", properly called a "bugcheck". You must reset the computer to continue. The blue screen gives an indication of the error, and usually a list of the kernel modules and a stack trace. More details of how to decode this information are given later. Annoying though these bug checks are, they do stop further damage being done to the operating system, such as corrupting disks.

NT and W2000 usually log a "Save Dump" event for a bugcheck, listing the most pertinent information. An event may not be logged if the bugcheck occurred at boot time, before the event log service has started.

In W98, a similar blue screen appears for fatal errors, again giving a brief description of what went wrong. W98 can usually carry on, but it may be best to restart the PC.

The two most common causes of fatal errors are

• Accessing nonexistent memory

• Accessing paged memory at or above DISPATCH_LEVEL IRL

Core Dumps

If NT or W2000 has a bugcheck, you can also get it to produce core dumps in a file on disk, called memory.dmp by default. You have to enable this option in the Control Panel System applet Advanced tab Startup and Recovery section. You can use the WinDbg and DumpExam tools to inspect the dump. However, I found that using WinDbg in this way was not particularly productive.

In NT and W2000, you can include information in the core dump by calling KeInitializeCallbackRecord and KeRegisterBugCheckCallback. In the event of a bugcheck, your callback routine is called to store any state information in the core dump.

Driver Will Not Start

When you update a driver like Wdm1, the Device Manager may state that you need to restart the system before the driver will run. This means that the driver returned an error while loading.

There are two possible causes for such errors. Suppose your driver will start when the system reboots. This means that when it unloads it must be leaving something around that stops it from starting again. A common problem is forgetting to delete your device or the symbolic link to your device.

If your driver will not start when the system reboots, it means that you must have changed your driver so that the DriverEntry routine fails. Trace through the code to work out what is going wrong.

Just to complicate matters, in some circumstances, Windows needs to juggle the revised system resources when a driver is reloaded. In this case, Windows will not even attempt to start your driver if a reboot is necessary to satisfy the resource allocation process.

Hang Ups

A user thread can hang up if you never complete an IRP. The thread will never be able to complete. Have you queued the IRP somewhere and never processed it?

A driver can also hang up if it cannot acquire a resource that it needs. The different resources are described later. If a resource is unavailable, it may mean that just one IRP cannot be processed, or it could mean that all IRP processing grinds to halt.

A "deadly embrace" occurs if two different pieces of code are trying to access the same resources. For example, code A might hold resource X and want resource Y. If code B holds Y and wants X, then a deadly embrace occurs, hanging the whole system. The simplest solution is to always acquire resources in the same order.

You can also get hang ups if you try to acquire a resource more than once, or if your interrupt service routine never returns. Continual interrupts can seriously degrade the system performance.

Resource Leaks

Resource leaks are less dire, but still important to fix. For example, if you forget to free some memory allocated during each read, the system will eventually run out of memory.

Some resources are more important than others. For example, nonpaged memory should be used conservatively.

Time Dependencies

Possibly the worst type of problem to sort out is related to timing.

At the simplest level, a timing problem can simply mean that you have not filled a buffer quickly enough. For example, if your hardware needs to output data regularly, you may not have provided it with the data. Or did you fill it too quickly? Check that your driver works on different speed computers.

Another possible problem is that your driver may not be reading data quickly enough. For example, an isochronous device, such as a microphone, may generate a regular number of samples per second. Check that you can keep reading data at this speed, even in a stressed system. Alternatively, have a strategy for skipping samples (e.g., a call to your device to drop samples).

Debugging Techniques

Incremental Development

An incremental approach makes debugging far easier. Get each stage working and tested before moving onto the next stage.

An incremental approach still means that you should do proper design work. Think very carefully about how your driver is going to work before starting any development. Having decided upon a design, plan a development path that allows you to implement your design in stages.

Checked Version

Driver development environments are usually set up to produce two different builds: an optimized retail release version, called the free build, and an unoptimised test debug build, called the checked build.

Put any debug or test code so that it appears in the checked build. The simplest way to do this is to check the value of the preprocessor variable DBG, which is set to 1 in the checked build and 0 in free build. Here is an example of how to use this technique.

#if DBG

 DebugPrintInit("Wdm1 checked");

#else

 DebugPrintInit("Wdm1 free");

#endif

I shall soon look at the different types of debug code that you can put in your checked version.

Running under the checked build version of NT or W2000 can also pick up driver errors as the operating system makes more internal checks.

W2000 or W98

One decision you will need to make is whether to work primarily in Windows 2000 or Windows 98. You could set up the development environment in one operating system, and only do test installs in the other. As stated previously, you ought to be testing your driver in both operating systems.

My advice is to use Windows 2000 for development. A few useful tools are only available in W2000 (and NT). And, significantly, W2000 is better at detecting driver errors. For example, W2000 will usually cause a bugcheck when you try to access a bad address, such as writing to a NULL pointer. Windows 98 may not detect this sort of error and your driver will continue, oblivious to the problem. The downside to W2000 is that it takes a bit longer to restart.

It is useful to be able to dual boot a computer with Windows 2000 and Windows 98. If a device fails during system boot, you can use the other operating system to remove the offending driver temporarily. For this technique to work, you need the Windows 2000 system drive to be accessible to Windows 98 (i.e., not formatted in NTFS).

Debugging Tools

Apart from using your brain, there are two basic techniques for debugging. The first is to include "print" statements of some sort in your driver. The second is to do source code level debugging.

Windows 2000 Events

One way of reporting data is to generate NT and Windows 2000 event messages. For a commercial driver, you should use this facility to report any abnormal events to system administrators. However, it is somewhat complicated to set up a connection between a message number and the string it represents. You can include strings and data values as a part of the event.

The NT and Windows 2000 event viewer does not have the best display in the world, and it does not automatically update itself. Windows 98 has no event viewer.

Generating Windows Management Instrumentation (WMI) events is theoretically a way for a driver to report events. While this has the advantage that you should be able to view the data across a network, it is not a serious proposition for driver development, as it is even harder work to see events.

Tracing Tools

There are better tools available to display driver "print" trace statements. The next section discusses the DebugPrint software. This lets a driver use formatted print statements in the code. The output appears in a user mode monitor application.

As mentioned previously, two similar tools are available commercially: Driver Monitor in the Compuware Numega DriverWorks software, and OSRTracer in the Open Systems Resources OSR DDK software.

Driver Verifier

Windows 2000 includes Driver Verify for catching some common types of driver error. Use the Driver Verifier Manager (Start+Programs+Development Kits+Windows 2000 DDK+Driver Verifier) to change the driver verify settings.

Drivers can corrupt memory by accessing outside their allocated buffers. W2000 can use a special pool, with inaccessible memory at either side of a buffer. If you try to write to the inaccessible memory, a bugcheck occurs. The facility can be turned on for all your driver's memory requests. Alternatively, you can use it selectively by calling ExAllocatePoolWithTag with an appropriate Tag parameter.

Another common mistake is to access paged memory at DISPATCH_LEVEL IRQL or higher. A driver may "get away with it" if the paged memory is resident. Driver Verify can flush all paged memory to disk before your driver is called at elevated IRQL.

Drivers must also cope well if a memory request fails. Another Driver Verify feature can forcibly fail a random number of memory allocation requests.

Debuggers

The final and most powerful tool is a debugger. Standard user mode debuggers like Visual Studio do not work with drivers.

Instead, you must use a debugger designed for the job. The Microsoft DDKs come with the WinDbg debugger for NT and Windows 2000 systems. To use this, you must have two PCs — one running a checked build of NT/W2000 and another the free build — connected together using a serial cable. A normal network connection will also be useful. You can insert trace statements and debug at source-level. There are instructions for WinDbg in the DDKs. It will not be covered in this book.

NuMega Compuware at www.numega.com sells a debugger called SoftICE, which lets you to debug at source-level on a single PC.

DebugPrint

This book includes the DebugPrint software, which lets you use formatted print statements to trace the execution of a driver. Although not the ultimate debugging solution, it certainly gives a driver writer a useful tool for tracing what code a driver runs and what data is in variables. DebugPrint works in Windows 2000 and Windows 98, but not in earlier versions of these operating systems.

The source code of the DebugPrint driver and user mode monitor are included with the book. The DebugPrint driver serves to illustrate several driver development techniques. The DebugPrint source is described in Chapter 14.

DebugPrint is described in full on the web site www.phdcc.com/debugprint.

Trying out DebugPrint

To use DebugPrint, you must first install the DebugPrint driver. Do this in a similar way to the Wdm1 driver. This time, browse to the DebugPrint\sys directory and install the free build driver called "DebugPrint driver debugging tool".

You can now use the DebugPrint Monitor application to listen for trace print events from drivers that you are testing. You will probably find it convenient to set up a shortcut to this application at DebugPrint\exe\Release\DebugPrintMonitor.exe.

The Wdm1 driver includes various calls to the DebugPrint software. However, these calls only appear in the checked build of the driver. (You can opt to include the DebugPrint output in free builds.)

If you now reinstall the Wdm1 driver, selecting the checked build, you should see various events in the DebugPrint Monitor window, as shown in Figure 6.1. The displayed output is described in the next chapter.

Figure 6.1 Sample DebugPrint Monitor output

Using the DebugPrint Monitor

The DebugPrint Monitor program runs on the same computer as the drivers you are testing. It is a standard user mode MFC Win32 application that needs the shared MFC42.DLL library.

The Monitor is very easy to use. When started, it begins listening for DebugPrint trace events. If any events are buffered up, these are read and displayed first.

The Monitor displays one event per line. It has columns for the driver name, a timestamp, and the actual trace message. The latest event is always scrolled into view.

Use the Edit+Delete events menu to clear all the events from the display.

You can save the current list of events to a .dpm file. This is an ASCII text file with the columns separated by tab characters. You can reload .dpm files.

The Monitor remembers its position on the screen and the column widths. Printing events is not yet supported.

Using DebugPrint in Drivers

First, you must copy two standard source files into your driver project, DebugPrint.c and DebugPrint.h. Include DebugPrint.h in the driver's main header file. Amend the SOURCES file so that DebugPrint.c is built. These files are in the Wdm1 project source code.

Make calls to the DebugPrint functions in your driver code. You can only make these calls at DISPATCH_LEVEL IRQL or lower. This means that you can make DebugPrint calls in your DriverEntry, the main IRP dispatch routines, and in StartIo and Deferred Procedure Call (DPC) routines, but not in interrupt handling routines. The DebugPrintInit routine must be called at PASSIVE_LEVEL

By default, the DebugPrint source only prints in the "checked" debug build. However, you can force it to work in the "free" build by setting the DEBUGPRINT preprocessor variable to 1 before you include DebugPrint.h, e.g.,

#define DEBUGPRINT 1

The DebugPrint functions will never overflow the internal output buffer that they allocate. All wide characters are simply cast to single-byte ANSI characters when they are put in an output string.

DebugPrint calls should only introduce minor delays into the execution of your driver. The main work of the DebugPrint calls takes place in a system thread that runs in the background at a low real-time priority.

DebugPrint Calls

Listing 6.1 illustrates a typical series of DebugPrint calls in three standard driver routines.

Listing 6.1 Typical DebugPrint calls

NTSTATUS DriverEntry(…) {

#if DBG

 DebugPrintInit(Wdm1 checked");

#else

 DebugPrintInit("Wdm1 free");

#endif

 …

 DebugPrint("RegistryPath is %T", RegistryPath);

 …

}

NTSTATUS Read(…) {

 …

 DebugPrint("IRP %I. Reading %u bytes from %x", Irp, IrpStack->Parameters.Read.Length, Irp->AssociatedIrp.SystemBuffer);

 …

}

VOID Unload() {

 …

 DebugPrintClose();

}

Call DebugPrintInit to initialize the connection to the DebugPrint driver, passing the name of your driver as an ANSI NULL-terminated string. You typically use DebugPrintInit in your DriverEntry routine. Call DebugPrintClose to close the connection in your driver unload routine.

You can write simple NULL-terminated ANSI strings using DebugPrintMsg. For formatted print trace statements, use DebugPrint or DebugPrint2. DebugPrint uses an internal 100-byte buffer. DebugPrint2 lets you specify the size of buffer to allocate.

Calls to DebugPrint or DebugPrint2 must include a NULL-terminated ANSI format specification string, which may include one or more format specifier characters shown in Table 6.1 (e.g., %c for an ANSI character). You must provide an extra argument for each specifier in your format string. Failure to get this right could very easily result in an access violation. Be careful to use the correct uppercase or lowercase format specifier type character.

The available format specifiers cover a range of useful types. %I prints out the major and minor codes of an IRP. %T prints a UNICODE_STRING. Line feed and carriage return characters in the format string are ignored.

The %l, %L, %s, %S, and %x format specifier characters let you use one or more modifier characters to specify the maximum output width (e.g., %*l and %nl). The * modifier takes the maximum size from the next integer parameter to DebugPrint or DebugPrint2. The n modifier specifies the exact output width; where n is one or more characters between 1 and 9.

Table 6.1 DebugPrint format specifiers 

	Format Specifier	Type
%c	ANSI character	char
%C	Wide character	wchar_t
%d, %i	Signed integer in decimal	int
%D	__int64 in decimal	__int64
%I	IRP major and minor codes	PIRP
%l	__int64 in hexadecimal	__int64
%L	LARGE_INTEGER in hexadecimal	LARGE_INTEGER
%s	NULL-terminated ANSI character string	char*
%S	NULL-terminated Wide character string	wchar_t*
%T	UNICODE_STRING	PUNICODE_STRING
%u	ULONG in decimal	ULONG
%x	ULONG in hexadecimal	ULONG

Debugging Notes

Here are some notes on how to deal with some common debugging problems.

Updating Drivers

Updating a driver is fairly straightforward. The makefile for the examples in this book copy the new driver to the Windows System32\drivers directory. However, the old version will still be running in memory.

To use the new version you have to update the drivers for your device(s). Use the Update/Change driver option in the Device Manager properties for a device. Opt to "display a list of drivers in a specific location, so you can select the driver you want".

For the Wdm1 driver, select "Other Devices". You should see the list of book software drivers that you have installed. Select the one you want from this list. You do not have to select the Have Disk button (unless you want to install the checked version, say).

If asked, opt to use the new driver even if the Device Manager suggests that the current version may be newer. Windows 98 will force you to browse for the driver files. W2000 uses the driver files in the System32\drivers directory.

As noted above, if the new driver returns an error during its initialization then Windows will say that the system needs to reboot. Rebooting may not cure the problem.

NT Style Drivers

As mentioned in an earlier chapter you must update NT style drivers in a different way. As usual, you must get your driver into the Windows System32\drivers directory.

Run the Control Panel Devices applet. Find your driver, stop it, and start it again. You can also run the book software Servicer applet; type in the name of your driver, press Stop and then Start. If you run an NT style driver in Windows 98 you must reboot the computer to use an updated driver.

Driver Fails on Boot

If your driver fails catastrophically during system boot, the system will not load, which makes it tricky to delete or change the offending driver.

There are three solutions to this problem. In a dual boot system, simply reboot in the other operating system and delete or change the driver. Alternatively, both W2000 and W98 have "Safe mode" boot options that should allow you to start Windows, while only loading the most basic system drivers. Delete the offending driver and restart. A final option is to have a bootable floppy disk with a copy of Windows 98. Use this as a quick boot to delete the offending driver files.

Driver Dependencies

Watch out for one driver depending on another. The Wdm1 driver opens a handle to the DebugPrint driver during its initialization, and releases it only when the driver unloads. This means that the DebugPrint driver cannot be replaced while Wdm1 is running. To change the DebugPrint driver, Wdm1 has to be unloaded. Only when the new DebugPrint is safely running, can a Wdm1 device be installed again. 

Uncanceled IRPs

If a driver queues IRPs but does not provide suitable cancel or cleanup routines, a Win32 program could hang up if it calls CancelIo or exits with file handles open. In this case, the Win32 program appears to have exited but it is still locked in memory, so you will not be able to update it.

The I/O Manager gives a driver five minutes to cancel IRPs. After this time, it displays a message to the user and any pending IRPs are dissociated from the terminating thread.

A reboot is usually necessary to clear this situation.

Bugcheck Codes

When Windows 2000 bugchecks, it displays information in the "blue screen of death" and stops dead. The information on this screen can help you to track down the source of the problem. You can cause a bugcheck deliberately using the KeBugCheck and KeBugCheckEx routines. A debug version of your driver might do this if it detects some unsolvable problem. Release drivers should never bugcheck voluntarily.

A problem in your driver may not directly cause a bugcheck. For example, you could overwrite another driver's memory and cause it to fail.

The top few lines of the bugcheck screen contain the most useful information. Down below might be a module list, a stack trace, and instructions. In NT, then it will say that is producing a physical dump of memory even if you have not enabled this option in the Control Panel System applet.

The most common bugcheck codes are listed in Table 6.2. The full list of stop codes is given in DDK bugcodes.h. The exception codes for "Unhandled Kernel exception" bugchecks are in the NTSTATUS.H header in the DDK.

For example, put this code in the Wdm1 driver.

char* NULLptr = NULL;

*NULLptr = 5;

This does not cause any errors in W98. However, in W2000, the following bugcheck occurs. (Interestingly, a read from address 0x0 does not seem to cause a bugcheck in W2000.)

*** STOP: 0x0000001E (0xC0000005,0xF2D7B875.0x00000001,0x00000000)

KMODE_EXCEPTION_NOT_HANDLED

*** Address 0xF2D7B875 base at 0xF2D7A000 Datestamp 362DF72F – Wdm1.sys

The bugcheck code is 0x0000001E, which translates as an "Unhandled Kernel exception". The four numbers in brackets are the four extra parameters that are passed to KeBugCheckEx. Table 6.2 shows the interpretations for the common bugcheck codes. For this bugcheck, the first parameter is the exception code. 0xC0000005 indicates an access exception. The fourth parameter indicates the memory address that you tried to access (0x0) and the second parameter gives the address of the instruction that caused the exception. The exception occurred at address 0xF2D7B875, a little way into the code of Wdm1, which is loaded at 0xF2D7A000. 

Table 6.2 Common bugchecks

Code 0x0000000A IRQL_NOT_LESS_OR_EQUAL 1 Address referenced 2 IRQL (Not the correct IRQL) 3 0=read, 1=write 4 Address that referenced memory A driver tried to do something at an inappropriate IRQL (e.g., accessing paged memory at DISPATCH_LEVEL IRQL or higher)

Code 0x0000001E KMODE_EXCEPTION_NOT_HANDLED 1 Exception code: 0xC00000005 2 Address where exception occurred 3 4 Address referenced Access violation

Code 0x0000001E KMODE_EXCEPTION_NOT_HANDLED 1 Exception code: 0x80000003 2 Address where exception occurred Hard-coded breakpoint or ASSERT hit.

Code 0x000000BE Driver attempted to write to read-only memory

Code 0x000000C4 Driver Verifier detected exception. See its documentation for details.

Where Did the Bugcheck Happen?

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

Conclusion

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.

Dispatch Routine IRPs

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

Win32 Function	IRP Major Code	Base Driver routine name
CreateFile	IRP_MJ_CREATE	Create
CloseHandle	IRP_MJ_CLOSE	Close
ReadFile	IRP_MJ_READ	Read
WriteFile	IRP_MJ_WRITE	Write
DeviceIoControl	IRP_MJ_DEVICE_CONTROL	DeviceControl

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;

I/O Request Packets

Dispatch Routine Handling

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).

NTSTATUS Wdm1Read( IN PDEVICE_OBJECT fdo. IN PIRP Irp)

A dispatch routine is usually called at PASSIVE_LEVEL IRQL. (This is a bit unexpected, as you might expect dispatch routines to run at DISPATCH_LEVEL IRQL.) Running at PASSIVE_ LEVEL means that a dispatch routine can very easily be interrupted by other parts of the kernel or even your own driver. However, a routine that runs at PASSIVE_LEVEL can issue most kernel calls, including writing to other files.

A dispatch routine can be called at DISPATCH_LEVEL if a higher level driver calls you at this IRQL level. This might happen if it calls you from a completion routine, as described in Chapter 9. If you think this might be happening, then assume that your driver dispatch routines are running at DISPATCH_LEVEL

Dispatch routines run in an arbitrary thread context. As well as standard user mode threads, the kernel has its own threads that run only in kernel mode. Although your IRP will have originated in one of these threads, you cannot guarantee that you arc running in its context. This means that a valid address in the originating thread may not be valid when your driver sees it. A later section in this chapter shows how to access user buffers correctly.

Reentrancy

A dispatch routine must be reentrant. This means that it may be called "simultaneously" to process two separate IRPs. In a multiprocessor Windows 2000 system, one processor could call Wdm1Read with one IRP, and a second process on another CPU could also call Wdm1Read simultaneously with another IRP. However, do not dismiss reentrancy as some arcane requirement that your driver will never encounter. In Windows 98, the single processor could start running Wdm1Read to handle a first IRP. Wdm1Read could issue a kernel request that blocks its operation^[14]. Windows 98 might then schedule a different user application that issues another read resulting in another call to Wdm1Read.

The first technique to make your routine reentrant is to use local variables. Each separate call to Wdm1Read definitely has its own separate set of variables on the kernel stack.

Do not use global variables or variables in the device extension unless you protect access to them. However, when these variables are first set up (DriverEntry or AddDevice), you do not need to take special precautions.

The Wdm1 driver uses a spin lock to protect access to the shared memory buffer variables, as described later.

There are two other main techniques to achieve reentrancy in dispatch routines. The first is to use the services of the I/O Manager to create a device queue of IRPs. The IRPs in the device queue are passed one at a time to a StartIo routine in your driver.

The second technique is to use Critical section routines if your device interrupts the computer, as explained in full in Chapter 16. Calling KeSynchronizeExecution runs your Critical section routine safely. KeSynchronizeExecution raises the IRQL to the interrupt IRQL and acquires the interrupt spin lock. This technique ensures that your routine is run to completion without being interrupted by another part of the driver.

IRP Handling

There are three main techniques for handling IRPs.

• Handle immediately

• Put in a queue and process one by one

• Pass down to a lower-level driver

Only the simplest drivers, like Wdm1, can handle IRPs straightaway. Even so, you must still take precautions to ensure that your driver dispatch routines are reentrant.

Drivers that access real pieces of hardware usually want to serialize access to the hardware. As mentioned previously, the I/O Manager in the kernel provides a device queue that you can use. Dispatch routines call the kernel to put an IRP into the device queue. The I/O Manager calls your StartIo routine to process one IRP at a time. When your StartIo routine has completed an IRP, it should call the kernel to ensure that it is called again with the next available IRP.

Drivers might want to use more than one device queue. For example, a serial port driver will usually want to have two device queues; one for incoming read data and one for outgoing write data.

A driver can use a different queuing strategy. For example, the DebugPrint driver described in Chapter 14 lets only one read IRP be queued. Any further read IRPs are rejected while the first read IRP is outstanding.

The final main technique for handling IRPs is to pass them down for handling in a lower-level driver. This approach is common in WDM device drivers. Some drivers simply pass the handling of some IRPs to the next lower driver and forget about them. If you take a more active interest, you can inspect the results after all the lower-level drivers have handled the IRP. These techniques are covered later.

A variant on this theme is for a driver to build a new IRP (or IRPs), send it down to lower drivers, and process the results afterwards.

IRP Completion

When a driver has finished working on an IRP, it must tell the I/O Manager. This is called IRP completion. As this code snippet shows, you must set a couple of fields in the IRP IoStatus field structure. IoStatus.Status is set to an NTSTATUS status code. The number of bytes transferred is usually stored in IoStatus.Information.

Irp->IoStatus.Status = STATUS_SUCCESS;

Irp->IoStatus.Information = BytesTxd;

IoCompleteRequest(Irp,IO_NO_INCREMENT);

Finally, IoCompleteRequest is called (at or below DISPATCH_LEVEL IRQL). As well as the IRP pointer, you must supply a PriorityBoost parameter to give a boost to the scheduling priority of the thread that originated the IRP. For example, keyboard drivers use the constant IO_KEYBOARD_INCREMENT. This is a high value of 6 because foreground threads should respond quickly to user input.

If a dispatch routine does not process an IRP immediately, it must mark the IRP as pending using IoMarkIrpPending and return STATUS_PENDING. When you eventually get round to completing the IRP, do it as described above.

If an IRP is queued and its associated process dies unexpectedly (or calls CancelIo to cancel overlapped IRPs), these pending IRPs must be cancelled. You must set an IRP's cancel routine to handle this circumstance, and to handle the Cleanup IRP. Chapter 16 describes these options in full. Wdm1 does not queue IRPs, so handling these options is not necessary.

IRP Structure

Figure 7.1 shows that an I/O Request Packet consists of a header IRP structure followed by a series of stack locations, each an IO_STACK_LOCATION structure. The information in the header and the current IRP stack location tell a driver what to do.

Figure 7.1 IRP overview

Table 7.2 lists some of the fields in the IRP header structure that a driver can access, while Table 7.3 gives the general layout of the IO_STACK_LOCATION structure.

Table 7.2 Some IRP structure fields

Field	Description
IO_STATUS_BLOCK IoStatus	Completion status of IRP
PVOID AssociatedIrp.SystemBuffer	System space buffer (for Buffered I/O)
PMDL MdlAddress	Memory Description List (for Direct I/O)
BOOLEAN Cancel	Set if IRP has been cancelled
ULONG Flags	IRP Flags

Table 7.3 Some IO_STACK_LOCATION structure fields

typedef struct _IO_STACK_LOCATION {

 UCHAR MajorFunction;

 UCHAR MinorFunction;

 // …

 union {

  struct { … } Create;

  struct { … } Read;

  struct { … } Write;

  struct { … } DeviceIoControl;

 } Parameters;

 // …

} IO_STACK_LOCATION, *PIO_STACK_LOCATION;

The fact that there is an IRP header and several associated I/O stack locations can be a source of confusion. However, the stack locations are a powerful tool for processing IRPs when several layered drivers have to access an IRP in turn.

The I/O stack location contains most of the important information about the IRP. The MajorFunction is the IRP code (e.g., IRP_MJ_READ for a Read IRP). Some IRPs, such as IRP_ MJ_PNP, use the MinorFunction field to specify which particular Plug and Play function is being requested.

Each common IRP type has a struct within the Parameters union in the IO_STACK_LOCATION structure. For example, for Read IRPs, the Parameters.Read.Length field is the number of bytes to transfer. The parameters that are valid for each common IRP are described in the following text.

The key to understanding I/O stack locations is to realize that each driver needs to look at only one, the "current stack location". The information in the IRP header structure and the information in the current stack location are the parameters that a driver uses to process an IRP.

I/O Stack Locations

Let's go off track slightly to ask why Microsoft provides a set of I/O stack locations. If you have a stack of drivers that process an IRP, the highest might be a network protocol driver that can accept read requests of any length. This driver might know that the underlying transport driver can only cope with read transfers of up to 1024 bytes. Its job is to break up long transfers into a series of blocks, each with a maximum size of 1024 bytes. When the protocol driver calls the transport driver it, sets up the next I/O stack location with the transfer size set to 1024. When the transport driver processes the IRP, its current I/O stack location has this value, and it should proceed happily to process the IRP. When it has finished, the IRP is passed back to the protocol driver. This checks that the transfer worked and — assuming it did — sets up the next transfer and calls the transport driver again.

In this approach, the protocol driver sends the transport driver IRPs one by one. However, a more sophisticated protocol driver could allocate new IRPs, enough to move all the data. It could then issue them all to the transport driver. The protocol driver would have to check carefully that all the IRPs finished correctly. When all the data has been moved, one way or another, the protocol driver can finally complete its own original IRP.

This example reveals a problem. The field that contains the pointer to the data to be transferred is not in the I/O stack location, but in the IRP header. The transfer length is in the stack. Surely the data pointer ought to be in there as well. The fact that the original stack location is not changed by the call to the lower driver is good, as it makes it easier for a driver to remember how many bytes to transfer.

However, this reveals another common difficulty with IRPs — determining where to store a driver's own information about an IRP. Suppose the protocol driver wanted to remember something simple (e.g., how many bytes it had sent so far)^[15].

The ideal place for some storage for drivers would be the I/O stack location. However, there is no space specifically reserved for drivers. Nonetheless, Read IRPs have a ULONG at Parameters.Read.Key in the current I/O stack location that can be used safely, although the DDK does not specifically say so. Write IRPs have a similar ULONG at Parameters.Write.Key.

There is some room in the IRP header that can be used by drivers — a PVOID DriverContext[4] in Tail.Overlay. Use the following code to access the first of these locations.

PVOID p = Irp->Tail.Overlay.DriverContext[0];

However, it is not safe to use these locations for storing context while an IRP is processed by lower drivers, for the simple reason that these other drivers may use this memory too.

The final point to note about I/O stack locations is that you can use different major function code when you call a lower driver. For example, you might implement a read request by sending the lower driver an IOCTL.

Common IRP Parameters

This section lists the parameters that are set for the common IRPs. In the following discussion, "the stack" means the current I/O stack location.

Create IRP, IRP_MJ_CREATE

The main parameter of interest to the Create IRP handler is the FileObject field in the stack. This is a pointer to a _FILE_OBJECT structure. The FileName field in here is a UNICODE_STRING with any characters after the basic device name. If you appended \file to the symbolic link name found in the GetDeviceViaInterface routine in Wdm1Test, \file would appear in FileName. If no characters are appended, FileName has a length of zero.

Other parameters to the Create IRP are given in the Parameters.Create structure in the stack, such as the FileAttributes and ShareAccess.

Close IRP, IRP_MJ_CLOSE

If need be, you can double-check that the FileObject in the IRP header matches the one you were sent in the create request.

If you have queued up Read or Write IRPs for this file, the I/O Manager will have cancelled them before the close request is received. It does this by calling an IRP's Cancel routine and issuing a Cleanup IRP, as described in Chapter 16.

Read IRP, IRP_MJ_READ

The Parameters.Read structure in the IRP stack has Length and ByteOffset fields that say how many bytes are requested and the file pointer. ByteOffset is a 64-bit integer stored in a LARGE_INTEGER structure. The Microsoft compiler can handle this type directly (i.e., Parameters.Read.ByteOffset.Quad Part is an __int64). If you need to specify 64-bit constant values in your code, append i64 to the constant (e.g., 100i64).

The user buffer can be specified in one of two ways, depending on whether your driver uses Buffered I/O or Direct I/O. See the following text for details of these terms. If using Buffered I/O, a pointer to the user buffer is in the IRP header at AssociatedIrp.SystemBuffer. For Direct I/O, a Memory Descriptor List (MDL) is in the IRP header in the MdlAd-dress field.

The Key field in the IRP stack Parameters.Read structure does not seem to be used for anything, and so could be used by a driver for any purpose.

Write IRP, IRP_MJ_WRITE

The parameters for Write IRPs are identical to Read IRPs, except that the relevant parameters are in the stack Parameters.Write structure.

IOCTL IRP, IRP_MJ_DEVICE_CONTROL

The Parameters.DeviceIoControl structure in the IRP stack has IoControlCode, InputBufferLength, and OutputBufferLength parameters.

The user buffer is specified using one or more of the AssociatedIrp.SystemBuffer, MdlAddress, or stack Parameters.DeviceIoControl.Type3InputBuffer fields. See the next section for details.

User Buffers

As a driver can run in the context of any thread, a plain pointer into the user's address space is not guaranteed to access the correct memory.

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.

Buffered I/O

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.

Direct I/O

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.

Neither

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 Buffers

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

Create and 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));

Write

Things start to get interesting in the write dispatch routine, Wdm1Write, shown in Listing 7.2. It starts by getting the current stack location pointer and retrieving the current file pointer and the number of bytes to transfer. If the file pointer is less than zero (the kernel should ensure that it never is), it returns STATUS_INVALID_PARAMETER. It is possible to receive a transfer length of zero.

Listing 7.2 Wdm1 write dispatch routine

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

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 NTSTATUS status = STATUS_SUCCESS;

 ULONG BytesTxd = 0;

 // Get call parameters

 LONGLONG FilePointer = IrpStack->Parameters.Write.ByteOffset.QuadPart;

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

 DebugPrint("Write %d bytes from file pointer %d", (int)WriteLen,(int)FilePointer);

 if (FilePointer<0) status = STATUS_INVALID_PARAMETER;

 else {

  // Get access to the shared buffer

  KIRGL irql ;

  KeAcquireSpinLock(&BufferLock,&irql);

  BytesTxd = WriteLen;

  // (Re)allocate buffer if necessary

  if ( ((ULONG)FilePointer)+WriteLen>BufferSize) {

   ULONG NewBufferSize = ((ULONG)FilePointer)+WriteLen;

   PVOID NewBuffer = ExAllocatePool(NonPagedPool.NewBufferSize);

   if (NewBuffer==NULL) {

    BytesTxd = BufferSize – (ULONG)FilePointer;

    if (BytesTxd<0) BytesTxd = 0;

   } else {

    RtlZeroMemory(NewBuffer,NewBufferSize);

    if (Buffer!=NULL) {

     RtlCopyMemory(NewBuffer,Buffer,BufferSize);

     ExFreePool(Buffer);

    }

    Buffer = (PUCHAR)NewBuffer;

    BufferSize = NewBufferSize;

   }

  }

  // Write to shared memory

  if (BytesTxd>0 && Buffer!=NULL) RtlCopyMemory(Buffer+FilePointer, Irp->AssociatedIrp.SystemBuffer, BytesTxd);

  // Release shared buffer

  KeReleaseSpinLock(&BufferLock,irql);

 }

 DebugPrint("Write: %d bytes written", (int)BytesTxd);

 // Complete IRP

 return Completelrp(Irp,status,BytesTxd);

}

The shared memory buffer is implemented using these three global variables.

KSPIN_LOCK BufferLock;

PUCHAR Buffer = NULL;

ULONG BufferSize = 0;

If the buffer size is greater than zero, Buffer points to some nonpaged memory of this size. As mentioned earlier in this chapter, there must be some mechanism to protect access to such global variables in a multiprocessor environment (e.g., to prevent one dispatch routine from changing BufferSize while another, or even the same, routine tries to access or change it simultaneously).

Spin Locks

A kernel spin lock called BufferLock provides this protection. A spin lock can be used where code needs access to a resource of some sort for a short time.

The spin lock is initialized in the Wdm1 DriverEntry routine as follows.

KeInitializeSpinLock(&BufferLock);

Use the KeAcquireSpinLock function to acquire a spin lock and KeReleaseSpinLock to release it. Only one instance of a piece of code can acquire a spin lock at the same time. Other attempts to acquire the spin lock will "spin" until the resource becomes available. "Spinning" means that KeAcquireSpinLock keeps looking continuously. For this reason, make sure that you only hold a spin lock for a short time. The DDK recommends that you never hold a spin lock for more than 25 microseconds.

As shown in the code example, you must provide a pointer to a KIRQL variable in the call to KeAcquireSpinLock. This stores the original IRQL level before it is raised (if necessary) to DISPATCH_LEVEL The call to KeReleaseSpinLock lowers the IRQL if necessary. If you are certain that your code is working at DISPATCH_LEVEL, you can use the KeAcquireSpinLockAtDpcLevel and KeReleaseSpinLockFromDpcLevel routines for better performance.

The Wdm1 driver acquires the BufferLock spin lock for the duration of any accesses to the Buffer and BufferSize variables. Do not access paged code or data while holding a spin lock, as the system will almost certainly crash. Definitely do not exit a main dispatch routine while holding a spin lock.

Write Algorithm

The write dispatch stores the write data in the shared memory buffer, starting from the given file pointer. It extends the buffer, if necessary.

If there is no buffer at all, or the buffer needs to be extended, ExAllocatePool is called to allocate some nonpaged memory. Notice that the algorithm checks for a NULL return value and copes as best as it can.

A new memory buffer is zeroed using RtlZeroMemory. If an old shorter buffer exists, it is copied to the start of the new buffer using RtlCopyMemory. RtlMoveMemory can be used if the source and destination pointers overlap. The old buffer is removed with ExFreePool.

Finally, Wdm1Write copies the data from the user buffer using RtlCopyMemory. As Wdm1 uses Buffered I/O, it can simply copy the data from Irp->AssociatedIrp.SystemBuffer.

This algorithm is fairly crude, because the buffer may have to be reallocated often. A much-enhanced version of Wdm1 could implement a RAM disk.

The driver unload routine frees any shared memory buffer.

if (Buffer!=NULL) ExFreePool(Buffer);

Read

The read dispatch routine for Wdm1, Wdm1Read, is simpler than the write handler. It acquires the spin lock while it accesses the global variables. The required number of bytes are copied to the user's buffer at Irp->AssociatedIrp.SystemBuffer. If the user requests more data than is in the buffer, the request is truncated.

IOCTL

The Wdm1DeviceControl dispatch routine handles the four IOCTLs defined for Wdm1 devices: Zero the buffer, Remove the Buffer, Get the buffer size, and Get the buffer.

All these IOCTLs use Buffered I/O, so any input and output data is found at Irp->Associ-atedIrp.SystemBuffer. As usual, the routine acquires the shared buffer spin lock for the duration of the call. The actual implementation of each IOCTL is straightforward. The Get buffer size and Get buffer handlers check that the output buffer is large enough; if not, they return STATUS INVALID_PARAMETER.

Defining IOCTLs

An IOCTL code is a 32-bit value formed using the CTL_CODE macro shown in Table 7.4. The Wdm1 example defines its IOCTL codes in Ioctl.h, as shown in this example.

//define IOCTL_WDM1_ZERO_BUFFER CTL_CODE( \

 FILE_DEVICE_UNKNOWN, \

 0x801, \

 METHOD_BUFFERED, \

 FILE_ANY_ACCESS)

Table 7.4 CTL_CODE macro parameters

Parameter	Description
DeviceType	FILE_DEVICE_XXX value given to IoCreateDevice.
Control Code	IOCTL Function Code 0x000–0x7FF Reserved for Microsoft 0x800-0xFFF Private codes
TransferType	METHOD_BUFFERED METHOD_IN_DIRECT METHOD_OUT_DIRECT METHOD_NEITHER
RequiredAccess	FILE_ANY_ACCESS FILE READ_DATA FILE_WRITE_DATA FILE READ_DATA|FILE_WRITE_DATA

Ioctl.h is also included in the Wdm1Test project. It includes the standard winioctl.h header file first to get the definition of CTL_CODE.

System Control

Dispatch.cpp also contains a handler for the Windows Management Instrumentation IRP, IRP_MJ_SYSTEM_CONTROL. Wdm1SystemControl simply passes the IRP down to the next driver in the stack. A full explanation of this process is given later.

IoSkipCurrentIrpStackLocation(Irp);

PWDM1_DEVICE_EXTENSION dx = (PWDMl_DEVICE_EXTENSION)fdo->DeviceExtension;

return IoCallDriver(dx->NextStackDevice, Irp);

Conclusion

This chapter has looked in detail at I/O Request Packets (IRPs) and how to write dispatch routines to handle common IRPs. In addition, it has covered how to define IOCTL codes, and how to use spin locks. The Wdm1 dispatch routines implement a shared memory buffer, protected by a spin lock.

The next chapter looks at Plug and Play in detail, enhancing Wdm1 to support PnP correctly.

This chapter looks at the design of the Plug and Play (PnP) system and how PnP drivers fit into a device stack. A device stack is the means by which several layers of drivers can work together to process user requests. The next chapter looks at how to implement Plug and Play in detail, and describes the Wdm2 example. As well as PnP, Wdm2 supports Power Management, as described in Chapter 10.

Plug and Play — in a different form — is available in Windows 95 for virtual device drivers (VxDs). NT 4 does not support Plug and Play. Therefore, the Windows 98 and Windows 2000 support for Plug and Play in the Windows Driver Model is new for both environments. If you have any old NT 4 kernel mode device drivers, Microsoft recommends that you update them to support Plug and Play and Power Management. However, supporting Plug and Play requires a major change to driver code, so you will have to judge whether it is worthwhile.

Although Plug and Play initially looks complicated, it is possible to use the code the Pnp.cpp module described in the next chapter for most drivers. Careful use of the LockDevice and UnlockDevice routines is all that is needed elsewhere.

Design Overview

From a user's point of view, Plug and Play is straightforward. You just plug in some new equipment and Windows finds the device and prompts you for the correct drivers. Then you play with your new device.

The main benefit for users is that there should be no fiddling with DIP switches or jumpers to configure the device. Instead, Windows does all the necessary setting up. This is where your device driver comes in.

1. A standard bus driver detects when a device is added.

2. The device identifiers are used to find your driver.

3. Your driver is loaded and told that a device has been added.

4. A further message tells you what hardware resources to use.

5. Your driver then talks to your device, possibly using the services of a standard driver.

When a piece of equipment is unplugged, Windows detects this and tells your driver that the device has gone.

This chapter first looks at the overall Plug and Play design. It then covers the PnP messages that a driver receives. The bulk of the chapter is spent looking at how drivers work together in device stacks to find devices and process user requests.

Design Goals

The Plug and Play system is designed to satisfy these two goals.

• Cope with new devices when they are added to the system. Devices that are configurable in software must be told what resources or addresses to use.

• Make it easier for drivers to access complicated devices by providing standard drivers. For a relatively complicated bus like the Universal Serial Bus, it makes sense to provide a standard driver that other drivers must use if they want to access the bus.

The Plug and Play system brings both these design problems together. The standard drivers detect when a device is added or removed from the system.

Although Microsoft's solution satisfies both the original design goals, it still has some drawbacks. First, it makes a typical driver more complicated. Second, the device stack structure is complicated to understand, although it is not too difficult to use.

Plug and Play System

The PnP Manager controls these four main elements of the design.

• Standard bus drivers detect when devices are added or removed.

• Device identifiers are used to determine which driver or drivers to load.

• The following messages are sent to drivers when device related events occur:

  "A device has been added"

  "Your device has been removed"

  "Here are your device's resource assignments"

  "Please stop your device while its resources are reassigned"

• Device stacks are constructed so user requests can be processed in stages.

The rest of this chapter discusses this design in detail. The following chapter shows how to put this design into practice. Chapter 11 describes the installation process: how drivers are located and the format of installation INF files.

Detecting Devices

The first aim of the PnP system is to cope with new devices as they added to the system. Table 8.1 summarizes the requirements and the Microsoft solution, together with its one main drawback.

Standard bus drivers detect devices, both at power up and afterwards when devices are added or removed. Each bus driver retrieves one or more identifiers from its devices. These identifiers are used to find an appropriate device driver by looking through all the available installation files. If a suitable driver cannot be found, the user is prompted for a driver disk.

The driver is loaded and its AddDevice entry point is called to tell it that a new device has been found.

The bus driver or the installation file details the hardware resources that a device needs. Arbiters are used to decide what resources to give to each device. A Start Device PnP message tells the driver its device's resource assignments. It can then start to talk to its device properly.

In some cases, the bus driver must perform additional arbitration steps. For example, in the Universal Serial Bus, a device initially responds at a default address. The USB bus driver must assign the device a free USB address before it can use the full bus protocol. In addition, the USB bus driver must reserve some of the bus bandwidth for some types of device. If there is not enough bandwidth available then the device cannot be used.

The main drawback of this design is that resource assignments can be taken away from a device temporarily when it is up and running. Ideally, any I/O operations that are in progress should only pause briefly during this process. This is a complete pain because any I/O operations in progress at the time have to be halted, and any new I/O requests should be held in a queue until the device is restarted. Halting and queuing requests is not a trivial task for device drivers.

Suppose an existing PnP device currently uses IRQ7 and I/O ports 0x378 to 0x37A. The device can also be configured in software to use IRQ5 and ports 0x278 to 0x27A. Suppose a new device is now added that can only use IRQ7 and I/O ports 0x300 to 0x30F. It is possible to accommodate both these devices if the first one has its interrupt line changed from IRQ7 to IRQ5. To make this happen, the first driver must be halted and restarted straightaway with the new resource assignments^[16]. If this works, the second device can then be given its resource assignments.

Table 8.1 Plug and Play device detection

Aim	Detect all devices at power up. Load the most appropriate driver. Give each driver their resource assignments. For hot pluggable devices, cope as devices are added and removed
Solution	Provide enumerator bus drivers to find new devices and detect when devices are added or removed. Each device provides identifiers which arc used to find the most appropriate driver. The bus driver or INF file provides the device's resource requirements. Provide arbiters to decide which resources to allocate to which device. Send messages to indicate device events.
Drawback	Devices which are running may have to stopped so that their resources can be reassigned.

Driver Layers

The second aim of the Plug and Play system is to make standard drivers available for other drivers to use.

At the lowest level, a bus or class driver talks directly to the hardware. One or more client drivers are layered on top of such system drivers. These client drivers work at the functional level. For example, a USB printer client driver uses the USB bus driver to send its messages. However, the messages are only understood by the printer firmware. The client driver therefore controls the printer functions, letting the USB system driver handle all the messy low-level communications details.

Each bus driver has one device object that represents the whole bus. The bus driver creates a new device object, called the Physical Device Object (PDO), for each device that it finds on its bus. It provides various device identifiers to the PnP Manager. The PnP Manager finds and loads the most appropriate driver, and calls its AddDevice routine.

The newly loaded driver is called a function driver, as it should know how to control its device's function. The function driver must create its own new device object, called a Functional Device Object (FDO) which stores its information about the device^[17]. The FDO is created in a function driver's AddDevice routine. The AddDevice routine then goes on to layer itself above the bus driver PDO.

In this simple case, two device objects refer to the same physical device. The PDO is the bus driver's representation of the device, while the FDO stores the function driver information about the device.

Figure 8.1 shows the situation when two devices are attached to a single bus. The bus driver has two 'child' PDOs, one for each device. A suitable function driver has been found for each device. Each function driver has created an FDO to store information about its device.

The bus driver controls three different device objects. Each child PDO receives requests from the function driver layered about it. In addition, the bus driver has an FDO of its own which it uses to store information about the whole bus. A bus driver might handle child PDO requests by sending them to its FDO for processing.

Just to reiterate, each function driver knows how to control the functions in a device. However, a function driver usually uses the facilities of its underlying bus driver to talk to its device.

Even a virtual device driver like Wdm1 has a device stack. Wdm1 is a function driver and so its device object is an FDO. There is a bus driver underneath Wdm1, the system unknown driver. the unknown bus driver makes a PDO to represent each Wdm1 device. The Unknown driver does some important jobs, even though it does not correspond to a hardware bus. The following chapter describes the jobs that even a minimal bus driver like Unknown must do.

Figure 8.1 A bus driver, two devices, and their function drivers

Device Stacks

When one driver layers its device over another, it forms a device stack. Each device in the stack usually plays some part in processing user requests.

Figure 8.2 shows a generic device stack. A bus driver is always at the bottom of the stack. One or more function drivers do the main device control functions.

Filter drivers are used to modify the behavior of standard device drivers. Rather than rewrite a whole bus or class driver, a filter driver modifies its actions in the area of interest. As the figure shows, there are various types of filter driver. A bus filter driver acts on all devices that attach to a particular bus driver. Class filter drivers are installed in the stack for each device of the specified class. Finally, a device filter driver is installed for one particular device. Lower-level filter drivers are below the function driver, while upper-level drivers are above the function driver in the stack.

Filter drivers are only installed when a device is first installed, so they cannot be inserted once a device stack has been built.

Figure 8.2 Bus, function, and filter drivers

Monolithic and Layered Drivers

When a standard keyboard is found, Windows loads the appropriate driver. This talks directly to the keyboard through its controller electronics. The keyboard driver is described as monolithic because it takes over all the processing required to handle the keyboard (i.e., it does not use other drivers to do its job).

In contrast, USB drivers use a layered approach. To use a USB keyboard, the keyboard driver uses the services of the USB class drivers.

As shown in Chapter 21, the USB class drivers expose an upper edge that drivers higher than it must use. Such drivers can issue USB Request Blocks (URBs), which transmit or receive information from a USB device. The keyboard driver does not care how the USB class drivers do their job.

The situation for the USB class drivers themselves is probably slightly different^[18]. They are told where the USB bus controller electronics live, and they make use of the services of the PCI bus driver. However, I suspect that the USB class drivers talk directly to their own hardware. Asking the PCI bus driver to write or read memory would be too slow.

A different approach would have been to let each USB driver talk directly to the USB hardware in a monolithic driver. This would lead to two problems. The first is that each USB driver would need a large amount of code. Duplicating this code would waste memory and writing large drivers is decidedly error prone. The second problem is almost of more significance: how would all these different drivers coordinate their activities? The answer is, of course, with difficulty. Using different layers of drivers solves both these problems.

Plug and Play Messages

This section looks at the messages that a PnP driver receives. Its AddDevice routine is called when a device is added. After that, messages are sent using the PnP IRP. The PnP messages have the same major function code IRP_MJ_PNP, but each message uses a different minor function code. Each message has different parameters in the IRP.

A PnP driver must implement an AddDevice routine and handle various PnP IRPs. Table 8.2 is a list of all the minor function codes. The first eight of these minor codes are the most important. The other minor function codes are usually just handled by bus drivers.

Table 8.2 Plug and Play minor function codes

Common PnP IRPs
IRP_MN_START_DEVICE	Assign resources and start a device
IRP_MN_QUERY_REMOVE_DEVICE	Ask if a device can be removed
IRP_MN_CANCEL_REMOVE_DEVICE	Cancel a query remove request
IRP_MN_REMOVE_DEVICE	Device has been unplugged or uninstalled Deallocate resources and remove a device
IRP_MN_SURPRISE_REMOVAL (W2000 only)	A user has unexpectedly unplugged a device
IRP_MN_QUERY_STOP_DEVICE	Ask if a device can be stopped
IRP_MN_CANCEL_STOP_DEVICE	Cancel a query stop request
IRP_MN_STOP_DEVICE	Stop a device for resource reallocation
Unusual PnP IRPs
IRP_MN_QUERY_DEVICE_RELATIONS	Ask for PDOs that have certain characteristics
IRP_MN_QUERY_INTERFACE	Let a driver export a direct-call interface
IRP_MN_QUERY_CAPABILITIES	Ask about device capabilities (e.g., whether it can be locked or ejected)
IRP_MN_QUERY_RESOURCES	Get a device's boot configuration resources
IRP_MN_QUERY_RESOURCE_REQUIREMENTS	Ask what resources a device requires
IRP_MN_QUERY_DEVICE_TEXT	Get a device's description or location string
IRP_MN_FILTER_RESOURCE_REQUIREMENTS	Let filter and function drivers filter a device's resource requirements
IRP_MN_READ_CONFIG	Read configuration space information
IRP_MN_WRITE_CONFIG	Set configuration space information
IRP_MN_EJECT	Eject the device from its slot
IRP_MN_SET_LOCK	Set device locking state
IRP_MN_QUERY_ID	Get hardware, compatible, and instance IDs for a device
IRP_MN_QUERY_PNP_DEVICE_STATE	Set bits in a device state bitmap
IRP_MN_QUERY_BUS_INFORMATION	Get type and instance number of parent bus
IRP_MN_DEVICE_USAGE_NOTIFICATION	Notify whether a device is in the path of a paging, hibernation, or crash dump file.
IRP_MN_QUERY_LEGACY_BUS_INFORMATION	Returns legacy bus information (W2000 only)

Figure 8.3 shows the PnP states for a device and the messages that are sent to change state. The minor function code names are shortened in the figure (e.g., IRP_MN_START_DEVICE is shown as START_DEVICE). In this book, a PnP IRP with an IRP_MN_START_DEVICE minor function code is called a Start Device message. The other PnP function codes are given similar names.

When a device is added to the system, Windows finds the correct driver and calls its DriverEntry routine. Chapter 11 explains how Windows finds the correct drivers.

The PnP Manager then calls the driver's AddDevice routine to tell it that a device has been added. It is at this point that the driver makes its own device object, the Functional Device Object (FDO). However, the driver should not try to access its device hardware yet.

In due course, the driver receives an IRP_MN_START_DEVICE IRP that includes information about the resources the device has been assigned. It can then start talking properly to the device hardware.

If a device is about to be unplugged, Windows asks the driver if it is all right for the device to be removed using an IRP_MN_QUERY_REMOVE_DEVICE IRP. If the driver agrees, an IRP_MN_ REMOVE_DEVICE IRP is sent to remove the device. If the driver does not want its device removed (e.g., if it is in the middle of a long transfer) it fails the remove request. It is then sent an IRP_MN_CANCEL_REMOVE_DEVICE IRP to put it back in the started state.

If a user unexpectedly pulls out a device, the driver is sent an IRP_MN_REMOVE_DEVICE IRP in Windows 98 or an IRP_MN_SURPRISE_REMOVAL IRP in Windows 2000. You have to cope with interrupted transfers as well as you can.

The other main state change occurs when the PnP Manager wishes to reallocate some of the driver's resources. This might happen if a new device of some sort is plugged in, meaning that the resource assignments need to be juggled about. The PnP Manager asks to stop the driver temporarily while its resources are reassigned. Similarly, in response to remove requests, an IRP_MN_QUERY_STOP_DEVICE IRP asks if it is OK to stop your device. If it is, an IRP_MN_STOP_DEVICE IRP is issued to take the device into the stopped state. If not, an IRP_MN_ CANCEL_STOP_DEVICE IRP moves the device back into the started state. While stopped, the driver should not access its device. An IRP_MN_START_DEVICE IRP informs the driver of its new resources and starts the device again.

Figure 8.3 Plug and Play device states and messages

Note that a driver might receive a remove device message while in the stopped or awaiting resources states. These state changes are not shown in the diagram for the sake of clarity.

The next chapter looks in detail at how to handle these state changes. For the moment, I will look at device enumeration and then how layers of PnP drivers work together to form a device stack.

Device Enumeration

The enumeration process finds all the devices on a user's PC.

Fixed and Configurable Devices

As you probably know, most of the hardware devices on a PC motherboard are found at fixed locations. For example, on most PCs, the keyboard controller is something that looks like an 8042 processor that can be accessed at I/O ports 0x60 and 0x64. The keyboard controller interrupts on line IRQ1.

This approach works satisfactorily for the one keyboard controller that every mother-board has. However, with serial ports and the old ISA bus, things soon started to get too complicated for most users. If an old ISA bus card just uses fixed addresses and interrupts, it could easily conflict with another card. An interim solution was to provide jumpers and switches on each card to make it configurable. However, configuring this hardware was too much for most mortals to cope with.

The solution to this problem is to have devices that are configurable by software. This means that a bus driver tells each card or device where it should be located, possibly according to assignments given by the PnP Manager. All the newer buses, such as PCI, USB, and IEEE 1394 are software-configurable. Some PnP ISA devices are configurable in software, as well.

Usually, this works as follows. When a card or device powers up, it is detected by its bus driver. The bus driver uses the slot or port number to interrogate the device. Some configuration information or a device descriptor tells the bus driver what sort of resources the card needs. The bus driver or the PnP Manager then allocates the resources appropriately and tells the card this information, either by sending it a command or by writing to its registers. The card then configures itself to respond at the addresses it has been given. The card or device can then start operating normally.

The PnP Configuration Manager sorts out the basic system resources for drivers: I/O ports, Memory addresses, DMA channels, and Interrupts. However, the bus resources required in a particular bus environment are usually controlled by the bus driver. For example, only the USB drivers know about bandwidth allocation on the USB bus. When a USB client driver tries to configure its device, the USB bus driver decides if its bandwidth requirements can be satisfied.

Some types of device can be reconfigured after they have powered up. Configurable hot-pluggable devices can be plugged in or unplugged while the computer is switched on. The appropriate bus driver detects these changes and allocates or deallocates the card or device's resources. However, subsidiary buses are usually designed so that resources do not need to be reassigned in mid-flow.

Enumeration

When Windows is started, it does not know which devices are attached to the computer. It can work out some basic information for itself, such as how much memory it has, but how does it find out about the rest?

Windows uses drivers to enumerate the available hardware. Enumeration means finding and listing any available devices. Arbitrators are then used to juggle all their resource requirements. An appropriate driver (or drivers) is found for each device. The drivers are then told which resources to use, and off they go.

Figure 8.4 shows how enumeration works. Enumeration starts at the lowest level. The root device in the PC finds the basic chips that are on the motherboard^[19]. It finds any simple devices, such as built-in serial ports and the keyboard. It also finds the PCI adapter, the electronics that control the PCI bus.

The PCI bus driver then enumerates and configures any hardware it finds. First, it finds a bridge to the ISA bus. The driver for this then finds a PnP ISA sound card, and the sound card drivers are loaded.

The PCI bus driver also finds a USB bus controller. The USB drivers enumerate the USB bus and find a keyboard and printer attached. These are configured and the appropriate drivers are loaded.

Figure 8.4 Hardware enumeration

Device Tree

Figure 8.5 shows a device tree for part of my PC. A device tree is usually shown growing upwards from a root device at the bottom. The lower-level drivers are the ones that interact with the hardware.

As can be seen, the main keyboard driver can get information from two sources, either the legacy keyboard or a USB keyboard. The USB keyboard driver is layered above the HID and USB class drivers and the PCI bus driver. Whether the keyboard is legacy or USB, Win32 gets the same response: the drivers hide the hardware.

Figure 8.5 Device tree

The advantage of this approach is that each driver builds upon the work undertaken in lower layers, making it much easier to write most drivers. Indeed, it is the only way to write some types of drivers. If you are writing a USB driver, you must access your device through the USB class drivers. This means that you have to learn the specification of the relevant class driver. However, this is a far easier task than writing a huge monolithic driver that works with other similar drivers.

One possible drawback is that all this layering of drivers will take more processing time. While this is certainly a valid criticism, it is likely that a monolithic driver would use similar layering internally, so I/O should not take too much longer. More importantly, drivers that are easier to write are more likely to be stable.

Device Stacks

It does not make sense to have huge monolithic drivers. Wherever possible, a series of driver layers are built up, each performing an appropriate task. The advantage of this layering is that it breaks up I/O into a series of manageable tasks. If each layer has a standard specification, it means that a whole layer can be replaced and the higher layers will not know the difference. The lower layers hide the implementation details.

Microsoft has helped this layering process by providing standard bus and class drivers that implement one driver layer for a whole class of devices. For example, the Human Input Device (HID) class driver provides all the common functionality that these devices must implement. A driver that wants to talk to a specific type of HID device will layer itself above the Windows HID class driver. It will make I/O requests to this HID class driver. The HID driver layers itself above other drivers that let it talk to the real world.

As an another example, the USB class drivers are layered internally. Two types of electronics can be used to interface a PC to a physical USB bus: the Open Host Controller Interface (OpenHCI) and the Universal Host Controller Interface (UHCI). Windows chooses either the OpenHCI.sys driver or the UHCD.sys driver as the layer to interface to the electronics. Each driver implements the same upper-edge functionality. Other internal layers of the USB class drivers are built upon this common base.

PnP Support and the Device Stack

The PnP system has been designed to work with configurable devices and layers of drivers. A device stack represents the layers of drivers that process requests.

When a bus driver enumerates its bus, it gets the PnP Manager to call each new driver's AddDevice routine for each device it finds. The resources are assigned using the Start Device message. PnP messages are used to stop other drivers while the resources are being rejigged. Appropriate PnP messages are issued when a hot-pluggable device is removed.

The PnP system works with layers of drivers. I/O requests can be passed down to lower-level drivers for processing. A driver can then inspect the results from lower drivers and act accordingly. A driver can also generate new I/O requests to send to lower drivers.

Device Objects

Chapter 5 mentioned briefly that a PnP driver, such as Wdm1, has to deal with several different types of device object.

Each driver layer must create a device object to hold its information about a device. These device objects are arranged in a device stack, as shown in Figure 8.6. Note that it is the device objects that are directly connected together, not the drivers themselves (though each device object obviously knows with which driver it is associated). The arrangement is called a device stack, even though it does not correspond with the usual programmer definition of a stack.

The important point is that layers of device objects are built up. I/O requests are sent to the top of the stack and are gradually sent down the driver layers for processing. The results are sent back up the stack for post-processing.

In many cases, however, IRPs do not simply flow down to the bottom of the device stack and rise back up again. If one driver rejects a request, it can fail the IRPimmediately and send it back up straightaway. Another common scenario is as follows. Suppose one driver receives a read request. To process the read, it might have to issue two read requests to its underlying drivers. The driver issues these two requests in turn and then waits for the results before finally completing its own request (i.e. sending it back up the stack).

Figure 8.6 Device objects

As Figure 8.6 shows, the various device objects have different names. Each device object is, in fact, the same DEVICE_OBJECT structure. Different names are given to each type of device object simply to remind us what type of driver is involved.

The device object at the bottom of the stack is called the Physical Device Object (PDO). A PDO is created and serviced by the appropriate bus driver. For example, the USB bus driver provides the PDO for the USB keyboard and USB printer devices.

The main driver that services a device is called a function driver. An installation INF file may specify that more than one Function driver is put into the device stack.

Each function driver creates its own device object called a Functional Device Object (FDO). As Chapter 5 demonstrated, IoCreateDevice is used to create an FDO. After an FDO is created, it is usually attached to the device stack using IoAttachDeviceToDeviceStack. This returns a pointer to the next device down the stack that is stored in a field called NextStackDevice in the device extension. This typical device driver does not know where it is in the stack, so it passes any requests to NextStackDevice. In a simple case, the next device object might be the same as the PDO.

Some DDK examples refer to the next device in the stack as TopOfStack. I thought that this was slightly misleading, as the next device is not the top of all the device stack. Some other drivers call this field LowerDeviceObject.

A final category of device object is called a Filter Device Object (Filter DO). Filter device drivers are slipped into the driver stack as the stack is built to modify the behavior of other drivers.

The AddDevice routine in each function or filter driver is called whenever a new device stack is built. Each AddDevice routine is passed a pointer to the same bus driver PDO. AddDevice then makes an FDO that is then attached to the device stack. The order in which the driver AddDevice routines are called determines the order of drivers in the stack. In this way, the device stack is built from the bottom up. Similarly, when a device is removed, the device stack is deconstructed by removing the highest drivers first. The PDO serves as the anchor point for the whole device stack, as each driver in the stack is given the same PDO pointer.

Upper Edges

This section uses a full example to illustrate two points. First, it shows how I/O requests are handled by a real driver stack. Second, it shows how drivers can have an upper edge that is different from that provided by lower layers.

USB Keyboard Example

Figure 8.7 shows how a USB keyboard might be used. A USB keyboard must be accessed via the HID class driver. The figure shows how two possible HID clients talk to the keyboard.

The items in this figure are not discussed in detail. The chapters on USB and HID will explain all. The major information flows are of concern just now.

The USB keyboard driver is a kernel mode HID client that sends requests to the HID class driver in the form of standard IRP_MJ_READ and IRP_MJ_WRITE IRPs. These must be in the right format to be recognized by the HID class driver. Alternatively, a user mode HID application can access the HID keyboard directly (rather than by waiting for standard Windows character messages). It does this using the Win32 ReadFile and WriteFile routines. These calls appear to the HID class driver as IRP_MJ_READ and IRP_MJ_WRITE IRPs. Again, these requests must be in the correct HID format.

Internally, the HID class driver uses one of its minidrivers to talk to the lower drivers. In this case, it is using its USB minidriver to talk to the top of the USB stack. Although it is not shown on the diagram, the main HID class driver actually uses Internal IOCTLs to request I/O from a minidriver.

The HID USB minidriver generates Internal IOCTLs to use the services of the USB class drivers. The most common Internal IOCTL has a control code of IOCTL_INTERNAL_USB_SUBMIT_URB. This submits a USB Request Block (URB) to the USB class driver. To get some input data, the minidriver will almost certainly use the URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER function code within a URB.

As mentioned before, the USB class drivers are layered internally. In this case, the diagram shows that the OpenHCI USB host controller driver is in use. The OpenHCI driver will make some use of its lower driver, the PCI bus driver. However, it will do most of its work by talking directly to the OpenHCI USB Controller hardware. It will read and write memory and controller registers. It will almost certainly handle interrupts and use DMA to transfer information.

The USB controller hardware itself is responsible for the very last stage of the keyboard I/O request handling. It generates the appropriate signals on the USB bus, according to the instructions given to it by the USB class drivers. The USB keyboard understands these signals and responds according to its specification.

When a key is pressed on the keyboard, information percolates its way back up through the chain of drivers, ending up at one of the client drivers as a keypress input report.

Figure 8.7 HID USB Keyboard I/O Request handling

Functional and Physical Device Objects

Just to complicate matters, the previous example does not involve just one device stack. Instead, there are actually four, as shown in Table 8.3.

A device stack must always end at a Physical Device Object (PDO). Each bus driver creates a PDO for each device it finds.

1. Starting from the HID Keyboard driver's FDO, going down the stack, there is an FDO created by the HID class driver and a PDO created by the USB bus driver. These three device objects are in the first device stack.

2. The DDK documentation says that the USB class drivers are layered internally, with a hub driver at the top and a host controller driver at the bottom (OpenHCI, in this case).

3. The USB host controller was originally found by the PCI bus driver. Therefore, the host controller itself has an FDO that is layered on top of a PDO created by the PCI bus driver.

4. The PCI bus was originally found by the Windows root bus driver. The final device stack therefore consists of the PCI bus FDO layered on top of the root bus PDO.

This arrangement looks complicated. However, if you are trying to use only the USB class drivers, you do not really care how they process your requests. All the details of the other device stacks are hidden from you.

Table 8.3 USB Keyboard device stacks

Driver	Device stack
HID Keyboard driver	HID Keyboard device FDO
	HID class device FDO
	PDO (created by USB hub bus driver)
USB Hub USB	Hub device FDO
	PDO (created by USB host controller bus driver)
USB Host controller	USB Host Controller device FDO
	PDO (created by PCI bus driver)
PCI Adapter	PCI device FDO
	PDO (created by root bus driver)

Upper Edge Definitions

This example shows how several standard Windows system drivers have been used in the device stack for a USB keyboard. Each driver writer usually needs to know only the specification of the next layer down^[20]. The USB Keyboard driver writer needs to understand only the HID class driver specification. Knowledge of the different USB controllers and how to use them is definitely not required.

The upper edge of a driver is the specification of how to use it. The upper edge of the HID class driver responds to standard read and write IRPs. However, the upper edge of the USB class drivers only responds to Internal IOCTL IRPs. This is a sensible option for the USB class drivers, as it is not appropriate for user mode drivers to call them directly. User mode programs could not adhere to the timing requirements of the USB class drivers.

The example also shows that the upper edge presented by a driver does not determine its lower edge. The HID class drivers accept standard read and write IRPs. However, it implements these by sending Internal IOCTLs to its own minidriver. The USB minidriver implements its upper edge by sending URBs to the USB class drivers in its own Internal IOCTLs.

Thus, you have to look at some of the earlier example figures with care. Figure 8.5 shows function, filter, and bus drivers in a smooth hierarchy. In real life, the chain of events is much more complicated, as I/O requests are processed by several drivers.

A filter driver must have the same upper and lower edge because it must slip into the stack without affecting other drivers. A filter can modify or inspect the requests in which it is interested. However, all other requests must be passed down the stack unmodified. It is possible for a filter driver to perform some extra checking, which will mean that some IRPs are never passed down. However, it is vital that user mode applications or higher-level drivers can continue to function normally.

Conclusion

This chapter has presented the background for Plug and Play device drivers, the messages they handle, and how they fit into the WDM device stack. The next chapter looks at how to implement Plug and Play in practice and illustrates it in the Wdm2 device driver.

The last chapter went through the theory of Plug and Play (PnP) and the device stack. This chapter looks at how to implement Plug and Play in practice, with a discussion of the advanced topics of Plug and Play Notification and Bus drivers.

The Wdm2 example includes full PnP and Power Management facilities. Power Management is described in the next chapter.

The Wdm1Test user mode application tests some of the Wdm2 PnP functionality. The Wdm1Notify Win32 program displays PnP Notification device change events for the Wdm2 device interface.

Implementing Plug and Play

Supporting Plug and Play primarily means implementing an AddDevice routine and an IRP_MJ_PNP handler. This PnP IRP has eight minor function codes that most WDM drivers need to support.

• IRP_MN_START_DEVICE (Start Device)

• IRP_MN_QUERY_REMOVE_DEVICE (Query Remove)

• IRP_MN_REMOVE_DEVICE (Remove Device)

• IRP_MN_CANCEL_REMOVE_DEVICE (Cancel Remove)

• IRP_MN_STOP_DEVICE (Stop Device)

• IRP_MN_QUERY_STOP_DEVICE (Query Stop)

• IRP_MN_CANCEL_STOP_DEVICE (Stop Device)

• IRP_MN_SURPRISE_REMOVAL (Surprise Removal)

Looking at this list, it might not seem too complicated to handle Plug and Play in a driver. In fact, there are many things to get right. At a basic level this means:

• Coping with adding and removing devices

• Getting resource assignments

• Handling Query Stop and Query Remove messages

• Handling Stop messages

• Handling Surprise Removal messages

However, as will be shown, it soon becomes apparent that you must also do the following tasks:

• Allow only I/O requests while the device is started

• Not allow a device to be removed while there are any open handles

• Queue I/O requests while the device is not started

• Wait until any I/O requests have completed before handling remove requests

• Process Start Device messages after lower devices have started

• Pass unsupported IRPs down the stack

The rest of this chapter will look at the theory behind all the important PnP messages. The Wdm2 example driver shows how to implement most of the related tasks listed above. However, the most complicated — queuing I/O requests — is left until Chapter 16.

Refer to the previous chapter if you need to remind yourself of the difference between function and filter drivers, and the different types of device objects that the Wdm2 driver deals with.

Adding and Removing Devices

When a PnP driver handles an AddDevice message, it means that a new device has be found. Either a bus driver has found the device at power on or when it was inserted, or the user has added it by hand from the Control Panel. As Wdm2 devices are virtual, these have to be added by hand.

The PnP Manager will have worked out which drivers are going to be in the stack. The Physical Device Object (PDO) is created by the bus driver first. Then, going up the stack, each driver's AddDevice routine is called in turn. Chapter 11 describes how the PnP Manager works out which drivers to put in the stack.

If a driver's AddDevice routine fails, any drivers below it (whose AddDevice succeeded) will be sent a Remove Device message. Be prepared to accept a Remove Device message straightaway after your AddDevice routine has completed.

The job of an AddDevice routine is to create and initialize a device object for the current driver to use, and to connect it to the device stack. For function drivers, the device object is called a Functional Device Object (FDO). Filter drivers make a Filter Device Object (Filter DO). As mentioned in the last chapter, PDOs, FDOs, and Filter DOs all use the same DEVICE_OBJECT structure. Microsoft recommends that we use different names to help us remember what sort of driver owns the device object.

When a Wdm2 device is added, the Unknown bus driver makes a PDO for it. The PnP Manager passes the PDO to Wdm2. The Wdm2AddDevice routine, shown later, calls IoCreateDevice to create the Wdm2 Functional Device Object and eventually calls IoAttachDeviceToDeviceStack to attach it to the device stack. In between, the FDO and its device extension are initialized and a device interface for it is set up.

The eventual job of the Remove Device message handler is to stop the device and delete the FDO. In Wdm2, PnpRemoveDeviceHandler, shown later, eventually calls IoDetachDevice to detach the device object from the stack and calls IoDeleteDevice to delete the device object and its device extension memory. Processing Remove Device PnP messages safely is, in fact, a bit more complicated than this, as will be shown. Note that a Remove Device request will be the last IRP a driver receives before it is unloaded.

Basic PnP Handlers

The Wdm1 driver handles adding a device in its AddDevice routine and its Wdm1Pnp routine handles the remove device minor code IRP_MN_REMOVE_DEVICE.

The AddDevice and IRP_MJ_PNP handlers are called at PASSIVE_LEVEL IRQL in the context of a system thread. Calls to these routines may be issued while other IRPs are running in the same driver. Even in a uniprocessor computer, processing of a Read IRP could have stalled for some reason. A PnP call could then be issued.

AddDevice

In the Wdm2 driver, the code for adding and removing devices is substantially the same as Wdm1. The Wdm2AddDevice routine in Listing 9.1 is exactly the same, apart from new lines initializing some extra fields in the device extension. These all relate to handling PnP and Power IRPs correctly and are explained in due course.

Most of the PnP handling code is in the Wdm2 Pnp.cpp module. Some changes have been made to the Dispatch.cpp code from the Wdm1 version. A new module DeviceIo.cpp handles device starting and stopping.

Listing 9.1 Wdm2 Wdm2AddDevice

NTSTATUS Wdm2AddDevice(IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT pdo) {

 DebugPrint("AddDevice");

 NTSTATUS status;

 PDEVICE_OBJECT fdo;

 // Create our Functional Device Object in fdo

 status = IoCreateDevice(DriverObject, sizeof(WDM2_DEVICE_EXTENSION), NULL, FILE_DEVICE_UNKNQWN, 0, FALSE, &fdo);

 if (NT_ERROR(status)) return status;

 // Initialise device extension

 PWDM2_DEVICE_EXTENSION dx = (PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 dx->fdo = fdo;

 dx->pdo = pdo;

 dx->UsageCount = 1;

 KeInitializeEvent(&dx->StoppingEvent, NotificationEvent, FALSE);

 dx->OpenHandleCount = 0;

 dx->GotResources = false;

 dx->Paused = false;

 dx->IODisabled = true;

 dx->Stopping = false;

 dx->PowerState = PowerDeviceD3;

 dx->PowerIdleCounter = NULL;

 DebugPrint("FDO is %x",fdo);

 // Initialise device power state

 POWER_STATE NewState;

 NewState.DeviceState = dx->PowerState;

 PoSetPowerState(fdo, DevicePowerState, NewState);

 // Register and enable our device interface

 status = IoRegisterDevicelnterface(pdo, &WDM2_GUID, NULL, &dx->ifSymLinkName);

 if (NT_ERROR(status)) {

  IoDeleteDevice(fdo);

  return status;

 }

 IoSetDeviceInterfaceState(&dx->ifSymLinkName, TRUE);

 DebugPrint("Symbolic Link Name is %T",&dx->ifSymLinkName);

 // Attach to the driver stack below us

 dx->NextStackDevice = IoAttachDeviceToDeviceStack(fdo.pdo);

 // Set fdo flags appropriately

 fdo->Flags &= ~DO_DEVICE_INITIALIZING;

 fdo->Flags |= DO_BUFFERED_IO;

 dx->PowerIdleCounter = PoRegisterDeviceForIdleDetection(pdo, 30, 60, PowerDeviceD3);

 return STATUS_SUCCESS;

}

Remove Device handler

The code that handles removing devices has been moved to PnpRemoveDeviceHandler, as shown in Listing 9.2. This is the same as before, apart from calling the PnpStopDevice routine, which is explained in the following text.

Listing 9.2 Wdm2 PnpRemoveDeviceHandler

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

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 DebugPrintMsg("PnpRemoveDeviceHandler");

 // Wait for I/O to complete and stop device

 PnpStopDevice(dx);

 // Pass down stack and carry on immediately

 NTSTATUS status = PnpDefaultHandler(fdo, Irp);

 // disable device interface

 IoSetDeviceInterfaceState(&dx->ifSymLinkName, FALSE);

 RtlFreeUnicodeString(&dx->ifSymLinkName);

 // unattach from stack if (dx->NextStackDevice)

 IoDetachDevice(dx->NextStackDevice);

 // delete our fdo

 IoDeleteDevice(fdo); 

 return status;

}

Main PnP IRP Handler

The main IRP_MJ_PNP dispatch routine, Wdm2Pnp, has changed considerably from Wdm1, as shown in Listing 9.3. The bulk of the code is a switch statement based on the PnP minor function code. Most of the interesting minor function handling is delegated to subsidiary routines, but some are handled inline. All other minor function codes are handled by the PnpDefaultHandler routine. The PnpQueryCapabilitiesHandler routine is described in the chapter on Power Management.

Listing 9.3 Wdm2 Wdm2Pnp

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

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 DebugPrint("PnP %I",Irp);

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

 // Remember minor function

 PIO_STACK_LOCATION TrpStack = IoGetCurrentIrpStackLocation(Irp);

 ULONG MinorFunction = IrpStack->MinorFunction;

 NTSTATUS status = STATUS_SUCCESS;

 switch (MinorFunction) {

 case IRP_MN_START_DEVICE:

  status = PnpStartDeviceHandler(fdo,Irp);

  break;

 case IRP_MN_QUERY_REMOVE_DEVICE:

  status = PnpQueryRemoveDeviceHandler(fdo,Irp);

  break;

 case IRP_MN_SURPRISE_REMOVAL:

  status = PnpSurpriseRemovalHandler(fdo, Irp);

  break;

 case IRP_MN_REMOVE_DEVICE:

  status = PnpRemoveDeviceHandler(fdo,Irp);

  return status;

 case IRP_MN_QUERY_STOP_DEVICE:

  dx->Paused = true;

  dx->IODisabled = true;

  status = PnpDefaultHandler(fdo,Irp);

  break;

 case IRP_MN_STOP_DEVICE:

  status = PnpStopDeviceHandler(fdo,Irp);

  break;

 case IRP_MN_QUERY_CAPABILITIES:

  status = PnpQueryCapabilitiesHandler(fdo.Irp);

  break;

 case IRP_MN_CANCEL_REMOVE_DEVICE: // fall thru case IRP_MN_CANCEL_STOP_DEVICE:

  dx->Paused = false;

  dx-> IODisabled = false;

  status = PnpDefaultHandler(fdo,Irp);

  break;

 default:

  status = PnpDefaultHandler(fdo,Irp);

 }

 UnlockDevice(dx);

#if DBG

 if (status!=STATUS_SUCCESS) DebugPrint("PnP completed %x",status);

#endif

 return status;

}

Passing Unsupported IRPs Down the Stack

PnpDefaultHandler (Listing 9.4) passes the PnP IRP down the device stack for processing by all the lower device drivers. Call IoCallDriver whenever you want a driver to process an IRP. If you have created an IRP from scratch, you must set up all the IRP and IRP stack fields correctly. The different ways of allocating and sending your own IRPs are discussed in Chapter 21.

For PnpDefaultHandler, all the IRP structure fields are already set up correctly in the existing PnP IRP that is to be passed onto the next driver. What about the IRP stack?

One IRP stack location is reserved for each possible device in a device stack. When an IRP is passed to the next driver, the next stack location must be set up for it. However, in this case, the Wdm2 driver is never going to need to look at the IRP or its stack location again. IoSkipCurrentIrpStackLocation does not copy the current stack location to the next one. In fact, it simply sets up the IRP internally so that the next driver's call to IoGetCurrentlrpStackLocation returns the same stack location as Wdm2 saw.

You need to set up the next IRP stack location properly if you are going to inspect the IRP processing results or even simply wait for the IRP to complete. Use the routine IoCopyCurrentIrpStackLocationToNext if you simply want to copy the current stack location without changing any of the information. An example of this function is given in Listing 9.4 when Wdm2 waits for an IRP to be processed by all the lower drivers.

IoCallDriver, IoSkipCurrentlrpStackLocation, IoCopyCurrentlrpStackLocationToNext, and the other relevant function IoSetCompletionRoutine must be called at DISPATCH_LEVEL IRQL or lower.

PnpDefaultHandler therefore simply sets up the stack location and passes the IRP to the next lower driver in the device stack. It does not wait for the IRP to complete. It returns the status code that IoCallDriver returns.

Listing 9.4 Wdm2 PnpDefaultHandler

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

 DebugPrintMsg("PnpDefaultHandler");

 PWDM2_DEVICE_EXTENSI0N dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 IoSkipCurrentIrpStackLocation(Irp);

 return IoCallDriver(dx->NextStackDevice, Irp);

}

PnP States and Messages

Before continuing with the rest of the PnP implementation, it is worth looking again at the Plug and Play message and state diagram that was shown in the last chapter.

Figure 9.1 shows the main theoretical device states that a device can be in and the messages that are sent to change between these states. As mentioned before, a message such as START_DEVICE in this diagram corresponds to a PnP IRP with a minor code of IRP_MN_START_ DEVICE.

Note that I said "theoretical" device states. There are no visible flags in the kernel device structure that say which state a device is in. Wdm2 has to maintain its own state variables.

Another important point to note is that your code should be prepared to accept more-or-less any message from any state. The DDK documentation says in at least two places that an unexpected message may occasionally be sent when in one particular state.

Figure 9.1 Plug and Play device states and messages

State Flags

The device extension for Wdm2 device objects is shown in Listing 9.5. Four state flags are used to ensure that I/O requests are only begun when the device is in the Started state.

Paused	Device has a remove pending or stop pending
GotResources	Device running normally or paused (i.e., not stopped)
IODisabled	Paused or stopped
Stopping	Device is in process of being removed or stopped

The GotResources flag is set when the device has retrieved and allocated any hardware resources that it needs. In Figure 9.1, the GotResources flag is set when the device is in the Started, Stop pending, and Remove Pending states.

The Paused flag is set when the device is in the Stop Pending or Remove Pending States.

The IODisabled flag is set when GotResources is false or Paused is true (i.e., in the Stoppending, Remove Pending, Stopped, and Surprise removed states).

The Stopping flag is used during the processing of Remove Device and Stop Device messages, as described in the following text.

In the Device not present state, a device object and its flags simply do not exist.

Some devices may want to have an InterruptsEnabled flag, as well, to indicate when device interrupts are enabled.

Listing 9.5 Wdm2 device extension

typedef struct _WDM2_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

 DEVICE_POWER_STATE PowerState; // Our device power state

 PULONG PowerIdleCounter; // Device idle counter

 // Resource allocations

 bool GotPortOrMemory;

 bool PortInIOSpace;

 bool PortNeedsMapping;

 PUCHAR PortBase;

 PHYSICAL_ADDRESS PortStartAddress;

 ULONG PortLength;

 bool GotInterrupt;

 ULONG Vector;

 KIRQL Irql;

 KINTERRUPT_MODE Mode;

 KAFFINITY Affinity;

 PKINTERRUPT InterruptObject;

} WDM2_DEVICE_EXTENSION, *PWDM2_DEVICE_EXTENSION;

The GotResources flag indicates that Wdm2 has been assigned its resources. Wdm2 does not use any hardware resources. However, it still needs this flag to indicate the state it is in.

The Paused flag has no hardware interpretation. It is simply a way of stopping IRPs from starting when in the Stop Pending or Remove Pending states. In a full PnP implementation, IRPs must be queued while the Paused flag is set. Wdm2 should never get in the Stop Pending state, as it has no resources to reallocate. It should only be in the Remove Pending state briefly. For simplicity sake, Wdm2 does not queue IRPs. Chapter 16 gives this subject the full airing it deserves.

The IODisabled flag is provided so that the dispatch routines have to check only one flag quickly, not both GotResources and Paused. Each normal IRP dispatch routine, therefore, has the following code at the top that fails the IRP straightaway with an appropriate error code if the device is disabled.

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

To recap, three flags in the Wdm2 device extension are used to ensure that normal I/O requests are permitted only when the Wdm2 device is fully started. In fact, there will be very few times in the life of a Wdm2 device when I/O requests are not permitted. (Strictly speaking, I could have combined the Paused and IODisabled flags, but it is clearer to have them separate.)

Holding IRPs

When a device is not fully started, a full PnP implementation ought to queue I/O request IRPs.

Consider the various PnP stop messages. These occur when some new hardware has been added to the system or a new device has been plugged in. The PnP Manager may decide that it can only accommodate the new device by reassigning the resources that an existing device currently uses. It does this by issuing a Query Stop message first. If all devices in the stack agree that a stop can take place, then the PnP Manager issues a Stop Device request. If any of the drivers in the stack do not want the device stopped, the PnP Manager issues a Cancel Stop message. It then probably informs the user that there are not enough resources available currently and so a restart is necessary. When the resources have been reassigned, it sends a StartDevice message with the new resource allocations.

During this entire process, it seems reasonable that I/O requests on existing devices carry on as normal. In practice, this means not starting any new requests and holding them in a queue for processing when the device is started again. A user might therefore notice a slight pause in proceedings while resources are reassigned, but I/O requests should not fail.

The DDK documentation recommends that drivers do not start any new I/O requests after a Query Stop or Query Remove message has been received. This lets any following stop or remove request proceed quickly.

The end result is that IRPs ought to be queued when in the Stop Pending, Remove Pending, and Stopped states. In the Wdm2 driver, this means that IRPs ought to be queued when the IODisabled flag is true. However, as stated before, Wdm2 does not hold IRPs, as this is a complicated subject to be covered in Chapter 16.

As shown in Listing 9.3, Wdm2 handles Query Stop message by setting the Paused and IODisabled flags before passing the IRP down the stack. The Query Remove request does the same job. The Cancel Stop and Cancel Remove messages undo these actions by clearing Paused and IODisabled.

Open Handles

What happens if the user asks to remove the Wdm2 device while there are open handles to it?

The PnP Manager sends a Query Remove request to the driver. The simplest approach is to refuse to let a device be removed while there are any open handles. The DDK documentation says that the Query Remove must be failed if "there are open handles that cannot be closed".

Wdm2 uses the simple approach. It keeps a count of open handles to a device in the OpenHandleCount variable in the device extension. OpenHandleCount is initialized to zero when the device is created in Wdm2AddDevice. The InterlockedIncrement and InterlockedDecrement routines are used in the Wdm2Create and Wdm2Close dispatch routines, respectively, to maintain this count safely.

InterlockedIncrement(&dx->OpenHandleCount);

Listing 9.6 shows the complete Query Remove handler for Wdm2. If OpenHandleCount is greater than zero, PnpQueryRemoveDeviceHandler simply fails the IRP straightaway. Notice that it does not need to pass the PnP IRP down the stack as it is failing it. Instead, it just completes the IRP with the STATUS_UNSUCCESSFUL status code.

If there are no open handles, Wdm2 sets its Paused and IODisabled flags, as discussed before. However, in this case, PnpQueryRemoveDeviceHandler must pass the IRP down the stack in PnpDefaultHandler to give lower devices a chance to reject the Query Remove IRP.

Listing 9.6 Wdm2 PnpQueryRemoveDeviceHandler

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

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 DebugPrintMsg("PnpQueryRemoveDoviceHandler");

 if( dx->OpenHandleCount>0) {

  DebugPrint("PnpQueryRemoveDeviceHandler: %d handles still open", dx->OpenHandleCount);

  return CompleteIrp(Irp, STATUS_UNSUCCESSFUL, 0);

 }

 dx->Paused = true;

 dx->IODisabled = true;

 return PnpDefaultHandler(fdo,Irp);

}

When to Process PnP IRPs

You must be careful to process PnP IRPs at the right time. When a Start Device message is received for a USB device, for example, the USB drivers must enable the device at the bus level first. It is only then that the function drivers above can access the device. In fact, when processing the Start Device message, the drivers must process the message in order, going up the device stack.

Similar considerations apply when processing Stop, Remove, and Surprise Removal messages. In these cases, all the drivers in the stack must process the IRP first, in order going down the stack. Each driver must do whatever it needs to do to stop its device before the lower drivers pull the rug out from under its feet.

Handle the Cancel Remove and Cancel Stop requests on the way up the stack so that all the lower devices have restarted. However, the Wdm2 driver enables requests straightaway and then passes the IRP down the stack for processing.

The other PnP messages are usually processed by drivers on the way down the device stack. However, in a few circumstances, you may wish to see what results the lower drivers have produced.

WDM drivers can process IRPs in both these orders. So far, I have only shown how to process IRPs in order going down the stack. I shall now look at how to process IRPs in the other order.

IRP Completion Routines

As mentioned before, the IoCallDriver routine is used to call another driver. It is important to realize that IoCallDriver may return before the IRP has been completely processed. In this case, IoCallDriver returns STATUS_PENDING.

If a driver wants to process an IRP when all lower drivers have completed processing it, the driver must set a completion routine for the IRP. The completion routine is called when all the lower drivers have finished processing the IRP. The completion routine is called in an arbitrary context. I now show how a completion routine signals that it has been run using a kernel event.

Listing 9.7 shows how the ForwardIrpAndWait routine forwards an IRP to the lower drivers and waits for its completion. As ForwardIrpAndWait waits for the completion routine event to become signalled, it must run at PASSIVE_LEVEL IRQL. Waiting for dispatcher objects, such as events, is covered in full in Chapter 14. PnP IRPs are always called at PASSIVE_LEVEL, so it is safe to call ForwardIrpAndWait.

To set a completion routine, the next IRP stack location must be set up correctly. As described previously, IoCopyCurrentIrpStackLocationToNext copies all the current stack location parameters. Having done this, IoSetCompletionRoutine is used to set the completion routine to the ForwardedIrpCompletionRoutine function. ForwardIrpAndWait is then ready to call the next driver using IoCallDriver.

The last three BOOLEAN parameters of IoSetCompletionRoutine specify the circumstances in which you want the completion routine called. If the first BOOLEAN, InvokeOnSuccess, is TRUE, the completion routine is called if the IRP completes successfully. The other two BOOLEAN parameters, InvokeOnError and InvokeOnCancel, state whether the completion routine should be called if an error is returned or the IRP is cancelled. In ForwardIrpAndWait, I want the completion routine called in all circumstances, so all these parameters are set to TRUE.

ForwardIrpAndWait now has two tasks to perform. The completion routine has to signal when it has run, and the main code must wait for this signal. The signalling mechanism is a kernel event, which is basically the same as its Win32 equivalent. Chapter 14 discusses kernel events in full. The event is initialized to the nonsignalled state using KeInitializeEvent. When the completion routine runs, it simply calls KeSetEvent to set the event into the signalled state. ForwardIrpAndWait uses KeWaitForSingleObject to wait for the event to become signalled.

A completion routine has a standard prototype, passing the device object, the IRP, and a context pointer. In this case, ForwardIrpAndWait uses a pointer to the event as the context pointer. The context pointer is set in the IoSetCompletionRoutine call. When the IRP has been processed by all the lower drivers, ForwardedIrpCompietionRoutine is called. It simply sets the event.

ForwardedIrpCompletionRoutine returns a status of STATUS_MORE_PROCESSING_REQUIRED. This means that the IRP has not been completed by this driver and some other part of the driver will complete it. The only other alternative is to return STATUS_SUCCESS, in which case the IRP continues its journey back up the device stack.

IoCallDriver returns STATUS_PENDING if the IRP has not completed its processing by the lower drivers. If this value is returned, ForwardIrpAndWait must wait for the completion routine to run. Once the event has been set, the call to KeWaitForSingleObject returns. ForwardIrpAndWait retrieves the status returned by the lower drivers from the IRP's IoStatus.Status field.

If IoCallDriver returns any value apart from STATUS_PENDING, this means that the IRP has been processed by all the lower drivers. The completion routine has been run and the event set. However, ForwardIrpAndWait does not need to wait for the event, as it already knows that the IRP has been processed in full.

There is no way to know in advance if IoCallDriver will return a pending status. Therefore, if you want to use an IRP after calling IoCallDriver you must set a completion routine.

Completion routines may run at DISPATCH_LEVEL IRQL or lower in an arbitrary thread context. To be safe, you should assume that it is running at DISPATCH_LEVEL IRQL. This means that the completion routine itself and the context pointer must not be in paged memory. The ForwardIrpAndWait event variable is in the kernel stack. This is normally in non-paged memory. Apparently, the kernel stack can be pageable if a user mode wait is issued. However, as a kernel mode wait is used here, the event memory should be safely nonpaged.

Listing 9.7 Wdm2 Forwarding IRPs and waiting for completion

NTSTATUS Forward IrpAndWait(IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

 DebugPrintMsg("ForwardIrpAndWait");

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 KEVENT event;

 KeInitializeEvent(&event, NotificationEvent, FALSE);

 IoCopyCurrentIrpStackLocationToNext(Irp);

 IoSetCompletionRoutine(Irp, (PIO_COMPLETION_ROUTINE)ForwardedIrpCompletionRoutine, (PVOID)&event, TRUE, TRUE, TRUE);

 NTSTATUS status = IoCallDriver(dx->NextStackDevice, Irp);

 if (status==STATUS_PENDING) {

  DebugPrintMsg("ForwardIrpAndWait: waiting for completion");

  KeWaitForSingleObject(&event, Executive, KernelMode, FALSE, NULL);

  status = Irp->IoStatus.Status;

 }

#if DBG

 if (status!=STATUS_SUCCESS) DebugPrint("ForwardIrpAndWait: completed %x",status);

#endif

 return status;

}

NTSTATUS ForwardedIrpCompletionRoutine(IN PDEVICE_OBJECT fdo, IN PIRP Irp, IN PKEVENT ev) {

 KeSetEvent(ev, 0, FALSE);

 return STATUS_MORE_PROCESSING_REQUIRED;

}

Most completion routines should include the following code to remember if any lower driver has pended an IRP. If any driver in a stack marks an IRP as pending then the I/O Manager has to take special steps to ensure that the IRP results are returned to user space in the correct thread context.

Calling IoMarkIrpPending sets an internal pending flag in the current IRP stack location. When a lower driver completes an IRP, IoCompleteRequest sets the Irp->PendingReturned flag equal to the IRP stack internal flag. To remember that the IRP was pended, a completion routine must therefore call IoMarkIrpPending if Irp->PendingReturned is set.

if (Irp->PendingReturned) IoMarklrpPending(Irp);

PnP Start Device Handler

The Wdm2 driver handles the PnP Start Device message in its PnpStartDeviceHandler routine shown in Listing 9.8. The state diagram in Figure 9.1 shows that the Start Device message is received either from the Awaiting resources state or the Stopped state.

PnpStartDeviceHandler can then do whatever it needs to do to start its device. Wdm2 delegates this to the routine StartDevice, which will be covered later. StartDevice is passed a pointer to the allocated resources, in the IRP stack Parameters.StartDevice.AllocatedResourcesTranslated field.

If StartDevice succeeds, it will have set the GotResources flag. PnpStartDeviceHandler also then clears the Paused and IODisabled flags.

The drivers above Wdm2 in the device stack could fail the Start Device IRP. If this happens, Wdm2 and the other lower drivers will be sent a Remove Device request.

Listing 9.8 Wdm2 PnP start device handler

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

 DebugPrintMsg("PnpStartDeviceHandler");

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSION)fdo->DeviceExtension;

 PIO_STACK_LOCATION IrpStack = IoGetCurrentIrpStackLocation(Irp);

 NTSTATUS status = ForwardIrpAndWait(fdo, Irp);

 if (!NT_SUCCESS(status)) return CompleteIrp(Irp, status, Irp->IoStatus.Information);

 DebugPrint("PnpStartDeviceHandler: post-processing");

 status = StartDevice(dx, IrpStack->Parameters.StartDevice.AllocatedResourcesTranslated);

 if (NT_SUCCESS(status)) {

  dx->Paused = false;

  dx->IODisabled = false;

 }

 return Complete Irp(Irp, status, 0);

}

Device Locking

When a user wants to remove a Wdm2 device, the PnP Manager always asks if it is all right to remove it using a Query Remove request. As described previously, Wdm2 agrees to a removal request only if there are no open handles to the device. Therefore, for the main RemoveDevice request, the Wdm2 driver can be certain that there is no I/O in progress on the device.

However, some devices are hot-pluggable (i.e., a user can ruthlessly pull out the plug, or it could be bashed out by mistake). In this case, a PnP driver does not receive a Query Remove message. Instead, in Windows 98, it simply gets a Remove Device message. Windows 2000 sends a Surprise Removal message first and then sends a Remove Device request when all the open handles are closed.

A driver needs to cope with surprise removals in the best way possible. A SurpriseRemoval IRP must succeed. Obviously, the driver needs to stop any further I/O as soon as possible. However, one or more I/O requests may be in progress or queued up. It is fairly straightforward to cancel all the IRPs in a device queue; see Chapter 16 for details. However, the best method to handle I/O IRPs that are in progress is more complicated.

If you cannot somehow fail any I/O requests in progress, the recommended solution is to wait for them to complete. The main IRP processing routines are more than likely to be using the device or device extension, so these structures cannot be deleted until it is certain that they will not be used again. The main IRP processing routines almost certainly encounter some sort of problem. Make sure that they can handle a device being removed. A routine might be expecting an interrupt. Chapter 17 later shows how two different types of timers can be used to provide a time-out for I/O requests.

What is best way to keep track of how many I/O requests are in progress? The answer is to laboriously keep track of the number of open I/O requests in a UsageCount field in the device extension. A call to LockDevice is made at the beginning of each IRP request to increment UsageCount. UnlockDevice is called when each IRP is completed to decrement UsageCount.

UsageCount is set to one when the device is created. To remove or stop a device, an extra call to UnlockDevice is made. If there are no other IRPs in progress, this call should have decremented UsageCount to zero. If there are IRPs in progress, UsageCount will at this stage have a value greater than zero. However, when these IRPs finish, UnlockDevice will be called and so UsageCount will in due course become zero.

The Remove Device or Stop Device PnP IRP needs to know when UnlockDevice decrements UsageCount to zero. Another kernel event, StoppingEvent, is used for this purpose. UnlockDevice sets StoppingEvent into the signalled state when UsageCount drops to zero.

Listing 9.9 shows the PnpStopDevice routine that the Wdm2 driver uses to stop a device. It is called by the Remove Device, Surprise Removal, and Stop Device PnP IRP handlers. PnpStopDevice sets the IODisabled flag straightaway to stop any new requests from starting. The device is already stopped if GotResources is false, so no more processing is required.

PnpStopDevice resets StoppingEvent and then calls UnlockDevice twice. The first undoes the call to LockDevice at the start of the main PnP IRP handler. The second will reduce UsageCount to zero, either straightaway or when all the IRPs in progress complete. PnpStopDevice then waits for StoppingEvent to be set by UnlockDevice.

PnpStopDevice then calls the StopDevice routine, described later. StopDevice resets the GotResources flag. PnpStopDevice's last task is to call LockDevice again to increment UsageCount again. The main PnP IRP handler calls UnlockDevice in due course to get UsageCount down to its correct value of zero.

Listing 9.9 PnpStopDevice routine

void PnpStopDevice(IN PWDM2_DEVICE_EXTENSION dx) {

 // Stop I/O ASAP

 dx->IODisabled = true;

 // Do nothing if we're already stopped

 if (!dx->GotResources) return;

 // Wait for any pending I/O operations to complete

 dx->Stopping = true;

 KeResetEvent(&dx->StoppingEvent);

 UnlockDevice(dx);

 UnlockDevice(dx);

 KeWaitForSingleObject(&dx->StoppingEvent, Executive, KernelMode, FALSE, NULL);

 DebugPrint("PnpStopDevice: All pending I/O completed");

 dx->Stopping = false;

 // Stop our device before passing down

 StopDevice(dx);

 // Bump usage count back up again

 LockDevice(dx);

 LockDevice(dx);

}

Listing 9.10 shows how a typical I/O IRP dispatch routine fits into the Wdm2 device Plug and Play handling. Initially, it checks the IODisabled flag and then it tries to lock the device using LockDevice. If LockDevice fails, the correct response is to return STATUS_DELETE_PENDING. The Wdm2 PnpStopDevice routine always sets the IODisabled flag first, so the dispatch routine will never return STATUS_DELETE_PENDING. This could be fixed by adding another suitable flag to the device extension.

The dispatch routine ends by completing the IRP and calling UnlockDevice. If the IRP is not completed straightaway, do not call UnlockDevice straightaway. Instead, wait until the IRP is completed or cancelled before calling UnlockDevice.

All dispatch routines should include calls to LockDevice when an IRP arrives and UnlockDevice when an IRP is completed or passed onto another driver. PnP and WMI IRP handlers should also call these routines.

Listing 9.10 Dispatch routine entry and exit code

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

 PWDM2_DEVICE_EXTENSION dx = (PWDM2_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);

 // …

 // Complete IRP

 CompleteIrp(Irp,status,BytesTxd);

 UnlockDevice(dx);

 return status;

}

PnpStopDevice also sets another flag in the device extension, Stopping, to true while it is waiting for all pending I/O to complete. Although not strictly necessary in Wdm2, it is another way of forcing an IRP routine to see if it is OK to start during the call to LockDevice.

Listing 9.11 shows the LockDevice and UnlockDevice routines. They use InterlockedIncrement and InterlockedDecrement calls to ensure that UsageCount is maintained safely in multiprocessor systems. If UnlockDevice finds that UsageCount has decremented to zero, it sets the StoppingEvent flag. LockDevice also checks the Stopping flag. If it is set, a PnP IRP is trying to stop the device and so the caller should not continue. In this case, UsageCount is decremented and StoppingEvent is set, if appropriate, before false is returned.

Listing 9.11 LockDevice and UnlockDevice routines

bool LockDevice(IN PWDM2_DEVICE_EXTENSION dx) {

 InterlockedIncrement(&dx->UsageCount);

 if (dx->Stopping) {

  if (InterlockedDecrement(&dx->UsageCount)==0) KeSetEvent(&dx->StoppingEvent, 0, FALSE);

  return false;

 }

 return true;

}

void UnlockDevice(IN PWDM2_DEVICE_EXTENSION dx) {

 LONG UsageCount = InterlockedDecrement(&dx->UsageCount);

 if (UsageCount==0) {

  DebugPrintMsg("UnlockDevice: setting StoppingEvent flag");

  KeSetEvent(&dx->StoppingEvent, 0, FALSE);

 }

}

To wrap up the last loose ends, the handlers for the Stop Device and Surprise Removal messages are exactly the same, as shown in Listing 9.12. They both simply call PnpStopDevice and call PnpDefaultHandler to pass the IRP down the stack.

Listing 9.12 Stop device handler

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

 DebugPrintMsg("PnpStopDeviceHandler");

 PWDM2_DEVICE_EXTENSION dx=(PWDM2_DEVICE_EXTENSI0N)fdo->DeviceExtension;

 // Wait for I/O to complete and stop device

 PnpStopDevice(dx);

 return PnpDefaultHandler(fdo, Irp);

}

W2000 Device Locking

W2000 provides standard routines to replace our LockDevice and UnlockDevice routines, and the associated variables. You must provide an IO_REMOVE_LOCK field in your device extension. Initialise this field using IoInitializeRemoveLock function in your AddDevice routine. Replace all calls to LockDevice with IoAcquireRemoveLock and calls to UnlockDevice with IoReleaseRemoveLock. In the PnpStopDevice routine above, replace the code that waits for all pending I/O to complete with a call to IoReleaseRemoveLockAndWait.

The DDK recommended that you call IoAcquireRemoveLock whenever you pass out a reference to your code, e.g., a timer, DPC, or any other call-back routine. Call IoReleaseRemoveLock when these call-backs are disabled, i.e., usually in your Remove Device handler.

Getting Resource Assignments

A Start Device PnP IRP passes a list of the resources that have been assigned to the device. Although the Wdm2 driver never gets any resources, the code in DeviceIo.cpp goes through the steps to find these out. In addition, there is a lot of commented out code that shows how to use the resources. The WdmIo driver described in Chapters 15-17 show how hardware resources are actually used.

DeviceIo.cpp primarily contains the StartDevice and StopDevice routines. StartDevice must get the list of assigned resources, check that the resources are suitable, allocate them, and do any hardware-related initialization for the driver. If that all goes well, it should set the GotResources flag to true. StopDevice must release any hardware resources and reset the GotResources flag.

StartDevice calls RetrieveResources to find out which resources have been assigned to it by the PnP Configuration Manager. The Start Device PnP message passes two fields in the IRP stack Parameters.StartDevice structure, AllocatedResources, and AllocatedResourcesTranslated. AllocatedResources lists the resources in "raw form". This is how the device itself will see addresses, etc. Use AllocatedResources to program the device itself. Usually the "translated form" of the resource list, AllocatedResourcesTranslated, is of more interest to the driver. Use the AllocatedResourcesTranslated to connect to interrupt vectors, map I/O space, and memory.

If there are no resources assigned, W2000 sets these fields to NULL. In W98, a resource list is allocated but the "partial resource" count is zero.

Table 9.1 shows the raw and translated resource assignments for an I/O Port and two different interrupts in Windows 98 and Windows 2000.

Table 9.1 Resource assignments

I/O Port	Address
AllocatedResources	378
AllocatedResourcesTranslated	378
Interrupt (W98)	Vector	IRQL	Affinity	Mode
AllocatedResources	7	7	1	Latched
AllocatedResourcesTranslated	37	20	1	Latched
Interrupt (W2000)	Vector	IRQL	Affinity	Mode
AllocatedResources	3	3	-1	Latched
AllocatedResourcesTranslated	33	24	1	Latched

Partial Resource Descriptors

A resource list is an array of full resource descriptors. A full resource descriptor has a partial resource list, an array of partial resource descriptors. The relevant structures (CM_RESOURCE_ LIST, CM_FULL_RESOURCE_DESCRIPTOR, CM_PARTIAL_RESOURCE_LIST, and CM_PARTIAL_ RESOURCE_DESCRIPTOR) are also covered in Chapter 18.

WDM drivers have only one full resource descriptor^[21]. Therefore, inspect the array of partial resource descriptors to see what resources have been assigned. The resource descriptors are given in no particular order.

Table 9.2 shows the different types of resource information that can be found in a partial resource descriptor. The Type field specifies what resource is described. There is also a ShareDisposition field that specifies how the resource can be shared. One of the following values can be found: CmResourceShareDeviceExclusive, CmResourceShareDriverExclusive, or CmResourceShareShared.

Table 9.2 Partial resource descriptors

I/O Port	(Type==CmResourceTypePort)
PHYSICAL_ADDRESS	u.Port.Start Port Bus specific start address
ULONG u.Port.Length	Number of addresses
USHORT Flags	CM_RESOURCE_PORT_IO or CM_RESOURCE_PORT_MEMORY if you need to map the port into memory with MmMapIoSpace
Memory	(Type==CmResourceTypeMemory)
PHYSICAL_ADDRESS	u.Memory.Start Bus specific start address
ULONG u.Memory.Length	Number of addresses
USHORT Flags	CM_RESOURCE_MEMORY_READ_WRITE CM_RESOURCE_MEMORY_READ_ONLY CM_RESOURCE_MEMORY_WRITE_ONLY
Interrupt	(Type==CmResourceTypeInterrupt)
ULONG u.Interrupt.Level	The interrupt IRQL
ULONG u.Interrupt.Vector	The interrupt vector
ULONG u.Interrupt.Affinity	The set of processors to which the interrupt is dispatched.
USHORT Flags	CM_RESOURCE_INTERRUPT_LEVEL_SENSITIVE CM_RESOURCE_INTERRUPT_LATCHED
DMA	(Type==CmResourceTypeDma)
ULONG u.Dma.Channel	System DMA controller channel
ULONG u.Dma.Port	MCA type device port
USHORT Flags	See the DDK
Other resource types
UCHAR Type	CmResourceTypeDeviceSpecific CmResourceTypeBusNumber CmResourceTypeDevicePrivate CmResourceTypePcCardConfig

The RetrieveResources code shown in Listing 9.13 extracts and checks the resources that have been assigned for this device. It first checks whether any resources have been assigned. As Wdm2 does not need any resources, it simply returns STATUS_SUCCESS if there are no resources.

RetrieveResources then goes through the partial resource descriptor list checking for I/O Port, Memory, and Interrupt resource types. The assigned information is stored in the device extension and printed out using DebugPrint. Other resource types result in an error.

Listing 9.13 RetrievereSources routine

NTSTATUS RetrieveResources(IN PWDM2_DEVICE_EXTENSION dx, IN PCM_RESOURCE_LIST AllocatedResourcesTranslated) {

 if (AllocatedResourcesTranslated==NULL || AllocatedResourcesTranslated->Count==0) {

  DebugPrintMsg("RetrieveResources: No allocated translated resources");

  return STATUS_SUCCESS; // or whatever

 }

 // Get to actual resources

 PCM_PARTIAL_RESOURCE_LIST list = &AllocatedResourcesTranslated->List[0].PartialResourceList;

 PCM_PARTIAL_RESOURCE_DESCRIPTOR resource = list->PartialDescriptors;

 ULONG NumResources = list->Count;

 DebugPrint("RetrieveResources: %d resource lists %d resources", AllocatedResourcesTranslated->Count, NumResources);

 bool GotError = false;

 // Clear dx

 dx->GotInterrupt = false;

 dx->GotPortOrMemory = false;

 dx->PortInIOSpace = false;

 dx->PortNeedsMapping = false;

 // Go through each allocated resource

 for (ULONG i=0; i<NumResources; i++,resource++) {

  switch (resource->Type) {

  case CmResourceTypePort:

   if (dx->GotPortOrMemory) {

    GotError = true;

    break;

   }

   dx->GotPortOrMemory = true;

   dx->PortStartAddress = resource->u.Port.Start;

   dx->PortLength = resource->u.Port.Length;

   dx->PortNeedsMapping = (resource->Flags & CM_RESOURCE_PORT_IO)==0;

   dx->PortInIOSpace = !dx->PortNeedsMapping;

   DebugPrint("RetrieveResources: Port %x%x Length %d NeedsMapping %c",

    dx->PortStartAddress.HighPart, dx->PortStartAddress.LowPart, dx->PortLength, dx->PortNeedsMapping);

   break;

  case CmResourceTypeInterrupt:

   dx->GotInterrupt = true;

   dx->Irql = (KIRQL)resource->u.Interrupt.Level;

   dx->Vector = resource->u.Interrupt.Vector;

   dx->Affinity = resource->u.Interrupt.Affinity;

   dx->Mode = (resource->Flags = CM_RESOURCE_INTERRUPT_LATCHED) ? Latched : LevelSensitive;

   DebugPrint("RetrieveResources: Interrupt vector %x IRQL %d Affinity %d Mode %d",

    dx->Vector, dx->Irql, dx->Affinity, dx->Mode);

   break;

  case CmResourceTypeMemory:

   if (dx->GotPortOrMemory) { GotError = true; break; }

   dx->GotPortOrMemory = true;

   dx->PortStartAddress = resource->u.Memory.Start;

   dx->PortLength = resource->u.Memory.Length;

   dx->PortNeedsMapping = true;

   DebugPrint("RetrieveResources: Memory %x%x Length %d",

    dx->PortStartAddress.HighPart, dx->PortStartAddress.LowPart, dx->PortLength);

   break;

  case CmResourceTypeDma:

  case CmResourceTypeDeviceSpecific:

  case CmResourceTypeBusNumber:

  default:

   DebugPrint("RetrieveResources: Unrecognised resource type %d", resource->Type);

   GotFrror = true;

   break;

  }

 }

 // Check we've got the resources we need

 if (GotError /*|| !GotPortOrMemory || !GotInterrupt*/)

  return STATUS_DEVICE_CONFIGURATION_ERROR;

 return STATUS_SUCCESS;

}

Allocating Resources

The StartDevice routine now allocates the system resources it requires. The Wdm2 driver does not need or expect any resources, so this code is commented out. The WdmIo driver covered in Chapters 15-17 does use system resources. These chapters cover Critical section routines and Interrupts in detail. However, I will briefly introduce these topics now.

For memory mapped I/O ports (with the CM_RESOURCE_PORT_MEMORY flag bit set) you must call MmMapIoSpace to get a pointer that can be used by a driver. Do not forget to call MmUnmapIoSpace when the device is stopped.

dx->PortBase = (PUCHAR)MmMapIoSpace(dx->PortStartAddress, dx->PortLength, MmNonCached);

For ordinary I/O ports and memory, simply use the low 32 bits of the PortStartAddress^[22].

dx->PortBase = (PUCHAR)dx->PortStartAddress.LowPart;

For interrupts, IoConnectInterrupt is called to install an interrupt handler. You must be ready to handle an interrupt straightaway, so make sure that everything is set up correctly. It is common to be able to disable interrupts by writing some value to a device register. Write a DisableDeviceInterrupts routine to disable interrupts before calling IoConnectInterrupt and call your EnableDeviceInterrupts routine when you are ready to receive interrupts.

Any code that tries to access some real hardware must synchronize its activities with the interrupt handler. It is no good having an interrupt during a complicated device access procedure. Critical section routines solve this problem. You call KeSynchronizeExecution passing the name of the function you want called. KeSynchronizeExecution raises the IRQL to the correct interrupt level and calls your routine. When it has completed, the IRQL is lowered again. Critical section routines obviously need to be in nonpaged memory and cannot access paged memory.

EnableDeviceInterrupts and DisableDeviceInterrupts are usually Critical section routines and will usually need to be called via KeSynchronizeExecution.

Finally, StartDevice powers up its device, as described in the next chapter.

Port and Memory I/O

There are several standard kernel routines to access I/O ports and memory, as this code snippet shows.

void WriteByte(IN PWDM2_DEVICE_EXTENSION dx, IN ULONG offset, IN UCHAR byte) {

 if (dx->PortInIOSpace) WRITE_PORT_UCHAR(dx->PortBase+offset, byte);

 else WRITE_REGISTER_UCHAR(dx->PortBase+offset, byte);

}

Read data using the routines with READ in their name and write data with WRITE routines. PORT routines access I/O registers in I/O port space, while REGISTER routines access registers in memory space. Each type has UCHAR, USHORT, and ULONG variants. Finally, BUFFER variants transfer more than one data value. For example, use the following code to read a set of ULONG values from I/O port space into a buffer.

READ_PORT_BUFFER_ULONG( PortBase, Buffer, Count);

As mentioned previously, synchronize all your hardware accesses with any interrupt routines using Critical section routines and KeSynchronizeExecution. Chapter 16 covers Critical section routines.

Device Access

Most WDM drivers do not, in fact, need to access I/O ports and memory or handle interrupts. Instead, they access their devices using the facilities provided by class drivers. For example, a USB client driver uses the oft-mentioned USB Request Blocks (URBs) to access its device.

When a USB client driver handles a PnP Start Device message, it first waits for the IRP to be processed by lower level drivers. It then typically issues one or more URBs to its device before completing its IRP.

For Stop Device messages, a USB client driver might well want to issue one or more URBs to its device before the IRP is sent down the stack.

Testing Wdm2

The Wdm2Test Win32 console application in the Wdm2\exe subdirectory of the book software tests the Wdm2 driver. Wdm1Test is the same as Wdm1Test with only one change, apart from referencing the Wdm2 driver. Wdm2Test halts halfway through, waiting for the user to press a key. While it is waiting, it has a handle to the first Wdm2 device still open.

First, install a Wdm2 device using one of the installation INF files in the book software Wdm2\sys directory. It does not matter whether you use the free or checked build, although the checked build produces DebugPrint trace output.

Wdm2Test tests to see if a Query Remove request is rejected while there are any open handles to a Wdm2 device. Run Wdm2Test but do not press a key when it stops halfway through. Now try to remove the Wdm2 device or reinstall its driver. The request should be rejected. Windows will state that the system must be restarted for the operation to complete.

Check that the Wdm2 driver can be removed or reinstalled when Wdm2Test has completed.

It is very difficult to test the other new aspects of Plug and Play support in the Wdm2 driver. First, Stop Device and Surprise Removal requests should never be issued for virtual devices that have no resources. Second, it is not possible to suddenly remove a Wdm2 device in such a way that the Wdm2 driver has to wait for pending I/O to complete. Do appropriate tests for drivers that have resources and can be suddenly removed.

If the test for open handles is not made, then W2000 in fact will still not allow the device to be removed, as it must contain its own internal reference count for the device. However, W98 would let the device be removed. Any I/O requests on open handles would then simply fail.

Actual Plug and Play Messages

The DebugPrint output from Wdm2 shows exactly which Plug and Plug messages are sent by Windows during add device and remove device operations.

Adding a Device

The following PnP calls are made when a Wdm2 device is successfully added, or when the driver for a device is reinstalled. Two of the messages are issued only by Windows 2000.

AddDevice

(W2000) IRP_MN_QUERY_LEGACY_BUS_INFORMATION

IRP_MN_FILTER_RESOURCE_REQUIREMENTS

IRP_MN_START_DEVICE

IRP_MN_QUERY_CAPABILITIES

IRP_MN_QUERY_PNP_DEVICE_STATE

IRP_MN_QUERY_DEVICE_RELATIONS BusRelations

IRP_MN_QUERY_DEVICE_RELATIONS BusRelations (W2000)

Removing a Device

The following PnP messages are sent when a Wdm2 device is successfully removed, or when the driver for a device is reinstalled.

IRP_MN_QUERY_DEVICE_RELATIONS RemoveRelations

IRP_MN_QUERY_REMOVE_DEVICE

IRP_MN_REMOVE_DEVICE

Unknown Status Returns

It is interesting to note the IRP status values are returned by the lower Unknown driver when Wdm2 sends IRPs down the stack. Windows is supposed to set the IRP status return value to STATUS_NOT_SUPPORTED before it is issued to the top of the device stack. If Wdm2 sees this value on return from its PnpDefaultHandler routine, it means that the lower drivers have not processed the IRP or have deliberately not returned STATUS_NOT_SUPPORTED.

For Wdm2, W98 succeeds all the PnP IRPs that it receives.

For Wdm2, W2000 does not process IRP_MN_FILTER_RESOURCE_REQUIREMENTS, IRP_MN_QUERY_PNP_DEVICE_STATE, IRP_MN_QUERY_BUS_INFORMATION, and IRP_MN_QUERY_DEVICE_RELATIONS IRPs.

Other PnP IRPs

This section briefly describes the Plug and Plug minor function code IRPs that have not been described in full before. These IRPs are handled by PnP bus drivers. The notes for each function code indicate if it is possible for a function driver to intercept the IRP.

Most function drivers ignore all these PnP IRPs. However, a function driver that performs Power Management may well want to handle IRP_MN_QUERY_CAPABILITIES. The following chapter describes how this is done.

IRP_MN_DEVICE_USAGE_NOTIFICATION

This message tells a driver if its device is in the path of a paging, hibernation, or crash dump file. Do not allow a device to be removed until you are notified that no critical file is on its path.

IRP_MN_FILTER_RESOURCE_REQUIREMENTS

The Windows 2000 PnP Manager sends this IRP to a device stack so filter and function drivers can adjust the resources required by the device, if appropriate. Function, filter, and bus drivers can handle this request.

IRP_MN_QUERY_BUS_INFORMATION

The PnP Manager uses this IRP to request the type and instance number of a device's parent bus.

Bus drivers should handle this request for their child devices (PDOs). Function and filter drivers do not handle this IRP.

IRP_MN_QUERY_CAPABILITIES

The PnP Manager sends this IRP to get the capabilities of a device, such as whether the device can be locked or ejected, and various Power Management features. Function and filter drivers can handle this request if they alter the capabilities supported by the bus driver. Bus drivers must handle this request for their child devices.

This IRP is sent twice, both before and after function drivers are loaded and started.

A driver can send one of these IRPs down the stack to see what the bus driver capabilities are.

IRP_MN_QUERY_DEVICE_RELATIONS

This IRP asks how this device relates to other devices and comes in five different forms. All forms return an array of pointers to the relevant PDOs.

A BusRelations query asks for the PDOs of all the devices physically present on the bus. EjectionRelations asks which devices are also ejected if this device is ejected. PowerRelations asks which devices are also powered down when this device is powered down. RemovalRelations asks which devices must be removed when this device is removed. TargetDeviceRelation calls ObReferenceObject for the device PDO and returns the PDO.

IRP_MN_QUERY_DEVICE_TEXT

The PnP Manager uses this IRP to get a device's description or location information. Bus drivers must handle this request for their child devices if the bus supports this information. Function and filter drivers do not handle this IRP.

Parameters.QueryDeviceText.DeviceTextType is either DeviceTextDescription or DeviceTextLocationInformation.Parameters.QueryDeviceText.LocaleId is an LCID specifying the locale for the requested text.

IRP_MN_QUERY_ID

This IRP gets device, hardware, compatible, or instance IDs for a device, depending on whether Parameters.QueryId.IdType is BusQueryDeviceID, BusQueryHardwareIDs, BusQueryCompatibleIDs, or BusQueryInstanceID.

IRP_MN_QUERY_INTERFACE

The IRP_MN_QUERY_INTERFACE request enables a driver to export a direct-call interface to other drivers.

IRP_MN_QUERY_PNP_DEVICE_STATE

The query asks the drivers in the device stack to set any of the state bits shown in Table 9.3. Be careful not to overwrite any bits that are set by other drivers.

Table 9.3 Query device state bits

PNP_DEVICE_DISABLED	The device is physically present but is disabled in hardware.
PNP_DEVICE_DONT_DISPLAY_IN_UI	Don't display the device in the user interface. The device is physically present but not usable in the current configuration.
PNP_DEVICE_FAILED	The device is present but not functioning correctly. When both this flag and PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED are set, the device must be stopped before the PnP Manager assigns new hardware resources.
PNP_DEVICE_REMOVED	The device has been physically removed.
PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED	The resource requirements for the device have changed.
PNP_DEVICE_NOT_DISABLEABLE	The device cannot be disabled.

If any of the state characteristics change after the initial query, a driver notifies the PnP Manager by calling IoInvalidateDeviceState. In response to a call to IoInvalidateDeviceState, the PnP Manager queries the device's PNP_DEVICE_STATE again.

IRP_MN_QUERY_RESOURCE_REQUIREMENTS

The PnP Manager uses this IRP to get a device's resource requirements list. Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP.

IRP_MN_QUERY_RESOURCES

The PnP Manager uses this IRP to get a device's boot configuration resources. Bus drivers must handle this request for their child devices that require hardware resources. Function and filter drivers do not handle this IRP.

IRP_MN_READ_CONFIG

Bus drivers for buses with configuration space must return the relevant information for their child devices. Filter and function drivers do not handle this request.

IRP_MN_SET_LOCK

This request is used to lock or unlock a device. Bus drivers must handle this IRP for a child device that supports device locking. Function and filter drivers do not handle this request.

IRP_MN_WRITE_CONFIG

Bus drivers must write the given information into the configuration space of the child device. Function and filter drivers do not handle this request.

Plug and Play Notification

Plug and Play Notification informs Win32 programs and device drivers of device change events that interest them, such as device arrival and removal. They can also refuse requests to remove a device. PnP Notification uses a device interface GUID or a file handle to identify which devices are of interest.

Win32 applications and device drivers register to receive PnP notifications so that they can cope if a device is about to be removed, or if they want to use a device that has just been added. For example, if a program is in the middle of a long transfer, it could refuse permission for a device to be removed. In addition, device drivers can be informed of all devices that expose the required device interface.

Win32 PnP Notification

A Win32 program calls RegisterDeviceNotification to register that it wants to receive PnP Notification device change messages. You must pass either a window handle or (in W2000 only) a service status handle. The NotificationFilter parameter points a structure that says what type of events you want to receive.

To receive events about devices with a particular device interface, pass a DEV_BROADCAST_DEVICEINTERFACE structure pointer to RegisterDeviceNotification. Set the dbcc_classguid field to the device interface GUID of interest. Set the dbcc_size and dbcc_devicetype fields appropriately.

I have not tried it, but passing a DEV_BROADCAST_HANDLE structure pointer should let you receive events from one open file handle, including custom events.

Do not forget to call UnregisterDeviceNotification when you do not wish to receive any further PnP Notification events.

Device Change Message

Each PnP Notification event is sent to a Win32 program as a WM_DEVICECHANGE message. In MFC applications, this appears in an OnDeviceChange handler.

Table 9.4 lists the main event types returned in wParam. lParam may point to an appropriate structure. For device interface change events, it is a DEV_BROADCAST_DEVICEINTERFACE structure whose dbcc_name field contains the device filename.

For a WM_DEVICECHANGE message that asks permission to remove a device, the handler must return TRUE to agree or BROADCAST_QUERY_DENY^[23] to deny the requests. Returning FALSE seems to have the same effect as returning TRUE.

Table 9.4 WM_DEVICECHANGE event types

DBT_CONFIGCHANGECANCELED	A request to change the current configuration (dock or undock) has been cancelled
DBT_CONFIGCHANGED	The current configuration has changed, due to a dock or undock
DBT_CUSTOMEVENT	A custom event has occurred
DBT_DEVICEARRIVAL	A device has been inserted and is now available
DBT_DEVICEQUERYREMOVE	Permission is requested to remove a device. Any application candeny this request and cancel the removal
DBT_DEVICEQUERYREMOVEFAILED	A request to remove a device has been cancelled
DBT_DEVICEREMOVEPENDING	A device is about to be removed. Cannot be denied
DBT_DEVICEREMOVECOMPLETE	A device has been removed
DBT_DEVICETYPESPECIFIC	A device-specific event has occurred
DBT_QUERYCHANGECONFIG	Permission is requested to change the current configuration (dock or undock)
DBT_DEVNODES_CHANGED	Device tree has changed
DBT_USERDEFINED	The meaning of this message is user-defined

Wdm2Notify application

Wdm2Notify is a Win32 MFC dialog application that displays any device change events for the Wdm2 device interface. It can be found in the Wdm2\Notify directory of the book software. I had a little difficulty setting up the project so that it would compile and link correctly. As I was using VC++ 5, some of the header files and libraries were out of date. I therefore had to change the project settings to use the Platform SDK include directories first, before the Visual C++ directories. My Platform SDK was installed at D:\MSSDK, so you may need to change the project settings if you want to recompile Wdm2Notify. I also had to link to the version of user32.lib in the Platform SDK. If you are running a later version of Visual Studio, you may be able to undo these project changes.

Some of the device change structures are defined in dbt.h, so I included this header file in the Wdm2Notify main MFC header, stdafx.h. I also had to include the following line in the stdafx.h to ensure that the correct functions were declared.

#define WINVER 0x0500

Listing 9.14 shows the main Wdm2Notify PnP Notification routines in file Wdm2Notif.yDlg.cpp. RegisterDeviceNotification is called in the dialog OnInitDialog routine and unregistered in DestroyWindow. Device change messages are handled in OnDeviceChange. The rest of the source code for Wdm2Notify can be found on the book software disk.

Listing 9.14 Wdm2Notify device change routines

BOOL CWdm2NotifyDlg::OnInitDialog() {

 CDialog::OnlnitDialog();

 // …

 // Register for Wdm2 device interface changes

 DEV_BROADCAST_DEVICEINTERFACE dbch;

 dbch.dbcc_size = sizeof(dbch);

 dbch.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;

 dbch.dbcc_classguid = WDM2_GUID;

 dbch.dbcc_name[0] = '\0';

 WdmNotificationHandle = RegisterDeviceNotification(GetSafeHwnd(), &dbch, DEVICE_NOTIFY_WINDOW_HANDLE);

 if (WdmNotificationHandle==NULL)

  GetDlgItem(IDC_STATUS)->SetWindowText("Cannot register for Wdm2 class device notification");

 return TRUE;

}

BOOL CWdm2NotifyDlg::DestroyWindow() {

 if (WdmNotificationHandle!=NULL) {

  UnregisterDeviceNotification(WdmNotificationHandle);

  WdmNotificationHandle = NULL;

 }

 return CDialog::DestroyWindow();

}

BOOL CWdm2NotifyDlg::OnDeviceChange(UINT nEventType, DWORD dwData) {

 CString Msg = "duh";

 switch (nEventType) {

 case DBT_CONFIGCHANGECANCELED:

  Msg.Format("DBT_CONFIGCHANGECANCELED");

  break;

 case DBT_CONFIGCHANGED:

  Msg.Format("DBT_CONFIGCHANGED");

  break;

 case DBT_CUSTOMEVENT:

  Msg.Format("DBT_CUSTOMEVENT");

  break;

 case DBT_DEVICEARRIVAL:

  Msg.Format("DBT_DEVICEARRIVAL");

  break;

 case DBT_DEVICEQUERYREMOVE:

  Msg.Format("DBT_DEVICEQUERYREMOVE");

  break;

 case DBT_DEVICEQUERYREMOVEFAILED:

  Msg.Format("DBT_DEVICEQUERYREMOVEFAILED");

  break;

 case DBT_DEVICEREMOVEPENDING:

  Msg.Format("DBT_DEVICEREMOVEPENDING");

  break;

 case DBT_DEVICEREMOVECOMPLETE:

  Msg.Format("DBT_DEVICEREMOVECOMPLETE");

  break;

 case DBT_DEVICETYPESPECIFIC:

  Msg.Format("DBT_DEVICETYPESPECIFIC");

  break;

 case DBT_QUERYCHANGECONFIG:

  Msg.Format("DBT_QUERYCHANGECONFIG");

  break;

 case DBT_DEVNODES_CHANGED:

  Msg.Format("DBT_DEVNODES_CHANGED");

  break;

 case DBT_USERDEFINED:

  Msg.Format("DBT_USERDEFINED");

  break;

 default:

  Msg.Format("Event type %d",nEventType);

 }

 PDEV_BROADCAST_DEVICEINTERfACE pdbch = (PDEV_BROADCAST_DEVICEINTERFACE)dwData;

 if (pdbch!=NULL && pdbch->dbcc_devicetype==DBT_DEVTYP_DEVICEINTERFACE) {

  CString Msg2;

  Msg2.Format("%s: %s",Msg,pdbch->dbcc_name);

  Msg = Msg2;

 }

 CListBox* EventList = (CListBox*)GetDlgItem(IOC_EVENT_LIST);

 EventList->AddString(Msg);

 return TRUE; // or BROADCAST_QUERY_DENY to deny a query remove

}

Running Wdm2Notify in Windows 98

Figure 9.2 shows some typical output in the Wdm2Notify window in Windows 98 as the Wdm2 driver is updated for an installed Wdm2 device. First the PnP Manager asks if it is OK for the existing Wdm2 device to be removed. Then it issues remove pending and remove complete messages. When the driver has been updated, the Wdm2 device is added again resulting in a device arrival message. Finally, a DBT_DEVNODES_CHANGED event indicates that the device tree has changed.

I am not sure why there are so many duplicate device change messages.

If Wdm2Notify returns BROADCAST_QUERY_DENY to the Query Remove message, the remove is correctly refused and a DBT_DEVICEQUERYREMOVEFAILED message is then issued.

Figure 9.2 Wdm2Notify output in Windows 98

Running Wdm2Notify in Windows 2000

The Beta 2 version of Windows 2000 produces output very different from Wdm2Notify. It issues only a DBT_DEVICEREMOVECOMPLETE message and then a DBT_DEVICEARRIVAL message. A Query Remove request is not issued and there are no repeat messages. I hope that the final version of W2000 will issue more PnP Notification device change messages to Win32 applications.

Device Driver PnP Notification

A driver uses PnP Notification to find devices with a particular device interface. A driver does this so that it can issue calls to the devices that it finds. It may wish to layer its own device on top of each found device. This technique is commonly used when finding Human Input Devices, and a full example of this is given in Chapter 23.

PnP Notification in device drivers works in a similar way to Win32 applications. Remember that this is one device driver asking for device change notifications about devices controlled by another driver.

The driver must call IoRegisterPlugPlayNotification to indicate which events it is interested in receiving, and eventually call IoUnregisterPlugPlayNotification when done. You must pass the name of a callback routine to IoRegisterPlugPlayNotification, along with a context pointer.

In device drivers, you can ask for three different categories of PnP Notification events. If you ask for EventCategoryDeviceInterfaceChange events your callback routine is passed a DEVICE_INTERFACE_CHANGE_NOTIFICATION structure that notifies you only of device removal and device arrival events, along with the appropriate symbolic link. Specify the relevant GUID in the EventCategoryData parameter of IoRegisterPlugPlayNotification. If you specify PNPNOTIFY_DEVICE_INTERFACE_INCLUDE_EXISTING_INTERFACES for the EventCategoryFlags parameter, arrival events are also sent straightaway for any existing devices that have a matching device interface GUID.

If you register for EventCategoryHardwareProfileChange events, you receive query change, change complete, and change cancelled events.

Finally, if you ask for EventCategoryTargetDeviceChange events, you receive query remove, removal completes, and remove cancelled messages for one specific device. You must supply a pointer to the relevant file object as the EventCategoryData parameter of IoRegisterPlugPlayNotification. I assume that you can reject query remove requests.

Driver PnP Notification is particularly important for client drivers that use device interfaces exposed by the system class drivers. For example, kernel mode Human Input Device (HID) client drivers can use PnP Notification to identify all installed HID devices. See Chapter 23 for a full example of PnP Notification in device drivers.

As mentioned earlier, device stacks cannot be changed once they are built. PnP Notification lets you find existing devices and effectively layer on top of them.

Notification Request Driver Interactions

As might expect, Win32 programs and device drivers that register for PnP Notification events will effect the operation of a driver. Query remove requests are processed by PnP Notification applications and drivers before the main driver receives an IRP_MN_QUERY_REMOVE_DEVICE IRP. Cancel remove notification messages are sent to applications and other drivers after the main driver has processed its IRP_MN_CANCEL_REMOVE_DEVICE message. Remove pending messages are sent before a device is removed (or surprise removed) and a remove complete notification message is sent afterwards.