Intel® Distribution for GDB* Release Notes

ID 763674
Updated 10/15/2024
Version 2025.0
Public

author-image

By

Where to Find the Release

Intel® Distribution for GDB* is available as part of the Intel® oneAPI Base Toolkit. To download the Intel® oneAPI Base Toolkit and learn more about toolkits, visit the Intel® oneAPI Toolkits main page.

Visit Intel® oneAPI Toolkit and Component Versioning Schema for more information about semantic versioning and how it is used with Intel® oneAPI.

Release Notes for Linux* OS

Major Features

  • Multi-target: The debugger can orchestrate multiple targets of different architectures. This feature allows you to debug the "host" portion and the "kernel" of a SYCL* program in the same Intel® Distribution for GDB* session.
  • Auto-attach: The debugger automatically creates an inferior that attaches itself to the Intel® Graphics Technology target to be able to receive events and control the GPU for native debugging.
  • Thread SIMD lanes: The debugger displays SIMD lane information for the GPU threads on the command line interface. You can switch between lanes.
  • Support for debugging a kernel offloaded to a CPU, GPU, or FPGA-emulation device.
  • The debugger is based on the GDB* 15.1 release.

Key Capabilities

  • Support for Intel® Iris® Xe Graphics.
  • Automatically detecting JIT-compiled, or dynamically loaded, kernel code for debugging.
  • Defining breakpoints (both inside and outside of a kernel) to halt the execution of the program.
  • Inspecting and changing the values of variables in the application.
  • Inspecting and changing register values.
  • Listing the threads; switching the current thread context.
  • Listing active SIMD lanes; switching the current SIMD lane context per thread.
  • Evaluating and printing the values of expressions in multiple threads and SIMD lane contexts.
  • Disassembling the machine instructions.
  • Displaying and navigating the function call-stack.
  • Source- and instruction-level stepping.
  • Non-stop and all-stop debug mode.
  • Recording the execution using Intel® Processor Trace (Intel® PT).
  • Printing of Intel® Processor Trace (Intel® PT) PTWRITE payloads and asynchronous events in the instruction history and function-call history.
  • Reading and writing Intel® Advanced Matrix Extensions (Intel® AMX) registers.
  • Reading and writing of the Intel® CET Shadow Stack Pointer (pl3_ssp) register.
  • Reading and writing of the Intel® APX registers (Extended GPRs $r16 - $r31) including byte, word and dword pseudo registers.

System Requirements

Documentation

Changes in the 2025.0 Release

  • Rebased to GDB version 15.1. See the changes here.
  • Added further support for Intel® CET Shadow Stack:
    • Introduce a new subcommand of the backtrace command backtrace|bt shadow to print the shadow stack backtrace.
  • Added support for the Intel® APX registers (Extended GPRs $r16 - $r31) including byte, word and dword pseudo registers, as well as coredump support.
  • Defining a breakpoint at a location before a kernel (i.e. inside the host code) no longer causes the breakpoint to be also defined at the start of the kernel.
  • In case of a page fault event coming from the GPU, the debugger now displays a warning that the location reported for the signal may be inaccurate.
  • Added support for XE2 debugging.
  • Enabled GPU inferior calls with the setting set unwindonsignal on.

Known Issues and Limitations

  • For OpenMP* #pragma omp single  blocks in C++, private variables cannot be inspected and breakpoints may occasionally not hit the expected line.
  • With kernels older than 5.9, hanging behavior may be seen for devices with id 0x3E98. The GPU can be programmatically reset for recovery.
  • Compilers may emit trampoline functions, which do not exist in the source code, but can be visible in the backtrace and step commands.

  • The Intel® Distribution for GDB* from 2025.0 onwards uses the latest Python* version, so it may result in some syntax warnings inside Python scripts on your system. The environment variable PYTHONWARNINGS=ignore can be used to control the display of Python warnings.

On GPU devices:
  • GDB might occasionally return the message "Cannot execute this command while the target is running". Ignore the message as it should not affect further debugging.
  • If you define a breakpoint at a location before a kernel (inside the host code), the breakpoint is also defined at the start of the kernel. This is similar to defining a breakpoint at a comment line or an empty line: in these cases, the breakpoint is defined for the next source line.
  • If the currently selected SIMD lane of a thread becomes inactive, GDB might silently switch the focus to the first active SIMD lane in this thread.
  • Dereferencing sycl::multi_ptr is not supported.
  • Applications that use unified shared memory (USM) may appear as raising a SIGSEGV when a USM-allocated memory is being accessed. This is a mechanism used by the runtime to trigger memory migration. In such cases, sending the signal back to the application resumes the program. For this, use GDB's signal SIGSEGV command.
  • While a workload submitted to a subdevice of a GPU is being debugged, no other workload can be executed or debugged on the same subdevice.
  • The debugger does not support disabling of displaced-stepping before the start of a GPU kernel.

Release Notes for Windows* OS

Major Features

  • Support for debugging a kernel offloaded to a CPU, GPU, or FPGA-emulation device.
  • Integration into Microsoft Visual Studio* interface to enable GPU remote debugging. This feature allows you to debug the "host" portion and the "kernel" of a SYCL* program in the same VS remote debugging session.

Key Capabilities

  • Inserting a breakpoint inside a kernel and stopping when the breakpoint is hit by a thread.
  • Inspecting SIMD lanes.
  • Inspecting device information.
  • Inspecting local variables.
  • Source-level stepping.
  • Backtracing function calls.
  • Examining threads.
  • Reading registers.
  • Disassembling.
  • Automatic launch of gdbserver-ze.
  • Support for debugging SYCL* programs.
  • Support for debugging OpenMP* C++ kernel code for CPU and GPU offloads.
  • Ability to connect and debug a target outside the domain network.

System Requirements

You can download the latest driver at Intel® Arc™ & Iris® Xe Graphics - WHQL - Windows.

Documentation

To set up the debugger, refer to the Get Started with Debugging SYCL*. 

Changes in 2025.0 Release 

  • Introduction of Intel® Distribution for GDB* Health Check. This feature assists in identifying common setup issues and misconfigurations that could prevent successful debugging.
  • Includes performance improvement and bug fixes.
  • Fixed a bug in Fortran Expression Evaluator (FEE) extension causing duplicate entries in Locals window.

Known Issues and Limitations

On GPU devices:

  • Resizable BAR or Smart Access Memory must be enabled for debugging applications using Intel® Arc™ A-Series Graphics. When disabled, GPU debugging is not possible.
  • With a two-machine setup, when a debugging session is interrupted abruptly during kernel offload to a GPU, there is a possibility that further debugging is not possible. This is often indicated by deployment errors despite the Visual Studio Remote Debugger session running on the target. In this case, restarting the target machine should resolve the issue.
  • If you define a breakpoint at a location before the kernel (inside the host code), the breakpoint is also defined at the start of the kernel. This is similar to defining a breakpoint at a comment line or an empty line: in these cases, the breakpoint is defined for the next source line.
  • Applications that use unified shared memory (USM) may give an access violation exception reading a specific location, when a USM-allocated memory is being accessed. This is a mechanism used by the runtime to trigger memory migration. In such cases, resume the program by clicking the Continue button or pressing F5 function key inside your Visual Studio instance.
  • A message box displaying the information, GDB exited unexpectedly with exit code 0 (0x0). Debugging will now abort appears at the termination of GPU offload programs. Since this occurs only at the end, it does not affect any other functionality and will be resolved in an upcoming release.

On CPU and GPU devices:

  • For OpenMP #pragma omp single blocks in C++, private variables cannot be inspected and breakpoints may occasionally not hit the expected line.
  • Compilers may emit trampoline functions, which do not exist in the source code, but can be visible when stepping or when examining the call stack.

On FPGA emulator devices:

  • For debugging on FPGA emulator, ahead-of-time (AoT) compilation is not supported. Ensure that in Project Properties > SYCL   Enable FPGA Workflows is set to no.
  • For debugging on an FPGA emulator, no support for OpenMP.

On CPU devices and FPGA emulator devices:

  • In Microsoft Visual Studio*, the following message is displayed on the output window during debugging the kernel offloaded to a CPU/FPGA device. "INTEL_GT_DEBUGGER: (257891284) Unable to execute command. The MIEngine is not currently debugging any process." This can be ignored and should not have any effect on the program execution and further debugging
  • It is recommended to disable the GPU debugger for smooth debugging on CPU and FPGA emulator devices.

Previous oneAPI Releases

Notices and Disclaimers

Intel technologies may require enabled hardware, software or service activation.

No product or component can be absolutely secure.

Your costs and results may vary.

© Intel Corporation. Intel, the Intel logo, and other Intel marks are trademarks of Intel Corporation or its subsidiaries. Other names and brands may be claimed as the property of others.

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

The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.

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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.