Get Started with GDB* for oneAPI on
Linux* OS Host (Beta)
Set Up the GPU Debugger
- Check that you have installed and loaded the debug companion driver(igfxdcd). You can check whether the module is installed with:modinfo igfxdcdIf the module is not found, install it with:
where<install_dir>is the oneAPI install location . To check if the module is loaded, type:lsmod | grep igfxdcdIf the output is empty, load the debug companion driver with:sudo modprobe igfxdcdYou must load the module after each system reboot.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:sudo dpkg -i <install_dir>/debugger/latest/igfxdcd-<version>-Linux.deb
- For RPM-based systems:sudo rpm -i <install_dir>/debugger/latest/igfxdcd-<version>-Linux.rpm
- 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 :1234 1The output below indicates successful attachment:Attached; pid = 1 Listening on port 1234
- To exit testing, press Ctrl+C.If the output is similar to the shown below, it means that the companion driver is not installed properly or you have restarted the system without callingmodprobeafterwards:failed to initialize GT; result: Failure Exiting
Compile the Program with Debug Information
- Compile the DPC++ application by enabling the debug info (-gflag) and turning off optimizations (-O0flag). To debug thearray-transform.cppsample application, issue the following commands:dpcpp -g -O0 array-transform.cpp -o array-transformThe.cmakefile provided with the sample already passes the-g -O0flags.
- For Intel® oneAPI Base Toolkit version beta06 or lower, tell the DPC++ runtime that you want to preserve the debug information embedded in the kernel by defining theSYCL_PROGRAM_COMPILE_OPTIONSenvironment variable as follows:export SYCL_PROGRAM_COMPILE_OPTIONS="-g -cl-opt-disable"The DPC++ runtime converts the kernel to an executable native code via a JIT compilation.
- To use Ahead-of-Time (AOT) compilation mode:
For more information on AoT compilation, please refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.
- For debugging on GPU:Pass the-cl-opt-disableand-cl-kernel-debug-enableflags 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-cl-kernel-debug-enableflag is required to run the application under the debugger. If it is not passed, the kernel cannot be offloaded to GPU during the debugging session, resulting in a runtime error.
- For debugging on CPU, no additional actions are required.
Start Debug Session
- For debugging on CPU:run cpu
- For debugging on GPU:run gpu
- Define the environment variables as follows:export CL_CONFIG_DEVICES=fpga-emu
- Ensure thatIntel_FPGA_SSG_Emulatoris installed by running:
The returned value must becat /etc/OpenCL/vendors/Intel_FPGA_SSG_Emulator.icdlibintelocl_emu.so.
This document describes the basic scenarios to follow while debugging DPC++ and OpenCL with GDB*.
This document describes all common tasks that you can complete with GDB* and provides necessary technical details..
The notes contain the most up-to-date information about GDB* as part of the Intel® oneAPI Base Toolkit (Beta).
This page contain brief introduction on Intel® oneAPI Toolkits (Beta) and links to useful resources.