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.

• Support for Intel® Core™ Ultra processors (Series 2) and Intel® Arc™ B-Series Graphics on Linux*.

• 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 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

• General hardware requirements: Intel® oneAPI Base Toolkit System Requirements.

• Specific system requirements: Intel® Distribution for GDB* System Requirements.

Documentation

• To set up the debugger, refer to Get Started Guide for Linux*.

• To follow basic debugging scenarios, refer to the Linux Debug Examples.

• To see common Intel Distribution for GDB commands, refer to the Cheat Sheet.

Changes in the 2025.1 release

• Rebased to GDB version 15.2. See the changes here.

• Intel® Distribution for GDB* adds support for Intel® Core™ Ultra processors (Series 2) and Intel® Arc™ B-Series Graphics on Linux*, in addition to the existing Windows support, allowing developers to efficiently debug application code on these new CPUs and GPUs. See https://dgpu-docs.intel.com/driver/client/overview.html for more details.

• Added a ‘reason’ field to the thread’s MI output that maps the stop reason to a string that can be used by MI consumers.

• The info line command now prints all occurrences of the same line, e.g., when using the command on a templated function that is instantiated with different template arguments.

• Added the -shadow-stack-list-frames MI command which allows MI consumers to retrieve the shadow stack backtrace. It is equivalent to the CLI subcommand backtrace shadow but supports low-frame and high-frame as command line parameters.

• Added a new thread filter command to get a list of filtered thread ids.

• Various bug fixes and improvements.

• Improved support for XE2 debugging.

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

Changes in the 2024.2 Release

• Rebased to GDB version 14.2. See the changes here.

• Debugging support for Intel MPX has been removed. This includes the removal of

  • MPX register support

  • the commands set|show mpx bound

• Added further support for Intel® CET Shadow Stack:

  • return, call and displaced stepping on CALL instructions when debugging programs using CET

  • pl3_ssp in coredump files

• When recording with Intel® PT, GDB now supports showing asynchronous events in the instruction history and function-call history. This is controlled by the new command set|show record btrace pt event-tracing.

• Added support for stepping inside atomic regions of a GPU kernel, e.g., inside a sequence of dpas instructions labeled as “Atomic”.

• Fixed a problem where stepping over a statement, e.g. with next, would not stop if the statement was triggering the auto-attach feature.

Changes in the 2024.1 Release

• Added support for reading and writing of the Intel® CET Shadow Stack Pointer (pl3_ssp) register. The following will be added in a future release:

  • return, call and displaced stepping on CALL instructions when debugging programs using CET

  • pl3_ssp in coredump files

• Rebased to GDB version 14.1. See the changes here.

• Added global option set print shadowed on|off to omit shadowed variables for C/C++ and Fortran on info locals. By default shadowed variables are printed.

• Added support for breakpoints inside atomic regions of a GPU kernel, e.g., inside a sequence of dpas instructions labeled as “Atomic”.

• Added support for debugging GPU kernels in large-grf mode. Large-grf mode allows kernels to run with double the number of GRF registers per thread but only half the number of concurrent threads.

• Various bug fixes, including the following:

  • If GDB dies with an internal error or is killed, a gdbserver-ze process is no longer left running in the background.

  • A problem that was causing delays in the start-up phase when using the non-stop mode is fixed.

Changes in the 2024.0 Release

• The target ID of a GPU thread is changed to display the Level Zero device thread identifier in the format ZE s.ss.eu.th, where s denotes the slice, ss the subslice, eu the execution unit, and th the thread.

• The “Execution Mask” (emask) register, which was previously deprecated, is removed.

• In inferior calls made during expression evaluation on GPUs, all SIMD lanes except the selected lane are disabled.

• Added a finer control over scheduler locking settings. Check help set scheduler-locking to see the new options.

• When displaying the PCI location of a GPU device, the domain field is also printed. E.g.: 0000:18:00.0.

• The registers of a thread on a GPU are defined in three groups: arf, grf, virtual. Use the info reg <group> command to list the registers and their values that belong to a particular group.

• Performance is enhanced for GPU debugging to improve the debug session startup time and the info threads command in certain scenarios.

• Added support for defining watchpoints on tagged data pointers (Intel® Linear Address Masking) on CPUs.

• Various bug fixes, including the following:

  • The non-stop mode can be used on systems with multiple (sub)devices.

  • Fixed an auto-attach problem that was seen when attaching to a running application before the Intel® oneAPI Level Zero backend is initialized.

  • Fixed a problem where a redundant SIGINT event could be shown after a GPU workload has been resumed for stepping.

Changes in the 2023.2 Release

• Removed Eclipse plugin, as Eclipse can now be configured to use gdb-oneapi natively. See Using Eclipse IDE for details.

• Rebased on GDB version 13.1. See the changes here.

• Removed the DCD-based gdbserver target from the code base.

• Improve error messages printing during auto attach for GPU offload debugging.

• Added support for reading and writing shared local memory (SLM) via sycl::local_accessor and generic pointers.

• Added convenience variables for workitem coordinates: $_thread_workgroup, $_workitem_local_id, $_workitem_global_id.

• Various bug fixes and improvements, including the following:

  • Fixed a problem where a thread could run until termination and become unavailable as a result of executing the next command when scheduler-locking was set to off or replay.

  • Reduced the overhead of the info threads command. The improvement is applicable when frame argument values are not needed to be printed. This can be achieved by changing the setting globally using set print frame-arguments none, or by using with print frame-arguments none -- info threads for a single command execution.

Changes in the 2023.1 Release

• Added the set|show suppress-mi-notifications command which guards suppression of some MI notifications. Check help set|show suppress-mi-notifications for more info.

• Added the --stopped option to the -thread-info MI command to print stopped threads only.

• The Array Transform and Jacobi samples of the debugger now use the ONEAPI_DEVICE_SELECTOR environment variable to select a device instead of a command-line argument.

• The “Channel Enable” (ce) register is now available in the register list of the GPU target. The “Execution Mask” (emask) register is deprecated; ce should be used instead.

• Various bug fixes and performance improvements, including the following:

  • Fixed occasionally reporting an arbitrary thread as unavailable after resuming the debuggee program.

  • Fixed stopping on module load events using the set stop-on-solib-events 1 command, which allows the user to inspect the newly loaded kernel prior to submission of a workload.

  • Fixed a gdbserver-ze assertion violation due to a race condition in non-stop mode.

  • Improved performance of when hitting a breakpoint with a large number of threads and resuming these stopped threads.

  • Improved performance for single-stepping statements via the next and step commands.

  • Fixed GDB prompt being displayed prematurely when attaching to a live process before the Intel® oneAPI Level Zero backend is initialized.

  • Fixed SIMD wildcard range in thread apply <thread range>:*: unavailable threads are ignored.

  • Renamed labels of unavailable threads in info threads from (inactive) to (unavailable).

Changes in the 2023.0 Release

• Switched from DCD debug driver to Intel® oneAPI Level Zero (Level Zero) (currently only supporting discrete GPUs).

• Bumped GDB version to 12.1. See changes here.

• Added a new option -stopped to info threads to print stopped threads only.

• Added the --qid option to the -thread-info MI command to print qualified-id of threads.

• Fixed issue with corrupted debug sessions after detaching from GPU.

• Improved error reporting, debugging experience and usability overall.

• Various bug fixes and performance improvements.

Changes in the 2022.3 Release

• Added the info devices command. This feature displays additional information about Intel® Graphics Technology devices currently used by the debugged program.

• Fixed and improved the debugger behavior for when the debugged program is restarted while stopped inside the GPU workload.

• Introduced set|show skip-trampoline-functions commands to step through functions marked as trampolines in the debug info. Check help set|show skip-trampoline-functions for more info.

• Fixed a crash in GDB when gdbserver-gt terminates abruptly during the debug session.

• Fixed an issue with function calls in expression evaluation for DG2.

• Various bug fixes and performance improvements.

Changes in the 2022.2 Release

• Bumped GDB version to 11.2. See changes here.

• Introduced set|show suppress-cli-notifications commands to suppress notifications to be printed out. Check help set|show suppress-cli-notifications for more info.

• Added support for function calls in expression evaluation on GPU targets.

• Fixed an issue with loading shared library symbols for Intel® Graphics Technology remote target on Windows*.

• Fixed an issue with the until command when debugging the same executable within a single session. Now, until is interpreted within the current program space.

• Fixed a crash in gdbserver-gt when attempting to continue debugged process when it has died.

• Fixed an error when attempting to re-run the executable while the offloaded GPU kernel inferior is the current context.

• Intel® Graphics Technology specific performance improvements.

• Stability improvements.

• Deprecated the printing of Intel® TSX abort reasons (info tsx-abort-reason). This feature will be removed in the 2022.3 release.

• Added DG2 support (beta). Known issues:

  • Conditional breakpoints may not work as expected.

  • Function calls in expression evaluation do not work correctly.

• Fixed asynchronous MI mode, now one can use set mi-async on.

Changes in the 2022.1 Release

• Various bug fixes and improvements.

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.

• Attaching to a running GPU process in all-stop mode is currently unsupported on XE2.

• Debugging a SYCL GPU application is not supported on Battlemage GPUs where eu_count is 288.

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

• Inspecting local variables.

• Inspecting variable values for different SIMD lanes.

• Source-level stepping.

• Backtracing function calls.

• Examining threads.

• Scheduler-locking step and continue options.

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

• Perform Health Check to identify common setup issues and misconfigurations.

System Requirements

• General hardware requirements: Intel® oneAPI Base Toolkit System Requirements.

• Specific system requirements: Intel® Distribution for GDB* System Requirements.

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

Documentation

To set up the debugger, refer to Get Started Guide for Windows.

Changes in the 2025.1 Release

• Introduced scheduler-locking step and scheduler-locking continue UI buttons to allow the user to control the scheduler locking behavior while debugging. This enables the user to choose whether to stay on the current thread or switch to another when stepping or continuing.

• Added remote target check capability to Intel® Distribution for GDB* Health Check. This allows users to detect setup issues in the remote target from the host machine.

• Rebase the MI extension on to the release branch “Visual Studio 2022 17.12 Preview 3” from Microsoft*.

• Includes performance improvement and bug fixes.

• Added support for XE2 debugging.

Changes in the 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.

Changes in the 2024.2 Release

• Introduction of new Intel® oneAPI SIMD Lane Parallel Watch window for viewing variable values for all SIMD lanes at once when performing GPU debugging.

• Added support to debug applications with shared local memory (SLM) in Visual Studio.

• Debugging support for Intel® Core™ Ultra processors.

• Includes performance improvement and bug fixes.

Changes in the 2024.1 Release

• Includes performance improvement and bug fixes.

• Rebase the MI extension on to the release branch “Visual Studio 2022 17.8 Preview 2” from Microsoft*.

• Improve usability by displaying SIMD Lane in groups of 8.

• Fixed the Fortran Expression Evaluator (FEE) Microsoft Visual Studio* extension to enable the inspection of multiple variables sharing the same name within the Locals view, thereby enhancing the debugging experience for OpenMP programs.

• Addressed the evaluation of zero-length string variables in the FEE.

Changes in the 2024.0 Release

• Includes performance improvement and bug fixes.

• Ability to specify custom install directory of oneAPI base toolkit.

• Added the option to filter the stopped threads in Intel® oneAPI GPU Thread window.

• Fixed Fortran Expression Evaluator (FEE) extension incompatibility issues with Visual Studio 2022 version 17.7.

• Added int64 array bound support to FEE Visual Studio extension.

• The “Execution Mask” (emask) register, which was previously deprecated, is removed.

Changes in the 2023.2 Release

• Includes performance improvement and bug fixes.

• Ability to debug GPU locally on a single machine.

• Removed the DCD-based gdbserver target from the code base.

• Following improvements were made to the Intel® oneAPI GPU Thread window:

  • Add filter feature.

  • Add option to group by columns.

  • Addition of workgroup ID, local ID and global ID.

• Added support for debugging assumed-rank arrays in Visual Studio with ifx compiler.

• Breakpoint hit count in the Breakpoint window now increments correctly.

• localID, globalID, and workgroupID have been added in the oneAPI Visual Studio extension.

• Now you can debug on a single machine in Windows. A remote debugging machine is no longer required.

• Thread filtering is now supported in Visual Studio when debugging a SYCL kernel.

Changes in the 2023.1 Release

• GPU debugging is supported for Windows with Intel® oneAPI Level Zero (Level Zero).

• Target installer (Intel Distribution for GDB Target) is available with Intel® oneAPI Base Toolkit (Base Kit).

• Introduction of new Intel® oneAPI GPU Thread window for visual representation of threads, lanes and device info when performing GPU debugging.

• Introduction of new SIMD lane toolbar to give user the flexibility to change SIMD lanes on a stopped thread during GPU debugging. This is in addition to the Intel® oneAPI GPU Thread window where user can perform the same operation.

• Introduction of new SIMD lane conditional breakpoint to stop on SIMD lane specific conditions.

• The “Channel Enable” (ce) register is now available in the register list of the GPU target. The “Execution Mask” (emask) register is deprecated; ce should be used instead.

Changes in the 2023.0 Release

• DCD is deprecated and all the libraries that use DCD and/or related components are removed.

• Removed target installer (Intel® Distribution for GDB* Target).

• GPU debugging is not supported for Windows due to DCD deprecation and missing support in Intel® oneAPI Level Zero (Level Zero).

Changes in the 2022.2 Release

• Removed support for Visual Studio* 2017.

• Addressed the issue where the user was unable to connect and debug a target outside the domain network.

• GPU thread names are now accessible in the application debug process in Visual Studio Code* (VS Code).

Changes in the 2022.1 Release

• Support for Microsoft Visual Studio* 2022.

• Two separate debug driver installers depending on platform (refer to Intel® Distribution for GDB* System Requirements)

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 > SYCLEnable 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 affect on the program execution and further debugging.

• We recommend you disable the GPU debugger for smooth debugging on CPU and FPGA emulator devices.