tools/cuda-ab: P2 arbitrary-kernel suite expansion (regs/streams/printf), smiley push wiring, near-native perf harness (offline readiness; guest validation pending)

1 files changed, 70 insertions, 0 deletions

diff --git a/tools/cuda-ab/perf/results-template.md b/tools/cuda-ab/perf/results-template.md
new file mode 100644
index 0000000..ce387e9
--- /dev/null
+++ b/tools/cuda-ab/perf/results-template.md
@@ -0,0 +1,70 @@
+# Performance result: <STAMP> — <one-line verdict>
+
+> Copy this file to `open-iov/docs/05-operations/05-performance-results.md` (or
+> append a dated section under the existing results heading) at recording time.
+> Rules: every number below must come from a `perf/results/<stamp>-{host,guest}/`
+> artifact produced by `perf.sh` on a **verified-green** stack; no hand numbers,
+> no re-used runs, no claim without the JSON path. See `perf/PLAN-AND-HARNESS.md`
+> §5–§6 for thresholds and evidence discipline.
+
+## Environment
+
+| Item | Host (oracle) | Guest (vGPU) |
+|---|---|---|
+| Date (UTC) | | |
+| GPU / clocks | | |
+| Driver | | |
+| CUDA toolkit / binary | | |
+| Module sha256 / commit | | |
+| Insmod recipe | | |
+
+## Verification (gate)
+
+| Check | Result |
+|---|---|
+| `victory_mail` MAIL/VADD/STATUS in this boot | |
+| `perf_workload` bad=0 both sides | |
+| Host `/sys/kernel/debug/vgsp/gsp-phys-state` work_gr before→after | |
+| `pending release starved` absent (ISSUE-0001 gate) | |
+
+## Metrics (mean/median/p95 over N runs)
+
+| ID | Metric | Host | Guest | Guest/Host | Threshold | Verdict |
+|---|---|---|---|---|---|---|
+| P1 | init_ms (process start → device) | | | | ≤ 2.0× (doc 3.3) | |
+| P2 | malloc_first_ms / malloc_ms p95 | | | | calibration §4 | |
+| P3 | launch_first_ms (guest-observed) | | | | calibration §4 | |
+| P3h | host GR elapsed_ms (r3 metric) | n/a | 189/166 baseline | | ≤ 1.2× prior | |
+| P4 | launch_warm p50 / p95 | | | | calibration §4 | |
+| P5 | copy HtoD/DtoH small (latency proxy) | | | | ≤ 5× | |
+| P6 | MSI-X injection p95 (host trace) | n/a | | | ≤ 1 ms provisional | |
+| P7 | HtoD GB/s (16 MiB) | | | | ≥ 95% | |
+| P8 | DtoH GB/s (16 MiB) | | | | ≥ 95% | |
+| P9 | kernel_fma ms / GFLOP/s | | | | ≥ 90–95% | |
+| P10 | throughput kps | | | | calibration §4 | |
+| P11 | dispersion p95/median per metric | | | | ≤ 1.5 | |
+| P12 | clock64 kernel cycles (cross-check) | | | | report only | |
+
+## Host-side evidence (from `host-gr-dmesg.txt`)
+
+| Launch (ok) | elapsed_ms | submit→ok ms |
+|---|---|---|
+| | | |
+
+## Regression check
+
+Previous recorded baseline (stamp / artifact): ______________________
+Result: same / better / worse — per-metric notes:
+
+## Conclusion
+
+<One paragraph. State the rung this supports, the limiting metric, and the next
+optimization candidate. Link the compare.json path.>
+
+## Evidence paths
+
+* `open-iov/tools/cuda-ab/perf/results/<stamp>-host/results.json`
+* `open-iov/tools/cuda-ab/perf/results/<stamp>-guest/results.json`
+* `open-iov/tools/cuda-ab/perf/results/<stamp>-guest/compare.json`
+* durable copy: `backups/evidence-<date>/perf-<stamp>/` (campaign evidence home)
+* `handoff-meta-plan.md` §2 delta: appended <date> (see snippet in PLAN §6)