otpu-lens

otpu-lens record -o file [options]otpu-lens open [file] [--port N] [--no-browser]otpu-lens html file -o outotpu-lens info fileotpu-lens list

otpu-lens is the host frontend for Lens, the openTPU profiler. record runs decode (or a kernel workload) with the hardware trace buffer enabled, reads 64-bit TRACE records back, rebuilds them into the same profile JSON the RTL/ISA path produces, and writes an `.otpuprof` file. open, html, info, and list are passed through to `python -m opentpu.lens`.On the card, record tokenizes a prompt, prefills, then traces --tokens decode steps starting at --pos (default: the last prompt token). Each traced step becomes one profile (`kind` hw). If the bitstream has no trace buffer (register map 1), the profile is counters-only (`kind` board). --sim does the same on the Verilator board model: a kernel workload from list (default mlp-small) or qwen-tiny.Lost events are reported in each profile's hwtrace metadata, as notes, and on stdout: TRACE_DROP (capture queue drops) and records that did not fit the buffer. --keep first (default) stops when the buffer is full so the tail is missing; --keep last uses a ring and drops the head. The web UI shows a roofline, a timeline, and per-instruction tables, including a floorplan replay of what each unit is doing each cycle.

record -o, --out file

Profile file to write (required for record).

XDMA device prefix (default `/dev/xdma0`).

Use the Verilator board model instead of a card.

Hugging Face checkpoint for a card recording (default `models/Qwen3-0.6B` in the repository).

Prompt to tokenize (default `What is the capital of France?`).

Comma-separated token ids instead of --prompt (no tokenizer).

Number of steps to trace; one profile each (default 1).

Position of the first traced step (default: last prompt token; qwen-tiny default 3).

When the trace buffer fills: keep the first records or the last (ring).

With --sim: a kernel name from list, or qwen-tiny (default mlp-small).

Serve the profile in the Lens app after writing.

Weight format of the layers / LM head (`int8`, `fp4`, `int4`, and `mix` for layers).

Listen port (default 0, ephemeral).

Do not launch a browser.

record on a card needs XDMA, a bitstream with a trace buffer for full timelines, and the device lock (it will not run beside otpu-chat). A map-1 bitstream yields counters only. Dropped or wrapped traces make the timeline incomplete. Card record uses transformers unless --prompt-ids is given. open / html start a small local HTTP server that serves the profiler page. The command is installed only via `pip install -e .` in the openTPU tree.

Lens is the openTPU profiler: first an RTL/ISA recorder (`python -m opentpu.lens`), then otpu-lens to capture the same profiles from the card's TRACE_CTRL buffer so a run on hardware can be inspected with the same roofline and floorplan views.

otpu-chat(1), otpu-smi(1), perf(1)

Source code · Documentation