wolfSSL · AlexLanzano · Apr 7, 2026 · Jul 9, 2026
diff --git a/.github/workflows/wolfhal-stm32h563zi-nucleo.yml b/.github/workflows/wolfhal-stm32h563zi-nucleo.yml
@@ -0,0 +1,38 @@
+name: wolfHAL STM32H563ZI Nucleo Build
+
+on:
+  push:
+    branches: [ 'master', 'main', 'release/**' ]
+  pull_request:
+    branches: [ '*' ]
+
+jobs:
+  wolfhal_stm32h563zi_nucleo_build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ARM toolchain
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y gcc-arm-none-eabi
+
+      - name: Clone wolfHAL
+        run: |
+          set -euo pipefail
+          git clone --depth 1 https://github.com/wolfSSL/wolfHAL.git ../wolfHAL
+
+      - name: Build STM32H563 port with the wolfHAL driver backend
+        run: |
+          set -euo pipefail
+          make -C src/port/stm32h563 ENABLE_WOLFHAL=1 BOARD=stm32h563zi_nucleo \
+            CC=arm-none-eabi-gcc OBJCOPY=arm-none-eabi-objcopy
+
+      - name: Verify binary
+        run: |
+          set -euo pipefail
+          test -f src/port/stm32h563/app.bin
+          arm-none-eabi-size src/port/stm32h563/app.elf
diff --git a/Makefile b/Makefile
@@ -150,6 +150,8 @@ CPPCHECK_FLAGS=--enable=warning,performance,portability,missingInclude \
 			   --suppress=comparePointers:src/port/rp2350_cyw43439/syscalls.c \
 			   --suppress=unknownMacro:src/port/stm32h563/dot1x_client.c \
 			   --suppress=preprocessorErrorDirective:src/supplicant/supplicant_features.h \
+			   --suppress=comparePointers:src/port/stm32h563/boards/stm32h563zi_nucleo/startup.c \
+			   --suppress=comparePointers:src/port/stm32h563/boards/stm32h563zi_nucleo/syscalls.c \
 			   --disable=style \
 			   --std=c99 --language=c \
 			   --platform=unix64 \

diff --git a/src/port/stm32h563/Makefile b/src/port/stm32h563/Makefile
@@ -7,6 +7,14 @@ ROOT := ../../..
 # Default is TZEN=0 (TrustZone disabled)
 TZEN ?= 0
 
+# wolfHAL driver backend: set ENABLE_WOLFHAL=1 to build the port on top of
+# the wolfHAL HAL (Ethernet MAC/PHY, RNG, UART, GPIO, clocks) instead of the
+# in-tree bare-metal drivers. Selects the self-contained board directory
+# boards/$(BOARD). First cut supports TZEN=0 and FREERTOS=0 only.
+ENABLE_WOLFHAL ?= 0
+BOARD ?= stm32h563zi_nucleo
+WOLFHAL_ROOT ?= $(ROOT)/../wolfHAL
+
 # TLS support: set ENABLE_TLS=1 to include wolfSSL TLS server
 # Requires wolfSSL cloned alongside wolfip (or set WOLFSSL_ROOT)
 ENABLE_TLS ?= 0
@@ -122,6 +130,44 @@ CFLAGS_WOLFSSL := $(filter-out -Werror,$(CFLAGS_WOLFSSL))
 CFLAGS_WOLFSSL += -Wno-unused-variable -Wno-unused-function
 CFLAGS_WOLFSSL += $(EXTRA_CFLAGS_WOLFSSL)
 
+ifeq ($(ENABLE_WOLFHAL),1)
+# -----------------------------------------------------------------------------
+# wolfHAL driver backend
+# -----------------------------------------------------------------------------
+# board_init() programs the PLL directly and the wolfHAL SysTick driver owns
+# the SysTick handler, so the wolfBoot-launched (TZEN=1) clock flow and the
+# FreeRTOS SysTick are not supported in this first cut.
+ifeq ($(TZEN),1)
+  $(error ENABLE_WOLFHAL=1 does not support TZEN=1 yet (board_init owns the PLL, which conflicts with the wolfBoot-launched NS clock flow))
+endif
+ifeq ($(FREERTOS),1)
+  $(error ENABLE_WOLFHAL=1 does not support FREERTOS=1 yet (wolfHAL SysTick conflicts with the FreeRTOS SysTick handler))
+endif
+
+ifeq ($(wildcard $(WOLFHAL_ROOT)/wolfHAL/wolfHAL.h),)
+  $(error wolfHAL not found at $(WOLFHAL_ROOT). Clone it alongside wolfip: git clone https://github.com/wolfSSL/wolfHAL.git (or set WOLFHAL_ROOT))
+endif
+
+BOARD_DIR := boards/$(BOARD)
+
+CFLAGS += -DENABLE_WOLFHAL -DTZEN_ENABLED=0
+CFLAGS += -I$(WOLFHAL_ROOT) -I$(BOARD_DIR) -I$(ROOT)/src/port/wolfHAL
+
+LDSCRIPT := $(BOARD_DIR)/linker.ld
+
+# The board dir carries its own wolfHAL-specific startup/ivt/syscalls; the
+# bare-metal stm32_eth.c driver is replaced by board.c (BSP bringup) plus the
+# generic wolfhal_eth.c bridge.
+SRCS := $(BOARD_DIR)/startup.c $(BOARD_DIR)/ivt.c $(BOARD_DIR)/syscalls.c
+SRCS += main.c $(BOARD_DIR)/board.c $(ROOT)/src/port/wolfHAL/wolfhal_eth.c
+SRCS += $(ROOT)/src/wolfip.c
+
+# wolfHAL driver selection (WHAL_CFG_* defines) + wolfHAL driver TUs.
+include $(BOARD_DIR)/board.mk
+else
+# -----------------------------------------------------------------------------
+# In-tree bare-metal drivers (default)
+# -----------------------------------------------------------------------------
 # Select linker script based on TZEN setting
 ifeq ($(TZEN),1)
   LDSCRIPT := target_tzen.ld
@@ -131,11 +177,12 @@ else
   CFLAGS += -DTZEN_ENABLED=0
 endif
 
-LDFLAGS := -nostdlib -T $(LDSCRIPT) -Wl,-gc-sections
-
 # Base source files
 SRCS := startup.c ivt.c syscalls.c
 SRCS += main.c $(ROOT)/src/port/stm32/stm32_eth.c $(ROOT)/src/wolfip.c
+endif
+
+LDFLAGS := -nostdlib -T $(LDSCRIPT) -Wl,-gc-sections
 
 ifeq ($(FREERTOS),1)
 ifeq ($(wildcard $(FREERTOS_PATH)/include/FreeRTOS.h),)
@@ -515,7 +562,7 @@ endif
 OBJS := $(patsubst %.c,%.o,$(SRCS))
 
 all: app.bin
-	@echo "Built with TZEN=$(TZEN) ENABLE_TLS=$(ENABLE_TLS) ENABLE_TLS_CLIENT=$(ENABLE_TLS_CLIENT) ENABLE_HTTPS=$(ENABLE_HTTPS) ENABLE_SSH=$(ENABLE_SSH) ENABLE_MQTT=$(ENABLE_MQTT) ENABLE_MQTT_BROKER=$(ENABLE_MQTT_BROKER) FREERTOS=$(FREERTOS)"
+	@echo "Built with TZEN=$(TZEN) ENABLE_WOLFHAL=$(ENABLE_WOLFHAL) ENABLE_TLS=$(ENABLE_TLS) ENABLE_TLS_CLIENT=$(ENABLE_TLS_CLIENT) ENABLE_HTTPS=$(ENABLE_HTTPS) ENABLE_SSH=$(ENABLE_SSH) ENABLE_MQTT=$(ENABLE_MQTT) ENABLE_MQTT_BROKER=$(ENABLE_MQTT_BROKER) FREERTOS=$(FREERTOS)"
 ifeq ($(ENABLE_TLS),1)
 	@echo "  wolfSSL: $(WOLFSSL_ROOT)"
 endif
@@ -576,6 +623,11 @@ factory: factory.bin
 $(WOLFSSL_ROOT)/%.o: $(WOLFSSL_ROOT)/%.c
 	$(CC) $(CFLAGS_WOLFSSL) -DWOLFSSL_USER_SETTINGS $(if $(filter 1,$(ENABLE_SSH)),-DENABLE_SSH -DWOLFSSL_WOLFSSH) $(if $(filter 1,$(ENABLE_MQTT_BROKER)),-DENABLE_MQTT_BROKER) $(if $(filter 1,$(ENABLE_DOT1X)),-DHAVE_PBKDF2 -DHAVE_AES_KEYWRAP) -I$(WOLFSSL_ROOT) -c $< -o $@
 
+# wolfHAL driver objects: first-party HAL, but built with -Werror relaxed
+# since the port's -Wextra is stricter than wolfHAL's own build.
+$(WOLFHAL_ROOT)/%.o: $(WOLFHAL_ROOT)/%.c
+	$(CC) $(filter-out -Werror,$(CFLAGS)) -c $< -o $@
+
 clean:
 	rm -f *.o app.elf app.bin
 	rm -f app_v1_signed.bin factory.bin wolfboot_padded.bin
@@ -584,6 +636,10 @@ clean:
 	rm -f $(ROOT)/src/port/stm32/*.o
 	rm -f $(ROOT)/src/port/freeRTOS/*.o
 	rm -f $(ROOT)/src/supplicant/*.o
+ifeq ($(ENABLE_WOLFHAL),1)
+	rm -f boards/$(BOARD)/*.o
+	rm -f $(WOLFHAL_ROOT)/src/*.o $(WOLFHAL_ROOT)/src/*/*.o
+endif
 ifeq ($(FREERTOS),1)
 	rm -f $(FREERTOS_PATH)/*.o
 	rm -f $(FREERTOS_PATH)/portable/MemMang/*.o
@@ -614,7 +670,7 @@ verify: app.bin
 	@strings app.bin | grep -q "MQTT Broker: Initializing" && echo "  ✓ MQTT broker enabled" || echo "  ✗ MQTT broker disabled"
 	@echo ""
 	@echo "Binary size: $$(ls -lh app.bin | awk '{print $$5}')"
-	@echo "Build flags: TZEN=$(TZEN) ENABLE_TLS=$(ENABLE_TLS) ENABLE_HTTPS=$(ENABLE_HTTPS) ENABLE_SSH=$(ENABLE_SSH) ENABLE_MQTT=$(ENABLE_MQTT) ENABLE_MQTT_BROKER=$(ENABLE_MQTT_BROKER) FREERTOS=$(FREERTOS)"
+	@echo "Build flags: TZEN=$(TZEN) ENABLE_WOLFHAL=$(ENABLE_WOLFHAL) ENABLE_TLS=$(ENABLE_TLS) ENABLE_HTTPS=$(ENABLE_HTTPS) ENABLE_SSH=$(ENABLE_SSH) ENABLE_MQTT=$(ENABLE_MQTT) ENABLE_MQTT_BROKER=$(ENABLE_MQTT_BROKER) FREERTOS=$(FREERTOS)"
 
 # Show memory usage
 size: app.elf
@@ -643,6 +699,8 @@ help:
 	@echo ""
 	@echo "Options:"
 	@echo "  TZEN=1          Enable TrustZone support"
+	@echo "  ENABLE_WOLFHAL=1 Use the wolfHAL driver backend (requires wolfHAL; TZEN=0, FREERTOS=0)"
+	@echo "  BOARD=<name>    Board under boards/ (default: stm32h563zi_nucleo)"
 	@echo "  ENABLE_TLS=1    Enable TLS server (requires wolfSSL)"
 	@echo "  ENABLE_TLS_CLIENT=1 Enable TLS client test (Google)"
 	@echo "  ENABLE_HTTPS=1  Enable HTTPS web server (requires TLS)"
@@ -655,11 +713,13 @@ help:
 	@echo "  WOLFSSL_ROOT=   Path to wolfSSL (default: ../wolfssl)"
 	@echo "  WOLFSSH_ROOT=   Path to wolfSSH (default: ../wolfssh)"
 	@echo "  WOLFMQTT_ROOT=  Path to wolfMQTT (default: ../wolfmqtt)"
+	@echo "  WOLFHAL_ROOT=   Path to wolfHAL (default: ../wolfHAL)"
 	@echo "  CC=             C compiler (default: arm-none-eabi-gcc)"
 	@echo "  OBJCOPY=        Objcopy tool (default: arm-none-eabi-objcopy)"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make                                                        # Basic TCP echo (port 7)"
+	@echo "  make ENABLE_WOLFHAL=1                                       # Basic TCP echo via the wolfHAL driver backend"
 	@echo "  make ENABLE_TLS=1                                           # TLS echo server (port 8443)"
 	@echo "  make ENABLE_TLS=1 ENABLE_HTTPS=1                            # TLS + HTTPS web (port 443)"
 	@echo "  make ENABLE_TLS=1 ENABLE_SSH=1                              # TLS + SSH shell (port 22)"