# User guide

The User guide is organised by what you are doing. Start with a task below, then follow its prerequisites and examples. If
you have not run a profile yet, [Getting started](https://ambiqai.github.io/helia-profiler/getting-started/) is
the shorter path.

## The blocks of a run configuration

Use these configuration blocks to find the guide for your next change.
The generated [configuration reference](https://ambiqai.github.io/helia-profiler/reference/configuration/) lists
all keys and defaults.

| Block | Choose or inspect |
|---|---|
| `model` | [Model format and arena size](https://ambiqai.github.io/helia-profiler/guide/models/), [memory placement](https://ambiqai.github.io/helia-profiler/guide/memory/) |
| `engine` | [Runtime or ahead-of-time compiler](https://ambiqai.github.io/helia-profiler/guide/engines/) |
| `target` | [Board and clock](https://ambiqai.github.io/helia-profiler/guide/boards/), [toolchain](https://ambiqai.github.io/helia-profiler/guide/toolchains/), [transport](https://ambiqai.github.io/helia-profiler/guide/transports/) |
| `profiling` | [Counters and sampling](https://ambiqai.github.io/helia-profiler/guide/pmu-counters/) |
| `power` | [Instrument, wiring and measurement window](https://ambiqai.github.io/helia-profiler/guide/power/) |
| `output` | [Result files](https://ambiqai.github.io/helia-profiler/guide/output/) and [model overlays](https://ambiqai.github.io/helia-profiler/guide/model-explorer/) |
| `timeouts`, `build` | [Stage limits and dependency resolution](https://ambiqai.github.io/helia-profiler/guide/configuration/) |

## Set up a run

- [Engines](https://ambiqai.github.io/helia-profiler/guide/engines/): heliaRT, heliaAOT, TFLM and ExecuTorch: supported model formats, setup and configuration.
- [Models](https://ambiqai.github.io/helia-profiler/guide/models/): The model formats each engine accepts, the tensor arena, and how to size it from a measurement.
- [Boards and targets](https://ambiqai.github.io/helia-profiler/guide/boards/): The board registry, what each SoC family can capture, the CPU clock and custom boards.
- [Toolchains](https://ambiqai.github.io/helia-profiler/guide/toolchains/): GCC, Arm Compiler 6 and the Arm Toolchain for Embedded: install, select, compare.
- [Capture transports](https://ambiqai.github.io/helia-profiler/guide/transports/): RTT, USB CDC, UART and SWO: what each needs plugged in and what it can lose.
- [Memory placement](https://ambiqai.github.io/helia-profiler/guide/memory/): Where the arena and the weights live, how automatic placement decides, and how to tune it.
- [ExecuTorch NS kernels](https://ambiqai.github.io/helia-profiler/guide/executorch-ns-kernels/): Compare the ns and arm providers on a Cortex-M55 using the documented operator measurements.
- [Configuration](https://ambiqai.github.io/helia-profiler/guide/configuration/): How the file and the command line merge, and the behaviour a schema table cannot express.

## Measure

- [PMU counters](https://ambiqai.github.io/helia-profiler/guide/pmu-counters/): Counter groups per SoC, multi-pass capture and overflow detection.
- [Power measurement](https://ambiqai.github.io/helia-profiler/guide/power/): Joulescope wiring, INA228, measurement windows and on-device summaries.

## Read results

- [Output files](https://ambiqai.github.io/helia-profiler/guide/output/): Every file a run writes, its schema and its units.
- [Inference and layer timing](https://ambiqai.github.io/helia-profiler/guide/latency/): Read clean inference timing and instrumented layer costs with the right units and scope.
- [Compare results](https://ambiqai.github.io/helia-profiler/guide/analysis-comparison/): Re-analyse a bundle, compare two runs, and the rules that make a comparison fair.
- [Model Explorer overlays](https://ambiqai.github.io/helia-profiler/guide/model-explorer/): Per-layer cost on the model graph.

## Concepts

- [How hpx works](https://ambiqai.github.io/helia-profiler/guide/concepts/): The pipeline, engine adapters, firmware generation, capture, field diagnostics and how to add an engine, each with a block diagram.