2.31. Paravirtualized Debugging

This section covers debugging of guest operating systems using interfaces supported by paravirtualization providers.

Note

Paravirtualized debugging significantly alter guest operating system behaviour and should only be used by expert users for debugging and diagnostics.

These debug options are specified as a string of key-value pairs separated by commas. An empty string disables paravirtualized debugging.

2.31.1. Hyper-V Debug Options

All of the options listed below are optional, and thus the default value specified will be used when the corresponding key-value pair is not specified.

  • Key: enabled

    Value: 0 or 1

    Default: 0

    Specify 1 to enable the Hyper-V debug interface. If this key-value pair is not specified or the value is not 1, the Hyper-V debug interface is disabled regardless of other key-value pairs being present.

  • Key: address

    Value: IPv4 address

    Default: 127.0.0.1

    Specify the IPv4 address where the remote debugger is connected.

  • Key: port

    Value: UDP port number

    Default: 50000

    Specify the UDP port number where the remote debugger is connected.

  • Key: vendor

    Value: Hyper-V vendor signature reported by CPUID to the guest

    Default: When debugging is enabled: Microsoft Hv, otherwise: VBoxVBoxVBox

    Specify the Hyper-V vendor signature which is exposed to the guest by CPUID. For debugging Microsoft Windows guests, it is required the hypervisor reports the Microsoft vendor.

  • Key: hypercallinterface

    Value: 0 or 1

    Default: 0

    Specify whether hypercalls should be suggested for initiating debug data transfers between host and guest rather than MSRs when requested by the guest.

  • Key: vsinterface

    Value: 0 or 1

    Default: When debugging is enabled, 1, otherwise 0

    Specify whether to expose the VS#1 virtualization service interface to the guest. This interface is required for debugging Microsoft Windows 10 32-bit guests, but is optional for other Windows versions.

2.31.1.1. Setting up Windows Guests for Debugging with the Hyper-V Paravirtualization Provider

Windows supports debugging over a serial cable, USB, IEEE 1394 Firewire, and Ethernet. USB and IEEE 1394 are not applicable for virtual machines, and Ethernet requires Windows 8 or later. While a serial connection is universally usable, it is slow.

Debugging using the Hyper-V debug transport, supported on Windows Vista and later, offers significant benefits. It provides excellent performance due to direct host-to-guest transfers, it is easy to set up and requires minimal support from the hypervisor. It can be used with the debugger running on the same host as the VM or with the debugger and VM on separate machines connected over a network.

Prerequisites

  • A VM configured for Hyper-V paravirtualization running a Windows Vista or newer Windows guest. You can check the effective paravirtualization provider for your VM with the output of the following VBoxManage command:

    VBoxManage showvminfo "VM name"
  • A sufficiently up-to-date version of the Microsoft WinDbg debugger required to debug the version of Windows in your VM.

  • While Windows 8 and newer Windows guests ship with Hyper-V debug support, Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista guest, copy the file kdvm.dll from a Windows 8.0 installation. This file is typically located in C:\Windows\System32. Copy it to the same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or 64-bit version of the DLL which matches your guest OS.

    Note

    Only Windows 8.0 ships kdvm.dll. Windows 8.1 and newer Windows versions do not.

VM and Guest Configuration

  1. Power off the VM.

  2. Enable the debug options with the following VBoxManage command:

    VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"

    The above command assumes your debugger will connect to your host machine on UDP port 50000. However, if you need to run the debugger on a remote machine you may specify the remote address and port here. For example:

    VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"

    See Section 2.31.1, “Hyper-V Debug Options” for the complete set of options.

  3. Start the VM.

  4. In the guest, start an elevated command prompt and execute the following commands:

    • For a Windows 8 or newer Windows guest:

      bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4
    • For a Windows 7 or Vista guest:

      bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4
      bcdedit /set dbgtransport kdvm.dll

      The IP address and port in the bcdedit command are ignored when using the Hyper-V debug transport. Any valid IP and a port number greater than 49151 and lower than 65536 can be entered.

      The encryption key in the bcdedit command is relevant and must be valid. The key "1.2.3.4" used in the above example is valid and may be used if security is not a concern. If you do not specify any encryption key, bcdedit will generate one for you and you will need to copy this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used to encrypt the debug data exchanged between Windows and the debugger.

    • Run one or more of the following commands to enable debugging for the appropriate phase or component of your Windows guest:

      bcdedit /set debug on
      bcdedit /set bootdebug on
      bcdedit /set {bootmgr} bootdebug on

      Please note that the bootdebug options are only effective on Windows 8 or newer when using the Hyper-V debug transport. Refer to Microsoft Windows documentation for detailed explanation of bcdedit options.

  5. Start Microsoft WinDbg on your host machine or remote host.

    From the File menu, select Kernel Debug. On the NET tab, specify the UDP port number you used in the paravirtdebug options. If you did not specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall or other security software.

    In the Key field, enter 1.2.3.4 or the encryption key from the bcdedit command in your Windows guest.

    Click OK to start listening for connections. Microsoft WinDbg typically shows a Waiting to Reconnect message during this phase.

    Alternatively, to directly start a debug session, run WinDbg from the command line as follows :

    windbg.exe -k net:port=50000,key=1.2.3.4

    See the WinDbg documentation for the complete command line syntax.

  6. Reboot your Windows guest and it should then connect as a debuggee with Microsoft WinDbg.