User Guide

  • 2022.2
  • 04/11/2022
  • Public Content

GDB GPU Support for Intel® oneAPI Toolkits

Using Visual Studio Code* with Intel® oneAPI Toolkits

Generate Launch Configurations and Debug

This extension for Visual Studio Code (VS Code) enables GPU debugging with the GDB for Intel® oneAPI debugger (
gdb-oneapi
).
  1. Press
    Ctrl+Shift+P
    ( or
    View -> Command Palette…
    ) to open the Command Palette.
  2. Type
    Intel oneAPI
    to view options of the installed extensions.
  3. Click on
    Intel oneAPI: Generate launch configurations
    .
  4. Follow the prompts to add launch configurations. First, select the executable:
  5. Select
    yes
    , to automatically break on main.
  6. Answer the prompt to set arguments to be passed to the application to debug. In the example below, an argument named
    gpu
    will be passed on the command line when the application being debugged is launched.
  7. After completing all of the prompts, you will see the new argument in the
    .vscode/launch.json
    file:
  8. Using the VS Code Explorer, open the source code file or files that contain the section of code you plan to debug. In the example below, the
    array-transform.cpp
    file has been opened and a breakpoint has been set at line #45.
  9. Start debugging by clicking the Run and Debug button on the left. Then click the Debug button at the top. Note the pulldown list of launch configurations next to the Debug button. The pulldown list corresponds to the “name” fields in the launch.json file located in the
    .vscode
    folder of your project folder.
Note that you can modify the configuration manually. For example, you may need to change:
  • "args"
    - Example
    ["arg1", "arg2"]
    . If you are escaping characters, you will need to double escape them. For example,
    ["{\\\"arg1\\\": true}"]
    will send
    {"arg1": true}
    to your application.
  • "stopAtEntry"
    - If set to true, the debugger should stop at the entry-point of the target (ignored on attach). Default value is false.
  • "cwd"
    - Sets the working directory of the application launched by the debugger.
  • "environment"
    - Environment variables to add to the environment for the program. Example:
    [ { "name": "config", "value": "Debug" } ], not [ { "config": "Debug" } ]
    .
For information about launch.json features, see Configuring C/C++ debugging

SIMD View

This extension provides a view in the debug view that displays the SIMD lane state of a Intel GPU thread. The view will automatically populate when hitting a GPU thread breakpoint.
ThreadID
The thread ID that GDB sees in the GPU inferior process. For example, 2.1 in the GDB console would be 1.
To rename the thread while debugging:
  1. Press
    CTRL+Shift+P
    to open the Command Pallette.
  2. Type
    Open Debug Console
    and press enter.
  3. Select the desired thread with:
    -exec thread THREADID
  4. Rename the thread using;
    -exec thread name YOURNAME
  5. Press Continue (F5) on your debug window to see renewed threads.
Name
The string name of the GPU thread.
SIMD Lanes
The status of the SIMD lanes in the thread. The bits indicate how many lanes are active and 0 indicates inactive lane. Typically the status will be SIMD8 (8 lanes). Ideally, all lanes should be active.

Differences between GDB and GDB-oneapi

All differences between these two distributions of GDB can be listed using one of the help command:
  1. Press
    Ctrl+Shift+P
    ( or
    View -> Command Palette…
    ) to open the Command Palette.
  2. Type
    help
    to see help commands.
  3. Select
    Intel oneAPI: List gdb-oneapi debugger unique commands (help)
    .
  4. A new window will open showing the differences and links to documentation.
  5. If you want quick access to GDB-oneAPI Online Documentation, select
    Intel oneAPI: Open gdb-oneapi debugger online documentation (help)
    .

Product and Performance Information

1

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