# 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](./kernel-driver-types.md#out-of-tree-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

::::{tab-set}
:sync-group: debugging

:::{tab-item} All GPUs and operating systems
:sync: general

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.

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

   ```bash
   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.

3. Enable GPU debugging when the card is in the idle mode.

   ```bash
   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/`.

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

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

5. Set the following environment variables.

   ```bash
   export ZET_ENABLE_PROGRAM_DEBUGGING=1
   export IGC_VISAOptions="-enableBarrierWA"
   ```
   
:::

:::{tab-item} Client GPUs on Ubuntu Desktop 25.04
:sync: client-gpu-25-04

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

1. Install the kernel from the PPA package and reboot to apply the changes.

   ```bash
   apt-get install -y linux-intel
   ```

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

   ```bash
   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.

3. Enable GPU debugging when the card is in the idle mode.

   ```bash
   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/`.

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

   ```bash
   echo 0 | sudo tee /sys/class/drm/${card}/device/prelim_enable_eudebug
   ```

5. Set the following environment variables.

   ```bash
   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](client/virtualized) 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](https://www.intel.com/content/www/us/en/docs/distribution-for-gdb/get-started-guide-linux/2023-0/overview.html).