Menu
Run LLK tests using the test runner agent. Never run pytest directly.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Create, extend, debug, and validate Quasar LLK performance tests and their PerfRunType kernel paths. Use when adding perf_[op]_quasar.py, wiring PerfConfig, implementing UNPACK_ISOLATE / MATH_ISOLATE / PACK_ISOLATE / L1_CONGESTION, or investigating implausible Quasar perf metrics and dvalid handshakes.
Create, extend, debug, and validate Quasar LLK performance tests and their PerfRunType kernel paths. Use when adding perf_[op]_quasar.py, wiring PerfConfig, implementing UNPACK_ISOLATE / MATH_ISOLATE / PACK_ISOLATE / L1_CONGESTION, or investigating implausible Quasar perf metrics and dvalid handshakes.
Route gh-aw workflow design/create/debug/upgrade requests to the right prompts.
Convert LLK lib/API tile-size args to ckernel::TensorShape and maintain TRISC TensorShape coverage. Use when adding TensorShape parameters, replacing face_r_dim/num_faces, editing LLK_VALIDATE_TENSOR_SHAPE_*, regenerating tensor_shape_coverage_*.h, or reviewing TensorShape PRs.
Audit LLK code for races on the backend CONFIG register file where differently-named fields share the SAME 32-bit config word — both cross-thread (unpack/math/pack write the same word) and intra-thread (a full-word write clobbers a sibling field the same thread set elsewhere). Use after adding/changing any ALU_FORMAT_SPEC / ALU_ACC_CTRL / ALU_ROUNDING_MODE / STACC_RELU / THCON_SEC* write, any WRCFG_32b/cfg[]= full-word write to a multi-field word, or any cfg_reg_rmw_tensix on a word another thread also touches.
Audit hand-written Tensix/SFPU instruction sequences for missing pipeline-latency padding — where a dependent instruction consumes a multi-cycle-latency result before it is ready and a NOP (or independent-instruction spacing) is required. Use after touching any raw TTI_SFP*/TTI_* sequence, ckernel_sfpu_* kernels, or hand-assembled instruction streams. NOT a cross-thread race — an intra-thread micro-architectural hazard.
| name | run-test |
| description | Run LLK tests using the test runner agent. Never run pytest directly. |
| user_invocable | true |
Wraps .claude/scripts/run_test.sh, which serialises simulator access (flock), kills stale port processes, sets TT_UMD_SIMULATOR_PATH, and exposes count / compile / simulate / run subcommands. Agents and Claude must never call pytest directly.
/run-test <test_file> [--arch <arch>] [options]
Examples:
/run-test test_eltwise_binary_quasar.py --arch quasar
/run-test test_sfpu_square_quasar.py --arch quasar --k Float16
/run-test test_eltwise_binary_quasar.py --arch quasar --rerun
/run-test test_eltwise_binary_quasar.py --arch quasar --compile-only
/run-test test_sfpu_square_quasar.py --arch quasar --no-split
/run-test test_eltwise_binary_quasar.py --arch quasar --maxfail 5
/run-test test_matmul_quasar.py --arch quasar --test-id 'test_matmul_quasar.py::test_matmul[math_fidelity:LoFi-...-format:Float16->Float16-...]'
<test_file> — required, e.g. test_sfpu_square_quasar.py--arch <arch> — quasar, blackhole, wormhole. Required unless inferable (see below)--k <expr> — pytest -k filter (applied to both compile-producer and consumer so the two phases stay aligned)--test-id <id> — single parametrize ID (single-quotes/brackets safe)--maxfail <N> — stop after N failures--rerun — skip compile, simulate only (uses prior compile-producer artifacts)--compile-only — compile-producer only, no simulate--no-split — combined compile+run in one pytest invocation (issue-solver tests)--port <N> — simulator port (default 5556)--timeout <secs> — pytest timeout ceiling (default 600)--progress — manual-debug aid: emit a [progress] <phase>: elapsed=Ns, last_output=Ns ago line to stderr every 30s during compile and simulate. Off by default; pass when you suspect a hang and want to see whether a phase is alive but slow vs. truly stuck. Pair with --progress-interval <secs> to tune.If --arch is not provided, infer in this order:
tests/python_tests/quasar/ → quasar*_quasar.py / *_blackhole.py / *_wormhole.py → use thattest_matmul.py): ask the userParse the test file, arch (or infer), and options.
Pick a subcommand for the script:
--compile-only → compile--rerun → simulate--no-split → run --no-split (combined invocation)run (compile then simulate)Spawn the llk-test-runner agent. Its system prompt covers env setup, script invocation, exit-code diagnosis, and output formatting — just pass the inputs:
Agent tool:
subagent_type: "llk-test-runner"
description: "Run tests: {test_file} ({arch})"
prompt: |
test_file: {test_file}
arch: {arch}
command: {compile|simulate|run|count}
options: {whatever applies from --k / --test-id / --maxfail / --no-split / --port / --timeout}
Relay the agent's verdict to the user. On FAIL or COMPILE_FAIL, suggest /debug-kernel. On ENV_ERROR or HANG, surface the agent's diagnosis and stop — don't auto-retry (the same hang will reappear, and env errors need a human fix).
When run_test.sh detects a silicon hang (exit 5), after killing the
consumer tree and before resetting the device, it runs .claude/scripts/llk_triage.py.
Output appears in the RUN_LLK_TESTS_HANG block as:
--- llk-triage ---
=== LLK TRIAGE ===
Arch: blackhole
Location: 0,0
== Mailbox state ==
Unpacker @ 0x... = 0x000000FF (KERNEL_COMPLETE)
Math @ 0x... = 0x00000000 (incomplete)
...
Hung kernel threads: Math
== Tensix state (per RISC) ==
{ ... PC, soft-reset, status per RISC ... }
--- end llk-triage ---
Standalone use (e.g., to inspect a wedged device manually):
source tests/.venv/bin/activate
python3 .claude/scripts/llk_triage.py --arch blackhole \
[--location 0,0] [--device-id 0]