Skip to content
Skills Library
Programming · Analysis

tt-asserts

/tt-asserts

Turn on assertion checking inside Tenstorrent kernels — lightweight kernel asserts, LLK asserts in the compute library, and the LLK sanitizer — and read back what fired. Use when a kernel produces impossible results, when you suspect a broken assumption about tile dimensions or data formats, or when a run hangs and you want to know whether an assert caused it. A fired assert halts the core and looks exactly like a hang from outside.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Turn on assertion checking inside Tenstorrent kernels — lightweight kernel asserts, LLK asserts in the compute library, and the LLK sanitizer — and read back what fired. Use when a kernel produces impossible results, when you suspect a broken assumption about tile dimensions or data formats, or when a run hangs and you want to know whether an assert caused it. A fired assert halts the core and looks exactly like a hang from outside.

Original author description

Turn on assertion checking inside Tenstorrent kernels — lightweight kernel asserts, LLK asserts in the compute library, and the LLK sanitizer — and read back what fired. Use when a kernel produces impossible results, when you suspect a broken assumption about tile dimensions or data formats, or when a run hangs and you want to know whether an assert caused it. A fired assert halts the core and looks exactly like a hang from outside.

How it works

  1. When to invoke
  2. Surface
  3. Force the state
  4. Output
  5. Traps
Original SKILL.md headings · 104 lines, 671 words
SKILL.md preview
---
name: tt-asserts
description: Turn on assertion checking inside Tenstorrent kernels — lightweight kernel asserts, LLK asserts in the compute library, and the LLK sanitizer — and read back what fired. Use when a kernel produces impossible results, when you suspect a broken assumption about tile dimensions or data formats, or when a run hangs and you want to know whether an assert caused it. A fired assert halts the core and looks exactly like a hang from outside.
metadata:
  tier: kernel
  upstream:
    - repo: tenstorrent/tt-metal
      ref: 058b93d450f21b9b86a6ddf58f6f8f2c7744f8f1
      path: docs/source/tt-metalium/tools/lightweight_kernel_asserts.rst
    - repo: tenstorrent/tt-metal
      ref: 058b93d450f21b9b86a6ddf58f6f8f2c7744f8f1
      path: docs/source/tt-metalium/tools/llk_asserts.rst
    - repo: tenstorrent/tt-metal
      ref: 058b93d450f21b9b86a6ddf58f6f8f2c7744f8f1
      path: tools/setup_llk_assert_env.sh
    - repo: tenstorrent/tt-metal
      ref: 058b93d450f21b9b86a6ddf58f6f8f2c7744f8f1
      path: tt_metal/tt-llk/common/sanitizer/output.h
    - repo: tenstorrent/tt-metal
      ref: 058b93d450f21b9b86a6ddf58f6f8f2c7744f8f1
      path: tt_metal/llrt/rtoptions.cpp
---

# tt-asserts

Three independent assertion mechanisms, one decision. They are folded together
because turning one on without knowing how it reports wastes the run — and
because the reporting paths interact.

| Mechanism | Checks | Enable |
|---|---|---|
| Lightweight kernel asserts | Your own `ASSERT(...)` in kernel code | `TT_METAL_LIGHTWEIGHT_KERNEL_ASSERTS=1` |
| LLK asserts | tt-llk's own assumptions — tile dims, data formats, hardware config, during unpack/math/pack/tilize | `TT_METAL_LLK_ASSERTS=1` |
| LLK sanitizer | Deeper tt-llk invariants, by severity | `TT_METAL_LLK_SANITIZER=1` |

## When to invoke

- A kernel returns impossible values and you want the library's own assumptions
  checked rather than guessing which one broke.
- You want an `ASSERT` in your kernel to actually stop the run.
- A run hangs and you need to know whether an assert caused it.

Not this skill: reading the halted state itself — `tt-triage`. Printing values
rather than asserting on them — `tt-dprint`.

## Surface

```bash
TT_METAL_LLK_ASSERTS=1 pytest <test>
```

Upstream pairs that with `TT_METAL_LIGHTWEIGHT_KERNEL_ASSERTS=1`. Measured on
Wormhole, the pair overflows the dispatch build under ttnn and adds no detail —
`references/llk-asserts.md`.

The sanitizer adds six independent severity toggles —
`TT_METAL_LLK_SANITIZER_{PEDANTIC,WARN,ERROR,FAULT,INFO,INTERNAL}=1`. Each is a
switch, not a threshold, so setting `ERROR` does not imply `FAULT`.

Per-family detail, and what each reports where:
`references/lightweight.md`, `references/llk-asserts.md`,
`references/sanitizer.md`.

## Force the state

The instrumented path is a one-liner upstream ships. **Source it, do not execute
it** — it works by exporting into your shell, and it takes two required paths:

```bash
cd $TT_METAL_HOME && source python_env/bin/activate
source tools/setup_llk_assert_env.sh assert.txt /tmp/tt_dprint.log
TT_METAL_LLK_ASSERTS=1 pytest <your test> > test_output.txt
```

That wires a 5-second dispatch timeout to a triage command, so a silent `ebreak`
becomes three files: the host `RuntimeError`, the device assert dump, and the
DPRINT log. Mechanism in `references/llk-asserts.md`.

## Output

**Nothing is printed at the moment an assert fires.** The macro expands to an
`if` plus a RISC-V `ebreak`: the core halts and enters debug mode, the host waits
on a command-queue completion that never arrives, and what you see is a hang.

Where the diagnosis comes from depends on which reporter is enabled:

| Enabled alongside | What reports the failure |
|---|---|
| Lightweight asserts | `tt-triage.py --run=dump_lightweight_asserts` — callstacks, template params, runtime args, locals |
| Watcher | The assertion message on stderr and in `watcher.log` |
| Neither | Still `tt-triage`, but with less detail |

The sanitizer is the exception: it prints, prefixed `llk::san | <severity> |`.

## Traps

**A fired assert is indistinguishable from a hang.** Dispatch times out, triage
runs, and nothing says "assert" until you look. Any investigation that reaches
for a hang workflow should check the asserts it had enabled before blaming the
NoC.

**Enabling an assert family is not enabling a report.** `TT_METAL_LLK_ASSERTS=1`
on its own gives an `ebreak` with no runtime message, but triage recovers the
assert expression, callstack, template parameters and locals from the ELF, so
the lightweight-asserts pairing that upstream documents is not needed for
detail. Measured on Wormhole n300 the pairing also overflows the dispatch
build under ttnn. Prefer LLK asserts alone; use watcher only if you want the
message on stderr and in `watcher.log`. See `references/llk-asserts.md`.

**The sanitizer will not compile on its own.** With `LLK_SAN_ENABLE` set but
neither LLK asserts nor device print enabled, the build stops with a `#error`.
It is a compile-time dependency, not a silent degradation.

**`setup_llk_assert_env.sh` exports `TT_METAL_DEVICE_PRINT=1`, which does not
exist.** It is not in the `EnvVarID` list and is ignored; printing is enabled by
the `TT_METAL_DPRINT_CORES=all` the script also sets. Do not copy that line out
as if it were the switch — see `tt-dprint`.

**The setup script turns DPRINT on for every core, which collides with watcher.**
DPRINT and watcher share on-chip SRAM. Using watcher as the reporter *and* the
script together silently corrupts both, so choose one reporter.

**`tt-smi -r` is part of the script's timeout command.** It resets the device
after dumping. On a shared host that hits every tenant — know it is there before
running it.
Files in this package (4)
  • SKILL.md 6 KB
  • references/lightweight.md 2 KB
  • references/llk-asserts.md 4 KB
  • references/sanitizer.md 3 KB

Versions

The database has no other skills named tt-asserts.

Database snapshot: 13.11.2026 · package version 46131401ee29 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100tt-review-core
    Shared review contract for all Tenstorrent code review — severity vocabulary, the evidence rule, scope, output shape, and the do-not-flag guards. Use when reviewing any change to a Tenstorrent repository (tt-metal, tt-llk, tt-inference-server, model code), and load it before any domain review skill.
  • 90llk-race-audit-review
    Reviews tt-llk kernel changes for the nine intra-kernel race hazard classes plus stale hardware config across invocations — cfg-word overlap, dataflow CB sync, instruction latency, mailbox sync, MMIO ordering, NoC sync, reconfig stalls, semaphore handshakes, and srcreg bank sync…
  • 100add-project
    Guide the user through submitting a new entry to the Awesome Tenstorrent list. Use when the user wants to add, submit, or propose a project, library, tool, or resource to tt-awesome.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.