Tutorial: Debugging with Intel® Distribution for GDB*
The setup procedure depends on whether you want to debug a DPC++, OpenMP™, or OpenCL™ program. For remote debugging, configure your systems the following way:
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 to File > New > Browse Intel® oneAPI Samples. Select the Debugger: Array Transform sample.
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>\array-transform.exe.
Set Working Directory to <path_to_deployment_directory>.
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.
Set Deployment Directory to <path_to_deployment_directory>.
The directory will be created on the target system and the array-transform executable will be copied to this location.Under Configuration Properties select DPC++.
Go to the Optimization tab and change Set Optimization to Disabled (/Od).
Click the Configuration Manager button at the top of the window and select the Deploy option. Close the Property Pages.
Build and Debug the Sample with the Breakpoint Outside the Kernel
To check whether you set up the remote debugger successfully, start the debugging with the breakpoint outside the kernel:
Your application will launch on the target system. The example output is as follows:
[SYCL] Using device: [Intel® Graphics [0x5927]] from [Intel® Level-Zero]
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set Enable Debugging to True.
Set Server to the name of the remote target system.
Set TCP/IP post to the port number used when running gdbserver-gt. The default is 1234.
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 Sample GPU Debugging Session to start the debugging.
Prepare a Project for Debugging on a GPU
To debug an OpenMP project, set environment variables as follows:
For opencl:
LIBOMPTARGET_OPENCL_COMPILATION_OPTIONS=-g -cl-opt-disableFor level0:
LIBOMPTARGET_LEVEL0_COMPILATION_OPTIONS=-g -cl-opt-disableTo prepare a project for debugging, do the following:
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set Enable Debugging to True.
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.
Now you are ready to debug your project with the kernel offloaded to the 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.
Ensure you use the following flags when calling the clBuildProgram function:
-g -cl-opt-disable to enable the debug 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.
Set Up Intel® Distribution for GDB* with Enhanced GPU Offload
Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
Set Enable Debugging to True.
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.
Build and Debug the Sample
Now you are ready to debug your project with the kernel offloaded to the GPU. Follow the steps in Sample GPU Debugging Session to start the debugging.