bench: the PC-sampling overhead harness (numbers outstanding)

.gitignore

@@ -90,6 +90,9 @@ shim/perfagent-gpu-fpless
 # `make -C shim nvidia-workload`, needs the CUDA toolkit, and has no extension
 # for the *.so / *.o rules above to catch.
 shim/nvidia/testdata/cuda_workload
+# The CONCURRENT CUDA workload the PC-sampling overhead benchmark is measured
+# against: built by `make -C shim nvidia-concurrent`, same story.
+shim/nvidia/testdata/cuda_concurrent
 bench/cmd/scenario/scenario
 bench/cmd/report/report
 

Makefile

@@ -121,3 +121,27 @@ bench-self: bench-build test-workloads
 		--cpu-budget 1.5 --resolution-budget 0.5 \
 		--out bench-self.json
 	@echo "self-profile bench written to bench-self.json"
+
+# GPU PC-sampling overhead (plan Task 12): the marginal cost of Tier B and of
+# Tier A at three duty fractions, against the shipping Phase 4 configuration
+# with PC sampling off. Needs an NVIDIA GPU, the CUPTI adapter and the
+# concurrent CUDA workload; reports BENCH_SKIPPED and exits 0 without any of
+# them.
+#
+# The capability set is gpuprobe's own and is SMALLER than the one
+# bench-scenarios needs. cap_sys_admin is deliberately not in it.
+#
+# Exit codes: 0 when the measurement completed (whatever the verdict — an
+# honest TIER_A_UNSHIPPABLE is a successful run of this benchmark), 3 when an
+# arm could not prove it ran in the mode it claims, in which case the numbers
+# are not a tier decision and must not be recorded as one.
+.PHONY: bench-gpu-pc-overhead
+bench-gpu-pc-overhead: bench-build
+	@$(MAKE) -C shim nvidia nvidia-concurrent
+	@if ! getcap ./bench/cmd/scenario/scenario | grep -q cap_bpf; then \
+		echo "*** scenario binary missing caps; run: sudo setcap cap_bpf,cap_perfmon,cap_checkpoint_restore+ep ./bench/cmd/scenario/scenario"; \
+		exit 1; \
+	fi
+	./bench/cmd/scenario/scenario --scenario gpu-pc-overhead --runs 5 \
+		--out bench-gpu-pc-overhead.json
+	@echo "gpu pc-sampling overhead written to bench-gpu-pc-overhead.json"

bench/README.md

@@ -19,6 +19,51 @@ Two-layer benchmark for `--unwind dwarf` startup cost. Companion to
 - `system-wide-mixed` — N processes across Go/Python/Rust/Node from
   `test/workloads/`, attached via `-a`. Measures `/proc/*` walk +
   per-PID maps parse + per-distinct-binary compile.
+- `gpu-pc-overhead` — the marginal cost of GPU PC sampling, and the
+  pre-committed thresholds that turn it into a decision. See below.
+
+## `gpu-pc-overhead`
+
+Plan Task 12. Measures the **marginal** cost of PC sampling: the baseline arm
+is the shipping Phase 4 configuration (shim injected, RUNTIME + RESOURCE
+callbacks, `CONCURRENT_KERNEL` activity, 100 ms drain, consumer attached) with
+PC sampling **off**, not an uninjected run. Spec §9.1 already measured
+injection and the activity path, and those costs are paid either way.
+
+Five arms, five interleaved runs each, medians, fixed work rather than fixed
+time:
+
+| arm | duty |
+| --- | --- |
+| baseline (PC sampling off) | — |
+| Tier B continuous | — |
+| Tier A 50 ms / 450 ms | 10% |
+| Tier A 50 ms / 950 ms | 5% |
+| Tier A 50 ms / 1950 ms | 2.5% |
+
+The workload is `shim/nvidia/testdata/cuda_concurrent.cu`: several streams,
+non-trivial kernel durations, genuine overlap. It is a **second** workload, not
+a change to `cuda_workload.cu` — the serial fixture the adapter and the phase
+gate are proven against gives serialization nothing to destroy, so measuring
+Tier A on it would understate its cost. The harness measures the achieved
+concurrency out of the profile and **fails** if the baseline arm is near
+serial or its kernels are microseconds long.
+
+Every arm proves it ran in the mode it claims, from both ends independently —
+the adapter's own report line on stderr and the consumer's counters — and a
+mismatch fails the run rather than contributing a number. Cross-arm, a lower
+duty must open strictly fewer bursts, or the three Tier A arms are one arm
+under three names.
+
+```bash
+make -C shim nvidia nvidia-concurrent
+make bench-build
+sudo setcap cap_bpf,cap_perfmon,cap_checkpoint_restore+ep ./bench/cmd/scenario/scenario
+make bench-gpu-pc-overhead
+```
+
+Exit codes: `0` when the measurement completed (whatever the verdict), `3`
+when an arm could not prove what it measured.
 
 ## First-time setup
 
@@ -55,13 +100,25 @@ The aggregator (`bench/cmd/report/`) reads JSON and produces markdown.
 ## Flags
 
 `bench/cmd/scenario`:
-- `--scenario pid-large | system-wide-mixed` (required)
+- `--scenario pid-large | system-wide-mixed | self | gpu-pc-overhead` (required)
 - `--processes N` (default 30) — fleet size for system-wide
 - `--runs N` (default 5) — iterations
 - `--drop-cache` (default off) — drop page cache between runs (warm-cache by default)
 - `--out PATH` — JSON output path
 - `--workloads-dir PATH` — auto-detected if not set
 
+`gpu-pc-overhead` only:
+- `--gpu-shim PATH` / `--gpu-workload PATH` — the adapter and the concurrent workload
+- `--gpu-iters N` / `--gpu-rounds N` — the fixed work; the calibration pass says
+  when they need retuning for the device in front of you
+- `--gpu-streams N` (4) / `--gpu-blocks N` (16) / `--gpu-threads N` (256) —
+  the concurrency; fewer blocks means more kernels co-reside
+- `--gpu-sync-every N` (4) — device sync cadence; forces concurrency to refill
+- `--gpu-min-concurrency` (1.5) / `--gpu-min-kernel-us` (50) — the guards that
+  refuse to report numbers from a microbenchmark
+- `--gpu-min-bursts` (4) — the floor on bursts per Tier A arm
+- `--gpu-min-calibration-sec` (10) / `--gpu-max-calibration-sec` (120)
+
 `bench/cmd/report`:
 - `--in PATH` (repeatable) — summary mode
 - `--diff A.json --diff B.json` — diff mode