GPU Debugging

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 supported for all GPUs through out-of-tree kernel drivers. However, these drivers are primarily designed for data center GPUs, and using them with client GPUs can lead to display issues. To resolve this, we offer Personal Package Archive (PPA) packages specifically for client GPUs on Ubuntu Desktop 25.04, which enable GPU debugging without impacting the display.

To configure your system and enable GPU debugging, choose one of the following procedures. If you are using a client GPU on Ubuntu Desktop 25.04, follow the second procedure; otherwise, use the first.

Configuring the system to support GPU debugging tools

All GPUs and operating systems

Follow these steps if you are using a data center GPU on any supported operating system or a client GPU on Ubuntu Desktop 22.04 or 24.04. Please note that enabling this feature on a client GPU may cause display issues.

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"

Client GPUs on Ubuntu Desktop 25.04

Follow these steps if you are using a client GPU on Ubuntu Desktop 25.04.

Install the kernel from the PPA package and reboot to apply the changes.
```
apt-get install -y linux-intel
```

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

for card in /sys/class/drm/card*; do
  if [[ -e "${card}/device/prelim_enable_eudebug" ]]; 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}/device/prelim_enable_eudebug)
    echo "${card} (${vendor}:${device}) supports" \
      "prelim_enable_eudebug. Current value: ${value}"
  fi
done

Example output:

/sys/class/drm/card0 (8086:5690) supports prelim_enable_eudebug. 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}/device/prelim_enable_eudebug
```
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}/device/prelim_enable_eudebug

Set the following environment variables.

export ZET_ENABLE_PROGRAM_DEBUGGING=1
export IGC_VISAOptions="-enableBarrierWA"

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