mcpField
R
rocprofiler-pc-sampling

rocprofiler-pc-sampling

github.com/amd开发470189 次安装2 天前更新
代码仓库

关于 rocprofiler-pc-sampling

rocprofiler-pc-sampling 是指导 AMD GPU 程序进行 PC 采样分析的技能，适用于需要定位内核热点与停顿原因的开发者。它说明 rocprofv3 的采样设置，并附带脚本汇总热点位置和停顿原因。

主要功能

  1. 01说明 host-trap 与 stochastic 采样设置
  2. 02配置采样间隔及输出格式
  3. 03采集内核跟踪用于归因
  4. 04用脚本分析热点与停顿原因
  5. 05提供采样结果解读建议

适用场景

  1. 01分析 AMD GPU 内核性能热点
  2. 02定位工作负载中的停顿原因
  3. 03比较不同 PC 采样配置的结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/amd/skills --skill rocprofiler-pc-sampling

安装后在 Claude Code 中输入/rocprofiler-pc-sampling确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.federated.json
skill-card.md
evals/
evals.json
machine.yml
evals/resources/
cuda_demo.cu
demo_program.hip.cpp
resources/
stall-reasons.md
scripts/
analyze_pc_sampling.py
tests/
test_analyze_pc_sampling.py

详细介绍

PC 采样

前提条件

  • 系统必须安装 ROCm，且可访问 AMD GPU；也就是说，运行 amd-smi 至少应返回一个有效设备。
  • GPU 必须支持 PC 采样。可通过 rocprofv3-avail info --pc-sampling 或 rocprofv3 -L 确定可用的 PC 采样配置。采样方法和间隔必须与该命令的输出相符。还请留意特定配置报告的标志；截至撰写本文时，随机采样间隔必须是 2 的幂。
  • 应使用调试符号和优化标志（例如 -g -O3）构建应用程序，以便获取源码行归属信息和具有代表性的执行配置文件。

如何使用 PC 采样

要使用 PC 采样运行 rocprofv3：

  • 使用标志 --pc-sampling-beta-enabled 显式启用 PC 采样。
  • 使用 --pc-sampling-method 指定 PC 采样方法类型：host_trap 或 stochastic
  • 使用 --pc-sampling-unit 指定采样间隔单位：host_trap 使用 time，stochastic 使用 cycles
  • 使用 --pc-sampling-interval 指定采样间隔：指定 time 时，填入表示微秒的整数；指定 cycles 时，填入表示周期数的整数。
  • 添加 --kernel-trace 标志，以跟踪内核启动并进行归属分析
  • 使用 --output-format 指定 json 或 csv 输出格式；默认输出格式 rocpd 目前不支持 PC 采样输出。

典型命令如下：

rocprofv3 \
  --pc-sampling-beta-enabled \
  --pc-sampling-method stochastic \
  --pc-sampling-unit cycles \
  --pc-sampling-interval 1048576 \
  --kernel-trace \
  --output-format json \
  -- <target app>
PC 采样输出

与输出相关的选项：

  • -d <dir>：输出位置（默认值：%cwd%）
  • -o <prefix>：名称前缀（默认值：%hostname%/%pid%）
  • --output-format csv,json：同时生成两种格式

默认路径模式：<output_dir>/<output_prefix>_<name>.<ext>，其中前缀为 %hostname%/%pid%，除非进行了覆盖。

可能的输出文件
文件格式内容
*_pc_sampling_stochastic.csv 或 *_pc_sampling_host_trap.csvCSV扁平采样记录；每个样本一行
*_agent_info.csvCSVGPU/CPU 代理元数据（不是样本）
*_kernel_trace.csvCSV内核分发记录（使用 --kernel-trace 时）
*_results.jsonJSON一个文件中的所有数据
PC 采样指南

PC 采样有两种类型：host-trap 和 stochastic。Stochastic 需要硬件支持，因此仅在较少的 GPU 上可用，但能提供更多信息。

默认输出格式 rocpd 目前不支持 PC 采样，因此必须显式指定 json（首选）或 csv。json 输出包含更多信息。

  • 除非采样间隔需要大于 stochastic 所支持的范围，否则优先使用 stochastic 采样。
  • 使用 stochastic 采样时，优先选择 json 输出格式，因为它包含更丰富的信息。
  • 优先选择较大的 stochastic 采样间隔（2^18^-2^20^；通常为最大值），除非工作负载较短，导致无法获得足够的样本。较短的间隔会迅速产生大量数据。
  • host trap 间隔优先设为约 1000 微秒，必要时再缩短。

分析 PC 采样结果

此技能的文件夹中包含一个分析脚本：scripts/analyze_pc_sampling.py。传入输出样本文件（.json 或 .csv）后，它会报告采样位置和停顿原因的排名。你也可以使用 --kernel <kernel name> 将结果筛选到特定内核。

运行随附的 python 脚本，对输出文件进行基本分析。使用脚本的输出分析用户的代码，解释其性能，并提供具体且相关的改进建议。告知用户热点位置、热点原因（如果有）以及可能的改进方案。如果没有明显的潜在改进，请简要说明原因。例如，转置操作严重受内存带宽限制，性能良好的转置内核在分析结果中会出现大量 WAITCNT 停顿。这是任务本身固有的特性，不一定意味着内核存在问题。不过，朴素的转置内核可能会出现分散的读写操作，导致内存流量远高于必要水平，从而产生更多 WAITCNT 停顿。

操作步骤清单

  1. 确保满足上述先决条件
  2. 如果目标应用没有包含调试信息的最新构建版本，则进行构建
  3. 按照上述说明，使用 rocprofv3 和 PC 采样设置对应用进行性能分析
  4. 使用此技能随附的分析脚本处理性能分析输出
  5. 检查运行是否成功，以及是否生成了数量足够的样本
  6. 根据脚本输出分析代码的行为，并就可能的改进提供具体建议

其他提示

工作负载过小可能导致采样数量不足。请确保工作负载足够大，以便获得有代表性的样本数。如果有源代码且工作负载过小，可以考虑修改代码以多次调用内核，并在性能分析运行结束后恢复原状。

Host-trap 采样可能会出现一到两条指令的归属偏移；如果样本归属看起来不合理，请检查周围的指令和分支目标。

此技能的 resources/stall-reasons.md 中简要介绍了各种停顿类型及其成因。

rocm-systems 仓库在此文件夹中提供了若干 PC 采样文档：projects/rocprofiler-sdk/source/docs/how-to/。你也可以在此处访问这些文档：https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/develop/how-to/cdna3-cdna4-pc-sampling.html

一次只支持一种 PC 采样配置，因此，如果报告的有效配置恰好只有一种，那么很可能有其他进程正在使用 PC 采样。

评论

支持 Markdown