Setting Up USB KDNET EEM Kernel-Mode Debugging (KDNET-EEM-USB)

Debugging Tools for Windows supports kernel debugging over a USB cable using Ethernet Emulation Mode (EEM) This topic describes how to set up USB EEM using the kdnet.exe utility.

The computer that runs the debugger is called the host computer, and the computer being debugged is called the target computer.

Kernel-Mode USB EEM device requirements

The following is required:

• On the target computer, a Synopsys USB 3.0 controller connected to an USB type C port.

• On the host computer, an externally accesible USB 3.0 port is required.

• Windows 10 October 2020 Update (20H2) or later

The KDNET-EEM-USB transport can be configured for:

• PCI debug device. These debug devices are set using dbgsettings::busparams=seg.bus.dev.fun.
• ACPI-DBG2 Table debug devices. These debug devices are set using dbgsettings::busparams=1|2|3, which 1|2|3 points to specific the ACPI DBG2-Table array entry containing the debug device configuration.

Cable requirements

• A standard USB 3.0 Type C to Type A cable is required to connect the host type A port to the target type C port.

Binary transport files

Binaries kd_0C_8086.dll for x64, and kd_8003_5143.dll for ARM are used to support the KDNET-EEM-USB debugger transport.

Confirm that a supported USB controller is available on the target

On the target computer, launch Device Manager.

Confirm that the Synopsys USB 3.0 Dual-Role Controller is listed.

Determine the debugging port when multiple ports are available

After you have identified a port that supports debugging, the next step is to locate the physical USB connector that is associated with that port.

For example, on the Surface Pro X, use the lower of the two USB C ports is used for KDNET EEM debugging.

Use kdnet.exe to confirm device support and view the busparams value

Intel / AMD 64 devices

The BCDEDIT debug options are stored in the Boot Configuration Data (BCD) store. For more information, see BCDEdit /debug.

ARM devices

ARM devices use ACPI DBG2 table for configuring the debugger, where the busparams points to the DBG2 table entry. To specify the debugging port that will be used, busparm is used. Typically just the first busparam is used and it’s either 0 or 1 depending on the device. Typically, devices don't use busparams=0, since the 0 DBG2 table entry is normally reserved for the serial device COM. For more information on the ACPI DBG2 table, see Microsoft Debug Port Table 2 (DBG2).

Use kdnet.exe to configure KDNET EEM USB

Use the kdnet.exe utility to display the parameter information for controllers that support KDNET-EEM-USB transport debugging.

1. Confirm that the Windows Debugging Tools are installed on the host and target system. For information on downloading and installing the debugger tools, see Debugging Tools for Windows.

2. Locate the kdnet.exe utility. By default, the files are located here.

   C:\Program Files (x86)\Windows Kits\10\Debuggers\x64

3. On the target computer, open a Command Prompt window as Administrator. Enter this command to verify that the target computer has a supported network adapter and to view the busparams value.

   C:\KDNET>kdnet.exe
   
   Network debugging is not supported on any of the NICs in this machine.
   KDNET supports NICs from Intel, Broadcom, Realtek, Atheros, Emulex, Mellanox
   and Cisco.
   
   Network debugging is supported on the following USB controllers:
   busparams=1, Device-mode USB controller with Vendor ID: 5143 (Default)
   busparams=2, Device-mode USB controller with Vendor ID: 5143
   busparams=3, Device-mode USB controller with Vendor ID: 5143
   busparams=4, Device-mode USB controller with Vendor ID: 5143
   
   This Microsoft hypervisor supports using KDNET in guest VMs.
   

4. As the output from kdnet.exe indicates that a supported USB controller with a busparams value of 1 is available, we can proceed.

Setting Up the Target Computer

Use the kdnet.exe utility to configure the debugger settings on the target PC, by following these steps.

1. Use the command shown below to set the, busparams value, the IP address and the port of the host system and generated a unique connection key. The 169.254.255.255 IP address is used for all USB EMM connections.

2. Pick a unique port address for each target/host pair that you work with, within the recommended range of 50000-50039. 50005 is shown in the example.

   C:\>kdnet.exe 169.254.255.255 50005

   Enabling network debugging on Intel(R) 82577LM Gigabit Network Connection.
   Key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p

3. Copy the returned key into a notepad .txt file. In the example shown, the generated key has a value of:

   2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p

4. Use the BCDEdit command to check that the parameters are as expected. For more information, see BCDEdit /dbgsettings

   C:\>bcdedit /dbgsettings

   busparams               1
   key                     2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
   debugtype               NET
   hostip                  169.254.255.255
   port                    50005
   dhcp                    No
   The operation completed successfully.

Disable the firewall on the host

On the host, disable the firewall for the debugger.

Connecting WinDbg to the target for kernel debugging

On the host computer, open WinDbg. On the File menu, choose Kernel Debug. In the Kernel Debugging dialog box, open the Net tab. Paste in your port number and key that you saved to in the notepad .txt file earlier. Select OK.

You can also start a WinDbg session by opening a Command Prompt window and entering the following command, where is the port you selected above, and is the key that was returned by kdnet.exe above. Paste in the key in that you saved to in the notepad .txt file earlier.

windbg -k -d net:port=<YourDebugPort>,key=<YourKey>

Reboot the target computer

Once the debugger is connected, reboot the target computer. One way to do reboot the PC, is to use the shutdown -r -t 0 command from an administrator's command prompt.

After the target PC restarts, the debugger should connect automatically.

Troubleshooting

Troubleshooting Target

Confirm that the Windows KDNET-USB-EMM Network Adapter is present under Network Adapters in Windows Device Manager.

The device properties show when the controller is reserved for use by the Windows kernel debugger.

Troubleshooting Host

Confirm that the Windows KDNET-USB-EMM Network Adapter is present under Network Adapters in Windows Device Manager.

On the host the KDNET-EEM connection using the USB Type A port is shown.

Intel PCI - Connection retries messages on the debugger console windows and cannot break-in into the target - SkipPciProbeDebugDevice

If you encounter the following message in KDNET debugger console, cannot initiate a break-in into the target, or experience issues with certain commands (e.g., kdfiles), it may be due to KDNET receiving an out-of-sequence ping packet."

... Retry sending the same data packet for 128 times.

The transport connection between host kernel debugger and target Windows seems lost.
please try resync with target, recycle the host debugger, or reboot the target Windows.

This issue can happen because the pci.sys driver is incorrectly probing the debug device. To eliminate the errors, create the following registry entry on the TARGET device at an administrator command prompt.

reg add HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\SERVICES\kdnet /v SkipPciProbeDebugDevice /t REG_DWORD /d 1 /f

Then restart the target machine.

shutdown /r /t 0

Once the device reboots then the errors should disappear, and commands should work as expected.

See also

Setting Up KDNET Network Kernel Debugging Automatically

Setting Up KDNET Network Kernel Debugging Manually

Setting up USB 3.0 xHCI-DBC kernel-mode debugging (KDUSB)

Setting up USB KDNET kernel-mode debugging (KDNET-USB)