Debug GPU-side errors in Metal

Highlight

Xcode 12 为 Metal 增加 Enhanced Command Buffer Errors 和 Shader Validation，开发者可以把 GPU 端错误定位到 encoder、draw call、Metal 函数，部分场景还能定位到 shader 行号。

核心内容

Metal 的麻烦在于，很多 bug 发生在 GPU 上。CPU 侧 API 用错时，Metal API Validation 会给出函数入口、错误类型、调用栈和源码位置。GPU 侧的 shader 错误经常只表现为命令缓冲区失败、画面损坏、阴影缺失，或者偶发的数据污染。

这类错误包括全局内存或 threadgroup memory 越界、访问 nil texture、argument buffer 资源驻留无效、长时间运行或无限循环。过去看到的常常是一句笼统的 command buffer error。一个命令缓冲区里可能有上百个 encoder，开发者只能人工缩小范围。

Xcode 12 给 Metal 调试流程补了两层信息。第一层是 Enhanced Command Buffer Errors，它把 command buffer 的错误拆到 encoder 级别，告诉你哪些 encoder completed、pending、affected、faulted 或 unknown。第二层是 Shader Validation，它在 GPU 上插桩 Metal shader，检测未定义行为，并把错误定位到 draw call、Metal function、GPU backtrace，条件满足时还会给出文件和行号。

这两层工具对应一条清晰的排查路径：先检测错误，再定位范围，再分类，最后修复代码。Enhanced Command Buffer Errors 适合常开在开发和 QA 中，低开销场景还可以带到线上收集遥测。Shader Validation 开销更高，适合 Xcode 调试、自动化测试和发布前验证。

详细内容

让 command buffer 报告 encoder 级状态

（03:40）Enhanced Command Buffer Errors 通过新的 descriptor API 开启。关键开关是 errorOptions = .encoderExecutionStatus。

let desc = MTLCommandBufferDescriptor()
desc.errorOptions = .encoderExecutionStatus
let commandBuffer = commandQueue.makeCommandBuffer(descriptor: desc)

关键点：

MTLCommandBufferDescriptor() 创建命令缓冲区描述对象。
desc.errorOptions = .encoderExecutionStatus 要求 Metal 在错误发生时记录 encoder execution status。
makeCommandBuffer(descriptor:) 用这个描述对象创建 command buffer，后续错误才会带上 encoder 信息。

（03:55）错误发生后，encoder 信息放在 NSError.userInfo 的 MTLCommandBufferEncoderInfoErrorKey 里。每个 MTLCommandBufferEncoderInfo 都带有 label、debug signposts 和 error state。

if let error = commandBuffer.error as NSError? {

    if let encoderInfos =
        error.userInfo[MTLCommandBufferEncoderInfoErrorKey]
        as? [MTLCommandBufferEncoderInfo] {

        for info in encoderInfos {
            print(info.label + info.debugSignposts.joined())
            if info.errorState == .faulted {
                print(info.label + " faulted!")
            }
        }
    }
}

关键点：

commandBuffer.error as NSError? 取出命令缓冲区完成后的错误对象。
MTLCommandBufferEncoderInfoErrorKey 对应一组 encoder info，用 recorded order 排列。
info.label 和 info.debugSignposts 依赖开发者平时给 encoder 添加的调试标识。
info.errorState == .faulted 表示这个 encoder 直接造成 command buffer fault。
affected 代表可能受故障影响，但 Metal 不能确认它就是源头。

这个机制先解决“从哪里开始看”的问题。视频中明确建议开发和 QA 阶段对每个 command buffer 开启它。由于它直接集成在 Metal 中，开销较低，也可以在评估性能后带到用户设备上，用遥测逐步缩小问题范围。

用 Shader Validation 找到 shader 中的未定义行为

（07:08）Shader Validation 是运行在 GPU 上的验证层。它会插桩 Metal shader，检测会造成未定义行为的操作。检测到问题时，工具会阻止该操作，并生成日志，帮助定位 draw call、Metal function，部分场景还能定位到具体 shader 行。

它能检测的范围包括：

device memory 和 constant memory 越界访问。
threadgroup memory 越界访问。
对 null texture object 调用 texturing functions。

视频中的例子很典型。一个 out-of-bounds read 有时会落到未分配虚拟内存，触发 command buffer fault；有时会落到相邻 buffer，读取错误数据或破坏另一个 buffer。后一种情况可能没有 command buffer error，只表现为间歇性的渲染错误。Shader Validation 的价值就在这里：没有 fault 时，也能发现部分未定义行为。

（09:47）在 Xcode 中使用时，打开 scheme settings 的 Diagnostics，勾选 Metal 区域里的 Shader Validation。Xcode 会同时为所有 command buffer 开启 Enhanced Command Buffer Errors。接着添加 Metal diagnostics breakpoint，程序命中 shader validation error 时会停下，并显示 GPU 和 CPU backtrace。

演示里，Ray Tracing 示例出现了缺失阴影和画面线条。启用 Shader Validation 后，Xcode 在 Metal shader 中标注出 out-of-bounds memory read。开发者沿着 GPU backtrace 回到调用点，发现二维坐标转一维数组索引时把 gridX 乘以宽度，修正为 gridY * width + gridX 后渲染恢复。

在 Xcode 外启用验证并读取日志

（15:05）自动化测试或非 Xcode 运行环境也能启用验证层。MTL_DEBUG_LAYER 设为非零值会打开 API Validation，MTL_SHADER_VALIDATION 设为非零值会打开 Shader Validation。两个变量可以同时设置，也可以分别使用，但必须早于 Metal device 创建；device 创建后，这些值会被锁定，本进程后续修改不会生效。

（15:39）command buffer 现在有 logs 属性。它只在 command buffer 完成后有效，所以读取逻辑要放进 completion handler。

commandBuffer.addCompletedHandler { (commandBuffer) in
    for log in commandBuffer.logs {
        let encoderLabel = log.encoderLabel ?? "Unknown Label"
        print("Faulting encoder \"\(encoderLabel)\"")
        guard let debugLocation = log.debugLocation,
              let functionName = debugLocation.functionName
        else {
            return
        }
        print("Faulting function \(functionName):\(debugLocation.line):\(debugLocation.column)")
    }
}

关键点：

addCompletedHandler 确保代码在 command buffer 完成后运行。
commandBuffer.logs 可能包含多个 Shader Validation errors。
log.encoderLabel 把错误关联回 encoder。
log.debugLocation 在 library 从源码编译或带有 debug symbols 时提供源码位置。
functionName、line、column 让自动化测试日志直接指向 shader 函数和位置。

（15:40）同一类信息也会进入系统日志，可以用 log stream 过滤 Metal GPU debug 日志。

log stream --predicate "subsystem = 'com.apple.Metal' and category = 'GPUDebug'"

关键点：

subsystem = 'com.apple.Metal' 只看 Metal 子系统。
category = 'GPUDebug' 过滤 GPU debug 相关日志。
日志会包含进程名、错误类型、错误细节，以及 Metal 文件名和行号等信息。

开启 Shader Validation 前要知道的成本

（17:17）Shader Validation 会增加 pipeline 编译时间。视频建议使用异步编译方法，把编译分散到多个线程，降低开发期间的等待。

（17:34）Metal library 要带 debug symbols。Xcode debug scheme 会自动处理；手动调用 Metal frontend 时，需要加 -g。运行时从源码编译 library 时，建议使用 #line directive，给 backtracer 一个可识别的文件名。

（18:26）Shader Validation 是进程级开关。开启后，进程内所有 Metal commands，包括 UI rendering，都会经过验证层。它会带来较高的性能和内存开销，视频建议用于开发和 QA，不建议面向用户开启。

（18:57）开启后，某些查询结果可能改变。计算 pipeline 的 maxTotalThreadsPerThreadgroup 和 threadExecutionWidth 都需要重新读取。部分 instrumentation 可以通过环境变量关闭，例如已经自行检查 null texture 时，可设置 MTL_SHADER_VALIDATION_TEXTURE_USAGE = 0 关闭 texture usage instrumentation，但会放弃对应检测能力。

核心启发

做一个 Metal 错误遥测通道：在 QA 构建里用 MTLCommandBufferDescriptor 开启 encoder execution status，把 faulted encoder 的 label、signposts 和设备信息一起上传。这样可以把“偶现 GPU crash”变成可聚合的问题列表。
把 Shader Validation 接入渲染回归测试：在 CI 的图形测试任务里设置 MTL_DEBUG_LAYER=1 和 MTL_SHADER_VALIDATION=1，运行关键渲染路径后读取 commandBuffer.logs。测试失败信息直接输出 faulting encoder、function、line 和 column。
为每个 render pass 建立命名规范：给 command encoder 设置稳定 label，并在复杂 pass 中插入 debug signposts。Enhanced Command Buffer Errors 和 Xcode Metal Debugger 都会复用这些标识，故障报告能直接指向业务模块。
给 shader 编译管线保留调试符号模式：调试和 QA 构建统一启用 Metal debug symbols。运行时编译的 shader 源码加 #line directive，让 Shader Validation 的 backtrace 能指向真实文件或生成器输出位置。
做一个发布前 GPU 未定义行为检查清单：覆盖越界 device memory、threadgroup memory、null texture、argument buffer 资源驻留和 timeout。Enhanced Command Buffer Errors 负责 encoder 级定位，Shader Validation 负责能被插桩发现的未定义行为。

关联 Session

Gain insights into your Metal app with Xcode 12 — 继续学习 Xcode 12 的 Metal Debugger、capture 和诊断工具。
Optimize Metal apps and games with GPU counters — GPU 错误修完后，用 counters 找到性能瓶颈。
Build GPU binaries with Metal — 配合 shader 调试符号和编译管线，改善 Metal pipeline 加载与诊断。
Get to know Metal function pointers — 理解更复杂的 Metal shader 调用结构，方便在调试时阅读 GPU backtrace。

Highlight

核心内容

详细内容

让 command buffer 报告 encoder 级状态

用 Shader Validation 找到 shader 中的未定义行为

在 Xcode 外启用验证并读取日志

开启 Shader Validation 前要知道的成本

核心启发

关联 Session

评论