Start using the Intel® Distribution for GDB* for debugging Data Parallel C++ (DPC++) and OpenCL™ applications. Follow the instructions below to set up the debugger to debug applications with kernels offloaded to CPU and GPU devices.
Intel® Distribution for GDB* is available as part of the Intel® oneAPI Base Toolkit. For more information on oneAPI toolkits, visit the product page.
Visit the Release Notes page for the Known Issues and most up-to-date information.
You can use a DPC++ sample code, Array Transform, to get started with the Intel® Distribution for GDB*. The sample does not generate errors and aims to be minimal for illustrating debugger features. The code processes elements of the input array depending on whether they are even or odd, and produces an output array. You can use the sample to debug on both the CPU or GPU, specifying the chosen device through a command line argument. Note though that GPU debugging requires two machines and additional configuration for remote debugging.
If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them. Refer to the Installation Guide.
To set up the GPU debugger, you must have root access.
Check that you have installed and loaded the debug companion driver (igfxdcd). You can check whether the module is installed with:
modinfo igfxdcd
If the module is not found, install it 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
where <install_dir> is the oneAPI install location.
Load the debug companion driver with:
sudo modprobe igfxdcd
If you have not already done so, 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
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
To exit testing, press Ctrl+C.
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
You can use the sample project, Array Transform, to quickly get started with the application debugger.
To get the sample, choose any of the following ways:
Navigate to the src of the sample project:
cd array-transform/src
Compile the DPC++ application by enabling the debug info (-g flag) and turning off optimizations (-O0 flag).
Option 1. You can use the CMake file to configure and build the application. Refer to the README of the sample for the instructions.
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. Ahead-of-Time (AOT) compilation may help avoid longer just-in-time (JIT) compilation times at runtime. To use Ahead-of-Time compilation mode:
For debugging on GPU:
Pass the -cl-opt-disable and -cl-kernel-debug-enable 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 (OC Compiler LOC). For more information, refer the section "Install OpenCL™ Offline Compiler (OCLOC)" of the Installation Guide.
For debugging on CPU, no additional actions are required.
For more information on AOT compilation, please refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.
When the setup above is completed, start the debug session:
gdb-oneapi array-transform
You should see the (gdb) prompt.
run cpu
Example output:
[SYCL] Using device: [Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz] from [Intel(R) OpenCL]
run gpu
Example output:
[SYCL] Using device: [Intel(R) Graphics Gen9 [0x3e9b]] from [Intel(R) Level-Zero][New Thread 1073741824]
run accelerator
Document |
Description |
---|---|
This document describes the basic scenarios to follow while debugging DPC++ and OpenCL with Intel® Distribution for GDB*. |
|
This document describes all common tasks that you can complete with Intel® Distribution for GDB* and provides necessary technical details.. |
|
The notes contain the most up-to-date information about Intel® Distribution for GDB* as part of the Intel® oneAPI Base Toolkit. |
|
This page contains brief introduction on oneAPI toolkits and links to useful resources. |
|
The document briefly describes Intel® Distribution for GDB* prerequisites and useful commands. |
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.
OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission by Khronos.