# config The run description: what to profile, on what, how, and what to write out. Every field of a YAML config file lands in one of these. Every name on this page is imported from `helia_profiler`. **API tier:** `stable` Generated from the `src/helia_profiler` tree `fe269596788d6ab1604cf433559e96b5f48c1d13`. [Machine-readable model](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config.json) 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. **API tier:** `stable` Top-level report format emitted by the report stage. **API tier:** `stable` 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. **API tier:** `stable` Inference engine selection and passthrough config. **API tier:** `stable` 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. **API tier:** `stable` Master switch. When ``False``, no heartbeats are emitted or expected and the host falls back to the legacy line-gap timeout. Emit a heartbeat after this many profiled ops. ``0`` disables this trigger. Lower values add more PMU/inter-op overhead but give finer-grained progress. Emit a heartbeat when at least this many wall-clock milliseconds have elapsed since the last heartbeat. ``0`` disables this trigger. Useful for engines with a single large invocation (e.g. AOT command streams) where ``every_n_ops`` does not fire. Maximum time the host will wait without receiving *any* line from the firmware before declaring the run hung. Hard ceiling on total capture time, in seconds. ``None`` means unbounded (rely on heartbeats). Set to a positive int for a safety net in CI or unattended runs. 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. **API tier:** `stable` Hardware target. **API tier:** `stable` PMU capture settings. Counter selection is specified via *pmu_counters* — a mapping of compute-unit group (``cpu``, ``mve``, ``memory``, ``ethos_npu``) to a selection: * ``"default"`` — curated set of the most useful counters. * ``"all"`` — every counter in the group (multi-pass). * ``["NAME", …]`` — explicit counter names. The ``ethos_npu`` group samples the Ethos-U NPU's own PMU (NPU cycles, MAC activity, SRAM/external bus beats) and requires an NPU-equipped board plus ``engine.backend: ethos_u`` (engine.type helia-rt or helia-aot). **API tier:** `stable` Report output settings. **API tier:** `stable` NSX build-system overrides. Controls how the generated firmware's NSX manifest resolves modules. Default behaviour keeps the selected board's default NSX channel, and generated manifests pin the qualified compatibility baseline's full commit SHAs 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. Ordinary profiles reuse a structurally compatible ``nsx.lock`` byte for byte and always materialize with frozen sync. ``update_dependencies`` is the only mode that intentionally advances refs. ``offline`` additionally requires the exact lock and all locked module trees to already exist. **API tier:** `stable` Top-level immutable configuration for a profiling run. **API tier:** `stable` The clean-window target the firmware is actually built with. ``profiling.window_target_ms`` is raised to a power-usable floor only in ``window_mode: auto`` -- ``fixed`` means "use my number". This is a derived property rather than a helper each caller re-implements, because the rule spans two config sections and every caller (firmware render, power planner) must agree on the same effective value (#136). --- Machine-readable: [`config.json`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config.json) · [`config.md`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config.md), complete and lossless.