Architecture of the User-Mode Driver Framework - 1

Architecture of the User Mode Driver Framework

Version 1.0 February 21, 2007

Abstract

The Microsoft® Windows® Driver Foundation (WDF) includes frameworks to support the development of both user-mode and kernel-mode drivers. The user-mode driver framework (UMDF) enables drivers for some types of devices to run in user mode instead of kernel mode. This paper describes the architecture of the user-mode driver framework and how drivers interact with the framework to service their devices.

This information applies for the following operating systems:
Windows Vista™
Microsoft Windows XP

The current version of this paper is maintained on the Web at:

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

Contents

Introduction

Devices Supported in User Mode

Overview of the UMDF Driver Model

UMDF Object Model

UMDF Objects

Driver Callback Interfaces

UMDF Driver Features

Impersonation

Device Property Store

I/O Request Flow

I/O Request Dispatching

Create, Cleanup, and Close Requests

Create, Cleanup, and Close in a Filter Driver

Create, Cleanup, and Close in a Function Driver

Create, Read, Write, and Device I/O Control Requests

I/O Queues

Dispatch Type

Queues and Power Management

I/O Request Objects

Retrieving Buffers from I/O Requests

Sending I/O Requests to an I/O Target

Creating Buffers for I/O Requests

Canceled and Suspended Requests

Request Cancellation

Request Suspension

Completing I/O Requests

Adaptive Time-outs

Self-Managed I/O

Synchronization Issues

Synchronization Model

Locks

Plug and Play and Power Management Notification

Device Enumeration and Startup

Device Power-Down and Removal

Surprise Removal Sequence

Build, Test, and Debug

Installation and Configuration

Versioning and Updates

Resources

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.

© 2007 Microsoft Corporation. All rights reserved.

Microsoft, MSDN, Win32, Windows, 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 Microsoft® Windows® Driver Foundation (WDF), contains a framework for the creation of user-mode drivers. The user-mode driver framework (UMDF) is designed to support protocol device classes such as cameras and portable music players. It integrates the installation and management of these devices with standard operating system facilities, such as I/O and Plug and Play and power management.

UMDF is based on the same conceptual driver programming model as the kernel-mode driver framework (KMDF) that is also part of WDF. However, the two frameworks implement the model with different components, device-driver interfaces (DDIs), and data structures. KMDF includes some objects that are available only in kernel mode, and UMDF includes some objects that are available only in user mode.

Like KMDF, UMDF provides intelligent defaults, so that driver developers can focus on their device hardware and avoid writing code to perform many common driver tasks. Instead, that code is built into the framework, thus making vendor-written drivers smaller, ensuring greater code reuse and providing for global bug fixes by Microsoft.

This paper describes the architecture and features of UMDF and outlines the requirements for drivers that use UMDF (sometimes called UMDF-based drivers or simply UMDF drivers). It assumes basic familiarity with the Windows operating system and I/O model.

Devices Supported in User Mode

UMDF supports the development of drivers for protocol-based or serial bus–based devices, such as Universal Serial Bus (USB) devices and network-connected devices. For example, drivers for the following types of devices can be written in user mode:

  • Portable storage devices, such as personal digital assistants (PDAs) and cell phones
  • Portable media players
  • USB bulk transfer devices
  • Auxiliary display devices

The device can be directly connected, connected on the network, or connected via a wireless protocol such as Bluetooth. UMDF also supports software-only drivers.

The initial UMDF release includes the following sample UMDF drivers:

  • Skeleton, a minimal driver that is intended for use as a template for driver development
  • Echo, a simple software-only driver that shows the use of a serial I/O queue
  • USB/FX2_Driver and USB/Echo_driver, which are function drivers for the USB-FX2 board that was designed by OSR
  • USB/Filter, which is a filter driver for the USB-FX2 device stack

User-mode drivers can support 32-bit or 64-bit devices for any Windows hardware platform and can be distributed on Windows Update. UMDF is currently supported for Windows Vista™ and Windows XP.

Drivers that require the following cannot be written as UMDF drivers; they must be written as kernel-mode drivers:

  • Handling interrupts
  • Direct access to the hardware, such as direct memory access (DMA)
  • Strict timing loops
  • Use of nonpaged pool or other resources that are reserved for kernel mode

In addition, a UMDF driver cannot be a client of the Windows kernel or of a kernel-mode driver.

Overview of the UMDF Driver Model

A UMDF driver runs in a driver host process that also hosts UMDF and a run-time environment. Each such driver operates as part of a stack of drivers that manage a device. The user-mode drivers are loaded above the kernel-mode drivers at the top of the stack. Because user-mode components do not have access to the system address space where the system and kernel-mode drivers maintain I/O requests and other shared data, the UMDF architecture includes components that communicate between kernel mode and user mode.

Figure 1 shows the overall architecture of the UMDF driver model.

Figure 1. UMDF Driver Architecture

Figure 1 shows two device stacks that service two different devices. Each device stack includes a UMDF driver that runs in its own driver host process. The figure includes the following components, described according to the typical flow of an I/O request:

Applications. The applications are clients of the drivers. These applications are user-mode processes that issue I/O requests through the Microsoft Win32® File I/O API. The Win32 functions call I/O routines in the Windows kernel.

Windows kernel. The Windows kernel creates I/O request packets (IRPs) to represent the user-mode I/O requests and forwards them to the top of the kernel-mode device stack for the target device.

Reflector. The reflector is a kernel-mode WDM filter driver that is installed at the top of the kernel-mode device stack for each device that a UMDF driver manages. The reflector manages communication between the kernel-mode components and the user-mode driver host process. The reflector forwards I/O, power, and Plug and Play messages from the operating system to the driver host process, so that user-mode drivers can respond to I/O requests and participate in Plug and Play device installation, enumeration, and management. The reflector also monitors the driver host process to ensure that it responds properly to messages and completes critical operations in a timely manner, thus helping to prevent driver and application hangs. Microsoft provides the reflector.

Driver manager. The driver manager creates and shuts down the driver host processes and maintains status information about them. It also responds to messages from the reflector. The driver manager runs as a Windows service and is started during installation of the first device that has a UMDF driver. One instance of the driver manager handles all of the driver host processes. The driver manager must be running all of the time that any device controlled by a UMDF driver is installed on the system. Microsoft provides the driver manager.

Host process. The host process is the process in which the user-mode driver runs. It is separate from the application process and the driver manager. It runs in the security credentials of a LocalService account, although it is not a Windows service. The host process contains the user-mode device stack for the device. The device stack is visible to all applications across the system. Each instance of a device has its own device stack. Currently, each instance has a separate driver host process, too.

The host process includes the following components:

  • The UMDF driver is an in-process component object model (COM) component that controls the hardware from user mode. An independent hardware vendor (IHV) supplies the UMDF driver.
  • The framework exposes the user-mode DDI, which is a dynamic-link library (DLL) of COM-style objects that support the presentation, flow, and management of I/O, power, and Plug and Play requests to the driver.
  • The run-time environment dispatches I/O requests, loads the driver, constructs and destroys the user-mode device stack, manages a user-mode thread pool, and handles messages from the reflector and the driver manager.

The host process is a child process of the driver manager.

Kernel-mode drivers. Additional kernel-mode drivers can service each device. Either Microsoft or an IHV can supply these drivers.

UMDF Object Model

UMDF drivers are object oriented and event driven. The driver and the framework create instances of objects that are required to support the driver’s device. The driver implements event callback interfaces to handle events that affect these objects.

The objects and interfaces are based on the COM programming pattern. UMDF uses only a small subset of COM, specifically the COM lifetime model; it does not depend on the entire COM infrastructure and run-time library. The UMDF run-time environment loads the driver by reading information that is stored in the registry under the WDF service key.

UMDF uses only the query-interface and reference-counting features of COM. Every UMDF interface derives from IUnknown and therefore supports the QueryInterface, AddRef, and Release methods by default. The AddRef and Release methods manage object lifetime. The QueryInterface method enables other components to determine which interfaces the driver supports.

UMDF Objects

UMDF manages a series of objects that are exposed to the user-mode driver. UMDF creates some of these objects in response to application-triggered actions, such as an I/O request; the driver creates other objects by calling methods on UMDF interfaces.

For each type of object, UMDF defines one or more interfaces through which to manipulate instances of the object. The interfaces provide methods and properties. Methods define actions that can be taken on behalf of the object and return a status to indicate whether they succeeded or failed. Property operations set and get the attributes of the object and cannot fail. Some interfaces are implemented by UMDF, and others are implemented by the driver.

Table 1 lists all the UMDF object types and the interfaces that UMDF implements on each type.

Table 1. UMDF Object Types

Type of object / Interfaces / Description
Base object / IWDFObject / Exposes a base object for use as the driver requires.
Device / IWDFDevice / Exposes an instance of a device object. A driver typically has one device object for each device that it controls.
Driver / IWDFDriver / Exposes the driver object itself. Every driver has one driver object.
File / IWDFFile / Exposes a framework file object that was opened by the Win32 CreateFile function, through which applications can access the device.
IWDFDriverCreatedFile / Exposes a framework file object that the driver created.
I/O queue / IWDFIoQueue / Exposes an I/O queue, which controls the flow of I/O in the driver. A driver can have any number of I/O queues.
I/O request / IWDFIoRequest / Exposes a request for device I/O.
I/O target / IWDFIoTarget / Represents the next-lower driver in the device stack, to which the driver sends I/O requests.
Memory / IWDFMemory / Exposes memory that the driver uses, typically an input or output buffer that is associated with an I/O request.
USB device / IWDFUsbTargetDevice / Exposes a USB device object that is an I/O target. Inherits from IWdfIoTarget.
USB interface / IWDFUsbInterface / Exposes an interface on a USB device.
USB pipe / IWDFUsbTargetPipe / Exposes a USB pipe that is an I/O target. Inherits from IWdfIoTarget.

As the table shows, the UMDF-implemented interfaces are named IWDFXxx. The driver calls methods on these interfaces to perform operations on its objects. For example, UMDF implements the IWDFIoRequest interface, and the driver calls methods in this interface to retrieve the parameters for the I/O request.

For the driver, devices, and queues, both the framework and the driver maintain objects. The driver-created objects are callback objects, on which the driver implements the callback interfaces that are required to service its device. A driver has one driver callback object, one device callback object for each device that it supports, and one queue callback object for each queue that it creates. The callback objects serve as the “context memory” for the driver.

Driver Callback Interfaces

The driver implements callback interfaces to provide device-specific responses to events. Each callback interface is implemented on a specific object type. For example, Plug and Play callback interfaces (IPnpCallback, IPnpCallbackHardware, and IPnpCallbackSelfManagedIo) are implemented for device objects, and I/O queue callback interfaces (IQueueCallbackCreate, IQueueCallbackRead, and so forth) are implemented on I/O queue objects.

When a Plug and Play, power management, or I/O request arrives, UMDF calls methods in the driver’s callback interfaces to handle the associated events. For example, when UMDF receives a read request, it calls methods in the driver’s IQueueCallbackRead interface.

A driver implements callback interfaces only for the events that are important to its operation. When the event occurs for an object, the framework invokes the callback for that object. For example, the unexpected removal of a device is a Plug and Play event. If a device can be removed unexpectedly, its driver should implement the IPnpCallback interface (which includes the OnSurpriseRemoval method) to perform device-specific operations upon ejection. When the Plug and Play manager sends a surprise-removal notification for the device, UMDF calls the OnSurpriseRemoval method with a pointer to the IWDFDevice interface for the device that has been removed.

For most events, a driver can either provide a callback interface or allow UMDF to perform a default action in response. For a few events, however, a driver-specific callback is required. For example, adding a device is an event for which every Plug and Play driver must include a callback. The driver object’s IDriverEntry::OnDeviceAdd callback creates the device object.

The names of the driver-implemented callback interfaces are generally in the form IObjectAction, where Object identifies the object to which the interface applies and Action indicates what the interface does. For example, the IQueueCallbackRead interface is implemented for I/O queues and contains methods called when a queue receives a read request.