WDF Custom Driver Design Pattern

PETER WIELAND

Software Design Engineer

2 04/19/2023MICROSOFT CONFIDENTIAL

Agenda• What is the WDF Custom Driver Pattern?• Example• Components

• Device• Custom Driver• App• Device Metadata

• Design Guidance• Questions & Code Walkthrough

3 04/19/2023MICROSOFT CONFIDENTIAL

WDF Custom Driver Pattern

Advantages Disadvantages

Can meet needs of the broadest range of devices

Requires development, certification & maintenance of a custom device driver

Vendor controls which Metro style apps access their device

Only vertical solutions are supported, and only a small # of apps can have privileged access to the device

Existing custom drivers can be easily adapted for this pattern

This is the most complicated pattern with the most components and moving parts.

Communications between app and driver must be written in C++

Not supported for external devices on WinRT

• A device, such as a USB attached device, that doesn't fit into any of the other patterns.

• Protocols: Any. A custom device driver provides access to the device from the app

• Access Model: Restricted• API: Device Access: (CreateDeviceAccessInstance(), IDeviceIoControl())

4 04/19/2023MICROSOFT CONFIDENTIAL

WDF Custom Driver Pattern

• Custom USB Device : USB credit-card reader with app to perform CC transactions

• Acquisition Scenarios: Automatic Acquisition, Windows Store Download

• Device Discovery: Windows.Devices.Enumeration• Device Access: CreateDeviceAccessInstance(), IDeviceIoControl

EXAMPLE

Device

Device driver

Device metadata

Metro style app

+ metaapp+ +

5 04/19/2023MICROSOFT CONFIDENTIAL

ComponentsDEVICE

Device

• Custom WDF Driver pattern can be applied to any device• Other patterns may be a better fit, depending on the device

• Device must have a unique hardware ID

• Device must be pass Windows Hardware Certification

• For use with real, external devices• Not software or virtualized devices

6 04/19/2023MICROSOFT CONFIDENTIAL

Components

• Written using Windows Driver Framework (WDF)• Driver can be user-mode or kernel-mode WDF driver• See

Using the Windows Driver Framework to build better drivers• Driver provides communications between app &

device• Registers a custom device interface for the app to open• Sets restricted property on interface to grant privileged app

access• App sends I/O controls to the driver to control device

• Driver should be signed and deployed to Windows Update

• Custom driver can use other drivers to talk to device• e.g. USB HID drivers

DEVICE DRIVER

Device driver

7 04/19/2023MICROSOFT CONFIDENTIAL

Components

• Declares the custom device interface class as a device capability in app manifest

• Discovers device interface using DeviceInformation’s FindAllAsync() method

• Opens a handle to the device using CreateDeviceAccessInstance()

• Communicates with device using IDeviceIoControl interface

• Last two steps can only be done in C++ code• Recommend creating a C++ WinRT component for this

APP

appMetro style app

8 04/19/2023MICROSOFT CONFIDENTIAL

Components

• For the purposes of a device app, Device Metadata:• Declares your app as a privileged app

• Set AccessCustomDriver attribute to “true”• Declares your app as an automatically acquired app for the

device

• Permission applies to the device container• App can access any restricted interface it has declared

access to in the container

DEVICE METADATA

meta

Device metadata

9 04/19/2023MICROSOFT CONFIDENTIAL

Design Guidance

• Authoring the Device Driver• Write custom drivers in user-mode WDF where possible• Drivers must be certified with the Windows Hardware Certification Kit (WHCK)

• Check Windows Hardware Certification requirements for your device type

• May want to create new device interface specifically for device app• Can provide different capabilities to admin running desktop app vs. normal user

running device app• Many existing device interfaces assume administrator access• App to driver interface can only use IOCTLs

10 04/19/2023MICROSOFT CONFIDENTIAL

Updating with Custom WDF Pattern

• Loose coupling between app, device metadata, and drivers.

• Components are distributed through different services with update rhythms:• App updates – Available sometime after acceptance. Users are notified of an

update and must initiate update.• Device metadata updates – 2 days after acceptance, auto-download within 8

days• Driver updates – available sometime after acceptance. Driver notification &

update dependent on Windows Update client settings.

• Components need to behave gracefully when all proper components are not present. (maintain forward and backward compatibility)

11 04/19/2023MICROSOFT CONFIDENTIAL

Sample Walkthrough

12 04/19/2023MICROSOFT CONFIDENTIAL

Summary

• Very flexible in terms of devices supported

• Only supports restricted app model

• Certified custom driver makes this a costly pattern

• Beware of compatibility between components