# Targets

A target describes the compiler's view of the hardware: core, capabilities,
clock choices, memory capacities, preferred placement order and alignment.
Select it with `platform.name`; choose build-system integration separately with
`module.type`.

```sh
helia-aot list-targets
helia-aot target-info --name apollo510_evb
```

Names are case-insensitive, with lowercase canonical spellings. The
[Targets reference](https://ambiqai.github.io/helia-aot/reference/targets/) is generated from the registry
and contains the full values for each platform.

## The families

| Family | Core | Platforms |
| --- | --- | --- |
| Apollo3 | Cortex-M4 | `apollo3_evb`, `apollo3p_evb`, `apollo3_blue_evb`, `apollo3_blue_plus_evb`, `apollo3_blue_thin_evb` |
| Apollo4 | Cortex-M4 | `apollo4p_evb`, `apollo4l_evb`, `apollo4p_blue_kbr_evb`, `apollo4p_blue_kxr_evb`, `apollo4l_blue_evb` |
| Apollo330 | Cortex-M55 | `apollo330mp_evb` |
| Apollo510 | Cortex-M55 | `apollo510_evb`, `apollo510b_evb`, `apollo510l_evb` |
| Atomiq | Cortex-M55 with Ethos-U85 | `atomiq110` |

A registry entry is not a promise that every firmware format and toolchain has
been exercised on that board. See [build coverage](https://ambiqai.github.io/helia-aot/guide/toolchains/#status).

## What a target changes

**Kernel selection.** Operator candidates use target capabilities to determine
which implementations are applicable. The compiled kernel library also has CPU
and feature flags; changing platform metadata alone does not rebuild that
library or configure silicon. See
[kernel selection](https://ambiqai.github.io/helia-aot/guide/how-it-works/#kernel-selection).

**Float support.** Operators requiring native FP16 consult `supports_fp16`.
An explicit FP16 capability is accepted unless it contradicts a known
incompatible CPU. When the capability is absent, a normalized `cortex-m55` CPU
still provides a compatibility fallback. Removing `FP16` from a Cortex-M55
capability list therefore does not disable all FP16 lowering.

FP16 storage is a separate concern: some copies and software
FP16-to-FP32 widening do not require native FP16 computation. Read
[Precision](https://ambiqai.github.io/helia-aot/guide/precision/) before inferring support from tensor
width alone. FP32 has no equivalent platform gate.

**Memory planning.** Capacities and preferred order guide allocation and tensor
rules. They do not install linker sections or reserve memory for your
application: a capacity is the total a program links into (on Apollo510 EVBs,
the linker script's 496 KB MCU_TCM and the MRAM after the bootloader). Leave
your application's share with a
[`max_size` constraint](https://ambiqai.github.io/helia-aot/guide/memory-placement/#constraints).
Only `apollo510_evb` currently declares PSRAM in the registry. Module-specific
placement hooks and your firmware linker configuration must realize the plan;
check the map file after linking.

## Overriding a platform

A registered name selects its registry definition. `platform.memories`
replaces the sizes of memories the target has, for that conversion only, for
a board variant whose sizes differ; a size above the registered one is logged,
and a memory the target lacks is an error. Other `platform` fields
such as `capabilities` or `min_alignment` do not override it: the converter
ignores them and warns about configured overrides.

For an application budget or stronger arena alignment, retain the registered
target and use memory constraints. This example gives the model at most 8 MiB
of the Apollo510 entry's PSRAM and a 32-byte alignment floor in that bank:

```yaml
platform:
  name: apollo510_evb
memory:
  constraints:
    - name: psram
      max_size: 8388608
      arena_alignment: 32
```

These are model allocation constraints, not PSRAM initialization or linker
configuration. See [memory constraints](https://ambiqai.github.io/helia-aot/guide/memory-placement/#constraints)
for their scope and the report checks to perform.

To change the hardware definition itself, use an **unregistered** lowercase
name and supply every required custom-platform field. This complete example
copies the Apollo510 entry's hardware values and chooses a stricter minimum
alignment; it does not inherit anything from the registry:

```yaml
platform:
  name: apollo510_custom
  cpu: cortex-m55
  speeds: [96, 250]
  memories:
    mram: 4128768
    sram: 3145728
    dtcm: 507904
    itcm: 262144
    psram: 32940032
  preferred_memory_order: [dtcm, sram, mram, psram]
  min_alignment: 32
  capabilities: [mcu, usb, psram, dsp, mve, fp16]
```

Review the complete definition against the actual board before adapting it.
An unregistered name without CPU, nonempty speeds/memories/preferred order and
minimum alignment fails during target resolution. `capabilities` must describe
the features the hardware really supplies. A custom name is conversion-local;
it is not added to `list-targets`.

| Field | Meaning for a custom definition |
| --- | --- |
| `name` | Unregistered name; registered names instead select the registry entry. |
| `cpu` | Core name, such as `cortex-m55`. |
| `speeds` | Declared clock speeds in MHz; conversion does not set the hardware clock. |
| `memories` | Complete region capacities in bytes. |
| `capabilities` | Available MCU, DSP, USB, BLE, MVE, PSRAM, FP16 or NPU features. |
| `preferred_memory_order` | Memory preference when a placement rule does not name a region. |
| `min_alignment` | Power-of-two pointer alignment floor. |

CLI `--platform.memories` merges entries with the YAML configuration mapping,
and on a registered target the result resizes the memories it names for that
conversion (see [Overriding a platform](https://ambiqai.github.io/helia-aot/guide/targets/#overriding-a-platform)). Kernel experiments requiring
a different capability set need a complete custom definition, or an explicitly
registered Python platform. Keep declarations truthful and record the kernel
library's CPU/build flags as well.

Native FP16 support still falls back to a normalized `cortex-m55` CPU when a
custom definition omits `fp16`; an empty list does not force a scalar/FP32-only
path. Generated section hooks also depend on module format and platform family,
so review them and the linker map when using a custom name.

Python users can register platforms through `helia_aot.platforms`; explicitly
registered names become discoverable through `list-targets` and subsequently
resolve to their registered definition.

## Ethos-U

For accelerator deployment, first compile a supported model with Arm Vela.
heliaAOT does not invoke Vela. It consumes the resulting LiteRT model, lowers
`ETHOS_U` nodes into driver calls, and leaves non-accelerated nodes on ordinary
paths. The command stream and base-address tensors are part of the generated
module; supported offline allocation offsets and 16-byte alignment are
preserved.

`atomiq110` declares an Ethos-U85-256 and is the registered target with `NPU`.
That target entry describes hardware; it does not establish U85 execution
qualification.

The generated accelerator code requires the Ethos-U core driver header and
linkage. For CMake, provide `ethosu_core_driver` before adding the generated
module, or use the generated build file's explicit include/link integration.
The generated README and build file identify the dependency.

`HELIA_ETHOSU_ALLOW_STUB=1` permits a nonfunctional stub for host code-generation
checks. It returns success without executing the NPU. Never use a stub result
as accelerator inference evidence.

### The platform gate, and opting out

The NPU gate requires an explicit `NPU` capability; unlike FP16 there is no CPU
fallback. For a simulator that supplies an accelerator while the chosen
platform description does not, the operator gate can be disabled in YAML:

```yaml
operators:
  - type: ETHOS_U
    attributes:
      require_platform_npu: "false"
```

This only bypasses the platform check. It neither adds an accelerator nor
supplies the driver or makes a stub functional. Nested operator rules belong in
YAML; `--operators` does not accept these inline structures.

### What works now, and what is planned

| Path | Repository evidence |
| --- | --- |
| Parse Vela output and emit accelerator calls | Registered parser/operator/template implementation. |
| Run Vela | External prerequisite, not an AOT conversion stage. |
| Ethos-U55 | End-to-end Corstone-300 FVP test setup, using the platform-gate override. |
| Ethos-U85 / Atomiq110 | No U85 execution in that test setup; qualify the intended driver, simulator or board separately. |

The Corstone-320/U85 work is tracked in
[issue #78](https://github.com/AmbiqAI/helia-aot/issues/78). Check actual execution
evidence for your model and environment rather than treating the issue's status
or a registry entry as proof of a deployment.