verify-mock

/verify-mock — Verify your mock before declaring done

You've implemented a mock for a silicon API in tt-emule. Before declaring it complete, walk this checklist. Skipping any step is how regressions creep in.

Invoke from /implement-mock Step 4 or /compute-llk-bringup PCC triage, or directly when finishing up a mock.

Pre-implementation

• Confirm you ran /arch-lookup "<silicon_function>" and have the

authoritative HW spec.

• Confirm you picked a Strategy (A/B/C — see /implement-mock Step 2)

and which kernel-API layer (layer-1 / 1.5 / 2 / 3, per docs/kernel-api-layers.md) the mock targets.

• If the spec is arch-specific (WH vs BH vs QSR), confirm which arch

the target test uses (TT_EMULE_ARCH=blackhole|wormhole|quasar).

• Check no existing mock already covers the same surface (avoid

duplicates / conflicting overloads).

Implementation

• The mock signature exactly matches silicon's signature (template

params, defaults, return type). Mismatches cause silent ADL surprises.

• Real math (not a no-op) if the test will check PCC against torch.

No-op stubs are only OK for HW pipeline state (UNPACK/MATH/PACK config calls).

• Format-aware path for bf16 vs fp32 vs uint16 vs Bfp8b vs Bfp4b if

the API reads/writes a CB. Use the enum-driven predicates (__emule_compute::cb_is_32bit_format(cb_id) and siblings) — never page-size heuristics (see docs/cb-dataformat.md).

• Use __emule_nfaces::rowmajor_to_nfaces[] on CB reads/writes —

emule DST is row-major, CB tiles are face-packed.

• If touching DST: call __emule_dst_check(idst, "name") early and

__emule_dst_mark_dirty(idst) on writes.

• If the silicon impl has multiple template variants (e.g.

<BroadcastType bcast_type>), all variants are supported (use if constexpr to dispatch).

• Comment cites silicon source (DeepWiki page, Confluence page, or

tt_llk_*/...:line) for non-obvious choices.

Build + sanity

• Build passes (only when you touched emulated_program_runner.cpp

or other runner sources):

  cmake --build ${TT_METAL_DIR}/build_emule -j$(nproc)

• Wipe per-test JIT temp dirs before testing:

  rm -rf /tmp/tt_emule_jit_* /tmp/tt_emule_src_*

The persistent disk cache at /tmp/tt_emule_jit_cache_* is hashed and self-invalidates on header content change; per-test temp dirs at /tmp/tt_emule_jit_*/ need an explicit wipe.

Verification

• Sentinel test passes — your project's smallest end-to-end

emule test that exercises the JIT compile + dispatch path.

• Target test reaches the new mock (verify with

TT_EMULE_KEEP_JIT_TEMP=1 + grep the patched kernel.cpp / wrapper.cpp under /tmp/tt_emule_jit_*/).

• Target test passes (or PCC improves above its threshold).
• tt-metal regression matches the recorded baseline:

  TT_METAL_DIR=<tt-metal-checkout> bash scripts/run_regression_wormhole.sh   2>&1 | tee /tmp/rg-wh.log
  TT_METAL_DIR=<tt-metal-checkout> bash scripts/run_regression_blackhole.sh  2>&1 | tee /tmp/rg-bh.log
  TT_METAL_DIR=<tt-metal-checkout> bash scripts/run_regression_quasar.sh     2>&1 | tee /tmp/rg-qs.log

Run the three sequentially (shared JIT cache). Any test that previously passed and now fails blocks ship; consult .github/known-failures-quasar.txt for the QS allowlist.

• Coverage came from an existing tt-metal test, not a new one.

Prefer fixing the mock so a canonical tt-metal test passes over authoring a test. A new tt-metal test is a last resort; when genuinely unavoidable it must live under `tests/emule/` (e.g. tests/emule/ccl/), formatted to tt-metal's pre-commit config (black line-length 120, isort, autoflake), wired into the emule pytest runner (scripts/run_ttnn_pytests_*.sh), with the pin bumped to the companion commit. See the CLAUDE.md project rule.

Documentation

• If you added a new strategy / pattern, append to

.claude/references/emule-mapping.md (the catalog) and link from /implement-mock Step 2 (the strategy taxonomy).

• If you discovered a HW-spec-vs-emule-mock divergence the test

doesn't catch, note it in the commit message and in any relevant docs/<subsystem>-emulation.md.

Common gotchas

• No-op stub compiles but produces zero/garbage at runtime. Add

real math even if "obvious" — recip_tile returning 0 is harder to debug than recip_tile undefined.

• Template parameter mismatch with silicon signature. Causes

"no matching function" errors that look like the mock isn't found. Always copy the silicon signature exactly, then maybe add defaults.

• `#ifdef __EMULE_JIT_MODE` placed inside a `#if defined(COMPILE_FOR_)`

block.** Both run; the inner one wins. Make sure the gate is at the right level — usually OUTSIDE the per-RISC guard.

• Allowlist-add poisons sentinel. If the op's op.hpp doesn't

compile under TRISC (even if your test only uses BRISC), the whole allowlist breaks. The sentinel run catches this.

• `tt_l1_ptr`, `VALID`/`INVALID` undefined. These come from

dataflow_api.h (tt_l1_ptr) and hostdevcommon/common_values.hpp (VALID/INVALID). Both must be #included for any code path that uses them — silicon path may pull them transitively, emule may not.

• `compute_kernel_hw_startup` redefinition. Both

jit_kernel_stubs.hpp and api/compute/compute_kernel_hw_startup.h define overloads. Use the __EMULE_COMPUTE_KERNEL_HW_STARTUP_DEFINED guard pattern (first-included-wins).

Anti-checklist

These are NOT done criteria — don't get hung up:

• Bit-exact match with silicon output. PCC > test's threshold

(~0.998) is the bar.

• Real sfpi:: SIMD math (the shim provides types only).
• Fabric / multichip semantics (out of scope).

Related skills

• /implement-mock — end-to-end workflow (this checklist is its

Step 4 in expanded form).

• /compute-llk-bringup — specialization for LLK compute shims.
• /memory-debug — when verification fails with PCC < threshold or

ATOL mismatch (partial zeros, off-by-N writes).