Get Started with Intel® Distribution for GDB* on Linux* OS Host
Start using the Intel® Distribution for GDB* for debugging 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 information about key capabilities, new features, and known issues.
You can use a SYCL* 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 systems and additional configuration for remote debugging.
Prerequisites
If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them. Refer to the Installation Guide.
Additionally, you can install an extension for Visual Studio Code* for debugging GPU with Intel® Distribution for GDB*. Refer to the .
Set Up the GPU Debugger
To set up the GPU debugger, you must have root access.
During kernel debugging, the GPU is halted and the video
output is unavailable on your target machine. Because of this, you cannot debug the GPU from the target system if the GPU card of the system is also used for graphical output. In this case, connect to the
machine via
ssh.
- Install the necessary dependencies with the following command:sudo apt install dkms linux-headers-generic
- Set up your CLI environment by sourcing thesetvarsscript located in the root of your toolkit installation.Linux (sudo):source /opt/intel/oneapi/setvars.shLinux (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 igfxdcdUpdate the debug companion driver each time the debugger is updated, using the same command as for installation.The host system does not recognize theigfxdcdsignature 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 1The output below indicates successful attachment:intelgt: attached to device 1 of 1; id 0x5927 (Gen9) Attached; pid = 1 Listening on port 1234The 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, pressCtrl+C.
Compile the Program with Debug Information
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:
- Use the oneAPI CLI Samples Browser to select Array Transform from the Getting Started category.
- Download from GitHub*.
- Navigate to thesrcof the sample project:cd array-transform/src
- Compile the application by enabling the debug info (-gflag) and turning off optimizations (-O0flag). 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 -O0flags.
- Option 2. To compile thearray-transform.cppsample application without the CMake file, issue the following commands:dpcpp -g -O0 array-transform.cpp -o array-transformIf compilation and linking is done separately, retain the-g -O0flags at the link step. The link step is whendpcpptranslates 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 kblfor 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-enableand-cl-opt-disableflags 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-transformAhead-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
For OpenMP CPU offload, when Intel® oneAPI Level Zero (Level Zero) loader libraries are installed, before running the application, set the environment variable to use the OpenCL CPU backend:
LIBOMPTARGET_PLUGIN=opencl
. Start a Debug Session
If you use a Linux* kernel 5.9+, before starting 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_msFor 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_msThe 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
When the setup above is completed, start the debug session:
- Start Intel® Distribution for GDB* as follows:gdb-oneapi array-transformYou should see the(gdb)prompt.
- To make sure that the kernel is offloaded to the right device, do the following steps. When you execute theruncommand from the(gdb)prompt, pass thecpu,gpuoracceleratorargument:
- For debugging on the CPU:run cpuExample output:[SYCL] Using device: [Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz] from [Intel(R) OpenCL]
- For debugging on the GPU:run gpuExample output:[SYCL] Using device: [Intel(R) Graphics Gen9 [0x3e9b]] from [Intel(R) Level-Zero][New Thread 1073741824]
- For debugging on the FPGA-emulator:run acceleratorExample output:[SYCL] Using device: [Intel(R) FPGA Emulation Device] from [Intel(R) FPGA Emulation Platform for OpenCL(TM) software]
Thecpu,gpu, andacceleratorparameters are specific to the Array Transform application. - To quit the Intel® Distribution for GDB*:quit
For your convenience, common Intel® Distribution for GDB* commands are provided in the Reference Sheet.
To debug the Array Transform sample and learn more about Intel® Distribution for GDB* , walk through basic debugging
scenarios using the Tutorial.
Learn More
Document | Description |
---|---|
This document describes the basic scenarios to follow while debugging SYCL* 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 information about key capabilities, new features, and known issues of Intel® Distribution for GDB*. | |
This page contains brief introduction on oneAPI toolkits and links to useful resources. | |
This one-page document briefly describes Intel® Distribution for GDB* prerequisites and useful commands. | |
This small SYCL* application has two versions: bugged and fixed. Use the sample to exercise application debugging with Intel® Distribution for GDB*. |
Notices and Disclaimers
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.