Live Kernel-Mode Debugging Using WinDbg (Classic)
There are two ways you can use WinDbg to initiate a live kernel-mode debugging session.
WinDbg Menu
When WinDbg is in dormant mode, you can begin a kernel debugging session by choosing Kernel Debug from the File menu or by pressing CTRL+K. When the Kernel Debugging dialog box appears, click the appropriate tab: NET, COM, USB, or Local. Each tab specifies a different connection method.
Command Prompt
In a Command Prompt window, you can initiate a kernel-mode debugging session when you launch WinDbg. Enter one of the following commands:
windbg [-y SymbolPath] -k net:port=PortNumber,key=Key[,target=TargetIPAddress|TargetMachineName]
windbg [-y SymbolPath] -k usb:targetname=USBString
windbg [-y SymbolPath] -k com:port=ComPort,baud=BaudRate
windbg [-y SymbolPath] -k com:ipport=SerialTcpIpPort,port=SerialIPAddress
windbg [-y SymbolPath] -k com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect]
windbg [-y SymbolPath] -k com:modem
windbg [-y SymbolPath] -kl
windbg [-y SymbolPath] -k
For more information, see WinDbg Command-Line Options.
Environment Variables
For debugging over a serial (COM port), 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.
SerialTcpIpPort
The target TCP IP port of the emulated serial COM port.
SerialIPAddress
The target TCP IP address of the emulated serial COM port.
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.
Previous version parameters
Important
The 1394 transport is available for use in Windows 10, version 1607 and earlier. It is not available in later versions of Windows. You should transition your projects to other transports, such as KDNET using Ethernet. For more information about that transport, see Setting Up KDNET Network Kernel Debugging Automatically.
1394Channel
The 1394 channel number. Valid channel numbers are any integer between 0 and 62, inclusive. 1394Channel must match the number used by the target computer, but does not depend on the physical 1394 port chosen on the adapter.
1394Protocol
The connection protocol to be used for the 1394 kernel connection. This can almost always be omitted, because the debugger will automatically choose the correct protocol. If you wish to set this manually, and the target computer is running Windows XP, 1394Protocol should be set equal to "channel". If the target computer is running Windows Server 2003 or later, 1394Protocol should be set equal to "instance". If it is omitted, the debugger will default to the protocol appropriate for the current target computer. This can only be specified through the command line or the environment variables, not through the WinDbg graphical interface.
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
windbg -k
The following command lines could be used to start WinDbg without any environment variables.
windbg -y d:\mysymbols -k com:port=com2,baud=57600
windbg -y d:\mysymbols -k com:port=\\.\com2,baud=115200
windbg -y d:\mysymbols -k net:port=50000,key=AutoGeneratedKey
windbg -y d:\mysymbols -k net:port=50000,key=AutoGeneratedKey,target=TargetIPAddress