# Config reference (version 2)

Every block and field a `helx run` config may contain. Blocks are strict: an unknown key is an error. Keys starting with `x-` are ignored extension keys. Cross-field rules (exactly one model, one memory choice, engine and backend pairing) live in the schema's validators and are reported by `helx validate config`.

Generated by `scripts/render_references.py` from the models; do not edit by hand.

## `RawPipelineConfig`

A ``version: 2`` config: one run block, defaults, and exactly one model.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `version` | one of `2` | required | Always 2. |
| `run` | block `RawRunConfig` | required | Where the bundle goes and which platform, mode and target the run is attributed to. |
| `defaults` | block `RawDefaultsConfig` | empty block | Settings every model inherits. |
| `models` | list[block `RawModelConfig`] | required | Exactly one model. |

## `RawRunConfig`

``run:`` where the bundle goes and which platform, mode and target the experiment is attributed to.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `results_dir` | str | required | Where the bundle is written, relative to the config. |
| `workspace_dir` | str or null | none | Working directory for the run; a temporary one when omitted. |
| `keep_workspace` | bool | `false` | Keep the workspace after the bundle is written. |
| `keep_debug_artifacts` | bool | `false` | Keep Vela's debug database and other debug outputs. |
| `enable_vela` | bool | `true` | Compile with Vela; false hands the original model to the runtime. |
| `non_vela_tensor_arena_size` | int or null | none | Tensor arena size in bytes when Vela is bypassed. |
| `energy_model` | str or null | none | Energy model YAML to use instead of the one derived from the platform, relative to the config. |
| `platform` | str or null | none | A shipped platform name (helx platform list) or a path to a platform YAML. |
| `platform_mode` | str or null | none | Operating mode of the platform to run in, e.g. ULP or HP. |
| `platform_overrides` | dict[str, Any] or null | none | Timing overrides for this run: memories..{read_latency_cycles, write_latency_cycles, max_outstanding, max_outstanding_writes, burst_length, ports_used, bandwidth, rate_window_cycles}, and sram_port_hash (the address mask that picks the NPU's SRAM port, e.g. 0x80; U85 FVP runs only). |
| `contention` | dict[str, Any] or null | none | Emulated application traffic: .{share_taken (0 to below 1, the fraction of the memory's bandwidth other traffic uses), extra_latency_ns (queueing latency added), rate_window_cycles (timing-adapter window, at least 256; default: the run's own)}, and apply_to_vela (default false: only the FVP sees it; true: Vela compiles for it too). |
| `target` | str or null | none | Which realization of the SoC a measurement is attributed to: a packaged helia-npu target id or a YAML path. |

## `RawDefaultsConfig`

``defaults:`` the vela and fvp blocks a model inherits unless it overrides them.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `vela` | block `RawVelaConfig` | empty block | Vela settings every model inherits unless it overrides them. |
| `fvp` | block `RawFvpConfig` | empty block | FVP settings every model inherits unless it overrides them. |

## `RawVelaConfig`

``vela:`` knobs, at the defaults level or per model.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `arena_cache_size` | int or null | none | Bytes of port 0 memory Vela may use for its weight cache, and for the arena when the arena is on port 0 (Vela's --arena-cache-size). |

## `RawFvpConfig`

``fvp:`` the local runner: whether to build and run, on which subsystem, with which engine and PMU program.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | bool or null | none | Build the local runner; with run, execute it on the FVP. |
| `subsystem` | one of `corstone_300`, `corstone_320` or null | none | Corstone FVP subsystem, corstone_300 or corstone_320. Unset, helx runs the FVP that simulates the platform's NPU: corstone_300 for an Ethos-U55 or U65, corstone_320 for an Ethos-U85. |
| `build_type` | one of `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel` or null | none | Runner build type: Debug or Release. |
| `target` | str or null | none | CMake build target of the runner; defaults to helx_inference_runner. |
| `runtime_engine` | one of `tflite_micro`, `helia_rt`, `helia_aot` or null | none | Inference runtime linked into the runner: litert (tflite_micro), heliaRT or heliaAOT. |
| `helia_rt_backend` | one of `helia` or null | none | heliaRT uses heliaCORE only (helia-core, with helia/ns-cmsis-nn aliases); defaults to heliaCORE. |
| `tensor_io` | block `TensorIOPolicy` or null | none | Fixed-shape input bytes, retained outputs and optional numerical reference comparisons. |
| `acquisition` | block `AcquisitionPolicy` or null | none | Build-time state, warmup and measured-count policy for all three runtimes; explicit policies exclude tracing. |
| `pmu_profile` | one of `default`, `ext_stall`, `default_ext_rd_stall`, `dv_align`, `port_stall`, `sram_stall`, `sram_transactions` or null | none | Which PMU counter set the runner reports: default, ext_stall, default_ext_rd_stall, dv_align, port_stall or sram_stall or sram_transactions (aggregate SRAM accepted transactions plus energy beats). |
| `cmake_args` | list[str] | empty | Extra CMake arguments for the runner build. |
| `build_args` | list[str] | empty | Extra arguments appended to cmake --build, overriding its generated defaults. Main and fenced per-segment runner builds default to up to four parallel jobs, capped at the reported CPU count (one if unknown). Set ["--parallel", "8"] to choose another runner limit. LiteRT's nested dependency and library builds use a separate fixed four-job limit. |
| `run` | bool or null | none | Execute the runner on the FVP after building it. |
| `skip_fvp_download` | bool or null | none | Do not download the FVP; fail if it is missing. |
| `simlimit` | int or null | none | Simulated seconds before the FVP gives up. |
| `host_timeout_seconds` | int or null | none | Wall-clock seconds the host waits for the FVP. |
| `fvp_args` | list[str] | empty | Extra command-line arguments for the FVP. |
| `bus_trace` | block `RawBusTraceConfig` | empty block | Record and summarise the NPU's bus traffic during the run (Corstone-320 only). |
| `helia_aot` | dict[str, Any] | empty | heliaAOT configuration passed through untouched; its shape belongs to helia-aot. |

## `TensorIOPolicy`

Opt-in input binding and output retention for fixed-shape runner tensors.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `inputs` | tuple or null | none | All input tensors, refilled before every invoke; absent explicitly selects zero bytes. |
| `references` | tuple | `()` | One reference set per measured invocation, or empty for capture without comparison. |
| `comparison` | ComparisonPolicy | `ComparisonPolicy(default=Tolerance(absolute=0.0, relative=0.0), per_tensor=(), nan=<NaNPolicy.NEVER_MATCH: 'never_match'>)` | Stored-value tolerances and NaN policy; same-sign infinities match. |

## `TensorLiteral`

One tensor's specification and exact little-endian bytes, independent of external file paths.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `spec` | TensorSpec | required | Model index, name, storage dtype and fixed dimensions. |
| `data_hex` | str | required | Lowercase hexadecimal bytes, without a prefix or whitespace. |

## `TensorReference`

One measured invocation's reference outputs and their declared source.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `tensors` | tuple | required | All reference output tensors in model-index order. |
| `origin` | one of `files`, `host_litert`, `producer` | required | Caller-declared source of the reference values. |
| `description` | str | required | Model, tool/version, dataset or other identifying context for the reference. |

## `AcquisitionPolicy`

Build-time lifecycle controls; None warmup preserves the runner's automatic choice.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `state` | one of `carry`, `single` | `carry` | carry retains variables across invokes; single permits one invoke on the initialized instance. |
| `warmup_invokes` | int or null | none | Uncounted warmup invokes. Unset: carry warms up once when CALL_ONCE is present; single uses zero. |
| `measured_invokes` | int | `1` | Measured invokes on one initialized instance; single requires one. |

## `RawBusTraceConfig`

``fvp.bus_trace:`` record every NPU bus transaction on the FVP and summarise it in the bundle (Corstone-320).

| Field | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | bool or null | none | Trace the NPU's AXI masters during the run; the bundle gets a per-interface timeline, transfer sizes, a Perfetto trace and checks against the PMU. With per_layer fencing on, the fenced run is traced too, and each NPU invocation gets its own traffic (per_segment.bus_trace_csv), checked against its PMU counts. Off by default: the FVP writes a raw trace of about 85 bytes per transaction (tens of MB for a model of a few million cycles) while it runs. |
| `keep_raw` | bool or null | none | Keep the FVP's raw traces in the bundle (artifacts/bus_trace.txt, and artifacts/fenced_bus_trace.txt for the fenced run) instead of deleting them once summarised. |

## `RawModelConfig`

One entry of ``models:``: the model, its memory choice, and per-model overrides of the defaults.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `name` | str or null | none | Model name; defaults to the source file's stem. |
| `source` | str or null | none | The model: a path relative to the config, an http or https URL, or an s3 URI. |
| `memory_modes` | list[str] or null | none | One of Vela's mode names (Sram_Only, Shared_Sram, Dedicated_Sram): an alias for the placement it means on the platform. |
| `memory_placement` | list[Any] or null | none | One entry naming the physical memory for const (weights), arena (activations) and cache (Vela's weight cache). |
| `vela` | block `RawVelaConfig` | empty block | Vela settings for this model, over the defaults. |
| `fvp` | block `RawFvpConfig` | empty block | FVP settings for this model, over the defaults. |
| `per_layer` | block `RawPerLayerConfig` | empty block | Where to cut the model into separately measured segments. |

## `RawPerLayerConfig`

``per_layer:`` where to cut the model into separately measured segments.

| Field | Type | Default | Meaning |
|---|---|---|---|
| `mode` | one of `off`, `per_op`, `per_group`, `explicit` | `off` | off, per_op (a fence after every operator) or per_group (a fence every group_size operators). |
| `group_size` | int | `1` | Operators per segment for per_group. |
| `boundaries` | list[int] or null | none | Explicit operator indices to cut at, instead of a regular grouping. |