Chris Cant - Writing Windows WDM Device Drivers

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.

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.

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.

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.

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.