调试指南¶

问题报告¶

在报告问题或发现缺陷时，我们通常需要回溯（backtrace）、调试日志，或两者都需要，以便定位问题。

图形调试¶

如果你的缺陷与图形问题有关——例如颜色不匹配、顶点爆炸、闪烁等——那么你必须在问题报告中包含图形调试日志。

图形调试位于桌面端的 General -> Debug，以及 Android 端的 Advanced Settings -> Debug。Android 用户无需额外操作；不过桌面端用户可能需要安装 Vulkan 验证层：

• Windows：安装 Vulkan SDK
• Linux、BSD 等：从包管理器安装 vulkan-validation-layers、vulkan-layers 或类似包。它通常位于例如 /usr/lib64/libVkLayer_khronos_validation.so

启用图形调试后，重新运行有问题的游戏并继续操作。请注意，在较弱的硬件上游戏可能会运行得极其缓慢。

调试日志¶

调试日志可在桌面端的 General -> Debug -> Open Log Location 中找到，在 Android 端则是 Share Debug Logs。所有缺陷报告都必须包含这些日志，某些 UI 缺陷除外——但即使是 UI 缺陷，我们也强烈建议附上日志。

调试（宿主机代码）¶

在宿主机上调试时忽略 SIGSEGV：

• gdb：handle SIGSEGV nostop pass
• lldb：pro hand -p true -s false -n false SIGSEGV

调试（客户机代码）¶

gdb¶

你必须为 aarch64 安装 GDB 才能调试目标。通过你的包管理器安装，例如：

• 在 Arch 上：
• sudo pacman -Syu aarch64-linux-gnu-gdb
• 在 Gentoo 上：
• sudo emerge --ask crossdev
• sudo crossdev -t aarch64-unknown-linux-gnu --ex-gdb

运行 ./build/bin/eden-cli -c <path to your config file (see logs where you run Eden normally to see where it is)> -d -g <path to game>，或在 General > Debug 处启用 Enable GDB Stub，然后连接一个 aarch64-gdb：

• target remote localhost:6543

输入 c（表示继续），然后如果它崩溃了，只需执行 bt（回溯）和 layout asm。

gdb 速查表¶

• mo <cmd>：监视器命令，可用 get info、get fastmem 和 get mappings。输入 mo help 获取更多信息。
• detach：从远程分离（即重启模拟器）。
• c：继续
• p <expr>：打印变量，使用 p/x <expr> 以十六进制打印。
• r：运行
• bt：打印回溯
• info threads：打印所有活动线程
• thread <number>：切换到指定线程（参见 info threads）
• layout asm：以汇编模式显示（TUI）
• si：单步执行汇编指令
• s 或 step：单步执行一行代码（非汇编）
• display <expr>：每步显示变量。
• n：下一步（跳过函数调用帧）
• frame <number>：切换到指定帧（来自 bt）
• br <expr>：在 <expr> 处设置断点。
• delete：删除所有断点。
• catch throw：在抛出异常处设置断点。也可以使用 br __cxa_throw
• br _mesa_error：在 mesa 错误处中断（事先设置环境变量 MESA_DEBUG=1），参见 MESA_DEBUG。

表达式可以是 variable_names 或 1234（数字），或 *var（指针解引用），或 *(1 + var)（计算后的表达式）。

更多信息请输入 info gdb 并阅读手册页。

RenderDoc¶

RenderDoc 是一款免费、跨平台、多图形 API 调试器。它是诊断图形应用程序问题的宝贵工具，并支持 Vulkan。从 renderdoc.org 获取。

当 RenderDoc 的 Vulkan 层在 Eden 创建 Vulkan 设备之前被加载时，RenderDoc 可以捕获 Eden 的 Vulkan 输出。在使用 RenderDoc 诊断问题之前，最好确保没有验证错误。任何错误都意味着应用程序的行为是未定义的。话虽如此，如果你确实遇到验证错误，RenderDoc 也可以帮助调试这些错误。

在 Windows 上使用¶

你可以使用 RenderDoc UI 启动 Eden，也可以让 Eden 在内部附加 RenderDoc：

在 Windows PowerShell 中：

$env:ENABLE_VULKAN_RENDERDOC_CAPTURE='1'
.\eden.exe

当 RenderDoc 附加后，Eden 会记录默认的 Windows 捕获文件夹：

%LOCALAPPDATA%\Temp\RenderDoc

按 RenderDoc 的捕获热键（通常是 F12）来捕获一帧。若要停止使用 RenderDoc，请关闭 Eden 并重新启动，不要设置 ENABLE_VULKAN_RENDERDOC_CAPTURE。

Eden 热键¶

Eden 还有一个独立的 Toggle Renderdoc Capture 热键，由调试设置 renderdoc_hotkey 控制。 该热键不会加载或卸载 RenderDoc。它只是通过 RenderDoc 的 API 切换 Eden 自身的手动捕获：

• 第一次按下：开始捕获
• 第二次按下：结束本次捕获

使用 RenderDoc 调试黑屏的简单检查清单¶

在调试黑屏时，应用程序可能在很多地方错误地设置了 Vulkan。 以下是一份简短的检查清单，请逐一确认这些项目是否正确：

• 绘制调用计数正确（即不为零；如果渲染许多三角形，则不是 3）
• 顶点缓冲区已绑定
• 顶点属性正确——确保每个属性的大小和偏移与应有值匹配
• 任何已绑定的推送常量和描述符都具有正确的数据——包括：
• 矩阵值正确——仔细检查模型、视图和投影矩阵是否上传正确
• 管线状态正确
• 视口范围正确——x,y 为 0,0；width 和 height 为屏幕尺寸；minDepth 为 0，maxDepth 为 1，NDCDepthRange 为 0,1
• 填充模式符合预期——通常为 solid（实心）
• 剔除模式合理——通常为 back（背面）或 none（无）
• 绕序方向正确——通常为 CCW（逆时针）
• 裁剪区域正确——通常与 viewport 的 x,y、width 和 height 相同
• 混合状态正确
• 深度状态正确——通常启用，Function 设置为 Less than or Equal
• 渲染到交换链时，交换链图像已绑定
• 渲染到的图像与呈现到交换链时所用的图像相同

另外，存在一个 RenderDoc 扩展（存档），它可以自动完成许多手动步骤。