Get Started with Intel® Distribution for GDB* on Windows* OS Host
Start using the Intel® Distribution for GDB* for debugging applications. Follow the
instructions below 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 oneAPI toolkits, visit
the product
page.
Visit the Release
Notes
page for information about key capabilities, new features, and known
issues.
You can use a SYCL* sample code, Array Transform, to get started with
the Intel® Distribution for GDB*. The sample does not generate errors
and aims to be minimal for illustrating debugger features. The code
processes elements of the input array depending on whether they are
even or odd, and produces an output array. You can use the sample to
debug on both the CPU or GPU. Note though that GPU
debugging requires
two systems and additional configuration for remote debugging.
Prerequisites
- Install the Intel® oneAPI Base Toolkit for Windows* OS.
- Install Microsoft Visual Studio* 2019 or 2022.Support for Visual Studio* 2017 is removed starting Intel® oneAPI 2022.2 release.
- If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them.
Get Started with CPU Debugging
Build the Application
- In Microsoft Visual Studio*, go toFile > New > Browse Intel oneAPI Samplesand selectDebugger: Array Transform.If you have already fetched the sample or you have your own sample, simply open the solution file with Microsoft Visual Studio.
- In theSolution Explorer, right-click thearray-transformproject and selectProperties. Alternatively, press Alt+Enter.
- UnderConfiguration Properties, selectGeneraland setPlatform ToolsettoIntel® oneAPI DPC++ Compiler.
- UnderConfiguration Properties, selectDebugging.SetCommand Argumentstocpu.
- SelectLinkerand set thePass additional options to device compilersfield to/Od.This setting disables kernel optimizations to provide a smooth debug experience.
- ClickApplyto save the changes.
- To build the solution, selectBuild > Build Solutionin the main Visual Studio toolbar. In theOutputwindow, verify that the build is successful.
Debug the Application
You are ready to debug your project.
- Set breakpoint at line 83 in thearray-transform.cppfile.
- From theDebugmenu, selectStart Debugging.
- Click theLocal Windows Debuggermenu.
You will see when the thread hits the breakpoint.
Refer to the
tutorial
to learn more about using Intel® Distribution for GDB*.
Get Started with GPU Debugging
For debugging on a GPU using Intel® Distribution for GDB*, you
must complete the remote setup of Microsoft Visual Studio remote
debugger.
Debugging and running an application on the same machine is not
supported yet.
High-level steps are the following:
- On the target system, install Intel® oneAPI run-time dependencies and Microsoft Visual Studio remote debugger.
- On the host system, prepare an application for debugging using oneAPI plugin of Microsoft Visual Studio.To debug a SYCL* application, complete the following steps:
- On the target system, debug the application with the kernel offloaded to the GPU.
- On the host system, analyze the Intel® Distribution for GDB* output.

If you are more comfortable with video format, refer to the
getting started
video
describing how to set up Intel distribution for GDB to debug a
SYCL* app with kernels offloaded to the GPU device.
Configure the Target System
- Make sure that runtime dependencies on shared libraries from Intel® oneAPI Toolkits are available on the target system. You can choose one of the following ways:
- Install run-time dependencies on the target system (recommended). Select Intel® oneAPI DPC++/C++ Compiler Runtime for Windows* from the list of runtime dependencies.
- Install Intel® oneAPI DPC++/C++ Compiler component from Intel® oneAPI Base Toolkit on the target system.
- Copy runtime dependencies from the host to the target.
- Add the runtime dependencies to the PATH variable on the target system. Skip this step if you opted for installing runtime dependencies package in step 1.If you use the sample program, Array Transform, add the following compiler paths to thePATHvariable:
- Path toIntel\oneapi\compiler\latest\windows\bin
- Path toIntel\oneapi\compiler\latest\windows\redist\intel64_win\compiler.
- Do not add these settings to theEnvironmentfield in theProperty Pages > Debuggingtab in Microsoft Visual Studio. Otherwise, this value substitutes the originalPATHvariable on the remote system.
- Additional Files to Deployfeature of Microsoft Visual Studio does not support deploying entire directories. Do not use this option for deploying oneAPI libraries.
- Copy the installer of Microsoft Visual Studio remote debugger(gen_debugger_target.msi)from the host system to the target one.For targets with 6th-10th Gen Intel® Core™ processor families (except for 10th Gen Intel® Core™ processor family (Codename Ice Lake)), use thegen_debugger_target_gen9.msiinstaller.The installer is located at<install_dir>\target. The default installation path isC:\Program Files (x86)\Intel\oneapi\debugger\latest. You can use %ONEAPI_ROOT% variable, specifying the debugger latest version:%ONEAPI_ROOT%\debugger\latest.
- Run the installer on the target. After the installation, reboot the system.The installer sets the following registry keys to 0:
- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\GraphicsDrivers\Scheduler\EnablePreemption
- HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\GraphicsDrivers\TdrLevel
These settings disable Timeout Detection and Recovery (TDR) and preemption requests from the GPU scheduler. OS will not be able to recover automatically if the GPU stops responding while producing a graphics output. Ideally, install the remote debugger only on computing GPUs.To learn more about Microsoft Visual Studio remote debugger, refer to Microsoft documentation.
Configure and Debug the Application
The further setup procedure depends on whether you want to
debug a program following SYCL*, OpenMP™, or OpenCL™ standards. For remote
debugging, configure your systems as described in the following
sections:
Debug a SYCL* Application on a GPU
Prepare a Project for Debugging on a GPU
Follow the steps below to set up the debugging session for the
Array Transform sample:
- On your host system, launch Microsoft Visual Studio*. Navigate toFile > New > Browse Intel® oneAPI Samples.Select theDebugger: Array Transformsample. If you already created the Debugger: Array Transform project for CPU debugging, you can use that existing project.
- Open Array TransformProperties. You needPropertieswindow to complete all of the next steps in this section.
- UnderConfiguration PropertiesselectDebugging.
- From theDebugger to launchdrop-down menu, selectRemote Windows* Debugger.
- ForRemote Command, specify the path to the deployment directory on thetargetsystem. For example,C:\deploy\array-transform.exe.
- SetRemote Command Argumentstogpu.
- SetWorking Directoryto the path to the deployment directory on thetargetsystem.
- UpdateRemote Server Nameusing the remote debugger name from the target system, including the port number. The default port used by the Microsoft Visual Studio* 2019 Remote Debugger server is 4024.You can get the Remote Server name from the window that appears on the target system when you start the Remote Debugger.
- SetDeployment Directoryto the path to the deployment directory on thetargetsystem.The directory will be created on the target system and thearray-transformexecutable file will be copied to this location.Remote Command,Working Directory, andDeployment Directoryfields must point to the same path.
- UnderConfiguration PropertiesselectDPC++.
- Go to theGeneraltab and changeDebug Information FormattoProgram Database (/Zi).
- Go to theOptimizationtab and changeSet OptimizationtoDisabled (/Od).LeaveEnable/Disable DPC++ early optimization before generation of SPRI-V codeas default.
- Click theApplybutton to set your changes.
- Click theConfiguration Managerin the upper right corner of thePropertieswindow and mark theDeploycheck box. Close the Property Pages.TheDeploycheck box is disabled until theDeployment Directoryis specified.
Build and Debug the Sample with the Breakpoint Outside the Kernel
To verify the remote debugger setup, start the debugging with
the breakpoint outside the kernel:
- On the target system, start the remote debugger by clicking theRemote Debuggerin theStartmenu.
- On the host system, return to your project and set a breakpoint outside the kernel offloaded to the GPU. For example, at line 83 of thearray-transform.cppfile.
- To build the solution, selectBuild > Build Solution. In theOutputwindow, verify that the build is successful.
- To start debugging, on theDebugtoolbar, clickRemote Windows Debuggerbutton.
- You may be prompted to log in to the target system. Be sure that credentials are set for the target system.
- If you see the error message"Target is not available. GDB Server cannot be run automatically."for the first time, refer to the “Troubleshooting” section. Then, you can ignore the message and click OK.
When the debugger hits the breakpoint, the example Visual Studio output is as follows:Your application will launch on the target system. The example output of the Remote Windows Debugger on the target system is as follows:[SYCL] Using device: [Intel(R) Graphics [0x5927]] from [Intel(R) Level-Zero]Such output indicates that you set up the remote debugger successfully. - Quit the debugger by clicking the
button.
Now you can set up Intel® Distribution for GDB* to analyze a
part of the program offloaded to a GPU.
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
- OpenTools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
- SetEnable DebuggingtoTrue.
- (Optional) Enable secure connection to the target by settingEnable SSH SSL TunneltoTrue.If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change theMaximum Number of Retriesto control how many times a user can re-enter credentials.Security of the SSH configuration defines security of your system. See the NIST SSH guidelines on setting a strong password.
- UpdateServerfield using the Remote Debugger name from the target system. Server equals to theRemote Server Nameyou set in the Array TransformProperties.
- SetTCP/IP postto the port number used when runninggdbserver-gt.The default is1234.The TCP/IP port must differ from the port number used by Microsoft Visual Studio remote debugger.
- ClickOKto save the changes.
Build and Debug the Sample with the Breakpoint Inside the Kernel
Now you are ready to debug your project with the kernel
offloaded to the GPU. Follow the steps in the
tutorial
to start the debugging.
Debug an OpenMP Application on a GPU
Prepare a Project for Debugging on a GPU
To debug an OpenMP project, set environment variables as
follows:
- Set device type to GPU:LIBOMPTARGET_DEVICETYPE=GPU
- Chooseopenclorlevel0as an offload target:LIBOMPTARGET_PLUGIN=opencl
- Configure flags for the backend compiler.Foropencl:LIBOMPTARGET_OPENCL_COMPILATION_OPTIONS=-g -cl-opt-disableForlevel0:LIBOMPTARGET_LEVEL0_COMPILATION_OPTIONS=-g -cl-opt-disable
- (Optional) Print offload profile information at the end of offload:LIBOMPTARGET_PROFILE=T
- (Optional) Print OpenMP library debug traces:LIBOMPTARGET_DEBUG=1

To prepare a project for debugging, do the following:
- Create a new C++ Console App project.
- SetProperty Pages > General > Platform ToolsettoIntel C++ Compiler 2021. PressApply.
- SetProperty Pages > C/C++ > Language [Intel C++] > OpenMP SupporttoGenerate Parallel Code (/Qiopenmp).
- SetProperty Pages > C/C++ > Language [Intel C++] > Enable OpenMP OffloadingtoGenerate x86 + SPIR64 fat binary (/Qopenmp-targets:spir64).
- Add your code and compile the application.
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
- OpenTools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
- SetEnable DebuggingtoTrue.
- (Optional) Enable secure connection to the target by settingEnable SSH SSL TunneltoTrue.If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change theMaximum Number of Retriesto control how many times a user can re-enter credentials.Security of the SSH configuration defines security of your system. See the NIST SSH guidelines on setting a strong password.
- SetServerto the name of the remote target system displayed in the Visual Studio remote debugger.
- SetTCP/IP postto the port number used when runninggdbserver-gt.The default is1234.
Build and Debug the Sample
Now you are ready to debug your project with the kernel
offloaded to the GPU. Follow the steps in the
tutorial
to start the debugging.
Debug an OpenCL Application on a GPU
Prepare a Project for Debugging on a GPU
To debug an OpenCL project, the kernel source file must be
available on both host and target systems under the
same
absolute path. To achieve that, do any of the following:- Share the sources of your project from the host to the target system and create a symbolic link on the target that mirrors the host path to the kernel.
- If your project is on a shared drive, which is accessible from both host and target systems, use its network path everywhere.
Do not share the source code from the target system to
the host one. Microsoft Visual Studio internally resolves
paths to sources while the debugger does not - as a result,
it cannot find the specified kernel and set a breakpoint.
Ensure you use the following flags when calling the
clBuildProgram
function:- -g -cl-opt-disableto enable the debugging information and disable optimizations inside the kernel
- -s <full_path_to_kernel.cl>to point to the kernel source fileWithout the flag, Microsoft Visual Studio cannot set a breakpoint inside the kernel.
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
- OpenTools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
- SetEnable DebuggingtoTrue.
- (Optional) Enable secure connection to the target by settingEnable SSH SSL TunneltoTrue.If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change theMaximum Number of Retriesto control how many times a user can re-enter credentials.Security of the SSH configuration defines security of your system. See the NIST SSH guidelines on setting a strong password.
- SetServerto the name of the remote target system displayed in the Visual Studio remote debugger.
- SetTCP/IP postto the port number used when runninggdbserver-gt.The default is1234.
Build and Debug the Sample
Now you are ready to debug your project with the kernel
offloaded to the GPU. Follow the steps in the
tutorial
to start the debugging.
Learn More
Document | Description |
---|---|
This document describes the basic scenarios to follow while debugging SYCL* and OpenCL with Intel® Distribution for GDB*. | |
This document describes all common tasks that you can complete with Intel® Distribution for GDB* and provides necessary technical details. | |
The notes contain information about key capabilities, new features, and known issues of Intel® Distribution for GDB*. | |
This page contains brief introduction on oneAPI toolkits and links to useful resources. | |
The video describes how to set up Intel® Distribution for GDB* to debug a SYCL* app with kernels offloaded to the GPU device. | |
This small SYCL* application has two versions: bugged and fixed. Use the sample to exercise application debugging with Intel® Distribution for GDB*. |
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.