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). GPU debugging using VS Code is not currently supported on Windows.

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).