# 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.