Porting a Driver from WDM to KMDF

Porting a Driver from WDM to KMDF - 54

Porting a Driver from WDM toKMDF

September 12, 2006

Abstract

This paper provides information about how to port drivers that conform to the Microsoft® Windows® Driver Model (WDM) to use the kernel-mode driver framework (KMDF) of the Windows Driver Foundation (WDF) for the Microsoft Windows family of operating systems. It assumes that readers are experienced with WDM and acquainted with KMDF. A companion to this paper titled Summary of KMDF and WDM Equivalents provides tables that compare specific aspects of the two models.

This information applies for the following operating systems:
Microsoft Windows Vista™
Microsoft Windows Server® 2003
Microsoft Windows XP
Microsoft Windows 2000

The current version of this paper is maintained on the Web at:
http://www.microsoft.com/whdc/driver/wdf/WDF_Port.mspx

References and resources discussed here are listed at the end of this paper.

Contents

Introduction 4

Which Drivers Can Be Ported 5

Why to Port a Driver 6

Differences between WDM and KMDF 7

Driver Structure 8

Device Objects and Driver Roles 8

Object Model 9

Object Creation 10

Object Context Area 11

Object Lifetime and Deletion 12

Supported IRP Types 13

I/O Queues 14

I/O Targets 15

Synchronization and Concurrency 15

Driver Installation 17

Strategies for Porting 17

WDM Driver Analysis 17

Steps in Porting 18

DriverEntry Routine 19

EvtDriverDeviceAdd Callback 19

WDFDEVICE_INIT Structure 20

Initialization for an FDO 21

Initialization for a Filter DO 21

Device Object Context Area 21

Device Object Creation 23

Additional EvtDriverDeviceAdd Tasks 23

Child Device Enumeration (PDOs Only) 23

Static and Dynamic Enumeration 23

PDO-Specific Initialization 24

Plug and Play and Power Management 25

Power Policy Ownership 25

Event Callbacks for Plug and Play and Power IRPs 26

Device Enumeration and Power-Up 27

Power-up Sequence for a Function or Filter Device Object 27

Power-Up Sequence for a Physical Device Object 29

Device Power-Down and Removal 30

Power-Down and Removal Sequence for a Function or Filter Device Object 31

Power-Down and Removal Sequence for a Physical Device Object 32

Surprise-Removal Sequence 33

Interrupts 34

I/O Queues and I/O Requests 35

Create I/O Queues 35

Port I/O Dispatch Routines to I/O Event Callback Functions 37

Parameters for I/O Requests 37

Access to Buffers for Buffered and Direct I/O 37

Create Requests 38

Read Requests 39

Write Requests 39

Device I/O Control Requests 40

Internal Device I/O Control Requests 41

Access to Buffers for Neither I/O 41

Complete a Request 44

Handle a Canceled Request 44

Forward a Request to the Next Lower Driver 45

Issue an I/O Request 46

DMA Support 48

WMI Support 49

Timers, DPCs, and Work Items 50

Requests that KMDF Does Not Support 51

Installation Procedure 52

General Guidelines for Porting 53

Resources 53

Disclaimer

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

© 2006 Microsoft Corporation. All rights reserved.

Microsoft, Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Introduction

The kernel-mode driver framework (KMDF) component of the Microsoft® Windows® Driver Foundation (WDF) provides an infrastructure for developing kernel-mode drivers. It is layered on top of the Windows Driver Model (WDM) and implements code to handle many common driver requirements. In essence, the framework is a skeletal device driver that can be customized for specific devices.

Architecturally, KMDF drivers are similar to WDM drivers. A WDM driver consists of a DriverEntry function, various dispatch routines that the operating system calls to service I/O requests, and additional driver-specific utility functions. A KMDF driver consists of a DriverEntry function, various event callback functions that the framework calls to service I/O requests, and additional driver-specific utility functions.

However, within this broad structure, the two models have important differences:

·  Dispatch routines and event callback functions. In the WDM model, each dispatch routine corresponds to a major I/O request packet (IRP) code. IRP codes identify Plug and Play, power management, and Windows Management Instrumentation (WMI) requests in addition to requests for actual device I/O. The driver must determine how to handle each IRP that is based on the current state of the device, driver, and operating system. The driver must therefore maintain information about its own state and that of its device and the system as a whole.

In the WDF model, a driver implements event callback functions that map to driver-oriented and device-oriented tasks rather than to broad IRP codes. The framework tracks system, driver, and device state, interprets the request that each IRP represents, and calls a state-specific event callback. Thus, the driver handles only requests that are pertinent to its device and is not required to maintain extensive state information.

·  Interaction with the operating system. WDM drivers must call the operating system directly to handle many common tasks, whereas KMDF drivers can usually call the framework instead. The framework calls the underlying operating system functions after validating all parameters and verifying that the driver is running at the correct interrupt request level (IRQL) to make the call.

The framework implements much of the infrastructure that most drivers require to manage queues, synchronization, and cancellation. In most cases, WDM drivers must manage such features on their own.

Most kernel-mode WDM drivers can be ported to use KMDF. This paper provides information about porting such drivers, including:

·  Which drivers can be ported

·  Advantages of porting

·  Differences between the WDM and KMDF models

·  Details about porting driver code from WDM to KMDF

·  Required revisions to the existing driver’s INF to install the KMDF driver

Readers of this paper should have experience with WDM drivers and be familiar with the architecture of KMDF. For pointers to more information, see "Resources" at the end of this paper.

In addition, see the companion document titled Summary of KMDF and WDM Equivalents for a set of tables that show the corresponding KMDF and WDM object types, KMDF event callback functions and WDM driver-supplied routines, and the KMDF methods and their WDM equivalents.

Which Drivers Can Be Ported

Whether a particular driver can be ported to WDF depends on:

·  The operating system versions on which the driver must run

·  The type of device that the driver supports

·  Which driver model the driver uses

KMDF can be used to create drivers that will run on Microsoft Windows 2000 and later versions of the operating system.

Table 1 summarizes the device and driver types that KMDF supports.

Table 1. Device and Driver Types Supported by KMDF

Device or driver type / Previous driver model /
Control and non-Plug and Play drivers / Legacy
Human interface device (HID) drivers / HID miniport (WDM-based)
IEEE 1394 client drivers1 / Depends on device class
ISA, PCI, PCMCIA, and secure digital (SD) devices2 / WDM
Network Driver Interface Specification (NDIS) protocol drivers / WDM upper edge and NDIS lower edge
NDIS WDM drivers / NDIS upper edge and WDM lower edge
SoftModem drivers / WDM with upper-edge support for Telephony Application Programming Interface (TAPI) interface
Storage class drivers and filter drivers / WDM
Transport driver interface (TDI) client drivers / WDM
USB client drivers / Depends on device class
Winsock client drivers / WDM with a callback interface for device-specific requests

1 Supported for devices that do not conform to existing device class specifications.
2 Supported, if device class or port drivers do not provide the driver dispatch functions.

In general, KMDF can be used to write drivers that conform to WDM, supply entry points for the major I/O dispatch routines, and handle IRPs. For some device types, the device class and port drivers supply driver dispatch functions and call a miniport driver to handle specific I/O details. Such miniport drivers are essentially callback libraries and are not currently supported by KMDF. In addition, KMDF does not support device types that use Windows image acquisition (WIA).

However, a minidriver that is based on a driver model in which the minidriver communicates with other drivers by using WDM interfaces can be ported. For example, the Ndisedge sample drivers that are provided with KMDF show how to use KMDF to implement the WDM lower edge.

Except for drivers that support printers and a few other device types, most Windows drivers run in kernel mode. By using WDF, however, certain additional drivers can run in user mode. If a driver does not service interrupts, perform direct memory access (DMA), require kernel-mode resources such as the nonpaged pool, or act as the client of a kernel-mode driver, consider rewriting it to run in user mode, by using the user-mode driver framework (UMDF). This paper does not cover user-mode driver implementation. For information about UMDF, see the white paper titled Architecture of the User-Mode Driver Framework, which is listed in "Resources" at the end of this paper.

Why to Port a Driver

If already have a WDM driver, you might wonder why to even consider porting it to KMDF. You have already spent hours learning the intricacies of the WDM model and mastering dozens of rules for handling Plug and Play and power IRPs. Your driver works. Or does it? Are you certain your driver handles all these tasks correctly?

Here are a few advantages of porting a driver to KMDF.

KMDF Drivers Are Simpler and Easier to Maintain. KMDF defines an object-based, event-based driver model. A driver instantiates the KMDF objects that it requires and implements callback functions that respond to specific events. The often complex logic that determines when to invoke the callback functions—particularly for Plug and Play and power management—resides within KMDF.

The KMDF model results in drivers that are more concise and thus much simpler and easier to debug than WDM drivers. KMDF drivers require minimal common code for default operations because most such code resides in the framework, where it has been thoroughly tested and can be globally updated.

Because KMDF event callbacks are clearly and narrowly defined, KMDF-based drivers typically require little code complexity. Each driver event callback routine is designed to perform a specific task. Therefore, compared to WDM drivers, KMDF-based drivers have fewer lines of code and a minimal number of state variables and locks.

As part of the KMDF development effort, Microsoft has converted many of the sample drivers that are shipped with the Windows Driver Kit (WDK) from WDM to KMDF. Without exception, the KMDF drivers are smaller and less complex.

Table 2 shows "before-and-after" statistics for the PCIDRV, Serial, and OSRUSBFX2 drivers.

Table 2. Statistics for Sample WDM and KMDF Drivers

Statistic / PCIDRV1 / Serial2 / OSRUSBFX23 /
WDM / KMDF / WDM / KMDF / WDM / KMDF
Total lines of code / 13,147 / 7,271 / 24,000 / 17,000 / 16,350 / 2,300
Lines of code required for Plug and Play and power management / 7,991 / 1,795 / 5,000 / 2,500 / 8,700 / 742
Locks and synchronization primitives / 8 / 3 / 10 / 0 / 9 / 0
State variables required for Plug and Play and power management / 30 / 0 / 53 / 0 / 21 / 0

1 The PCIDRV sample supports the Intel E100B NIC card. The WDM and KMDF versions are functionally equivalent.

2 The Serial sample supports a serial device. In this case, the WDM sample supports a multiport device, but the KMDF sample supports only a single port. However, the statistics for the WDM driver do not include code, locks, or variables that are required solely to support multiport devices, so the statistics are comparable.

3 The OSRUSBFX2 sample supports the USB-FX2 board built by OSR. The WDM and KMDF versions are functionally equivalent. The WDM version is available at http://www.osronline.com.

As the table shows, converting these drivers from WDM to KMDF resulted in significant reductions in code size—particularly for Plug and Play and power management. The KMDF samples also require fewer locks and synchronization primitives and state variables.

KMDF Has Built-in Support for Bus and Filter Drivers. A KMDF driver indicates whether it is a bus, function, or filter driver for a particular device. According to the settings that the driver makes and the callbacks that it implements, KMDF invokes the appropriate callbacks at the right times and handles the correct IRPs. The framework calls the driver only for those I/O requests that the driver handles and provides default handling for any other requests.

KMDF Manages Most Interactions with the Operating System. A KMDF driver dynamically links at run time with the framework, which handles many interactions with the operating system. The framework intercepts IRPs that are directed to the driver and handles them by applying defaults and invoking driver callbacks as required. As a result, most of the complicated code to interact with the operating system is implemented in the framework instead of in the driver.