Get Started with GDB* for oneAPI on Linux* OS Host (Beta)

Get Started

  • 2021.1-beta
  • 07/29/2020
  • Public Content
Contents

Get Started with GDB* for oneAPI on
Linux*
 OS Host (Beta)

This guide is designed to help you start using GDB* for debugging Data Parallel C++ and OpenCL™ applications. It covers the fundamental debugging experience and describes how to setup the debugger to debug applications with kernels offloaded to the CPU and GPU devices.
GDB* is available as part of the Intel® oneAPI Base Toolkit (Beta). For more information on Intel® oneAPI toolkits (Beta), visit the product page.
The HOST target is out of the scope of this guide: for that, you can use the standard debugger functionality.
Visit the Release Notes page for the Known Issues and most up-to-date information.

Prerequisites

Ensure that
gdb-oneapi
 and
gdbserver-gt
 binaries are present in the path variable. Otherwise, update environment variables by sourcing the
/opt/intel/inteloneapi/setvars.sh
 script.

Set Up the GPU Debugger

Prerequisites:
 Check that you have fulfilled the requirements of the Intel® Graphics Compute Runtime for oneAPI Level Zero and OpenCL™ Driver. In particular, you need to have permissions to access files
/dev/dri/renderD*
. This typically means that your user account is a member of the "video" (on Ubuntu* 18, Fedora* 30, and SLES* 15 SP1) or "render" (on Ubuntu* 19 and higher, CentOS* 8, and Fedora* 31) group.
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. 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 <install_dir>/debugger/latest/igfxdcd-<version>-Linux.deb
    • For RPM-based systems: 
      sudo rpm -i <install_dir>/debugger/latest/igfxdcd-<version>-Linux.rpm
    where
    <install_dir>
     is the oneAPI install location . To check if the module is loaded, type: 
    lsmod | grep igfxdcd
    If the output is empty, load the debug companion driver with: 
    sudo modprobe igfxdcd
    You must load the module after each system reboot.
    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: 
    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.
    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 calling
    modprobe
     afterwards: 
    failed to initialize GT; result: Failure

Exiting

Compile the Program with Debug Information

  1. 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
    The
    .cmake
     file provided with the sample already passes the
    -g -O0
     flags.
  2. 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 the
    SYCL_PROGRAM_COMPILE_OPTIONS
     environment 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.
  3. To use Ahead-of-Time (AOT) 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
      -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 Debug Session

To make sure that the kernel is offloaded to the right device, do the following steps:
For Debugging on CPU or GPU
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
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
    .
When you execute the
run
 command from the
(gdb)
 prompt, pass the
accelerator
 argument: 
run accelerator
When the setup above is completed, start GDB* as follows: 
gdb-oneapi array-transform
You should now see the
(gdb)
 prompt.

Learn More

Document
Description
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.

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.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804