FAQ for the Intel® Distribution for GDB*

author-image

By

What is the difference between gdb and gdb-oneapi?

The Intel® Distribution for GDB* (gdb-oneapi) is a superset of the GNU Project debugger (gdb). gdb-oneapi extends a subset of existing gdb commands and features and may, in some cases, add additional debugger commands. You must use gdb-oneapi to debug SYCL* C++ and Intel OpenMP workloads (aka kernels) running on Intel GPUs. The additional features in gdb-oneapi focus on debugging SYCL* and OpenMP applications written in the C, C++, and Fortran languages.

To see which version of gdb the gdb-oneapi debugger is based on, run the following command in a terminal session:

$ gdb-oneapi --version
GNU gdb (Intel(R) Distribution for GDB\* 2024.0.0) 13.1

In this example, gdb-oneapi is based on version 13.1 of the GNU Project debugger (gdb).

If you get a “gdb-oneapi: command not found” or “gdb-oneapi is not recognized” message, either you have not installed the Intel® oneAPI Base Toolkit or you have not setup the Intel oneAPI environment variables in your terminal session. Installing the Intel® HPC Toolkit also installs the Intel compilers and the gdb-oneapi application debugger.

How do I get started debugging my GPU application?

On your Linux* system, use gdb-oneapi to debug CPU and Intel GPU code. On your Windows* system, select the option to install the oneAPI extensions for Visual Studio when you are installing the Intel® oneAPI Base Toolkit or the Intel® HPC Toolkit. When debugging a Windows application the Microsoft debugger will be used for debugging CPU code and gdb-oneapi will be used for Intel GPU debugging. In both cases (Linux and Windows) the Intel oneAPI Base Toolkit and the Intel HPC Toolkit include the Intel SYCL compilers and the gdb-oneapi debugger. On Windows, both toolkits also include the Intel oneAPI extensions for Visual Studio.

For help debugging GPU-enabled Intel OpenMP applications see this article:

How can I tell if my system software and GPU hardware are properly configured for debugging my application on an Intel GPU?

The simplest way to check that compatible GPU and drivers are installed is to use the sycl-ls command. At a minimum, you need to install the Intel oneAPI DPC++/C++ compiler to get a copy of the sycl-ls utility. For more utility, install the Intel oneAPI Base Toolkit onto your development system (it includes the Intel oneAPI DPC++/C++ compiler, multiple SYCL-enabled libraries and the sycl-ls application). Once installed, open a new terminal session, and source the setvars script to setup the oneAPI development environment variables. From that same terminal session, enter sycl-ls at the prompt, after setvars has completed.

If you are working with a remote Windows debug system and cannot install the oneAPI development tools onto that remote Windows system, you can:

  • Copy the sycl-ls.exe application from your host Windows development system to a temporary directory on the remote Windows debug system.
  • Install the version of the Intel® oneAPI DPC++/C++ Compiler Runtime for Windows that matches the version of the compiler on your host Windows development system, onto the remote Windows debug system.

If there is no compatible GPU installed, you will typically see output like the following:

[opencl:cpu:1] Intel(R) OpenCL, Intel(R) Xeon(R) Gold 6248 CPU @ 2.50GHz OpenCL 3.0 (Build 0) [2023.16.8.0.24_160000]

If there is an Intel GPU present and the appropriate GPU driver is installed, you will see output similar to the following:

[opencl:acc:0] Intel(R) FPGA Emulation Platform for OpenCL(TM), Intel(R) FPGA Emulation Device OpenCL 1.2 [2023.16.9.0.01_160000]
[opencl:cpu:1] Intel(R) OpenCL, Intel(R) Xeon(R) Gold 6248 CPU @2.50GHz OpenCL 3.0 (Build 0) [2023.16.9.0.01_160000]
[ext_oneapi_level_zero:gpu:0] Intel(R) Level-Zero, Intel(R) Data Center GPU Max 1550 1.3 [1.3.26690]

Notice the reference to a level_zero:gpu device in the very last line of the second set of output from the sycl-ls command; this represents a GPU that can be used for running and debugging Intel GPU SYCL code. You might see a GPU device listed in the sycl-ls output as opencl:gpu:0. An application that runs on an OpenCL GPU device cannot be debugged using gdb-oneapi. However, an OpenCL application that runs on the FPGA emulator or on a CPU can be debugged with gdb-oneapi. For more help understanding the output of the sycl-ls command see the SYCL Device Selection in the Host Code article in the Intel oneAPI Programming Guide.

In addition to the presence of a GPU, there are environment variables and kernel parameters that must be configured to enable debugging on the GPU. On Windows, the GPU debug setup is handled automatically by the Visual Studio extension for oneAPI development and debug. See the prerequisites in the Windows Debug Getting Started Guide for more details.

The following environment variable is typically required for a GPU debug session on Linux:

export ZET_ENABLE_PROGRAM_DEBUGGING=1

If you debug as a “normal” user on a Linux system, you need to be a member of the video and render groups. Also, the /sys/class/drm/${card}/prelim_enable_eu_debug feature must be enabled in the GPU kernel mode driver.

The following environment variable can be used to force your SYCL application to run on a GPU device:

export ONEAPI_DEVICE_SELECTOR=level_zero:gpu

The following environment variables may be required, in addition, for an OpenMP GPU debug session:

export LIBOMPTARGET_DEVICETYPE=GPU
export LIBOMPTARGET_PLUGIN=LEVEL0
export OMP_TARGET_OFFLOAD=mandatory

Help debugging Intel® MPI Library applications can be found in the GPU Support section of the Intel® MPI Library Developer Reference for Linux* OS document.

See the links below for more help configuring environment variables and driver parameters for debugging.

The following links may be helpful for understanding and resolving GPU driver issues:

Where do I download current GPU drivers for debugging my application on GPU?

Can I debug my GPU application with Eclipse?

Yes, the Eclipse IDE for C/C++ Developers is supported “natively” by the gdb-oneapi debugger on Linux (Windows is not supported). This means that standard debug support is provided using the Eclipse IDE for C/C++ Developers distribution (Eclipse version 2023-06 (4.28) or later).

For access to advanced gdb-oneapi features (such as visualizing SIMD lanes) in an IDE, you must use Visual Studio (on Windows) or Visual Studio Code (on Linux). The guide below describes how to configure the Eclipse IDE to use gdb-oneapi to debug applications on Linux.

Can I debug my GPU application with Visual Studio on Windows?

Yes, a gdb-oneapi Visual Studio extension is available for use with the Microsoft Visual Studio IDE. During installation of the Intel® oneAPI Base Toolkit (Base Kit) you are given the option to install a collection of Visual Studio extensions that support development of Intel oneAPI applications on your Windows system. Support for developing and debugging Fortran applications requires installation of the Intel® HPC Toolkit (HPC Kit).

  • The list of supported GPU devices can be found here.
  • Be sure to install the latest GPU drivers onto your Windows debug system.
  • Local GPU debugging requires a dedicated GPU for display, in addition to an Intel GPU that supports SYCL or Intel OpenMP compute applications.
  • Use remote GPU debugging when your Windows test system does not have a dedicated GPU for display. In that case, two Windows systems are required: a host and a target (the remote system). Visual Studio and the Base Kit must be installed on the host system. During development, your oneAPI application is deployed from the host system to the target system, where it will run and be debugged.
  • Your remote target system may require installation of the oneAPI runtime libraries to run your application on the remote system. You can find the runtime packages in the “Runtime Versions” section of the “Single Component Downloads and Runtime Versions” article.
  • For a step-by-step guide, read Get Started with Intel® Distribution for GDB* on Windows* OS Host.

Can I debug my GPU application with Visual Studio Code?

Yes, several oneAPI extensions are available for developing oneAPI applications with Visual Studio Code (aka VSCode). A summary of the Intel oneAPI extensions for VSCode can be found in the Using Visual Studio Code with Intel® oneAPI Toolkits User Guide. You can find the latest oneAPI extensions for VSCode in the VSCode marketplace, specifically the extensions that show the “oneAPI” logo. Or type “oneapi” into the extension marketplace dialog inside a running instance of VSCode (Ctrl-Shift-x or “gear icon > Extensions”).

NOTE: The VSCode gdb-oneapi extension only supports debugging your application on Linux systems. For help debugging with VSCode, see the “Troubleshooting” section near the end of the debug extension’s overview.

To debug, you need the “GDB with GPU Debug Support for Intel oneAPI Toolkits” extension as well as the gdb-oneapi debugger, which can be found in the Intel® oneAPI Base Toolkit (Base Kit).

The “Code Sample Browser for Intel oneAPI Toolkits” extension is a convenient way to browse and install Intel oneAPI samples that are ready to be compiled and run. Most of the samples are short and easy to understand. They are especially useful if you want to familiarize yourself with the Intel oneAPI development tools.

Where are the gdb-oneapi release notes?

Where is the gdb-oneapi debugging troubleshooting guide?

Where is the Intel® Distribution for GDB* user manual?

The Intel® Distribution for GDB* (gdb-oneapi) is a superset of the GNU Project debugger (gdb). The complete Intel Distribution for GDB User Manual (PDF) is a superset of the Debugging with GDB documentation; that is, the gdb-oneapi documentation extends the existing gdb documentation. An Intel® Distribution for GDB∗ Reference Sheet (PDF) is a one-sheet summary of the most useful gdb-oneapi commands.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.