菜单
Run LLK tests using the test runner agent. Never run pytest directly.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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]
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.