MUSA Compute Sanitizer 最佳实践
本文档提供场景化的快速参考，帮助你快速找到常见问题的解决方案。
快速命令参考
基本使用：
# 默认检查（越界 + API 错误）
mt-compute-sanitizer ./my_program
# 启用所有检查（包括泄漏检查）
mt-compute-sanitizer --leak-check=full ./my_program
# 禁用 API 错误检查
mt-compute-sanitizer --report-api-errors=no ./my_program
常用选项：
| 选项 | 描述 | 默认值 |
|---|---|---|
--leak-check=full | 启用内存泄漏检查 | no |
--report-api-errors=no | 禁用 API 错误报告 | all |
场景一：首次使用 - 检查程序错误
用户问题
"我刚写完一个 MUSA 程序，运行时报错了，但我不知道具体哪里有问题，该怎么排查？"
解决步骤
最简单的使用方式：直接运行程序
mt-compute-sanitizer ./my_program
Sanitizer 会自动检测以下错误：
- 内存越界访问
- 内存泄漏
- API 调用错误
预期输出
========= COMPUTE-SANITIZER
==PROF== 'my_program' started, pid:123456
==PROF== 'my_program' exit, exit code(0)
========= ERROR SUMMARY: 0 errors
如果有错误：
========= Device memory out of bounds. Address: 0x...
========= ERROR SUMMARY: 1 error
下一步
- 无错误 → 继续 场景五 启用更多检查
- 有错误 → 根据错误类型查看对应场景
场景二：检查内存越界访问
用户问题
"我的程序有时候能跑、有时候不能跑，怀疑是数组访问越界了，怎么确定？"
快速解决
# 越界检查默认启用
mt-compute-sanitizer ./my_program
典型输出
========= Device memory out of bounds. Address: 0x...
========= ERROR SUMMARY: 1 error
常见原因速查
| 原因 | 快速修复 |
|---|---|
| 无边界检查 | 添加 if (idx < n) |
| blockSize 过大 | 确保 blockSize * gridSize <= n |
| 指针计算错误 | 检查指针算术 |
完整错误示例和修复代码，可参考 用户指南 - 越界检查。
场景三：检查内存泄漏
用户问题
"我的程序运行一段时间后显存越来越少，怀疑有显存泄漏，怎么检测？"
快速解决
# 必须显式启用泄漏检查
mt-compute-sanitizer --leak-check=full ./my_program
典型输出
========= Leaked 4096 bytes at 0x1006da04000
========= ERROR SUMMARY: 3 errors
常见原因速查
| 原因 | 快速修复 |
|---|---|
| 缺少 musaFree() | 为每个 musaMalloc() 添加对应 musaFree() |
| 提前 return | 确保所有返回路径都释放内存 |
| 异常处理 | 使用 RAII 或 try-catch 确保释放 |
完整错误示例和修复代码，可参考 用户指南 - 泄漏检查。
场景四：检查 API 错误
用户问题
"我的程序有时候返回错误码，但不知道具体是什么错误，怎么办？"
快速解决
# API 错误检查默认已启用
mt-compute-sanitizer ./my_program
常见 API 错误速查
| 错误 | 含义 | 常见原因 |
|---|---|---|
| invalid argument | 无效参数 | Size = 0, NULL 指针 |
| out of memory | GPU 内存耗尽 | 分配过多 |
| invalid device | 无效 GPU 设备 | 设备未初始化 |
完整 API 错误示例，可参考 用户指南 - API 错误检查。
场景五：组合使用多种检查
用户问题
"我想同时检查内存越界和内存泄漏，该怎么操作？"
快速解决
# 启用所有检查
mt-compute-sanitizer --leak-check=full ./my_program
检查组合对比
| 命令 | 越界 | 泄漏 | API 错误 |
|---|---|---|---|
mt-compute-sanitizer ./app | ✅ | ❌ | ✅ |
mt-compute-sanitizer --leak-check=full ./app | ✅ | ✅ | ✅ |
场景六：解释错误信息
用户问题
"Sanitizer 输出了很多信息，但我看不懂，该怎么办？"
快速参考
错误摘要：
========= ERROR SUMMARY: X errors
0 errors- 未检测到错误>0 errors- 发现错误，查看上方详细信息
完整的错误信息解读，可参考 用户指南 - 常见错误模式。
常见问题速查表
| 问题 | 快速答案 |
|---|---|
| 内存泄漏检测不到 | 使用 --leak-check=full 显式启用 |
| 只想检查某个 kernel | 目前需要通过代码插桩实现 |
| 不需要 API 错误报告 | 使用 --report-api-errors=no 关闭 |
如需查看详细说明和完整示例，可参考 用户指南。
