# power

Power capture settings: which instrument measures the rail, how it is wired to the board, and which window of the run is integrated.

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/power.json)

Power measurement settings.

**API tier:** `stable`

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`` must agree, or a run could
silently build no monitor while appearing to configure one.

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.

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.

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`` widens the gap most (two sequential
JLinkExe invocations), but every family can reproduce the same
``no_gate_rise`` degradation (issue #114). 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.

---

Machine-readable: [`power.json`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config/power.json) · [`power.md`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config/power.md), complete and lossless.