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.2
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, 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=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 debug feature of the kernel mode driver 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.
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.