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.

effective_window_target_ms property #

effective_window_target_ms: int

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 had drifted into three hand-rolled copies, one of which disagreed: the firmware render used the mode-gated form while the power planner clamped unconditionally, so a fixed window shorter than the floor produced a plan describing a 5 s window against firmware built to spin for 1 s. That is invisible under the default auto, which is why nothing caught it (found by review of #136).

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.

monitor_selected property #

monitor_selected: bool

Whether generated power firmware talks to an on-target monitor.

The single source of truth for both firmware gates: NSX module selection in firmware/__init__.py and render-context derivation in PowerMonitorContext.from_config. When these two used separate predicates and disagreed, runs silently built no monitor at all while appearing to configure one.

gated_external_capture property #

gated_external_capture: bool

Whether this run asks for host-gated external power capture.

The single source of the predicate that gates every piece of GPIO sync machinery: the firmware's kPowerSyncEnabled (via SyncContext.power_sync_enabled and the NSX GPIO module selection in firmware/__init__.py) and the host-side lock-step default below. Internal (on-device monitor) mode measures inside the firmware and has no host poller to race, so it is excluded.

lockstep_wiring_available property #

lockstep_wiring_available: bool

Whether the board carries the two extra lock-step wires.

state (device -> host) and go (host -> device); 0 means the wire is not assigned. Single-sourced because three consumers ask the same question and must agree: the lock-step default (:attr:lockstep_resolved), the power.lockstep: true config validator, and the no_gate_rise diagnostic, which only names lock-step as the likely fix when the wiring can actually support it.

lockstep_resolved property #

lockstep_resolved: bool

Effective 3-wire GPIO lock-step decision for this run.

An explicit power.lockstep always wins -- auto-enable is a default, never an override, so lockstep: false still forces the free-running path for bring-up on incomplete wiring.

Left unset, lock-step is enabled whenever the board is wired for it and gated external capture is requested. The hazard it closes is not family-specific: without lock-step kSyncLockstep bakes false, hpx_sync_wait_go() compiles to a no-op, and the target free-runs its measured window straight out of reset. Any reset latency the host spends after that -- flash-tool exit, JLinkExe teardown, poller start-up -- races the gate. Apollo5's default debug_reset+swpoi_reset makes the gap widest (two sequential JLinkExe invocations; see the AP510 combo+RTT t2-gate-race investigation, which is why the rule was originally AP5-only), but Apollo4 Blue Plus reproduced the same no_gate_rise degradation on a single-invocation debug_reset with a ~5 s window (issue #114), and Apollo3 differs only in how narrow the gap is. So the condition is the wiring and the mode, not the SoC family.

This is the one place both the firmware generator (which bakes kSyncLockstep in at build time, via FirmwareRenderContext) and the host-side capture path (which must arm/wait/signal accordingly) resolve the same answer -- callers must not read :attr:lockstep directly.

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, 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.

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.

Only applies to modules NSX resolves itself (e.g. nsx-core, nsx-ambiq-bsp). Engine-provided modules (nsx-helia-rt, nsx-cmsis-nn) are configured through engine.config (dist_path/source_path/source/cmsis_nn_path/cmsis_nn_ref) instead — an entry here targeting one of those names is ignored with a warning.

Compatibility baseline#

CompatibilityBaseline dataclass #

CompatibilityBaseline(schema: str, schema_version: int, baseline_id: str, neuralspotx_package: str, neuralspotx_version: str, neuralspotx_sha256: str, projects: tuple[CompatibilityProject, ...], modules: tuple[CompatibilityModule, ...], engines: tuple[CompatibilityEngine, ...])

Validated, immutable baseline loaded from HPX package data.

fingerprint property #

fingerprint: str

Return the canonical SHA-256 identity reserved for Stage 5.

to_dict #

to_dict() -> dict[str, Any]

Return a stable JSON-safe representation for reports and Stage 5.

CompatibilityResolution dataclass #

CompatibilityResolution(baseline: CompatibilityBaseline, qualification: QualificationState, module_overrides: tuple[str, ...] = (), engine_overrides: tuple[str, ...] = ())

Resolved baseline plus explicit override classification.

to_dict #

to_dict() -> dict[str, Any]

Return structured result provenance without lossy enum conversion.

load_compatibility_baseline #

load_compatibility_baseline(path: Path | None = None) -> CompatibilityBaseline

Load and strictly validate an HPX compatibility baseline.

Enums#

QualificationState #

Bases: StrEnum

Compatibility state of a resolved profiling configuration.

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.

wire_name property #

wire_name: str

Identifier the firmware emits on the wire (HPX_ENGINE=).

The wire protocol predates the hyphenated config spelling and uses C-identifier-safe names, so helia-aot goes out as helia_aot. Owned here rather than derived inline at the render boundary so the two spellings cannot drift apart.

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.