wolfBoot

https://github.com/wolfssl/wolfboot
Admin
wolfBoot is a portable, OS-agnostic, secure bootloader solution for 32-bit microcontrollers, relying...
Tokens:210,436
Snippets:2,241
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Copy Example Configuration

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copy the example configuration file to be used for building wolfBoot.

```bash
cp config/examples/sama5d3.config .config
```

--------------------------------

### NXP iMX-RT Build Configuration Example

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Example configuration variables for building wolfBoot with the NXP iMX-RT SDK. Ensure MCUXPRESSO points to your SDK installation.

```makefile
MCUXSDK?=1
MCUXPRESSO?=$(PWD)/../NXP/mcuxpresso-sdk/mcuxsdk
MCUXPRESSO_DRIVERS?=$(MCUXPRESSO)/devices/RT/RT1060/MIMXRT1062
MCUXPRESSO_CMSIS?="$(PWD)/../CMSIS_5/CMSIS"
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/pico-sdk/rp2350/README.md

Copy the example configuration file for rp2350 to be used as the main configuration.

```bash
cp config/examples/rp2350.config .config
```

--------------------------------

### One-time Setup: Toolchain Installation

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Installs the necessary ARM GCC toolchain, Git, Make, CMake, and build essentials for the project.

```bash
sudo apt install -y gcc-arm-none-eabi git make cmake build-essential
```

--------------------------------

### Build and Run wolfBoot on QEMU with TPM

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

This example demonstrates the steps to configure, build, and run wolfBoot on QEMU, utilizing swtpm for TPM emulation and secure boot features. It includes key generation, image signing, and policy installation.

```bash
cp config/examples/x86_fsp_qemu_seal.config .config
tools/scripts/x86_fsp/qemu/qemu_build_fsp.sh
make keytools
make tpmtools
./tools/keytools/keygen --force --ecc384 -g wolfboot_signing_private_key.der --ecc256 -g tpm_seal_key.key
make CFLAGS_EXTRA="-DHAVE_ECC256"
PCR0=$(python ./tools/scripts/x86_fsp/compute_pcr.py --target qemu wolfboot_stage1.bin | tail -n 1)
./tools/tpm/policy_sign -ecc256 -key=tpm_seal_key.key  -pcr=0 -pcrdigest=$PCR0
./tools/scripts/x86_fsp/tpm_install_policy.sh policy.bin.sig
make test-app/image.elf
IMAGE=test-app/image.elf SIGN=--ecc384 tools/scripts/x86_fsp/qemu/make_hd.sh
./tools/scripts/x86_fsp/qemu/qemu.sh -t
```

--------------------------------

### Setup Configuration and Key Tools

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/flash-OTP.md

Initializes the project configuration and builds the necessary key management tools for the STM32H5 OTP KeyStore setup.

```sh
cp config/examples/stm35h5-tz-dualbank-otp-lms.config .config
make include/target.h
make keytools
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/wolfssl/wolfboot/blob/master/INSTALL.md

Copy an example configuration file from the `config/examples` directory to the wolfBoot root directory as `.config`. This sets up the build environment for a specific platform.

```sh
cp ./config/examples/zynqmp.config .config
```

--------------------------------

### Build lib-fs Example Script

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/lib.md

Execute this script to automate the generation and verification of a signed boot partition for the lib-fs example.

```bash
./tools/scripts/build_lib_fs_example.sh
```

--------------------------------

### Example Boot Output with DEBUG_UART=1

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

This output shows the initialization and partition information when wolfBoot starts with debug UART enabled on the Renesas RX72N.

```text
wolfBoot HAL Init
Boot partition: 0xFFC00000
Image size 27772

| ------------------------------------------------------------------- |
| Renesas RX User Application in BOOT partition started by wolfBoot   |
| ------------------------------------------------------------------- |

wolfBoot HAL Init

=== Boot Partition[ffc00000] ===
Magic:    WOLF
Version:  01
Status:   ff (New)
Trailer Magic: ˇˇˇˇ

=== Update Partition[ffdf0000] ===
Magic:    ˇˇˇˇ
Version:  00
Status:   ff (New)
Trailer Magic: ˇˇˇˇ

Current Firmware Version: 1
Hit any key to call wolfBoot_success the firmware.
```

--------------------------------

### Build wolfBoot for Renesas RX65N

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Basic commands to copy the example configuration and build wolfBoot for the Renesas RX65N. Ensure the RX GCC toolchain is installed and accessible.

```sh
cp ./config/examples/renesas-rx65n.config .config
make
```

--------------------------------

### One-time Setup: Rust Installation

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Installs Rust using rustup, ensuring a minimal profile and the stable toolchain, required for m33mu's simulator plugins.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
    sh -s -- -y --default-toolchain stable --profile minimal
. "$HOME/.cargo/env"
```

--------------------------------

### Postinit Hook Example

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/hooks.md

This hook is called after all loader initialization, just before wolfBoot_start().

```c
void wolfBoot_hook_postinit(void) {
    // Custom post-initialization logic here
}
```

--------------------------------

### Setup Default Configuration

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/CCS/TMS570LC43xx/README.md

Sets up the default configuration for building the project. Ensure you are in the project root directory.

```bash
cp config/examples/ti-tms570lc435.config .config
```

--------------------------------

### Configure and Compile MCX A Firmware

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copies the example configuration file and builds the wolfBoot firmware for the MCX A microcontroller using make.

```bash
cp config/examples/mcxa.config .config
make
```

--------------------------------

### Install and Set Up MCUXpresso SDK

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Installs the 'west' tool and sets up the MCUXpresso SDK repository for the FRDM-MCXN947 board. Ensure you are in the '../NXP' directory before running.

```shell
cd ../NXP

# Install west
python -m venv west-venv
source west-venv/bin/activate
pip install west

# Set up the repository
west init -m https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git mcuxpresso-sdk
cd mcuxpresso-sdk
west update_board --set board frdmmcxn947

deactivate
```

--------------------------------

### Install west and Set Up MCUXpresso SDK

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Installs the 'west' tool and sets up the NXP MCUXpresso SDK repository for the FRDM-MCXA153 board. Ensure the SDK is placed in the expected directory.

```bash
cd ../NXP

# Install west
python -m venv west-venv
source west-venv/bin/activate
pip install west

# Set up the repository
west init -m https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git mcuxpresso-sdk
cd mcuxpresso-sdk
west update_board --set board frdmmcxa153

deactivate
```

--------------------------------

### Copy Example Configuration for T2080 RDB

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copy the default NXP T2080 configuration file to be used for building wolfBoot.

```bash
cp ./config/examples/nxp-t2080.config .config
```

--------------------------------

### Copy Example Configuration for STM32H5 TrustZone

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/STM32-TZ.md

Copy one of the example configurations for STM32H5 with TrustZone and PKCS11 support to your project's .config file. Choose the appropriate configuration based on whether you need Dual Bank support or LMS support.

```bash
cp config/examples/stm32h5-tz.config .config
cp config/examples/stm32h5-tz-dualbank-otp.config .config
cp config/examples/stm32h5-tz-dualbank-otp-lms.config .config
```

--------------------------------

### Example Boot Output on UART 0

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

This is an example of the bootloader output observed on UART 0 for the VA416x0. It shows firmware version, state, and public key information.

```text
wolfBoot HAL Init
Boot partition: 0x9800 (sz 5060, ver 0x1, type 0x601)
Partition 1 header magic 0x00000000 invalid at 0x24800
Boot partition: 0x9800 (sz 5060, ver 0x1, type 0x601)
Booting version: 0x1
========================
VA416x0 wolfBoot demo Application
Copyright 2025 wolfSSL Inc
GPL v3
Version : 0x1
========================

System information
====================================
Firmware version : 0x1
Current firmware state: NEW
No image in update partition.

Bootloader OTP keystore information
====================================
Number of public keys: 1

  Public Key #0: size 96, type 6, mask FFFFFFFF
  ====================================
  5F D6 0D 55 DE 8B 17 99 C0 57 4A A9 D1 EF 2A C8
  6C 36 4A D7 BA 21 5A CB 13 45 AE 45 A0 35 C9 B3
  6B 0D 4F FF 69 47 29 17 10 1D 6D 4F 44 83 3E EF
  9B BE B7 BB 11 75 01 81 45 14 19 7E B2 BD C0 A6
  11 0C FA F6 B5 F9 59 BA B9 A5 8E 34 4A CD C5 83
  7E 43 EF 61 6E C4 15 88 3C FE D6 76 47 D9 82 A4
```

--------------------------------

### Stage 1 Loader Build Example

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Loader.md

Example of how to build the stage 1 loader, specifying the RAM address to load wolfBoot to. This is used on platforms where flash is not memory mapped.

```bash
make WOLFBOOT_STAGE1_LOAD_ADDR=0x1000 stage1
```

--------------------------------

### Build and Run Emulator

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Builds the project and runs the emulator test script. This is the simplest way to start local testing.

```bash
make emu
```

--------------------------------

### Setup Signing Key

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/flash-OTP.md

Copies a generated private key to be used for signing firmware updates.

```sh
cp 1.key wolfboot_signing_private_key.der
```

--------------------------------

### Setting up MCUXpresso SDK for LPC55S69

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Install the 'west' package manager and initialize the MCUXpresso SDK repository for the LPCXpresso55S69 board.

```bash
cd ../NXP

python -m venv west-venv
source west-venv/bin/activate
pip install west

west init -m https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git mcuxpresso-sdk
cd mcuxpresso-sdk
west update_board --set board lpcxpresso55s69

deactivate
```

--------------------------------

### Install West for MCUXpresso SDK Setup

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Installs the 'west' tool, a meta-tool for managing multiple git repositories, which is required for setting up the MCUXpresso SDK. Ensure you are in the NXP directory before running.

```sh
cd ../NXP

# Install west
python -m venv west-venv
source west-venv/bin/activate
pip install west

# Set up the repository
west init -m https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git mcuxpresso-sdk
cd mcuxpresso-sdk
west update_board --set board frdmmcxw71

deactivate
```

--------------------------------

### Manual Key Management Setup

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/compile.md

For manual key management, first import your public key to generate the keystore, then copy your private key to the expected file name for the build system to detect.

```bash
./tools/keytools/keygen --ecc256 -i my-public-key.der
```

```bash
cp my-private-key.der wolfboot_signing_private_key.der
```

--------------------------------

### Run the update server

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/MPLAB/README.md

Start the test-update-server with the signed firmware image. The server will then be ready to receive update requests from the target device.

```bash
tools/test-update-server/server mplab_app_v8_signed.bin
```

--------------------------------

### Example Custom Encryption Key Get Function

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/encrypted_partitions.md

A test implementation for `wolfBoot_get_encrypt_key` using hardcoded test key and nonce values. This is useful for development and testing purposes.

```c
#include "wolfboot/wolfboot.h"
#include "image.h"

int RAMFUNCTION wolfBoot_get_encrypt_key(uint8_t *key, uint8_t *nonce)
{
    int i;
    /* Test key: "0123456789abcdef0123456789abcdef" (32 bytes for AES-256) */
    const char test_key[] = "0123456789abcdef0123456789abcdef";
    /* Test nonce: "0123456789abcdef" (16 bytes) */
    const char test_nonce[] = "0123456789abcdef";

    for (i = 0; i < ENCRYPT_KEY_SIZE && i < (int)sizeof(test_key); i++) {
        key[i] = (uint8_t)test_key[i];
    }
    for (i = 0; i < ENCRYPT_NONCE_SIZE && i < (int)sizeof(test_nonce); i++) {
        nonce[i] = (uint8_t)test_nonce[i];
    }
    return 0;
}
```

--------------------------------

### SiFive HiFive1 JLink GDB Server and Debugging

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Setup for debugging WolfBoot on SiFive HiFive1 using JLinkGDBServer and GDB. This involves starting the server and connecting GDB with symbol information.

```shell
In one terminal:
`JLinkGDBServer -device FE310 -port 3333`

In another terminal:
```
riscv64-unknown-elf-gdb wolfboot.elf -ex "set remotetimeout 240" -ex "target extended-remote localhost:3333"
add-symbol-file test-app/image.elf 0x20020100
```
```

--------------------------------

### Example Boot Output

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Illustrates the expected boot log messages from wolfBoot and the test application, showing firmware version and successful execution.

```text
========================================
wolfBoot Secure Boot - AMD Versal
========================================
Current EL: 2
Timer Freq: 99999904 Hz
QSPI: Lower ID: 20 BB 21
QSPI: Upper ID: 20 BB 21
QSPI: 75MHz, Quad mode, DMA
Versions: Boot 1, Update 0
Trying Boot partition at 0x800000
Loading header 512 bytes from 0x800000 to 0xFFFFE00
Loading image 664 bytes from 0x800200 to 0x10000000...done
Boot partition: 0xFFFFE00 (sz 664, ver 0x1, type 0x601)
Checking integrity...done
Verifying signature...done
Successfully selected image in part: 0
Firmware Valid
Loading elf at 0x10000000
Invalid elf, falling back to raw binary
Loading DTB (size 24894) from 0x1000 to RAM at 0x1000
Booting at 0x10000000

===========================================
 wolfBoot Test Application - AMD Versal
===========================================
Current EL: 1
Firmware Version: 2 (0x00000002)
Application running successfully!

Entering idle loop...

```

--------------------------------

### Install wolfcrypt-py with Local WolfSSL

Source: https://github.com/wolfssl/wolfboot/blob/master/README.md

Install wolfcrypt-py using a local WolfSSL installation. This is useful if you have a custom WolfSSL build.

```sh
cd wolfssl
./configure --enable-keygen --enable-rsa --enable-ecc --enable-ed25519 --enable-des3 CFLAGS="-DFP_MAX_BITS=8192 -DWOLFSSL_PUBLIC_MP"
make
sudo make install

cd wolfcrypt-py
USE_LOCAL_WOLFSSL=/usr/local pip3 install .
```

--------------------------------

### Install Arm GNU Toolchain

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/VSCode/README.md

Install the Arm GNU Toolchain using winget with a specified installation directory. Ensure to restart VS Code or the terminal for PATH refreshes.

```powershell
winget install -e --id Arm.GnuArmEmbeddedToolchain --override "/S /D=C:\Tools\arm-gnu-toolchain-14.2.rel1"
# reopen VS / terminal so PATH refreshes
```

--------------------------------

### Sample Boot Output with FSP on QEMU

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

This output shows the initialization process of wolfBoot with Intel FSP support on a QEMU target. It details memory initialization and FSP service calls.

```text
Cache-as-RAM initialized
FSP-T:0.0.10 build 0
FSP-M:0.0.10 build 0
no microcode for QEMU target
calling FspMemInit...

============= FSP Spec v2.0 Header Revision v3 ($QEMFSP$ v0.0.10.0) =============
Fsp BootFirmwareVolumeBase - 0xFFE30000
Fsp BootFirmwareVolumeSize - 0x22000
Fsp TemporaryRamBase       - 0x4
Fsp TemporaryRamSize       - 0x50000
Fsp PeiTemporaryRamBase    - 0x4
Fsp PeiTemporaryRamSize    - 0x34000
Fsp StackBase              - 0x34004
Fsp StackSize              - 0x1C000
Register PPI Notify: DCD0BE23-9586-40F4-B643-06522CED4EDE
Install PPI: 8C8CE578-8A3D-4F1C-9935-896185C32DD3
Install PPI: 5473C07A-3DCB-4DCA-BD6F-1E9689E7349A
The 0th FV start address is 0x000FFE30000, size is 0x00022000, handle is 0xFFE30000
Register PPI Notify: 49EDB1C1-BF21-4761-BB12-EB0031AABB39
Register PPI Notify: EA7CA24B-DED5-4DAD-A389-BF827E8F9B38
Install PPI: B9E0ABFE-5979-4914-977F-6DEE78C278A6
Install PPI: A1EEAB87-C859-479D-89B5-1461F4061A3E
Install PPI: DBE23AA9-A345-4B97-85B6-B226F1617389
DiscoverPeimsAndOrderWithApriori(): Found 0x2 PEI FFS files in the 0th FV
Loading PEIM 9B3ADA4F-AE56-4C24-8DEA-F03B7558AE50
Loading PEIM at 0x000FFE3D8C8 EntryPoint=0x000FFE3EC4C PcdPeim.efi
Install PPI: 06E81C58-4AD7-44BC-8390-F10265F72480
Install PPI: 01F34D25-4DE2-23AD-3FF3-36353FF323F1
Install PPI: 4D8B155B-C059-4C8F-8926-06FD4331DB8A
Install PPI: A60C6B59-E459-425D-9C69-0BCC9CB27D81
Register PPI Notify: 605EA650-C65C-42E1-BA80-91A52AB618C6
Loading PEIM 9E1CC850-6731-4848-8752-6673C7005EEE
Loading PEIM at 0x000FFE3F114 EntryPoint=0x000FFE411DF FspmInit.efi
FspmInitPoint() - Begin
BootMode : 0x0
Install PPI: 7408D748-FC8C-4EE6-9288-C4BEC092A410
Register PPI Notify: F894643D-C449-42D1-8EA8-85BDD8C65BDE
PeiInstallPeiMemory MemoryBegin 0x3EF00000, MemoryLength 0x100000
FspmInitPoint() - End
Temp Stack : BaseAddress=0x34004 Length=0x1C000
Temp Heap  : BaseAddress=0x4 Length=0x34000

```

--------------------------------

### Start GDB Server on Windows

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Command to start the ST-LINK GDB server on Windows for debugging.

```bash
ST-LINK_gdbserver -d -cp C:\ST\STM32CubeIDE_1.7.0\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.0.0.202105311346\tools\bin -e -r 1 -p 3333
```

--------------------------------

### Build WolfBoot with Makefile

Source: https://github.com/wolfssl/wolfboot/blob/master/README.md

Create a .config file with build specifications, generate keytools, and then build the project. Assumes a .config file exists.

```bash
cp config/examples/stm32h7.config .config
make keytools
make
```

--------------------------------

### Start GDB Server on macOS

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Command to start the ST-LINK GDB server on macOS for debugging.

```bash
/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.1.300.202403291623/tools/bin/ST-LINK_gdbserver -d -cp /Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_2.1.201.202404072231/tools/bin -e -r 1 -p 3333
```

--------------------------------

### STM32WB55 ST-Link Installation

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Steps to clone, build, and install the ST-Link utility for programming the STM32WB55 target.

```shell
git clone https://github.com/stlink-org/stlink.git
cd stlink
cmake .
make
sudo make install
```

--------------------------------

### Build wolfBoot for PIC32CK

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Configure the build using the example configuration file and then build wolfBoot. Ensure you run 'make clean' before building.

```shell
cp config/examples/pic32ck.config .config
make clean
make
```

--------------------------------

### Prepare SD Card for Bare-metal Payload

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Builds WolfBoot for Zynq7000, prepares the FSBL, generates the BOOT.BIN, and then uses a script to partition and copy the necessary files to the SD card for a bare-metal application.

```sh
cp config/examples/zynq7000_sdcard.config .config
make TARGET=zynq7000
cp ${PREBUILT_DIR}/zynq_fsbl.elf .
bootgen -arch zynq -image tools/scripts/zynq7000/zynq7000_qspi.bif -w -o BOOT.BIN
sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX
```

--------------------------------

### Install HSS Payload Generator Tool

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Clones the HSS repository, builds the payload generator tool, and installs it to /usr/local/bin.

```shell
git clone https://github.com/polarfire-soc/hart-software-services.git
cd hart-software-services
cd tools/hss-payload-generator
make
# install tool
sudo cp hss-payload-generator /usr/local/bin/
```

--------------------------------

### Configure and Build wolfBoot for PIC32CZ

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copy the example configuration, clean the build, and then build wolfBoot. Ensure DUALBANK_SWAP is set in the configuration if needed.

```shell
cp config/examples/pic32cz.config .config
make clean
make
```

--------------------------------

### Confirm Ninja and GCC Installation

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/VSCode/README.md

Verify that Ninja and the Arm GNU cross-compiler are installed and accessible in the system's PATH.

```powershell
ninja --version

Get-Command arm-none-eabi-gcc
```

--------------------------------

### Build the wolfBoot Demo

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Navigates to the wolfBoot project directory and executes the make command to build the demo binaries.

```bash
cd path/to/wolfBoot/port/stmicro/stm32h5-tz-wolfhsm
make
```

--------------------------------

### Failure Record Example Usage

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/API.md

Example code demonstrating how to retrieve and print failure records using the wolfBoot API.

```APIDOC
```c
struct wolfBoot_failure_record rec;
int i, n = wolfBoot_get_failure_count();
for (i = 0; i < n; i++) {
    if (wolfBoot_get_failure(i, &rec) == 0) {
        printf("failure: phase %u cause %u part %u ver 0x%x\n",
            rec.phase, rec.cause, rec.partition, rec.fw_version);
    }
}
```
```

--------------------------------

### Board Source File (board.c)

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/wolfHAL.md

Define wolfHAL device instances and implement hal_init and hal_prepare_boot. Export g_wbFlash and g_wbUart as non-static globals.

```c
#include "hal.h"
#include "board.h"

/* Clock controller */
whal_Clock g_wbClock = {
    .regmap = { .base = ..., .size = 0x400 },
    .cfg = &(whal_<Family>Rcc_Cfg) { ... },
};

/* Flash */
whal_Flash g_wbFlash = {
    .regmap = { .base = ..., .size = 0x400 },
    .cfg = &(whal_<Family>Flash_Cfg) {
        .startAddr = 0x08000000,
        .size = ...,
    },
};

#ifdef DEBUG_UART
whal_Gpio g_wbGpio = { ... };
whal_Uart g_wbUart = { ... };
#endif

void hal_init(void)
{
    whal_Clock_Init(&g_wbClock);
    whal_Flash_Init(&g_wbFlash);
#ifdef DEBUG_UART
    whal_Gpio_Init(&g_wbGpio);
    whal_Uart_Init(&g_wbUart);
#endif
}

void hal_prepare_boot(void)
{
#ifdef DEBUG_UART
    whal_Uart_Deinit(&g_wbUart);
    whal_Gpio_Deinit(&g_wbGpio);
#endif
    whal_Flash_Deinit(&g_wbFlash);
    whal_Clock_Deinit(&g_wbClock);
}
```

--------------------------------

### Start GDB Server for Debugging

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Starts the JLinkGDBServer on a specific port for debugging. This should be run in a separate terminal from the GDB client.

```shell
JLinkGDBServer -if swd -Device MCXN947_M33_0 -port 3333
```

--------------------------------

### Install Ninja Build Tool

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/VSCode/README.md

Install the Ninja build tool using winget. This is a required build tool for the wolfBoot project.

```powershell
winget install --id Ninja-build.Ninja -e
```

--------------------------------

### One-time Setup: Build m33mu Emulator

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Clones the m33mu repository, configures it with CMake (disabling wolfSSL), builds the m33mu emulator, and creates a symbolic link for it in ~/.local/bin.

```bash
cd ~
git clone https://github.com/danielinux/m33mu
cd m33mu
cmake -S . -B build -DM33MU_ENABLE_WOLFSSL=OFF
cmake --build build --target m33mu -j
mkdir -p ~/.local/bin
ln -sf "$PWD/build/m33mu" ~/.local/bin/m33mu
```

--------------------------------

### Start GDB Server for Debugging

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Starts the JLinkGDBServer for debugging the wolfBoot firmware on the NXP MCXA153. This command should be run in a separate terminal.

```bash
JLinkGDBServer -if swd -Device MCXA153 -port 3333
```

--------------------------------

### Environment Setup for Xilinx Tools

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Sources the environment script for Xilinx Vitis or Vivado. This is a one-time setup per shell session.

```sh
source /opt/Xilinx/2025.2/Vitis/settings64.sh
```

--------------------------------

### Example wolfBoot Boot Log

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

This is a sample boot log demonstrating the initialization and verification process of wolfBoot on the Kontron VX3060-S2, including FSP details and disk partition checks.

```text
Press any key within 2 seconds to toogle BIOS flash chip
Cache-as-RAM initialized
FSP-T:A.0.7E build 70
FSP-M:A.0.7E build 70
microcode revision: AA, date: 12-28-2022
machine_update_m_params
calling FspMemInit...
warm reset required
Press any key within 2 seconds to toogle BIOS flash chip
Cache-as-RAM initialized
FSP-T:A.0.7E build 70
FSP-M:A.0.7E build 70
microcode revision: AA, date: 12-28-2022
machine_update_m_params
calling FspMemInit...
success
top reserved 0_78C50000h
mem: [ 0x78C40000, 0x78C50000 ] - stack (0x10000)
mem: [ 0x78C3FFF4, 0x78C40000 ] - stage2 parameter (0xC)
hoblist@0x78C90000
mem: [ 0x78C38000, 0x78C3FFF4 ] - page tables (0x7FF4)
page table @ 0x78C38000 [length: 7000]
mem: [ 0x78C37FF8, 0x78C38000 ] - stage2 ptr holder (0x8)
TOLUM: 0x78C37FF8
mem: [ 0x100000, 0x100014 ] - stage1 .data (0x14)
mem: [ 0x100020, 0x100040 ] - stage1 .bss (0x20)
CPUID(0):1B 756E6547 6C65746E
mem: [ 0x58000100, 0x5806196C ] - wolfboot (0x6186C)
mem: [ 0x5806196C, 0x58282000 ] - wolfboot .bss (0x220694)
load wolfboot end
Authenticating wolfboot at 58000200...
Boot partition: 0x58000100 (sz 399212, ver 0x1, type 0x201)
verify_payload: image open successfully.
verify_payload: integrity OK. Checking signature.
wolfBoot: verified OK.
starting wolfboot 64bit
call temp ram exit...successA.0.7E build 70
call silicon...successcap a 2268409840
ddt disabled 0
device enable: 172049
device enable: 172049
AHCI port 0: Disk detected (det: 04 ipm: 00)
AHCI port 1: Disk detected (det: 03 ipm: 01)
SATA disk drive detected on AHCI port 1
Reading MBR...
Found GPT PTE at sector 1
Found valid boot signature in MBR
Valid GPT partition table
Current LBA: 0x1
Backup LBA: 0x6FCCF2F
Max number of partitions: 128
Software limited: only allowing up to 16 partitions per disk.
Disk size: 1107095552
disk0.p0 (0_8000000h@ 0_100000)
disk0.p1 (0_20000000h@ 0_8100000)
disk0.p2 (4_0h@ 0_28100000)
disk0.p3 (4_0h@ 4_28100000)
disk0.p4 (1_0h@ 8_28100000)
disk0.p5 (0_80000000h@ 9_28100000)
disk0.p6 (0_80000000h@ 9_A8100000)
Total partitions on disk0: 7
Checking primary OS image in 0,5...
Checking secondary OS image in 0,6...
Versions, A:1 B:1
Load address 0x58282000
Attempting boot from partition A
```

--------------------------------

### CMake Configuration Output Example

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/CMake.md

This is an example of the output seen when CMake parses a .config file, indicating the configuration mode and loaded settings.

```text
-- Found a .config file, will parse
-- Config mode: dot (.config cache)
-- Loading config from: /mnt/c/workspace/wolfBoot-gojimmypi
-- Reading config file: /mnt/c/workspace/wolfBoot-gojimmypi/.config
-- -- Parsing lines from config file...
-- -- Found line: ARCH?=ARM
-- -- Parsed key: ARCH
-- -- Parsed op:  ?
-- -- Parsed val: ARM
-- -- Assignment: ARCH=ARM
-- -- Found line: TARGET?=stm32h7
-- -- Parsed key: TARGET
-- -- Parsed op:  ?
-- -- Parsed val: stm32h7
-- -- Assignment: TARGET=stm32h7
-- -- Found line: SIGN?=ECC256
-- -- Parsed key: SIGN
-- -- Parsed op:  ?
-- -- Parsed val: ECC256
  ...etc...
```

--------------------------------

### Configure and Compile MCX W Firmware

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copies the example configuration file to .config and then builds the project using make. Ensure you have the MCUXpresso SDK set up.

```sh
cp config/examples/mcxw.config .config
make
```

--------------------------------

### Start PEMicro GDB Server

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Starts the PEMicro GDB server console for debugging. Ensure the device, interface, and port are correctly specified.

```shell
pegdbserver_console -device=NXP_S32K1xx_S32K142F256M15 -startserver -interface=OPENSDA -port=USB1 -serverport=7224 -speed=5000
```

--------------------------------

### Basic CMake Setup for Pico SDK

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/pico-sdk/rp2350/test-app/CMakeLists.txt

Sets the minimum CMake version, defines the path to the wolfboot SDK, and configures the C++ compiler. It also initializes the Pico SDK.

```cmake
cmake_minimum_required(VERSION 3.13)
set(WOLFBOOT_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../..")
get_filename_component(WOLFBOOT_PATH "${WOLFBOOT_PATH}" ABSOLUTE)
set(CMAKE_CXX_COMPILER arm-none-eabi-gcc)
set(LIB_PICO_RUNTIME_INIT=0)

include(${PICO_SDK_PATH}/pico_sdk_init.cmake)

set(PICOTOOL_FETCH_FROM_GIT_PATH ../wolfboot/build/picotool)
set(BOOT_STAGE2_FILE ${CMAKE_CURRENT_LIST_DIR}/boot2_empty.S)
set(PICO_NO_RUNTIME 1)

project(blink)
```

--------------------------------

### Start ST-Link GDB Server on Mac OS

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Command to start the ST-Link GDB server on macOS, specifying paths to necessary tools.

```bash
/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.300.202203231527/tools/bin/ST-LINK_gdbserver -d -cp /Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_2.0.200.202202231230/tools/bin -e -r 1 -p 3333
```

--------------------------------

### Example Boot Output Log

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/XilinxSDK/README.md

This log shows a typical output from the wolfBoot secure boot process, including verification, loading, and execution of a firmware image.

```log
wolfBoot Secure Boot
Read FlashID Lower: Ret 0, 20 BB 20
Read FlashID Upper: Ret 0, 20 BB 20
Versions: Boot 1, Update 0
Trying Boot partition at 800000
Boot partition: 800000 (size 226024, version 0x1)
info: LMS wolfBoot_verify_signature
info: using LMS parameters: L2-H5-W8
info: wc_LmsKey_Verify returned OK
Successfully selected image in part: 0
Firmware Valid
Loading flash image from 8014A8 to RAM at 10000000 (226024 bytes)
Loading elf at 10000000
Found valid elf64 (little endian)
Program Headers 2 (size 56)
Load 57536 bytes (offset 10000) to 0 (p 0)
Clear 20600 bytes at 0 (p 0)
Entry point 0
DTB boot partition: 7B0000
Failed parsing DTB to load
Booting at 0
Hello World

Successfully ran Hello World application
```

--------------------------------

### Configure and Build WolfBoot

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Select a configuration file and build the WolfBoot project. The 'make' command generates a factory image. Use 'make clean' to ensure a fresh build.

```bash
cp ./config/examples/nxp-t1024.config .config   # T1024
cp ./config/examples/nxp-t1040.config .config   # T1040
make clean
make keytools
make
```

--------------------------------

### Load Application with picotool

Source: https://github.com/wolfssl/wolfboot/blob/master/IDE/pico-sdk/rp2350/README.md

Load the signed application binary into the boot partition of the RP2350 using picotool.

```bash
picotool load build/blink_v1_signed.bin -o 0x10040000
```

--------------------------------

### Start OpenOCD for PolarFire SoC Debugging

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Use this command to start the OpenOCD server for debugging on PolarFire SoC. Ensure the SC_INSTALL_DIR is correctly set.

```shell
$SC_INSTALL_DIR/openocd/bin/openocd --command "set DEVICE MPFS" --file board/microsemi-riscv.cfg
```

--------------------------------

### Install Debian Packages for WolfBoot Testing

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Installs necessary packages for compiling WolfBoot, running test scripts, and setting up the Buildroot environment on a Debian-like system.

```bash
# for wolfBoot and others
apt install git make gcc

# for test scripts
apt install sudo dosfstools curl
apt install qemu qemu-system-x86 ovmf gnu-efi

# for buildroot
apt install file bzip2 g++ wget cpio unzip rsync bc
```

--------------------------------

### Build wolfBoot for QSPI Boot

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Build wolfBoot for QSPI boot by copying the QSPI configuration, cleaning the build, and running make.

```shell
cp config/examples/zynqmp.config .config
make clean
make
```

--------------------------------

### Test Boot with QEMU

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Launch the assembled boot image using QEMU for Raspberry Pi 3 emulation. Requires a root file system image.

```bash
qemu-system-aarch64 -M raspi3b -m 1024 -serial stdio -kernel wolfboot_linux_raspi.bin -cpu cortex-a53 -drive file=../wolfboot/2020-02-13-raspbian-buster-lite.img,if=sd,format=raw
```

--------------------------------

### Install LLVM using winget

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Windows.md

Installs the LLVM toolchain, including Clang, using the Windows Package Manager. Ensure winget is available in your command prompt.

```dos
winget install -e --id LLVM.LLVM
```

--------------------------------

### Build with Certificate Chain Verification

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Signing.md

This example demonstrates how to build WolfBoot with certificate chain verification enabled, specifying custom keys and certificate chain files. It shows the use of `make` with specific variables for local key management.

```makefile
make CERT_CHAIN_VERIFY=1 \
     USER_PRIVATE_KEY=my-leaf-private-key.der \
     USER_PUBLIC_KEY=my-leaf-pubkey.der \
     USER_CERT_CHAIN=my-cert-chain.der
```

--------------------------------

### Run Demo with Live Output Logging

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Starts the m33mu emulator with wolfBoot and wolfHSM, capturing all output to a log file while simultaneously streaming it to the terminal.

```bash
env -u LD_LIBRARY_PATH m33mu \
    wolfboot.bin image_v1_signed.bin:0x60000 \
    --persist --uart-stdout --timeout 600 --expect-bkpt 0x7d \
    2>&1 | tee /tmp/m33mu-wolfhsm.log
```

--------------------------------

### macOS GDB Server Setup and Command

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Setup command to create a symbolic link for the ST-LINK GDB server on macOS, followed by the command to run the server.

```bash
sudo ln -s /Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_1.6.0.202101291314/tools/bin/native/mac_x64/libSTLinkUSBDriver.dylib /usr/local/lib/libSTLinkUSBDriver.dylib
/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_1.6.0.202101291314/tools/bin/ST-LINK_gdbserver -d -cp ./Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_1.6.0.202101291314/tools/bin -e -r 1 -p 3333
```

--------------------------------

### Install Xilinx Cable Drivers

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Installs the necessary drivers for the Platform Cable II USB JTAG adapter. This requires root privileges and a cable replug afterward.

```sh
sudo /opt/Xilinx/2025.2/Vitis/data/xicom/cable_drivers/lin64/install_script/install_drivers/install_drivers
```

--------------------------------

### Prepare SD Card for Linux Payload

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Builds WolfBoot for Zynq7000, prepares the FSBL, generates the BOOT.BIN, appends and signs the DTB to the zImage, and then uses a script to partition and copy the signed image to the SD card.

```sh
cp config/examples/zynq7000_sdcard.config .config
make TARGET=zynq7000
cp ${PREBUILT_DIR}/zynq_fsbl.elf .
bootgen -arch zynq -image tools/scripts/zynq7000/zynq7000_qspi.bif -w -o BOOT.BIN
./tools/scripts/zynq7000/prepare_linux.sh    # appends DTB to zImage and signs as one image
mv image_v1_signed.bin test-app/zImage_signed.bin
sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX test-app/zImage_signed.bin
```

--------------------------------

### Install pyocd and Download LPC54S018M Pack

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Install the pyocd tool and download the necessary device pack for the LPC54S018M. This is required for debugging and flashing the SPIFI boot series.

```shell
pip install pyocd
pyocd pack install LPC54S018J4MET180
```

--------------------------------

### Configure and Compile wolfBoot for NXP LPC54S0xx

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Copy the example configuration file and build wolfBoot for the NXP LPC54S0xx SPIFI boot series. This produces 'factory.bin' containing wolfBoot and the signed test application.

```makefile
cp config/examples/nxp_lpc54s0xx.config .config
make
```

--------------------------------

### Start JLinkGDBServer for Debugging

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Starts the JLinkGDBServer in one terminal, which allows GDB to connect and debug the firmware running on the MCXW716. Ensure the correct device and port are specified.

```sh
JLinkGDBServer -if swd -Device MCXW716 -port 3333
```

--------------------------------

### Quick Start Workflow for STM32H5-TZ-WolfHSM

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

This sequence of commands builds the wolfboot binary and a signed test application, stages them, and then flashes them to a NUCLEO-H563ZI board, opening a serial console for observation.

```bash
cd port/stmicro/stm32h5-tz-wolfhsm
make                # build wolfboot.bin + signed test app, stage in ./out
./load.sh           # flash to NUCLEO-H563ZI and open a serial console
```

--------------------------------

### Verify m33mu Installation

Source: https://github.com/wolfssl/wolfboot/blob/master/port/stmicro/stm32h5-tz-wolfhsm/README.md

Checks if the m33mu emulator is installed correctly by listing supported CPUs. It uses `env -u LD_LIBRARY_PATH` to work around potential library conflicts.

```bash
env -u LD_LIBRARY_PATH m33mu --cpu list
```

--------------------------------

### Boot Hook Example

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/hooks.md

This hook is called after hal_prepare_boot() but before do_boot(). It receives a pointer to the verified wolfBoot_image struct, allowing inspection of firmware metadata.

```c
void wolfBoot_hook_boot(struct wolfBoot_image *boot_img) {
    // Custom logic before booting the image
    // Inspect boot_img->version, boot_img->type, etc.
}
```

--------------------------------

### Verify Update by Booting New Firmware (Client Mode)

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/wolfHSM.md

Rerun the wolfBoot simulator to boot the new firmware and verify the update was successful after staging it in client mode.

```shell
# In the wolfBoot terminal window, run the following to update the image and confirm the update
./wolfboot.elf success get_version
```

--------------------------------

### Start JLink GDB Server for Nordic nRF5340

Source: https://github.com/wolfssl/wolfboot/blob/master/docs/Targets.md

Starts the JLink GDB Server for debugging the Nordic nRF5340. Use port 3333 for the application core and 3334 for the network core.

```shell
# To debug the app core:
JLinkGDBServer -device nRF5340_xxAA_APP -if SWD -port 3333
# To debug the net core:
JLinkGDBServer -device nRF5340_xxAA_NET -if SWD -port 3334
```
Tokens:
Raw