Debug a SYCL* Application on a CPU

Use the simple SYCL application named Array Transform to perform basic debugging operations, such as break, run, print, continue, info, disassemble, and next. The application being debugged is limited to running on multiple CPU threads by setting the ONEAPI_DEVICE_SELECTOR=*:cpu environment variable.

The debug array transform application used in this example can be found in the Intel oneAPI sample repo or by way of the oneapi-cli sample browser tool. After you have installed and initialized the Intel oneAPI Base Toolkit environment, run oneapi-cli --help in your terminal command line. The sample includes a build script to create an application that can be debugged and run on either a CPU or a GPU (the compiler debug flags are set during the build).

See the oneAPI Development Environmental Setup for details regarding initialization of the oneAPI development environment.

Debug a SYCL* Application on a GPU

Use a simple SYCL application named Array Transform to perform basic debugging operations, such as break, run, print, continue, info, disassemble, and next. This example describes how to interact with SIMD lanes, as additional thread elements. The application being debugged is instructed to run on a GPU by setting the ONEAPI_DEVICE_SELECTOR=level_zero:gpu environment variable. For a list of differences of debugging a kernel on a CPU and a GPU, refer to [link to <user-guide/major-diffs.rst>].

Debug a SYCL* Program on the FPGA Emulator

The FPGA emulator runs on the CPU and behaves similarly to the CPU device. Make sure you complete the necessary setup steps described in the Get Started Guide and proceed with instructions on Basic Debugging on CPU.

Debug an OpenCL™ Application

Starting with the 2023.0 release of oneAPI, debugging OpenCL™ applications is not supported. For earlier versions (2022.x and earlier), see these instructions.

Debugging Options

This example has some useful options for debugging, such as Auto-Attach, Reducing Overhead, Pretty-Printing, Prettify Frames, and more.

Live Attach

The debugger supports attaching to applications that are already running. This may be useful to debug workloads that show hang-like behavior, such as deadlocks, infinite loops, etc.

Multi-device debugging

Debugging applications on systems containing multiple GPUs is supported by gdb-oneapi. There are some important restrictions and limitations that need to be considered. Three multi-device scenarios are discussed in this example: a single application submits multiple kernels to multiple devices; multiple applications submit kernels to multiple devices; and multiple applications submit kernels to a single device.

The debug array transform application used in this example can be found in the Intel oneAPI sample repo or by way of the oneapi-cli sample browser tool. After you have installed and initialized the Intel oneAPI Base Toolkit environment, run oneapi-cli --help in your terminal command line. The sample includes a build script to create an application that can be debugged and run on either a CPU or a GPU (the compiler debug flags are set during the build).

Multi-Target

The multi-target feature enables debugging of multiple targets in a single debugging session.

Debugging MPI Programs

There are multiple ways to debug MPI spawned processes. One such method, using gtool, attaches the debugger to the specified processes, while the second method, using xterm, opens a terminal window for each process.

Using Intel® Distribution for GDB* with Docker*

This document describes how to debug Docker* applications running on Intel GPU devices. Instructions how to debug natively can be found here. It describes how to create and use Docker images for the following debugging scenarios, and how to use the run image command to debug.

This document explains how to use Using Intel® Distribution for GDB* (gdb-oneapi) with Docker containers based on the ubuntu:latest image. The same approach can be used to debug in images based on other supported GNU/Linux distributions.