This extension for Visual Studio Code (VS Code) enables additional features of GPU debugging with GDB for Intel® oneAPI toolkits.
To learn more about using extensions with oneAPI, see Using Visual Studio Code with Intel® oneAPI Toolkits.
Start using this VS Code extension with guide Get Started with Intel® Distribution for GDB* on Linux* OS Host.
Note that this feature is only available for the Linux* target platform.
This extension enables the ability to prepare launch configurations for running and debugging projects created using Intel oneAPI toolkits:
- Open your DPC++ project in VS Code.
- Build your DPC++ project with the
-g
and-O0
options to prepare for debugging. - Press
Ctrl+Shift+P ( or View -> Command Palette... )
to open the Command Palette. - Type Intel oneAPI and select
Intel oneAPI: Generate launch configurations
. - Follow the prompts to add a DPC++ launch configuration.
- Open the C++ source file(s) that you will be debugging in the VS Code edit window.
- The configuration is now available to debug and run using the gdb-oneapi debugger. You can find it in .vscode/launch.json. To debug and run, click on the Run icon or press
Ctrl+Shift+D
.
Note that you can modify the configuration manually. For example, you may need to change:
"args"
- An array of arguments to be passed to your app by the debugger."stopAtEntry"
- Setting to "true" forces a break on your main() function. 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.
More information about all the launch.json
features can be found at Configuring C/C++ debugging.
The Debugger Health Checks provide a tool for verifying the setup and functionality of the oneAPI environment and debugger. It allows you to run a series of tests to ensure that key components, such as GPU drivers, environment variables, and debugging tools, are correctly configured.
- Open the Debugger Health Checks panel by clicking on the stethoscope icon in the status bar or pressing Run in the panel.
- The tests will automatically execute, and results will be displayed in a tree format. Each check will show whether it passed, failed, or requires attention (warning).
- Hover over each test result to view additional information about the specific check, including version numbers and recommendations on how to resolve issues.
In the settings, you can specify an additional designation for active and inactive lanes using any text character. This may be useful for clearer recognition of lane status.
In the settings, there's an option to enable or disable the display of inactive threads. This can help users focus on active threads or get a comprehensive view of all threads.
In the debug view, this extension provides SIMD View, which displays the SIMD lane state of an Intel GPU thread. The view will automatically populate when hitting a GPU thread breakpoint.
The specific values corresponding to the status of the SIMD lanes in your current color scheme can be found in the SIMD Lanes tooltip. Dark blue represents active lanes that are stopped at a breakpoint, light blue indicates active lanes that do not meet breakpoint conditions, and grey indicates inactive lanes.
Note that SIMD lane specific breakpoints are saved between sessions, but will be applied only after hitting a regular breakpoint inside the kernel.
There are several ways to set a SIMD lane specific breakpoint:
-
Add such a breakpoint by right-clicking on the desired line, selecting "Add Conditional Breakpoint" and "Expression". Then use the commands -break-insert and specify the thread number using the flag -p and SIMD lane using the flag -l:
-break-insert -p THREADID -l SIMDLANE
-
Use the
Intel oneAPI: Add SIMD lane conditional breakpoint
function at the desired line from the drop-down menu and specify the THREADID and SIMDLANE in format:THREADID:SIMDLANE
Note that SIMD lane specific breakpoints are saved between sessions, but will be applied only after hitting a regular breakpoint inside the kernel.
There are several ways to set a SIMD lane specific breakpoint:
-
Add such a breakpoint by right-clicking on the desired line, selecting "Add Conditional Breakpoint" and "Expression". Then use the commands -break-insert and specify the thread number using the flag -p and SIMD lane using the flag -l:
-break-insert -p THREADID -l SIMDLANE
-
Use the
Intel oneAPI: Add SIMD lane conditional breakpoint
function at the desired line from the drop-down menu and specify the THREADID and SIMDLANE in format:THREADID:SIMDLANE
You can choose a new SIMD lane by clicking on it. Choosing a new SIMD lane will show updated information in the SELECTED LANE tab, and extended thread information can be found using the debug console (command -exec -thread-info
).
You can see additional properties in separate tabs while debugging:
- Lane Number - the number of the currently selected lane;
- State - indicates the current status of the lane;
- Work item Global ID - the global ID coordinates of the Work item processed by the current context. Unsigned int vector of size 3, when available. Otherwise, void;
- Work item Local ID - The local ID coordinates of the work item processed by the current context, within its thread's workgroup. Unsigned int vector of size 3, when available. Otherwise, void;
- Execution Mask - the hex mask encodes for which lanes the breakpoint condition was evaluated to true;
- ID - current thread ID;
- Active Lanes mask - the hex mask of the SIMD lanes which were hit by the breakpoint;
- SIMD Width - the number of working items processed in kernel by a GPU thread.
You can see your device's info in a separate tab while debugging.
The SIMD Variable Watch functions like the classic Watch panel but displays values for all lanes, making it convenient to compare values without the need for switching between lanes. Most expressions can be evaluated only for active lanes, however GDB convenience variables are usually available for inactive lanes, too, e.g. $_workitem_global_id or $_workitem_local_id.
VS Code's generic debugger now includes a feature for viewing binary data. When a variable supports memory viewing and editing, an inline binary icon appears in the Variables view. Clicking on the icon opens the Hex Editor, allowing to perform operations on the binary data. This functionality appears in the Variables and Watch panels. Clicking on the icon opens the Hex Editor, in which is possible to inspect conveniently large pieces of data. This functionality enables users to examine the memory space of Intel® GPU kernels.
Note that SIMD lane specific breakpoints are saved between sessions, but will be applied only after hitting a regular breakpoint inside the kernel.
There are several ways to set a SIMD lane specific breakpoint:
-
Add such a breakpoint by right-clicking on the desired line, selecting "Add Conditional Breakpoint" and "Expression". Then use the commands -break-insert and specify the thread number using the flag -p and SIMD lane using the flag -l:
-break-insert -p THREADID -l SIMDLANE
-
Use the
Intel oneAPI: Add SIMD lane conditional breakpoint
function at the desired line from the drop-down menu and specify the THREADID and SIMDLANE in format:THREADID:SIMDLANE
You can choose a new SIMD lane by clicking on it. Choosing a new SIMD lane will show updated information in the SELECTED LANE tab, and extended thread information can be found using the debug console (command -exec -thread-info
).
You can see additional properties in separate tabs while debugging:
- Lane Number - the number of the currently selected lane;
- State - indicates the current status of the lane;
- Work item Global ID - the global ID coordinates of the Work item processed by the current context. Unsigned int vector of size 3, when available. Otherwise, void;
- Work item Local ID - The local ID coordinates of the work item processed by the current context, within its thread's workgroup. Unsigned int vector of size 3, when available. Otherwise, void;
- Execution Mask - the hex mask encodes for which lanes the breakpoint condition was evaluated to true;
- ID - current thread ID;
- Active Lanes mask - the hex mask of the SIMD lanes which were hit by the breakpoint;
- SIMD Width - the number of working items processed in kernel by a GPU thread.
You can see your device's info in a separate tab while debugging.
The SIMD Variable Watch functions like the classic Watch panel but displays values for all lanes, making it convenient to compare values without the need for switching between lanes. Most expressions can be evaluated only for active lanes, however GDB convenience variables are usually available for inactive lanes, too, e.g. $_workitem_global_id or $_workitem_local_id.
VS Code's generic debugger now includes a feature for viewing binary data. When a variable supports memory viewing and editing, an inline binary icon appears in the Variables view. Clicking on the icon opens the Hex Editor, allowing to perform operations on the binary data. This functionality appears in the Variables and Watch panels. Clicking on the icon opens the Hex Editor, in which is possible to inspect conveniently large pieces of data. This functionality enables users to examine the memory space of Intel® GPU kernels.
VS Code's generic debugger now includes a feature for viewing binary data. When a variable supports memory viewing and editing, an inline binary icon appears in the Variables view. Clicking on the icon opens the Hex Editor, allowing to perform operations on the binary data. This functionality appears in the Variables and Watch panels. Clicking on the icon opens the Hex Editor, in which is possible to inspect conveniently large pieces of data. This functionality enables users to examine the memory space of Intel® GPU kernels.
To display the differences between these two distributions of GDB:
- Press
Ctrl+Shift+P ( or View -> Command Palette... )
to open the Command Palette. - Type help to see help commands.
- Choose
Intel oneAPI: List gdb-oneapi debugger unique commands (help)
. - A new window will open with a list of the differences and links to documentation.
- For quick access to GDB-oneAPI Online Documentation, see
Intel oneAPI: Open gdb-oneapi debugger online documentation (help)
.
Note that the debug session is started by running a command from this terminal. If characters remain in the terminal, this will make the command incorrect and cause the debugging session to hang.
Install Visual Studio Code (version 1.86, or newer) and open this project within it. You also need node + yarn
.
- Switch to project root folder.
yarn install
code .
At this point you should be able to run the extension in the "Extension Development Host".
-
This extension is released under the MIT License.
-
oneapi-gdb-debug-0.5.0.vsix\extension\media\userHelp\content.json
Copyright (c) 2021-2024 Intel Corporation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “Free Software” and “FreeSoftware Needs Free Documentation”, with the Front-Cover Texts being “A GNU Manual,”and with the Back-Cover Texts as in (a) below. (a) The FSF’s Back-Cover Text is: “You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.”
Other names and brands may be claimed as the property of others.
Your use of this software and any required dependent software (
GDB with GPU Debug Support for Intel® oneAPI Toolkits
)
is subject to the terms and conditions of the software license
agreements for the Software Package, which may also include notices, disclaimers, or
license terms for third party or open source software included in or with the Software
Package, and your use indicates your acceptance of all such terms. Please refer to the
./third-party-programs*.txt
or other similarly-named text file included with the Software
Package for additional details.