Get Started with Intel® Distribution for GDB* on
Linux* OS Host
- Ensure thatgdb-oneapiandgdbserver-gtbinaries are present in the PATH variable. Otherwise, update environment variables by sourcing the<oneAPI_root_dir>/setvars.shscript.
- If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them. Refer to the Installation Guide.
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.Load the debug companion driver with:sudo modprobe igfxdcdThe 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 $ONEAPI_ROOT/debugger/latest/igfxdcd-*-Linux.deb
- For RPM-based systems:sudo rpm -i $ONEAPI_ROOT/debugger/latest/igfxdcd-*-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:If you have not already done so, set up your CLI environment by sourcing thesetvarsscript located in the root of your toolkit installation.Linux (sudo): source /opt/intel/oneapi/setvars.sh Linux (user): source ~/intel/oneapi/setvars.shgdbserver-gt --attach :1234 1The output below indicates successful attachment: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.failed to initialize intelgt device for debug Exiting
Compile the Program with Debug Information
- To get the sample, choose any of the following ways:
- Use the oneAPI CLI utility 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 DPC++ application by enabling the debug info (-gflag) and turning off optimizations (-O0flag).
- You can use the CMake file to configure and build the application. Refer to the README of the sample for the instructions.
- To compile thearray-transform.cppsample application without the CMake file, issue the following commands:dpcpp -g -O0 array-transform.cpp -o array-transformThe CMake file provided with the sample already passes the-g -O0flags.
- If 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
- Ahead-of-Time (AOT) compilation can be employed to avoid the Just-in-Time (JIT) compilation costs at runtime. To use Ahead-of-Time 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-transformAhead-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.
Start a Debug Session
- (Optional) Disable the Auto-Attach feature by defining the environment variable as follows:export INTELGT_AUTO_ATTACH_DISABLE=1The Auto-Attach feature enables listening to debug events from the GPU. This feature is enabled by default and does not affect the debugging capability on the CPU device. You can turn it off to eliminate the extra output the feature creates. For more information about Auto-Attach, refer to the Tutorial.
- 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 cpu
- For debugging on the GPU:run gpu
- For debugging on the FPGA-emulator:run accelerator
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 Intel® oneAPI Toolkits and links to useful resources.
The document briefly describes Intel® Distribution for GDB* prerequisites and useful commands.