Unique Features in Intel® Distribution for GDB*#

The Intel® Distribution for GDB* (gdb-oneapi) is a superset of the GNU Project debugger (gdb). gdb-oneapi extends a subset of existing GDB commands and features and may, in some cases, add additional debugger commands. You must use gdb-oneapi to debug SYCL C++ and Intel OpenMP workloads (aka kernels) running on Intel GPUs. The additional features in gdb-oneapi focus on debugging SYCL and OpenMP applications written in the C, C++, and Fortran languages. The gdb-oneapi debugger also contains additional bug fixes and supports pretty-printing for several key SYCL types.

See the Intel Distribution for GDB release notes for details regarding new features, bug fixes, and known issues.

Note

The gdb-oneapi debugger does not support debugging OpenCL kernels running on a GPU. Debugging an OpenCL kernel on an Intel CPU is supported.

Note

When using gdb-oneapi to debug an application on an Intel CPU you may find additional GDB extensions that support CPU instructions and features that are unique to Intel CPUs.

To see which version of GDB the gdb-oneapi debugger is based on, type the following:

$ gdb-oneapi --version
GNU gdb (Intel(R) Distribution for GDB\* 2024.0.0) 13.1

In this example, gdb-oneapi is based on version 13.1 of the GNU Project debugger (GDB).

Some Key Extensions in Intel Distribution for GDB#

  • View SIMD lanes; switch between lanes and threads; and view variables and device info when debugging GPU kernel code.

  • Use the Visual Studio and Visual Studio Code (aka VSCode) IDE extensions for gdb-oneapi.

  • Utilize debugger features such as source stepping, expression evaluation, inspecting the call stack, defining conditions for breakpoints, non-stop mode, changing the scheduler-locking setting, and switching the current thread/lane when debugging a GPU kernel.

  • Disassemble Intel GPU machine code and display it as Intel GPU assembly language.

  • Attach gdb-oneapi to an already-running GPU workload.

  • Debug the host application code as well as the GPU code in the same debug session.

  • Debug multiple GPUs in the same debug session.

  • Use convenience variables to inspect GPU work items and global/local indices.

  • Create inferior-specific breakpoints that hit only on the inferior that you specify.

  • Print Intel® Processor Trace (Intel® PT) PTWRITE payloads in the instruction history and function-call history (supported on Intel CPUs only).

  • Read and write Intel® Advanced Matrix Extensions (Intel® AMX) registers (on supported Intel CPUs only).

Modified commands included in Intel Distribution for GDB#

For additional details regarding gdb-oneapi commands, refer to Differences of debugging a kernel on a CPU and a GPU.

Command

Description

info threads [-stopped]

SIMD lane support - Prints additional information about SIMD lanes Allows filtering to show only the stopped threads

thread [thread-id:lane]

SIMD lane support – Allows switching the context to a specific SIMD lane within a thread

thread apply [ thread-id[:lane]| all | all-lanes [-ascending]] [ command]

SIMD lane support - the command can apply a command also to all/ selected active SIMD lanes. Only available threads are applied. To apply all threads including unavailable, add the -unavailable option.

thread filter [ thread-id[:lane]| all | all-lanes [-ascending]] [ -location] [expression]

SIMD lane support - filters from all/selected active SIMD lanes using the location and the expression options. Filtering is applied only on available threads. To filter from all threads including unavailable, add the -unavailable option.

For the “all” and the “all-lanes” range selection option, by default the list of filtered thread ids is printed in descending order. To print in ascending order, add the “-ascending” option.

commands [command-list] end

SIMD lane support - additional ‘/a’ modifier.

record function-call-history

Now shows auxiliary information which can be omitted by ‘/s’ modifier”

break [location] inferior[inferior-num] [if [condition]]

Sets an inferior specific breakpoint

New commands included in Intel Distribution for GDB#

info devices

Display information about available GPU devices

set/show scheduler-locking

Modify run behavior of GPU threads. The setting can be used as following:

  • set scheduler-locking continue – Scheduler locking for continuing commands during normal execution.

  • set scheduler-locking eval – Scheduler locking for function calls during normal execution.

  • set scheduler-locking off – [Shortcut] No locking (threads may preempt at any time).

  • set scheduler-locking on – [Shortcut] Full locking (no thread except the current thread may run).

  • set scheduler-locking replay – Scheduler locking settings for replay mode. W/o arguments completely locks the scheduler in replay mode.

  • set scheduler-locking step – Scheduler locking for stepping commands. W/o arguments locks the scheduler for stepping.

maint jit dump [addr] [filename]

Output a JIT object with specific address to the desired file for offline inspection