WinUsb HowTo program

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

HowtoUseWinUSBtoCommunicatewithaUSBDevice‐2
March30,2009
©2009MicrosoftCorporation.Allrightsreserved.
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

HowtoUseWinUSBtoCommunicatewithaUSBDevice‐3
March30,2009
©2009MicrosoftCorporation.Allrightsreserved.
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 ...................................................................................................... 24
FutureFeatureConsiderations .................................................................................... 24
Summary ...................................................................................................................... 24
Resources ..................................................................................................................... 24

HowtoUseWinUSBtoCommunicatewithaUSBDevice‐4
March30,2009
©2009MicrosoftCorporation.Allrightsreserved.
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approachisWDF.TheWDFprogrammingmodelanddevicedriverinterface
(DDI)makesWDFUSBdriversmucheasiertoimplementthanequivalentWDM
drivers.YoucanimplementWDFUSBdriversineitherofthefollowingways:
• Usetheuser‐modedriverframework(UMDF)toimplementuser‐modeUSB
driversformostUSBdevicesforWindowsXPandlater.
• Usethekernel‐modedriverframework(KMDF)toimplementkernel‐modeUSB
driversforanyUSBdeviceforWindows2000andlater.
Thiswhitepaperdescribeshowtochoosethebestwaytoprovideapplicationswith
accesstoaUSBdeviceandanswerssomecommonquestionsaboutWinUSB.The
bulkofthepaperisadetailedwalkthrough—includingcodesamples—ofhowto
installWinUsb.sysasaUSBdevice’sfunctiondriverandhowtousetheWinUSBAPI
tocommunicatewiththedevicefromanapplication.

HowtoUseWinUSBtoCommunicatewithaUSBDevice‐5
March30,2009
©2009MicrosoftCorporation.Allrightsreserved.
TheexamplesinthispaperarebasedontheOSRUSBFX2LearningKitdevice,butyou
caneasilyextendtheprocedurestootherUSBdevices.Figure1isasimplified
diagramoftheFX2deviceandshowsitskeyfeatures.
USB
Socket
USB
Chip
Light Bar
Toggle Switches
LED Panel
Remote Wakeup
Switch
Figure 1. OSR USB FX2 Learning Kit device
Summary of WinUSB, UMDF, and KMDF Capabilities
Table1summarizesthecapabilitiesofWinUSB,UMDFUSBdrivers,andKMDFUSB
drivers.
Table1.WDFUSBFeatureSupport
RequirementsWinUSBUMDFKMDF
Supportsmultipleconcurrentapplications.NoYesYes
Isolatesdriveraddressspacefromapplicationaddressspace.NoYesNo
Supportsbulk,interrupt,andcontroltransfers.YesYesYes
Supportsisochronoustransfers.NoNoYes
Supportstheinstallationofkernel‐modedriverssuchasfilter
driversabovetheUSBdriver.
NoNoYes
Supportsselectivesuspendandwait/wakeYesYesYes
Table2summarizeswhichWDFoptionsaresupportedbydifferentversionsof
Windows.
Table2.WDFUSBWindowsSupport
RequirementsWinUSBUMDFKMDF
WindowsVistaandlaterYes1Yes1Yes
WindowsServer2003NoNoYes
WindowsXPYes2Yes2Yes
Windows2000 NoNoYes3
Notes:
1WinUSBandUMDFaresupportedonlyonx86andx64versionsofWindows.
2WINUSBandUMDFaresupportedonWindowsXPwithservicepack2orlater.
3KMDFissupportedonWindows2000withServicePack4orlater.