Tutorial: Debugging with Intel® Distribution for GDB*

Set Up a Remote Debugging Session

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:

DPC++ Application

Prepare a Project for Debugging on a GPU

Follow the steps below to set up the debugging session for the Array Transform sample:

  1. On your host system, launch Microsoft Visual Studio*. Navigate to File > New > Browse Intel® oneAPI Samples. Select the Debugger: Array Transform sample.

  2. Open Array Transform Property Pages.
  3. Under Configuration Properties select Debugging.

    1. From the Debugger to launch drop-down menu, select Remote Windows* Debugger.

    2. Set Remote Command to <path_to_deployment_directory>\array-transform.exe.

    3. Set Remote Command Arguments to gpu.
    4. Set Working Directory to <path_to_deployment_directory>.

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

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

  4. Under Configuration Properties select DPC++.

    1. Go to the General tab and change Debug Information Format to Program Database (/Zi).
    2. Go to the Optimization tab and change Set Optimization to Disabled (/Od).

      Note

      Leave Enable/Disable DPC++ early optimization before generation of SPRI-V code as default.
  5. Click the Apply button to set your changes.
  6. Click the Configuration Manager button at the top of the window and select the Deploy option. Close the Property Pages.

    Note

    The Deploy checkbox is disabled until the Deployment Directory is specified.

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:

  1. On the target system, start the remote debugger by clicking the Remote Windows Debugger in the Start menu.
  2. On the host system, return to your project and set a breakpoint outside the kernel offloaded to the GPU. For example, at line 83.
  3. To build the solution, select Build > Build Solution. In the Output  window, verify that the build is successful.
  4. From the Debug menu, select Start Debugging.

Note

You may be prompted to log in to the target system. Be sure that credentials are set for the target system.

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

  1. Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.

  2. Set Enable Debugging to True.

  3. Set Server to the name of the remote target system.

  4. Set TCP/IP post to the port number used when running gdbserver-gt. The default is 1234.

    Note

    The TCP/IP port should differ from the port number used by Microsoft Visual Studio remote debugger.

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.

OpenMP Application

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

To prepare a project for debugging, do the following:

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

Set Up Intel® Distribution for GDB* with Enhanced GPU Offload

  1. Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.

  2. Set Enable Debugging to True.

  3. Set Server to the name of the remote target system displayed in the Visual Studio remote debugger.

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

OpenCL™ Application

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.

Note

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

  1. Open Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.

  2. Set Enable Debugging to True.

  3. Set Server to the name of the remote target system displayed in the Visual Studio remote debugger.

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