Use when you need to classify why code is slow (front-end vs back-end vs speculation), when hunting branch misprediction sites, after /bench-compare or /perf-regression finds a regression needing root cause, or when building an isolated hot-loop harness. Cross-arch TMA and branch tracing.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Use when you need to classify why code is slow (front-end vs back-end vs speculation), when hunting branch misprediction sites, after /bench-compare or /perf-regression finds a regression needing root cause, or when building an isolated hot-loop harness. Cross-arch TMA and branch tracing.
user-invocable
true
Top-Down Profiling — Classify, Trace, Fix
Structured workflow for diagnosing why code is slow using hardware performance
counters. Works on both x86-64 (Intel/AMD) and AArch64 (ARM Neoverse/Cortex).
CPI > 1.0 → proceed to Mode 3 (Top-Down Classification)
High branch-misses → suspect predictor/layout, proceed to Mode 4 (Branch Trace)
High icache_misses → suspect code size, see references/tma-diagnosis-actions.md FE-Bound section
High cache-misses or LLC-loads → memory/locality issue, see /linux-perf-profile Mode 3 (ARM) or BE-Bound remediation
Cross-ref rust-perf-triage/references/profiling-tools.md for detailed counter interpretation.
Mode 3: Top-Down Classification
Classify the bottleneck into four categories: Retiring, Bad Speculation,
Frontend Bound, Backend Bound. The commands differ by architecture and vendor.
See linux-perf-profile Mode 1 for the full ARM topdown derived metrics table.
Unified interpretation
Category
Threshold
Meaning
Next step
Retiring high
> 80%
Near peak efficiency
Mode 2 for µop reduction; see references/tma-diagnosis-actions.md
Bad Speculation high
> 15%
Branch mispredictions
Mode 4 for branch traces
Frontend Bound high
> 20%
ICache / decode stalls
references/tma-diagnosis-actions.md FE section
Backend Bound high
> 40%
Memory / execution ports
references/tma-diagnosis-actions.md BE section
See references/tma-diagnosis-actions.md for the complete diagnosis-to-action mapping.
Mode 4: Branch Trace Recording & Decoding
After Mode 3 identifies Bad Speculation or you see high branch-misses in Mode 2,
record branch traces to find the exact misprediction sites.
x86-64 (Intel LBR, Skylake+ = 32 entries)
# Record with LBR (user-space branches, ~100K sample period)sudo perf record -o perf.data -c 100000 -b -e cycles:u \
-- taskset -c 2 ./target/release/tiny_hot
# Identify misprediction hotspots (function-level)
perf report --sort symbol_from,symbol_to,mispredict --stdio
# Dump raw branch stacks with Rust demangling
perf script -F ip,sym,brstack | rustfilt | head -200
# Map specific addresses to source
addr2line -e ./target/release/tiny_hot 0x<ADDRESS>
# View disassembly around a hot branch
objdump -dr --no-show-raw-insn ./target/release/tiny_hot | rustfilt | less
# Annotate with per-basic-block cycles/IPC (Skylake+ timed LBR)
perf annotate --symbol=<function_name> --stdio
Branch type filtering (narrow capture to specific branch types):
perf record -j cond,u ./binary # conditional branches only (mispredict candidates)
perf record -j any_call,any_ret,u ./binary # calls and returns only
perf record -j ind_call,u ./binary # indirect calls only
CYCLES = elapsed cycles since previous recorded branch
x86-64 (AMD Zen 4+ LbrExtV2, kernel 6.1+)
Same perf commands as Intel LBR. AMD Zen 4 supports hardware branch filtering
and misprediction flags. Zen 3 BRS is limited (16 entries, no filtering, no
prediction info) — use Zen 4+ for serious LBR work.
AArch64 (ARM SPE branch sampling)
ARM SPE provides statistical branch sampling. For branch misprediction profiling:
# Record branch mispredictions (event_filter bit 7 = 0x80)sudo perf record -e arm_spe/branch_filter=1,event_filter=0x80/ \
-- taskset -c 2 ./target/release/tiny_hot
# Record all branchessudo perf record -e arm_spe/branch_filter=1/ \
-- taskset -c 2 ./target/release/tiny_hot
# Analyze
perf report --stdio --percent-limit=1.0
# View decoded samples
perf script
SPE vs LBR: SPE is a statistical sampler (like Intel PEBS) — it samples
individual operations with rich metadata (addresses, latency, cache level).
It does NOT provide a continuous branch history like LBR. ARM BRBE (ARMv9.2,
FEAT_BRBE) is the true LBR equivalent but is only available on the newest cores.
