zephyr

ExecuTorch on Zephyr

When to use this skill

• Setting up a Zephyr workspace with ExecuTorch as a module
• Adding or configuring a board for an ET Zephyr sample
• Debugging west build failures (linker overflow, section placement, CMake/Python issues)
• Sizing allocator pools for a specific model + board combination

When to use a different skill

Advanced Topics

Architecture

ExecuTorch integrates as a Zephyr external module via zephyr/module.yml. The module exposes ET libraries (runtime, kernels, backends) as Zephyr CMake targets that applications link against.

zephyr_workspace/
├── zephyr/                      # Zephyr kernel
│   └── submanifests/
│       └── executorch.yaml      # pulls ET as a west project
├── modules/lib/executorch/      # ET source (or symlink for dev)
│   └── zephyr/
│       ├── module.yml           # declares ET as Zephyr module
│       ├── CMakeLists.txt       # top-level Zephyr-aware build
│       └── samples/
│           ├── hello-executorch/
│           └── mv2-ethosu/
└── build/                       # west build output

Setup

1. Create Zephyr workspace

mkdir zephyr_workspace && cd zephyr_workspace
python3 -m venv .venv && source .venv/bin/activate
pip install west "cmake<4.0.0" pyelftools ninja jsonschema

west init --manifest-rev v4.4.0

2. Add ExecuTorch as a module

Create zephyr/submanifests/executorch.yaml with the manifest snippet (see zephyr/README.md in the ET repo for the canonical content), or copy it from an existing ET checkout:

# From an existing ET checkout (before west update):
cp /path/to/your/executorch/zephyr/executorch.yaml zephyr/submanifests/

For local development, symlink your ET checkout after west update:

west config manifest.project-filter -- '-.*,+zephyr,+executorch,+cmsis,+cmsis_6,+cmsis-nn,+hal_ethos_u'
west update
rm -rf modules/lib/executorch
ln -s /path/to/your/executorch modules/lib/executorch
west packages pip --install

3. Install ExecuTorch

cd modules/lib/executorch
git submodule sync && git submodule update --init --recursive
./install_executorch.sh
cd ../../..

4. Install Zephyr SDK

west sdk install --gnu-toolchains arm-zephyr-eabi

5. Install Ethos-U tools (if targeting NPU boards)

modules/lib/executorch/examples/arm/setup.sh --i-agree-to-the-contained-eula
source modules/lib/executorch/examples/arm/arm-scratch/setup_path.sh

This installs Vela compiler and Corstone FVP binaries.

Building

Basic build

west build -b <board> modules/lib/executorch/zephyr/samples/<sample> -- \
    -DET_PTE_FILE_PATH=<path/to/model.pte>

Build and run on FVP

west build -b mps3/corstone300/fvp modules/lib/executorch/zephyr/samples/mv2-ethosu -t run -- \
    -DET_PTE_FILE_PATH=mv2_u55_128.pte

Force correct Python

If CMake picks up the wrong Python (common on systems with multiple interpreters):

west build ... -- -DPython3_EXECUTABLE=$(which python3)

Clean rebuild

rm -rf build && west build ...

ET-Specific Zephyr Concepts

Model embedding

pte_to_header.py converts a .pte file into a C header with the model bytes placed in a named section (default: network_model_sec). The section name is controlled by ET_PTE_SECTION in CMakeLists.txt.

Allocator pools

ET requires three memory pools at runtime. The method and temp pools are sized via Zephyr Kconfig; fast scratch is a compile-time macro in some samples.

Defaults are sample- and model-dependent — check the specific sample's prj.conf, board .conf, and Kconfig definitions rather than assuming a single repo-wide default.

Pool sizing depends on the model. To find required sizes:

1. Build and run — runtime errors report exactly how many bytes were requested vs available
2. The method pool must hold the largest planned buffer + all input tensors
3. The temp pool must hold the delegate's scratch buffer (model-dependent)
4. If used, fast scratch must cover the backend's small fast-memory requirement

DMA accessibility

NPU backends (Ethos-U) require model data and scratch buffers in DMA-accessible memory. Which regions are DMA-accessible depends on the board:

When CONFIG_ET_ARM_MODEL_PTE_DMA_ACCESSIBLE=y is set in the board conf (which defines ET_ARM_MODEL_PTE_DMA_ACCESSIBLE for the C++ sources), the runtime skips copying the model blob to a writable SRAM buffer. Use this when the model already resides in DMA-accessible memory (DDR, MRAM). Note: this Kconfig symbol is defined per-sample (e.g., in mv2-ethosu/Kconfig), not globally.

Selective ops build

gen_oplist.py reads the .pte file to determine which ops are needed and generates a selective kernel build. If the model is fully NPU-delegated, no portable ops are built. If fallback ops exist (e.g., aten:: ops not handled by the delegate), only those specific kernels are compiled.

Key Files

Supported Boards