Prerequisites

Set Up the GPU Debugger

Install the necessary dependencies with the following command:
sudo apt install dkms linux-headers-generic
Set up your CLI environment by sourcing the
setvars
script located in the root of your toolkit installation.
Linux (sudo):
source /opt/intel/oneapi/setvars.sh
Linux (user):
source ~/intel/oneapi/setvars.sh
Install the debug companion driver
(igfxdcd)
with:
For APT-based systems:

sudo dpkg -i $ONEAPI_ROOT/debugger/latest/igfxdcd-*-Linux.deb

For RPM-based systems:

sudo rpm -i $ONEAPI_ROOT/debugger/latest/igfxdcd-*-Linux.rpm
Load the debug companion driver with:
sudo modprobe igfxdcd
Update the debug companion driver each time the debugger is updated, using the same command as for installation.
The host system does not recognize the
igfxdcd
signature if the public signature key is not installed on the system. You can download the key from the following locations:
For APT-based systems: https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
For RPM-based systems: https://yum.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2023.PUB
Test if you now can attach to the GPU and listen to debug events by executing the following command:
gdbserver-gt --attach --hostpid=999 :1234 1
The output below indicates successful attachment:
intelgt: attached to device 1 of 1; id 0x5927 (Gen9)
Attached; pid = 1
Listening on port 1234
The output below indicates that the companion driver is not installed or loaded properly. Please, review the GPU installation and configuration instructions to ensure that you set up the device correctly.
no device '1' found, there are 0 devices

Exiting
To exit testing, press
Ctrl+C
.

Compile the Program with Debug Information

To get the sample, choose any of the following ways:

Use the oneAPI CLI Samples Browser to select Array Transform from the Getting Started category.
Download from GitHub*.

Navigate to the

src

of the sample project:

cd array-transform/src

Compile the application by enabling the debug info (

-g

flag) and turning off optimizations (

-O0

flag). Disabling optimization is recommended for stable and accurate debug environment: this helps to avoid confusion caused by changes to the code after compiler optimization.

You can still compile the program with optimization enabled (-O2 flag), which can be helpful if you aim at GPU assembly debugging.

You can compile the program in several ways. Options 1 and 2 use just-in-time (JIT) compilation, which is recommended to debug the sample. Option 3 uses ahead-of-time (AOT) compilation.

Option 1. You can use the CMake file to configure and build the application. Refer to the README of the sample for the instructions.

The CMake file provided with the sample already passes the

-g -O0

flags.

Option 2. To compile the

array-transform.cpp

sample application without the CMake file, issue the following commands:

dpcpp -g -O0 array-transform.cpp -o array-transform

If compilation and linking is done separately, retain the

-g -O0

flags at the link step. The link step is when

dpcpp

translates these flags to be passed to the device compiler at runtime. Example:

dpcpp -g -O0 -c array-transform.cpp
dpcpp -g -O0 array-transform.o -o array-transform

Option 3. You can use AOT compilation to avoid longer JIT compilation times at runtime. JIT compilation can take significantly longer for large kernels under the debugger. To use Ahead-of-Time compilation mode:

For debugging on GPU:

Specify the device that you will use for program execution. For example,
-device kbl
for 7th generation Intel® Core™ Processor (Kaby Lake with Intel® Processor Graphics Gen9). For the list of supported options and more information on AOT compilation, refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.
Pass the 
-cl-kernel-debug-enable
and
-cl-opt-disable
 flags to the device compiler.

For example:

dpcpp -g -O0 -fsycl-targets=spir64_gen-unknown-unknown-sycldevice \
-Xs "-device kbl -internal_options -cl-kernel-debug-enable -options -cl-opt-disable" \
array-transform.cpp -o array-transform

Ahead-of-Time compilation requires the OpenCL™ Offline Compiler (OC Compiler LOC). For more information, refer the section “Install OpenCL™ Offline Compiler (OCLOC)” of the Installation Guide.

For debugging on CPU:

dpcpp -g -O0 -fsycl-targets=spir64_x86_64-unknown-linux-sycldevice array-transform.cpp -o array-transform

Start a Debug Session

Copy the contents of the following files to a location where you can easily find it:
For 5.9 - 5.12:
/sys/kernel/debug/dri/0/i915_params/enable_hangcheck
/sys/class/drm/card0/engine/rcs0/preempt_timeout_ms
For 5.13+:
/sys/kernel/debug/dri/0/i915_params/enable_hangcheck
/sys/kernel/debug/dri/0/i915_params/request_timeout_ms
/sys/class/drm/card0/engine/rcs0/preempt_timeout_ms
After a debug session, set back the original values you noted down.
Run the following commands (requires root/sudo access):
For 5.19 - 5.12:
echo N | sudo tee /sys/kernel/debug/dri/0/i915_params/enable_hangcheck
echo 0 | sudo tee /sys/class/drm/card0/engine/rcs0/preempt_timeout_ms
For 5.13+:
echo N | sudo tee /sys/kernel/debug/dri/0/i915_params/enable_hangcheck
echo 0 | sudo tee /sys/kernel/debug/dri/0/i915_params/request_timeout_ms
echo 0 | sudo tee /sys/class/drm/card0/engine/rcs0/preempt_timeout_ms
The above steps configure card 0 and the render command streamer on that card. If your system has more than one card or the setup uses compute command streamers, repeat the above steps for each card and for each command streamer.
Alternatively, you may add the following kernel parameters, which would cover all cards and all command streamers on the system:
For 5.9 - 5.12:
i915.enable_hangcheck=0
For 5.13+:
i915.request_timeout_ms=0
i915.enable_hangcheck=0

Start Intel® Distribution for GDB* as follows:

gdb-oneapi array-transform

You should see the

(gdb)

prompt.

To make sure that the kernel is offloaded to the right device, do the following steps. When you execute the

run

command from the

(gdb)

prompt, pass the

cpu

,

gpu

or

accelerator

argument:

For debugging on the CPU:

run cpu

Example output:

[SYCL] Using device: [Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz] from [Intel(R) OpenCL]

For debugging on the GPU:

run gpu

Example output:

[SYCL] Using device: [Intel(R) Graphics Gen9 [0x3e9b]] from [Intel(R) Level-Zero][New Thread 1073741824]

For debugging on the FPGA-emulator:

run accelerator

Example output:

[SYCL] Using device: [Intel(R) FPGA Emulation Device] from [Intel(R) FPGA Emulation Platform for OpenCL(TM) software]

The

cpu

,

gpu

, and

accelerator

parameters are specific to the Array Transform application.

To quit the Intel® Distribution for GDB*:

quit

Learn More

Notices and Disclaimers