Writing WDF Drivers I: Core Concepts

Overview

The Windows Driver Foundation (WDF) is the modern standard for creating Windows drivers, and is the preferred way to implement most new drivers for Windows.  WDF enables developers to write drivers that execute in either kernel-mode using the Kernel Mode Driver Framework (KMDF) or user-mode using the User Mode Driver Framework V2 (UMDF V2).

The goal of this seminar is to help engineers learn both the fundamental and practical details of KMDF and UMDF V2. This includes both basic architectural information about Windows and the Windows I/O Subsystem as it relates to WDF, plus the specific details of how to write, test, diagnose, and support drivers using KMDF and UMDF V2.

The seminar focuses specifically on KMDF and UMDF V2 software drivers, filter drivers, drivers for USB devices, as well as drivers for programmed I/O type devices (interfaced via either PCI-family or motherboard-based buses).  The basics of writing KMDF client drivers for SoC/IoT-type environments and low-power devices such as that connect via GPIO, I2C, and SPI are also discussed (though this topic is not covered in detail).

The seminar takes a unique approach to the topics presented:  Key architectural details are described first, and then those details are made concrete and accessible via presentation of task-based practical implementation steps.  Finally, larger groups of architectural and implementation concepts are collected and made directly useful though the review and discussion of several carefully chosen case studies.

Hardware Included: If you’re interested in writing drivers for USB devices, you’ll be pleased to know that we include the OSR USB FX2 Learning Kit hardware with the seminar. With this custom-designed USB device, you’ll be able to do the optional, USB-specific, lab exercises.

This is the most recent version of the seminar that we’ve been teaching on-campus to Microsoft’s own internal software development and test engineers for the last ten years.

Details

Length: 5 days

Format: Lecture with Optional Lab Exercises ONLINE ONLY

Cost: $4,455 (when paid 6 weeks in advance; $4,950 otherwise)

Other Applicable Discounts:
5% multi-student discount (paid online, same credit card, same order)
Contact OSR for previous student discounts

Current Schedule

ONLINE (content live-streamed via the Internet)
10-14 March 2025

9:00AM – 5:00PM EDT (UTC-0400)

(Click Register Now to register and pay via credit card; OR Register Offline Here)

Target Audience

This seminar is designed for engineers who need to understand how to design, develop, and test Windows drivers using the WDF Kernel Mode Driver Framework (KMDF) or the WDF User Mode Driver Framework V2 (UMDF V2).

Prerequisites

Students attending this seminar will be assumed to have a good working knowledge of general O/S concepts (user mode versus kernel mode, virtual memory concepts, and concurrency issues) and device concepts (such as buses, interrupts, and registers).  Previous experience developing device drivers (on any operating system) will definitely be an advantage, but is not required.

For users who plan to do the self-directed lab assignments: Attendees will need to be able to use Windows and Microsoft’s Visual Studio. Working knowledge of the C programming language, and how to read and write to a file using Win32 APIs (CreateFile, ReadFile, WriteFile) are also assumed.

Hands-On Lab Assignments

To enhance your learning, this class includes a set of optional lab exercises. These lab exercises are designed to be done on your own, outside of the time reserved for the seminar. During the week of your seminar, the instructional team will be available to review, discuss, and answer questions about any of the lab exercises. If you choose to do any of the lab exercises some days or weeks after the seminar, you’ll be able to email your instructor to get answers to any questions you might have.

Each student who wants to attempt these lab exercises will need to have access to their own pre-configured and pre-tested “lab system.” If your seminar is in-person, you will need to bring this system (presumably a laptop) with you to the seminar, so you can work on the lab assignments before and after class. If you’re attending your seminar remotely, you can use any type of system you prefer. In either case, please carefully read and understand the setup requirements for this system.

The hardware and software requirements for this seminar are described on our OSR Seminar Lab System Setup Requirements page.

After This Seminar

This seminar provides you with the necessary information to attend OSR’s Kernel Debugging and Crash Analysis seminar, as well as OSR’s Writing WDF Drivers II: Advanced Implementation Techniques seminar.

Seminar Outline

• Introduction
  Welcome remarks, seminar goals and objectives. Introduction to WDF, as well as KMDF and UMDF V1 and UMDF V2 and when each model is the most appropriate.

• Windows OS Architecture for Driver Writers
  A review of core Windows architecture concepts of specific importance to driver developers. Topics include:
  • General organization of NTOS:  Executive, Kernel, and HAL.
  • Processes and threads.
  • Memory management.
  • Introduction to key I/O Manager objects (File Object, Device Object, Driver Object).
  • Overview of PnP process.
  • Power Management.
  • Executive Services.
  • Object Manager – How an object name (such as a file specification) is processed.
  • How File Objects are created and the process-specific handle table.
  • Windows Kernel introduction.
  • Windows HAL introduction.

• The Windows Device Tree
  This module comprises a detailed view of how the Windows PnP subsystem discovers and enumerates devices and loads their associated drivers. Details for devices on dynamically enumerable buses (such as PCIe, USB, or Bluetooth) and non-dynamically enumerable buses (such as SPI, I2C, or GPIO) are described. All about Physical Device Objects (PDOs), Function Device Objects (FDOs), and filter Device Objects. How filter drivers work their magic. How requests are processed, and passed from driver to driver within the Windows I/O Subsystem. I/O request completion handling. Further discussion and description (expanding on information from the previous module) of how system requests in general and I/O request in particular are passed from user-mode to kernel-mode, initially in the context of the requesting thread.

• Driver Installation
  How Windows finds “the best” driver for a given device. A brief discussion of how drivers are installed, and how INF files are created. Operation parameters that need to be specified as part of the INF file. Driver signing throughout history and today, and why it’s the subject of so much confusion. A brief discussion of how to track-down install problems.

• The WDF Object Model
  WDF object characteristics and taxonomy. How objects are instantiated and used in KMDF and UMDF V2. An overview of the most common WDF objects.

• Driver Initialization
  How a WDF driver and its associated device are initialized. Also, handling typical PnP and power management events such as device discovery (EvtDriverDeviceAdd), power-up (EvtDeviceD0Entry), and power-down (EvtDeviceD0Exit). How WDF drivers are notified of and claim their hardware resources, including registers, ports, connections, and interrupts.

• Building and Debugging
  Students are assumed to already be familiar with the basics of how to use Visual Studio. We’ll review the details, as well as discuss how to setup and use WinDbg, the Windows kernel debugger. We’ll also discuss specific issues about building and debugging drivers for Windows using the Windows Driver Kit and Visual Studio.

OPTIONAL LAB: Building and Debugging, Driver Initialization (DriverEntry, EvtDeviceD0Entry, etc.).

• Interrupt Request Levels & Deferred Procedure Calls
  In this module, we discuss the all-important concept of Interrupt Request Levels (IRQLs), and the specific uses that Windows makes of various IRQLs. We also discuss Deferred Procedure Calls (DPCs) and how they’re used in Windows for Interrupt Service Routine completion (DPCforISR). We also discuss passive-level interrupts and its associated Work Item for ISR.

• Queues and Requests
  How a WDF driver gets I/O requests, and how those requests are processed. Topics include: how WDF Queues are instantiated, Queue dispatch types, and how Queues can be used to sort Requests; How Requests are processed and completed; How the user data buffer associated with a Request is accessed and in what process context this access occurs; How Requests are completed with data, status, and information returned to the originator.

• Buffer Methods and Device Controls
  The different ways that requestor data buffers can be described are discussed. Direct I/O, Buffered I/O, and “Neither I/O” are described, compared, and contrasted. Also discussed is how to define custom Device IO Control Codes (IOCTLs), and how the previously described buffering methods apply to IOCTLs.

OPTIONAL LAB: Request Processing and Completion, Filtering

• Case Study 1: Programmed I/O Device
  This case study reviews and demonstrates all the topics discussed in the seminar to this point. To do this, the instructor takes students on a guided walk-through of the code for a driver for a very simple PCIe Digital I/O device, reviewing and reinforcing concepts along the way. All phases of driver operation are reviewed from device discovery, to claiming hardware resources, processing power state changes, and processing and completing requests both synchronously and asynchronously.
  
  While details of PCIe PIO device drivers are specifically addressed, the focus is on reinforcing concepts that are common to all WDF drivers from Programmed I/O devices. These concepts include receiving hardware resources, receiving and processing I/O Requests, accessing device registers, moving data between the user’s data buffer and the device, handling interrupts, and completing Requests.

• I/O Targets
  How a driver sends Requests to other drivers in the system, and optionally receives the results. Local, Remote, and Special I/O Targets. Both synchronously and asynchronously send operations are discussed. Completion routines are also covered.

• Case Study 2: USB
  
  • Part 1: USB Concepts
    The basics of USB are discussed including device, configuration, and interface descriptors. Endpoints and pipes are described.
    
  • Part 2: Implementing WDF USB Drivers
    In this section, we describe how USB drivers are implemented in KMDF. This includes how a configuration and interface is chosen, and how endpoints are retrieved. How to send vendor commands to a device via Endpoint. Using Bulk and Interrupt endpoints. The WDF Continuous Reader is briefly discussed, as is supporting Selective Suspend (USB device power management).
    
    While the details of writing USB device drivers are discussed, the focus is (once again) on reinforcing general WDF implementation concepts (in this case, getting custom-defined I/O Requests, converting them to device-specific operations, and sending Requests to other drivers) that are common to all WDF drivers from devices that are attached to the system via protocol-based buses.

OPTIONAL LAB: USB drivers, using the student’s own OSR USB FX-2 device (supplied as part of the seminar)

• Driver Quality and Debugging: Best Practices
  In this session, we discuss some of the tools and techniques that are available for testing and ensuring driver quality. We discuss how the WDF Kernel Debugger Extensions (WDFKD) can be used to debug WDF drivers (both KMDF and UMDF V2). We discuss Windows Driver Verifier, as well as WDF Verifier and the “In Flight Recorder.” We discuss Code Analysis and Static Driver Verifier, as well as how SAL Annotations can be used to enhance the effectiveness and breadth of these tools.

• Case Study 3: SPB/GPIO Device
  How Simple Peripheral Bus (SPB) and GPIO-connected Client devices (such as sensors on SPI, I2C, and GPIO buses) are supported in Windows. Acquiring Connection Resources using the RESOURCE_HUB. Controller drivers and Client drivers. Walk-through of the initialization and I/O processing for a Client driver that receives interrupts via a GPIO line and collects data from an I2C or SPI bus. An introduction to the Power Management Framework (PoFx), including review of example configurations and callbacks for single-component devices.
  
  As in all our case studies, while we discuss the specifics of handling SPI/I2C and GPIO devices, the goal of this module is to reinforce WDF concepts that apply to a wide variety of drivers. Specifically, in this case study, we see receiving, processing, and completing Requests, including building new Requests from received Requests and sending those to other drivers using WdfRequestSend.

• Locking
  In this module, we discuss issues relating to synchronizing access to shared data within a driver. The much-misunderstood topic of WDF Synchronization Scope is fully described, as is extending sync scope to other callback routines via the Automatic Serialization parameter. WDFSPINLOCKs and WDFWAITLOCKs are discussed, along with the underlying implementations of each and how they’re used and the implications of using each of these serialization mechanisms from user-mode drivers.

• Cleanup, Close, and Cancel
  We give specific definitions for each of these operations, and discuss why Request cancellation is one of the most confused (and most poorly implemented) functions in so many WDF drivers. We emphasize how each of these operations can interact, and discuss why they’re so often misunderstood. We discuss strategies for handling the cancellation of queued and in-progress requests are discussed, as what processing typically takes place as part of cleanup and close processing.

• Helpful Classes
  A brief description of a few Framework classes such as WDFSTRING, WDFCOLLECTION, WDFWORKITEM, and WDFTIMER that might be useful for driver developers to know.

OPTIONAL LAB: USB continued, Open/Close processing.