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