USB Client Driver Etiquette

1
(No Transcript)
2
USB Client Driver Etiquette

• Jay Senior
• Windows Base Developer
• Microsoft

3
Agenda

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

4
Installing Your Device

• Two install apis
• UpdateDriverForPlugAndPlayDevices
• Used if device has been plugged in.
• SetupCopyOEMInf
• Used if the inf is not being copied by the
  install.
• Includes and Needs pragmas
• No recursion on W2K
• 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.
• New section suffixes .ntx86, .ntia64, see DDK
  for more.

5
Driver Basics

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

6
Ping-Pong IRPs

• Make sure not to recursively send ping-pong IRP
• On hot unplug, requests will complete quickly.
• Dont spin tightly on requests when a device
  returns error. Make sure to wait a while before
  re-submitting.
• When you create an IRP and specify a completion
  routine, don't call IoMarkIRPPending in the
  completion routine.
• Theres no more stack locations. ltboom!gt

7
USB Hand Grenade

• Freeing the URB/IRP while it is pending in the
  USB stack
• Don't free anything attached to an active request
• 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
• In IRP_MN_REMOVE, can wait forever for requests
  to complete
• IoReleaseRemoveLockAndWait

8
Timing Out Requests

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

9
Isochronous Devices

• Need to be able to turn around requests quickly.
• Put out two 4 ms frames -gt Cant keep up.
• Submit two 32 ms frames and then party on one
  while it's pending -gt Uh Bad!
• To get low latency use many small requests.
• Proper solution
• Put down eight 4-ms requests.

10
Bus Interface

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

11
High-Speed USB

• Making a device that works both 1.1 and 2.0.
• Mostly only an issue when working with ISO.
• Don't assume that there is still a max packet
  size of 64 bytes.
• Retrieve it from endpoint descriptor. Potential
  max of 512 bytes.
• 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.

12
Power Management on USB

• Device States
• D0 is on
• D2 is suspend. i.e. lt 500 uA
• D3 is off
• 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.
• Dont forget, power dispatch should at least
  have
• PoStartNextPowerIRP,
• IoSkipCurrentIRPStackLocation
• PoCallDriver

13
Selective Suspend

• Allows bus to go to low power while PC is on
• Allows processor to go to C3 and save battery
• 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
• USBhub does not power manage its PDOS
• Whenever an idle IRP completes, must understand
  what power state you're in
• See SelSus DDK example for more info

14
Testing Tips and Tools

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

15
Call to Action!

• Use DDK tools like GenINF and CheckINF
• Run appropriate WHQL HCT Kits on your devices
• www.microsoft.com/hwtest
• The Windows XP DDK has the most recentsample
  code
• DDK Developer / Product Support offers various
  support options
• Contact the OEM / IHV Recon teams
• Subscribe to the Windows Hardware Newsletter
• http//www.microsoft.com/hwdev