---
name: uplift
description: Diagnose and fix emule regressions caused by bumping the tt-metal pin (and its bundled tt-umd submodule). Use when a pin bump turns the C++ or TTNN regression red — device-open crashes, JIT-compile errors, hangs, or new data mismatches — and you need to prove the cause and land a faithful emule-side fix.
---

# Uplift: surviving a tt-metal / tt-umd pin bump

When the tt-metal pin moves forward (e.g. a companion change merges to main, or
you re-pin to a newer commit), you import **two** moving parts at once: the
tt-metal source *and* the tt-umd submodule it points at. Either can regress the
emule build because emule substitutes its own runtime (`SWEmuleChip`,
`emulated_program_runner.cpp`) and JIT kernel shims (`include/jit_hw/`) for the
real hardware path. This skill is the methodology for turning a red post-bump
regression into a proven root cause and a minimal, faithful fix.

The governing principle, learned the hard way: **prove it by building and
running, not by reading `git log`.** Pickaxe/`git show`/blame routinely mislead
(moved code, squash merges, shallow submodule object DBs that render a commit as
a whole-tree add). A bisection that compiles and runs an oracle is the only
authority.

## When to invoke

- A pin bump (or `tt-metal-pin.txt` change) makes a previously-green regression
  fail.
- Symptoms after a bump: device-open aborts (`SIGABRT`/`SIGSEGV` during
  `start_device`), `jit_compile_kernel: compiler failed` (`use of undeclared
  identifier ...`), a deterministic hang, or new ATOL/PCC mismatches across many
  unrelated ops.
- You suspect the bundled umd bump rather than tt-metal source, and need to
  isolate which.

For a *single* missing compute shim (one `<op>_tile`), use `/compute-llk-bringup`.
For data-corruption on a kernel that runs without crashing, use `/memory-debug`.
This skill is for **broad** regressions that a pin bump introduced.

## Step 0 — Read the failure correctly, don't trust the label

- **Inspect artifacts, not the check's green/red.** A C++ regression job can show
  "pass" while its result artifact shows aborts — known-failure allowlists and
  classify steps can absorb failures, and exit codes don't always propagate. Open
  the actual run log/artifact and read the per-test verdicts.
- **Classify the failure mode** before chasing — they have different root-cause
  paths:
  - *device-open crash* (fails in the `device` fixture / `start_device`, before
    any op) → a shared runtime/reset/topology path, almost always umd or the
    emule chip.
  - *JIT-compile error* (`undeclared identifier`, header not found) → a jit_hw
    shim drift; the kernel can't compile against emule's headers.
  - *hang* → often a JIT-infra issue (e.g. forking a compiler from a
    many-threaded process), not the op.
  - *data mismatch* → op-correctness; usually `/memory-debug` territory.
- **Per-arch scope.** Supported arches gate the decision; an out-of-scope arch is
  typically allowlist-gated and expected-broken — don't let its churn block a
  bump, but don't silently regenerate its allowlist over a *real* new regression
  either.

## Step 1 — Build a fast, deterministic oracle

Pick the **smallest, fastest** test that reproduces the failure with an
unambiguous signal, and wrap it so it emits exactly `GOOD` / `BAD` / `SKIP`:

- `GOOD` = clean pass.
- `BAD` = the *specific* signature (e.g. a particular abort message + address, or
  the exact compiler error). Match the signature, not just "non-zero exit", so an
  unrelated failure can't masquerade as the bug.
- `SKIP` = build break or any other outcome → maps to `git bisect` 125.

## Step 2 — Bisect: isolate metal-source vs the umd bump

The pin range moves both metal and the umd gitlink, so bisect in two stages.

1. **Metal bisect.** `git bisect start <new-pin> <old-pin>` in tt-metal, then
   `git bisect run` a script that, per commit: updates the umd submodule to *that
   commit's* recorded gitlink, builds **only the oracle's target** (not the whole
   tree), runs the oracle, and returns 0/1/125.
   - If the first-bad commit changes **only the umd gitlink**, the regression
     rides with the umd bump — proceed to the umd bisect.
   - If it's a metal-source commit, the cause is in tt-metal; triage that commit.
2. **UMD bisect.** Pin metal at the first-bad (umd-bump) commit, then
   `git bisect start <bad-umd> <good-umd>` *inside the submodule* and bisect with
   the same oracle, varying only umd. Build breaks on old-umd-vs-newer-metal
   become `SKIP`.

Bisection rules that keep it honest:
- **Hold the emule layer fixed** (the jit_hw headers and any local emule source)
  for the whole bisect — the variable under test is metal+umd, exactly what the
  bump changed.
- **Build the minimal target** so each step is a fast incremental relink.
- **Automate with `git bisect run`** so you don't hand-judge steps.
- Restore all repos (`git bisect reset`, re-checkout the intended pin, resync the
  submodule) when done.

## Step 3 — Prove the boundary and the mechanism

- **Controlled before/after:** build+run the oracle at `culprit^` (GOOD) and
  `culprit` (BAD) with everything else fixed. That's the proof.
- **Read the mechanism from a two-tree diff, not `git show`.** `git show
  <culprit>` can render a whole-tree add in a shallow/grafted submodule; use
  `git diff <culprit^> <culprit> -- <file>` between two checked-out trees.
- **Read the upstream PR the culprit came from.** It is the authoritative spec for
  any emule-side mirror — its diff tells you the exact old→new API or behavior
  mapping to replicate.

## Step 4 — Design the fix (two recurring classes)

Most uplift regressions are one of these.

### A. Behavioral regression in a shared runtime path
Upstream changed a path that emule used to neutralize. *Example shape:* a device
bring-up step that used to dispatch through a per-chip virtual the SW chip
overrode as a no-op now issues an unconditional register write that the emule
memory model can't satisfy.

Fix principles:
- **Preempt at the right layer**, using an existing mode/chip-type signal the code
  already branches on. Gate **strictly** on the emulated case so silicon /
  simulation / other modes are untouched.
- **No magic constants** when a canonical accessor exists; prefer "skip the
  operation for this mode" over "match a hardcoded address".

### B. API-surface drift in the JIT kernel shims (`jit_hw`)
Upstream renamed/refactored a kernel-facing API (an enum collapse, a template
signature change, a moved header) and the emule shim still exposes the old
surface, so kernels fail to JIT-compile with `undeclared identifier`.

Fix principles:
- **Mirror the upstream change exactly** in the shim — same enum/struct/signature
  surface — using the upstream PR diff as the spec.
- **Preserve emule's bodies** (host `memcpy` / no-op / emulated sync). Only the
  *option/signature surface* changes; the emulated semantics stay.
- Migrate **all dependents in the same surface** (the header's call sites, sibling
  headers that reference the renamed symbols) so nothing dangles. Leave genuinely
  independent/older surfaces (e.g. a separate `experimental/` API with its own
  self-contained definitions) alone.
- Keep `.claude/references/structure.yaml` in sync when symbols are added/removed.

## Step 5 — Wire the fix through the repo chain

A fix can span tt-umd → tt-metal → tt-emule. Order and push mechanics matter:

- **Push dependencies before dependents.** If the metal commit bumps the umd
  gitlink to a fix commit, that umd commit must be on its remote *first*, or the
  submodule pointer dangles for CI.
- **Never push without explicit go-ahead**; for tt-emule's own PR, bump
  `tt-metal-pin.txt` to the (pushed) metal fix commit, using the **full** SHA.
- **Re-sync the vendored e2e demo on any pin bump.** The end-to-end model lane
  (`docs/e2e-models.md`) drives an emule-vendored copy of `simple_text_demo.py`
  at `tt-metal/tests/emule/models/test_tt_transformers_text_demo.py`, which
  tracks upstream only as of the pin SHA in its header. When you move
  `tt-metal-pin.txt`, re-run
  `git show <new-pin>:models/tt_transformers/demo/simple_text_demo.py` into the
  vendored file and re-apply its two `# emule:` markers. The demo is not in the
  C++ regression, so this drift is otherwise uncaught until the nightly e2e lane
  runs against the new pin.
- **jit_hw edits need no C++ rebuild.** Shims are compiled at JIT time, so a
  jit_hw change takes effect on the next kernel compile — clear the JIT cache and
  re-run; iteration is fast.

## Step 6 — Verify recovery and prove no regression

- **Oracle before/after** on the built fix: the `BAD` signature is gone.
- **Broad sweep:** run one test per previously-failing file. The headline
  invariant is that the **crash-signature count goes to zero**; PASS count rises
  with no new failures.
- **Triage every residual** into exactly one bucket: (a) caused by the fix — must
  be zero; (b) the original bug — must be zero; (c) a *separate* pre-existing gap
  that was merely unmasked once earlier crashes stopped. A fix that doesn't touch
  op math can't cause a data mismatch — reason from that.
- **Don't conflate a sweep with the curated suite.** A one-test-per-file sweep
  runs the *first collected* test in each file, which is usually **not** what the
  curated regression script selects (it uses `-k`/`::node` subsets). Before
  treating a sweep failure as real, check whether the curated script even
  exercises that node:
  - Map the failing node to the script's exact `run_pytest` args and resolve
    membership with `--collect-only`.
  - **Validate your collection-parsing first.** Verbose pytest config (`-vvs`)
    makes `--collect-only` print a `<Function ...>` tree, *not* `file::node`
    lines — grep for the `<Function ...>` reprs, and confirm your grep matches a
    test you *know* is selected before trusting any zero counts. (Class-based
    tests are `Class::method`; a bare `file::method` nodeid will error.)

## Step 7 — De-scope and track what isn't yours

- A residual that is a **separate pre-existing gap** (e.g. a missing compute-LLK
  shim, a known SIGFPE, an op-correctness mismatch) should be **filed and
  tracked**, not used to block the uplift, and not "fixed" by widening the uplift
  fix's scope.
- If the uplift's root cause is upstream-intended (a legitimate refactor), the
  emule side is what must adapt — the fix belongs in the emule layer
  (umd SW chip / `jit_hw`), not a revert.
- Note any cross-arch implication (a shim/runtime fix for the supported arch often
  also addresses the same root cause flagged for an out-of-scope arch) but don't
  chase the out-of-scope arch in the same change.

## Anti-patterns (consolidated)

1. **Concluding from `git log -S` / `git show` / blame.** They mislead on moved
   code, squashes, and shallow submodules. Bisect (build+run) is authoritative.
2. **Trusting a green CI label.** Read the artifact; allowlists hide aborts.
3. **A range-based guard that swallows real errors.** Gate on the specific
   case/mode, not "anything that would fault".
4. **Intercepting low-level I/O to dodge a high-level behavior change.** Preempt
   the operation at the layer that owns it.
5. **Hardcoding magic values** when a canonical accessor or a mode flag exists.
6. **Pushing a dependent before its dependency** (metal gitlink before the umd
   commit it references).
7. **Reading a one-test-per-file sweep as the curated suite.** Check
   `--collect-only` membership, with a validated parser.

## References

- `/compute-llk-bringup` — for a single missing compute `<op>_tile` shim (the
  common Class-B fix when the drift is one op).
- `/memory-debug` — for data-corruption residuals (Class-C, op math).
- `docs/api-injection-points.md` — where emule intercepts the pipeline
  (helps choose the "right layer" in Step 4A).
- `references/emule-mapping.md` — HW concept → emule strategy vocabulary.
- `BUILD_GUIDE.md` — build/test setup, the targets to build for an oracle, and the
  regression scripts.