Wire protocol#

Every line the profiler firmware puts on a transport, and the one command the host writes back, generated from the registry in helia_profiler.wire. tests/contracts/test_wire_protocol.py renders the firmware templates across a matrix of SoCs, transports, engines and binaries and asserts that what they emit is exactly what this page says.

How to read the tables#

• Scope — which engines emit the token. all means every engine.
• Condition — the firmware render gate. always means the token's source is in every build within its scope. This is a template condition: the dedicated power binary compiles hpx_printf to a no-op, so a token whose source is present there still prints nothing (see the power-binary rule below).
• Consumer — what on the host reads it. unconsumed means firmware emits it and nothing currently reads it: honest provenance, not a bug.
• Criticality — protocol breaks capture or a verdict, metric silently degrades a reported number, diagnostic costs only diagnosability.

The power-binary rule#

hpx_printf compiles to an empty function when the dedicated power binary is built, so that binary emits only the power terminal record. Every transport-stream token below is either excluded from its source or present and silent there.

Sentinels#

Frame the stream. The parser ignores everything before the start sentinel and stops at the end sentinel.

Handshake lines#

Valueless lines that coordinate host and firmware around attach and model upload.

Metadata keys#

HPX_<KEY>=<value> lines under the start header, parsed by ^HPX_(\w+)=(.+)$ into a key/value map with the key lower-cased.

Indexed metadata keys#

One printf format, one line per index — heliaAOT reports per-input and per-output sizes where the other engines report one static key.

Records#

Token-then-payload lines. The space after the token defeats the key/value regex, so these reach no consumer.

Heartbeat phases#

HPX_HEARTBEAT phase=<phase> … progress records. Any heartbeat refreshes the host's inactivity deadline; only clean_window_begin carries data the host acts on.

Error codes#

HPX_ERROR=<code> …. The host raises on the first one it sees, with a code-specific hint where it has one.

Warning codes#

HPX_WARN=<code> …. Non-fatal; the run continues.

Power terminal record#

The dedicated power binary's entire output: a versioned envelope between its own start/end markers, optionally carrying an on-device measurement payload, preceded by monitor diagnostics the envelope parser ignores.

Power terminal key groups#

The envelope's required fields must all be present or the record is rejected. The measurement fields are an all-or-none group, emitted only for a successful window read from an on-target monitor.

• Required: HPX_POWER_COMPLETED_COUNT, HPX_POWER_ELAPSED_US, HPX_POWER_ERROR_CODE, HPX_POWER_FINAL_PHASE, HPX_POWER_GATE_ASSERTED, HPX_POWER_GATE_LOWERED, HPX_POWER_REQUESTED_COUNT, HPX_POWER_STATUS, HPX_POWER_TERMINAL_VERSION
• Optional (all-or-none): HPX_POWER_BUS_VOLTAGE_UV, HPX_POWER_CALIBRATION_ID, HPX_POWER_CHARGE_NC, HPX_POWER_ENERGY_NJ, HPX_POWER_MEASUREMENT_COUNT, HPX_POWER_MEASUREMENT_DURATION_US, HPX_POWER_MEASUREMENT_OVERFLOW, HPX_POWER_MEASUREMENT_SCOPE, HPX_POWER_MEASUREMENT_SOURCE

CSV body#

The per-layer rows between two iteration sentinels carry no HPX_ token of their own. Every engine prints the same header shape — "Layer","Op", one quoted column per enabled counter, then "overflow" — and differs only in how the Op column identifies a layer. Counter columns fall back to the raw event id ("0x%04lx") when a pass supplied no name, and parts without an Armv8-M PMU print the single cycle counter as "ARM_PMU_CPU_CYCLES".

• tflm — rows are <index>,<tag>,<counters...>,<overflow>; the tag is TFLM's per-op tag string (or ?).
• helia-rt — Identical to tflm — same template, same profiler class.
• helia-aot — rows are <index>,<OP_TYPE>:<op_id>,<counters...>,<overflow>; the operator id disambiguates repeated op types.
• executorch — rows are <index>,OPERATOR_CALL|DELEGATE_CALL:c<chain>i<instr>,<counters...>,<overflow>.

Heartbeat phases#

The complete phase vocabulary — see the table above for which engines emit which, and when: clean_window_begin, init, allocate, allocated, model_init_done, infer, warmup_done, flushing.

Documented gaps#

These are true of the shipped protocol and recorded rather than silently fixed; changing any of them changes wire bytes.

• ExecuTorch's HPX_ARENA_SIZE counts only the planned arena — its method and temporary arenas are excluded, so the figure is not comparable with TFLM's single-arena number.
• Every profile build's clean_window_begin heartbeat carries a real duration statement: infer windows announce a measured warm-inference estimate (both window modes), and busy-loop windows announce window_target_ms itself as a compile-time constant — the busy loop is calibrated to fill exactly that, and the iteration count drives nothing inside it (#170). The hardcoded est_ms=0 survives only in dedicated power binaries, where hpx_printf compiles to a no-op and the host times the capture from its planned duration — no listener exists, and the power arm is the template's first branch in both window modes, so no power render measures anything pre-window. A runtime est_ms=0 can still appear on an infer window if the measurement degrades (DWT frozen through every warmup by a debugger-attach transient); the host then reads 0 as 'no estimate' and keeps its flat heartbeat timeout. Byte-stream transports (RTT/SWO/UART, via collect_lines) hold an announced budget as a floor on their inactivity deadline until it expires; USB CDC raises its overall capture deadline instead, and its 300 s per-read line gap is not widened — a silent window longer than that is cut short on USB CDC regardless of the announce. Both derive the budget from window_budget_s, capped at WINDOW_BUDGET_CAP_S. A busy-loop announce carries iters=1 — the window completes exactly one busy pass, and on a lossy transport that drops HPX_CLEAN_INFER_COUNT the iters fallback feeds the gate-duration check, which a planned inference count the window never runs would fail as a duration mismatch. (Per-inference energy is never derived for busy windows — the summary omits it by probe.)
• HPX_VERSION is checked against the expected protocol version and then discarded: it never reaches FirmwareMeta or summary.json.
• HPX_CONST_BLOB_LOADED region=… size=… looks like a metadata key but is space-separated, so the generic key/value regex never matches it and it reaches no consumer.
• HPX_ERROR= and HPX_WARN= lines also satisfy the generic key/value regex, so the parser incidentally stores the payload of the last one under the keys error and warn. Nothing reads them.