tools: durable BAR0 GR register sampler + analyzer (gr-regs/)

reg_sampler.py: high-rate read-only MMIO sampler for the physical GPU's
PGRAPH/FECS/SKED/PFIFO registers (FECS current-context valid + pointer,
SKED CWD table occupancy/activity, GRFIFO, FE QMD-virt, PMC_ENABLE) with
analyze_regs.py for value distributions and transition timelines. Recorded
ground truth and register semantics in tools/gr-regs/README.md. Used to
capture the live distro-driver CUDA reference (FECS VALID=1, CWD table
0x3f002000 while running) and to observe the ladder's forwarded launch
(CWD entry + SKED processing after the mode-35 lane enable).

1 files changed, 36 insertions, 0 deletions

diff --git a/tools/gr-regs/README.md b/tools/gr-regs/README.md
new file mode 100644
index 0000000..3294742
--- /dev/null
+++ b/tools/gr-regs/README.md
@@ -0,0 +1,36 @@
+# gr-regs - GR/FECS/SKED register ground truth
+
+Read-only BAR0 sampling of the physical GPU's GR state, used to answer
+"what does a working GR launch do to the engine" and "what does our
+forwarded launch actually reach" without instrumenting any driver.
+
+## Files
+
+- `reg_sampler.py` - high-rate read-only MMIO sampler (root required).
+  `sudo python3 reg_sampler.py <seconds> <Hz> <outfile> [label]`
+- `analyze_regs.py` - value distribution + transition timeline for a sample
+  file: `python3 analyze_regs.py <outfile>`
+
+## What the registers mean (TU104)
+
+| Register | Meaning |
+|---|---|
+| `FECS_CURRENT_CTX` / `FECS_NEW_CTX` | FECS context load target: `PTR[27:0] = instance PA>>12`, `TARGET[29:28]`, `VALID[31]`. A channel is engine-current only while `VALID=1` on its instance. |
+| `CWD_TABLE_0..3` | SKED context work-descriptor table. Cold/idle reads `CWD_TABLE_0=0x00002000`; a scheduled QMD shows its group + state (e.g. `0x3f002000`) and `CWD_TABLE_1` carries the QMD id (`QMD VA>>8`). |
+| `SKED_ACTIVITY`, `SKED_HWW_ESR` | SKED processing / first-error latch. |
+| `GRFIFO_STATUS`, `PGRAPH_STATUS` | GR FIFO and engine activity. |
+| `FE_QMD_VIRT_*` | FE QMD virtual-address translation; reads 0 in native use. |
+| `badfxxxx` samples | GPU "bad fence"/clock-gated pattern during driver handoff; filter them out. |
+
+## Ground truth recorded 2026-10-06 (distro 570.211.01, live CUDA)
+
+- CWD_TABLE_0 leaves the cold `0x00002000` and reads `0x3f002000`/`0x3f002400`
+  while CUDA runs.
+- FECS_CURRENT_CTX/NEW_CTX read `0x801f3acb`/`0x801f3edf` (VALID=1) with the
+  active channel's instance PA>>12.
+- FE_QMD_VIRT_CONTROL/BASE stay 0.
+
+These values are the reference for the campaign's forwarded-launch work
+(see `backups/evidence-20261002-victory/`); a forwarded QMD that never
+enqueues leaves `CWD_TABLE_0` at the cold value, one that enqueues shows the
+same class of transitions as the real driver.