Tutorial: Debugging with Intel® Distribution for GDB*

Set up a Remote Debugging Session

For remote debugging, configure your systems the following way:

Prepare a Project for Debugging

The setup procedure depends on whether you want to debug a DPC++, OpenMP™, or OpenCL™ program.

Debugging DPC++ Program

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

  1. On your host system, launch Microsoft Visual Studio*. Navigate to Extensions > Intel > Browse Intel® oneAPI Samples. Under Intel® oneAPI Base Toolkit > Debugger, select the Array Transform sample.

  2. Navigate to Property pages > DPC++ and ensure that Debug Information Format is set to Program Database. Go to the Optimization tab and ensure that Set Optimization is disabled. Go to Property pages > Linker and set Pass additional options to device compilers to `/Od`.

    Compile your application.

Debugging OpenMP Program

  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.

Debugging OpenCL Program

To debug an OpenCL program, 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 you 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 located 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:

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 .

Set up Project Debugging Properties

  1. Open array-transform Property Pages. Under Configuration Properties choose Debugging.

  2. From the Debugger to launch drop-down menu, choose Remote Windows* Debugger.

  3. Set Remote Command to the path to <path_to_deployment_directory>\array-transform.exe.

  4. Set Working Directory to <path_to_deployment_directory>.

  5. Update Remote Server Name. 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 array-transform executable will be copied to this location on the target system.

  7. Go to Property Pages > Configuration Manager and check the Deploy checkbox for the project. If the checkbox is disabled, make sure that you have specified the deployment directory.

To debug an OpenMP project, set environment variables as follows:

Run the Microsoft Visual Studio* remote debugger. For instructions, see the Microsoft documentation.

gdbserver-gt starts automatically on the target system when debugging is enabled. If not, run the server on the target manually.

Now you are all set to debug both host side of the program and the GPU kernel.