otpu-diag
Full hardware diagnostic of an openTPU FPGA card or its Verilator model
TLDR
SYNOPSIS
otpu-diag [--sim] [--dev path] [--mem quick|full] [--only sections] [options]
DESCRIPTION
otpu-diag is the full hardware diagnostic of an openTPU card (or its Verilator board model with --sim). After `pip install -e .` in the FeSens/openTPU tree it is installed as a console script. Unlike otpu-selftest it does not stop at the first failure: it runs every check whose prerequisites passed, marks the others SKIP (naming the failed prerequisite), and ends with a works / does-not-work matrix per section plus diagnosis hints from the pattern of failures. The exit status is 1 when any check failed.Sections are platform (PCIe, driver, ID, configuration, calibration, STATUS errors, temperature, power estimate), regs (read/write patterns, read-only sanity), i2c (when the bitstream exposes I2C: scan the LM73 bus and the PCIe SMBus; read only), mem (per channel: walking data and address bits, random blocks, partial writes, DMA bandwidth, the interleave; --mem full adds a march C- over every byte of both channels), isa (one program per instruction variant, bit for bit against the ISA simulator), system (demo, masked-write and vops programs, cycle counters, --soak), model (only with --model). --only still always runs platform.On a missing device it prints the XDMA / ID failures and hints to run otpu-setup.
PARAMETERS
--sim
Use the Verilator board model instead of hardware (memory tests scaled to the model).--dev path
XDMA device prefix (default `/dev/xdma0`).--mem quick|full
Memory tests. full also runs a march C- over every byte of both channels (default quick).--soak N
Rerun the kernel set N times and count intermittent failures (default 0).--model name
Short name (qwen3, lfm2, qwen35) or a checkpoint directory: run the model section.--tokens N
Tokens to generate with --model (default 8).--only sections
Comma-separated sections besides platform: regs, i2c, mem, isa, system, model.--bw-mib N
Bandwidth test size per channel in MiB (default 256).--power-json file
Vivado power summary used for the estimate.--json path
Also write the report as JSON.
CAVEATS
A real card needs XDMA character devices and a loaded openTPU bitstream. Checks hold the device lock and will not run beside otpu-chat or otpu-serve. --mem full walks all 4 GiB and takes much longer than the default. --model needs transformers and a checkpoint. I2C is read-only and skipped when the bitstream has no I2C pins. Power estimates need a Vivado `power.json` for that bitstream. The command is installed only via `pip install -e .` in the openTPU tree.
HISTORY
otpu-diag is part of the openTPU host tools (Apache-2.0, FeSens). It sits next to otpu-selftest in the README table: selftest stops at the first failure for bring-up; diag keeps going so a bad pinout, a weak DRAM channel, or a wrong bitstream can be told apart from the pattern of PASSes and FAILs.
SEE ALSO
otpu-selftest(1), otpu-setup(1), otpu-smi(1), otpu-chat(1)
