This guide is designed to help you start using Intel® Distribution for GDB* for debugging Data Parallel C++ (DPC++) and OpenCL™ applications. It describes how 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 Intel® oneAPI Toolkits, visit the product page.

Visit the Release Notes page for the Known Issues and most up-to-date information.

Prerequisites

Set Up the GPU Debugger

To set up the GPU debugger, you must have root access.

Note: During kernel debugging, the GPU is halted and the video output is unavailable on your target machine. Connect to the machine via ssh.

  1. 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

    Important: The host system does not recognize the igfxdcd signature if the public signature key is not installed on the system. You can download the key from the following locations:

  2. Test if you now can attach to the GPU and listen to debug events by executing the following command:

    Note: 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
    gdbserver-gt --attach :1234 1

    The output below indicates successful attachment: 

    Attached; pid = 1
Listening on port 1234

  3. 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 GT; result: Failure

Exiting

Compile the Program with Debug Information

You can use the sample project, Array Transform, to quickly get started with the application debugger.

  1. 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*.

  2. Navigate to the src of the sample project: 

    cd array-transform/src

  3. Compile the DPC++ application by enabling the debug info (-g flag) and turning off optimizations (-O0 flag).

    • To debug the array-transform.cpp sample application, issue the following commands: 
      dpcpp -g -O0 array-transform.cpp -o array-transform

      Note: The .cmake file provided with the sample already passes the -g -O0 flags.

    • 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

    • Ahead-of-Time (AOT) compilation is the recommended method for typical sized application since compiling with debug information takes considerably longer time. 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.

        Note:

        -cl-kernel-debug-enable flag 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.

      For more information on AOT compilation, please refer to the Intel® oneAPI DPC++ Compiler Developer Guide and Reference.

Start a Debug Session

When the setup above is completed, start the debug session:

  1. (Optional) Disable the Auto-Attach feature by defining the environment variable as follows: 
    INTELGT_AUTO_ATTACH_DISABLE=1

    The 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.

  2. Start Intel® Distribution for GDB* as follows: 
    gdb-oneapi array-transform

    You should see the (gdb) prompt.

To make sure that the kernel is offloaded to the right device, do the following steps:

For Debugging on CPU or GPU

  1. When you execute the run command from the (gdb) prompt, pass the cpu or gpu argument:

    • For debugging on CPU: 
      run cpu
    • For debugging on GPU: 
      run gpu
  2. To follow the basic debugging scenarios, refer to the Tutorial.

For Debugging on an FPGA Emulation Device

  1. Define the environment variables as follows: 

    export CL_CONFIG_DEVICES=fpga-emu

  2. Ensure that Intel_FPGA_SSG_Emulator is installed by running: 

    cat /etc/OpenCL/vendors/Intel_FPGA_SSG_Emulator.icd
    The returned value must be libintelocl_emu.so.

  3. Start Intel® Distribution for GDB* as follows: 
    gdb-oneapi array-transform

  4. Execute the run command from the (gdb) prompt, pass the accelerator argument: 

    run accelerator
  5. To follow the basic debugging scenarios, refer to the Tutorial.

Learn More

Document

Description

Tutorial: Debugging with Intel® Distribution for GDB*

This document describes the basic scenarios to follow while debugging DPC++ and OpenCL with Intel® Distribution for GDB*.

Intel® Distribution for GDB* User Guide

This document describes all common tasks that you can complete with Intel® Distribution for GDB* and provides necessary technical details..

Intel® Distribution for GDB* Release Notes

The notes contain the most up-to-date information about Intel® Distribution for GDB* as part of the Intel® oneAPI Base Toolkit.

Intel® oneAPI product page

This page contains brief introduction on Intel® oneAPI Toolkits and links to useful resources.

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.