摘要本篇从知识准备和环境搭建两个维度帮助读者评估自身的阅读准备度并搭建一个可编译、可调试、可运行 libhsakmt 的本地环境为后续各章的源码级分析打下基础。1. 前置知识体系阅读本专栏不需要你是 GPU 驱动专家但需要具备以下几个方向的基础知识。下表按必备 / 建议 / 加分三级列出帮助你快速评估自身的准备度级别知识领域具体要求必备C 语言能阅读中大规模 C 项目~16,000 行熟悉指针、结构体、位运算、函数指针、宏展开必备Linux 系统编程理解ioctl、mmap、open/close、文件描述符了解errno错误处理模式必备Linux 用户态基本操作能使用 shell、编辑器、git、cmake、make建议sysfs / procfs了解 Linux 通过/sys和/proc暴露内核信息的机制第二章 Topology 重度依赖建议虚拟内存基础理解虚拟地址 vs 物理地址、页表、mmap 映射第三 ~ 四章 Memory / FMM 核心前提建议GPU 基本概念知道 GPU 有显存VRAM、计算单元CU、命令队列Queue、DMA 引擎SDMA加分HSA 标准了解 HSA Foundation 的 Agent / Signal / Queue / Memory Region 抽象模型加分内核驱动开发理解 Linux 字符设备驱动、ioctl 命令编码方式_IOW/_IOR/_IOWR加分DRM/KFD 子系统了解 Linux DRM 框架、AMD 的 amdgpu 驱动和 KFDKernel Fusion Driver子系统1.1 不需要什么为避免过度准备以下列出不需要提前掌握的内容不需要CUDA 或 HIP 编程经验 —— 本专栏聚焦 Runtime 底层不涉及 GPU kernel 编写不需要汇编语言 —— libhsakmt 是纯 C 用户态代码不含汇编不需要内核编译经验 —— 我们只分析用户态 Thunk 层不修改内核不需要AMD 硬件手册 —— 涉及寄存器和 PM4 指令包时专栏会给出必要背景1.2 推荐的补充阅读如果你在某些领域的基础比较薄弱以下资源可以帮助快速补课领域推荐资源C 语言进阶C Programming: A Modern Approach(K.N. King)Linux 系统编程The Linux Programming Interface(Michael Kerrisk)重点阅读第 4、5、14、49 章文件 I/O、ioctl、mmap虚拟内存CSAPP深入理解计算机系统第 9 章GPU 架构入门AMD CDNA / RDNA 白皮书AMD 官网免费下载HSA 标准HSA Platform System Architecture Specification2. 硬件要求2.1 推荐配置AMD dGPU要完整运行 libhsakmt包括 kfdtest 测试套件你需要一块 ROCm 支持的 AMD 独立显卡。当前主流支持列表GPU 系列代表型号架构Instinct MI300MI300X / MI300ACDNA 3Instinct MI200MI250X / MI250 / MI210CDNA 2Instinct MI100MI100CDNA 1Radeon RX 7000RX 7900 XTX / 7900 XTRDNA 3Radeon RX 6000RX 6900 XT / 6800 XTRDNA 2完整的支持矩阵请查阅 ROCm 官方兼容性文档。2.2 最低配置仅源码阅读如果你暂时没有 AMD GPU仍然可以跟随本专栏进行源码阅读与编译。libhsakmt 作为用户态库编译不依赖 GPU 硬件。只是无法运行 kfdtest 测试或实际调用/dev/kfd。此外libhsakmt 的Model 机制第十章提供了软件 GPU 仿真能力可在无硬件环境下运行部分功能路径。3. 操作系统3.1 推荐系统操作系统版本备注Ubuntu22.04 / 24.04 LTSROCm 官方一级支持RHEL8.x / 9.xROCm 官方支持SLES15 SP5ROCm 官方支持本专栏的所有命令和示例以Ubuntu 22.04/24.04为基准。3.2 Windows / WSLlibhsakmt 同样支持 Windows 构建通过 DXG/WDDM 后端源码位于src/dxg/。不过本专栏主线聚焦 Linux KFD 后端。Windows 用户可以通过 WSL2 搭建 Linux 环境来跟随操作。4. 驱动安装4.1 安装 ROCm 内核驱动libhsakmt 的运行时依赖 KFD 内核驱动即/dev/kfd设备节点。推荐通过 ROCm 官方包管理器安装# Ubuntu —— 安装 ROCm 内核驱动amdgpu-dkms# 参考https://rocm.docs.amd.com/projects/install-on-linux/en/latest/sudoaptupdatesudoaptinstallamdgpu-dkmssudoreboot重启后验证驱动是否正常加载# 检查 KFD 设备节点ls-la/dev/kfd# 预期输出: crw-rw---- 1 root render ... /dev/kfd# 检查 amdgpu 驱动模块lsmod|grepamdgpu# 预期输出: amdgpu ... 显示已加载# 检查 GPU 渲染节点ls/dev/dri/render*# 预期输出: /dev/dri/renderD128 可能有多个4.2 用户组权限访问/dev/kfd和/dev/dri/render*需要用户属于render和video组sudousermod-a-Grender,video$USER# 需要重新登录生效5. 获取源码libhsakmt 的源码位于rocm-systems超级仓库的projects/rocr-runtime/libhsakmt/路径下。5.1 完整克隆gitclone https://github.com/ROCm/rocm-systems.gitcdrocm-systems5.2 稀疏检出推荐超级仓库包含大量子项目如果只关注 rocr-runtime可以使用稀疏检出节省时间和磁盘空间gitclone --no-checkout--filterblob:none https://github.com/ROCm/rocm-systems.gitcdrocm-systemsgitsparse-checkout init--conegitsparse-checkoutsetprojects/rocr-runtimegitcheckout develop检出后的关键路径rocm-systems/ └── projects/ └── rocr-runtime/ ├── CMakeLists.txt # 顶层构建入口 ├── libhsakmt/ # ← 本专栏的主角 │ ├── CMakeLists.txt │ ├── include/hsakmt/ # 公共头文件 │ ├── src/ # 源码20 个 .c 文件 │ └── tests/ # 测试套件 └── runtime/ └── hsa-runtime/ # HSA Runtime链接 libhsakmt6. 安装编译依赖6.1 Ubuntu一键安装sudoaptupdatesudoaptinstall-y\build-essential\cmake\pkg-config\libelf-dev\libdrm-dev\libdrm-amdgpu-dev\libnuma-dev\xxd各依赖的用途包名用途build-essentialgcc / g / make 编译工具链cmake(≥ 3.7)构建系统pkg-config依赖库发现libelf-devELF 二进制格式解析HSA Runtime 加载 GPU 代码对象libdrm-devDRM 用户态库libdrm-amdgpu-devAMD GPU 专用 DRM 接口libhsakmt 通过它与 amdgpu 驱动交互libnuma-devNUMA 拓扑感知内存分配xxd十六进制转储工具HSA Runtime 构建时需要6.2 RHEL / CentOSsudodnfinstall-y\gcc gcc-cmake\cmake\pkgconfig\elfutils-libelf-devel\libdrm-devel\numactl-devel\vim-common# 提供 xxd7. 编译构建7.1 完整构建ROCr ROCt推荐方式同时构建 HSA Runtime 和 libhsakmt产出完整的libhsa-runtime64.socdprojects/rocr-runtimemkdirbuildcdbuild cmake-DCMAKE_BUILD_TYPEDebug\-DCMAKE_INSTALL_PREFIX/opt/rocm\..make-j$(nproc)使用Debug模式编译可保留符号信息方便后续用 GDB 跟踪 libhsakmt 内部流程。构建产物build/ ├── libhsakmt/ │ └── libhsakmt.a # libhsakmt 静态库 └── runtime/hsa-runtime/ └── libhsa-runtime64.so # 最终交付件内含 libhsakmt7.2 仅构建 libhsakmtThunk Only如果你只想编译和研究 libhsakmt 本身可以跳过 HSA Runtimecdprojects/rocr-runtimemkdirbuildcdbuild cmake-DCMAKE_BUILD_TYPEDebug\-DBUILD_ROCROFF\..make-j$(nproc)此模式下只产出libhsakmt.a编译更快依赖更少不需要rocm-llvm-dev和xxd。7.3 关键 CMake 选项选项默认值说明CMAKE_BUILD_TYPEDebugDebug保留符号Release开启优化BUILD_SHARED_LIBSONON 共享库.soOFF 静态库.aBUILD_ROCRONOFF仅编译 libhsakmtThunk OnlyBUILD_THUNK_VIRTIOOFFON启用 VirtIO 虚拟化后端ADDRESS_SANITIZEROFFON启用 ASAN 地址消毒检测8. 验证环境8.1 编译验证构建成功后检查产物是否存在# 检查 libhsakmt 静态库ls-labuild/libhsakmt/libhsakmt.a# 检查 HSA Runtime 共享库如果进行了完整构建ls-labuild/runtime/hsa-runtime/libhsa-runtime64.so# 查看 libhsakmt 导出的符号nm build/libhsakmt/libhsakmt.a|grep T hsaKmt|head-20# 预期输出: 一系列 hsaKmt* 函数符号8.2 运行时验证需要 AMD GPU如果你安装了 ROCm 驱动和 AMD GPU可以用rocminfo快速验证整个栈是否正常# 安装 rocminfo如果尚未安装sudoaptinstallrocminfo# 运行设备枚举rocminfo# 预期输出: 列出 CPU Agent 和 GPU Agent 的详细信息rocminfo的执行路径正是应用 → HSA Runtime → libhsakmt → KFD如果它能正常输出 GPU 信息说明整个栈从上到下都是通的。8.3 KFD 测试可选libhsakmt 自带的kfdtest测试套件可以验证 Thunk 层的各个功能模块cdprojects/rocr-runtimemkdirbuildcdbuild cmake-DCMAKE_BUILD_TYPEDebug..make-j$(nproc)# 运行 kfdtest需要 root 权限或正确的用户组cdlibhsakmt/tests/kfdtest ./kfdtest⚠️ kfdtest 需要实际的 AMD GPU 硬件和 KFD 驱动。在无硬件环境下运行会报错这是预期行为。9. 源码阅读工具推荐libhsakmt 约 16,000 行 C 代码、20 个源文件选择合适的工具可以大幅提升阅读效率工具推荐理由VS Code clangd支持跳转定义、查找引用、符号大纲、类型推断。对 C 项目配合compile_commands.json效果极佳Vim/Neovim clangd (LSP)同上适合 terminal 工作流GDBDebug 构建下可单步跟踪 libhsakmt 内部流程配合ioctl断点观察用户态→内核态的调用边界strace追踪ioctl系统调用直观看到 libhsakmt 与/dev/kfd的交互9.1 生成 compile_commands.json为 VS Code / clangd 生成编译数据库启用精确的代码跳转和补全cdprojects/rocr-runtimemkdirbuildcdbuild cmake-DCMAKE_BUILD_TYPEDebug\-DCMAKE_EXPORT_COMPILE_COMMANDSON\..make-j$(nproc)# compile_commands.json 生成在 build/ 目录下# 将其链接到项目根目录供 clangd 发现ln-sbuild/compile_commands.json../compile_commands.json9.2 使用 strace 观察 ioctl 调用在后续学习中当你想直观看到 libhsakmt 的某个函数最终发出了哪些 ioctl 调用时strace是最直接的工具# 追踪 rocminfo 对 /dev/kfd 的 ioctl 调用strace-eioctl-frocminfo21|grepkfd这个技巧在第一章OpenClose和第五章Queue的学习中尤其有用。10. 小结准备项状态检查C 语言 Linux 系统编程基础能读懂ioctl(fd, cmd, arg)的含义操作系统Ubuntu 22.04 / 24.04 LTSAMD GPU ROCm 驱动可选ls /dev/kfd存在用户组权限groups输出包含render和video编译工具链cmake --version≥ 3.7源码获取ls projects/rocr-runtime/libhsakmt/src/*.c输出 20 个文件编译通过build/libhsakmt/libhsakmt.a存在代码导航VS Code 中CtrlClick可跳转到hsaKmtOpenKFD的定义当以上各项全部就绪你就拥有了一个完整的 libhsakmt 学习环境。下一篇开始我们将正式进入第一章 ——OpenClose设备生命周期管理从hsaKmtOpenKFD()的第一行代码开始深入 libhsakmt 的世界。