feat: add toplev subtool for Top-Down Methodology analysis - #60
Open
atheurer wants to merge 2 commits into
Open
Conversation
Integrates Andy Kleen's pmu-tools/toplev into tool-kernel as a new subtool. Since toplev uses the perf binary under the hood, co-locating it with the perf/turbostat/perf-stat subtools avoids duplicating PMU infrastructure in a separate tool-pmu container. Workshop change: git clones pmu-tools into /usr/local/share/pmu-tools during image build — minimal overhead (Python scripts only, no compile). Subtool command: toplev.py -l3 -I <interval_ms> -x , -a --no-multiplex -l3: three-level Top-Down breakdown (Frontend/Backend-Memory/Core) -x , : CSV output for post-processing --no-multiplex: avoid multiplexing errors on saturated CPUs CDM metrics emitted (system-wide, utilization %): toplev:frontend-bound toplev:backend-bound toplev:memory-bound ← key metric: confirms cache/mem stalls toplev:core-bound ← key metric: confirms execution unit stalls toplev:bad-speculation toplev:retiring Usage: --subtools toplev --subtools turbostat,perf-stat,toplev --interval 3 Requires bare-metal host with hardware PMU access. AI-assisted-by: Claude Sonnet 4.6
LLC-load-misses is not supported on AMD EPYC (returns <not supported>).
Replace with stalled-cycles-backend and stalled-cycles-frontend which
are generic hardware aliases that work on both Intel and AMD:
AMD Zen 4: stalled-cycles-backend = event=0x87,umask=0x01
stalled-cycles-frontend = event=0x87,umask=0x02
These metrics directly answer the memory-bound vs core-bound question:
backend-stall-rate = stalled-cycles-backend / cycles * 100
frontend-stall-rate = stalled-cycles-frontend / cycles * 100
A high backend-stall-rate with low cache-miss-rate (as observed on AMD
EPYC Genoa) points to memory ordering stalls, TLB pressure, or store
buffer conflicts — not L3 cache capacity misses.
AI-assisted-by: Claude Sonnet 4.6
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Integrates Andy Kleen's pmu-tools/toplev into tool-kernel as a new
toplevsubtool, alongside the existingturbostat,perf, andperf-statsubtools.Motivation
When investigating uperf TCP stream throughput variability on AMD EPYC (Genoa), we confirmed via
perf-stat(PR #59) that IPC drops from ~0.65 to ~0.27 during low-throughput 3-second intervals — same instruction count, 2.4× more cycles. This is execution stalls. To determine whether those stalls are memory-bound (cache misses) or core-bound (execution unit pressure), we need Top-Down analysis which perf-stat alone can't provide.toplevdirectly answers this withmemory-bound %andcore-bound %.Why in tool-kernel (not tool-pmu)?
toplevcallsperf statunder the hood — the sameperfbinary that tool-kernel already builds from source. Co-locating them avoids duplicating PMU infrastructure. The only additional workshop dependency is agit cloneof pmu-tools (Python scripts, no compilation).Stacks on PR #59
This branch includes the perf-stat subtool from PR #59 plus the toplev addition. Should be rebased/merged after #59 lands.
CDM metrics
toplev:frontend-boundtoplev:backend-boundtoplev:memory-boundtoplev:core-boundtoplev:bad-speculationtoplev:retiringUsage
🤖 Generated with Claude Code