wolfBoot Zephyr Integration (ARM TEE Replacement)

This guide explains how to replace the default TEE provider with wolfBoot as the PSA/TEE provider in a vanilla Zephyr workspace.

It assumes:

• You have this wolfBoot repo on disk (this workspace).
• You want Zephyr to build and run the PSA crypto sample using wolfBoot as the TEE.

1) Create a fresh Zephyr workspace

From the workspace root:

mkdir -p zephyrproject
cd zephyrproject
python3 -m venv .venv
./.venv/bin/pip install --upgrade pip west jsonschema pyelftools

./.venv/bin/west init -m https://github.com/zephyrproject-rtos/zephyr
./.venv/bin/west update

You now have a vanilla Zephyr tree under zephyrproject/zephyr.

2) Patch Zephyr for wolfBoot integration

From the Zephyr base (zephyrproject/zephyr), apply the patches in order:

cd /path/to/your/workspace/zephyrproject/zephyr

git apply /path/to/your/workspace/wolfboot/zephyr/patches/*.patch

These patches add:

• wolfBoot TEE driver hooks (drivers/tee/wolfboot + Kconfig/CMake wiring).
• Device-tree binding for the wolfBoot TEE and the wolfssl vendor prefix.
• samples/wolfboot_integration/psa_crypto.
• STM32H5 NS board variants used by the sample (Nucleo H563ZI and H573I-DK).
• Kconfig tweaks so PSA crypto client is enabled with WOLFBOOT_TEE, and the legacy TEE dependency isn’t forced when not configured.

3) Build wolfBoot (secure side) first

wolfBoot provides the secure-side PSA service and CMSE veneers. Build it before the Zephyr app:

cd /path/to/your/workspace/wolfboot
cp config/examples/stm32h5-tz-psa.config .config
make clean wolfboot.bin

This also produces src/wolfboot_tz_nsc.o, which Zephyr links for CMSE veneers.

4) Build the PSA crypto sample with wolfBoot as an extra module

Use the Zephyr sample in-tree, and point ZEPHYR_EXTRA_MODULES to the wolfBoot repo:

cd /path/to/your/workspace/zephyrproject/zephyr

./../.venv/bin/west build -p auto \
  -b nucleo_h563zi/stm32h563xx/ns \
  -d ./build \
  ./samples/wolfboot_integration/psa_crypto \
  -- -DZEPHYR_EXTRA_MODULES=/path/to/your/workspace/wolfboot

Notes:

• The wolfBoot module provides the PSA client veneers, PSA IPC glue, and minimal PSA API wrappers.
• The sample overlay uses compatible = "wolfssl,tee" and the vendor prefix is registered.

5) Flash on STM32H5 Nucleo (TrustZone enabled)

Follow the STM32H5 target guide in wolfboot/docs/Targets.md and program the board with STM32_Programmer_CLI. The key steps are:

# Enable TrustZone
STM32_Programmer_CLI -c port=swd -ob TZEN=0xB4

# Secure window (first 384KB) + remainder non-secure
STM32_Programmer_CLI -c port=swd -ob SECWM1_STRT=0x0 SECWM1_END=0x2F SECWM2_STRT=0x0 SECWM2_END=0x7F

# Secure wolfBoot image
STM32_Programmer_CLI -c port=swd -d wolfboot.bin 0x0C000000

# Non-secure Zephyr payload
STM32_Programmer_CLI -c port=swd -d zephyrproject/zephyr/build/zephyr/zephyr.payload_v1_signed.bin 0x08060000

For the full option-byte list and related notes, see wolfboot/docs/STM32-TZ.md.

Troubleshooting

Missing syscall stubs when building wolfBoot

If you see link errors for _read/_write/_close/_lseek/_fstat/_isatty, wolfBoot includes weak stubs in:

wolfboot/src/arm_tee_psa_ipc.c

PSA symbols missing during Zephyr build

Make sure:

• You built wolfBoot first (for wolfboot_tz_nsc.o).
• You passed -DZEPHYR_EXTRA_MODULES=/path/to/wolfboot.

Kconfig warnings about WOLFBOOT_* symbols

The wolfBoot module supplies its own Kconfig (wolfboot/zephyr/Kconfig) and will generate wolfboot.conf during the sample build when ZEPHYR_EXTRA_MODULES is set correctly.