1. ROCr Runtime 简介
ROCr Runtime（即 HSA Runtime）是 AMD ROCm 软件栈的核心运行时库，实现了 HSA (Heterogeneous System Architecture) 规范。它为上层应用和框架（如 HIP、OpenCL）提供底层 GPU 资源管理能力，包括：
- 设备发现与管理— 枚举系统中的 CPU 和 GPU Agent
- 内存管理— 分配、映射、拷贝 GPU/CPU 可访问的内存
- 任务调度— 通过 AQL 队列向 GPU 提交计算任务
- 信号同步— 实现 CPU 与 GPU、GPU 与 GPU 之间的同步
- 进程间通信— 跨进程共享 GPU 内存和资源
rocrtst是 ROCr Runtime 的官方测试套件，用于验证上述功能的正确性和性能。
2. rocrtst 的定位
┌─────────────────────────────────────────┐ │ 应用层 (HIP / OpenCL) │ ├─────────────────────────────────────────┤ │ ROCr Runtime (libhsa) │ ← rocrtst 测试的目标 ├─────────────────────────────────────────┤ │ Thunk (libhsakmt) │ ├─────────────────────────────────────────┤ │ 内核驱动 (amdgpu) │ ├─────────────────────────────────────────┤ │ AMD GPU 硬件 │ └─────────────────────────────────────────┘rocrtst 直接调用 ROCr Runtime 的 HSA API 进行测试，不依赖 HIP 或 OpenCL 等上层框架。它的作用是：
- 验证 ROCr API 实现的正确性（功能测试）
- 评估关键操作的性能指标（性能测试）
- 检验异常输入的处理能力（负面测试）
- 检查高并发场景的稳定性（压力测试）
3. HSA 核心概念
理解以下概念是阅读和编写 rocrtst 用例的前提。
3.1 Agent
Agent 代表系统中的一个计算设备。通常有两类：
| 类型 | 说明 | 示例 |
|---|---|---|
| CPU Agent | 主机处理器 | x86_64 CPU |
| GPU Agent | 图形处理器 | gfx942, gfx1100 等 |
通过hsa_iterate_agents()枚举系统中所有 Agent。
3.2 Queue（队列）
Queue 是向 GPU 提交任务的通道。应用将 AQL (Architected Queuing Language) 数据包写入队列，GPU 硬件自动取出并执行。
CPU GPU │ │ │ ┌──────────────────┐ │ │ │ AQL Queue │ │ │ │ ┌────┬────┬────┐ │ │ └───►│ pkt│ pkt│ pkt│─┼──────► │ └────┴────┴────┘ │ └──────────────────┘3.3 Signal（信号）
Signal 是一个 64 位整数值，用于同步。常见用途：
- 完成通知— GPU 执行完任务后修改 Signal 值，CPU 等待该变化
- 门控— 利用 Barrier 包等待多个 Signal 满足条件后再继续
3.4 Memory（内存）
HSA 定义了多种内存区域：
| 内存类型 | 位置 | 说明 |
|---|---|---|
| System Memory | 主机内存 | CPU 可直接访问，GPU 通过 PCIe 访问 |
| Local Memory (VRAM) | 显存 | GPU 本地高带宽内存 |
| SVM (共享虚拟内存) | 统一地址空间 | CPU 和 GPU 使用相同虚拟地址访问 |
关键 API：hsa_memory_allocate()、hsa_memory_copy()、hsa_amd_memory_async_copy()等。
3.5 Kernel（GPU 内核）
GPU 上运行的计算程序。在 rocrtst 中，kernel 源码为 OpenCL C 格式（.cl文件），通过 LLVM/Clang 编译为.hsaco（HSA Code Object）文件，运行时加载到 GPU 执行。
4. 目录结构
rocrtst/ ├── README.md # 官方构建说明 │ ├── common/ # 公共基础设施 │ ├── base_rocr.h / .cc # BaseRocR 基类：设备、kernel、内存池管理 │ ├── base_rocr_utils.h / .cc # 工具函数（查找 Agent、加载 kernel 等） │ ├── common.h / .cc # 通用常量和宏定义 │ ├── helper_funcs.h / .cc # 辅助函数 │ ├── hsatimer.h / .cc # 高精度计时器 │ ├── os.h / .cc # 操作系统抽象层 │ ├── concurrent_utils.h / .cc # 并发测试工具 │ ├── env_config.h / .cc # 环境配置 │ └── platform_filter.h / .cc # 平台过滤（按 GPU 型号跳过测试） │ ├── Kernels/ # GPU kernel 源码 │ ├── CMakeLists.txt # kernel 编译规则 │ ├── binary_search_kernel.cl # 二分查找 kernel │ ├── read_kernel.cl # 读操作 kernel │ └── write_kernel.cl # 写操作 kernel │ ├── suites/ # 测试套件（核心） │ ├── test_common/ # 主入口与构建系统 │ │ ├── CMakeLists.txt # 顶层 CMake（编译所有测试） │ │ ├── main.h # 主头文件 │ │ └── test_base.h / .cc # TestBase 基类 │ ├── functional/ # 功能测试（26 个模块） │ ├── performance/ # 性能测试（6 个模块） │ ├── negative/ # 负面测试（2 个模块） │ └── stress/ # 压力测试（2 个模块） │ ├── samples/ # 独立示例程序 │ ├── rocm_async/ # 异步内存拷贝工具 │ ├── binary_search/ # 二分查找示例 │ ├── ipc/ # 进程间通信示例 │ └── rocrinfo/ # 系统信息查询 │ ├── gtest/ # Google Test 框架 ├── thirdparty/ # 第三方库（hwloc 等） └── config/ # 测试配置文件5. 类继承体系
rocrtst 采用面向对象的设计，所有测试用例遵循统一的继承结构：
rocrtst::BaseRocR ← 最底层基类（common/base_rocr.h） │ 管理：Agent、Kernel、内存池、Profile │ └── TestBase ← 测试基类（suites/test_common/test_base.h） │ 定义生命周期：SetUp() → Run() → Close() │ 提供：DisplayResults()、平台过滤 │ ├── SvmMemoryTestBasic ← 具体测试（functional/svm_memory.h） ├── MemoryAllocationTest ← 具体测试（functional/memory_allocation.h） ├── DispatchTimeTest ← 具体测试（performance/dispatch_time.h） └── ... ← 其他测试用例每个测试用例需要实现以下虚函数：
| 方法 | 用途 |
|---|---|
SetUp() | 初始化 HSA Runtime、获取 Agent、分配内存、加载 Kernel |
Run() | 执行核心测试逻辑 |
Close() | 释放资源、关闭 HSA Runtime |
DisplayResults() | 输出测试结果（可选） |
6. 测试套件概览
6.1 功能测试 (functional/) — 26 个模块
验证 ROCr API 的正确性，按领域可分为：
- 内存管理：
memory_basic、memory_allocation、memory_access、memory_alignment、memory_atomics、metadata_prefetch、svm_memory、virtual_memory - 队列与信号：
counted_queues、aql_barrier_bit、signal_kernel、signal_concurrent - 设备管理：
agent_props、filter_devices、cu_masking、cuid - 生命周期：
concurrent_init、concurrent_shutdown、concurrent_init_shutdown、reference_count - 其他：
ipc、debug_basic、gpu_coredump、deallocation_notifier、test_fault_example、time_stamp
6.2 性能测试 (performance/) — 6 个模块
测量关键操作的延迟和带宽：dispatch_time、enqueueLatency、memory_async_copy、memory_async_copy_numa、memory_async_copy_on_engine、agent_preload
6.3 负面测试 (negative/) — 2 个模块
验证错误输入的处理：memory_allocate_negative_tests、queue_validation
6.4 压力测试 (stress/) — 2 个模块
高并发场景验证：memory_concurrent_tests、queue_write_index_concurrent_tests
7. 构建产物
构建完成后生成：
| 产物 | 说明 |
|---|---|
rocrtst64 | 主测试可执行文件，包含所有测试用例 |
<gpu>/rocrtst64 | 各 GPU 型号目录下的符号链接 |
<gpu>/*.hsaco | 各 GPU 型号编译的 kernel 二进制文件 |
8. 总结
| 项目 | 说明 |
|---|---|
| 测试框架 | Google Test (gtest) |
| 测试目标 | ROCr Runtime (HSA API) |
| 编程语言 | C++ (测试代码) + OpenCL C (GPU kernel) |
| 构建系统 | CMake |
| 测试数量 | 36 个模块（functional 26 + performance 6 + negative 2 + stress 2） |
| 统一入口 | 所有测试编译为rocrtst64单一可执行文件 |
下一篇：02-环境搭建 — 搭建 rocrtst 的开发与运行环境
