Setting Up Kernel-Mode Debugging of a Virtual Machine Manually using a Virtual COM Port
Debugging Tools for Windows supports kernel debugging of a virtual machine. The virtual machine can be located on the same physical computer as the debugger or on a different computer that is connected to the same network. This topic describes how to set up debugging of a virtual machine manually using a virtual COM Port via KDCOM.
Using KDNET virtual networking is a faster option and is recommended. For more information, see Setting Up Network Debugging of a Virtual Machine with KDNET.
Setting Up the Target Virtual Machine
The computer that runs the debugger is called the host computer, and the virtual machine being debugged is called the target virtual machine.
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. Re-enable these security features when testing is complete and appropriately manage the test PC, when the security features are disabled.
In the virtual machine, in an elevated Command Prompt window, enter the following commands.
bcdedit /debug on
bcdedit /dbgsettings serial debugport:n baudrate:115200
where n is the number of a COM port on the virtual machine.
In the virtual machine, configure the COM port to map to a named pipe. The debugger will connect through this pipe. For more information about how to create this pipe, see your virtual machine's documentation.
Start the debugger in elevated mode, for example from an administrator command prompt. The debugger must be running in elevated mode when debugging a VM over a serial pipe. Once the debugger is attached and running, reboot the target VM.
Starting the Debugging Session Using WinDbg
On the host computer, open WinDbg as an Administrator. The debugger must be running in elevated mode when debugging a VM over a serial pipe. On the File menu, choose Kernel Debug. In the Kernel Debugging dialog box, open the COM tab. Check the Pipe box, and check the Reconnect box. For Baud Rate, enter 115200. For Resets, enter 0.
If the debugger is running on the same computer as the virtual machine, enter the following for Port.
\\.\pipe\PipeName.
If the debugger is running on a different computer from the virtual machine, enter the following for Port.
\\VMHost\pipe\PipeName
Select OK.
You can also start WinDbg at the command line. If the debugger is running on the same physical computer as the virtual machine, enter the following command in a Command Prompt window.
windbg -k com:pipe,port=\\.\pipe\PipeName,resets=0,reconnect
If the debugger is running on a different physical computer from the virtual machine, enter the following command in a Command Prompt window.
windbg -k com:pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect
Starting the Debugging Session Using KD
To debug a virtual machine that is running on the same physical computer as the debugger, enter the following command in an elevated Command Prompt window.
kd -k com:pipe,port=\\.\pipe\PipeName,resets=0,reconnect
To debug a virtual machine that is running on a different physical computer from the debugger, enter the following command in a Command Prompt window.
kd -k com:pipe,port=\\VMHost\pipe\PipeName,resets=0,reconnect
Parameters
VMHost
Specifies the name of the computer that the virtual machine is running on.
PipeName
Specifies the name of the pipe that you created on the virtual machine.
resets=0
Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. Use the resets=0 parameter for Microsoft Virtual PC and other virtual machines whose pipes drop excess bytes. Do not use this parameter for VMware or other virtual machines whose pipes do not drop all excess bytes.
reconnect
Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the debugger does not find the named pipe when the debugger is started, the reconnect parameter causes the debugger to wait for a pipe that is named PipeName to appear. Use reconnect for Virtual PC and other virtual machines that destroy and re-create their pipes during a computer restart. Do not use this parameter for VMware or other virtual machines that preserve their pipes during a computer restart.
For more information about additional command-line options, see KD Command-Line Options or WinDbg Command-Line Options.
Generation 2 Virtual Machines
By default, COM ports are not presented in generation 2 virtual machines. You can add COM ports through PowerShell or WMI. For the COM ports to be displayed in the Hyper-V Manager console, they must be created with a path.
To enable kernel debugging using a COM port on a generation 2 virtual machine, follow these steps:
Disable Secure Boot by entering this PowerShell command:
Set-VMFirmware –Vmname VmName –EnableSecureBoot Off
where VmName is the name of your virtual machine.
Add a COM port to the virtual machine by entering this PowerShell command:
Set-VMComPort –VMName VmName 1 \\.\pipe\PipeName
For example, the following command configures the first COM port on virtual machine TestVM to connect to named pipe TestPipe on the local computer.
Set-VMComPort –VMName TestVM 1 \\.\pipe\TestPipe
Once the debugger is attached and running, stop and cold start the VM to activate the COM ports in the VM. The emulated UARTS aren’t available for debugging unless at least one is actually configured with a pipe name and they cannot be hot-added.
Re-enable secure boot, once you are done updating the configuration changes.
For more information about Generation 2 VMs, see Generation 2 Virtual Machine Overview.
Remarks
If the target computer has stopped responding, the target computer is still stopped because of an earlier kernel debugging action, or you used the -b command-line option, the debugger breaks into the target computer immediately.
Otherwise, the target computer continues running until the debugger orders it to break.
Troubleshooting Firewalls and Network Access Issues
Your debugger (WinDbg or KD) must have access through the firewall. This can even be the case for virtual serial ports that are supported by network adapters.
If you are prompted by Windows to turn off the firewall when the debugger is loaded, select all three boxes.
Depending on the specifics of the VM in use, you may need to change the network settings for your virtual machines to bridge them to the Microsoft Kernel Network Debug Adapter. Otherwise, the virtual machines will not have access to the network.
Windows Firewall
You can use the Control Panel to allow access through the Windows firewall. Open Control Panel > System and Security, and select Allow an app through Windows Firewall. In the list of applications, locate Windows GUI Symbolic Debugger and Windows Kernel Debugger. Use the checkboxes to allow those two applications through the firewall. Restart your debugging application (WinDbg or KD).
Third Party VMs
VMWare
If you restart the virtual machine by using the VMWare facilities (for example, the reset button), exit WinDbg, and then restart WinDbg to continue debugging. During virtual machine debugging, VMWare often consumes 100% of the CPU.
See also
Setting Up Network Debugging of a Virtual Machine with KDNET