How to Use WinUSB to Communicate with a USB Device

How to Use WinUSB to Communicate with a USB Device March 30, 2009 Abstract Independent hardware vendors (IHVs) who manufacture USB devices must often provide a way for applications to access the device’s features. Historically, this has meant using the Windows® Driver Model (WDM) to implement a function driver for the device and installing the driver in the device stack above system-supplied protocol drivers. The Windows Driver Foundation (WDF) is now the preferred model for USB drivers. It provides IHVs with three options for providing access to a USB device: • Implementing a user-mode driver by using the WDF user-mode driver framework (UMDF). • Implementing a kernel-mode driver by using the WDF kernel-mode driver framework (KMDF). • Installing WinUsb.sys as the device’s function driver and providing an application that accesses the device by using the WinUSB API. This white paper provides guidelines for when to use each option and includes a detailed walkthrough of how to install WinUsb.sys as a device’s function driver and use the WinUSB API to communicate with the device. This information applies for the following operating systems: Windows 7 Windows Server® 2008 Windows Vista® Windows XP References and resources discussed here are listed at the end of this paper. For the latest information, see: http://www.microsoft.com/whdc/connect/usb/winusb_howto.mspx Disclaimer: This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein. The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. 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 presented after the date of publication. This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred. © 2009 Microsoft Corporation. All rights reserved. Microsoft, MSDN, Windows, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners. Revision History Date Change March 30, 2009  Added additional information for communicating with endpoints. December 6, 2007  Added a section on DFU to the WinUSB FAQ.  Removed the note from Table 1 indicating that WinUSB does not support WinUSB selective suspend on Windows XP. August 30, 2007 Created Contents Introduction 4 Summary of WinUSB, UMDF, and KMDF Capabilities 5 Guidelines for Providing Access to USB Devices 6 Introduction to WinUSB 6 WinUSB FAQ 7 How to Install WinUsb.sys as a Function Driver 8 How to Use the WinUSB API 12 Obtain a Handle to the Device and Initialize WinUSB 12 Obtain the Device Path 13 Obtain a File Handle for the Device 15 Initialize WinUSB 15 Configure the Device 15 Communicate with Endpoints 17 Control Requests 17 WinUSB I/O Requests 19 WinUSB Write Requests 19 Default WinUSB Write Behavior 20 WinUSB Read Requests 20 Default WinUSB Read Behavior 20 Pipe Policies 21 WinUSB Power Management 23 Selective Suspend 23 Detecting Idle 23 Future Feature Considerations 23 Summary 24 Resources 24 Introduction Independent hardware vendors (IHVs) who manufacture USB devices must typically provide a way for applications to access the device’s features. Historically, this has meant using the Windows® Driver Model (WDM) to implement a function driver for the device and installing the driver in the device stack above system-supplied protocol drivers such as Usbhub.sys or Usbccgp.sys. The function driver exposes a device interface that applications use to obtain the device’s file handle. They can then use the handle to communicate with the driver by calling Windows API functions such as ReadFile and DeviceIoControl. Drivers are the most flexible way to provide access to a USB device and allow the device to be accessed by any application, including multiple concurrent applications. However, drivers require a significant development effort, and some devices are simple enough that they do not require the full support of a custom function driver. For example, devices such as machine controllers or data loggers are typically accessed only by a single application that was written specifically for the associated device. In these cases, WinUSB provides a simpler alternative to implementing a custom USB driver. WinUSB was developed concurrently with the Windows Driver Foundation (WDF) and is available for Windows XP and later versions of Windows. It includes a kernel-mode driver, WinUsb.sys, which is an integral part of WDF user-mode driver framework (UMDF) support for USB drivers. However, for USB devices that are accessed by only a single application, vendors can often install WinUsb.sys as their device’s function driver instead of implementing a custom driver. The application can then configure the device and access its endpoints by using the WinUSB API. For those USB devices that require the features of a custom function driver, the preferred