Business telephone etiquette for success. Telephone Etiquette.
May 8, 20012 USB Client Driver Etiquette Jay Senior Windows Base Developer Microsoft.
Transcript of May 8, 20012 USB Client Driver Etiquette Jay Senior Windows Base Developer Microsoft.
May 8, 2001 2
USB Client Driver Etiquette
USB Client Driver Etiquette
Jay SeniorJay SeniorWindows Base DeveloperWindows Base Developer
MicrosoftMicrosoft
May 8, 2001 3
AgendaAgenda
What not to do: Wreak Havoc. How?What not to do: Wreak Havoc. How? Proper setup methodsProper setup methods Fun with IRPs and URBsFun with IRPs and URBs USB specific issuesUSB specific issues High-speed specific issuesHigh-speed specific issues Power managementPower management Testing tips and toolsTesting tips and tools
May 8, 2001 4
Installing Your DeviceInstalling Your Device
Two install apisTwo install apis– UpdateDriverForPlugAndPlayDevicesUpdateDriverForPlugAndPlayDevices
Used if device has been plugged in.Used if device has been plugged in.– SetupCopyOEMInfSetupCopyOEMInf
Used if the inf is not being copied by the install.Used if the inf is not being copied by the install. Includes and Needs pragmasIncludes and Needs pragmas
– No recursion on W2KNo recursion on W2K No redistribution of system files - specify sourcediskfilesNo redistribution of system files - specify sourcediskfiles
– USBhub is always present on the system, so no need to copyUSBhub is always present on the system, so no need to copy– USBhub no longer backward compatible on W2K.USBhub no longer backward compatible on W2K.
New section suffixes: .ntx86, .ntia64, see DDK for more.New section suffixes: .ntx86, .ntia64, see DDK for more.
May 8, 2001 5
Driver BasicsDriver Basics
Think in terms of multithreadedThink in terms of multithreaded– How many times should an URB be submitted? We’veHow many times should an URB be submitted? We’ve
seen the same one get submitted more than once.seen the same one get submitted more than once. Never make assumptions in filter driversNever make assumptions in filter drivers Tear down symbolic links on surprise removal IRPTear down symbolic links on surprise removal IRP
– IoSetDeviceInterfaceState(&SymbolicLinkName, FALSE);IoSetDeviceInterfaceState(&SymbolicLinkName, FALSE); Synchronize requests with pnp Synchronize requests with pnp
– Wait for aborts to complete before completing remove.Wait for aborts to complete before completing remove.– IoReleaseRemoveLockAndWait is your friend.IoReleaseRemoveLockAndWait is your friend.
Don't leave a DbgBreakPoint in production code!Don't leave a DbgBreakPoint in production code!
May 8, 2001 6
Ping-Pong IRPsPing-Pong IRPs
Make sure not to recursively send ping-pong IRPMake sure not to recursively send ping-pong IRP On hot unplug, requests will complete quickly.On hot unplug, requests will complete quickly.
– Don’t spin tightly on requests when a device returns Don’t spin tightly on requests when a device returns error. Make sure to wait a while before re-submitting.error. Make sure to wait a while before re-submitting.
When you create an IRP and specify a completion When you create an IRP and specify a completion routine, don't call IoMarkIRPPending in the routine, don't call IoMarkIRPPending in the completion routine. completion routine. – There’s no more stack locations. <boom!>There’s no more stack locations. <boom!>
May 8, 2001 7
USB Hand GrenadeUSB Hand Grenade
Freeing the URB/IRP while it is pending in the USB stackFreeing the URB/IRP while it is pending in the USB stack Don't free anything attached to an active requestDon't free anything attached to an active request Concept of ownershipConcept of ownership
– Just because IoCancelIRP called, doesn't mean that the IRP is Just because IoCancelIRP called, doesn't mean that the IRP is yours yetyours yet
– To guard, make sure to wait for completion routine to get hitTo guard, make sure to wait for completion routine to get hit In IRP_MN_REMOVE, can wait forever for requests to In IRP_MN_REMOVE, can wait forever for requests to
completecomplete– IoReleaseRemoveLockAndWaitIoReleaseRemoveLockAndWait
May 8, 2001 8
Timing Out RequestsTiming Out Requests
USB stack has no concept of timing out requestsUSB stack has no concept of timing out requests Client driver's responsibility to timeout their own Client driver's responsibility to timeout their own
requestsrequests– Otherwise, the request might stay on the HW getting Otherwise, the request might stay on the HW getting
NAK'ed the whole timeNAK'ed the whole time Cancel after timeout case. Cancel after timeout case.
– If you created the IRP, better have a completion routine!If you created the IRP, better have a completion routine! USB specific Abort pipe USB specific Abort pipe
– Keep track of outstanding requests and wait forKeep track of outstanding requests and wait forrequests to completerequests to complete
May 8, 2001 9
Isochronous DevicesIsochronous Devices
Need to be able to turn around requests quickly.Need to be able to turn around requests quickly. Put out two 4 ms frames -> Can’t keep up.Put out two 4 ms frames -> Can’t keep up. Submit two 32 ms frames and then party on one Submit two 32 ms frames and then party on one
while it's pending -> Uh… Bad!while it's pending -> Uh… Bad! To get low latency use To get low latency use many many small requests.small requests. Proper solution: Proper solution:
– Put down eight 4-ms requests.Put down eight 4-ms requests.
May 8, 2001 10
Bus InterfaceBus Interface
Available in W2K, WinME, and XPAvailable in W2K, WinME, and XP Can be called at high IRQLCan be called at high IRQL Expandable by specifying higher version numberExpandable by specifying higher version number IsDeviceHighSpeedIsDeviceHighSpeed Example: Example:
– Is my device high speed?Is my device high speed?– Allows driver writer to write one driverAllows driver writer to write one driver
May 8, 2001 11
High-Speed USBHigh-Speed USB
Making a device that works both 1.1 and 2.0. Making a device that works both 1.1 and 2.0. – Mostly only an issue when working with ISO. Mostly only an issue when working with ISO.
Don't assume that there is still a max packet size Don't assume that there is still a max packet size of 64 bytes. of 64 bytes. – Retrieve it from endpoint descriptor. Potential max of Retrieve it from endpoint descriptor. Potential max of
512 bytes.512 bytes. Microframes - 8 microframes whereas there is Microframes - 8 microframes whereas there is
only one frame on 1.1only one frame on 1.1– 32 packets would have gone in 32 frames previously. 32 packets would have gone in 32 frames previously.
One frame is still 1 ms, but there are 8 microframes per One frame is still 1 ms, but there are 8 microframes per frame. So queuing 32 packets will go over 4 frames. frame. So queuing 32 packets will go over 4 frames.
May 8, 2001 12
Power Management on USBPower Management on USB
Device States:Device States:– D0 is onD0 is on– D2 is suspend. i.e. <= 500 uAD2 is suspend. i.e. <= 500 uA– D3 is off D3 is off
Once the hub PDO is not in D0, all requests will fail, so… Once the hub PDO is not in D0, all requests will fail, so… – Cancel all pending requests before you send on the power Cancel all pending requests before you send on the power
down request to the hub PDO.down request to the hub PDO. Don’t forget, power dispatch should at least have: Don’t forget, power dispatch should at least have:
– PoStartNextPowerIRP, PoStartNextPowerIRP, – IoSkipCurrentIRPStackLocation IoSkipCurrentIRPStackLocation – PoCallDriverPoCallDriver
May 8, 2001 13
Selective SuspendSelective Suspend
Allows bus to go to low power while PC is onAllows bus to go to low power while PC is on Allows processor to go to C3 and save batteryAllows processor to go to C3 and save battery Understand the difference between system power Understand the difference between system power
down and selective power downdown and selective power down– Track system power state, so that you don't power up Track system power state, so that you don't power up
without receiving a corresponding S0 IRPwithout receiving a corresponding S0 IRP USBhub does not power manage its PDOSUSBhub does not power manage its PDOS
– Whenever an idle IRP completes, must understand Whenever an idle IRP completes, must understand what power state you're inwhat power state you're in
See “SelSus” DDK example for more infoSee “SelSus” DDK example for more info
May 8, 2001 14
Testing Tips and ToolsTesting Tips and Tools
Run the driver verifier!Run the driver verifier!– More tests every dayMore tests every day
Test devicesTest devices– On all flavors - UHCI, OHCI and now EHCI. On all flavors - UHCI, OHCI and now EHCI. – On both XP and Win2KOn both XP and Win2K– While connected to an external hubWhile connected to an external hub
Slight electrical differences - overcurrent protection...Slight electrical differences - overcurrent protection...
Test unplugging devicesTest unplugging devices– While in useWhile in use– While in low-power modeWhile in low-power mode– While selectively suspendedWhile selectively suspended
May 8, 2001 15
Call to Action!Call to Action!
Use DDK tools like GenINF and CheckINFUse DDK tools like GenINF and CheckINF Run appropriate WHQL HCT Kits on your devicesRun appropriate WHQL HCT Kits on your devices
– www.microsoft.com/hwtestwww.microsoft.com/hwtest The Windows XP DDK has the most recentThe Windows XP DDK has the most recent
sample codesample code– DDK Developer / Product Support offers various DDK Developer / Product Support offers various
support options support options Contact the OEM / IHV Recon teams Contact the OEM / IHV Recon teams Subscribe to the Windows Hardware NewsletterSubscribe to the Windows Hardware Newsletter
– http://www.microsoft.com/http://www.microsoft.com/hwdevhwdev