How to make Ethernet and lwIP working on STM32

[Piranha]

This is an umbrella topic where I will collect the key problems and solutions to finally get networking on STM32 working. The issues formatted as bold are the most critical ones.

HAL ETH drivers have been significantly reworked since the following firmware packages: CubeF4 v1.27.0, CubeF7 v1.17.0, CubeH5 v1.0.0, CubeH7 v1.10.0

Series: F1, F2, F4, F7, H5, H7 (all STM32 with Ethernet)

• lwIP driver Tx deadlock. [reworked drivers]
• Missing compiler and CPU memory barriers. [legacy drivers]
• RMII mode not enabled because of lacking SYSCFG synchronization. [legacy drivers]
• Unwanted interrupts not masked.
• CubeMX generates wrong PHY configuration. [legacy drivers]
• Not possible to use a custom PHY driver in CubeMX. [reworked drivers]
• Wrong clock source and PLL configuration. [examples]
• lwIP driver zero-copy Rx PBUF pool size is inappropriate. [reworked drivers]
• CubeMX generates broken lwippools.h file for C++.
• CubeMX generates a dysfunctional lwIP application without RTOS.
• Unnecessary delay in LAN8742_Init() and link state management in low_level_init(). [reworked drivers]
• Unnecessary delays and peripheral reset in HAL_ETH_Init() function.
• Multiple flaws in a PTP API implementation. [reworked drivers]
• Poorly chosen MDIO frequency limits and scarce documentation.

Series: F1, F2, F4, F7 (older Synopsys basic peripheral)

• Many flaws as a result from incorrect porting of the reworked H7 series HAL ETH driver. [reworked drivers]
• No DMA access to a data in FLASH memory. [reworked drivers]
• Tx complete interrupt not triggered. [legacy drivers] The related documentation is also wrong.
• Wrong Tx checksum offload documentation.
• Wrong PTP clock source documentation.
• Wrong PPS output documentation.

Series: H5, H7 (newer Synopsys QoS peripheral)

• HAL ETH driver sets wrong MDIO frequency.
• Wrong descriptor ring length documentation.
• Wrong and misleading descriptor tail pointer documentation.
• Wrong or scarce DMA Rx resuming documentation.

Series: F7, H7 (Cortex-M7 CPU)

• Flawed MPU configuration and D-cache maintenance in lwIP driver. [reworked drivers]
• Overlapping and merged memory regions in linker script files.
• Critical spelling errors in linker script files.
• The example code in the article "DMA is not working on STM32H7 devices" is flawed in multiple ways.

lwIP API related:

• Ethernet link and DHCP management code is not thread-safe. When used with RTOS, the code ignores lwIP requirements described in Common pitfalls and Multithreading.
• The example code in the article "How to create project for STM32H7 with Ethernet and LwIP stack working" is not thread-safe. It uses RTOS and lwIP RAW API, but doesn't do lwIP core locking.
• Improper use of NETIF and link up/down statuses. The meaning of netif_set_up()/netif_set_down() functions changed in v2.0.0, but ST's code is not updated. Now NETIF must be up regardless of link state, but for a link state only the functions netif_set_link_up()/netif_set_link_down() must be used.
• Improper use of DHCP client. The code is for an outdated version of DHCP client, which needed external state management. Current versions fully manage the state internally. Monitoring of the state and reporting IP addresses can be done by a callback set up with netif_set_status_callback() without wasting a thread on it.

Other related information:

Another detailed topic by @alister​: "[bug fixes] STM32H7 Ethernet". While mostly dedicated to H7 series, it also has a good amount of information relevant to all Ethernet/lwIP related development.

Open source zero-copy Ethernet/lwIP driver example. The hardware driver is for F2 series, which means that it's almost the same for all Fx series. The lwIP related code and general ideas are still valid for all series.

My other closely related topic: "Actually working STM32 Ethernet and lwIP demonstration firmware". As that topic is currently unavailable, because ST still has not moved it to the new forum, I am attaching a PDF copy of that topic and the related firmware files to this topic.

[Piranha]

As the main topic has hit a 10000 character limit, I'm changing this message to a list of fixed issues, which many people will still find useful.

Series: F1, F2, F4, F7 (older Synopsys basic peripheral)

• lwIP driver Rx deadlock. [Fixed in CubeMX v5.5.0]

Series: H7 (newer Synopsys QoS peripheral)

• lwIP driver Rx buffers released while still in use. The discussion in this topic also has a significant amount of related information. [Fixed in CubeH7 v1.10.0]
• HAL driver wrong Rx channel descriptor tail pointer. [Fixed in CubeH7 v1.8.0]

Series: F7, H7 (Cortex-M7 based)

• lwIP driver Rx data buffers not aligned to cache line size. The address and size of buffers, on which D-cache invalidation is done, must be aligned to __SCB_DCACHE_LINE_SIZE, which is 32 bytes for Cortex-M7. Instead of doing D-cache maintenance, newer ST provided code uses MPU to configure specific memory regions as non-cacheable. It's a very poor solution performance wise, but at least it is functionally correct. For a proper and decent solution it is recommended to read my article "Maintaining CPU data cache coherence for DMA buffers". [Fixed by using MPU.]

[Amel NASRI]

Hi @Piranha​ ,

Needed follow-up actions for each discussion are tracked internally by me & Imen.

I suggest to close the current question.

-Amel

[Piranha]

I've added substantial amount of new information.

[ranran]

Hi Piranha,

Thank you very much for the information.

If I may please ask why you don't share the sources ? I will try to do the modifications for H7.

Thanks

[nguen nguyen]

Can anyone send example project ? thanks so much Cubemx 5.4

[alister]

My fixes and improvements to ST's STM32H7 ETH driver and lwIP ethernetif.c are at https://community.st.com/s/question/0D50X0000C6eNNSSQ2/bug-fixes-stm32h7-ethernet.

Source code and documentation attached.

I don't use evaluation boards or build example code.

You'll have to port my changes yourself.

[anotherandrew]

Thank you @Piranha​ for this detailed write-up! I've updated the original thread to point to this one. *excellent* information and lots of detail.

[JBerry]

I am attempting to get Ethernet work on an STM32H745 on the M7 core currently. But I am using CubeIDE 1.4.2 and CubeMX 6.0.1 with ver 1.8.0 of the H7 firmware package. Since these are a bit newer, it is unclear to me which of these issues are still present and which still need fixing. Does anyone have any updates that apply to the newer stuff?

[MTros.1]

Yes, I think same as you. It is worthy to make it clear which ones have remained until now.