Skip to main content
skill CX Codex

rocprofiler-pc-sampling — Claude Code skill: setup and usage

rocprofiler-pc-sampling profiles AMD GPU applications with rocprofv3 program counter sampling to uncover execution hotspots and GPU stall reasons.

MIT 592 installs ★ 510 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add amd/skills --skill rocprofiler-pc-sampling -a claude-code
Open on GitHub

What rocprofiler-pc-sampling does

This skill guides PC sampling execution using rocprofv3 with the --pc-sampling-beta-enabled flag. It chooses between stochastic sampling and host_trap, tracks dispatches with --kernel-trace, and saves data as JSON or CSV. Because default rocpd files lack PC sampling support, explicit format selection is required.

An internal script at scripts/analyze_pc_sampling.py digests the resulting traces. It reports the heaviest sample locations along with dominant stall causes, such as memory-related WAITCNT pauses in transpose operations.

A functional ROCm install and a compatible AMD GPU verified by amd-smi are mandatory. The target executable must also be compiled with debug symbols and optimization (-g -O3) to allow line-by-line attribution.

What it helps with

  • Locate hotspot instructions in AMD GPU kernel execution
  • Identify stall reasons behind GPU compute delays
  • Configure stochastic PC sampling in rocprofv3
  • Attribute PC samples to source lines in optimized builds

Example prompts for the agent

  • Run stochastic PC sampling on ./bin/gemm_test and summarize the hotspots
  • Analyze stall reasons for matrix_kernel from the json profiling output
  • Profile my AMD GPU binary with rocprofv3 using host_trap sampling

How to install rocprofiler-pc-sampling

1Skills CLI (Vercel)

npx skills add amd/skills --skill rocprofiler-pc-sampling -a claude-code

2Manually: put the files in place

~/.claude/skills/rocprofiler-pc-sampling/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rocprofiler-pc-sampling/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about rocprofiler-pc-sampling

How to install rocprofiler-pc-sampling in Claude Code?

Run npx skills add amd/skills --skill rocprofiler-pc-sampling -a claude-code.

What does rocprofiler-pc-sampling do?

It configures rocprofv3 with program counter sampling on AMD hardware and processes output traces to spot performance stalls.

Which output formats work with PC sampling?

You must select json or csv. The default rocpd format does not currently support PC sampling records.

Source text

SKILL.md · MIT
---
name: rocprofiler-pc-sampling
description: Profiles a target application using rocprofv3 with program counter sampling enabled and then analyzes the results. Use when the user has a program that runs on an AMD GPU and asks to perform PC sampling, to determine the runtime performance characteristics of their application, to determine stall reasons, or to determine hotspots in the code.
---

# PC Sampling

## 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.

## How to use PC Sampling

To run rocprofv3 with PC sampling:

- explicitly enable pc sampling with the flag `--pc-sampling-beta-enabled`.
- specify the 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 Sampling Outputs

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.

#### 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 Guidance

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.

## Analyzing PC Sampling Results

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.

## Procedure Checklist

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

## 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 configuration can be used at a time, so if exactly one valid configuration is reported then PC sampling is probably being actively used by another process. If this happens, report it to the user and inform them that results may be affected.

© amd · MIT · amd/skills

Similar skills

All skills for Code review and refactoring →

From the same set18

The whole set →
local-ai-app-integration local-ai-app-integration integrates Embeddable Lemonade into apps that currently call cloud AI APIs. Useful when shipping on-device inference on Windows x64 or Linux x64. CX Codex +1 1,300installs hyperloom-workload-optimizer hyperloom-workload-optimizer bootstraps Hyperloom on an AMD Instinct host and kicks off multi-agent throughput optimization for LLM serving. Useful when a model on MI300X, MI325X or MI355X needs to push more tokens per second. CX Codex +1 1,200installs quark-install quark-install installs or verifies AMD Quark and makes sure the Python environment has a PyTorch build that matches the accelerator. Useful when the quark import fails or kernels won't compile. CX Codex +1 966installs quark-torch-llm-ptq quark-torch-llm-ptq walks a PyTorch or Hugging Face model through AMD Quark post-training quantization: intake, plan, manifest, run. CX Codex +1 965installs flydsl-kernel-authoring flydsl-kernel-authoring — a skill for Claude Code and Cursor serving as a reference manual for authoring and reviewing FlyDSL GPU kernels on AMD GPUs. CX Codex +1 437installs flydsl-kernel-trace-analysis The flydsl-kernel-trace-analysis Claude Code skill profiles GPU kernels and analyzes their instruction-level traces to locate stalls. Run it to collect a trace or inspect an existing dispatch directory. CX Codex +1 436installs rocprofiler-systems-choosing-a-profiling-preset rocprofiler-systems-choosing-a-profiling-preset is a Claude Code skill that selects a runtime preset by workload and profiling goal. It activates on preset questions or commands missing --preset. CX Codex +1 266installs rocprofiler-systems-discovering-profiling-options rocprofiler-systems-discovering-profiling-options is a Claude Code skill that finds the right command for exploring ROCPROFSYS profiling options. It handles requests about available counters, ROCm tracing domains, and run flags. CX Codex +1 266installs

Project sponsors

Companies that keep this analytics open