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 debuggin using WinDbg* Preview, refer to the Microsoft* documentation.

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)

Attention

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 at http://software.intel.com/en-us/support 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.

    Note

    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.

Note

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:

    Note

    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.

Attention

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.

Note

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

For more information, refer to Intel® 64 and IA-32 Architectures Software Developer Manuals.

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.

Note

Consider using Sysinternals* Process Explorer software to view the Window Title of running processes.

The Intel Debugger 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
Intel® Debug Extensions for WinDbg* for Intel® Processor Trace User and Reference Guide Provides information about requirements and constraints and the commands of the Intel® Debug Extensions for WinDbg* for Intel® Processor Trace.
Intel® Debug Extensions for WinDbg* for Microsoft* Hyper-V Support - User Guide Provides information about the WinDbg* over Intel® DCI extension for Microsoft* Hyper-V support and describes architecture of virtual machines.

Intel® System Debugger (Intel® System Studio) Release Notes

Intel® System Debugger (Intel® oneAPI Toolkits) Release Notes

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 Intel® System Studio product page. See this page for support and online documentation.
Intel® oneAPI (Beta) Intel® oneAPI (Beta) product page. See this page for support and documentation for various toolkits.

Notices and Disclaimers

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.

Intel technologies' features and benefits depend on system configuration and may require enabled hardware, software or service activation. Performance varies depending on system configuration. No product or component can be absolutely secure. Check with your system manufacturer or retailer or learn more at [intel.com].

Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.

This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest forecast, schedule, specifications and roadmaps.

The products and services described may contain defects or errors which may cause deviations from published specifications. Current characterized errata are available on request.

Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Microsoft, Windows, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries.

© Intel Corporation.

This software and the related documents are Intel copyrighted materials, and your use of them is governed by the express license under which they were provided to you (License). Unless the License provides otherwise, you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related documents without Intel's prior written permission.

This software and the related documents are provided as is, with no express or implied warranties, other than those that are expressly stated in the License.

For more complete information about compiler optimizations, see our Optimization Notice.