Hi, my name is Qiang Qiu. I work for USB core test team. I write USB device drivers and services to test USB core stack with DSF simulated EHCI controller, hub and different types of devices. I enjoy working on device drivers. In this article, I’m going to provide a roadmap to getting started with USB driver development.
1. Obtain and Install the latest WDK and debugging tools
To build a driver, you must install WDK which contains the resources, libraries, tools, documentation that you need to develop WDF driver. Go to WHDC web site to obtain and install latest version of WDK and debugging tools.
To debug WDM and KMDF kernel drivers, two computers are needed: One to host the debugger and another to host the driver that is being debugged. This page will tell you how to setup kernel mode debug environment.
To debug UMDF drivers, the debugger and driver can be run either on the same computer or on two separate computers. This page will tell you how to setup user mode debug environment.
2. Choose which framework to use for your driver: WinUSB, UMDF, KMDF or WDM
There are several different ways to interact with a USB device. You can either write your own driver or use Microsoft provided generic USB driver called WinUSB.
WinUSB includes the WinUSB kernel-mode driver winusb.sys, which is an integral part of WDF user-mode driver framework (UMDF) support for USB drivers, and the WinUSB user-mode dynamic link library Winusb.dll. For USB devices that are accessed by only a single application, developers can often install WinUsb.sys as their device’s function driver instead of implementing a custom driver. If you manage your device with user-mode software, WinUSB will cost you less time, effort and expense devoted to driver development. Driver with WinUSB is likely to cause less system errors which improve the customer experience, is easier to manage power, brings less security threat because user mode driver can not sniff data at kernel level, and is easier and smaller to update driver package. WinUSB would be the easiest and best approach except if your driver want to do data streaming through isochronous endpoints or the functions you want to implement already have kernel-mode support in the Windows operating system (such as modem functions which is supported by TAPI or LAN functions which is supported by NDIS).
The new Windows Driver Framework provides User-Mode Driver Framework (UMDF) library for user mode driver development and Kernel-Mode Driver Framework (KMDF) library for kernel mode driver development. UMDF and KMDF implement the same conceptual driver programming model with different components, device driver interfaces (DDIs), and data structures.
If the WinUSB driver can not meet your driver requirement, try UMDF next. UMDF provides a unified model that can work across device classes and integrates tasks handling for installation, Plug and Play (PnP) and power management. It supports protocol device classes such as cameras and portable music players.
KMDF should be used only if UMDF or WinUSB don’t solve your purpose. KMDF framework is a library communicating with the operating system by using WDM interfaces. It provides interfaces simpler than WDM interface and handles many operations such as Plug and Play (PnP) and power management that must be handled by WDM drivers themselves. It also provides much of the synchronization code that is required for multiprocessor environments.
There is a common misunderstanding that miniport drivers such as NDIS or AVSTREAM cannot be written using KMDF. This WinHEC presenation provides more detail on how to use KMDF in miniports. Using KMDF provided USB I/O Target interfaces to interact with your USB device from an NDIS or AVSTREAM miniport is the best way to create a simple, robust driver.
WDM driver uses a set of interfaces to communicate directly with kernel-mode Windows components such as I/O manager and the Plug and Play (PnP) manager. WDM drivers are difficult to write, complex, less robust, and should not be written unless absolutely necessary.
This page will further help you choose a driver model based on the device class.
3. Check system requirements for your driver
You can develop WinUSB and UMDF drivers for Windows XP and later versions of Windows (not including Windows Server 2003). You can develop and build KMDF drivers for Windows 2000 with Service Pack 4 and later versions of Windows. You can develop WDM drivers for any version of Windows.
4. Obtain a test device
- In most cases, the developer for a new driver will be given a device and/or a specification for a device and told to write a driver for it. If the device is just in prototype development phase, it will be helpful to use below Device Simulation Framework (DSF) to build a simulator following the specification for development and testing purposes.
- OSR Learning Kits has all the required hardware specifications to implement a driver. It can be obtained from http://www.osronline.com/. OSR Learning Kits is the best actual hardware to study USB samples in WDK.
- You can use the Device Simulation Framework (DSF) which is a part of WDK for USB Devices to test your driver (Choose install it during WDK installation). DSF only uses software to simulate USB devices, so that you do not need any special hardware. DSF has already created some sample USB Device Simulators such as HID Generic Device, Loopback Device, Audio Device and Keyboard Device. You can use them directly if you install DSF on your computer. There is an instruction to guide you to test your USB driver with a USB Device Simulator.
5. Reference samples from the WDK
- WinUSB Samples
The most comprehensive documentation for how to use WinUSB to access a USB device is this whitepaper “How to USB WinUSB to communication with a USB Device“. For sample code, refer below UMDF Fx2_Driver sample.
UMDF Driver Skeleton Sample: This sample demonstrates how to use UMDF to write a basic driver. It is a starting point for implementing a function driver.
Fx2_Driver: This sample demonstrates how to use UMDF to create a driver to perform bulk and interrupt data transfers with OSR USB Fx2 Learning Kit.
- KMDF Samples
OSRUSBFX2: This sample is a step by step tutorial to demonstrate how to create a KMDF driver to perform bulk and interrupt data transfers to an USB device with OSR USB Fx2 Learning Kit. If you are new to KMDF driver, this sample is the best one to start with.
USBSAMP: This sample demonstrates how to perform bulk and isochronous data transfers to a generic USB device.
In the next blog post, I will describe the difference between OSRUSBFX2 and USBSAMP samples.
HIDUSBFX2: This sample demonstrates how to write a HID minidriver in which a non-HID USB device is mapped to a HID device.
Toaster -WDF Version: This sample is a rewrite of the WDM toaster driver and is great starting point for understanding KMDF. It illustrate the functionality for bus driver, function driver and filter drivers for a hypothetical bus and its devices.
- WDM Samples
Toaster – WDM Version: This sample demonstrates how to write a bus driver, a function driver, assorted class, device and bus filter drivers, a class installer, and a device-specific co-installer for a hypothetical bus and its devices.
USBView Sample Application: This sample provides a GUI application to browse all connected controllers and USB devices on your computer. It is able to dump USB device’s descriptors, query information about the devices from the registry via USB requests to the device. This is a useful tool but not a driver sample.
We STONGLY DISCOURAGE you from using WDM Isochronous client driver sample (isousb.sys), Bulk transfer client driver sample (bulkusb.sys) and Selective suspend client driver sample (selsusp.sys) from old WDKs. These samples do not exist in the latest Windows 7 WDK installation package.