© 2003 Microsoft Corporation. All rights reserved. 1 Jason Kace WDEG – USB Core Team USB Client Driver Tips And Tricks: Part Two

1

© 2003 Microsoft Corporation. All rights reserved.

Jason KaceWDEG – USB Core Team

USB Client Driver Tips And Tricks: Part Two

2


Agenda Part Two

Tips and tricks you may not already know USB Transfer sizes

Device configuration tips

Recommended URB error recovery steps

Working with isochronous transfers

USB power management tips

Limitations of composite device support

XP selective suspend rules summary

Common driver errors Common URB/IRP handling errors

Tips on debugging common USB problems Bugcheck FE

Device fails to start (Code 10)

3


USB Transfers

What is a USB Transfer Bulk Interrupt Isochronous Control

USB TransferBuffer All Buffers should be allocated

from the nonpaged pool. Not necessary to create a MDL

USB Pipes One pipe for each open

endpoint SELECT_CONFIGURATION or

SELECT_INTERFACE requests return a PipeHandle.

UrbLink field must be NULL!!!

Struct

URB_BULK_OR_INTERRUPT_TRANSFER {

struct _URB_HEADER Hdr;

USBD_PIPE_HANDLE PipeHandle;

ULONG TransferFlags;

ULONG TransferBufferLength;

PVOID TransferBuffer;

PMDL TransferBufferMDL;

struct _URB *UrbLink;

…

};

4


Transfer Type MaximumTransferSize Error Reported

Control Endpoint 0 4k Error

Control (Other Endpoints)

64K Undetermined

Interrupt Unlimited None

UHCI Bulk Unlimited None

OHCI Bulk Effectively Unlimited(See note below)

None

EHCI Bulk

USB Maximum Transfer Sizes For Windows 2000

Comments Drivers should be aware of performance and resource trade-offs when using large

transfer sizes.

Use of very large bulk or interrupt transfers are not recommended due to resource limitations exposed by the OHCI driver.

Requests on the default control endpoint are limited to 4k for compatibility with older driver versions. The USB Specification limits other control transfers to 64k.

5


Transfer Type MaximumTransferSize Error Reported

Control Endpoint 0 4k Error

Control (Other Endpoints)

64K Undetermined

Interrupt Unlimited None

UHCI Bulk Unlimited None

OHCI Bulk 256k Bugcheck 0xFE

EHCI Bulk 4 MB Bugcheck 0xFE

USB Maximum Transfer Sizes For Windows XP And Later

Comments Table represents theoretical limits, not practical limits Drivers should be aware of performance and resource trade-offs when using large

transfer sizes. Use of very large transfers is not recommended Requests on the default control endpoint are limited to 4k for compatibility with older

driver versions. The USB Specification limits other control transfers to 64k.

6


Using The MaximumTransferSize Field

Used with the following URB requests: SELECT_CONFIGURATION

SELECT_INTERFACE

The MaximumTransferSize Field:

struct USBD_PIPE_INFORMATION

{

USHORT MaximumPacketSize ;

UCHAR EndpointAddress ;

UCHAR Interval ;

USBD_PIPE_TYPE PipeType

USBD_PIPE_HANDLE PipeHandle ;

ULONG MaximumTransferSize ;

. . .

}

Version Input Output Error

Windows 2000

Required None None

Windows XP, Server 2003

Not Used Not Used None

Longhorn Not Used Maximum Transfer Size allowed

TBD

7


Device Configuration Tips

Selecting a configuration that requires more power than the port can provide may result in the device being removed

USBD_PF_CHANGE_MAX_PACKET pipe flag Not needed to set the MaximumTransferSize for a pipe. Used only to override the MaximumPacketSize indicated in the

USB_ENDPOINT_DESCRIPTOR

URB_FUNCTION_SELECT_INTERFACE Can be used to set the MaximumTransferSize of MaximumPacketSize for a

pipe. Can be used to enable alternate interface settings

Composite Devices Setting the MaximumTransferSize in Windows 2000:

The parent driver will automatically set the transfer size to 4k. Drivers may not set this field.

Setting the MaximumTransferSize in Windows XP and Later:Driver may set the MaximumTransferSize via a SELECT_CONFIGURATION or

SELECT_INTERFACE request.

8


Working With Isochronous Transfers

2 Methods to send Iso transfers

1. Set the StartFrame manually

2. Let the bus driver schedule the transfer as soon as possible by setting the USBD_START_ISO_TRANSFER_ASAP flag

struct URB_ISOCH_TRANSFER{

struct _URB_HEADER Hdr;

USBD_PIPE_HANDLE PipeHandle;

ULONG TransferFlags;

ULONG TransferBufferLength;

PVOID TransferBuffer;

PMDL TransferBufferMDL;

ULONG StartFrame;

ULONG NumberOfPackets;

ULONG ErrorCount;

USBD_ISO_PACKET_DESCRIPTOR Packet[1];}

struct USBD_ISO_PACKET_DESCRIPTOR {

ULONG Offset ;

ULONG Length ;

USBD_STATUS Status ; }

9


Setting The StartFrame Manually

For Windows XP and later, if the start frame is not within +/-USBD_ISO_START_FRAME_RANGE of the current frame the URB will fail with USBD_STATUS_BAD_START_FRAME

For Windows XP and later, individual ISO packets will be returned with USBD_STATUS_ISO_NOT_ACCESSED_LATE if they could not be scheduled as indicated by the start frame.

For Windows 2000 this behavior varies by controller flavor

10


Using The USBD_START_ISO_TRANSFER_ASAP Flag For Windows XP

Microsoft Windows XP Isochronous Transfer Code Example (Not Actual Code) on the right

The problem occurs when the following conditions are met1. transfer URB using the

USBD_START_ISO_TRANSFER_ASAP

2. The endpoint has been used with the USBD_START_ISO_TRANSFER_ASAP flag since the last reset

One of Two Problems will Occur1. The URB arrives more than 256

frames too early2. URB arrives late, but less than 256

frames too late

DispatchIsochTransferURB {

If( FLAG(USBD_START_ISO_TRANSFER_ASAP) ) {

if (endpoint->state == ENDPOINT_FIRST_USE) {

StartFrame = CurrentFrame + DEFAULT_LATENCY; }

else {

StartFrame = endpoint->NextTransferStartFrame;

if (ABS((CurrentFrame - StartFrame)) > 256) {

StartFrame = CurrentFrame + DEFAULT_LATENCY;

}

}

endpoint->NextTransferStartFrame = StartFrame + FrameCount

}

else{

StartFrame = Urb->StartFrame;

}

QueueUrb(StartFrame, Urb);

return STATUS_PENDING;

}

11



Problem: URB arrives more than 256 frames earlier than scheduled.

Sequence:1. First URB arrives at frame 0.

StartFrame = 5.2. StartFrame for next URB is set to

(5+1024)=10293. URB is scheduled starting at frame 54. Second URB arrives at frame 5125. Second URB is scheduled starting at

frame (512+5)=517


If(FLAG(USBD_START_ISO_TRANSFER_ASAP))

{

if(endpoint->state==ENDPOINT_FIRST_USE){


else {

StartFrame =endpoint-

>NextTransferStartFrame;



} }

endpoint->NextTransferStartFrame = StartFrame + FrameCount;

}

else{

StartFrame = Urb->StartFrame; }


return STATUS_PENDING; }

Frame 0 Frame 2048

1

2

3

4

5

Urb 1

Urb 2

Frame 517 Frame 1028

12



Problem: URB arrives less than 256 frames late

Sequence:1. First URB arrives at frame 0. StartFrame =

5.2. StartFrame for next URB is set to

(5+1024)=10293. URB is scheduled starting at frame 54. Second URB arrives at frame 12005. Second URB is scheduled starting at

scheduled time, frame 1029, first 170 packets are late!!!



{



else {





} }


}

else{




Frame 0

1

2

3

4

5Urb 1

Urb 2

Frame 517 Frame 1028

Frame 1200

13



Potential Workarounds1. reset the pipe before sending

every URB2. Do not stream URBs from

multiple threads3. Be careful when sending

multiple isochronous URB requests to prevent an URB from arriving more than 256 frames before it will be scheduled

Currently Affected Platforms Windows XP Windows Server 2003



{



else {





} }


}

else{




14


Working With Isochronous Transfers

Error recovery Isochronous endpoints should not halt.

However, requests may occasionally return errors and the pipe may need to be reset.

If the URB completes successfully, individual isochronous packets may still have failed with an error. Drivers should check the ErrorCount field of the URB for a non-zero value.

Sending multiple IRP/URB pairs It is possible to have multiple isochronous IRP/URB pairs pending in the bus

driver simultaneously

In some cases and IRP/URB pair may arrive too early or too late to be scheduled and will be completed with an error

15


USB Errors

Status Returned IRP Status URB Status

Endpoint Stall URB_FUNCTION_RESET_PIPE will

clear the stall and reset the data toggle

Port Disabled/Device Disconnected Check the port status via an

IOCTL_INTERNAL_USB_GET_PORT_STATUS request

If the port is disabled a driver can issue and IOCTL_INTERNAL_USB_RESET_PORT request to re-enable the port.

struct _URB_HEADER

{

USHORT Length ;

USHORT Function ;

USBD_STATUS Status ;

. .

} ;

16


Port Status Action

Disabled AND Connected IOCTL_INTERNAL_USB_RESET_PORT

Enabled AND Connected URB_FUNCTION_RESET_PIPE

Not Connected Prepare for Remove

Recommended procedure for recovery

1. URB_FUNCTION_ABORT_PIPE and wait until all pending IRPs have completed.

2. Request the port status via IOCTL_INTERNAL_USB_GET_PORT_STATUS

3. Follow action in table below

USB Transfer Error Recovery Procedure

Comments URB_FUNCTION_RESET_PIPE will reset the pipe and clear a stall condition on the endpoint

These requests should be called at PASSIVE_LEVEL

Drivers should always retry the transfer and check for errors.

17


More Things You Should Know About USB I/O

The client driver is responsible for sending zero-length packets to terminate non-control transfers

Maximum interrupt endpoint polling interval supported Full and High Speed Devices: 32

Low Speed Devices: 8

Higher bInterval values are rounded down.

Determining if a device is operating at high-speed USB 2.0 Compliant devices are not necessarily high-speed devices

The bus driver exposes an interface, IsDeviceHighSpeed, which will return the speed of the device. See the DDK for more information on querying for USB interfaces.

USB_BUS_INTERFACE_USBDI_V1 busInterface;

if (NT_SUCCESS(GetBusInterface(DeviceObject, &busInterface)))

{

DeviceExtension->DeviceIsHighSpeed =

busInterface.IsDeviceHighSpeed(busInterface.BusContext); }

18


Composite Devices

What is a composite device USB device with multiple functions. Each function may consist of

one of more interfaces.

All functions share a single USB port.

Microsoft supplies a parent driver to multiplex requests from multiple functions

Function 2Function 1

USBCCGP.SYS

USBHUB.SYS

USBPORT,SYS

Function 2Function 1

USBHUB.SYS

USBHUB.SYS

USBD,SYS

Driver Stack for Windows XP and later Driver stack for Windows 2000

19


Configuration Descriptors For Composite Devices

Configuration descriptor returned to Function PDO 1USB_CONFIGURATION_DESCRIPTOR

bNumInterfaces = 2

USB_INTERFACE_DESCRIPTORbInterfaceNumber = 0




Configuration descriptor returned to function PDO 2USB_CONFIGURATION_DESCRIPTOR

bNumInterfaces = 1



USB_CONFIGURATION_DESCRIPTOR

bNumInterfaces = 3

USB_INTERFACE_ASSOCIATION_DESCRIPTOR

bFirstInterface = 0

bNumInterfaces = 2

USB_INTERFACE_DESCRIPTOR

bInterfaceNumber = 0








20


Limitations Of Composite Device Support

Reseting or Cycling a Port IOCTL_INTERNAL_USB_CYCLE_PORT is only supported for Windows XP

and later Whenever a driver loaded for a composite PDO issues cycles or resets its

port, the operation will affect all function drivers for the device

Device Configuration Composite drivers may not use configurations other than configuration

index 0 The configuration and device descriptors returned to a driver loaded for a

composite PDO are not necessarily the same as the descriptors returned by the device

Power Management A device will be armed for wake if any single function driver requests an

IRP_MN_WAIT_WAKE Selective suspend for composite devices is currently NOT supported The completion of a device power IRP for a lower power state does not

imply the device is in that state

21


USB Power Management Tips

Waking the System All pending Wait-Wake IRPs will be completed with

STATUS_SUCCESS when the system wakes. There is currently no way to determine which device woke the system.

If a device generates wake signaling while the system is suspending, the device may not be armed for wake.

A USB hub may wake the system on connect/disconnect events. There is currently no way to control this behavior. This may change in the future.

Drivers should follow WDM rules for power management Cancel all pending transfers before sending a device power IRP for

a lower power state. Do not send any transfers until after a device power IRP for power

state D0 completes successfully. This may fail if the device is not present.

22


Selective Suspend Tips For Windows XP

Methods for Signaling that a Device is Idle Issue an IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION request to the

bus driver

Arming a Device for Wake Devices which do not need to wake the bus in response to external events should not

need to submit IDLE IRPs

If a device needs to arm itself to wake the bus it should send an IRP_MN_WAIT_WAKE irp as early as possible, preferably before its IDLE-IRP callback is invoked

Methods for Canceling an Idle request 1. Cancel the pending IDLE IRP

2. Device in power state D0 after returning from the IDLE-IRP callback routine

Methods for Waking the Bus Client driver issues a device power IRP for device state D0

A device on the bus generates wake signaling

23


Client Driver Selective Suspend Flowchart

Recommended client driver selective suspend behavior

Highlights Issue a WAIT_WAKE request as

early as possible

Bus will not suspend if device is in D0 after returning from the callback

Set Power D0 on successful completion of IDLE IRP

Comments about USB Selective Suspend

A Hub is not idle until all devices connected to it are idle

The controller will not suspend until all connected devices are idle

Devices should cancel all pending I/O requests in their callbacks, before powering down

Device Idle?

Idle = 1

Idle = 0

Submit idle-irp

Idle-irp complete

Idle-irpsuccess?

Set Power D0

Power==D0

Yes

Yes

No

No

Power==D0

Yes

Process Request

Stay in D2

Idle-irpPending?

Cancel Idle Irp

No

Yes

Yes

Idle-irppending?

No

Idle-irp Callback

Idle == 1

Set Power D2

No

Power ==D0

No

Goto START

Yes

Goto START

No

START

Wait for CallbackYes

Yes

No

Arm Device forWake

24


Common USB Driver Errors

Do not free an IRP or an associated URB before the IRP has completed.

Aborting Transfers Wait after sending an URB_FUNCTION_ABORT_PIPE request for all

pending transfer IRPs to complete

A driver should cancel all pending transfers before stopping, being removed or going to a lower power state

Canceling IRPs Do not assume an IRP has been cancelled if IoCancelIrp has returned (there

may not be a cancel routine!) The USB bus driver does not have a timeout for requests. The client must

cancel requests that have timed out. USB IRPs may not complete immediately after being cancelled. The client

must wait for the IRPs to complete.

Recycling URBs Ensure that the parent IRP for an URB has completed before resending the

URB If using a MDL, ensure that all PTEs are released before reusing;

25


USB Bugcheck Code 0xFE

INTERNAL_ERROR:

USBPORT internal error. Often a result of low resources or a driver submitting too large a transfer size.

BAD_URB:

The URB submitted is attached to a currently pending IRP.

MINIPORT_ERROR:

This is generally related to a hardware error.

IRP_URB_DOUBLE_SUBMIT:

The client had submitted an IRP that is already pending in the bus driver.

kd> !analyze -v

*******************************************************************************

* *

* Bugcheck Analysis *

* *

*******************************************************************************

BUGCODE_USB_DRIVER (fe)

USB Driver bugcheck, first parameter is USB bugcheck code.

Arguments:

Arg1: 00000004, IRP_URB_DOUBLE_SUBMIT The caller has submitted an irp

that is already pending in the USB bus driver.

Arg2: 866f92d8, Address of IRP

Arg3: 86709e38, Address of URB

Arg4: 00000000

Debugging Details:

------------------

26


Debugging Common USB Problems

Device Fails to Start (Code 10) The bus driver will fail a client driver start IRP if the device

Is unresponsive to bus driver requests for descriptors, configuration, and addressing

Cannot be reset

Client drivers often fail their start IRP if a SELECT_CONFIGURATION or GET_DESCRIPTOR request fails.

There is currently no way to identify the root cause of the failure in the bus driver. A client driver can set a completion routine for its start IRP and check the status code for more information.

USBD_STATUS codes Every completed URB contains an USBD_STATUS code. These codes are

defined in usb.h. This status is often more descriptive than the IRP status returned.

27


Debugging Common USB Problems

User notification The following events may result in a pop-up bubble notifying the

user of a problem

Overcurrent condition

Not enough power available on the port

Device hub is nested too deeply

Controller bandwidth exceeded

High speed device plugged into a non-high speed port

28


Resources

Microsoft Resources www.microsoft.com/whdc www.microsoft.com/whdc/system/b

us/usb/default.mspx

www.microsoft.com/downloads/results.aspx?productID=&freetext=USB&DisplayLang=en

MSDN Newsgroups Windows Development Device

Drivers Windows Development Windows

DDK

Industry Resources www.usb.org www.pcisig.com www.pcmcia.org

Technical Papers IAD & USB2 Debug Device:

developer.intel.com/technology/usb/spec.htm

Booting Windows from USB Storage Devices: www.microsoft.com/whdc/system/bus/usb/usb-boot.mspx

USB CCID Smart Card Readers:www.microsoft.com/whdc/device/input/smartcard/USB_CCID.mspx

http://www.microsoft.com/whdc

http://www.microsoft.com/whdc/system/%0Bbus/usb/default.mspx

http://www.microsoft.com/whdc/system/%0Bbus/usb/default.mspx

http://www.microsoft.com/downloads/%0Bresults.aspx?productID=&freetext=USB&DisplayLang=en



http://www.usb.org/

http://www.pcisig.com/

http://www.pcmcia.org/

http://developer.intel.com/technology/usb/spec.htm



http://www.microsoft.com/whdc/system/bus/%0Busb/usb-boot.mspx

http://www.microsoft.com/whdc/system/bus/%0Busb/usb-boot.mspx

http://www.microsoft.com/whdc/device/input/%0Bsmartcard/USB_CCID.mspx

http://www.microsoft.com/whdc/device/input/%0Bsmartcard/USB_CCID.mspx

29

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

Documents

© 2003 Microsoft Corporation. All rights reserved. 1 Jason Kace WDEG – USB Core Team USB Client Driver Tips And Tricks: Part Two