rocprofiler-pc-sampling

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PC Sampling

PC 采样

Prerequisites

前置条件

The system must have a ROCm installation and an accessible AMD GPU; that is,
```
amd-smi
```
should return at least one valid device.
The GPU must support PC sampling. Available PC sampling configurations can be determined via
```
rocprofv3-avail info --pc-sampling
```
or
```
rocprofv3 -L
```
. Your sampling method and interval must align with the outputs of this command. Also pay attention to any flags reported for a given configuration; at time of writing, stochastic sampling intervals must be powers of two.
The application should be built with debug symbols AND optimization flags (e.g.
```
-g -O3
```
) in order to get source line attribution and a representative execution profile.

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

How to use PC Sampling

如何使用 PC 采样

To run rocprofv3 with PC sampling:

explicitly enable pc sampling with the flag
```
--pc-sampling-beta-enabled
```
.
specify the type of pc sampling method with
```
--pc-sampling-method
```
:
```
host_trap
```
or
```
stochastic
```
specify the interval unit for the sampling with
```
--pc-sampling-unit
```
:
```
time
```
for host_trap and
```
cycles
```
for stochastic
specify the sampling interval with
```
--pc-sampling-interval
```
: an integer representing microseconds if you specified
```
time
```
or cycles if you specified
```
cycles
```
.
add the
```
--kernel-trace
```
flag to track kernel launches for attribution
specify either the
```
json
```
or
```
csv
```
output format with
```
--output-format
```
; the default output format,
```
rocpd
```
, does not currently support PC sampling output.

A typical command will look like the following:

bash

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 采样运行 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 采样输出。

典型命令如下所示：

bash

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 Sampling Outputs

PC 采样输出

Output-related options:

```
-d <dir>
```
: output location (default:
```
%cwd%
```
)
```
-o <prefix>
```
: name prefix (default:
```
%hostname%/%pid%
```
)
```
--output-format csv,json
```
: emit both formats

Default path pattern:

<output_dir>/<output_prefix>_<name>.<ext>

where prefix is

%hostname%/%pid%

unless overridden.

与输出相关的选项：

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

默认路径模式：

<output_dir>/<output_prefix>_<name>.<ext>

，其中前缀默认为

%hostname%/%pid%

，除非手动覆盖。

Possible output files

可能的输出文件

File	Format	Contents
`_pc_sampling_stochastic.csv` or `_pc_sampling_host_trap.csv`	CSV	Flat sample records; one row per sample
`*_agent_info.csv`	CSV	GPU/CPU agent metadata (not samples)
`*_kernel_trace.csv`	CSV	Kernel dispatch records (with `--kernel-trace` )
`*_results.json`	JSON	All data in one file

文件	格式	内容
`_pc_sampling_stochastic.csv` 或 `_pc_sampling_host_trap.csv`	CSV	扁平化采样记录；每个采样占一行
`*_agent_info.csv`	CSV	GPU/CPU agent 元数据（不是采样数据）
`*_kernel_trace.csv`	CSV	内核调度记录（使用 `--kernel-trace` 时生成）
`*_results.json`	JSON	包含在一个文件中的所有数据

PC Sampling Guidance

PC 采样指南

There are two types of PC sampling: host-trap and stochastic. Stochastic requires hardware support and is available on fewer GPUs, but provides more information.

The default output format, rocpd, does not currently support pc sampling, so you must explicitly specify json (preferred) or csv. json outputs contain more information.

Prefer stochastic sampling unless the sampling interval needs to be larger than what stochastic can support.
Prefer the json output format since it will carry richer information when using stochastic sampling.
Prefer larger stochastic sampling intervals (2^18^-2^20^; often the maximum) unless the workload is short enough that this does not produce sufficient samples. Shorter intervals will quickly produce huge amounts of data.
Prefer host trap intervals on the order of 1000 microseconds, decreasing if needed.

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

默认输出格式 rocpd 当前不支持 PC 采样，因此必须显式指定 json（推荐）或 csv。json 输出包含的信息更丰富。

除非所需采样间隔大于 stochastic 能够支持的范围，否则优先使用 stochastic 采样。
优先使用 json 输出格式，因为使用 stochastic 采样时，该格式能够携带更丰富的信息。
优先使用较大的 stochastic 采样间隔（2^18–2^20，通常为最大值），除非工作负载运行时间过短，无法产生足够的采样。较短的间隔会迅速生成海量数据。
host trap 的间隔建议设为约 1000 微秒，必要时可进一步减小。

Analyzing PC Sampling Results

分析 PC 采样结果

Inside this skill's folder is an analysis script: scripts/analyze_pc_sampling.py. When passed the output sample file (.json or .csv) it will report the top sample locations and top stall reasons. You may also filter results to a particular kernel -with

--kernel <kernel name>

Run the included python script to perform basic analysis of the output files. Use its output to analyze the user's code, explain its performance, and help give specific and relevant suggestions for improvements. Inform the user of hot spots, the causes of the hotspots (if available), and possible improvements if any. If there are no notable potential improvements, briefly explain why. For example, transpose operations are heavily memory bound and a profile of a well-written transpose kernel will exhibit large amounts of WAITCNT stalls. This is inherent from the task itself and is not necessarily a failing of the kernel. However, a naive transpose kernel may exhibit scattered reads or writes, causing far more memory traffic and thus WAITCNT stalls than is necessary.

此 skill 的文件夹中包含一个分析脚本：scripts/analyze_pc_sampling.py。传入输出采样文件（.json 或 .csv）后，该脚本会报告主要的采样位置和主要停顿原因。还可以使用

--kernel <kernel name>

将结果筛选到特定内核。

运行随附的 Python 脚本，对输出文件执行基础分析。使用其输出分析用户的代码、解释其性能表现，并提供具体且相关的改进建议。应向用户说明热点、热点产生的原因（如果可以获得）以及可能的改进方案。如果没有值得注意的潜在改进项，则简要说明原因。例如，转置操作受到内存带宽的严重限制，因此一个编写良好的转置内核的性能分析结果会呈现大量 WAITCNT 停顿。这是任务本身固有的特性，并不一定表示内核存在缺陷。然而，一个实现简单的转置内核可能出现分散的读取或写入，导致内存流量远高于必要水平，从而产生更多 WAITCNT 停顿。

Procedure Checklist

操作检查清单

ensure the prerequisites defined above are met
if there is not an up-to-date build of the target application with debug information, build it
profile the application with rocprofv3 using pc sampling settings as directed above
run this skill's included analysis script on the profiling outputs
check that the run was successful and produced a non-trivial number of samples
use the output of the script to provide analysis of their code's behavior and specific guidance on possible improvements

确保满足上述前置条件
如果目标应用程序尚未使用最新代码和调试信息构建，则重新构建
按照上述 PC 采样设置，使用 rocprofv3 对应用程序进行性能分析
对性能分析输出运行此 skill 随附的分析脚本
检查运行是否成功，以及是否生成了数量足够的采样
使用脚本输出分析代码行为，并针对可能的改进提供具体指导

Misc. Tips

其他提示

Tiny workloads may produce too few samples. Ensure the workload is large enough to get a representative sample count. If source code is available and the workload is too small, consider modifying the code to invoke the kernel multiple times, and then restoring it to its original state after the profiling run.

Host-trap sampling can have an instruction "skid" of one or two instructions; if sample attribution does not make sense, look at the surrounding instructions and branch targets.

A brief overview of stall types and their causes is available in this skill's resources/stall-reasons.md.

The rocm-systems repository has several PC sampling documentation files in this folder: projects/rocprofiler-sdk/source/docs/how-to/. You may also access them here: https://rocm.docs.amd.com/projects/rocprofiler-sdk/en/develop/how-to/cdna3-cdna4-pc-sampling.html

Only one PC sampling configurations is supported at a time, so if exactly one valid configuration is reported then PC sampling is probably being actively used by another process.

极小的工作负载可能产生的采样过少。确保工作负载足够大，以获得具有代表性的采样数量。如果可以获得源代码且工作负载过小，可以考虑修改代码以多次调用内核，并在性能分析运行完成后将代码恢复为原始状态。

Host-trap 采样可能出现一条或两条指令的“偏移（skid）”；如果采样归因不合理，应查看周围的指令和分支目标。

此 skill 的 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 采样可能正被另一个进程使用。