Ethernet HAL Driver reworked by ST and available in 22Q1 (preview now available on GitHub)

MWB_CHa · ‎2021-12-21

Multiple feedbacks reported around Ethernet HAL driver and applications on STM32Cube FW have been acknowledged and analyzed. Many of them were related to RX packets management, to DMA management, or to overall performance. A summary list of tickets on GitHub and forum is provided below for reference.

We apologize for the time it took to provide an adapted solution. We are changing support model to provide more dynamic updates in the future (mainly leveraging GitHub mechanisms).

Today, based on the received feedbacks, the Ethernet HAL driver has been reworked to fix most known issues, enhance performance, and add some missing features.

The reworked Ethernet HAL driver (along with updated applications) is being deployed on STM32CubeH7, STM32CubeF4 and STM32CubeF7 FW packages.

Official publication dates are aligned with maintenance dates: 22Q1 for STM32H7 and STM32F4, and 22Q2 for STM32F7.

Before the official publication: the reworked Ethernet HAL driver and applications are shared on GitHub (https://github.com/STMicroelectronics/stm32h7xx_hal_driver/pull/16) in the form of a pull request, available for everyone for use and review. Feedbacks, comments, enhancements, and proposals are more than welcome.

After the official publication: more frequent updates are planned and will be anticipated on GitHub.

The reworked Ethernet HAL driver brings multiple changes and a compatibility break vs. legacy Ethernet HAL driver. Main changes are listed here:

Add support for PTP and ARP.
Rework packets reception and buffers allocation for a better integration and performance.
Rework packets transmission and buffers allocation (using Interrupts instead of polling and prevent packets lock during transmission).
Enhance DMA management.
Decouple Ethernet HAL driver from PHY driver.
Enhance maximum throughput in RX (94Mbs) and TX (92Mbs).
Enhance footprint (new driver size is 6% less than legacy driver).
Full integration with LwIP (with and without FreeRTOS) and NetXDuo with ThreadX.
Rework applications for STM32CubeH7 FW, STM32CubeF4 FW and STM32CubeF7 FW to align with new Ethernet HAL driver.
MISRA-C 2012, code coverage analysis, static code analysis and robustness validation added.

The new Ethernet HAL driver is supported by STM32CubeMX release of 22Q1 on STM32H7 and STM32F4. Support on STM32F7 follow in 22Q2.

Since the new Ethernet HAL driver brings a compatibility break, existing projects using it shall be updated accordingly. A step-by-step guide for how to update existing projects is shared in this forum and soon in a dedicated Wiki page. A pull request on STM32H7 CubeFW LwIP projects is also provided here to show how modifications are done.

Also, users with existing projects, who don’t want or need to move to the new Ethernet HAL driver can keep their projects running by pointing to legacy driver that will be available in a dedicated folder in future STM32Cube FW packages.

We warmly thank community contributors, and especially @alister and @Piranha who did a great job synthesizing encountered issues and feedbacks. We keep looking for your feedbacks to continue enhancing and adapting for your needs.

General FAQ :

Is new Ethernet HAL driver compatible with legacy driver?
- New driver is not compatible with the legacy driver.
Is it mandatory to switch to new Ethernet HAL driver?
- In order to benefit from better performance and reliability, it is preferred to switch to the new driver. But it is also possible to keep legacy driver that will still be available in STM32Cube FW packages.
Are all existing projects in STM32Cube FW package updated to use the new Ethernet HAL driver ?
- All LwIP projects on STM32H7, STM32F4 and STM32F7 STM32Cube FW packages are updated.
- Other projects using Ethernet HAL driver like demos or mbedTLS are kept using legacy driver.
Shall I expect issues with STM32CubeMX when generating code for ETH HAL ?
- Yes, STM32CubeMX 6.5.0 and newer support the new architecture of the ETH HAL and so do not generate the legacy structures. It means a project generated with that version will not be compatible with legacy ETH HAL.
- Specifically on X-CUBE-AZRTOS-H7, X-CUBE-AZRTOS-F7 and X-CUBE-AZRTOS-F4, it is not possible to use STM32CubeMX 6.5.0 for ETH without a compatibility break. An updated version for each package is being released to align them with new ETH HAL driver.

Detailed List of tickets:

Here below a list of main ticket that have been taken into consideration and fixed in the new Ethernet HAL driver and applications. Some of them come from community (very well summarized in a single post), some others are logged on GitHub, and others were logged on internal bug tracking system (the items without hyperlink):

81088 [ETH] RM0433 v6 faults and missing details on ETHERNET related sections

100608 [ETH]: Need to add new fields in the ETH_TxDescListTypeDef

79181 [STM32H7] ETH Ingress correction register

75481 Ticket 75481 - Ethernet PPS functionality clarification

62100 ARPEN support in Ethernet Driver

79615 Ethernet: Enable and handle the DMA

67970 Read Buffer Underflow interrupt

91624 SCB_InvalidateDCache_by_Addr alignment in ethernetif.c

97885 Question about CMSIS EMAC driver

100109 [HAL_ETH] By default MMC interrupt is not handled

83608 LWiP Interrupt and Through Put is Low

81685 [MW_LwIP] Can't ping device with mDNS feature

81312 Length value issue in HAL_ETH_GetReceivedFrame_IT

41452 MBED / Ethernet: inconsistent transmission issue

74243 Add LWIP examples for DISCO-H747I

48259 [ETH] Support of PTP feature in the driver

101731 [LwIP/ETH/MSP][ExamplesMX] Missing initialization to 0 for most local variables of

67276 Several bugs in ethernetif.c: giving back Rx descriptor to DMA before packet was processing by LWIP

91976 LWIP HAL project race condition

91624 SCB_InvalidateDCache_by_Addr alignment in ethernetif.c

108075 Ethernet not working with high AHB/APB2 divider

62100 ARPEN support in Ethernet Driver

67970 Ethernet: Enable and handle the DMA Read Buffer Underflow interrupt

104729 [GitHub] Wrong HSE_VALUE in NUCLEO-H743ZI LwIP_HTTP_Server_Netconn_RTOS application

101385 [ETH] Same issue as ticket 40298 but in STM32CubeH7 v1.8.0

101620 Support of MW_AzureRTOS and associated applications

63844 [LwIP License update] Update the Licenses (in readme and source files)

106013 [ETH] Ping max buffer size

108010 Ethernet HAL workaround against Ping Flood issue

108675 Ethernet erroneous data received in RMII configuration

108674 Ethernet erroneous data received in RMII configuration

108670 Ethernet erroneous data received in RMII configuration

Forum https://community.st.com/s/question/0D50X0000C6eNNSSQ2/bug-fixes-stm32h7-ethernetNetIPAnalysis.docx (including multiple forum tickets)

GitHub https://github.com/STMicroelectronics/cmsis_device_f7/pull/1

GitHub https://github.com/ARMmbed/mbed-os/issues/12459

GitHub https://github.com/STMicroelectronics/stm32h7xx_hal_driver/issues/8

GitHub https://github.com/STMicroelectronics/STM32CubeF4/issues/60

MWB_CHa · ‎2022-04-04

Hi @Pavel A. ,

Thanks for your valuable input.

We double checked the point about callbacks and potential impact on stack usage.

As you can see in table below, the stack usage with callbacks method is even better than the legacy model, so we think there's nothing to worry about at least from this side.

Another check has already been done also on CPU load with positive results (no impact of the new driver on the overall CPU load).

Regarding the point of architecture (Separation of the driver and higher/app/middleware level code could be more elegant and robust.):

It makes sense. But, actually our major constraint and main concern is the memory allocation which is done in application level (ethernetif.c), so there is a need to know how many allocations have been done. And if the number of allocations is managed inconsistently we fall back in the issues faced in legacy ETH HAL driver.

Which means this architecture was necessary to solve that particular problem. So I agree that a separation of the driver from high layer would be more elegant, but it would be less efficient in solving the main problem.

Please don't hesitate to comment/feedback.

Kind Regards,

MWB_CHa · ‎2022-04-04

Hello @RHitt.2 ,

Sorry for the delayed answer. I planned to provide the code on a GitHub fork waiting for official release. But the official release is almost ready and will be published mid April.

I'll provide in this post the link to GitHub update and the document will also be updated accordingly.

Kind Regards,

MWB_CHa · ‎2022-04-04

Hi @Pavel A.,

Thanks for your valuable input.

We double checked the point about callbacks and potential impact on stack usage.

As you can see in table below, the stack usage with callbacks method is even better than the legacy model, so we think there's nothing to worry about at least from this side.

Another check has already been done also on CPU load with positive results (no impact of the new driver on the overall CPU load).

Regarding the point of architecture (Separation of the driver and higher/app/middleware level code could be more elegant and robust.):

It makes sense. But, actually our major constraint and main concern is the memory allocation which is done in application level (ethernetif.c), so there is a need to know how many allocations have been done. And if the number of allocations is managed inconsistently we fall back in the issues faced in legacy ETH HAL driver.

Which means this architecture was necessary to solve that particular problem. So I agree that a separation of the driver from high layer would be more elegant, but it would be less efficient in solving the main problem.

Please don't hesitate to comment/feedback.

Kind Regards,

RHitt.2 · ‎2022-04-04

Thank you @MWB_CHa . I appreciate your kind support and update.

Asantos · ‎2022-04-13

Hi Chekib Hammami,

Do you already have a precise date when the X-CUBE-AZRTOS-H7 update will be available?

MWB_CHa · ‎2022-04-13

Hi @Community member ,

The package is ready and will be published early next week on both github and st.com.

Kind Regards,

FrankYang-P&S · ‎2022-04-17

Hi Chekib Hammami,

I also updated AZRTOS-H7 to V2.1.0, it still complains the compatible issue. My cubemx version is v6.5.0.

MWB_CHa · ‎2022-04-18

Hi @Community member ,

Servers sync might take some time and then this warning message will disappear from STM32CubeMX 6.5.0.

Kind Regards,

ktrofimo · ‎2022-04-21

This driver looks better than the legacy one, but still, some issues can happen.

1) STM32H743 DMA Tx error 2 (HAL_ETH_ERROR_BUSY). A possible solution is to check errors after transmitting attempt and reset DMA:

res = HAL_ETH_Transmit_IT(&heth, &TxConfig );
  if( res != HAL_OK ) {
	  printf("%s: HAL_ETH_Transmit failed, errorcode: %lx\n",
  				__func__,
				HAL_ETH_GetError(&heth));
 
  	  //Clear TBU flag to resume processing
  	  heth.Instance->DMACSR = ETH_DMACSR_TBU;
  	  //Instruct the DMA to poll the transmit descriptor list
  	  heth.Instance->DMACTDTPR = 0;
  }

The same could theoretically happen during receive, so probably this will help:

if (osSemaphoreAcquire(RxPktSemaphore, TIME_WAITING_FOR_INPUT) == osOK)
    {
      do
      {
        p = low_level_input( netif );
        if (p != NULL)
        {
          if (netif->input( p, netif) != ERR_OK )
          {
            pbuf_free(p);
          }
        }
      } while(p!=NULL);
    }
    if( (heth.Instance->DMACSR & ETH_DMACSR_RBU) != (uint32_t)RESET)
    {
        // Clear RBUS ETHERNET DMA flag
        heth.Instance->DMACSR = ETH_DMACSR_RBU;
        // Resume DMA reception. The register doesn't care what you write to it.
        heth.Instance->DMACRDTPR = 0;
    }

2) Driver is only one thing - lwIP should work well also. And here is a problem I still can't solve:

Under a quite high network activity (lots of pings and some http/modbus requests) lwIP stops responding. The problem is in tcpip_thread - it hangs and can't fetch anything from the TCPIP mailbox. Checking for the available queue space before sending a packet to this mailbox gives crazy big figures. If I try to reset this mailbox queue after I get error ERR_MEM from sys_mbox_trypost(), then I get a HardFault from FreeRTOS queue function. Tried to play with different FreeRTOS task priorities, but without success.

Please, help me understand how to fix this problem.

RZasa.1 · ‎2022-05-09

Hi,

Is new driver for STM32F4 supposed to work out of the box when generating code in CubeIDE (with RTOS v1)? Once my program hits MX_LWIP_Init(); it gets stuck there (in function prvCheckTasksWaitingTermination). No code after MX_LWIP_Init(); is executed.

I am using NUCLEO-F429ZI with default settings.