Simplified USB Function Driver: Simplified USB Function Driver


Outline: Outline Motivation and problem statement Opportunities to ease software development KMDF and USB devices Architecture and scenarios IHV opportunities WinUSB’s role in USB devices Architecture and scenarios IHV opportunities Summary


Motivation for Simplification: Motivation for Simplification USB is a highly popular bus HID, printers, scanners, media players, still cameras, Bluetooth radios, … Newer peripherals being developed daily over USB APIs for USB function drivers standardized since Windows 98. However, it is hard to write a WDM driver for a simple USB device. Interesting statistics 100% of new systems have a USB port (generally 2.0 capable) Average user attaches at least 8+ devices to system over time


Kernel Mode Driver Foundation (KMDF) - Architecture: Kernel Mode Driver Foundation (KMDF) - Architecture Motivation Too many: Rules that every WDM driver must implement Behaviors to get right Details to effectively test In the end, very hard to get right Solution Encapsulate all the hard problems into one location Provide a solution which has good default behavior


KMDF USB Support: KMDF USB Support KMDF encapsulates PIRP formatting and sending via IoCallDriver into the WDFIOTARGET object WDFUSBDEVICE WDF target object for configuration and control transfers WDFUSBINTERFACE Grouping object that contains WDFUSBPIPE objects for a configured interface WDFUSBPIPE WDF target object for non control endpoints A WDF target does the following for you Manage target state (Started, Stopped, Removed) Track sent requests and cancel them when asked Manage lifetime of the request and the memory in it You no longer have to worry about when to free memory or the request itself You can use KMDF USB functionality in both a full fledged WDF driver and in some existing WDM miniport models (e.g. NDIS-WDM)


KMDF USB Features: KMDF USB Features Configuration Easy iteration of interfaces and endpoints Select Configuration Automatic (select AlternateSetting 0 for each interface) Custom (driver provided settings list) SelectSetting for each interface AlternateSetting Optional continuous reader for any IN WDFUSBPIPE Can configure how many pending requests are polling Automatic buffer allocation and cleanup Selective Suspend functionality and logic built into WDF directly


KMDF USB DDI Examples: KMDF USB DDI Examples Configuration WdfUsbTargetDeviceSelectConfig WdfUsbInterfaceSelectSetting WdfUsbInterfaceGetNumConfiguredPipes WdfUsbInterfaceGetConfiguredPipe Async I/O on WDFUSBPIPE WdfUsbTargetPipeFormatRequestForRead WdfUsbTargetPipeFormatRequestForWrite Sync I/O on WDFUSBPIPE WdfUsbTargetPipeReadSynchronously WdfUsbTargetPipeWriteSynchronously


What is UMDF: What is UMDF Implementation of the WDF Driver Model in User Mode Provides: The infrastructure to run a device driver in user-mode The WDF I/O Pipeline and PnP/PM State Machine The core WDF objects Devices, Files, Queues, Requests, I/O Targets, etc... UMDF and KMDF both share the WDF Model So learning how to use one will apply to the other But they are not source or binary compatible Have similar but not identical DDIs Each has additional functionality applicable to its domain


WinUSB – Motivation and Architecture Motivation: WinUSB – Motivation and Architecture Motivation KERNEL Mode Driver handles Complex logging and I/O Power management PnP events, etc. USER Mode DLL exposes simpler USER Mode API Incorrect implementation leads to app hang/crash (not PC crash) Safer upgrade to new OS Solutions like HID are inefficient (need special H/W) IHVs don’t want to be experts in complex driver models Value Statement: Make the common case simple, and the rest possible


WinUSB – Candidates and Statistics: WinUSB – Candidates and Statistics Statistics Performance Able to maintain Hi-speed bus traffic at ~40MBps transfers !!! andlt;10% CPU utilized by system on 3GHz machine with 512MB RAM Code development time For beginners: 1-2 days to get initial device communication For advanced users: Few minutes. ;) Potential candidates Media Transfer Protocol (MTP) devices Test and measurement devices Simple sync/update utilities University/independent projects IAD devices When can you NOT use WinUSB? Bus drivers that need to build additional stacks in kernel ISOC devices


WinUSB – How to Write an INF?: WinUSB – How to Write an INF? Selection of class/class GUIDs in Version Section of INF Do NOT use Class 'USB' Selection of Interface GUIDs in INF WinUSB allows for multiple Interface GUIDS to be simultaneously registered In the HW.AddReg section, add : HKR,,DeviceInterfaceGUIDs, 0x10000,'{058815B2-9805-47d3-B7D5-ABC464D3CA06}' Use Include/Needs in your INF to load the right sections Ensure that INF works on ALL platforms – x86, IA64, x64 Always run latest logo program validation test to verify INF


WinUSB – Advanced Features around Pipe Policies: WinUSB – Advanced Features around Pipe Policies Policies that developers can set to modify the driver’s behavior Write pipe policies: SHORT_PACKET_TERMINATE (DEFAULT: false) RAW_IO (DEFAULT: false) Read pipe policies: AUTO_CLEAR_STALL (DEFAULT: false) PIPE_TRANSFER_TIMEOUT (DEFAULT: infinite) IGNORE_SHORT_PACKETS (DEFAULT: false) ALLOW_PARTIAL_READS (DEFAULT: true) AUTO_FLUSH (DEFAULT: false) RAW_IO (DEFAULT: false) Power policies AUTO_SUSPEND (DEFAULT: true) ENABLE_WAKE (DEFAULT: false) SUSPEND_DELAY (DEFAULT: 5 secs)


Microsoft Internal Consumers: Microsoft Internal Consumers WinUSB MTP is an early adopter of WinUSB for Windows codenamed 'Longhorn' Used internally for test and compliance tools KMDF USB Driver Library WinUSB itself is based on KMDF USB support Sample Driver (osrusbfx2 ) See KMDF talk for intro Microsoft Committed to using these drivers internally! Benefits of having internal Microsoft customers… Identify new and complex usage situations Get early feedback and catch bugs faster Validate assumptions and see if its really simple to program to this new interface!


Which Model is Right for You? : Which Model is Right for You? Use WinUSB and write code in User Mode… If device is exclusively owned by a single specific application, and If the code handling the device is entirely in application E.g. Device Validation and compliance test program Use KMDF and write code in Kernel Mode… If the driver needs to communicate with other drivers in Kernel Mode E.g. smart-card reader driver, etc If the device is not exclusively controlled by a single Application all the time. You may need a central entity to manage the resource E.g. serialandlt;-andgt;USB NIC If the device needs ISOC support or needs to control protocol timing very tightly E.g. Conference Camera driver KMDF will be made available on Windows 2000, but WinUSB may not


Which Model is Right for You? – Part 2: KMDF USB – Used for devices whose drivers have to be in kernel mode WinUSB with UMDF – Used for devices where a real driver is needed. E.g. Raise the level of abstraction of the device (there is a deep stack of third party added value) The device is shared across multiple applications Applications can recover from driver crashes or failures. Devices like cameras, cellphones, media players etc. belong to this category WinUsb without UMDF – Used for exclusive devices where an application has full control of the device and is high degree of knowledge about the device Which Model is Right for You? – Part 2


Which Model is Right for You? – Part 3: Which Model is Right for You? – Part 3


Call To Action: Call To Action Beta test these features and provide feedback KMDF WinUSB Provide Microsoft with feedback on features that you need but NOT yet available/implemented Ensure that your device works on ALL 32- and 64-bit platforms Follow the details on www.microsoft.com/whdc to ensure that your device is tested for Windows Logo Program


Additional Resources: Additional Resources Email: windf @ microsoft.com Web Resources: Whitepapers: http://www.microsoft.com/whdc Other Resources: Windows Development Kit for documentation


Slide19: © 2005 Microsoft Corporation. All rights reserved. This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.