Get Started

  • 2021.2
  • 03/26/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 the Known Issues and most up-to-date information.
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 GPU debugging requires two machines and additional configuration for remote debugging.

Prerequisites

If you aim to debug on GPU, install the latest GPU drivers and configure your system to use them.

Get Started with Debugging on a CPU

Build the Application
  1. In Microsoft Visual Studio* 2017 or 2019, go to
    File > New > Browse Intel oneAPI Samples
    and select
    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.
  3. Go to
    Project > Properties
    1. Select
      General
      and set 
      Platform Toolset
      to
      Intel® oneAPI DPC++ Compiler
      .
    2. Select
      Debugging
      • Set
        Command Arguments
        to
        cpu
      • Set the
        Environment
        filed to
        CL_CONFIG_USE_NATIVE_DEBUGGER=1
    3. To disable kernel optimizations for a smooth debug experience, select
      Linker
      and set the
      Pass additional options to device compilers
      field to
      /Od
      .
  4. To build the solution, select
    Build > Build Solution
    . In the
    Output
    window, verify that the build is successful.
Debug the Application
You are ready to debug your project.
  • From the
    Debug
    menu, select
    Start Debugging
    .
  • Click the
    Local Windows Debugger
    menu.
Refer to the tutorial to learn more about using Intel® Distribution for GDB*.

Get Started with Debugging on a GPU

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.
Configure the Target System
  1. Make sure that run-time 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 run-time dependencies.
    • Install Intel® oneAPI Toolkit on the target system.
    • Copy run-time dependencies from the host to the target.
  2. Add the run-time dependencies to the PATH variable on the target system. Skip this step if you opted for installing run-time 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
      .
    • You do not need to 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, so it is inconvenient to 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 install 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.
To learn more about Microsoft Visual Studio remote debugger, refer to Microsoft documentation.
For further instructions on setting up the Intel® Distribution for GDB* debugging session, refer to the tutorial.

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 the most up-to-date information about Intel® Distribution for GDB* as part of the Intel® oneAPI Base Toolkit.
This page contains brief introduction on oneAPI toolkits and links to useful resources.

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.