USB Address Description Test with enhanced logging for debugging

  • Article

Note  This content applies to the Windows Logo Kit (WLK). For the latest information using the new Windows Hardware Certification Kit (HCK), see Windows HCK User's Guide on the Windows Hardware Dev Center.

Type: Manual Test

Overview

A USB device must respond correctly to all possible USB device addresses from 0 through 127. This test verifies that devices can respond correctly at their assigned addresses and that they do not respond at any other address.

This version of the USB Address Description Test incorporates ETW events generated in the USB PORT driver into the log for debugging purposes. This test is not required to get a logo. See "Log Interpretation" below for details on interpreting the additional log information.

Details

The test includes the following parts:

Setup

This test fails if the test device is more than one hub deep. The test should be run with a USB-IF certified hub with less than seven ports.

Note  For embedded USB devices (for example, laptop devices) where it is impossible to meet the external hub connectivity requirement, follow these steps:

  1. Select the job USB Address Description Test with enhanced logging for debugging from the Available jobs pane in the Device Console.

  2. Click the Add Selected button on the Device Console. The selected job shows up in the bottom pane.

  3. Select this job from the bottom pane. Right-click it and select Edit Parameters.

  4. You will see the Parameter Edit window open, with parameters listed on the left and their values on the right.

  5. Change the value of IsEmbeddedUSBDevice parameter from FALSE to TRUE.

  6. To run this job, click the Schedule Jobs button on the Device Console.

Initialization

  1. Select device to test.

  2. Open handle to host controller.

  3. Gather initial information:

    • Device descriptor
    • Configuration descriptor
    • String descriptors (if supported by device and test)

Address test #1 (repeat for all addresses)

  1. Reset device port .

  2. Get descriptors (device, configuration, string) from address 0.

  3. Set device address (next address value not in use).

  4. Get descriptors using address 0 (device should not respond).

  5. Get descriptors using new address (device should respond).

  6. Compare descriptors to initial information.

Address test #2 (repeat for all addresses)

  1. Reset device port (first time only).

  2. Set address (next address value not in use).

  3. Get descriptors from previous address (device should not respond).

  4. Get descriptors from new address (device should respond).

  5. Compare descriptors to initial information.

Results

For success, a device must always respond with valid device, configuration, and string descriptors while not responding at its previous device address. Any failure is a test failure.

Results Interpretation

The test fails if any of the following occurs:

  • Any standard device request is not properly handled by the device being tested.

  • Any standard device request does not meet the response time requirements as defined in the USB specification.

  • A device fails to respond to a request at its currently assigned address.

  • A device responds at an address other than its currently assigned address.

Log Interpretation

Events logged:

  1. RAW_RESET_PORT_DISPATCH a. Occurs when a port reset is initiated b. Includes the following data:
    • Timestamp
    • Host Controller Address
    • Port Number
  2. RAW_RESET_PORT_STATUS1 a. Indicates the status after SetFeaturePortPower b. Includes the following data:
    • Timestamp
    • Host Controller Address
    • Port Number
    • Port Status
  3. RAW_RESET_PORT_STATUS2 a. Indicates the status after SetFeaturePortReset b. Includes the same data as STATUS1
  4. RAW_RESET_PORT_STATUS3 a. Indicates the status after ClearFeaturePortResetChange b. Includes the same data as STATUS1
  5. RAW_RESET_PORT_COMPLETE a. Indicates the port reset has completed b. Includes the following data:
    • Timestamp
    • Host Controller Address
    • Port Number
    • USB Status
  6. SEND_ONE_PACKET_DISPATCH a. Occurs when a packet is sent to the device b. Includes the following data:
    • Timestamp
    • Host Controller Address
    • Packet Information:
      • Device Address
      • Endpoint Address
      • Maximum Packet Size
      • Timeout
      • USB Packet Flags
      • Data Length
      • Hub Device Address
      • Port TT Number
      • Usbd Status
  7. SEND_ONE_PACKET_DISPATCH_DATA a. Occurs after a packet dispatch to log the raw data in the transaction b. In addition to all the information in PACKET_DISPATCH, includes raw packet data in hexadecimal format
  8. SEND_ONE_PACKET_TIMEOUT a. Indicates that the request to the device timed out b. Includes the same data as PACKET_DISPATCH
  9. SEND_ONE_PACKET_COMPLETE a. Indicates the request completed b. Includes the same data as PACKET_DISPATCH and USB Status
  10. SEND_ONE_PACKET_COMPLETE_DATA a. Occurs after the packet completion to log any raw data in the transaction b. Includes the following data:
    • Timestamp
    • Host Controller Address
    • Packet info (see above)
    • Raw packet data in hexadecimal format

Timestamp Interpretation:

Important  The standard timestamp tag on the log entry does not accurately represent the time the ETW event occurred. Refer to the event timestamp logged with the data to get accurate timing information. There is a delay between when the ETW events occur and when they are published to the log. This creates a chronological disparity between the standard log entries and the ETW entries. When correlating events in the log, be sure to use the event timestamp when reconstructing the data.

Port Status Interpretation:

Refer to the following sections of "Universal Serial Bus Specification Revision 2.0" to interpret the port status:

  • 11.24.2.7 - Get Port Status

  • 11.24.2.7.1 - Port Status Bits

  • Table 11-21 - Port Status Field, wPortStatus

Run Time: 10 minutes

Log File: usbhct_a.log

System Restart Required: No

Supported operating systems for testing:

  • Windows 7

Program: usbhct.exe

Requirements

Software Requirements

The test tool requires the following software:

  • Supported operating system (see list above)

  • Software components included with the device that is being tested

Hardware Requirements

The test tool requires the following hardware:

  • Device to be tested

  • Computer that meets the minimum software requirements

Processor

The test tool runs on the following processor architectures:

  • x86

  • x64

  • IA64

Running the Test

All test cases return Pass or Fail. Because this test is not required to run to get a logo, it will not show up in device console when making a submission. To run this test in the DTM, please see How to Manually Schedule USB DTM Jobs.

Command Syntax

Command option Description

usbhct.exe

Without any options, displays usage text

-a

Specifies to run the address test

-d [VID/PID]

Specifies the device VID XXXX, and PID YYYY

-l [string]

Log file name. ex: "addrtest.log"

-w

Enable ETW tracing in the logs

 

Code Tour

File Manifest

File Location

usbhct.exe

[WTT\TestBinRoot]\nttest\driverstest\usb\

hctrans.dll

[WTT\TestBinRoot]\nttest\driverstest\usb\

usbtree.dll

[WTT\TestBinRoot]\nttest\driverstest\usb\

ETWCap.dll

[WTT\TestBinRoot]\nttest\driverstest\usb\ETWCap\

USBRefresh.exe

[WTT\TestBinRoot]\nttest\driverstest\usb\

 

 

 

Build date: 9/14/2012