Rename board.h to wolfHAL_board.h. Add wolfHAL as a submodule. Update CI to use wolfHAL submodule instead of main branch

.github/workflows/wolfhal-build.yml

@@ -25,28 +25,23 @@ jobs:
     steps:
       - name: Checkout wolfTPM
         uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Install ARM toolchain
         uses: ./.github/actions/apt-retry
         with:
           packages: gcc-arm-none-eabi
 
-      - name: Checkout wolfHAL
-        uses: actions/checkout@v4
-        with:
-          repository: wolfSSL/wolfHAL
-          ref: main
-          path: wolfHAL
-
-      # wolfTPM does not ship board definitions, so stand in for the board.h an
-      # application would provide. Doubles as a check that the documented
-      # contract in hal/README.md is complete and sufficient.
+      # wolfTPM does not ship board definitions, so stand in for the
+      # wolfHAL_board.h an application would provide. Doubles as a check that
+      # the documented contract in hal/README.md is complete and sufficient.
       #
       # user_settings.h is needed because this is a bare metal build that never
       # runs ./configure, so the generated wolftpm/options.h does not exist.
       # WOLFTPM_USER_SETTINGS selects this header instead, which is the same
       # path a real wolfHAL application takes.
-      - name: Generate test board.h and user_settings.h
+      - name: Generate test wolfHAL_board.h and user_settings.h
         run: |
           mkdir -p test-board
           cat > test-board/user_settings.h <<'EOF'
@@ -55,7 +50,7 @@ jobs:
           /* Build options come from the compiler command line below. */
           #endif
           EOF
-          cat > test-board/board.h <<'EOF'
+          cat > test-board/wolfHAL_board.h <<'EOF'
           #ifndef TEST_BOARD_H
           #define TEST_BOARD_H
           #include <wolfHAL/wolfHAL.h>
@@ -76,7 +71,7 @@ jobs:
       - name: Build
         run: |
           set -e
-          INC="-Itest-board -IwolfHAL -I. -Ihal"
+          INC="-Itest-board -Ilib/wolfHAL -I. -Ihal"
           BASE="-mcpu=cortex-m4 -mthumb -Wall -Wextra -Werror
                 -Wmissing-prototypes -Wconversion -Wno-unused-parameter
                 -DWOLFTPM_WOLFHAL -DWOLFTPM_EXAMPLE_HAL -DWOLFTPM_USER_SETTINGS
@@ -93,23 +88,25 @@ jobs:
           build "I2C"                  -DWOLFTPM_I2C -DWOLFTPM_ADV_IO
           build "I2C, verbose"         -DWOLFTPM_I2C -DWOLFTPM_ADV_IO -DWOLFTPM_DEBUG_VERBOSE
 
-      # The board.h contract is enforced by #error guards. Verify a missing
-      # entry is reported by name rather than as a confusing undeclared symbol.
-      - name: Check board.h guards report missing macros
+      # The wolfHAL_board.h contract is enforced by #error guards. Verify a
+      # missing entry is reported by name rather than as a confusing undeclared
+      # symbol.
+      - name: Check wolfHAL_board.h guards report missing macros
         run: |
           set -e
           mkdir -p bad-board
-          sed '/BOARD_CS_PIN/d' test-board/board.h > bad-board/board.h
+          sed '/BOARD_CS_PIN/d' test-board/wolfHAL_board.h \
+            > bad-board/wolfHAL_board.h
           cp test-board/user_settings.h bad-board/
           if arm-none-eabi-gcc -fsyntax-only -mcpu=cortex-m4 -mthumb \
-               -Ibad-board -IwolfHAL -I. -Ihal \
+               -Ibad-board -Ilib/wolfHAL -I. -Ihal \
                -DWOLFTPM_WOLFHAL -DWOLFTPM_EXAMPLE_HAL -DWOLFTPM_USER_SETTINGS \
                -DWOLFTPM2_NO_WOLFCRYPT -DNO_FILESYSTEM -DWOLFTPM_INCLUDE_IO_FILE \
                hal/tpm_io_wolfhal.c 2> guard.log; then
             echo "FAIL: expected a compile error for the missing macro"
             exit 1
           fi
-          grep -q "board.h must define BOARD_CS_PIN" guard.log || {
+          grep -q "wolfHAL_board.h must define BOARD_CS_PIN" guard.log || {
             echo "FAIL: guard did not name BOARD_CS_PIN"; cat guard.log; exit 1; }
           echo "PASS: guard named the missing macro"
 

.gitmodules

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

README.md

@@ -331,7 +331,7 @@ make install
 --enable-i2c            Enable I2C TPM Support (default: disabled, requires advio) - WOLFTPM_I2C
 --enable-mmio           Enable built-in MMIO callbacks (default: disabled) - WOLFTPM_MMIO
 --enable-wolfhal        Enable wolfHAL IO callbacks (default: disabled) - WOLFTPM_WOLFHAL
-                        Requires the wolfHAL headers and an application provided board.h.
+                        Requires the wolfHAL headers and an application provided wolfHAL_board.h.
                         See hal/README.md for the required BOARD_* definitions.
 --enable-checkwaitstate Enable TIS / SPI Check Wait State support (default: depends on chip) - WOLFTPM_CHECK_WAIT_STATE
 --enable-smallstack     Enable options to reduce stack usage

configure.ac

@@ -647,7 +647,7 @@ fi
 
 # wolfHAL hardware abstraction layer
 # Selects hal/tpm_io_wolfhal.c for SPI/I2C. Requires wolfHAL headers and a
-# board.h supplying the BOARD_* peripheral definitions.
+# wolfHAL_board.h supplying the BOARD_* peripheral definitions.
 AC_ARG_ENABLE([wolfhal],
     [AS_HELP_STRING([--enable-wolfhal],[Enable wolfHAL IO callbacks (default: disabled)])],
     [ ENABLED_WOLFHAL=$enableval ],

hal/README.md

@@ -41,9 +41,9 @@ CubeMX headers present, for example, selects `tpm_io_st.c` instead.
 ### Board definitions
 
 wolfTPM does not ship board definitions. `tpm_io_wolfhal.c` includes
-`"board.h"`, which the application provides on its include path. A wolfHAL
-project already has one, so in most cases only the TPM specific entries below
-need adding to it.
+`"wolfHAL_board.h"`, which the application provides on its include path. A
+wolfHAL project already has one, so in most cases only the TPM specific entries
+below need adding to it.
 
 For SPI:
 
@@ -72,7 +72,7 @@ each transfer is retried up to `TPM_I2C_TRIES` times (default 10). Define
 A missing entry is reported at compile time, naming the macro required. Only
 the macros needed by the selected bus are checked.
 
-Example additions to an existing wolfHAL `board.h`:
+Example additions to an existing `wolfHAL_board.h`:
 
 ```c
 /* TPM on SPI1, chip select on PA15 */
@@ -84,14 +84,14 @@ extern whal_Spi_ComCfg g_tpmSpiComCfg;
 For I2C, where the session config carries the TPM address:
 
 ```c
-/* board.c */
+/* wolfHAL_board.c */
 whal_I2c_ComCfg g_tpmI2cComCfg = {
     .freq   = 400000, /* Hz */
     .addr   = 0x2e,   /* TPM target address */
     .addrSz = 7,      /* bits */
 };
 
-/* board.h */
+/* wolfHAL_board.h */
 extern whal_I2c_ComCfg g_tpmI2cComCfg;
 #define BOARD_I2C_COM_CFG  (&g_tpmI2cComCfg)
 ```

hal/tpm_io_wolfhal.c

@@ -46,17 +46,17 @@
  * selected, so the file compiles to nothing when built directly on a
  * platform that does not have wolfHAL available. */
 #include <wolfHAL/wolfHAL.h>
-#include "board.h"
+#include "wolfHAL_board.h"
 
 #ifdef WOLFTPM_I2C
-    /* board.h is supplied by the application, not by wolfTPM. It must
+    /* wolfHAL_board.h is supplied by the application, not by wolfTPM. It must
      * describe how this board reaches the TPM. */
     #ifndef BOARD_I2C_DEV
-    #error "wolfHAL: board.h must define BOARD_I2C_DEV (whal_I2c*)"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_I2C_DEV (whal_I2c*)"
     #endif
     /* Carries the TPM target address (typically 0x2e) and bus speed. */
     #ifndef BOARD_I2C_COM_CFG
-    #error "wolfHAL: board.h must define BOARD_I2C_COM_CFG (whal_I2c_ComCfg*)"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_I2C_COM_CFG (whal_I2c_ComCfg*)"
     #endif
     #ifdef TPM2_I2C_ADDR
     #error "wolfHAL: TPM2_I2C_ADDR is unused, set addr in BOARD_I2C_COM_CFG"
@@ -132,19 +132,19 @@
     }
 
 #else /* wolfHAL SPI */
-    /* board.h is supplied by the application, not by wolfTPM. It must
+    /* wolfHAL_board.h is supplied by the application, not by wolfTPM. It must
      * describe how this board reaches the TPM. */
     #ifndef BOARD_SPI_DEV
-    #error "wolfHAL: board.h must define BOARD_SPI_DEV (whal_Spi*)"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_SPI_DEV (whal_Spi*)"
     #endif
     #ifndef BOARD_SPI_COM_CFG
-    #error "wolfHAL: board.h must define BOARD_SPI_COM_CFG (whal_Spi_ComCfg*)"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_SPI_COM_CFG (whal_Spi_ComCfg*)"
     #endif
     #ifndef BOARD_GPIO_DEV
-    #error "wolfHAL: board.h must define BOARD_GPIO_DEV (whal_Gpio*) for chip select"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_GPIO_DEV (whal_Gpio*) for chip select"
     #endif
     #ifndef BOARD_CS_PIN
-    #error "wolfHAL: board.h must define BOARD_CS_PIN (chip select pin, active low)"
+    #error "wolfHAL: wolfHAL_board.h must define BOARD_CS_PIN (chip select pin, active low)"
     #endif
 
     int TPM2_IoCb_Wolfhal_SPI(TPM2_CTX* ctx, const byte* txBuf, byte* rxBuf,