Skip to content

Configuration#

ProfileConfig is the frozen, validated configuration object that profile() accepts. It is built once at startup by merging a YAML file with CLI overrides and never mutated afterwards.

YAML users

This page documents the Python dataclasses. If you configure heliaPROFILER via an hpx.yml file rather than calling the API directly, the Configuration Reference is the authoritative, field-by-field YAML schema.

Top-level config#

ProfileConfig #

Top-level immutable configuration for a profiling run.

Sections#

ModelConfig #

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.

EngineConfig #

Inference engine selection and passthrough config.

TargetConfig #

Hardware target.

ClockSelection #

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.

HeartbeatConfig #

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.

Attributes:

Name Type Description
enabled bool

Master switch. When False, no heartbeats are emitted or expected and the host falls back to the legacy line-gap timeout.
every_n_ops int

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.
every_ms int

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.
host_timeout_s int

Maximum time the host will wait without receiving any line from the firmware before declaring the run hung.
overall_timeout_s int | None

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.

ProfilingConfig #

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.

PowerConfig #

Power measurement settings.

OutputConfig #

Report output settings.

TimeoutsConfig #

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.

BuildConfig #

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.

NsxModuleOverride #

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.

Enums#

EngineType #

Bases: StrEnum

Supported inference engine identifiers.

StrEnum so values are interchangeable with raw strings — Jinja templates and YAML configs can compare against the canonical hyphen form ("helia-aot") without manually unwrapping .value.

short_slug property #

short_slug: str

Compact identifier used in case IDs and report tables.

Toolchain #

Bases: StrEnum

Supported cross-compiler toolchains for the profiler firmware.

GCC and ARM_NONE_EABI_GCC are aliases — both resolve to the GNU Arm Embedded toolchain. ARMCLANG is Arm Compiler 6 (Keil), ATFE is the Arm Toolchain for Embedded (LLVM).

Transport #

Bases: StrEnum

Host↔target transport for capture and heartbeat traffic.

OutputFormat #

Bases: StrEnum

Top-level report format emitted by the report stage.

Placement #

Bases: StrEnum

Logical placement region for arenas / weights / model data.

The four logical regions abstract over the SoC physical layout — e.g. Placement.TCM covers DTCM on AP5 and is unavailable on AP3. Engine adapters that emit physical names (heliaAOT's DTCM, ITCM, …) normalise to this enum at the adapter boundary.

PowerMode #

Bases: str, Enum

Power measurement mode.

ResetStrategy #

Bases: StrEnum

User-selectable reset policy for target lifecycle preparation.