# Toolchains and build environments

Use this page when choosing a compiler or adapting a generated module to a
firmware build. A format supported by the templates, a successful cross-build,
a simulator execution and a physical-board run establish different things.

For a complete first application, use
[Firmware integration](https://ambiqai.github.io/helia-aot/getting-started/integrate/). This page explains
the requirements behind those recipes.

## Status

The repository defines the following checks. They describe the coverage of the
test setup; they do not certify every model, compiler version or board build.
Heavy CI jobs also depend on the pull request's CI routing policy.

| Environment | Support and evidence | Integrator supplies |
| --- | --- | --- |
| Arm GNU Toolchain | The CMake end-to-end harness cross-builds and executes on Corstone-300 FVP using `apollo4p_blue_kbr_evb` and `apollo510_evb` conversion configurations. Native-contract tests separately use host GCC and a pinned kernel library. | Matching kernel build, CPU flags, startup and linker configuration. |
| Arm Compiler for Embedded (`armclang`) | Declared by the NSX manifest and represented in generated attribute guards; no repository CI job builds with it. | Compatible compiler/licence, SDK and kernel library; qualification of the actual firmware build. |
| Arm Toolchain for Embedded (`atfe`) | Declared by NSX and uses the Clang attribute path; no repository CI job builds with it. | Toolchain, SDK/kernel compatibility and build qualification. |
| IAR | Planned; not listed by the NSX manifest and no repository CI build qualifies it. | Compiler/SDK-specific attribute and header validation before relying on it. |
| Zephyr | A real `west build` compiles and links a generated `add_scalar_s8` module for Apollo510 against Zephyr and CMSIS 6. Verification is disabled in this compile-only fixture; it is not executed by that job. | West workspace, Zephyr SDK, Ambiq HAL/CMSIS modules and ns-cmsis-nn extra module. |
| FreeRTOS | The generated model API has no FreeRTOS dependency; there is no repository FreeRTOS application test. | Application task ownership, synchronization, SDK and memory setup. |
| Standalone CMake | Used by the FVP build harness; emits a static library requiring CMake 3.15 or newer. | Complete firmware parent project and compatible kernel linkage. |
| neuralSPOT | Default module format; templates and host contract checks cover output, but no repository job builds a neuralSPOT application. | NeuralSPOT tree, kernel module, board startup, logging and linker sections. |
| NSX | Manifest/build-file generation is covered; no repository job runs neuralSPOT-X. | NSX board layer, `NSX_BOARD_FLAGS_TARGET` and `nsx::cmsis_nn`. |
| CMSIS-Pack | Unit tests invoke `packchk` with XSD validation disabled and permit specific unresolved-dependency warnings. No consuming pack application is built. | Pack-aware build tool, installed kernel dependency and consumer build validation. |
| Bare metal | The FVP harness builds and executes a bare-metal image. | Startup, device configuration, linker script and physical-board qualification for your target. |

Version pins and minimum library requirements are on
[Versions and compatibility](https://ambiqai.github.io/helia-aot/reference/versions/). Simulator execution
is useful functional evidence; it is not an Ambiq board timing measurement.

## What the emitted code assumes of a compiler

**Language and library requirements.** Generated CMake libraries request
`c_std_99`. The generated common header also includes `stdalign.h`, generated
buffers use alignment declarations. Generated README files call for a
target-compatible C toolchain and distinguish the CMake C99 declaration from
the C11 host checks. Use the language support required by the complete SDK/kernel
build rather than treating the CMake declaration as proof of strict C99
portability.

The model uses preplanned buffers rather than a runtime heap allocator. Its
sources depend on the kernel headers and can use C library memory/math helpers.
The optional test harness adds logging and target counter access. Float and
Ethos-U paths bring additional dependencies described in
[Precision](https://ambiqai.github.io/helia-aot/guide/precision/) and [Targets](https://ambiqai.github.io/helia-aot/guide/targets/#ethos-u).

**Compiler extensions and placement.** NeuralSPOT ITCM placement uses guarded
GCC-style section attributes; DTCM placement delegates to the SDK's
`NS_PUT_IN_TCM`. Zephyr uses its own section macros, with target-specific DTCM
mapping. Staged-constant hydration also has a weak-symbol override. Audit these
constructs and the underlying SDK/kernel library when qualifying a toolchain.
An unrecognized compiler may take an empty hook; do not infer placement from a
successful build.

**Logging.** NeuralSPOT selects `ns_lp_printf`; Zephyr selects `printk` only with
`CONFIG_PRINTK`. CMake, NSX and pack output default to no logging. Overrides
must reach generated translation units, not only the application's `main.c`.

**Concurrency.** Serialize model calls, arena rebinding and constant hydration.
The arena table and hydration latch are module-global. Two contexts do not
provide independent concurrent instances. Under an RTOS, define one owner or
protect the complete inference/state-update sequence with application
synchronization.

**Checks in the repository.** Strict host compilation and C++ consumer tests
check emitted syntax and headers, including `extern "C"` placement. These do
not replace compilation with the actual target headers, compiler, libraries and
linker script. The version guard in `aot_common.h` checks the ns-cmsis-nn floor;
it cannot establish correct firmware configuration or execution.

## How the module types map to build environments

| `module.type` | Entry files | Integration recipe |
| --- | --- | --- |
| `neuralspot` | `module.mk` | [neuralSPOT](https://ambiqai.github.io/helia-aot/getting-started/integrate/#neuralspot) |
| `zephyr` | `zephyr/module.yml`, `Kconfig`, `CMakeLists.txt` | [Zephyr application](https://ambiqai.github.io/helia-aot/getting-started/integrate/#zephyr) |
| `cmake` | Root `CMakeLists.txt` | [CMake](https://ambiqai.github.io/helia-aot/getting-started/integrate/#cmake) |
| `nsx` | `CMakeLists.txt`, `nsx-module.yaml` | [NSX](https://ambiqai.github.io/helia-aot/getting-started/integrate/#nsx) |
| `cmsis_pack` | `.pdsc`, optionally a `.pack` archive | [CMSIS-Pack](https://ambiqai.github.io/helia-aot/getting-started/integrate/#cmsis-pack) |

For another build system, the CMake source list and public include directory
identify the module inputs. Carry over required definitions, dependency linkage,
logging and placement hooks as well as the `.c` files.

## When your toolchain is not listed

Start by compiling and linking the actual generated module against the intended
SDK and ns-cmsis-nn. Inspect the linker map for alignment and physical placement,
then run the enabled golden comparison. Retain the compiler version, flags,
library revision and logs with that evidence.

For support, report the compiler/version, `module.type`, target, model
configuration and the first build or runtime failure through
[Support](https://ambiqai.github.io/helia-aot/reference/support/). Template compatibility alone should
not be described as a tested deployment.