Configuration Reference#

This page is generated from the ProfileConfig pydantic dataclasses in src/helia_profiler/config.py — it is the single source of truth for every config key, its type, default, and status. Regenerate it after any config model change with:

uv run python tools/gen_config_reference.py

Unknown keys anywhere in the config tree are rejected at load time with did-you-mean suggestions drawn from these same models — see Configuration for the general validation behavior.

model#

Model file and arena sizing.

arena_location and weights_location are the preferred placement controls for runtime engines such as heliaRT: the arena is the mutable tensor arena, while weights are the model flatbuffer/constant data.

When a split field is omitted, the engine and memory planner choose the
fastest region that fits. ``helia-aot`` translates these coarse controls
into tensor rules; explicit ``engine.config.aot_args.memory.tensors`` rules
remain available for per-kind and per-tensor placement.

engine#

Inference engine selection and passthrough config.

target#

Hardware target.

target.clock#

Per-domain clock speed selection for the generated firmware.

Each field names a speed within the SoC's matching clock domain using Ambiq datasheet terminology (e.g. cpu="hp"). None selects that domain's default speed. Values are validated against the resolved SoC in stage 1, so unknown names raise a clear ConfigError rather than failing silently.

target.heartbeat#

Liveness / progress-reporting settings.

The firmware emits HPX_HEARTBEAT lines at configurable intervals so the host can (a) detect a hung run without using a large wall-clock timeout, and (b) show the user live progress.

profiling#

PMU capture settings.

Counter selection is specified via pmu_counters — a mapping of compute-unit group (cpu, mve, memory) to a selection:

• "default" — curated set of the most useful counters.
• "all" — every counter in the group (multi-pass).
• ["NAME", …] — explicit counter names.

power#

Power measurement settings.

output#

Report output settings.

timeouts#

Subprocess and network timeouts (seconds).

Every subprocess and long-lived HTTP call in heliaPROFILER reads its timeout from this struct instead of hard-coding it. Override any value in YAML under timeouts: to adapt to slow CI machines, laggy J-Link probes, or poor network conditions.

Capture-time timeouts (heartbeat / overall) live on HeartbeatConfig because they are tied to the on-device progress protocol.

build#

NSX build-system overrides.

Controls how the generated firmware's NSX manifest resolves modules. Default behaviour keeps the selected board's default NSX channel, but generated manifests explicitly track main for the neuralspotx and nsx-ambiq-sdk projects unless the user overrides those modules.

Advanced users can pin individual modules to a version, point them at a local checkout, or select a custom git ref — useful for SoC/board bring-up before changes land in the stable channel.

compiler_launcher selects a CMake compiler launcher (e.g. sccache or ccache) that wraps every compile to cache object output and speed up repeated builds. "auto" (the default) uses sccache then ccache if either is on PATH and otherwise does nothing — so the mere presence of the binary is the opt-in. "none" disables it; an explicit tool name or path requires that the launcher be found.

build.nsx_modules.<name>#

Override resolution for a single NSX module.

Exactly one mode must be set: * path — use a local directory as the module source (local: true). * ref — resolve the module's project at a specific git ref/tag. * version — pin the module to an exact version constraint.

Top-level keys#

Top-level immutable configuration for a profiling run.