本文档帮助你成功运行 rocrtst 的第一个测试，并掌握各种运行方式。
1. 运行前检查清单
在运行测试之前，确认以下条件：
# ✅ 1. rocrtst64 已构建并安装ls$ROCM_PREFIX/bin/rocrtst64# ✅ 2. GPU kernel 已编译（检查你的 GPU 型号目录）ls$ROCM_PREFIX/share/rocrtst/gfx942/# 替换为你的 GPU 型号# ✅ 3. HSA 运行时库可找到ls$ROCM_PREFIX/lib/libhsa-runtime64.so# ✅ 4. GPU 设备正常rocminfo|grep"Name:"|head-3# ✅ 5. 设置库路径exportLD_LIBRARY_PATH=$ROCM_PREFIX/lib:$LD_LIBRARY_PATH2. 运行第一个测试
2.1 从安装目录运行（推荐）
推荐从对应 GPU 的 ASIC 目录运行，这样 rocrtst 能自动找到.hsacokernel 文件：
cd$ROCM_PREFIX/share/rocrtst/gfx942# 替换为你的 GPU 型号# 运行一个简单的测试sudo$ROCM_PREFIX/bin/rocrtst64--gtest_filter="rocrtst.Test_Example"2.2 从 build 目录运行
构建后也可直接从 build 目录运行：
cdrocrtst/suites/test_common/build/gfx942# 替换为你的 GPU 型号sudo../rocrtst64--gtest_filter="rocrtst.Test_Example"2.3 预期输出
成功运行后，输出类似：
======================================================== ROC Runtime Test Suite Platform detected: Bare Metal Configuration: /opt/rocm-7.3.0/share/rocrtst/platform_config.yaml ======================================================== [==========] Running 1 test from 1 test suite. [----------] Global test environment set-up. [----------] 1 test from rocrtst [ RUN ] rocrtst.Test_Example ***** Test_Example ***** Setup: HSA Runtime Initialization ... Agent and Queue Info: Agent: gfx942 Queue Size: 131072 ... Kernel File: test_case_template_kernels.hsaco Running ... Closing ... [ OK ] rocrtst.Test_Example (XXX ms) [----------] 1 test from rocrtst (XXX ms total) [==========] 1 test from 1 test suite ran. (XXX ms total) [ PASSED ] 1 test.3. 测试套件与测试用例命名
rocrtst 中的测试按测试套件.测试用例格式命名：
| 测试套件 | 含义 | 示例 |
|---|---|---|
rocrtst | 通用/模板测试 | rocrtst.Test_Example |
rocrtstFunc | 功能测试 | rocrtstFunc.MemoryAccessTests |
rocrtstPerf | 性能测试 | rocrtstPerf.Memory_Async_Copy |
rocrtstNeg | 负面测试 | rocrtstNeg.Memory_Allocation_Negative_Tests |
rocrtstStress | 压力测试 | rocrtstStress.Memory_Concurrent_Allocate_Test |
4. 列出所有测试
sudo$ROCM_PREFIX/bin/rocrtst64--gtest_list_tests输出格式：
rocrtst. Test_Example Test_Example_InterruptDisabled Test_MetadataPrefetchPacket rocrtstFunc. MemoryAccessTests MemoryAccessCoherent GroupMemoryAllocationTest MemoryAllocateAndFreeTest SvmMemoryBasic VirtualMemoryManagement ... rocrtstPerf. Memory_Async_Copy AQL_Dispatch_Time_Single_SpinWait ... rocrtstNeg. Memory_Allocation_Negative_Tests ... rocrtstStress. Memory_Concurrent_Allocate_Test ...5. 筛选运行测试
使用--gtest_filter按模式筛选（支持通配符*和-排除）：
5.1 运行单个测试
sudorocrtst64--gtest_filter="rocrtstFunc.SvmMemoryBasic"5.2 运行整个套件
# 运行所有功能测试sudorocrtst64--gtest_filter="rocrtstFunc.*"# 运行所有性能测试sudorocrtst64--gtest_filter="rocrtstPerf.*"# 运行所有压力测试sudorocrtst64--gtest_filter="rocrtstStress.*"5.3 按关键字筛选
# 运行所有包含 "Memory" 的测试sudorocrtst64--gtest_filter="*Memory*"# 运行所有 SVM 相关测试sudorocrtst64--gtest_filter="*Svm*"# 运行所有 Queue 相关测试sudorocrtst64--gtest_filter="*Queue*"5.4 排除特定测试
# 运行所有功能测试，但排除 IPCsudorocrtst64--gtest_filter="rocrtstFunc.*:-*IPC*"# 运行所有测试，排除性能测试和压力测试sudorocrtst64--gtest_filter="*:-rocrtstPerf.*:rocrtstStress.*"5.5 组合多个模式
# 运行内存相关的功能测试和信号测试sudorocrtst64--gtest_filter="rocrtstFunc.*Memory*:rocrtstFunc.*Signal*"6. rocrtst 专用参数
除了 gtest 标准参数外，rocrtst 提供了额外的命令行参数：
6.1 参数一览
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--iterations <N> | -i | 每个测试的迭代次数 | 5 |
--verbosity <N> | -v | 输出详细程度 | 1 |
--monitor_verbosity <N> | -m | GPU 监控信息级别 | 0 |
--rocrtst_help | -r | 显示 rocrtst 帮助 | — |
6.2 verbosity 详细级别
| 级别 | 说明 | 适用场景 |
|---|---|---|
| 0 | 最简输出，仅显示摘要 | CI/CD 自动化 |
| 1 | 标准输出，显示中间数据 | 日常测试（默认） |
| 2 | 显示进度信息 | 长时间运行的测试 |
| ≥3 | 调试输出 | 排查问题 |
6.3 monitor_verbosity GPU 监控
| 级别 | 说明 |
|---|---|
| 0 | 不读取/显示任何 GPU 监控信息（默认） |
| 1 | 在第一个测试前和每个测试后打印所有可用的 GPU 监控信息 |
| ≥2 | 打印更多详细的监控信息（测试特定） |
⚠️ 使用
-m 1或更高级别需要系统安装amd_smi库。
6.4 使用示例
# 运行 SVM 测试，10 次迭代，进度显示sudorocrtst64--gtest_filter="*Svm*"-i10-v2# 运行性能测试，附带 GPU 监控数据sudorocrtst64--gtest_filter="rocrtstPerf.*"-m1# 运行全部测试，最简输出sudorocrtst64-v0# 查看 rocrtst 专用帮助sudorocrtst64-r7. gtest 常用参数
| 参数 | 说明 | 示例 |
|---|---|---|
--gtest_list_tests | 列出所有测试（不运行） | |
--gtest_filter=PATTERN | 按模式筛选测试 | "*Memory*" |
--gtest_repeat=N | 重复运行 N 次 | --gtest_repeat=3 |
--gtest_shuffle | 随机化测试顺序 | |
--gtest_output=xml:FILE | 输出 XML 格式报告 | --gtest_output=xml:result.xml |
--gtest_break_on_failure | 测试失败时触发断点 | 配合 GDB 使用 |
--gtest_also_run_disabled_tests | 运行被 DISABLED_ 前缀禁用的测试 |
8. 测试结果解读
8.1 通过
[ OK ] rocrtstFunc.SvmMemoryBasic (1234 ms) [ PASSED ] 1 test.8.2 失败
[ FAILED ] rocrtstFunc.SvmMemoryBasic (5678 ms) [ FAILED ] 1 test, listed below: [ FAILED ] rocrtstFunc.SvmMemoryBasic失败时查看详细错误信息，通常包含 HSA 状态码和错误位置。
8.3 跳过
部分测试会因平台不支持而跳过（如该 GPU 不支持 SVM），输出中 SetUp 阶段会提示 skip：
[ RUN ] rocrtstFunc.SvmMemoryBasic Test skipped: platform filtering (not supported on this GPU) [ OK ] rocrtstFunc.SvmMemoryBasic (10 ms)8.4 DISABLED 测试
以DISABLED_前缀命名的测试默认不运行。如需运行：
sudorocrtst64--gtest_also_run_disabled_tests--gtest_filter="*DISABLED*"9. 生成测试报告
# 生成 XML 格式报告（可被 Jenkins/CI 解析）sudorocrtst64--gtest_output=xml:rocrtst_report.xml# 生成 JSON 格式报告sudorocrtst64--gtest_output=json:rocrtst_report.json10. 常见运行问题
Q: 提示 “Permission denied” 或 “HSA_STATUS_ERROR”
A:大多数测试需要 root 权限：
sudorocrtst64...Q: 提示找不到 kernel 文件 (.hsaco)
A:确保从对应 GPU 的目录运行：
cd$ROCM_PREFIX/share/rocrtst/gfx942# 你的 GPU 型号sudo$ROCM_PREFIX/bin/rocrtst64...Q: 提示 “libhsa-runtime64.so: cannot open shared object file”
A:设置库搜索路径：
exportLD_LIBRARY_PATH=$ROCM_PREFIX/lib:$LD_LIBRARY_PATHQ: 测试长时间卡住不动
A:可能是 GPU hang。按Ctrl+C终止，检查dmesg中是否有 GPU 错误：
sudodmesg|grep-i"amdgpu\|gpu\|hang"|tail-20上一篇：03-构建指南
下一篇：05-功能测试详解 — 深入了解各功能测试模块
