Add lib/ dir to contain submodules. Add wolfHAL as a submodule.

.github/workflows/wolfhal-stm32h563zi-nucleo.yml

@@ -6,33 +6,23 @@ on:
   pull_request:
     branches: [ '*' ]
 
-env:
-  # wolfHAL pinned to a wolfSSL/wolfHAL main commit for reproducible CI.
-  # Bump WOLFHAL_REF to build against a newer HAL.
-  WOLFHAL_REF: 5302069e8d7baacefeeada94c4c8e5ef7426c1db
-
 jobs:
   wolfhal_stm32h563zi_nucleo_build:
     runs-on: ubuntu-latest
     timeout-minutes: 10
 
     steps:
+      # wolfHAL comes from the lib/wolfHAL submodule.
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Install ARM toolchain
         run: |
           set -euo pipefail
           sudo apt-get update
           sudo apt-get install -y gcc-arm-none-eabi
 
-      - name: Fetch wolfHAL (pinned to ${{ env.WOLFHAL_REF }})
-        run: |
-          set -euo pipefail
-          git init -q ../wolfHAL
-          git -C ../wolfHAL remote add origin https://github.com/wolfSSL/wolfHAL.git
-          git -C ../wolfHAL fetch --depth 1 origin "$WOLFHAL_REF"
-          git -C ../wolfHAL checkout -q FETCH_HEAD
-
       - name: Build STM32H563 port with the wolfHAL driver backend
         run: |
           set -euo pipefail
@@ -54,6 +44,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: DHCP + TCP echo under m33mu with the wolfHAL driver backend
         run: /bin/bash tools/scripts/run-m33mu-ci-in-container.sh stm32h563-m33mu-wolfhal stm32h563_m33mu_echo_wolfhal

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "lib/wolfHAL"]
+	path = lib/wolfHAL
+	url = https://github.com/wolfSSL/wolfHAL.git

src/port/stm32h563/Makefile

@@ -13,7 +13,7 @@ TZEN ?= 0
 # boards/$(BOARD). First cut supports TZEN=0 and FREERTOS=0 only.
 ENABLE_WOLFHAL ?= 0
 BOARD ?= stm32h563zi_nucleo
-WOLFHAL_ROOT ?= $(ROOT)/../wolfHAL
+WOLFHAL_ROOT ?= $(ROOT)/lib/wolfHAL
 
 # TLS support: set ENABLE_TLS=1 to include wolfSSL TLS server
 # Requires wolfSSL cloned alongside wolfip (or set WOLFSSL_ROOT)
@@ -149,7 +149,7 @@ ifeq ($(FREERTOS),1)
 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))
+  $(error wolfHAL not found at $(WOLFHAL_ROOT). Initialize the submodule: git -C $(abspath $(ROOT)) submodule update --init lib/wolfHAL (or set WOLFHAL_ROOT to an external checkout))
 endif
 
 BOARD_DIR := boards/$(BOARD)
@@ -682,7 +682,7 @@ 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 "  WOLFHAL_ROOT=   Path to wolfHAL (default: lib/wolfHAL submodule)"
 	@echo "  CC=             C compiler (default: arm-none-eabi-gcc)"
 	@echo "  OBJCOPY=        Objcopy tool (default: arm-none-eabi-objcopy)"
 	@echo ""

src/port/wolfHAL/README.md

@@ -32,10 +32,19 @@ handler that FreeRTOS also needs.
 
 `ENABLE_WOLFHAL=1` selects `boards/stm32h563zi_nucleo/` (its own
 `startup.c`/`ivt.c`/`syscalls.c`/`linker.ld` plus `board.c`/`board.h`/`board.mk`),
-pulls the wolfHAL STM32H5 driver TUs from a sibling wolfHAL checkout
-(`WOLFHAL_ROOT ?= ../wolfHAL`), and compiles the port's `main.c` against
+pulls the wolfHAL STM32H5 driver TUs from the `lib/wolfHAL` submodule
+(`WOLFHAL_ROOT ?= lib/wolfHAL`), and compiles the port's `main.c` against
 wolfHAL drivers instead of the hand-rolled bare-metal ones.
 
+Initialize the submodule once with
+
+```
+git submodule update --init lib/wolfHAL
+```
+
+or point `WOLFHAL_ROOT` at an external checkout to build against a
+different HAL.
+
 ## Port API
 
 ```c

tools/scripts/run-m33mu-ci-in-container.sh

@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# wolfHAL commit the wolfHAL jobs build against. CI passes this in from the
-# workflow; the default keeps local runs on the same pinned HAL.
-WOLFHAL_REF="${WOLFHAL_REF:-5302069e8d7baacefeeada94c4c8e5ef7426c1db}"
-
 usage() {
   cat <<'EOF'
 Usage: tools/scripts/run-m33mu-ci-in-container.sh <workflow> [job]
@@ -43,18 +39,6 @@ ensure_repo() {
   fi
 }
 
-ensure_repo_ref() {
-  local name="$1"
-  local url="$2"
-  local ref="$3"
-  if [ ! -d "../${name}/.git" ]; then
-    git init -q "../${name}"
-    git -C "../${name}" remote add origin "${url}"
-    git -C "../${name}" fetch --depth 1 origin "${ref}"
-    git -C "../${name}" checkout -q FETCH_HEAD
-  fi
-}
-
 build_echo() {
   make -C src/port/stm32h563 clean \
     CC=arm-none-eabi-gcc OBJCOPY=arm-none-eabi-objcopy
@@ -63,7 +47,11 @@ build_echo() {
 }
 
 build_echo_wolfhal() {
-  ensure_repo_ref wolfHAL https://github.com/wolfSSL/wolfHAL.git "${WOLFHAL_REF}"
+  # wolfHAL comes from the lib/wolfHAL submodule. CI checks it out with the
+  # repo; initialize it here for local runs.
+  if [ ! -f lib/wolfHAL/wolfHAL/wolfHAL.h ]; then
+    git submodule update --init lib/wolfHAL
+  fi
   make -C src/port/stm32h563 clean TZEN=0 ENABLE_WOLFHAL=1 BOARD=stm32h563zi_nucleo \
     CC=arm-none-eabi-gcc OBJCOPY=arm-none-eabi-objcopy
   make -C src/port/stm32h563 TZEN=0 ENABLE_WOLFHAL=1 BOARD=stm32h563zi_nucleo \