Live Kernel-Mode Debugging Using KD

In a Command Prompt window, you can initiate a live kernel-mode debugging session when you launch KD. Enter one of the following commands.

kd [-y SymbolPath] -k net:port=PortNumber,key=Key[,target=TargetIPAddress|TargetHostName]

kd [-y SymbolPath] -k usb:targetname=USBString

kd [-y SymbolPath] -k com:port=ComPort,baud=BaudRate

kd [-y SymbolPath] -k com:ipport=SerialTcpIpPort,port=SerialIPAddress

kd [-y SymbolPath] -k com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect]

kd [-y SymbolPath] -k com:modem

kd [-y SymbolPath] -kl

kd [-y SymbolPath] -k

For more information, see KD Command-Line Options.

Environment Variables

For debugging over a serial (COM port) connection, you can use environment variables to specify the connection settings.

Use the following variables to specify a serial connection.

set _NT_DEBUG_PORT = ComPort

set _NT_DEBUG_BAUD_RATE = BaudRate

For more information, see Kernel-Mode Environment Variables.

Parameters

SymbolPath
A list of directories where symbol files are located. Directories in the list are separated by semicolons. For more information, see Symbol Path.

PortNumber
A port number to use for network debugging. You can choose any number from 49152 through 65535. For more information, see Setting Up a Network Connection Manually.

Key
The encryption key to use for network debugging. We recommend that you use an automatically generated key, which is provided by bcdedit when you configure the target computer. For more information, see Setting Up a Network Connection Manually.

TargetIPAddress
The IPv4 address of the target machine.

When the target= IP address is specified, this causes the debugger to initiate a connection to the specified target machine, by sending a special packet to the target, that will cause it to attempt to connect with that debugger. The debugger will send packets to the target repeatedly approximately every half second, attempting to connect. If the connection is successful, the target will drop any existing connection, and communicate only with this instance of the debugger. This allows you to take control of the debugging session away from an existing debugging connection.

When the target is configured with a host IP address, and the debugger is being run on the machine with the configured host IP address, there is no need to specify the target= IP address parameter. When the target is configured with a host IP address, it will send OFFER packets to the host every three seconds. The OFFER packets allow the debugger to connect to the host when no target= IP address is specified.

For more information on configuring the host IP address on the target, see Setting Up KDNET Network Kernel Debugging Automatically and Setting Up KDNET Network Kernel Debugging Manually.

TargetMachineName
The machine name of the target PC. To use the machine name, the DNS system on the network must have the machine name associated with the IP address of the target PC.

USBString
A USB connection string. This must match the string specified with the /targetname boot option. For more information, see Setting up USB 3.0 xHCI-DBC kernel-mode debugging (KDUSB).

ComPort
The name of the COM port. This can be in the format "com2" or in the format "\\.\com2", but should not simply be a number. For more information, see Setting Up a Serial Connection Manually.

BaudRate
The baud rate. This can be 9600, 19200, 38400, 57600, or 115200.

VMHost
When debugging a virtual machine, VMHost specifies the name of the physical computer on which the virtual machine is running. If the virtual machine is running on the same computer as the kernel debugger itself, use a single period (.) for VMHost. For more information, see Setting Up a Connection to a Virtual Machine.

PipeName
The name of the pipe created by the virtual machine for the debugging connection.

resets=0
Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. This parameter is only needed when debugging certain kinds of virtual machines.

reconnect
Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the named pipe is not found when the debugger is started, the reconnect parameter will cause it to wait for a pipe of this name to appear. This parameter is only needed when debugging certain kinds of virtual machines.

-kl
Causes the debugger to perform local kernel-mode debugging. For more information, see Local Kernel-Mode Debugging.

SerialTcpIpPort
The target TCP IP port of the emulated serial COM port.

SerialIPAddress
The target TCP IP address of the emulated serial COM port.

Examples

The following batch file could be used to set up and start a debugging session over a COM port connection.

set _NT_SYMBOL_PATH=d:\mysymbols
set _NT_DEBUG_PORT=com1
set _NT_DEBUG_BAUD_RATE=115200
set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log
kd

The following command lines could be used to start WinDbg without any environment variables.

kd -y d:\mysymbols -k com:port=com2,baud=57600

kd -y d:\mysymbols -k com:port=\\.\com2,baud=115200

kd -y d:\mysymbols -k net:port=50000,key=AutoGeneratedKey