Get Started

  • XX.XX
  • 06/18/2020
  • Public Content

Get Started with the Intel® Debug Extensions for WinDbg*

Intel® Debug Extensions for WinDbg* comprise the following features:
  • Intel® Debug Extensions for WinDbg* for IA JTAG debugging
    Intel® Debug Extensions for WinDbg* for IA JTAG debugging (IA JTAG) enable the connection of WinDbg* to a target over the Joint Test Action Group (JTAG) interface. The server acts as a mediator and forwards the calls from WindDbg* to the IPC interface and back.
  • Intel® Debug Extensions for WinDbg* for Intel® Processor Trace
    Intel® Debug Extensions for WinDbg* for Intel® Processor Trace (Intel® PT) are designed to help WinDbg* users by extending their debugging tool set with execution tracing. The extension allows for easy setup of Intel® PT by abstracting hardware configuration and then reconstructing and displaying execution flow from the collected trace data. It integrates with other WinDbg* features, such as symbolization and high-level source display. For more information on how to use this feature, see: Intel® Debug Extensions for WinDbg* for Intel® Processor Trace User and Reference Guide
  • Intel® Debug Extensions for WinDbg* support for Microsoft* Hyper-V
    Intel® Debug Extensions for WinDbg* provide support for systems that have Microsoft* Hyper-V enabled. With this solution, you can use Intel® System Debugger JTAG functionality to debug target systems running under Virtualization-based Security (VBS). For more information on Microsoft Hyper-V, refer to the Microsoft documentation. For more information on the extension and virtual machine architecture, see the Intel® Debug Extensions for WinDbg* for Microsoft* Hyper-V Support - User Guide.
  • Intel® Debug Extensions for WinDbg* support for debugging with WinDbg* Preview.
    Intel® Debug Extensions for WinDbg* provide support for debugging with WinDbg* Preview. With this solution, you can use Intel® System Debugger JTAG functionality to debug target systems withWinDbg* Preview. For more information on debugging using WinDbg* Preview, refer to the Microsoft* documentation.
  • Intel® Debug Extensions for WinDbg* support for debugging Advanced Configuration and Power Interface (ACPI) Machine Language (AML) code.
    WinDbg* over the Intel® Direct Connect Interface (Intel® DCI) enables using the Microsoft* AMLI Debugger to debug Advanced Configuration and Power Interface (ACPI) Machine Language (AML) code. With WinDbg* over Intel® DCI, the Microsoft* AMLI Debugger is used as an extension to a native kernel debugger. For more information, refer to the corresponding User Guide
Intel® Debug Extensions for WinDbg* are available as part of the following products:
  • Intel® System Studio
  • Intel® oneAPI IoT Toolkit (Beta)
  • Intel® System Bring-up Toolkit (Beta)
Python* 2 is no longer supported. Intel® DFx Abstraction Layer (Intel® DAL) can now be used with Python* 3.

Using WinDbg* Themes

Before starting a debugging session, you can choose and customize the theme, the preconfigured WinDbg* workspace, that meets your needs best. The Debugging Tools for Windows* provide themes as a set of registry (
.reg
) files. For instructions on choosing the proper theme and loading it, refer to the Windows* Debugging Tools documentation.

Using the Intel® Debug Extensions for WinDbg* for IA JTAG debugging (IA JTAG)

Prerequisites
For a list of system requirements matching your configuration, see the Intel® System Debugger Release Notes.
In case you need assistance installing or running this product, please visit our Get Help page for support options.
Starting the Intel® Debug Extensions for WinDbg* for IA JTAG debugging
  1. WinDbg* must have access to kernel symbols for the connection to succeed; therefore, you must set the symbol file path beforehand. Launch WinDbg* without using the batch script and set the symbol file path by selecting
    File > Symbol File Path…
    and adding
    srv*C:\Symbols*http://msdl.microsoft.com/download/symbols
    to the path or by setting the
    _NT_symbol_path
    global environment variable with a corresponding value. Save the workspace by selecting
    File > Save Workspace
    and close WinDbg*. You need to do this only once before the first use.
  2. Connect the host system to the target one with the Intel® In-Target Probe (Intel® ITP) or the Intel® Direct Connect Interface (Intel® DCI).
  3. Power one the probe and the target system.
  4. Chose the IPC provider to be used during the debugging session:
    • OpenIPC. This is the default IPC provider.
    • Intel® DFx Abstraction Layer (Intel® DAL).
      This provider is supported by Intel® System Studio only
      .
  5. Depending on the provider selected
    , launch Intel® Debug Extensions for WinDbg* the following way:
    run
    windbg_iajtag_console.bat
    located at
    <
    install_dir
    >\system_debugger_<
    version
    >\
    the following way:
    • To use OpenIPC, choose any of the following options:
      • Click the desktop icon or open the
        Start Menu
        and click
        Intel® Debug Extensions for WinDbg*
        under
        Intel® System Studio <
        year
        >
        .
      • Run
        windbg_iajtag_console.bat
        located at
        <
        install_dir
        >\system_debugger_<
        version
        >\
      • Launch
        iss_shell.bat
        located in the root installation directory and run
        windbg_dci
        to invoke WinDbg*.
    • To use Intel® DAL
      (supported by Intel® System Studio only)
      , navigate to
      <
      install_dir
      >\system_debugger_<
      version
      >\
      , launch the command prompt, and run the following code line:
      windbg_iajtag_console.bat
      DAL
  6. At this point, two Python* objects are available for debugging:
    • itp
      - Intel® ITP interface
    • itpkd
      - wrapper over WinDbg* and kernel debug console
    Execute
    windbg()
    to halt the target and run a WinDbg* session. After that, WinDbg* starts connecting to the target.
    You can halt the target any time afterwards by running the
    halt()
    command.
    Connecting to the target can take several minutes. Do not enter any commands until the connection is fully established and the connection confirmation message is displayed (
    Target initialization succeeded
    ).
    If the connection fails, you see an exception in the console. Check the network connection if
    KDVersionBlock
    is not found. Run the target for a while if the kernel is not found.
Collecting Stop Error Information
Intel® Debug Extensions for WinDbg* provides a way to collect general information about a Stop error (also known as the bugcheck error and the Blue Screen of Death). This capability can be useful for cases when you cannot obtain a functional full memory dump or you do not require a high level of detail.
To collect information about a Stop error, connect to your target and run the following command in the Intel Debug Extensions for WinDbg* command prompt:
forensic.get_bsod_info(
<filename>
)
where
<filename>
is the path to the output text file.
Depending on the type of the Stop error, the output text file may contain a combination of the following information:
  • List of loaded modules with offsets and symbols information
  • Call stacks of all threads
  • Output of the
    !analyze -v -f
    WinDbg* command.
Tracing Advanced Configuration and Power Interface (ACPI) BIOS Code
You can use ACPI tracing to troubleshoot low-level platform issues.
Follow the steps below to receive ACPI trace messages. Note that you should run all commands in the Intel® Debug Extensions for WinDbg* command prompt.
The Intel Debug Extensions for WinDbg* command prompt prints ACPI trace messages. To cancel tracing, press Ctrl + C.
  1. Connect to your target
  2. Set a post-reset breakpoint by running the following command:
    forensic.set_init_breakpoint()
  3. Reset your target by running the following command:
    itp.resettarget()
  4. Remove the reset breakpoint with the following command:
    forensic.remove_init_breakpoint()
  5. Enable ACPI trace messages:
    acpi.amli_trace()

Using Intel® Debug Extensions for WinDbg* with WinDbg* Preview

System Requirements
To start using Intel® Debug Extensions for WinDbg* with WinDbg* Preview, follow the steps below:
  1. Connect to the target.
  2. Launch
    iss_shell.bat
    located in the installation root directory.
  3. Execute the
    windbg_preview
    command to start WinDbg* Preview.

Using Intel® Debug Extensions for WinDbg* for Microsoft* Hyper-V Support

Follow the steps below to start using Intel® Debug Extensions for WinDbg* for Microsoft* Hyper-V support.
Enable Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64 and Intel® Architecture in BIOS
  1. Power on the system and open the BIOS.
  2. Open the
    Processor
    submenu. The processor settings menu may be located under any of
    Chipset
    ,
    Advanced CPU configuration
    , or
    Northbridge
    tabs.
  3. Enable Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64 and Intel® Architecture. The settings might depend on the OEM and system BIOS.
  4. If the option is available, enable Intel® Virtualization Technology (Intel® VT) for Directed I/O (Intel® VT-d).
  5. Click
    Save
    and exit the BIOS.
For more information about the Intel® Virtualization Technology (Intel® VT) for IA-32, Intel® 64 and Intel® Architecture, see this article
Enable Microsoft* Hyper-V on Windows* 10
System Requirements
  • Windows* 10 Enterprise, Pro, or Education 64-bit Processor.
  • CPU support for Virtual Machine Monitor Node Extension (Intel® Virtualization Technology (Intel® VT) for Connectivity (Intel® VT-c) on Intel CPUs).
  • Minimum of 4 GB memory.
Microsoft Hyper-V is built into Windows* OS as an optional feature, no direct download needed.
Enable Microsoft Hyper-V to create virtual machines on Windows* 10 using any way suggested below:
  • Enable Microsoft Hyper-V using Windows* PowerShell:
    1. Launch the Windows PowerShell console as Administrator.
    2. Run the following command:
      Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All
    3. When the installation is completed, reboot the system.
  • Enable Microsoft Hyper-V through Settings:
    The Hyper-V role cannot be installed on Windows* 10 Home.
    1. Open Windows Settings and navigate to
      Apps
      >
      Apps & features
      .
    2. On the right, click
      Programs and Features
      under
      Related settings
      .
    3. Select
      Turn Windows features on or off
      .
    4. Check the
      Hyper-V
      root box:
    5. Click
      OK
      and exit the settings.
Configure the Target Windows* OS.
  1. On the target system, execute the following commands from the command line:
    bcdedit /debug on bcdedit
    /set
    hypervisordebug on bcdedit
    /set
    hypervisorlaunchtype auto
    Additionally, if you want to debug the process of loading the hypervisor, run the following command:
    bcdedit
    /set
    bootdebug on
  2. Reboot the target system.
Use Intel® Debug Extensions for WinDbg* over the Intel® Direct Connect Interface (Intel® DCI)
To start WinDbg*, execute
windbg_iajtag_console.bat
. This script sets up OpenIPC as a default IPC provider.
Microsoft* Hyper-V support with Intel® DFx Abstraction Layer (Intel® DAL) is not provided.
If Microsoft Hyper-V is active on the debug target, the
windbg()
command results in one of the following states:
  • If the target is halted, the WinDbg* UI is launched into the currently halted context. If Microsoft* Hyper-V is active, WinDbg* will likely start within its context.
  • If the target is not halted, the WinDbg* over Intel® DCI implementation breaks into NTOSKRNL (NT OS).
To support Microsoft Hyper-V environment within the Virtual machine monitor (VMM) context or guest context, Extended Page Tables (EPT) address translation is fully integrated. Thus, all
dbgeng
use cases are transparently supported.
The following virtualization-related symbols are currently available only to the customers with a special NDA contract signed with Microsoft:
  • storvsp.pdb
  • vhdparser.pdb
  • passthroughparser.pdb
  • hvix64.pdb
  • hvloader.pdb
Without a
.pdb
file, the debugger cannot resolve the function names or any global objects in the contex of the symbols enumerated above. Beside the symbol resolution support, other features are available for all users.
Run Control with Intel® Debug Extensions for WinDbg* over Intel® DCI
WinDbg* over Intel® DCI offers probe mode breakpoint support for Virtual Machine Monitors (VMM). Use the
breakin()
function to stop WinDbg* after a specified event. After the event is reported, you can start WinDbg* over Intel DCI and continue the session or proceed with using the console mode.
To set a breakpoint, use the following commands:
breakin(NTOSKRNL)
Break into the host kernel. From this point, WinDbg* is able to load symbols and KdBaseAddress found.
breakin(SMMENTRY)
Break into the probe mode after SMMENTRY event.
breakin(SMMEXIT)
Break into the probe mode after SMMEXIT event.
breakin(VMENTRY)
Break into the probe mode after VMENTRY event
breakin(VMEXIT)
Break into the probe mode after VMEXIT event
The list below introduces the basic set of run control commands:
  • To stop the execution of all general purpose cores, run
    halt()
    .
  • To get information about all general purpose cores executing, run
    status()
    when the target is halted.
  • To get information about the Microsoft* system application running in the halted debug context, run
    forensic.image_scans()
    .
  • To resume general purpose cores after stopping at a desired debug context, run
    go()
    .

Troubleshooting

If the connection to the target via the IA JTAG fails, WinDbg* issues the 'Server execution failed' message.
Possible issues and solutions are:
Error
Possible Root Causes
Solution
ERROR: Could not start kernel debugging using exdi: Unspecified error
  • The target is not connected or has no power.
  • The
    dllhost.exe
    and/or
    MasterFrame.HostApplication.exe
    processes are running.
  • Incorrect target configuration settings are used.
  • Check that the
    dllhost.exe
    and
    MasterFrame.HostApplication.exe
    processes are not running. Terminate both processes and try again.
  • Make sure that you applied correct target configuration settings using the Intel® DAL config console (for example, at
    <install_dir>
    \tools\\DAL_
    <version>
    \ConfigConsole.exe
    .)
ERROR: Could not start kernel debugging using exdi: Class not registered
The
ExdiIPC.dll
file was not registered correctly.
Register the
.dll
file as follows:
  1. Go to the
    <install-dir>
    \ system_debugger_
    <version>
    \windbg-ext\iajtagserver\intel64
    directory.
  2. Run the
    regsvr32 ExdiIPC.dll
    command.
ERROR: Could not start kernel debugging using exdi: Specified module could not be found
The
ExdiIPC.dll
file was removed after the registration.
Reinstall the add-on and make sure that it is available at
<install-dir>
\ system_debugger_
<version>
\windbg-ext\iajtagserver\intel64\ExdiIPC.dll
.
ERROR: Could not start kernel debugging using exdi: Win32 error 0x87
The parameter is incorrect
The
dllhost.exe
process froze after an abnormal termination of a debug session.
Kill the
dllhost.exe
process that has its Window Title set to
IntelExdiServer
.
Consider using Sysinternals* Process Explorer software to view the Window Title of running processes.
The Intel® Debug Extensions for WinDbg* eXDI COM server was not registered with Windows* OS due to a faulty installation.
Register the eXDI COM server by running
regsvr32 "
<install-dir>
\system_debugger_
<version>
\windbg-ext\iajtagserver\intel64\ExdiIpc.dll"
.
The log file contains:
ERROR: No probe found. Please check probe connection and power.
Connection between the host and the probe is not correctly established. The probe is powered off or out of order.
Check the host connection to the probe and the probe power. Also, check if the probe drivers are correctly installed and working.
The log file contains:
ERROR: No active threads detected
  • Connection between the target and the probe is not correctly established.
  • The probe is powered off or out of order.
  • Check the target connection to the probe and the target power.
  • Reset the target if locked.
WinDbg* is frozen.
WinDbg* is scanning memory to establish the connection. This can take several minutes. If the WinDbg* break was issued at the wrong time, the scanning process takes about 10 minutes.
Wait until the scanning is done.
ERROR: could not import runpy module
ModuleNotFoundError: No module named 'runpy'
The machine with Intel® System Debugger installed has not been cleaned.
Remove the folder
C:\Users\<username>\AppData\Local\Intel\windbg-ext-venv
and restart WinDbg*.

Training and Documentation

Document
Description
Provides information about requirements and constraints and the commands of the Intel® Debug Extensions for WinDbg* for Intel® Processor Trace.
Provides information about the WinDbg* over Intel® DCI extension for Microsoft* Hyper-V support and describes architecture of virtual machines.
Provides information about using WinDbg* over Intel® DCI to enable the Microsoft* AMLI Debugger to debug ACPI Machine Language (AML) code.
Contains the most up-to-date information about the Intel® System Debugger in general and Intel® Debug Extensions for WinDbg* in particular, including:
  • Overview information (including new features and product contents)
  • System requirements (hardware and software requirements for installing and using the product)
  • Known limitations
  • Technical support (links to contacts for reporting problems and getting assistance)
Intel® System Studio product page. See this page for support and online documentation.
Intel® oneAPI (Beta) product page. See this page for support and documentation for various toolkits.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804