Integrate wolfHAL into wolfBoot. Provide stm32wb example.

[AlexLanzano]

Summary

NOTE: This replaces #674, which was closed after significant refactoring.

Adds wolfHAL as an alternative HAL backend for wolfBoot, with a generic board abstraction that makes porting to new hardware a self-contained task. STM32WB Nucleo is the first supported board.

The wolfHAL abstraction is essentially free in flash: at production build settings (Base and RAM_CODE), the resulting image is within ±0.1% of the stock STM32WB HAL — see the size table below.

Motivation

wolfBoot's existing HAL implementations hardcode board-specific configuration (clock speeds, flash geometry, pin assignments) directly in the driver code via macros and register values. When a customer needs to bring up wolfBoot on custom hardware using the same MCU family, they must either modify the existing HAL source or duplicate it — even if the only differences are clock parameters or pin mappings.

wolfHAL separates the driver logic (per MCU family, maintained upstream) from the board configuration (per board, owned by the customer). With this integration, porting wolfBoot to a new board reduces to creating a self-contained board directory (hal/boards/<board>/) — no changes to the core build system or HAL shim required.

Since wolfHAL drivers are maintained as a standalone library, the same drivers used by wolfBoot can be reused in the application firmware and other wolfSSL projects (e.g. wolfTPM, wolfMQTT), giving customers a consistent hardware abstraction across their entire stack.

Architecture

A single TARGET=wolfhal with a BOARD=<board> variable replaces per-family target names. All board-specific details live in hal/boards/<board>/:

hal/boards/<board>/
├── board.h — #define macros mapping Board_* APIs to chip-specific wolfHAL drivers
├── board.c — device instances, clock/flash/GPIO/UART config, hal_init/hal_prepare_boot
└── board.mk — ARCH_FLASH_OFFSET, LSCRIPT_IN, wolfHAL driver objects, RAM_CODE rules

board.h macros resolve Board_* calls directly to wolfHAL driver functions at compile time, avoiding vtable indirection and enabling the linker to GC unused driver code.

A generic HAL shim (hal/wolfhal.c) implements wolfBoot's hal_flash_* and uart_write by calling the Board_* macros — shared across all boards with no board-specific code.

Changes

• hal/wolfhal.c — Generic wolfBoot HAL implementation. Maps hal_flash_write/erase/lock/unlock and uart_write to Board_* macros. Shared across all wolfHAL boards.

• hal/boards/stm32wb_nucleo/ — Board directory for STM32WB55 Nucleo:

  • board.h — maps Board_* to whal_Stm32wb* driver functions
  • board.c — device instances (64 MHz PLL from MSI, flash, GPIO/UART), hal_init/hal_prepare_boot
  • board.mk — build variables, wolfHAL driver objects, RAM_CODE linker rules

• hal/stm32wb.ld — Linker script updated with @WOLFHAL_FLASH_EXCLUDE_TEXT@/@WOLFHAL_FLASH_EXCLUDE_RODATA@/@WOLFHAL_FLASH_RAM_SECTIONS@ placeholders for conditional EXCLUDE_FILE rules when RAM_CODE=1.

• arch.mk — Minimal wolfhal target block: sets WOLFHAL_ROOT, adds include paths. Board-specific build details delegated to board.mk.

• Makefile — Includes hal/boards/$(BOARD)/board.mk and adds board.o to objects when TARGET=wolfhal. Adds linker script placeholder substitutions.

• test-app/app_wolfhal.c — Generic test application using Board_* API for GPIO (LED) and UART alongside wolfBoot update mechanism. Works with any wolfHAL board.

• test-app/Makefile — Adds wolfHAL board support (compiles board object with DEBUG_UART=1). Adds -ffunction-sections -fdata-sections to all test apps for gc-sections support. Defaults WOLFBOOT_ROOT?=.. so clean targets work standalone.

• docs/wolfHAL.md — Integration guide covering the board directory structure, adding new boards, RAM_CODE support, and test application.

• CI — Added wolfhal_stm32wb_test build job.

• config/examples/wolfhal_stm32wb_nucleo.config — Example config.

Image Size (vs stock stm32wb, .text bytes)

Identical build settings (ECC256 / SHA256, 128KB partitions, NVM_FLASH_WRITEONCE), arm-none-eabi-gcc 14.2.0.

Config	Stock	wolfHAL	Delta
Base	22,468	22,420	−48 (−0.21%)
+RAM_CODE	23,648	23,660	+12 (+0.05%)
+DEBUG_UART	24,248	24,616	+368 (+1.52%)

In production builds (no debug UART), the wolfHAL abstraction adds no measurable cost — the linker's --gc-sections recovers more bytes from wolfHAL's split compilation units than the abstraction adds. The +DEBUG_UART row reflects the wolfHAL UART driver's slightly heavier interface; since DEBUG_UART is a development-only flag, this does not affect shipping bootloader size.

[Copilot]

Pull request overview

Integrates wolfHAL as an alternate wolfBoot HAL backend, adding an STM32WB55 Nucleo example plus build/linker plumbing to support optional RAM-based flash driver execution.

Changes:

• Added STM32WB wolfHAL-based HAL and a Nucleo board configuration (clock/flash, optional GPIO/UART).
• Updated STM32WB linker script + build system to support RAM_CODE=1 via build-time linker-script placeholders.
• Added a wolfHAL STM32WB test app, documentation, submodule, and CI build job.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
test-app/app_wolfhal_stm32wb.c	New bare-metal STM32WB55 Nucleo test app using wolfHAL GPIO/UART with wolfBoot update flow.
test-app/Makefile	Adds section GC flags and wolfHAL STM32WB target object list + board object build rule.
lib/wolfHAL	Adds wolfHAL submodule pointer.
hal/wolfhal_stm32wb.c	New wolfHAL-backed STM32WB wolfBoot HAL implementation (flash ops + optional UART).
hal/stm32wb.ld	Adds build-time placeholders to move wolfHAL flash driver into RAM when RAM_CODE=1.
hal/boards/stm32wb_nucleo.c	New STM32WB55 Nucleo wolfHAL board configuration (clock/flash, optional UART).
docs/wolfHAL.md	New integration guide documenting targets/boards, RAM_CODE mechanism, and test app.
config/examples/wolfhal_stm32wb_nucleo.config	New example config selecting wolfHAL STM32WB + Nucleo board.
arch.mk	Adds wolfhal_stm32wb target block and defaults for linker placeholder substitutions.
Makefile	Extends linker-script generation to substitute wolfHAL-related placeholders.
.gitmodules	Registers wolfHAL submodule.
.github/workflows/test-configs.yml	Adds CI build job for the new example config.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dgarske]

I still like this better. Less noise to introduce wolfHAL

[dgarske]

I am happy with the state of this, but will hold for @danielinux to finalize.