Writing WDM Drivers

This section discusses the Microsoft Windows Driver Model (WDM) architecture. This architecture started in Windows 2000 as an enhancement to previous Windows NT device drivers.

NoteВ В Drivers for versions of Windows NT-based operating systems before Windows 2000 are not supported, and you should update these drivers. The WDM architecture does not support drivers for non-Windows NT-based operating systems (such as Windows 98), and you should rewrite such drivers.

This section is divided into three parts:

Windows Driver Model describes the Windows Driver Model (WDM), including types of WDM drivers, device configuration, and WDM versioning.

Device Objects and Device Stacks describes device objects and device stacks. The section includes information about physical device objects (PDOs), functional device objects (FDOs), and filter device objects (filter DOs). Drivers are often built from a set of device objects that work together. This set of device objects is called a stack. Stacks can help you understand the flow of information to and from a driver and how different parts of the driver communicate internally.

Kernel-Mode Driver Components describes which routines you must implement to have a functional driver and which routines are optional.

A device driver is a set of software code that must integrate into the operating system. To complete this integration, you must write a set of handler routines in your driver that process calls from the operating system. These routines can be simple function calls, but many of them implement the processing of I/O request packets (IRPs), which facilitate communication between drivers and the operating system.

NoteВ В WDM drivers can also use the Windows Driver Frameworks (WDF) library to make some parts of a device driver easier to write. Specifically, kernel-mode drivers can use the Kernel-Mode Driver Framework (KMDF), which is part of WDF. For more information about KMDF for kernel-mode drivers, see Kernel-Mode Driver Framework Overview. Note that KMDF does not replace WDM. You must still understand many parts of WDM to write a KMDF driver.

WDM Audio Terminology

This section describes the differences in terminology between the Microsoft Windows Driver Model (WDM) audio driver architecture and the generic Windows layered driver architecture. The generic driver architecture is exemplified by SCSI port/miniport drivers (see Storage Driver Architecture).

The terms defined by the generic and WDM audio driver architectures are similar, but they do have some important differences, as described below.

Miniport Driver (Generic)

The miniport driver (generic) is the hardware-specific driver for an adapter that resides on a system bus (for example, PCI or ISA). This driver has a single entry point, DriverEntry, and registers a table of functions with a port driver. This table of functions serves as the miniport driver’s upper-edge interface.

The miniport driver sits below the port driver in the driver stack. That is, all calls to the miniport driver are made from the port driver and all calls out of the miniport driver are to the port driver’s lower-edge interface.

The following figure illustrates the meaning of the terms stack, upper-edge interface, and lower-edge interface as they are used in this context. The block representing the port driver is stacked on top of the block representing the miniport driver. Hence, the miniport driver sits below the port driver in the «stack».

The port and miniport drivers communicate through the software interfaces that they expose to each other. In the preceding figure, these interfaces are associated with the lower-edge of the block representing the port driver and the upper-edge of the block representing the miniport driver. This representation is the source of the terms «lower-edge interface» and «upper-edge interface».

Port Driver (Generic)

The port driver (generic) surrounds a miniport driver.

The port driver:

Implements WDM streaming filters.

Provides a common interface to the rest of the operating system.

Handles I/O requests from the system and recasts these requests as calls into the miniport driver’s function table.

Provides the miniport driver with a library of support functions (the port driver’s lower-edge interface).

The port driver hides many of the details of the operating system from the miniport driver, and the miniport driver hides the specifics of the underlying hardware from the port driver. The implementation of the port driver might undergo changes for different operating system releases, but the port driver’s interface to the miniport driver remains more-or-less unchanged, enabling the miniport driver to be largely platform-independent.

Minidriver (Generic)

The minidriver (generic) represents a hardware component on a bus. The minidriver uses the bus driver to communicate to the physical device over the bus, and it binds together the bus driver and one or more class drivers.

Class drivers help the minidriver present the physical device to clients as a type of logical device. In WDM environments, a minidriver typically receives requests in IRP form from class drivers, and sends requests in IRP form to a bus driver.

A minidriver might also have to communicate with several class drivers. An example of a minidriver that binds to multiple class drivers is a minidriver for a CD-ROM drive on an IEEE 1394 bus. It might bind to a file-system driver so that the drive can be accessed from the file system. However, it also binds to a Redbook system driver so that audio can be streamed from CDs.

Bus Driver (Generic)

The bus driver (generic) gives minidrivers access to a physical bus. The Microsoft Windows hardware abstraction layer (HAL) is sometimes referred to as the system bus driver because it provides access to the system bus. For more information, see Bus Drivers.

Class Driver (Generic)

The class driver (generic) implements behavior that is common across a class of similar devices.

The class driver:

Eliminates duplication of functionality in hardware-specific drivers.

Is not bus-specific.

Is not aware of resource issues (for example, DMA and interrupts).

Miniport Driver (WDM Audio)

The miniport driver (WDM audio) implements a function-specific interface for a function on an audio adapter card that resides on a system bus. A miniport driver is a component of an adapter driver. It is not recognized as a driver by the operating system. In this regard, an audio miniport driver differs from a generic miniport driver.

Unlike generic miniport drivers, audio miniport drivers do not implement DriverEntry, are not registered, and do not rely entirely on their respective port drivers for support. Multiple audio miniport drivers that address multiple functions can be linked into a single adapter driver (and associated with a single device object).

Adapter Driver (WDM Audio)

The adapter driver (WDM audio) serves as a container for all miniport drivers associated with a given adapter. This adapter driver is recognized as a driver by the operating system and is contained in its own .sys file.

The audio adapter driver consists of a set of miniport drivers and additional code that addresses initialization issues. For example, an adapter driver implements a DriverEntry entry point.

Port Driver (WDM Audio)

The port driver (WDM audio) implements a KS filter on behalf of a miniport driver and operates in the context of a port class driver. The port driver exposes the miniport driver’s function-specific code as a KS filter to the system and is responsible for implementing adapter-independent functionality.

Unlike the generic port driver, the audio port driver shares the device object and is, therefore, instantiated differently. An audio port driver is also more closely resembles a generic class driver than it does a generic port driver in that it implements behavior that is expected of a class of devices (it is not bus-independent).

Port Class Driver (WDM Audio)

The port class driver (WDM audio) serves as a container for a collection of port drivers, each of which provides support for a different type of audio hardware function. The following figure shows the relationships between the audio port class and adapter drivers.

An adapter driver manages an adapter card that might contain several different hardware functions. As shown in the preceding figure, the adapter driver contains a miniport driver to manage each type of hardware function. Similarly, the port class driver is designed to provide support to adapter cards with multiple hardware functions. The port class driver provides a port driver for each of the well defined function types that it supports. The adapter driver binds its miniport driver for a particular function to the corresponding port driver for that function type. The port driver for each function handles communication with the WDM audio clients that use the function. The miniport driver contains all of the hardware-specific code for managing that function.

The port class driver (WDM audio) primarily functions as a container for multiple subdevices that are associated with a single device object. Bus drivers create a single physical device object (PDO) for each Plug and Play (PnP) node they enumerate.

In the case of an audio adapter, a single PnP node frequently contains multiple audio functions. To expose the various functions associated with a node as distinct devices typically requires writing a bus driver for the adapter. The bus driver enumerates the hardware functions and creates corresponding PDOs. In this scenario, one or more function-specific drivers need to bind to the PDOs and negotiate with the bus driver for access to shared resources on the adapter.

The port class driver uses the kernel streaming driver’s ability to expose various aspects of a single device object in order that the operating system recognizes the device as a set of distinct subdevices.

A reference string is appended to the device name to specify the desired subdevice. The kernel streaming driver dispatches creation IRPs based on this reference string. After a file object is created, the kernel streaming driver provides dispatching of IRPs that are targeted at the file object that represents the subdevice. In addition, the port class driver implements a COM-based model for packaging subdevices.

An adapter driver instantiates a port driver and a miniport driver and binds them together by passing a pointer to the miniport driver as a parameter to the port driver’s initialization function (see the code example in Subdevice Creation). The resulting port/miniport driver stack constitutes a KS filter that represents one of the subdevice types that the port class driver supports.

The port class driver’s PcRegisterSubdevice function registers the subdevice, which is perceived as a device by the rest of the system. The port driver receives creation IRPs targeted at the device object, but for only those IRPs that are specified by the reference string under which the subdevice is registered. The port driver also receives the IRPs targeted at the file objects that are associated with the subdevice. The port driver is responsible for the subdevice’s behavior as a KS filter and for communicating appropriately with the miniport driver.

For more information about designing drivers for multifunction audio cards, see Multifunction Audio Devices.

WDM Audio Drivers Overview

Windows Driver Model (WDM) audio drivers make use of the kernel streaming (KS) components, which operate in kernel mode and are part of the operating system.

Hardware vendors should make several design decisions before beginning development of a Windows-based audio hardware device.

The first decision is whether to design an audio device that requires a vendor-supplied custom driver. Windows contains operating-system support for PCI, USB, and IEEE 1394 devices that conform to the Microsoft Universal Audio Architecture (UAA) guidelines. The vendor does not need to provide a custom driver for a UAA-compatible audio device.

However, if a vendor-supplied custom audio driver is necessary, the vendor must choose whether the driver should be designed to work in conjunction with the PortCls system driver (Portcls.sys) or the AVStream class system driver (Ks.sys). Both PortCls and AVStream are part of the Windows operating system. PortCls is the correct choice for most audio adapters. For more information about PortCls, see Introduction to Port Class. For more information about AVStream, see AVStream Overview.

When designing a custom adapter driver that uses PortCls, the devices on the audio adapter are made available to applications using WaveRT. For more information, see Introducing the WaveRT Port Driver.

Two additional decisions involve how to present the adapter topology and pin data ranges to audio applications. The topology is a logical map of the data paths and control nodes in the adapter circuitry. The data ranges specify the data formats that the devices can support in their wave and MIDI streams. Both decisions affect how the devices on the audio adapter appear to applications.

In making all of the previously mentioned decisions, the hardware vendor must weigh the value of performance enhancements against the cost of implementing them. Another consideration is whether a particular solution can be made to work on a number of products in the Windows family. This section provides an overview of these issues as well as references to more detailed documentation about specific topics.

This section includes the following topics:

Windows Driver Model

In computing, the Windows Driver Model (WDM) — also known (somewhat misleadingly) at one point as the Win32 Driver Model — is a framework for device drivers that was introduced with Windows 98 and Windows 2000 to replace VxD, which was used on older versions of Windows such as Windows 95 and Windows 3.1, as well as the Windows NT Driver Model.

Contents

Overview

WDM drivers are layered in a complex hierarchy and communicate with each other via I/O request packets (IRPs). The Microsoft Windows Driver Model defined a unified driver model for the Windows 98 and Windows 2000 line by standardizing requirements and reducing the amount of code that needed to be written. WDM drivers will not run on operating systems earlier than Windows 98 or Windows 2000, such as Windows 95, Windows NT 4.0 and Windows 3.1. By conforming to WDM, drivers can be binary compatible and source compatible across Windows 98, Windows 98 Second Edition, Windows Me, Windows 2000, Windows XP, Windows Server 2003 and Windows Vista (for backwards compatibility) on x86-based computers. WDM is designed to be backward-compatible. That is, a version of WDM will be compatible with drivers written for earlier WDM versions. Such WDM drivers will not be able to take advantage of new operating system services, but they will still load and run. WDM is generally not forward-compatible. WDM will most likely fail to load drivers written for a newer version. For example, the WDM in Windows XP will load drivers written for Windows 2000, but will not apply new WDM features that were introduced in Windows XP. The WDM in Windows 2000 will not load a driver written for Windows XP.

WDM exists in the intermediary layer of Windows 2000 kernel-mode drivers and was introduced to increase the functionality and ease of writing drivers for Windows. Although WDM was mainly designed to be binary and source compatible between Windows 98 and Windows 2000, this may not always be desired and so specific drivers can be developed for either operating system. WDM drivers can be classified into the following types and sub-types:

Device Function Drivers

A function driver is the main driver for a device. A function driver is typically written by the device vendor and is required (unless the device is being used in raw mode). A function driver can service one or more devices.

• Class drivers: These are a type of function drivers and can be thought of as built-in framework drivers that miniport and other class drivers can be built on top of. The class drivers provide interfaces between different levels of the WDM architecture. Common functionality between different classes of drivers can be written into the class driver and used by other class and miniport drivers. The lower edge of the class driver will have its interface exposed to the miniport driver, while the upper edge of top level class drivers is operating system specific. Class drivers can be dynamically loaded and unloaded at will. They can do class specific functions that are not hardware or bus-specific (with the exception of bus-type class drivers) and in fact sometimes only do class specific functions like enumeration.
• Miniport drivers: These are also function drivers for USB, Audio, SCSI and network adapters. They should usually be source and binary compatible between Windows 98 and Windows 2000 and are hardware specific but control access to the hardware through a specific bus class driver.

Bus drivers

A bus driver services a bus controller, adapter, or bridge. Microsoft provides bus drivers for most common buses, such as PCI, PnPISA, SCSI, USB and FireWire. Each software vendor can create their own bus drivers if needed. A bus driver can service more than one bus if there is more than one bus of the same type on the machine.

Filter drivers

Filter drivers are optional drivers that add value to or modify the behavior of a device and may be non-device drivers. A filter driver can also service one or more devices. Upper level filter drivers sit above the primary driver for the device (the function driver), while lower level filter drivers sit below the function driver and above the bus driver.

• Driver service: This is a type of kernel-level filter driver implemented as a Windows service that enables applications to work with devices.

VxD, WDM and Windows 98

Windows 98 based operating systems (Windows 98, Windows 98 Second Edition, and Windows Me) are able to use both WDM and VxD (Virtual device driver) driver standards. Both drivers models can provide unique and different features for the same hardware. However, usually the newer WDM standard provides more features. For example, if a TV tuner card using a VxD driver is able to capture images at a resolution of 384 x 288 pixels, the same TV Tuner card with the WDM driver model may be able to capture at a resolution of 768 x 576 pixels. This can be attributed to the new Broadcast Driver Architecture model which is part of WDM.

Critisism

The Windows Driver Model, while a significant improvement over the VxD and Windows NT driver model used before it, has been criticised by driver software developers , most significantly for the following:

WDM has a very steep learning curve. Interactions with power management events and Plug-and-play are difficult. This leads to a variety of situations where Windows machines cannot go to sleep or wake up correctly due to bugs in driver code. I/O cancellation is almost impossible to get right. Thousands of lines of support code are required for every driver. No support for writing pure user-mode drivers. There were also a number of concerns about the quality of documentation and samples that Microsoft provided.

Because of these issues, Microsoft has released a new framework to replace WDM, called the Windows Driver Foundation, which includes Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF). Windows Vista supports both WDM and the newer Windows Driver Foundation. KMDF is also available for download for Windows XP and even Windows 2000, while UMDF is available for Windows XP.