> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug graphics issues

You can use the Snapdragon Profiler and kernel commands for performance profiling of the applications. This section describes how to collect information for profiling and debugging using the kernel commands, and how to collect logs.

**Caution**

Use these commands with caution because they may impact the power consumption of the device.

## **Capture Weston/Wayland logs**

You can use the Wayland/Weston logs to verify whether the display driver is loaded on the device and to find the supported OpenGL ES extensions. To capture the Weston/Wayland debug logs, run the following command before launching the Weston or any other application:

```text theme={null}
export WAYLAND_DEBUG=server/client
```

## **Debug Kernel/KGSL**

You can evaluate the performance of your application by adjusting the GPU to different frequency levels and setting the GPU or CPU to performance mode. Based on these evaluations, you can optimize the performance of your application.

### **Set CPU to performance mode**

1. Remount the file system using the following command:
   ```text theme={null}
   mount -o remount,rw /
   ```
2. To set all CPU cores, replace `cpux` with `cpu0`, `cpu1`, and `cpun`.
   ```text theme={null}
   echo 1 > /sys/devices/system/cpu/[cpux]/online
   ```
   ```text theme={null}
   cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_governors
   ```
   **Sample output**
   ondemand userspace performance schedutil
3. If any CPU clock is running at a low frequency, set the CPU to performance mode and verify the issue by running the following command:
   ```text theme={null}
   echo performance > /sys/devices/system/cpu/[cpux]/cpufreq/scaling_governor
   ```
4. To validate the trial settings, run the following commands:
   ```text theme={null}
   cat /sys/devices/system/cpu/[cpux]/online (cpux : cpu0,cpu1 …)
   ```
   ```text theme={null}
   cat /sys/devices/system/cpu/[cpux]/cpufreq/scaling_governor(cpux : cpu0, cpu1 …)
   ```

### **Set GPU frequency**

**Note**

The following commands work only with the Adreno/KGSL overlay or the qcom‑multimedia‑proprietary‑image.

1. Remount the file system using the following command:
   ```text theme={null}
   mount -o remount,rw /
   ```
2. For the power level, check the `available_frequencies` sys node.
   ```text theme={null}
   cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies
   ```
   **Sample output**
   812000000 700000000 608000000 550000000 450000000 315000000
   From the sample output, you can interpret GPU power levels as:
   | **Frequency**   | 812000000 | 700000000 | 608000000 | 550000000 | 450000000 | 315000000 |
   | :-------------- | :-------- | :-------- | :-------- | :-------- | :-------- | :-------- |
   | **Power level** | 0         | 1         | 2         | 3         | 4         | 5         |
3. Increment the GPU power level by one and perform the GPU power-level test by substituting `<level>` with 0, 1, 2, 3, 4, and 5 in the following commands:
   ```text theme={null}
   echo <level> > /sys/class/kgsl/kgsl-3d0/min_pwrlevel
   ```
   ```text theme={null}
   echo <level> > /sys/class/kgsl/kgsl-3d0/max_pwrlevel
   ```

**Note**

For QCS5430:

* The Adreno GPU frequency is fixed at 315 MHz.
* The power levels specified here aren’t supported and the output of the `available_frequencies` command displays 315000000.

### **Set GPU to performance mode**

* To set the GPU to performance mode, run the following command:
  ```text theme={null}
  mount -o remount,rw /
  echo 0 > /sys/class/kgsl/kgsl-3d0/min_pwrlevel
  echo 0 > /sys/class/kgsl/kgsl-3d0/max_pwrlevel
  ```
  **Note**
  These commands force the GPU to always run at the maximum frequency.
* To ensure that the GPU doesn’t enter the low-power state even if the device is idle for 10000000 ms, run the following command:
  ```text theme={null}
  mount -o remount,rw /
  echo 10000000 > /sys/class/kgsl/kgsl-3d0/idle_timer
  ```
* To set the GPU to performance mode while ensuring that the GPU doesn’t enter the low-power state, run the following command:
  ```text theme={null}
  mount -o remount,rw /
  echo 0 > /sys/class/kgsl/kgsl-3d0/min_pwrlevel
  echo 0 > /sys/class/kgsl/kgsl-3d0/max_pwrlevel
  echo 10000000 > /sys/class/kgsl/kgsl-3d0/idle_timer
  ```

**Note**

QCS5430 doesn’t support performance mode because the Adreno GPU frequency is fixed at 315 MHz.

### **Check other KGSL settings**

* To enable the KGSL clock, run the following command:
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_clk_on
  ```
* To enable the KGSL rail, run the following command:
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_rail_on
  ```
* To enable the KGSL bus, run the following command:
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_bus_on
  ```

## **Debug OpenGL ES-based applications**

You can use the Snapdragon Profiler tool to capture snapshots and real-time traces of OpenGL ES applications. For more information, see [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool).

## **Debug OpenCL-based applications**

You can use the Snapdragon Profiler tool to capture snapshots and real-time traces of OpenCL applications.

* For more information, see [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool).
* For performance profiling, see **Performance profiling** in [Qualcomm® Snapdragon™ Mobile Platform OpenCL General Programming and Optimization Guide](https://docs.qualcomm.com/bundle/publicresource/80-NB295-11_REV_C_Qualcomm_Snapdragon_Mobile_Platform_Opencl_General_Programming_and_Optimization.pdf).

**Note**

Some sections in the [Qualcomm® Snapdragon™ Mobile Platform OpenCL General Programming and Optimization Guide](https://docs.qualcomm.com/bundle/publicresource/80-NB295-11_REV_C_Qualcomm_Snapdragon_Mobile_Platform_Opencl_General_Programming_and_Optimization.pdf) apply to Android platforms but not to Qualcomm Linux devices. However, some profiling options are purely based on the OpenCL API and are therefore supported on the Qualcomm Linux devices. For example, the `clGetEventProfilingInfo` API.

## **Debug Vulkan-based applications**

Use the Snapdragon Profiler tool to capture snapshots and real-time traces of Vulkan applications. For more information, see [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool). Also, you can use validation layers to debug Vulkan applications.

### **Debug Vulkan application using validation layers**

To debug a Vulkan application using validation layers, do the following on the Linux host computer:

1. To set the source environment, run the following command:
   ```text theme={null}
   source <path-to-installed-platform-eSDK>/environment-setup-armv8-2a-qcom-linux
   ```
2. To download the validation layers, run the following command:
   ```text theme={null}
   git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers
   ```
3. To build the validation layers, run the following commands:
   ```text theme={null}
   cd Vulkan-ValidationLayers
   cmake -S . -B build -D UPDATE_DEPS=ON -D BUILD_WSI_XLIB_SUPPORT=OFF -D BUILD_TESTS=OFF -D CMAKE_BUILD_TYPE=Release -D BUILD_WSI_XCB_SUPPORT=OFF -D BUILD_WSI_WAYLAND_SUPPORT=ON
   cmake --build build --config Debug
   ```
   ```text theme={null}
   scp -r build/layers/libVkLayer_khronos_validation.so root@[IP-address-of-the-device]:/tmp/local/debug/vulkan/
   ```
   ```text theme={null}
   scp -r build/layers/VkLayer_khronos_validation.json root@[IP-address-of-the-device]:/tmp/local/debug/vulkan/
   ```
   ```text theme={null}
   export VK_LAYER_PATH=/tmp/local/debug/vulkan:$VK_LAYER_PATH
   ```
   **Note**
   If the `/tmp/local/debug/vulkan` directory isn’t available, create a similar directory.
4. To enable the validation layers on Vulkan applications, set the `VK_INSTANCE_LAYERS` environment variable as follows:
   ```text theme={null}
   export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation
   ```
5. To edit or append the settings in the `layers/vk_layer_settings.txt` file, run the following command:
   ```text theme={null}
   khronos_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG
   khronos_validation.report_flags = error,warn,perf
   khronos_validation.file = true
   khronos_validation.log_filename = vk_validatedump.txt
   ```
6. To push the `layers/vk_layer_settings.txt` file to the device, run the following command:
   ```text theme={null}
   scp -r vk_layer_settings.txt root@[IP-address-of-the-device]:/tmp/local/debug/vulkan/
   ```
7. To dump the log, add path of the validation layers by running the following command:
   ```text theme={null}
   export VK_LAYER_SETTINGS_PATH=/tmp/local/debug/vulkan/vk_layer_settings.txt
   ```
   This command generates the dumps in the same directory where the Vulkan application binary exists.

**Note**

If you are facing issues compiling the application or running it, use the following commands to check out the specific version. Later, repeat the steps from 3 to 7 and recompile the application and run.

```text theme={null}
git checkout -b <local_branch_name> --track remotes/origin/vulkan-sdk-1.3.275

example: git checkout -b 13275 --track remotes/origin/vulkan-sdk-1.3.275
```

To avoid data flush in the `tmp` directory, save the Vulkan application binary to another location. If you change the location of the binary, ensure that you update the environment variables and verify the changes after rebooting.