Intel Distribution for GDB* FAQ
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.2.0) 14.2In 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, confirm that you have installed the Intel® oneAPI Base Toolkit and that you have 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.
Get Started with Intel® Distribution for GDB* on Windows* OS Host
Get Started with Intel® Distribution for GDB* on Linux* OS Host
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 a 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 all or part of 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 script(s) needed to setup the oneAPI development environment variables. From that same terminal session, enter sycl-ls at the prompt, after environment setup has been completed.
If you are using any recommended IDE, such as Visual Studio for Windows, or VS Code for Linux, you can run Intel® Distribution for GDB* Health Check. This tool assists in diagnosing common setup issues and misconfigurations that can prevent successful debugging of applications on an Intel GPU. See the Running Intel® GDB Debugger Health Check in the Windows Debug Getting Started Guide and Debugger Health Checks for oneAPI for more details.
See the oneAPI Development Environmental Setup for details regarding initialization of the oneAPI development environment.
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 no compatible GPU devices are installed, no GPU devices will appear in the output, as shown in the example below:
[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 an Intel GPU is installed and the appropriate GPU driver is installed, the GPU device will appear in the output, as shown below:
[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=1If 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:gpuThe 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=mandatoryHelp 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.
Exhaustive List of DPC++ and SYCL Devices Environment Variables
Get Started with Intel® Distribution for GDB* on Windows* OS Host
Get Started with Intel® Distribution for GDB* on Linux* OS Host
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 Intel® oneAPI Base Toolkit 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.
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® Software Developer Tools” 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∗ Cheat Sheet (PDF) is a one-sheet summary of the most useful gdb-oneapi commands.