Prerequisites

Install the Intel® oneAPI Base Toolkit for Windows* OS.
Install Microsoft Visual Studio* 2017, 2019, or 2022.
Support for Visual Studio* 2017 is deprecated as of the Intel® oneAPI 2022.1 release, and will be removed in a future 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

In Microsoft Visual Studio*, go to
File > New > Browse Intel oneAPI Samples
and select
Debugger: 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 the
Solution Explorer
, right-click the
array-transform
project and select
Properties
. Alternatively, press Alt+Enter.
Under
Configuration Properties
, select
General
and set 
Platform Toolset
to
Intel® oneAPI DPC++ Compiler.
Under
Configuration Properties
, select
Debugging.
Set
Command Arguments
to
cpu
.

Select
Linker
and set the
Pass additional options to device compilers
field to
/Od.
This setting disables kernel optimizations to provide a smooth debug experience.
Click
Apply
to save the changes.
To build the solution, select
Build > Build Solution
in the main Visual Studio toolbar. In the
Output
window, verify that the build is successful.

Set breakpoint at line 83 in the
array-transform.cpp
file.
From the
Debug
menu, select
Start Debugging.
Click the
Local Windows Debugger
menu.

Get Started with GPU Debugging

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

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 the
PATH
variable:
Path to
Intel\oneapi\compiler\latest\windows\bin
Path to
Intel\oneapi\compiler\latest\windows\redist\intel64_win\compiler
.
Do not add these settings to the
Environment
field in the
Property Pages > Debugging
tab in Microsoft Visual Studio. Otherwise, this value substitutes the original
PATH
variable on the remote system.
Additional Files to Deploy
feature 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.
The installer is located at
<install_dir>\target
. The default installation path is
C:\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.

DPC++ Application
OpenMP™ Application
OpenCL™ Application

Debug a DPC++ Application on a GPU

On your host system, launch Microsoft Visual Studio*. Navigate to
File > New > Browse Intel® oneAPI Samples.
Select the
Debugger: Array Transform
sample. If you already created the Debugger: Array Transform project for CPU debugging, you can use that existing project.
Open Array Transform
Properties
. You need
Properties
window to complete all of the next steps in this section.
Under
Configuration Properties
select
Debugging.
From the
Debugger to launch
drop-down menu, select
Remote Windows* Debugger.
Set
Remote Command
to
<path_to_deployment_directory_on_target>\array-transform.exe
. For example,
C:\deploy\array-transform.exe
.
Set
Remote Command Arguments
to
gpu.
Set
Working Directory
to <path_to_deployment_directory_on_target>.
Update
Remote Server Name
using 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.
Set
Deployment Directory
to <path_to_deployment_directory_on_target>.
The directory will be created on the target system and the
array-transform
executable file will be copied to this location.
Remote Command
,
Working Directory
, and
Deployment Directory
fields must have the same values.

Under
Configuration Properties
select
DPC++.
Go to the
General
tab and change
Debug Information Format
to
Program Database (/Zi).

Go to the
Optimization
tab and change
Set Optimization
to
Disabled (/Od).
Leave
Enable/Disable DPC++ early optimization before generation of SPRI-V code
as default.

Click the
Apply
button to set your changes.
Click the
Configuration Manager
in the upper right corner of the
Properties
window and mark the
Deploy
check box. Close the Property Pages.
The
Deploy
check box is disabled until the
Deployment Directory
is specified.

On the target system, start the remote debugger by clicking the
Remote Windows Debugger
in the
Start
menu.
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 the
array-transform.cpp
file.
To build the solution, select
Build > Build Solution
. In the 
Output
 window, verify that the build is successful.
To start debugging, on the
Debug
toolbar, click
Remote Windows Debugger
button.
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.

Open
Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set
Enable Debugging
to
True.
(Optional) Enable secure connection to the target by setting
Enable SSH SSL Tunnel
to
True
.
If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change the
Maximum Number of Retries
to 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.

Update
Server
field using the Remote Debugger name from the target system. Server equals to the
Remote Server Name
you set in the Array Transform
Properties.
Set
TCP/IP post
to the port number used when running
gdbserver-gt.
The default is
1234.
The TCP/IP port must differ from the port number used by Microsoft Visual Studio remote debugger.

Click
OK
to save the changes.

Debug an OpenMP Application on a GPU

Set device type to GPU:
LIBOMPTARGET_DEVICETYPE=GPU
Choose
opencl
or
level0
as an offload target:
LIBOMPTARGET_PLUGIN=opencl
Configure flags for the backend compiler.
For
opencl
:
LIBOMPTARGET_OPENCL_COMPILATION_OPTIONS=-g -cl-opt-disable
For
level0
:
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

Create a new C++ Console App project.
Set
Property Pages > General > Platform Toolset
to
Intel C++ Compiler 2021
. Press
Apply.
Set
Property Pages > C/C++ > Language [Intel C++] > OpenMP Support
to
Generate Parallel Code (/Qiopenmp).
Set
Property Pages > C/C++ > Language [Intel C++] > Enable OpenMP Offloading
to
Generate x86 + SPIR64 fat binary (/Qopenmp-targets:spir64).
Add your code and compile the application.

Open
Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set
Enable Debugging
to
True.
(Optional) Enable secure connection to the target by setting
Enable SSH SSL Tunnel
to
True
.
If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change the
Maximum Number of Retries
to 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.

Set
Server
to the name of the remote target system displayed in the Visual Studio remote debugger.
Set
TCP/IP post
to the port number used when running
gdbserver-gt.
The default is
1234.

Debug an OpenCL Application on a GPU

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.

-g -cl-opt-disable
to enable the debugging information and disable optimizations inside the kernel
-s <full_path_to_kernel.cl>
to point to the kernel source file
Without the flag, Microsoft Visual Studio cannot set a breakpoint inside the kernel.

Open
Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set
Enable Debugging
to
True.
(Optional) Enable secure connection to the target by setting
Enable SSH SSL Tunnel
to
True
.
If this option is enabled, you will be asked to enter user credentials while connecting to the target system. You can also change the
Maximum Number of Retries
to 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.

Set
Server
to the name of the remote target system displayed in the Visual Studio remote debugger.
Set
TCP/IP post
to the port number used when running
gdbserver-gt.
The default is
1234.

Learn More

Notices and Disclaimers