Repository navigation
Building
The supported Secure build tuple is Armv8-M on STM32H563. The root Makefile
includes mk/target-stm32h563.mk, mk/layout.mk, mk/arch-armv8m.mk, and
mk/common.mk (target facts, the resolved layout configuration, architecture
facts, and the shared build in that order) and cross-compiles a freestanding
Cortex-M33 image.
- 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 --recursiveThe wolfHSM pin is on upstream main and includes the 128-bit flash programming
support merged in wolfHSM PR #524. Automatic release bumps require that merge
commit so an older release cannot drop the STM32H563 flash support.
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.
makeThis builds the lean default image: isolation level 3, one Non-secure image, Crypto, Internal Trusted Storage, Protected Storage and Initial Attestation, with the manifest checked at build time. Turn an add-on back on with its Make variable, alone or together:
make WT_MAX_GUESTS=2 secure-image # a second Non-secure guest
make WT_FWU=1 secure-image # PSA Firmware Update
make WT_MANIFEST_RUNTIME_CHECK=1 secure-image # boot-time manifest check
make WT_SHA256_FAST=1 secure-image # unrolled SHA-256 transform
make WT_ENGINE=hsm secure-image # the wolfHSM engine
make WT_MAX_GUESTS=2 WT_MANIFEST_RUNTIME_CHECK=1 WT_FWU=1 WT_SHA256_FAST=1 secure-image # full profileMacros lists what each add-on brings back and its measured cost.
The default uses the native crypto engine. Keep separate output directories when comparing or retaining both engine builds:
make secure-image WT_ENGINE=native BUILD_DIR=build-native
make secure-image WT_ENGINE=hsm BUILD_DIR=build-hsmWT_ENGINE_HSM=0 and WT_ENGINE_HSM=1 remain as legacy aliases for
native and hsm, respectively. WT_ENGINE is the public selector for new
builds. See Crypto Engines for the behavior, key model,
and measured footprint of each choice.
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/wolftrust.map |
Link map used to audit code and isolation-band placement |
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, 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.
The manifest is rendered into the build directory from the shared template
manifest/base.json under the build's layout configuration
(tools/manifest/render.py, WT_LAYOUT_CFLAGS), so every address and size
in it is the port's memory_map.h value for that build. CONFIG_VNET=y
applies the manifest/vnet.json overlay and WT_CONFORMANCE=1 the
manifest/conformance.json overlay; a port registers the variants it
supports in port/<soc>/port.json (build.variants).
make CONFIG_VNET=y WT_MAX_GUESTS=2
make WT_CONFORMANCE=1The 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.
The generator also checks the manifest against the port's
platform_caps.h limits and each partition stack against the linked level 3
layout. Without WT_FWU=1 it leaves the update partition out
(--exclude-partition PARTITION_FWU).
Examples:
make WT_TIMESLICE_MS=5
make WT_MAX_GUESTS=2
make BUILD_DIR=build-wrp WT_GUEST_FLASH_WRP=1
make CONFIG_VNET=y WT_MAX_GUESTS=2Link-time optimization is enabled by default for the Secure image. It lets GCC optimize across source-file boundaries while retaining the assembly, CMSE, and isolation-band objects that must keep stable linker behavior. Disable it for a toolchain diagnostic or an explicit non-LTO comparison:
make WT_LTO=0WT_LTO is recorded in secure_build_mode.stamp, so changing it rebuilds the
affected objects. Every Secure link also checks the final ELF for required
exception entries, zero-heap policy, and writable-state placement.
Use separate output directories when comparing footprints:
make BUILD_DIR=build-lto size-report
make BUILD_DIR=build-no-lto WT_LTO=0 size-reportRecord the LTO setting with published size results. Footprint lists the measured sizes and the options that change them.
The default image runs one guest; WT_MAX_GUESTS=2 adds the second guest the
reference two-guest demos use (the target runners pass it through the full
profile). Changing
guest addresses or sizes also requires matching manifest, guest linker,
emulator-load, flash, and measurement-record settings. See
Macros for the supported values, the build profiles, and what
each add-on costs.
Set up the pinned Zephyr workspace, then build the Zephyr PSA guest and the
FreeRTOS PSA guest together. The second guest runs only on a Secure image
built with WT_MAX_GUESTS=2:
make -C tests/firmware/zephyr-stm32h5 clone
make -C tests/firmware/zephyr-stm32h5 \
build-guest0-psa build-freertos-guest1WT_ENGINE must match the Secure image and every guest image. The guest build
scripts default to native and pass the same selector through the Secure and
guest builds:
WT_ENGINE=native make -C tests/firmware/zephyr-stm32h5 \
build-guest0-psa build-freertos-guest1
WT_ENGINE=hsm make -C tests/firmware/zephyr-stm32h5 \
build-guest0-psa build-freertos-guest1For a direct Zephyr configuration rather than the wrapper script:
- native uses
CONFIG_WOLFTRUST_NATIVE_CLIENT=yandCONFIG_WOLFTRUST_WOLFHSM_CLIENT=n; and - hsm uses
CONFIG_WOLFTRUST_WOLFHSM_CLIENT=yand leavesCONFIG_WOLFTRUST_NATIVE_CLIENTdisabled.
The native Zephyr module links guest wolfCrypt plus
src/client/crypto_native_client.c. The wolfHSM module instead links the
wolfHSM client, crypto-callback glue, and
src/client/hsm_psa_transport.c. The FreeRTOS
build_freertos_guest.sh script makes the same source and preprocessor choice
from its WT_ENGINE environment variable.
This produces:
tests/firmware/zephyr-stm32h5/build/guest0_psa/zephyr/zephyr.bintests/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 |
The cross-compile workflow links a Secure image with each engine. The M33MU
lifecycle job crosses guest: [zephyr, freertos] with
engine: [native, hsm]. The scenario job also adds the engine as a matrix
dimension, and the label-selected pull-request workflow runs each requested
scenario under both engines.
The hsmattackneg and hsmpinneg scenarios are intentionally hsm-only.
hsmattackneg injects raw wolfHSM protocol packets against a namespace and NVM
relay surface not linked into the native engine; hsmpinneg has the crypto
partition forge its own wolfHSM server pointers and proves the relay re-pins
them before its next pump, a server the native engine does not link. The
privileged tasklet stacks and registry are covered by the host tasklet_priv
suite and the check_secure_layout.py placement rule. All other scenario rows
run under both engines. See Testing for the commands and
validation scope.
make alone produces an unsigned flat Secure binary. The target
runners perform the complete assembly:
- build wolfBoot and the guest images;
- copy the unpatched wolfTrust binary;
- run
tools/measure/patch_guest_digests.pywith each guest ID, version, and binary; - sign the patched wolfTrust image with the wolfBoot key; and
- 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.
The optional wolfTrust virtual Ethernet switch for wolfIP guests is off by default:
make CONFIG_VNET=y WT_MAX_GUESTS=2
make test-vnet
make test-vnet-targetThe end-to-end VNET guests use
tests/firmware/stm32h563-vnet/, not the Zephyr and FreeRTOS demo
images.
make clean
make -C tests/host clean
make -C tests/firmware/zephyr-stm32h5 cleanThe 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.