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.