Toolchains

Choose the cross-compiler that builds the firmware. hpx builds through neuralSPOT-X, which supports three Cortex-M toolchains; the choice changes build time, binary size and cycle counts, so hold the model, engine and target settings fixed when comparing compilers. Supported combinations depend on the engine and board.

Prerequisites

At least one toolchain installed and found by hpx doctor (Install covers GCC). Arm Compiler 6 needs a licence; ATfE needs ATFE_ROOT.

Which toolchain

target.toolchain	Compiler	Linker	Cost to set up	Pick it when
arm-none-eabi-gcc (default; gcc is the accepted alias)	GNU Arm Embedded	GNU ld	free; install a supported host package	First setup, CI without a licence, cross-platform reproducibility. The default heliaRT registry module builds with it.
armclang	Arm Compiler 6	armlink	licence required	Cycle-count optimisation on Cortex-M55, or confirming a result replicates across compilers. Not covered by ExecuTorch validation.
atfe	Arm Toolchain for Embedded (LLVM)	LLD	free download, ATFE_ROOT	An open LLVM toolchain; preview status in hpx. Builds the heliaRT registry flow and ExecuTorch end to end.

The four accepted values are the Toolchain vocabulary in src/helia_profiler/vocab.py: arm-none-eabi-gcc, gcc, armclang, atfe. Arm Compiler 5 is not among them and is not supported; there is no flag or key for it.

Steps

1. Select it

hpx profile model.tflite --toolchain armclang

target:
  toolchain: armclang

The selection flows to nsx configure --toolchain. GCC is the special case: when arm-none-eabi-gcc or gcc is selected hpx omits the flag so neuralSPOT-X uses its default GCC configuration; armclang and atfe are passed through. Binary sections are probed with arm-none-eabi-size for GCC, fromelf for Arm Compiler 6 and llvm-size from ATFE_ROOT/bin for ATfE.

2. Install the one you chose

GCC

Install as on Install, then verify:

arm-none-eabi-gcc --version
arm-none-eabi-size --version

Arm Compiler 6

armclang ships with Arm Development Studio or the standalone Arm Compiler for Embedded, under licence:

export PATH="/path/to/ArmCompilerForEmbedded/<version>/bin:$PATH"
export ARMLMD_LICENSE_FILE="<port>@<server>"   # or an offline licence file
armclang --version
fromelf --version

armclang --version works without consuming a licence; the build fails at the first compile if the licence server is unreachable.

ATfE

Download from developer.arm.com and set ATFE_ROOT to the extracted toolchain root, not its bin/:

export ATFE_ROOT="/path/to/atfe/<version>"
"$ATFE_ROOT/bin/clang" --version
"$ATFE_ROOT/bin/llvm-size" --version

hpx expects clang, clang++, llvm-ar, llvm-objcopy, llvm-size and llvm-nm under $ATFE_ROOT/bin.

3. Compare on your own model

Compiler results depend on the model, the engine, the optimisation settings and the clock, so measure rather than assume. Same model, three toolchains, three directories:

hpx profile model.tflite --toolchain gcc      --output-dir results/gcc
hpx profile model.tflite --toolchain armclang --output-dir results/armclang
hpx profile model.tflite --toolchain atfe     --output-dir results/atfe
hpx compare results/gcc results/armclang

The work directory is not shared between toolchains; each run configures and builds from scratch. Hold the engine, board and counters constant and vary only --toolchain, otherwise a cycle delta could be any of them. The toolchain comparison example is that recipe with captured output.

Expected output

run_metadata.json records the resolved toolchain and the compiler version it found; the terminal report’s memory table names the size tool used. Different toolchains produce different cycle counts for the same model, which is the point of measuring.

Troubleshooting

armclang: command not found

The Arm Compiler bin/ directory is not on PATH. Source the setup script that ships with Arm Development Studio, or add the path.

License checkout failed (-15)

Set ARMLMD_LICENSE_FILE to the licence server or file. The version check passes without a licence; the compile step does not.

ATFE_ROOT is missing or incomplete

Point ATFE_ROOT at the extracted root, not bin/, and confirm $ATFE_ROOT/bin/clang and $ATFE_ROOT/bin/llvm-size exist.

Different cycle counts on different toolchains

Expected: the compiler is one of the variables that decide code generation. Isolate it by holding everything else constant.

What next

Capture transports for how the data leaves the board, or Engines if the engine you want constrains the toolchain (ExecuTorch is validated on GCC and ATfE).