Get Started

  • 2021.3
  • 06/28/2021
  • Public Content

Get Started with Intel® Distribution for GDB* on
Windows*
OS Host

Start using the Intel® Distribution for GDB* for debugging Data Parallel C++ (DPC++)
, OpenMP™,
and OpenCL™ 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 DPC++ 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 requires two systems and additional configuration for remote debugging.

Prerequisites

Get Started with CPU Debugging

Build the Application
  1. In Microsoft Visual Studio* 2017 or 2019, 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.
  2. Go to
    Tools > Options > Debugging > General
    and uncheck the
    Require source files to exactly match the original version
    box. Click
    OK
    .
  3. Go to
    Project > Properties.
    1. Under
      Configuration Properties
      , select
      General
      and set 
      Platform Toolset
      to
      Intel® oneAPI DPC++ Compiler.
    2. Under
      Configuration Properties
      , select
      Debugging.
      • Set
        Command Arguments
        to
        cpu
      • Set the
        Environment
        filed to
        CL_CONFIG_USE_NATIVE_DEBUGGER=1
    3. 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.
    4. Click
      Apply
      to save the changes.
  4. To build the solution, select
    Build > Build Solution
    in the main Visual Studio toolbar. In the
    Output
    window, verify that the build is successful.
Debug the Application
You are ready to debug your project.
  1. Set a breakpoint at line 83.
  2. From the
    Debug
    menu, select
    Start Debugging.
  3. Click the
    Local Windows Debugger
    menu.
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:
  1. On the host system, prepare an application for debugging using oneAPI plugin of Microsoft Visual Studio.
  2. On the target system, debug the application with the kernel offloaded to the GPU.
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 DPC++ app with kernels offloaded to the GPU device.
Configure the Target System
  1. 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.
  2. 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.
  3. 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.
  4. 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 DPC++, OpenMP™, or OpenCL™ program. For remote debugging, configure your systems as described in the following sections:

Debug a DPC++ 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:
  1. 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.
  2. Open Array Transform
    Properties
    . You need
    Properties
    window to complete all of the next steps in this section.
  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_on_target>\array-transform.exe.
      For example,
      C:\deploy\array-transform.exe.
    3. Set
      Remote Command Arguments
      to
      gpu.
    4. Set
      Working Directory
      to
      <path_to_deployment_directory_on_target>.
    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.
      You can get the Remote Server name from the window that appears on the target system when you start the Remote Debugger.
    6. 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.
  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).
      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
    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.
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:
  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. 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.
  5. 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
  1. Open
    Tools > Options > Intel® oneAPI > Intel® Distribution for GDB*.
  2. Set
    Enable Debugging
    to
    True.
  3. 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.
  4. 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.
  5. Click
    OK
    to 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
  • 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.
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-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.
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 the tutorial to start the debugging.

Learn More

Document
Description
This document describes the basic scenarios to follow while debugging DPC++ 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 DPC++ app with kernels offloaded to the GPU device.
This small DPC++ 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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.