PC sampling
PC sampling answers a question counters cannot: which instruction inside the
kernel is hot, and what the wavefront was waiting on. Use it after counters
have already identified the kernel worth this level of detail.
PC sampling is experimental. Every command below needs
, and
option names can change between releases, so run
rocprof-compute profile --experimental --help
before choosing flags.
Before you start
If
command -v rocprof-compute
finds the tool and
rocprof-compute analyze --debug-verify-deps
passes, skip this section.
On ROCm 10.2, use
instead of
.
Otherwise, check that ROCm and a GPU are present:
If either command fails, ROCm is not installed or no GPU is visible. Stop and
point the user to "Install the ROCm Core SDK" in the
install guide. Installing rocprof-compute
alone does not help.
Check the GPU against
compatible accelerators.
The table lists product families, so match the
that
prints, and use the
name to confirm. If the GPU is not supported, stop and
tell the user.
Then follow "Install the analyze mode dependencies" in the
install guide, which installs
rocprof-compute in a virtual environment of its own. Use the nightly index so the
version matches these skills. Activate that environment with
source <venv>/bin/activate
before you run rocprof-compute, and confirm with
rocprof-compute analyze --debug-verify-deps
. If the application is a Python
script, note the full path of its Python before you activate, and run the
script with that path.
1. Check what the hardware supports
bash
rocprofv3-avail info --pc-sampling
This reports the sampling methods the installed device accepts and the valid
interval range. Two methods exist:
- samples in hardware and is the only method that records a stall
reason. It requires MI300 or newer.
- works more widely but records no stall reason, and its samples
can land a little past the instruction responsible.
defaults to
. Fall back to
only
when the device rejects stochastic.
Start with the default interval: leave out
. Change it
only when the analysis shows too few or too many samples, and keep it within
the range the command above prints. Stochastic intervals are counted in cycles
and must be a power of two. Host-trap intervals are in microseconds.
2. Build for source attribution
Samples always map to the kernel's assembly. Mapping assembly back to a source
line requires debug info in the application, for example
. Without
it, the
column in CSV output is empty.
Keep optimization flags on; profiling a
build measures the wrong program.
Ask about the build before collecting, because rebuilding afterwards means
re-profiling.
3. Collect
bash
rocprof-compute profile \
--experimental \
--pc-sampling \
--pc-sampling-method stochastic \
--name <workload_name> \
-- <application> <args>
PC sampling does not collect counters. A PC-sampling-only profile cannot be
combined with the framework tracing options, and it will not populate the
counter panels. When the user needs both, collect two workloads.
4. Analyze
bash
rocprof-compute analyze --path ./workloads/<name>/<gpu_model>
The PC sampling table shows one row per kernel, hottest first, so it picks the
kernel to look at.
defaults to 10 kernels; pass
for
every kernel.
Read the table as:
| Column | Meaning |
|---|
| Sample count | how often execution was in the kernel |
| Stall reason | what the kernel's wavefronts were waiting on, stochastic sampling only |
For the hot instructions of that kernel, export the annotated disassembly
(step 5) and open the kernel's ISA CSV.
A high sample count marks a hot instruction, not a defective one. A loop body
is supposed to be hot. What matters is a hot instruction whose stall reason
says it is waiting: a memory stall on a load means the kernel is latency-bound
there, and the fix is usually coalescing, prefetching, or more independent work
between the load and its use.
Stall reasons and what each one implies are listed in
pc_sampling.rst. Do not interpret a stall
reason from host-trap data; it does not record one.
5. Export annotated disassembly
bash
rocprof-compute analyze --path ./workloads/<name>/<gpu_model> \
--output-format csv --output-name pc_report
CSV output writes per-kernel annotated disassembly into a
directory, with sample counts and source lines beside
each instruction.
stores the same content in the analysis
database. Both disable terminal output.
CSV output also writes
beside each captured source
file, with the sample counts of every source line and the ISA rows each line
compiled to. Start there to find the hottest source line.
6. When there are too few samples
A short kernel may not accumulate enough samples to be meaningful. Increase the
work the kernel does, or shorten the interval within the range the device
accepts, rather than drawing conclusions from a handful of samples.
For multi-process workloads, the PC sampling table combines each kernel's
samples from all processes, so use it only to pick the kernel. The per-kernel
ISA files keep each process and code object separate; read the instructions
there. See the multi-process sections of
pc_sampling.rst.