Us bdrv tips2

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

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)

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;
…
};

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.

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.

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

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.

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 ; }

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

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 met
1. transfer URB using the
USBD_START_ISO_TRANSFER_A
SAP
2. The endpoint has been used with the
USBD_START_ISO_TRANSFER_A
SAP flag since the last reset
One of Two Problems will Occur
1. The URB arrives more than 256
frames too early
2. 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) {
DEFAULT_LATENCY;
}
}
endpoint->NextTransferStartFrame = StartFrame +
FrameCount
}
else{
StartFrame = Urb->StartFrame;
}
QueueUrb(StartFrame, Urb);
return STATUS_PENDING;
}

Flag For Windows XP
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)=1029
3. URB is scheduled starting at frame 5
4. Second URB arrives at frame 512
5. Second URB is scheduled starting at
frame (512+5)=517
If(FLAG(USBD_START_ISO_TRANSFER_ASAP))
{
if(endpoint->state==ENDPOINT_FIRST_USE){
DEFAULT_LATENCY; }
else {
StartFrame =
endpoint->NextTransferStartFrame;
DEFAULT_LATENCY;
}
}
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

Flag For Windows XP
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)=1029
3. URB is scheduled starting at frame 5
4. Second URB arrives at frame 1200
5. Second URB is scheduled starting at
scheduled time, frame 1029, first 170
packets are late!!!
{
DEFAULT_LATENCY; }
else {
StartFrame =
DEFAULT_LATENCY;
}
}
}
else{
Frame 0
1
2
3
4
5
Urb 1
Urb 2
Frame 517 Frame 1028
Frame 1200

Flag For Windows XP
Potential Workarounds
1. reset the pipe before sending
every URB
2. Do not stream URBs from
multiple threads
3. 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
{
DEFAULT_LATENCY; }
else {
StartFrame =
DEFAULT_LATENCY;
}
}
}
else{

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

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_S
TATUS 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 ;
. .
} ;

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.

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); }

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

Configuration Descriptors For Composite Devices
Configuration descriptor returned to
Function PDO 1
USB_CONFIGURATION_DESCRIPTOR
bNumInterfaces = 2
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 0
Configuration descriptor returned to
function PDO 2
bNumInterfaces = 1
bNumInterfaces = 3
USB_INTERFACE_ASSOCIATION_DESCRIPTOR
bFirstInterface = 0
bNumInterfaces = 2

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

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.

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

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

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;

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:
------------------

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.

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

Resources
Microsoft Resources
 www.microsoft.com/whdc
 www.microsoft.com/whdc/system/bus/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/us
 USB CCID Smart Card Readers:
www.microsoft.com/whdc/device/input/smartcard/U

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.

Us bdrv tips2

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Was ist angesagt?

Was ist angesagt? (20)

Andere mochten auch

Andere mochten auch (13)

Ähnlich wie Us bdrv tips2

Ähnlich wie Us bdrv tips2 (20)

Us bdrv tips2