ROCm 环境变量设置计算单元数量HSA_CU_MASK 与 ROC_GLOBAL_CU_MASK 实战指南【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build本篇技术指南围绕 legacy-rocm-build 仓库中 docs/reference/environment-variables/setting-cus.rst 的核心内容展开系统讲解如何通过HSA_CU_MASK与ROC_GLOBAL_CU_MASK两个环境变量控制 AMD GPU 计算单元CU的启用范围。读完本文你将掌握这两类变量的语法规则、作用层级、与 GPU 隔离变量的协同方式以及常见的错误配置场景能够在实际计算负载中按需屏蔽或启用 CU。CDNA 2 / CDNA 3 架构中计算单元Compute Unit的结构示意图计算单元CU是什么在 AMD GPU 架构中计算单元Compute UnitCU是基础的可编程执行引擎负责运行复杂程序。AMD 设备架构建立在统一、可编程的计算引擎之上这些引擎即计算单元。每个计算单元内部包含 SIMD 核心、标量与向量 ALUSALU/VALU、寄存器文件、L0/L1 各级缓存等资源并依靠波前调度器wavefront scheduler决定每个时钟周期执行哪个波前从而实现延迟隐藏。完整定义可参考 docs/reference/glossary/device-hardware.rst。不同 GPU 的计算单元数量与组织方式不同例如MI100 总计 120 个 CU物理上组织为 8 个 Shader EngineSE每个 SE 含 15 个 CU每个 CU 又分为 4 个 SIMD 单元见 docs/reference/gpu-arch/mi100.mdMI250 的每个 GCD 有 104 个活跃 CU见 docs/reference/gpu-arch/mi250.mdMI300 系列采用 XCD/GCD 芯片设计计算元素集中于 XCD 内见 docs/reference/gpu-arch/mi300.md。在实际使用 GPU 加速计算负载时有时需要配置硬件对计算单元的占用方式。例如在多租户共享、性能隔离、故障规避或基准测试场景下希望让应用只用部分 CU。这是一个相对高级的选项建议在动手实验前先完整阅读本指南。两个环境变量及其作用层级GPU 驱动提供了两个环境变量用于设置使用的计算单元数量环境变量作用层级说明ROC_GLOBAL_CU_MASK运行时HIP / OpenCL设置在 HIP 或 OpenCL 运行时创建的队列上的 CU 掩码HSA_CU_MASK驱动更低层级设置在驱动中更低层级的队列创建上的掩码同时也会作用于被剖析profiling的队列两者的关键区别在于生效的队列创建层级ROC_GLOBAL_CU_MASK作用在 HIP/OpenCL 运行时创建的队列上而HSA_CU_MASK作用在驱动内部更底层的队列创建路径上并且会覆盖到被性能剖析工具监控的队列。正因为HSA_CU_MASK位于更底层它的影响范围更广在用 rocprof 等工具剖析队列时也需要依赖它来限制剖析队列的 CU 集合。注意这两个环境变量只影响 ROCm 软件栈中的计算应用不影响图形应用如 OpenGL/Vulkan 渲染。语法规则两个环境变量使用相同的语法形式为以分号分隔的CU_Set列表ID [0-9][0-9]* ex. base 10 numbers ID_list (ID | ID-ID)[, (ID | ID-ID)]* ex. 0,2-4,7 GPU_list ID_list ex. 0,2-4,7 CU_list 0x[0-F]* | ID_list ex. 0x337F OR 0,2-4,7 CU_Set GPU_list : CU_list ex. 0,2-4,7:0-15,32-47 OR 0,2-4,7:0x337F HSA_CU_MASK CU_Set [; CU_Set]* ex. 0,2-4,7:0-15,32-47; 3-9:0x337F逐项解读ID十进制数字表示单个 GPU 索引或单个 CU 编号。ID_list由单个 ID 或ID-ID区间组成的逗号分隔列表例如0,2-4,7表示 ID 0、2、3、4、7。注意区间2-4是闭区间包含端点。GPU_list即 GPU 索引列表例如0,2-4,7用于指定掩码作用于哪些 GPU。CU_list计算单元列表支持两种写法十六进制位掩码0x[0-F]*例如0x337F每一位代表一个 CUbit 0 对应 CU 0bit 1 对应 CU 1依此类推十进制 ID 列表同ID_list例如0,2-4,7。CU_SetGPU_list : CU_list的组合把一组 CU 掩码绑定到一组 GPU 上例如0,2-4,7:0-15,32-47或0,2-4,7:0x337F。HSA_CU_MASK及ROC_GLOBAL_CU_MASK一个或多个以分号;分隔的CU_Set例如0,2-4,7:0-15,32-47; 3-9:0x337F表示对 GPU 0/2/3/4/7 启用 CU 0-15 与 32-47同时对 GPU 3-9 应用十六进制掩码0x337F。掩码语义启用与禁用规则掩码的语义遵循以下规则GPU 索引基于ROCR_VISIBLE_DEVICES重排序之后的结果。也就是说掩码中的 GPU 编号不是物理槽位编号而是应用在ROCR_VISIBLE_DEVICES暴露并重排后的设备序列中的索引。对被列出的 GPU掩码中列出的 CU 被启用其余 CU 被禁用。对未列出的 GPU不受影响其全部 CU 保持启用。例如HSA_CU_MASK0:0-31表示仅对可见设备序列中的第 1 个 GPU 启用 CU 0 至 31其余 CU 全部关闭其他 GPU 不受任何影响CU 全部可用。与 GPU 隔离变量的配合由于掩码中的 GPU 索引取的是ROCR_VISIBLE_DEVICES重排后的编号因此在设置 CU 掩码之前往往先要通过 GPU 隔离变量缩小可见设备范围。若想从系统中排除某些 GPU 设备应当使用ROCR_VISIBLE_DEVICES而不是 CU 掩码——CU 掩码只能限制 GPU 内部的 CU无法隐藏整个 GPU 设备。ROCR_VISIBLE_DEVICES接受设备索引或 UUID 列表例如export ROCR_VISIBLE_DEVICES0,GPU-4b2c1a9f-8d3e-6f7a-b5c9-2e4d8a1f6c3b详细说明参见 docs/reference/system-optimization/gpu-isolation.md。完整的 ROCm 环境变量总览含 HIP、ROCR-Runtime、HIPCC 及各 ROCm 库的环境变量参见 docs/reference/environment-variables/index.rst。语法错误与解析终止规则变量解析在遇到语法错误时立即停止出错的CU_Set及其之后的所有内容都会被忽略。因此若一条长变量值中后续还有希望生效的配置请确保它前面的每一段都完全合法。以下是几类明确的语法错误情形重复的 GPU 或 CU ID同一 GPU 或 CU 在列表中重复出现例如0,0:0-15视为语法错误。掩码不含任何可用 CUCU_list为0x0十六进制掩码全 0时视为语法错误因为此时没有任何 CU 被启用。非法字符或非法结构不符合上述文法如使用了非十六进制字符、缺失冒号分隔、空段等的任何输入都会触发解析停止。设备相关的合法性约束并非所有 CU 配置在所有设备上都合法。典型限制来自WGPWorkgroup Processor结构WGP 是 AMD Radeon GPU 上的硬件单元包含两个计算单元及其关联资源用于高效调度和执行波前见 docs/reference/glossary/device-hardware.rst。在可以将两个 CU 组合成一个 WGP即内核以 WGP 模式运行的设备上不允许只禁用 WGP 中的单个 CU。换言之如果你的掩码尝试关闭 WGP 中的一半 CU驱动会将其视为非法配置。因此在为 RadeonRDNA 系设备设置 CU 掩码时应始终按成对WGP 粒度的方式启用或禁用 CU而不是任意指定单个 CU。实战示例示例 1单 GPU 启用部分 CU# 仅对可见设备序列中的第 1 个 GPU 启用 CU 0-15 和 CU 32-47 export HSA_CU_MASK0:0-15,32-47 ./your_hip_application示例 2多 GPU 分别设置# GPU 0/2/3/4/7 启用 CU 0-15 与 32-47GPU 3-9 应用十六进制掩码 0x337F export ROC_GLOBAL_CU_MASK0,2-4,7:0-15,32-47; 3-9:0x337F ./your_application示例 3十六进制位掩码# 0x337F 0011 0011 0111 1111即启用 CU 0-6、8-9、12-13 export HSA_CU_MASK0:0x337F ./your_application示例 4先隔离 GPU再限制 CU# 只暴露 2 个 GPU然后只让第 1 个 GPU 使用一半 CU export ROCR_VISIBLE_DEVICES0,1 export HSA_CU_MASK0:0-31 ./your_application在 CHANGELOG.md 的 SDK 演进记录中可以看到ROCm 的剖析与可见性机制一直在与ROCR_VISIBLE_DEVICES等隔离变量协同演进因此在实际使用中请留意当前 ROCm 版本的对应行为本指南中的变量语法与语义以当前仓库文档 docs/reference/environment-variables/setting-cus.rst 为准。【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ROCm 环境变量设置计算单元数量：HSA_CU_MASK 与 ROC_GLOBAL_CU_MASK 实战指南
ROCm 环境变量设置计算单元数量HSA_CU_MASK 与 ROC_GLOBAL_CU_MASK 实战指南【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build本篇技术指南围绕 legacy-rocm-build 仓库中 docs/reference/environment-variables/setting-cus.rst 的核心内容展开系统讲解如何通过HSA_CU_MASK与ROC_GLOBAL_CU_MASK两个环境变量控制 AMD GPU 计算单元CU的启用范围。读完本文你将掌握这两类变量的语法规则、作用层级、与 GPU 隔离变量的协同方式以及常见的错误配置场景能够在实际计算负载中按需屏蔽或启用 CU。CDNA 2 / CDNA 3 架构中计算单元Compute Unit的结构示意图计算单元CU是什么在 AMD GPU 架构中计算单元Compute UnitCU是基础的可编程执行引擎负责运行复杂程序。AMD 设备架构建立在统一、可编程的计算引擎之上这些引擎即计算单元。每个计算单元内部包含 SIMD 核心、标量与向量 ALUSALU/VALU、寄存器文件、L0/L1 各级缓存等资源并依靠波前调度器wavefront scheduler决定每个时钟周期执行哪个波前从而实现延迟隐藏。完整定义可参考 docs/reference/glossary/device-hardware.rst。不同 GPU 的计算单元数量与组织方式不同例如MI100 总计 120 个 CU物理上组织为 8 个 Shader EngineSE每个 SE 含 15 个 CU每个 CU 又分为 4 个 SIMD 单元见 docs/reference/gpu-arch/mi100.mdMI250 的每个 GCD 有 104 个活跃 CU见 docs/reference/gpu-arch/mi250.mdMI300 系列采用 XCD/GCD 芯片设计计算元素集中于 XCD 内见 docs/reference/gpu-arch/mi300.md。在实际使用 GPU 加速计算负载时有时需要配置硬件对计算单元的占用方式。例如在多租户共享、性能隔离、故障规避或基准测试场景下希望让应用只用部分 CU。这是一个相对高级的选项建议在动手实验前先完整阅读本指南。两个环境变量及其作用层级GPU 驱动提供了两个环境变量用于设置使用的计算单元数量环境变量作用层级说明ROC_GLOBAL_CU_MASK运行时HIP / OpenCL设置在 HIP 或 OpenCL 运行时创建的队列上的 CU 掩码HSA_CU_MASK驱动更低层级设置在驱动中更低层级的队列创建上的掩码同时也会作用于被剖析profiling的队列两者的关键区别在于生效的队列创建层级ROC_GLOBAL_CU_MASK作用在 HIP/OpenCL 运行时创建的队列上而HSA_CU_MASK作用在驱动内部更底层的队列创建路径上并且会覆盖到被性能剖析工具监控的队列。正因为HSA_CU_MASK位于更底层它的影响范围更广在用 rocprof 等工具剖析队列时也需要依赖它来限制剖析队列的 CU 集合。注意这两个环境变量只影响 ROCm 软件栈中的计算应用不影响图形应用如 OpenGL/Vulkan 渲染。语法规则两个环境变量使用相同的语法形式为以分号分隔的CU_Set列表ID [0-9][0-9]* ex. base 10 numbers ID_list (ID | ID-ID)[, (ID | ID-ID)]* ex. 0,2-4,7 GPU_list ID_list ex. 0,2-4,7 CU_list 0x[0-F]* | ID_list ex. 0x337F OR 0,2-4,7 CU_Set GPU_list : CU_list ex. 0,2-4,7:0-15,32-47 OR 0,2-4,7:0x337F HSA_CU_MASK CU_Set [; CU_Set]* ex. 0,2-4,7:0-15,32-47; 3-9:0x337F逐项解读ID十进制数字表示单个 GPU 索引或单个 CU 编号。ID_list由单个 ID 或ID-ID区间组成的逗号分隔列表例如0,2-4,7表示 ID 0、2、3、4、7。注意区间2-4是闭区间包含端点。GPU_list即 GPU 索引列表例如0,2-4,7用于指定掩码作用于哪些 GPU。CU_list计算单元列表支持两种写法十六进制位掩码0x[0-F]*例如0x337F每一位代表一个 CUbit 0 对应 CU 0bit 1 对应 CU 1依此类推十进制 ID 列表同ID_list例如0,2-4,7。CU_SetGPU_list : CU_list的组合把一组 CU 掩码绑定到一组 GPU 上例如0,2-4,7:0-15,32-47或0,2-4,7:0x337F。HSA_CU_MASK及ROC_GLOBAL_CU_MASK一个或多个以分号;分隔的CU_Set例如0,2-4,7:0-15,32-47; 3-9:0x337F表示对 GPU 0/2/3/4/7 启用 CU 0-15 与 32-47同时对 GPU 3-9 应用十六进制掩码0x337F。掩码语义启用与禁用规则掩码的语义遵循以下规则GPU 索引基于ROCR_VISIBLE_DEVICES重排序之后的结果。也就是说掩码中的 GPU 编号不是物理槽位编号而是应用在ROCR_VISIBLE_DEVICES暴露并重排后的设备序列中的索引。对被列出的 GPU掩码中列出的 CU 被启用其余 CU 被禁用。对未列出的 GPU不受影响其全部 CU 保持启用。例如HSA_CU_MASK0:0-31表示仅对可见设备序列中的第 1 个 GPU 启用 CU 0 至 31其余 CU 全部关闭其他 GPU 不受任何影响CU 全部可用。与 GPU 隔离变量的配合由于掩码中的 GPU 索引取的是ROCR_VISIBLE_DEVICES重排后的编号因此在设置 CU 掩码之前往往先要通过 GPU 隔离变量缩小可见设备范围。若想从系统中排除某些 GPU 设备应当使用ROCR_VISIBLE_DEVICES而不是 CU 掩码——CU 掩码只能限制 GPU 内部的 CU无法隐藏整个 GPU 设备。ROCR_VISIBLE_DEVICES接受设备索引或 UUID 列表例如export ROCR_VISIBLE_DEVICES0,GPU-4b2c1a9f-8d3e-6f7a-b5c9-2e4d8a1f6c3b详细说明参见 docs/reference/system-optimization/gpu-isolation.md。完整的 ROCm 环境变量总览含 HIP、ROCR-Runtime、HIPCC 及各 ROCm 库的环境变量参见 docs/reference/environment-variables/index.rst。语法错误与解析终止规则变量解析在遇到语法错误时立即停止出错的CU_Set及其之后的所有内容都会被忽略。因此若一条长变量值中后续还有希望生效的配置请确保它前面的每一段都完全合法。以下是几类明确的语法错误情形重复的 GPU 或 CU ID同一 GPU 或 CU 在列表中重复出现例如0,0:0-15视为语法错误。掩码不含任何可用 CUCU_list为0x0十六进制掩码全 0时视为语法错误因为此时没有任何 CU 被启用。非法字符或非法结构不符合上述文法如使用了非十六进制字符、缺失冒号分隔、空段等的任何输入都会触发解析停止。设备相关的合法性约束并非所有 CU 配置在所有设备上都合法。典型限制来自WGPWorkgroup Processor结构WGP 是 AMD Radeon GPU 上的硬件单元包含两个计算单元及其关联资源用于高效调度和执行波前见 docs/reference/glossary/device-hardware.rst。在可以将两个 CU 组合成一个 WGP即内核以 WGP 模式运行的设备上不允许只禁用 WGP 中的单个 CU。换言之如果你的掩码尝试关闭 WGP 中的一半 CU驱动会将其视为非法配置。因此在为 RadeonRDNA 系设备设置 CU 掩码时应始终按成对WGP 粒度的方式启用或禁用 CU而不是任意指定单个 CU。实战示例示例 1单 GPU 启用部分 CU# 仅对可见设备序列中的第 1 个 GPU 启用 CU 0-15 和 CU 32-47 export HSA_CU_MASK0:0-15,32-47 ./your_hip_application示例 2多 GPU 分别设置# GPU 0/2/3/4/7 启用 CU 0-15 与 32-47GPU 3-9 应用十六进制掩码 0x337F export ROC_GLOBAL_CU_MASK0,2-4,7:0-15,32-47; 3-9:0x337F ./your_application示例 3十六进制位掩码# 0x337F 0011 0011 0111 1111即启用 CU 0-6、8-9、12-13 export HSA_CU_MASK0:0x337F ./your_application示例 4先隔离 GPU再限制 CU# 只暴露 2 个 GPU然后只让第 1 个 GPU 使用一半 CU export ROCR_VISIBLE_DEVICES0,1 export HSA_CU_MASK0:0-31 ./your_application在 CHANGELOG.md 的 SDK 演进记录中可以看到ROCm 的剖析与可见性机制一直在与ROCR_VISIBLE_DEVICES等隔离变量协同演进因此在实际使用中请留意当前 ROCm 版本的对应行为本指南中的变量语法与语义以当前仓库文档 docs/reference/environment-variables/setting-cus.rst 为准。【免费下载链接】legacy-rocm-buildAMD ROCm™ Software - GitHub Home项目地址: https://gitcode.com/GitHub_Trending/ro/legacy-rocm-build创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考