Setting Up Kernel-Mode Debugging of a Virtual Machine Manually

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.

As an alternative to setting up debugging of a virtual machine manually, you can do the setup using Microsoft Visual Studio. For more information, see Setting Up Kernel-Mode Debugging of a Virtual Machine in Visual Studio.

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

Setting Up the Target Virtual Machine

  1. 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.

    Note  By default, COM ports are not presented in generation 2 virtual machines. For information about how to create a COM port, see Generation 2 Virtual Machines.

  2. Reboot the virtual machine.
  3. 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.

Starting the Debugging Session 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. 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

Click 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 a 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:

  1. Disable Secure Boot by entering this PowerShell command:

    Set-VMFirmware –Vmname VmName –EnableSecureBoot Off

    where VmName is the name of your virtual machine.

  2. 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

For more information, 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.

Note  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.

Related topics

Setting Up Kernel-Mode Debugging Manually

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.