Get Started with Intel® Distribution for GDB* on Linux* OS Host
Set Up the GPU Debugger
- If you aim to debug on GPU, a Linux Kernel that supports GPU debugging is needed.
- Enable i915 debug support in Kernel:
- Open a terminal.
- Open the grub file in/etc/default.
- In the grub file, find the lineGRUB_CMDLINE_LINUX_DEFAULT="".
- Enter the following text between the quotes (""):i915.debug_eu=1By default, the GPU driver does not allow workloads to run on a GPU longer than a certain amount of time. The driver kills such long-running workloads by resetting the GPU to prevent hangs. The hangcheck mechanism of the driver is disabled if the application is running under the debugger. If you plan to run long compute workloads also without a debugger being attached, consider applying GPU: Disable Hangcheck by addingi915.enable_hangcheck=0to the sameGRUB_CMDLINE_LINUX_DEFAULTline.
- Update GRUB for these changes to take effect:sudo update-grub
- 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
- Setup environmentUse the following environment variables to enable debugger support for Intel® oneAPI Level Zero:export ZET_ENABLE_PROGRAM_DEBUGGING=1 export IGC_EnableGTLocationDebugging=1
- System checkWhen everything is ready, please run the following command to confirm that the system configuration is reliable:python3 /path/to/intel/oneapi/diagnostics/latest/diagnostics.py --filter debugger_sys_check --forceA possible output of a well configured system is as follows:... Checks results: =========================================================================================================== Check name: debugger_sys_check Description: This check verifies if the environment is ready to use gdb (Intel(R) Distribution for GDB*). Result status: PASS Debugger found. libipt found. libiga found. i915 debug is enabled. Environmental variables correct. =========================================================================================================== 1 CHECK: 1 PASS, 0 FAIL, 0 WARNINGS, 0 ERRORS Console output file: /path/to/logs/diagnostics_filter_debugger_sys_check_force.txt JSON output file: /path/to/diagnostics/logs/diagnostics_filter_debugger_sys_check_force.json ...
Compile the Program with Debug Information
- 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 a stable and accurate debug environment. This helps to avoid confusion caused by changes to the code after compiler optimizations.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:icpx -fsycl -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 whenicpxtranslates these flags to be passed to the device compiler at runtime. Example:icpx -fsycl -g -O0 -c array-transform.cpp icpx -fsycl -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 a GPU:Specify the device that you will use for program execution. For example,-device dg2-g10for Intel® Data Center GPU Flex 140 Graphics. For the list of supported options and more information on AOT compilation, refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.For example:icpx -fsycl -g -O0 -fsycl-targets=spir64_gen -Xs "-device dg2-g10" 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 a CPU:icpx -fsycl -g -O0 -fsycl-targets=spir64_x86_64 array-transform.cpp -o array-transform
Start a 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:
Thecpu,gpu, andacceleratorparameters are specific to the Array Transform application.
- 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) Data Center GPU Flex Series 140 [0x56c1]] from [Intel(R) Level-Zero]
- 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]
- To quit the Intel® Distribution for GDB*:quit
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*.