mirror of https://github.com/wolfSSL/wolfBoot.git
109 lines
3.6 KiB
Markdown
109 lines
3.6 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
# 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.
|