Auto-Attach

The auto-attach feature enables listening to debug events from the GPU.

This feature allows the debugger to launch a gdbserver-ze process to listen to GPU debug events and connects the gdbserver-ze to the debugger. For each device on the system, an inferior is created on the gdbserver-ze connection. This feature is designed to improve your debugging experience and ensure that you can debug the kernel offloaded to GPU.

The auto-attach feature is enabled by default.

The feature does not affect the debugging capability on the CPU device. However, to eliminate the extra output this feature creates, you can turn it off with the INTELGT_AUTO_ATTACH_DISABLE environment variable. To do it, execute the following command on the shell before starting gdb-oneapi:

export INTELGT_AUTO_ATTACH_DISABLE=1

To enable the feature again:

unset INTELGT_AUTO_ATTACH_DISABLE

Pretty-Printing

The pretty-printing feature simplifies the display of complex objects. If a pretty-printer is registered for the type of value you are going to print, the debugger simplifies the output. Otherwise, the debugger prints the value normally.

Intel® Distribution for GDB* supports pretty-printing for SYCL* types id, buffer, and range from the sycl namespace.

You can write your own pretty-printer for any type. Refer to the GDB documentation https://sourceware.org/gdb/onlinedocs/gdb/Writing-a-Pretty_002dPrinter.html for more information.

To display the list of pretty-printers available, run the following command:

info pretty-print

Example output:

global pretty-printers:
  SYCL
    sycl::_V1::buffer
    sycl::_V1::id
    sycl::_V1::range
  builtin
    mpx_bound128

Pretty-printing is enabled by default. For example, when you print a value of the index variable:

print index

The output is the following:

$10 = sycl::_V1::id<1> = {32}

To disable pretty-printing and display raw content instead, use the /r flag:

print /r index

Example output:

$11 = {<sycl::_V1::detail::array<1>> = {common_array = {32, <No data fields>}}}

To disable all pretty-printers, use the following command:

disable pretty-printer

To enable pretty-printers:

enable pretty-printer

Prettify Frames

Some C++ templates/SYCL constructs make it difficult to view the output of info threads and backtrace given multi-line function names.

You can use the concept of frame filters to change the visibility of a printed frame with the ‘backtrace’ command. For details refer to the GDB documentation.

It is also possible to change the visibility of a printed frame globally. Consider the setting print frame-info:

(gdb) set print frame-info source-line
(gdb) info threads -stopped
  Id           Target Id                                           Frame
  <...>
  2.3:[0-15]   Thread 1.3                                          53               int dim1 = wiID[1];
  2.4:[0-15]   Thread 1.4                                          53               int dim1 = wiID[1];
  2.5:[0-15]   Thread 1.5                                          53               int dim1 = wiID[1];
  2.6:[0-15]   Thread 1.6                                          53               int dim1 = wiID[1];
  2.7:[0-15]   Thread 1.7                                          53               int dim1 = wiID[1];
  2.8:[0-15]   Thread 1.8                                          53               int dim1 = wiID[1];
  <...>

Refer to the GDB documentation for more information.