Add generic wolfHAL Ethernet port with STM32H563ZI Nucleo board support by AlexLanzano · Pull Request #97 · wolfSSL/wolfip

AlexLanzano · 2026-04-07T16:01:03Z

Summary

Add a generic wolfIP port that bridges to wolfHAL's whal_Eth / whal_EthPhy API — any board with a wolfHAL Ethernet driver can use wolfIP with no platform-specific port code
Include STM32H563ZI Nucleo-144 as the first reference board (boards/stm32h563zi_nucleo)
Port waits for PHY link negotiation, starts the MAC with correct speed/duplex, and wires wolfIP_ll_dev poll/send to
whal_Eth_Recv/whal_Eth_Send

Structure

src/port/wolfHAL/
├── Makefile, main.c, wolfhal_eth.c/h # Generic (board-independent)
└── boards/stm32h563zi_nucleo/ # Board-specific: clock, GPIO, ETH, UART, linker

Adding a new board requires only a boards/<name>/ directory with board.c/h, board.mk, and bare-metal startup files. The generic main.c and wolfhal_eth.c are shared across all boards.

Build

cd src/port/wolfHAL
make BOARD=stm32h563zi_nucleo

Requires arm-none-eabi-gcc and wolfHAL cloned as a sibling directory (overridable via WOLFHAL_ROOT).

Testing

I tested this by doing a ping 192.168.1.100 on my host PC. I successfully got a responses back.

Copilot

Pull request overview

Adds a new src/port/wolfHAL/ port intended to let wolfIP run on any target that provides wolfHAL whal_Eth / whal_EthPhy, with STM32H563ZI Nucleo-144 as the first reference board and a standalone Makefile-based bare-metal build.

Changes:

Introduces a generic wolfHAL-based link-layer adapter (wolfhal_eth.c/.h) that bridges wolfIP ll_dev poll/send to whal_Eth_Recv / whal_Eth_Send and starts the MAC after PHY negotiation.
Adds a generic bare-metal main.c for bringing up wolfIP, configuring a static IPv4 address, and starting a TCP echo server.
Adds a complete STM32H563ZI Nucleo board package (startup/IVT/linker/board init/syscalls + board.mk) and a port-local build system + .gitignore.

Reviewed changes

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

Show a summary per file

File	Description
src/port/wolfHAL/wolfhal_eth.h	Public API/docs for the generic wolfHAL Ethernet bridge.
src/port/wolfHAL/wolfhal_eth.c	Implements wolfIP ll_dev poll/send via wolfHAL and link negotiation + MAC start.
src/port/wolfHAL/main.c	Bare-metal reference app wiring board init + wolfIP + echo server.
src/port/wolfHAL/Makefile	New Makefile entrypoint for BOARD-based builds.
src/port/wolfHAL/.gitignore	Ignores build artifacts.
src/port/wolfHAL/boards/stm32h563zi_nucleo/board.mk	Toolchain flags and board + wolfHAL driver source list.
src/port/wolfHAL/boards/stm32h563zi_nucleo/board.h	Board API and exported wolfHAL device instances.
src/port/wolfHAL/boards/stm32h563zi_nucleo/board.c	STM32H563ZI init: flash latency, clocks, GPIO, ETH/PHY, SysTick timer, UART.
src/port/wolfHAL/boards/stm32h563zi_nucleo/syscalls.c	Newlib stubs + wolfIP hooks (incl. RNG).
src/port/wolfHAL/boards/stm32h563zi_nucleo/startup.c	Minimal reset handler (data/bss init + libc init + main).
src/port/wolfHAL/boards/stm32h563zi_nucleo/ivt.c	Cortex-M33 vector table.
src/port/wolfHAL/boards/stm32h563zi_nucleo/linker.ld	Memory map and sections for STM32H563ZI.

💡 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 4 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 3 comments.

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

dgarske

Can wolfHAL be less intrusive? Or show what an update of the existing STM32H5 wolfIP port look for the H5? Have you compare code size between the two (existing and this)? I'd almost like to see instead a proper update to a wolfHAL version of the drivers. Not src/port/wolfHAL but src/port/stm32h5 optionally using the wolfHAL to compare.

AlexLanzano · 2026-05-05T15:20:50Z

Can wolfHAL be less intrusive? Or show what an update of the existing STM32H5 wolfIP port look for the H5? Have you compare code size between the two (existing and this)? I'd almost like to see instead a proper update to a wolfHAL version of the drivers. Not src/port/wolfHAL but src/port/stm32h5 optionally using the wolfHAL to compare.

@dgarske The nice thing about having this in a separate src/port/wolfHAL is that we can maintain a generic application and layer on things like FreeRTOS, MQTT, TLS client/servers without having to re-implement this in each port.

Having this generic wolfHAL port structure makes it much easier to port existing platforms in wolfHAL to wolfip. You just add a new entry in boards/ that contains all the platform specific config instead of spinning up a new src/port/ dir and then having to re-implement all the same application level code.

I can move all of this out of src/port/wolfHAL and into src/port/stm32h5 but this would lose a lot of the nice things that wolfHAL provides IMO

Also, I'll get this size comparison between the existing H5 port and the wolfHAL port soon

aidangarske

Skoll Code Review

Scan type: securityOverall recommendation: COMMENT
Findings: 2 total — 2 posted, 0 skipped

Posted findings

[Medium] Unpinned wolfHAL checkout makes the CI firmware build depend on mutable upstream HEAD — .github/workflows/wolfhal-stm32h563zi-nucleo.yml:1-38
[Medium] wolfHAL Ethernet init failure is logged but networking still starts — src/port/stm32h563/main.c:849-1453

Review generated by Skoll

aidangarske

Skoll Code Review

Scan type: review-securityOverall recommendation: COMMENT
Findings: 6 total — 6 posted, 0 skipped
6 finding(s) posted as inline comments (see file-level comments below)

Posted findings

[Medium] wolfHAL syscalls omit wall-clock hooks required by TLS — src/port/stm32h563/boards/stm32h563zi_nucleo/syscalls.c:23-121
[Medium] 32-bit tick wraps while wolfIP expects a monotonic 64-bit clock — src/port/stm32h563/main.c:1095-1098
[Medium] wolfHAL backend conflicts with the existing DOT1X SysTick handler — src/port/stm32h563/boards/stm32h563zi_nucleo/board.c:34-37
[Medium] CI builds against mutable wolfHAL HEAD — .github/workflows/wolfhal-stm32h563zi-nucleo.yml:23-26
[Low] DEBUG_H5_ETH still references the removed STM32 Ethernet driver — src/port/stm32h563/main.c:1062-1128
[Low] New wolfHAL bridge has no automated behavioral coverage — src/port/wolfHAL/wolfhal_eth.c:27-96

Review generated by Skoll

aidangarske · 2026-07-31T20:34:53Z

+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ */
+#include <sys/stat.h>


🟠 [Medium] wolfHAL syscalls omit wall-clock hooks required by TLS · Logic

The wolfHAL Makefile replaces the existing STM32H563 syscalls with this new file, but the new implementation omits time() and _gettimeofday(). The previous syscalls provided both specifically for wolfSSL certificate validity checks and the 802.1X EAP-TLS demo. TLS/DOT1X builds may therefore fail to link or receive unusable time from libnosys.

Fix: Share or copy the existing wall-clock implementations into the board syscalls and test ENABLE_TLS and ENABLE_DOT1X builds.

aidangarske · 2026-07-31T20:34:54Z

            }
 #endif
            while (!dhcp_bound(IPStack) && dhcp_client_is_running(IPStack)) {
+#ifdef ENABLE_WOLFHAL


🟠 [Medium] 32-bit tick wraps while wolfIP expects a monotonic 64-bit clock · Logic

Before this PR, the port passed a continuously incremented uint64_t tick to wolfIP_poll. The wolfHAL path repeatedly assigns the 32-bit board_get_tick() value to that variable. After roughly 49.7 days, wolfIP's 64-bit timer clock moves backward to zero; existing TCP, DHCP, ARP, and other timer expirations can then be delayed for up to another 49 days.

Fix: Expose a monotonic uint64_t tick or extend the 32-bit SysTick counter across wrap before passing it to wolfIP.

aidangarske · 2026-07-31T20:34:54Z

+/* SysTick timing */
+volatile uint32_t g_tick = 0;
+
+void SysTick_Handler(void)


🟠 [Medium] wolfHAL backend conflicts with the existing DOT1X SysTick handler · Logic

The new board adds a strong SysTick_Handler, while the existing dot1x_client.c also defines a strong handler. The new Makefile rejects only TZEN and FreeRTOS, and still adds dot1x_client.c when ENABLE_DOT1X=1, so ENABLE_WOLFHAL=1 ENABLE_DOT1X=1 fails with a multiple-definition link error. Additionally, DOT1X programs a 32 MHz SysTick reload after wolfHAL has configured the CPU for 168 MHz.

Fix: Use one shared handler/timebase for wolfHAL and DOT1X, or explicitly reject ENABLE_DOT1X with ENABLE_WOLFHAL until the clock and handler integration is implemented.

aidangarske · 2026-07-31T20:34:54Z

+          sudo apt-get update
+          sudo apt-get install -y gcc-arm-none-eabi
+
+      - name: Clone wolfHAL


🟠 [Medium] CI builds against mutable wolfHAL HEAD · Security

The new workflow clones the wolfHAL default branch without pinning or verifying a commit. An upstream force-push or repository compromise can silently change the code compiled by CI and make firmware build results non-reproducible without any wolfIP PR change.

Fix: Pin wolfHAL to a reviewed commit or tag and verify its SHA; pin third-party Actions to immutable SHAs as well.

aidangarske · 2026-07-31T20:34:54Z

+#else
            dhcp_start_tick = tick;
+#endif
 #ifdef DEBUG_H5_ETH


🔵 [Low] DEBUG_H5_ETH still references the removed STM32 Ethernet driver · Logic

The wolfHAL branch no longer includes stm32_eth.h or builds stm32_eth.c, but both DEBUG_H5_ETH blocks still call stm32_eth_get_* functions. Building the new backend with EXTRA_CFLAGS=-DDEBUG_H5_ETH therefore produces missing declarations and linker failures.

Fix: Guard these diagnostics with #ifndef ENABLE_WOLFHAL or replace them with wolfHAL-compatible statistics.

aidangarske · 2026-07-31T20:34:54Z

+#include "wolfhal_eth.h"
+#include "board.h"
+#include <string.h>
+


🔵 [Low] New wolfHAL bridge has no automated behavioral coverage · Missing Tests

The new bridge has no tests for null arguments, PHY query failures, link timeout, MAC start errors, receive buffer lengths, or WHAL_ENOTREADY translation. The new CI job only verifies that an image and size output exist, so these paths are not exercised.

Fix: Add host-side tests with mocked wolfHAL devices, plus a target test covering link negotiation and frame polling.

Not sure if it's worth adding a mock host-side test suite for CI. The bridge will be tested on target.

AlexLanzano · 2026-08-02T16:42:37Z

Need to wait for 64bit tick support to land in wolfHAL (PR is open here wolfSSL/wolfHAL#53) for the wolfHAL CI build checks to pass

AlexLanzano requested review from danielinux and dgarske April 7, 2026 16:01

AlexLanzano assigned danielinux and dgarske Apr 7, 2026

Copilot AI review requested due to automatic review settings April 7, 2026 16:01

AlexLanzano marked this pull request as draft April 7, 2026 16:01

Copilot started reviewing on behalf of AlexLanzano April 7, 2026 16:03 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

AlexLanzano force-pushed the wolfHAL-integration branch from b5999a2 to 015ca06 Compare April 7, 2026 16:27

Copilot AI review requested due to automatic review settings April 7, 2026 16:38

AlexLanzano force-pushed the wolfHAL-integration branch from 015ca06 to 70ac819 Compare April 7, 2026 16:38

Copilot started reviewing on behalf of AlexLanzano April 7, 2026 16:40 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread src/port/wolfHAL/boards/stm32h563zi_nucleo/board.mk Outdated

Comment thread src/port/wolfHAL/boards/stm32h563zi_nucleo/board.c Outdated

Comment thread src/port/wolfHAL/boards/stm32h563zi_nucleo/board.h

Comment thread src/port/wolfHAL/README.md Outdated

AlexLanzano force-pushed the wolfHAL-integration branch from 70ac819 to 6e50685 Compare April 7, 2026 17:08

AlexLanzano marked this pull request as ready for review April 7, 2026 17:20

Copilot AI review requested due to automatic review settings April 7, 2026 17:20

Copilot started reviewing on behalf of AlexLanzano April 7, 2026 17:23 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread src/port/wolfHAL/main.c Outdated

Comment thread src/port/wolfHAL/boards/stm32h563zi_nucleo/board.c Outdated

Comment thread src/port/wolfHAL/Makefile Outdated

AlexLanzano force-pushed the wolfHAL-integration branch from 6e50685 to fc3675e Compare April 7, 2026 18:51

AlexLanzano force-pushed the wolfHAL-integration branch from fc3675e to 80a210f Compare April 17, 2026 18:22

AlexLanzano force-pushed the wolfHAL-integration branch 2 times, most recently from 9fbb31e to 878c293 Compare May 4, 2026 20:29

AlexLanzano mentioned this pull request May 4, 2026

wolfHAL Design Review wolfSSL/wolfHAL#37

Closed

dgarske removed their assignment May 4, 2026

dgarske requested changes May 4, 2026

View reviewed changes

dgarske assigned AlexLanzano May 4, 2026

AlexLanzano assigned dgarske and unassigned AlexLanzano May 5, 2026

danielinux assigned AlexLanzano May 29, 2026

AlexLanzano force-pushed the wolfHAL-integration branch from 878c293 to d1530a9 Compare June 3, 2026 14:49

AlexLanzano requested a review from dgarske June 3, 2026 14:49

AlexLanzano force-pushed the wolfHAL-integration branch 2 times, most recently from 9009c88 to 3974801 Compare June 4, 2026 23:00

AlexLanzano force-pushed the wolfHAL-integration branch from 3974801 to 2e9c1f4 Compare July 10, 2026 19:51

AlexLanzano removed their assignment Jul 10, 2026

AlexLanzano force-pushed the wolfHAL-integration branch from 2e9c1f4 to 8fbd34f Compare July 21, 2026 21:41

dgarske requested a review from aidangarske July 31, 2026 17:27

aidangarske reviewed Jul 31, 2026

View reviewed changes

AlexLanzano force-pushed the wolfHAL-integration branch from 8fbd34f to 268a01e Compare August 2, 2026 16:31

AlexLanzano added 2 commits August 2, 2026 12:31

Add generic wolfHAL Ethernet port with STM32H563ZI Nucleo board support

5d9f1da

Move wolfHAL integration into existing stm32h5 port

26851f3

AlexLanzano force-pushed the wolfHAL-integration branch from 268a01e to 26851f3 Compare August 2, 2026 16:40

AlexLanzano requested a review from aidangarske August 2, 2026 17:08

Uh oh!

Conversation

AlexLanzano commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Structure

Build

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dgarske left a comment

Choose a reason for hiding this comment

Uh oh!

AlexLanzano commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aidangarske left a comment

Choose a reason for hiding this comment

Skoll Code Review

Posted findings

Uh oh!

aidangarske left a comment

Choose a reason for hiding this comment

Skoll Code Review

Posted findings

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexLanzano commented Aug 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

AlexLanzano commented Apr 7, 2026 •

edited

Loading

AlexLanzano commented May 5, 2026 •

edited

Loading