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

# 调试图形问题

你可以使用 Snapdragon Profiler 和内核命令对应用程序进行性能分析。本节介绍如何使用内核命令收集用于性能分析和调试的信息，以及如何收集日志。

**注意（Caution）**

请谨慎使用这些命令，因为它们可能会影响设备的功耗。

## **捕获 Weston/Wayland 日志**

你可以使用 Wayland/Weston 日志来验证显示驱动是否已在设备上加载，并查找支持的 OpenGL ES 扩展。要捕获 Weston/Wayland 调试日志，请在启动 Weston 或任何其他应用程序之前运行以下命令：

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

## **调试 Kernel/KGSL**

你可以通过将 GPU 调整到不同的频率级别，并将 GPU 或 CPU 设置为性能模式来评估应用程序的性能。基于这些评估，你可以优化应用程序的性能。

### **将 CPU 设置为性能模式**

1. 使用以下命令重新挂载文件系统：
   ```text theme={null}
   mount -o remount,rw /
   ```
2. 要设置所有 CPU 核心，请将 `cpux` 替换为 `cpu0`、`cpu1` 和 `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
   ```
   **示例输出**
   ondemand userspace performance schedutil
3. 如果任何 CPU 时钟以低频率运行，请将 CPU 设置为性能模式，并通过运行以下命令验证问题：
   ```text theme={null}
   echo performance > /sys/devices/system/cpu/[cpux]/cpufreq/scaling_governor
   ```
4. 要验证试验设置，请运行以下命令：
   ```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 …)
   ```

### **设置 GPU 频率**

**注意**

以下命令仅适用于 Adreno/KGSL overlay 或 qcom‑multimedia‑proprietary‑image。

1. 使用以下命令重新挂载文件系统：
   ```text theme={null}
   mount -o remount,rw /
   ```
2. 对于功率级别，请检查 `available_frequencies` sys 节点。
   ```text theme={null}
   cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies
   ```
   **示例输出**
   812000000 700000000 608000000 550000000 450000000 315000000
   从示例输出中，你可以将 GPU 功率级别解读为：
   | **频率**   | 812000000 | 700000000 | 608000000 | 550000000 | 450000000 | 315000000 |
   | :------- | :-------- | :-------- | :-------- | :-------- | :-------- | :-------- |
   | **功率级别** | 0         | 1         | 2         | 3         | 4         | 5         |
3. 将 GPU 功率级别逐级递增，并在以下命令中将 `<level>` 分别替换为 0、1、2、3、4 和 5 来执行 GPU 功率级别测试：
   ```text theme={null}
   echo <level> > /sys/class/kgsl/kgsl-3d0/min_pwrlevel
   ```
   ```text theme={null}
   echo <level> > /sys/class/kgsl/kgsl-3d0/max_pwrlevel
   ```

**注意**

对于 QCS5430：

* Adreno GPU 频率固定为 315 MHz。
* 此处指定的功率级别不受支持，`available_frequencies` 命令的输出显示为 315000000。

### **将 GPU 设置为性能模式**

* 要将 GPU 设置为性能模式，请运行以下命令：
  ```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
  ```
  **注意**
  这些命令会强制 GPU 始终以最高频率运行。
* 要确保即使设备空闲 10000000 毫秒 GPU 也不会进入低功耗状态，请运行以下命令：
  ```text theme={null}
  mount -o remount,rw /
  echo 10000000 > /sys/class/kgsl/kgsl-3d0/idle_timer
  ```
* 要将 GPU 设置为性能模式，同时确保 GPU 不会进入低功耗状态，请运行以下命令：
  ```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
  ```

**注意**

QCS5430 不支持性能模式，因为 Adreno GPU 频率固定为 315 MHz。

### **检查其他 KGSL 设置**

* 要启用 KGSL 时钟，请运行以下命令：
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_clk_on
  ```
* 要启用 KGSL 电源轨（rail），请运行以下命令：
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_rail_on
  ```
* 要启用 KGSL 总线，请运行以下命令：
  ```text theme={null}
  echo 1 > /sys/class/kgsl/kgsl-3d0/force_bus_on
  ```

## **调试基于 OpenGL ES 的应用程序**

你可以使用 Snapdragon Profiler 工具捕获 OpenGL ES 应用程序的快照和实时跟踪。有关更多信息，请参阅 [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool)。

## **调试基于 OpenCL 的应用程序**

你可以使用 Snapdragon Profiler 工具捕获 OpenCL 应用程序的快照和实时跟踪。

* 有关更多信息，请参阅 [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool)。
* 有关性能分析，请参阅 [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) 中的 **Performance profiling**。

**注意**

[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) 中的部分章节适用于 Android 平台，而不适用于 Qualcomm Linux 设备。但是，某些性能分析选项完全基于 OpenCL API，因此在 Qualcomm Linux 设备上受支持。例如，`clGetEventProfilingInfo` API。

## **调试基于 Vulkan 的应用程序**

使用 Snapdragon Profiler 工具捕获 Vulkan 应用程序的快照和实时跟踪。有关更多信息，请参阅 [Snapdragon Profiler](https://dragonwingdocs.qualcomm.com/Technologies/Graphics/snapdragon-profiler-tool)。此外，你还可以使用验证层（validation layers）来调试 Vulkan 应用程序。

### **使用验证层调试 Vulkan 应用程序**

要使用验证层调试 Vulkan 应用程序，请在 Linux 主机上执行以下操作：

1. 要设置源环境，请运行以下命令：
   ```text theme={null}
   source <path-to-installed-platform-eSDK>/environment-setup-armv8-2a-qcom-linux
   ```
2. 要下载验证层，请运行以下命令：
   ```text theme={null}
   git clone https://github.com/KhronosGroup/Vulkan-ValidationLayers
   ```
3. 要构建验证层，请运行以下命令：
   ```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
   ```
   **注意**
   如果 `/tmp/local/debug/vulkan` 目录不存在，请创建一个类似的目录。
4. 要在 Vulkan 应用程序上启用验证层，请按如下方式设置 `VK_INSTANCE_LAYERS` 环境变量：
   ```text theme={null}
   export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation
   ```
5. 要编辑或追加 `layers/vk_layer_settings.txt` 文件中的设置，请运行以下命令：
   ```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. 要将 `layers/vk_layer_settings.txt` 文件推送到设备，请运行以下命令：
   ```text theme={null}
   scp -r vk_layer_settings.txt root@[IP-address-of-the-device]:/tmp/local/debug/vulkan/
   ```
7. 要转储日志，请运行以下命令添加验证层的路径：
   ```text theme={null}
   export VK_LAYER_SETTINGS_PATH=/tmp/local/debug/vulkan/vk_layer_settings.txt
   ```
   此命令会在 Vulkan 应用程序二进制文件所在的同一目录中生成转储文件。

**注意**

如果你在编译或运行应用程序时遇到问题，请使用以下命令检出特定版本。然后，重复步骤 3 到 7，重新编译应用程序并运行。

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

为避免 `tmp` 目录中的数据被清空，请将 Vulkan 应用程序二进制文件保存到其他位置。如果更改了二进制文件的位置，请确保更新环境变量，并在重启后验证更改。