Configuring GPU Debugging Tools

Intel GPU debugging functionality provides tools and features for analyzing performance, identifying issues, and optimizing graphics and compute workloads. Using the tools requires a proper system configuration, which is explained in this document.

Supported GPUs and drivers

GPU debugging is available when the system is configured with a driver and kernel that support it. Intel Graphics PPA packages include a configuration that enables GPU debugging. In containerized environments or when using Intel® Open Middleware Xe (Intel® OMIX), this capability may be limited.

Configuring the system to support GPU debugging tools

Follow these steps if you are using Ubuntu Desktop 22.04 or 24.04. Note that enabling this feature may cause display issues on GPUs other than Intel® Data Center GPU Max Series and Intel® Data Center GPU Flex Series.

Enumerate the current set of cards and check whether prelim_enable_eu_debug is enabled on that card.

for card in /sys/class/drm/card*; do
  if [[ -e "${card}/prelim_enable_eu_debug" ]]; then
    link="$(readlink "${card}")"
    link="${link#.*devices/}"
    link="${link%/drm*}"
    vendor=$(cat ${card}/device/vendor)
    vendor=${vendor/0x} # Prune 0x
    device=$(cat ${card}/device/device)
    device=${device/0x} # Prune 0x
    value=$(cat ${card}/prelim_enable_eu_debug)
    echo "${card} (${vendor}:${device}) supports" \
      "prelim_enable_eu_debug. Current value: ${value}"
  fi
done

Example output:

/sys/class/drm/card0 (8086:5690) supports prelim_enable_eu_debug. Current value: 0

If the command does not return anything, it means that GPU debugging is not available.

Enable GPU debugging when the card is in the idle mode.
```
echo 1 | sudo tee /sys/class/drm/${card}/prelim_enable_eu_debug
```
Replace ${card} with the corresponding card name, such as card0, from the output of the previous command, which appears after /sys/class/drm/.

Disable GPU debugging when the card is in the idle mode.

echo 0 | sudo tee /sys/class/drm/${card}/prelim_enable_eu_debug

Set the following environment variables.

export ZET_ENABLE_PROGRAM_DEBUGGING=1
export IGC_VISAOptions="-enableBarrierWA"

Display considerations

During GPU debugging, the GPU is halted and the video output is unavailable from that GPU. In this case, you can connect to the system remotely via Secure Shell (SSH) or prevent your display from using the GPU you want to use for debugging. On a system with both integrated and discrete GPUs, one way to achieve this is to use a virtual machine. You can find instructions for that method in the Configuring the Isolated Desktop Solution guide.

Intel’s GNU Debugger (GDB) distribution

Intel provides a version of GDB that is enabled with GPU debugging on Intel GPUs. For instructions on installing the Intel® Distribution for GDB*, and for examples of how to use it, see Distribution for GDB: Get Started Guide.