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. 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. 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 and Targets.

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
zephyr	zephyr/module.yml, Kconfig, CMakeLists.txt	Zephyr application
cmake	Root CMakeLists.txt	CMake
nsx	CMakeLists.txt, nsx-module.yaml	NSX
cmsis_pack	.pdsc, optionally a .pack archive	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. Template compatibility alone should not be described as a tested deployment.