More Related Content
Similar to Us bdrv tips2 (20)
Us bdrv tips2
- 1. 1 © 2003 Microsoft Corporation. All rights reserved.
Jason Kace
WDEG – USB Core Team
USB Client Driver Tips
And Tricks: Part Two
- 2. 2 © 2003 Microsoft Corporation. All rights reserved.
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. 3 © 2003 Microsoft Corporation. All rights reserved.
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. 4 © 2003 Microsoft Corporation. All rights reserved.
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. 5 © 2003 Microsoft Corporation. All rights reserved.
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. 6 © 2003 Microsoft Corporation. All rights reserved.
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. 7 © 2003 Microsoft Corporation. All rights reserved.
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. 8 © 2003 Microsoft Corporation. All rights reserved.
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. 9 © 2003 Microsoft Corporation. All rights reserved.
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. 10 © 2003 Microsoft Corporation. All rights reserved.
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) {
StartFrame = CurrentFrame +
DEFAULT_LATENCY;
}
}
endpoint->NextTransferStartFrame = StartFrame +
FrameCount
}
else{
StartFrame = Urb->StartFrame;
}
QueueUrb(StartFrame, Urb);
return STATUS_PENDING;
}
- 11. 11 © 2003 Microsoft Corporation. All rights reserved.
Using The USBD_START_ISO_TRANSFER_ASAP
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
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; }
Frame 0 Frame 2048
1
2
3
4
5
Urb 1
Urb 2
Frame 517 Frame 1028
- 12. 12 © 2003 Microsoft Corporation. All rights reserved.
Using The USBD_START_ISO_TRANSFER_ASAP
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!!!
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; }
Frame 0
1
2
3
4
5
Urb 1
Urb 2
Frame 517 Frame 1028
Frame 1200
- 13. 13 © 2003 Microsoft Corporation. All rights reserved.
Using The USBD_START_ISO_TRANSFER_ASAP
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
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; }
- 14. 14 © 2003 Microsoft Corporation. All rights reserved.
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. 15 © 2003 Microsoft Corporation. All rights reserved.
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 ;
. .
} ;
- 16. 16 © 2003 Microsoft Corporation. All rights reserved.
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. 17 © 2003 Microsoft Corporation. All rights reserved.
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. 18 © 2003 Microsoft Corporation. All rights reserved.
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. 19 © 2003 Microsoft Corporation. All rights reserved.
Configuration Descriptors For Composite Devices
Configuration descriptor returned to
Function PDO 1
USB_CONFIGURATION_DESCRIPTOR
bNumInterfaces = 2
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 0
USB_ENDPOINT_DESCRIPTOR
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 1
USB_ENDPOINT_DESCRIPTOR
Configuration descriptor returned to
function PDO 2
USB_CONFIGURATION_DESCRIPTOR
bNumInterfaces = 1
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 2
USB_ENDPOINT_DESCRIPTOR
USB_CONFIGURATION_DESCRIPTOR
bNumInterfaces = 3
USB_INTERFACE_ASSOCIATION_DESCRIPTOR
bFirstInterface = 0
bNumInterfaces = 2
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 0
USB_ENDPOINT_DESCRIPTOR
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 1
USB_ENDPOINT_DESCRIPTOR
USB_INTERFACE_DESCRIPTOR
bInterfaceNumber = 2
USB_ENDPOINT_DESCRIPTOR
- 20. 20 © 2003 Microsoft Corporation. All rights reserved.
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. 21 © 2003 Microsoft Corporation. All rights reserved.
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. 22 © 2003 Microsoft Corporation. All rights reserved.
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. 23 © 2003 Microsoft Corporation. All rights reserved.
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
- 24. 24 © 2003 Microsoft Corporation. All rights reserved.
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. 25 © 2003 Microsoft Corporation. All rights reserved.
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. 26 © 2003 Microsoft Corporation. All rights reserved.
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. 27 © 2003 Microsoft Corporation. All rights reserved.
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. 28 © 2003 Microsoft Corporation. All rights reserved.
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. 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.