Getting Started with USB Driver Development


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.


Comments (12)

  1. Kris says:

    Can you make use of VPC or VMWare for development and debugging, instead of two physical computers?

    Thanks.

  2. USB Blog says:

    If you are developing and testing with an actual piece of hardware, I would not recommed developing within VPC or VMWare.  While these products have varying levels of USB redirection support, there is no guarantee that it will give the same behavior as running on the host OS.  Some operations may get artificially serialized, timing may change, there may be varying levels of verification, etc.

    Having said that, if you are doing your initial development/testing on a simulated device (using DSF, which I highly recommend), then that can be done within VPC.  I have done this in the past, and it is a pretty cool way to do this initial work.  

    I hope that helps.

  3. Andy says:

    Similar to Kris, can I use Hyper-V with USB pass-thru to a guest for debugging?

  4. EXCELLENT MATERIAL WHICH IS PRESENTED IN MOST EASIEST MANNER AND EXPLAINED VERY WELL. THANK U

  5. TianyangHu says:

    If I want to convert a32-bit driver to 64-bit dirver, what kinds of the problem need to be considererd ?

    Thanks

  6. jitender samal says:

    I am doing some delay (WaitForSingleObject) in returning from the function OnDeviceRequest. The delay is because I want to read some data from the simulated USB Device which takes time.  After the delay when I return from OnDeviceRequest, the softehci cancels the transaction/setup request. Is there something to get rid of this problem?

  7. jefferycarlson@gmail.com says:

    what code sample could i use to simulate adding four mice in dsf? probably for the times sake can you point me to articles or samples someones created that add a mice in dsf.

  8. StevenChen says:

    We have a USB driver works on 2000/XP. Now we are upgrading to Win7. Will the existing driver work on Win7? If not what needs to be done? Thanks.

  9. bipul says:

    very good  study material

    i have one question, in the UMDF the example of winddk is using winusb to communicate to usb device instaed of winusb we can use usb hid class, if yes then how …

    Thanks

  10. usb_Dev says:

    hi , this article details the driver written to work with usb device . but if we want to write usb perpheral( controller) driver which has windows as OS then can you pls give me pointers for that ? does the framework remains same and how do we go about it ?

  11. amit says:

    Hi ,

    Can you please let me know how do we write usb (peripheral) controller/function  driver for windows phone  , so that it can work with windows USB host ?

    All the document talks about the function driver on top of usb host controller driver . Do we have different set of APIs and stack for that?

  12. Pre@ Posh says:

    i was looking for a USB driver development Engineer and was wondering if you know of someone who is exploring a consulting opportunity like that, please let me know in case you would know some one who would be intrested…

    Thanks