Building

Building

The supported Secure build tuple is Armv8-M on STM32H563. The root Makefile includes mk/target-stm32h563.mk, mk/arch-armv8m.mk, and mk/common.mk (target facts, architecture facts, and the shared build in that order) and cross-compiles a freestanding Cortex-M33 image.

Prerequisites

• GNU Make
• Python 3
• Git and initialized submodules
• GNU Arm Embedded tools with the arm-none-eabi- prefix
• a native C compiler for host tests

Some submodule URLs use GitHub SSH. Configure GitHub SSH access or an equivalent Git URL rewrite before initializing them.

git submodule update --init --recursive

The Zephyr guest build additionally uses a Python virtual environment, CMake, Ninja, and network access to create its v4.2.0 workspace. The FreeRTOS guest build uses the Arm cross-toolchain and network access; its default source reference is the mutable main branch, not a pinned workspace.

Secure image

make

The default target builds:

Output	Purpose
build/wolftrust.elf	Secure image with symbols
build/wolftrust.bin	Flat Secure binary
build/secure_cmse_implib.o	CMSE import library for Non-secure linking
build/manifest/wolftrust_manifest_generated.c	Generated manifest source
build/manifest/wolftrust_manifest_generated.h	Generated partition and service constants
build/nsc-syms.txt	Symbol list used to enforce the five-veneer gateway

Use another output directory or tool prefix as Make variables:

make BUILD_DIR=build-h5 TOOLPREFIX=/opt/gcc-arm/bin/arm-none-eabi-

The build records the variables enumerated by the secure_build_mode.stamp recipe and regenerates when one of those values changes. The current stamp omits TOOLPREFIX, WT_GUEST_FLASH_WRP, the VNET tuning variables (WT_VNET_POOL_SLOTS, WT_VNET_FRAME_MAX, WT_VNET_RX_QUEUE_DEPTH, WT_VNET_RX_IRQ, WT_VNET_TIMEOUT_TICKS, and WT_VNET_UNKNOWN_UCAST_FLOOD), and the test-only WT_VAULT_FOREIGN_PROBE, WT_VAULT_PROBE_SECURED, and WT_CONF_DIAG_TRAP variables. Use a fresh BUILD_DIR or clean the active output directory before changing an option that the recipe does not record.

Manifest generation

The default input is port/stm32h563/manifest.json. CONFIG_VNET=y selects manifest-vnet.json, and WT_CONFORMANCE=1 selects manifest-conformance.json.

make CONFIG_VNET=y
make WT_CONFORMANCE=1

The generator is constrained to FF-M framework version 0x0100, feature mask 0x1 (connection-based IPC), and 32-bit addresses. Unsupported capabilities or an invalid resource layout stop the build.

Build controls

Examples:

make WT_TIMESLICE_MS=5
make WT_MAX_GUESTS=1
make BUILD_DIR=build-wrp WT_GUEST_FLASH_WRP=1
make CONFIG_VNET=y

Changing guest count, addresses, or sizes also requires matching manifest, guest linker, emulator-load, flash, and measurement-record settings. See Macros for the supported values and constraints.

Reference guests

Set up the pinned Zephyr workspace, then build the Zephyr PSA guest and the FreeRTOS PSA guest together:

make -C tests/firmware/zephyr-stm32h5 clone
make -C tests/firmware/zephyr-stm32h5 \
    build-guest0-psa build-freertos-guest1

This produces:

• tests/firmware/zephyr-stm32h5/build/guest0_psa/zephyr/zephyr.bin
• tests/firmware/zephyr-stm32h5/build/freertos_guest1/freertos_guest1.bin

The same Makefile also provides:

Target	Result
build-guest0	Diagnostic Zephyr guest without the full PSA demo
build-guest0-psa	Zephyr PSA guest
build-guest1	Bare-metal heartbeat guest
build-freertos-guest1	FreeRTOS PSA guest
run	Zephyr PSA plus bare-metal guest under M33MU
run-uarts	Same pair with separated UART output
run-tui	Same pair with the M33MU TUI
zephyr-freertos-uarts	Zephyr and FreeRTOS PSA guests under M33MU

Authenticated image assembly

make alone produces an unsigned flat Secure binary. The target runners perform the complete assembly:

1. build wolfBoot and the guest images;
2. copy the unpatched wolfTrust binary;
3. run tools/measure/patch_guest_digests.py with each guest ID, version, and binary;
4. sign the patched wolfTrust image with the wolfBoot key; and
5. load wolfBoot, signed wolfTrust, and guests at matching addresses.

Do not sign wolfTrust before patching the guest records. An unpatched record count causes required guest launch to fail.

Virtual network build

The optional wolfTrust virtual Ethernet switch for wolfIP guests is off by default:

make CONFIG_VNET=y
make test-vnet
make test-vnet-target

The end-to-end VNET guests use tests/firmware/stm32h563-vnet/, not the Zephyr and FreeRTOS demo images.

Clean builds

make clean
make -C tests/host clean
make -C tests/firmware/zephyr-stm32h5 clean

The root target removes the Secure build, bare-metal and VNET reference firmware, and the host suites it names. The second command clears every native host-suite build; the third clears Zephyr and FreeRTOS guest outputs. Downloaded guest workspaces under ignored directories may remain.

See Getting Started for the shortest path and Testing for validation commands.