Setting Up Kernel-Mode Debugging over a USB 2.0 Cable Manually

Debugging Tools for Windows supports kernel debugging over a USB 2.0 debug cable. The easiest way to set up USB 2.0 debugging is to use Visual Studio. Fore more information, see Setting Up a USB 2.0 Connection in Visual Studio. If you choose not to use Visual Studio, you can set up USB 2.0 debugging manually, as described in this topic.

The computer that runs the debugger is called the host computer, and the computer being debugged is called the target computer. The host computer must be running a version of the operating systems starting with Windows 2000 through Windows 8, and the target computer must be running either Windows Vista, Windows 7, or Windows 8. USB debugging does not work over a hub or docking station.

Debugging over a USB 2.0 cable requires the following hardware:

• A USB 2.0 debug cable. This cable is not a standard USB 2.0 cable because it has an extra hardware component that makes it compatible with the USB2 Debug Device Functional Specification. You can find these cables with an Internet search for the term USB 2.0 debug cable.

• The host computer must have a USB 2.0 controller that is compatible with the Enhanced Host Controller Interface (EHCI) specification.

• The target computer must have a USB 2.0 controller that is compatible with the EHCI specification and that supports kernel debugging. Not all EHCI-compatible controllers have this support.

Setting Up the Target Computer

To set up the target computer, follow these steps:

1. On the target computer, in an elevated Command Prompt window, enter the following command:

   bcdedit /debug off

2. Reboot the target computer.
3. On the target computer, launch the UsbView tool. The UsbView tool is included in the Debugging Tools for Windows package.
4. In UsbView, locate all of the host controllers that are compatible with the EHCI specification. For example, you could look for controllers that are listed as Enhanced.
5. To find a physical USB connector that you can use for kernel debugging, plug any USB 2.0 device into any physical USB connector on the target computer. Refresh UsbView to see where your device is located. If you plugged your device into Port 1 under a controller that supports EHCI, then you have found a physical USB connector that you can use for kernel debugging. You might need to repeat this experiment with different physical USB connectors. It could be that there is no external physical USB connector that is exposed as Port 1 under an EHCI controller. In that case, you can look for a physical USB connector inside the computer. Perform the same steps to determine whether the internal USB connector is suitable for kernel debugging. If you cannot find a physical USB connector (either external or internal) that is exposed as Port 1 under an EHCI controller, then you cannot use the computer as a target for USB kernel debugging.
6. Note the number of the USB host controller that you intend to use for debugging on the target computer. Open Device Manager and locate that host controller. View the properties for the host controller to determine its PCI bus, device, and function numbers.

7. On the target computer, in an elevated Command Prompt window, enter one of the following sets of commands, depending on the version of Windows that is running on the target computer.

   Windows 7

   bcdedit /debug on

   bcdedit /dbgsettings usb targetname:someName

   bcdedit /set {dbgsettings} busparams x.y.z

   where x, y, and z are the bus, device, and function numbers for the host controller. The bus, device, and function numbers must be in decimal format (for example, busparams 0.29.7).

   Windows Vista

   bcdedit /debug on

   bcdedit /dbgsettings usb targetname:someName

   bcdedit /set {current} loadoptions busparams=x.y.z

   where x, y, and z are the bus, device, and function numbers for the host controller. The bus, device, and function numbers must be in hexadecimal format (for example, busparams=0.1D.7).

   In the preceding sets of commands, the target name someName can be any string; it does not have to be the official name of the target computer. You will need the target name later when you start a kernel debugging session from the host computer.

8. Reboot the target computer.

Setting Up the Host Computer

1. Use your USB 2.0 debug cable to connect the host and target computers. Recall that on the host computer you must use a USB 2.0 host controller that is compatible with the EHCI specification.

2. On the host computer, the USB debug driver might get installed automatically, or you might have to install it manually. To install the driver manually, perform the following steps:

   1. In Device Manager, locate the node that represents your USB 2.0 debug cable.
   2. In the property pages for that node, choose to update or install the driver.
   3. As you go through the driver installation wizard, navigate to the usb2dbg.inf file in the Debugging Tools for Windows package.
   4. Complete the driver installation wizard.

Starting the Debugging Session

Using WinDbg

On the host computer, open WinDbg. On the File menu, choose Kernel Debug. In the Kernel Debugging dialog box, open the USB 2.0 tab. Enter the target name that you created when you set up the target computer. Click OK.

You can also start a session with WinDbg by entering the following command in a Command Prompt window, where TargName is the target name you created when you set up the target computer:

windbg /k usb2:targetname=TargName

Using KD

On the host computer, open a Command Prompt window and enter the following command, where TargName is the target name you created when you set up the target computer:

kd /k usb2:targetname=TargName

Additional Support

For troubleshooting tips and detailed instructions on setting up kernel debugging over USB, search for "Setting Up Kernel Debugging with USB 2.0" in MSDN Blogs.

You can request additional support by sending mail to usbdbg@microsoft.com.

Send comments about this topic to Microsoft

Build date: 4/9/2013