User-Mode Driver Framework: Technical Synopsis Peter Wieland Development Lead Windows Device Experience Group Microsoft Corporation

Introduction Why User-Mode Drivers? WDF and UMDF Goals UMDF Architecture What’s changed since Windows Vista Beta 1 Where we’re going with UMDF

Reasons To Avoid Kernel Mode Drivers Kernel-Mode Drivers can corrupt the kernel Leads to data corruption and crashes Kernel-Mode Drivers can compromise the kernel Malicious driver can steal data, install hooks, open security holes, etc. Kernel-Mode Drivers are difficult to write Kernel-mode environment is very complex Even with KMDF

Why User-Mode Drivers? UM Drivers can’t corrupt or compromise kernel Can’t corrupt or steal data or crash the OS UM Drivers are limited in scope Run like Windows services Only act on data that passes through them UM Drivers run in an easier environment No IRQL, no DPCs, no non-paged pool Many user-mode tools and libraries available UM Drivers can still use WDF

Windows Driver Framework Goals Create a new model for driver development Provide object model which Encapsulates objects found in WDM drivers Isolates driver from internal implementation details Provide behavioral model which Defines a uniform set of behaviors for all objects Provides correct default behaviors for device drivers Helps driver writer manage object lifetimes Scales easily from simple to complex driver implementations Provide runtime environment which Integrates the driver with the underlying I/O system Enables “side-by-side” operation of major versions of framework

KMDF InterruptRegistryDPC Events and Timers Resource List PDOCollections KMDF And UMDF UMDF Impersonation Device Property Store Win32 I/O Target I/O Objects PNP State Machine USB I/O Target I/O Pipeline Two implementations of WDF Kernel-Mode Driver Framework (KMDF) for kernel-mode drivers User-Mode Driver Framework (UMDF) for user-mode drivers Each implements the core objects and behaviors Each has extensions for its environment

Core WDF Objects Driver Global state for driver Device A single piece of hardware I/O Target Request formatter for various busses & sends I/O requests to the lower device stack I/O Queue Allows driver to control request flow File Open connection to device (by client or driver) Request A single I/O operation Memory A buffer associated with for for use in I/O operations Object Driver created object can be inserted into parent tree Driver File Request DeviceFileRequest USB I/O Target Memory Object Memory I/O Queue System Owned Object Driver Owned Object Parent / Child Relationship Request Object

User-Mode Driver Goals UM Drivers are insulated from the kernel So they cannot harm the system UM Drivers look like any other driver UM Drivers act like any other driver Same installation through INFs Same Plug and Play and Power Management Same I/O features: Async I/O, cancellation, etc. Familiar to user-mode developers Use “user-mode patterns” where appropriate UM Drivers use the Windows Driver Framework Don’t invent a new driver model

WDF In UMDF UMDF provides core WDF model Supports the core I/O objects Device, File, Queue, Request, Memory Provides I/O pipeline and PnP state machine UMDF is not a user-mode version of KMDF Does not share the same DDI UMDF DDI builds around “COM Lite” and C++ Does not support kernel or hardware objects Interrupts, spinlocks, resource lists, etc. Has user-mode specific objects and behaviors Device registry access, impersonation, etc. Does not support bus drivers Does not support device wake

Kernel Driver Example Application Provided by: Microsoft ISV OEM IHV USB Driver Function Driver Filter Driver Handle Buffer IRP

UMDF Host UMDF Example Application USB Driver Handle Buffer IRP UMDF Reflector FxFunction Driver Filter DriverFx Fx Request UMIRP Fx Request Side Object IRP Handle

UMDF Components Driver Manager Windows Service Manages driver host processes for reflector Reflector Kernel-Mode Driver Ties together user and kernel device stacks Manages requests and kernel resources Validates driver behavior Enforces timeouts for critical requests

UMDF Components Host Process Runtime environment for drivers Manages per-device-stack resources Loads device drivers and frameworks into stacks Manages I/O flow between drivers Framework Library Driver Framework objects PnP State Machine Manages I/O flow within a driver

Runtime Environment Host Process defines runtime environment One host process per device All drivers for a device stack load in the host Host runs as Local Service Reduces threat of a user-mode driver Can use impersonation when needed (but use caution) Driver can use Win32 components Kernel32, Advapi, Winsock, COM But remember that you are writing a secure, robust, reliable service for the device Know what you’re calling into and what security risks it entails No GUI code in Drivers

Changes In UMDF What has changed since Driver DevCon last year (2005)? Improved Device Installation File Objects and Cleanup/Close callbacks Adaptive Timeouts New I/O Targets for USB through WinUSB Win32 handles (to files or devices)

Improved Device Installation Installation at last DevCon was complex Too many registry entries to add, etc. UMDF Co-Installer simplifies installation INF has WDF specific directives for Setting UM service binary path and interface GUID Setting up the UM driver load order Enabling impersonation Extensive logging in setupact.log See UMDF samples in WDK

Example INF Excerpt from old UMDF Skeleton Sample INF [Skeleton_Install.NT] CopyFiles = UMDriverCopy RegisterDlls = UMDF.RegisterDlls AddReg = DriverServiceKey_AddReg [Skeleton_Install.NT.hw] AddReg = Skeleton_Device_AddReg [Skeleton_Install.NT.Services] AddService = WUDFRd,0x000001fa,WUDFRD_ServiceInstall [Skeleton_Install.CoInstallers] AddReg = CoInstallers_AddReg [DriverServiceKey_AddReg] HKLM, "%UMDF_SERVICES%\UMDFSkeleton", "ComCLSID", 0, "{…}“ HKLM, …, "ImagePath", 0, "%12%\UMDF\UMDFSkeleton.dll“ [Skeleton_Device_AddReg] HKR, "WUDF", "DriverList", 0x , "UMDFSkeleton“ [UMDF.RegisterDlls] 11,, UMDFSkeleton.dll, 1

Example INF Excerpt from new UMDF Skeleton Sample INF [Skeleton_Install.NT] CopyFiles = UMDriverCopy [Skeleton_Install.NT.Services] AddService = WUDFRd,0x000001fa,WUDFRD_ServiceInstall [Skeleton_Install.CoInstallers] AddReg = CoInstallers_AddReg [Skeleton_Install.NT.Wdf] UmdfService = UMDFSkeleton,UMDFSkeleton_Install UmdfServiceOrder = UMDFSkeleton [UMDFSkeleton_Install] UmdfLibraryVersion = ServiceBinary = %12%\UMDF\UMDFSkeleton.dll DriverCLSID = {d d09b-458f-a5aa-35ef21eef5de}

File Objects And Cleanup/Close In UMDF, all requests have a file Either created by the framework or driver In KMDF some requests may have no file Cleanup and Close were queued requests Cleanup could get stuck in queue behind outstanding I/O Changed into IWDFFile object callbacks Cleanup and Close are synchronized with other callbacks See USB Echo and FX-2 samples for cleanup / close handling

Adaptive Timeouts Some requests are “critical operations” Close, Cancellation, Device Removal, etc. These cannot fail, and hold up the system Hard timeouts are sensitive to synchronization and serialization Reflector watches for “forward progress” If driver is completing I/O, reflector is happy Assumes that if driver is completing I/O it will eventually complete the critical I/O as well

I/O Targets USB I/O Target Allows driver to work with USB Works through WinUSB Driver Follows WDF pattern Does not implement continuing reader See USB Echo sample driver for example Win32 I/O Target Extends I/O Target DDI to driver opened file handle Can use to access a file or a device Acts as a local I/O target I/O flows through lower UM drivers and then to handle Allows coupling of UM driver stack to a non-PNP entity Network connected device, serial connected device, etc. Currently not used in samples Must specify which I/O target device uses Through UmdfDispatcher directive in INF See samples for example

UMDF Futures We’re building our post Windows Vista plans now Considering things like Common DDI with KMDF Managed driver support for UMDF I/O targets for more buses Device-Class specific extensions Visual Studio Integration We need customer feedback to validate our priorities – see Call to Action

Call To Action Install the Windows Driver Kit Try UMDF for your driver projects Send us feedback! We want to know how to make the framework better We want to know what features are still missing Respond to our survey microsoft.com

Resources Join the WDF Beta Program Participate in the UMDF newsgroup microsoft.beta.windows.driverfoundation.umdf at betanews.microsoft.com microsoft.beta.windows.driverfoundation.umdf at betanews.microsoft.com WHDC web site DevCon 2005 presentations Join us for the lab and Q&A Wednesday Ask the Experts Tuesday evening

© 2006 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. 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 provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.