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.

To configure your system and enable GPU debugging, choose one of the following procedures. The first procedure applies to Ubuntu Desktop 22.04 and 24.04. The second procedure is for Ubuntu Desktop 25.10 only. Since Intel® Data Center GPU Max Series and Intel® Data Center GPU Flex Series are not supported on Ubuntu Desktop 25.10, the first procedure is recommended for these GPUs.

Configuring the system to support GPU debugging tools

Ubuntu Desktop 22.04 and 24.04

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"

Ubuntu Desktop 25.10

Follow these steps if you are using Ubuntu Desktop 25.10.

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"

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.