Setting Up Kernel-Mode Debugging over a Serial Cable Manually
Debugging Tools for Windows supports kernel debugging over a null-modem cable. Null-modem cables are serial cables that have been configured to send data between two serial ports. Do not confuse null-modem cables with standard serial cables. Standard serial cables do not connect serial ports to each other. For information about how null-modem cables are wired, see Null-Modem Cable Wiring.
The computer that runs the debugger is called the host computer, and the computer being debugged is called the target computer.
Setting Up the Target Computer
Important
Before using bcdedit to change boot information you may need to temporarily suspend Windows security features such as BitLocker and Secure Boot on the test PC. You can re-enable Secure Boot once you’re done debugging and you’ve disabled kernel debugging.
On the target computer, open a Command Prompt window as Administrator, and enter the following commands, where n is the number of the COM port used for debugging on the target computer, and rate is the baud rate used for debugging:
bcdedit /debug on
bcdedit /dbgsettings serial debugport:n baudrate:rate
Note The baud rate must be the same on the host computer and the target computer. The recommended rate is 115200.
Reboot the target computer.
Starting the Debugging Session
Connect the null-modem cable to the COM ports that you have chosen for debugging on the host and target computers.
Using WinDbg
On the host computer, open WinDbg. On the File menu, choose Kernel Debug. In the Kernel Debugging dialog box, open the COM tab. In the Baud rate box, enter the rate you have chosen for debugging. In the Port box, enter COMn where n is the COM port number you have chosen for debugging on the host computer. Select OK.
You can also start a session with WinDbg by entering the following command in a Command Prompt window; n is the number of the COM port used for debugging on the host computer, and rate is the baud rate used for debugging:
windbg -k com:port=COMn,baud=rate
Using KD
On the host computer, open a Command Prompt window, and enter the following command, where n is the number of the COM port used for debugging on the host computer, and rate is the baud rate used for debugging:
kd -k com:port=COMn,baud=rate
Using Environment Variables
On the host computer, you can use environment variables to specify the COM port and the baud rate. Then you do not have to specify the port and baud rate each time you start a debugging session. To use environment variables to specify the COM port and baud rate, open a Command Prompt window and enter the following commands, where n is the number of the COM port used for debugging on the host computer, and rate is the baud rate used for debugging:
- set _NT_DEBUG_PORT=COMn
- set _NT_DEBUG_BAUD_RATE=rate
To start a debugging session, open a Command Prompt window, and enter one of the following commands:
- kd
- windbg
Troubleshooting Tips for Debugging over a Serial Cable
Specify correct COM port on both host and target
Determine the number of COM ports you are using for debugging on the host and target computers. For example, suppose you have your null-modem cable connected to COM1 on the host computer and COM2 on the target computer.
On the target computer, open a Command Prompt window as Administrator, and enter bcdedit /dbgsettings. If you are using COM2 on the target computer, the output of bcdedit should show debugport 2.
On the host computer, specify the correct COM port when you start the debugger or when you set environment variables. If you are using COM1 on the host computer, use one of the following methods to specify the COM port.
- In WinDbg, in the Kernel Debugging dialog box, enter COM1 in the Port box.
- windbg -k com:port=COM1, ...
- kd -k com:port=COM1, ...
- set _NT_DEBUG_PORT=COM1
Baud rate must be the same on host and target
The baud rate used for debugging over a serial cable must be set to the same value on the host and target computers. For example, suppose you have chosen a baud rate of 115200.
On the target computer, open a Command Prompt window as Administrator, and enter bcdedit /dbgsettings. The output of bcdedit should show baudrate 115200.
On the host computer, specify the correct baud rate when you start the debugger or when you set environment variables. Use one of the following methods to specify a baud rate of 115200.
- In WinDbg, in the Kernel Debugging dialog box, enter 115200 in the Baud rate box.
- windbg -k ..., baud=115200
- kd -k ..., baud=115200
- set _NT_DEBUG_BAUD_RATE=115200
Null Modem Cable Wiring
The following tables show how null-modem cables are wired.
9-pin connector
| Connector 1 | Connector 2 | Signals |
|---|---|---|
| 2 | 3 | Tx - Rx |
| 3 | 2 | Rx - Tx |
| 7 | 8 | RTS - CTS |
| 8 | 7 | CTS - RTS |
| 4 | 1+6 | DTR - (CD+DSR) |
| 1+6 | 4 | (CD+DSR) - DTR |
| 5 | 5 | Signal ground |
25-pin connector
| Connector 1 | Connector 2 | Signals |
|---|---|---|
| 2 | 3 | Tx - Rx |
| 3 | 2 | Rx - Tx |
| 4 | 5 | RTS - CTS |
| 5 | 4 | CTS - RTS |
| 6 | 20 | DSR - DTR |
| 20 | 6 | DTR - DSR |
| 7 | 7 | Signal ground |
Signal Abbreviations
| Abbreviation | Signal |
|---|---|
| Tx | Transmit data |
| Rx | Receive data |
| RTS | Request to send |
| CTS | Clear to send |
| DTR | Data terminal ready |
| DSR | Data set ready |
| CD | Carrier detect |
Additional Information
For complete documentation of the bcdedit command, see BCDEdit Options Reference.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for