May 8, USB Client Driver Etiquette Jay Senior Windows Base Developer Microsoft

May 8, Agenda w What not to do: Wreak Havoc. How? w Proper setup methods w Fun with IRPs and URBs w USB specific issues w High-speed specific issues w Power management w Testing tips and tools

May 8, Installing Your Device w Two install apis – UpdateDriverForPlugAndPlayDevices u Used if device has been plugged in. – SetupCopyOEMInf u Used if the inf is not being copied by the install. w Includes and Needs pragmas – No recursion on W2K w No redistribution of system files - specify sourcediskfiles – USBhub is always present on the system, so no need to copy – USBhub no longer backward compatible on W2K. w New section suffixes:.ntx86,.ntia64, see DDK for more.

May 8, Driver Basics w Think in terms of multithreaded – How many times should an URB be submitted? We’ve seen the same one get submitted more than once. w Never make assumptions in filter drivers w Tear down symbolic links on surprise removal IRP – IoSetDeviceInterfaceState(&SymbolicLinkName, FALSE); w Synchronize requests with pnp – Wait for aborts to complete before completing remove. – IoReleaseRemoveLockAndWait is your friend. w Don't leave a DbgBreakPoint in production code!

May 8, Ping-Pong IRPs w Make sure not to recursively send ping-pong IRP w On hot unplug, requests will complete quickly. – Don’t spin tightly on requests when a device returns error. Make sure to wait a while before re-submitting. w When you create an IRP and specify a completion routine, don't call IoMarkIRPPending in the completion routine. – There’s no more stack locations. – There’s no more stack locations.

May 8, USB Hand Grenade w Freeing the URB/IRP while it is pending in the USB stack w Don't free anything attached to an active request w Concept of ownership – Just because IoCancelIRP called, doesn't mean that the IRP is yours yet – To guard, make sure to wait for completion routine to get hit w In IRP_MN_REMOVE, can wait forever for requests to complete – IoReleaseRemoveLockAndWait

May 8, Timing Out Requests w USB stack has no concept of timing out requests w Client driver's responsibility to timeout their own requests – Otherwise, the request might stay on the HW getting NAK'ed the whole time w Cancel after timeout case. – If you created the IRP, better have a completion routine! w USB specific Abort pipe – Keep track of outstanding requests and wait for requests to complete

May 8, Isochronous Devices w Need to be able to turn around requests quickly. w Put out two 4 ms frames -> Can’t keep up. w Submit two 32 ms frames and then party on one while it's pending -> Uh… Bad! w To get low latency use many small requests. w Proper solution: – Put down eight 4-ms requests.

May 8, Bus Interface w Available in W2K, WinME, and XP w Can be called at high IRQL w Expandable by specifying higher version number w IsDeviceHighSpeed w Example: – Is my device high speed? – Allows driver writer to write one driver

May 8, High-Speed USB w Making a device that works both 1.1 and 2.0. – Mostly only an issue when working with ISO. w Don't assume that there is still a max packet size of 64 bytes. – Retrieve it from endpoint descriptor. Potential max of 512 bytes. w Microframes - 8 microframes whereas there is only one frame on 1.1 – 32 packets would have gone in 32 frames previously. One frame is still 1 ms, but there are 8 microframes per frame. So queuing 32 packets will go over 4 frames.

May 8, Power Management on USB w Device States: – D0 is on – D2 is suspend. i.e. <= 500 uA – D3 is off w Once the hub PDO is not in D0, all requests will fail, so… – Cancel all pending requests before you send on the power down request to the hub PDO. w Don’t forget, power dispatch should at least have: – PoStartNextPowerIRP, – IoSkipCurrentIRPStackLocation – PoCallDriver

May 8, Selective Suspend w Allows bus to go to low power while PC is on w Allows processor to go to C3 and save battery w Understand the difference between system power down and selective power down – Track system power state, so that you don't power up without receiving a corresponding S0 IRP w USBhub does not power manage its PDOS – Whenever an idle IRP completes, must understand what power state you're in w See “SelSus” DDK example for more info

May 8, Testing Tips and Tools w Run the driver verifier! – More tests every day w Test devices – On all flavors - UHCI, OHCI and now EHCI. – On both XP and Win2K – While connected to an external hub u Slight electrical differences - overcurrent protection... w Test unplugging devices – While in use – While in low-power mode – While selectively suspended

May 8, Call to Action! w Use DDK tools like GenINF and CheckINF w Run appropriate WHQL HCT Kits on your devices – w The Windows XP DDK has the most recent sample code – DDK Developer / Product Support offers various support options w Contact the OEM / IHV Recon teams w Subscribe to the Windows Hardware Newsletter –