Add CompositeEMAC and use it to rewrite STM32 Ethernet MAC driver (#438)

* Start on EMAC rewrite, but realized I can't do zero copy Tx

Make progress on driver

More progress, but I realized that I can't free packets from an ISR...

Driver building, now I can start testing...

Add CompositeEthMac

MAC boots and can send!  Rx not working yet though

Sending and receiving sort of working!

Clean up CTP code to use structs

Fix dumb cache and off by one issues with Rx

Fix a couple memory issues, making progress...

Fix double free when transmission uses more than 1 descriptor

Start adding multicast support

Making progress on multicast support

Multicast filter working!

Tests passing!

Improve mcast filter test

* multicast test working now!

* Working with no hacky workarounds!!!11!11!

* Update Nanostack memory manager, run formatter, make tests test nanostack

* Fix build

* Keep workin' on CompositeEMAC

* Implement GenericEthPhy

* Implement Tx DMA

* Start on Rx DMA

* Finish Rx DMA and multicast subscribes

* Progress on MAC driver

* Initial implementation of MAC driver complete!

* CompositeEMAC inits!

* Phy task and Tx seem to work!

* Rx kinda working

* Almost working! Just missing memory freed callback

* Woring! Add initial support for STM32H5 as well

* Fix STM32H5 init

* Ethernet working on STM32H5!

* Run formatter

* Fix us ticker build error

* Start on MAC v1 driver

* Working on v1 DMA

* Initial implementation of v1 DMA

* Fix some bugs, Tx DMA working but no packets are getting transmitted

* Tx and Rx working!

* Update F2 and F4 eth inits

* Try to fix bank test

* Disable Ethernet in HALs

* Apparently old GCC can't do attribute packed + alignas

* Add RMII watchdog, add power test, fix unittests build

* Debugging EMAC reboot test

* Fix deinit crash on STM32F7

* Fix a couple issues with the power down test

* Start on docs

* Oops missed diagram

* Fix typo

* Bugfix, improve docs

* Fix PNG

* More docs, renames

* More renames, fix !=

* Document Tx DMA

* Fix some DMA bugs:
- Broken check in Tx DMA meant it was always copying packets
- Tx DMA would assert fail from trying to free nullptr if an allocation failed during packet copy
- Rx DMA would not reset firstDescIdx after seeing an error descriptor, leading to an attempt to receive a 0 length packet about 20% of the time we ran the EMAC memory test

* Make EMAC memory test smarter. It now disables pool allocations when disabling input memory, and errors out if the MAC was working when it shouldn't've been.

* Document most of Rx DMA, do rename

* Reformat, fix STM32 Eth v2 potential to have issues when the Tx ring gets full

* Finish documenting Rx DMA

Author: Jamie Smith

connectivity/drivers/emac/CMakeLists.txt

@@ -5,7 +5,12 @@ if(NOT "DEVICE_EMAC=1" IN_LIST MBED_TARGET_DEFINITIONS)
     return()
 endif()
 
-add_library(mbed-emac STATIC EXCLUDE_FROM_ALL)
+add_library(mbed-emac STATIC EXCLUDE_FROM_ALL
+    sources/CompositeEMAC.cpp
+    sources/GenericEthPhy.cpp
+    sources/PhyDrivers.cpp)
+
+target_include_directories(mbed-emac PUBLIC include)
 
 if("ARM_FM" IN_LIST MBED_TARGET_LABELS)
     add_subdirectory(TARGET_ARM_FM)

connectivity/drivers/emac/CompositeEMAC.md

@@ -9,14 +9,28 @@ elseif("STM32F7" IN_LIST MBED_TARGET_LABELS)
     add_subdirectory(TARGET_STM32F7)
 elseif("STM32H7" IN_LIST MBED_TARGET_LABELS)
     add_subdirectory(TARGET_STM32H7)
+elseif("STM32H5" IN_LIST MBED_TARGET_LABELS)
+    add_subdirectory(TARGET_STM32H5)
 endif()
 
 target_include_directories(mbed-emac
     PUBLIC
         .
 )
 
-target_sources(mbed-emac
-    PRIVATE
-        stm32xx_emac.cpp
-)
+if("STM32H7" IN_LIST MBED_TARGET_LABELS OR "STM32H5" IN_LIST MBED_TARGET_LABELS)
+    target_sources(mbed-emac
+        PRIVATE
+            STM32EthMACv2.cpp
+    )
+endif()
+
+if("STM32F2" IN_LIST MBED_TARGET_LABELS OR "STM32F4" IN_LIST MBED_TARGET_LABELS OR "STM32F7" IN_LIST MBED_TARGET_LABELS)
+    target_sources(mbed-emac
+        PRIVATE
+            STM32EthMACv1.cpp
+    )
+endif()
+
+
+target_compile_options(mbed-emac PRIVATE -Wno-packed-bitfield-compat)

connectivity/drivers/emac/TARGET_STM/CMakeLists.txt

@@ -0,0 +1,84 @@
+/* Copyright (c) 2025 Jamie Smith
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "device.h"
+#include "CompositeEMAC.h"
+#include "MbedCRC.h"
+
+// Figure out the Ethernet IP version in use
+#if defined(TARGET_STM32H5) || defined(TARGET_STM32H7)
+#define ETH_IP_VERSION_V2
+#else
+#define ETH_IP_VERSION_V1
+#endif
+
+namespace mbed
+{
+constexpr auto MDIO_TRANSACTION_TIMEOUT = std::chrono::milliseconds(1); // used by STMicro HAL
+
+inline constexpr size_t NUM_PERFECT_FILTER_REGS = 3;
+static const std::pair<volatile uint32_t *, volatile uint32_t *> MAC_ADDR_PERF_FILTER_REGS[NUM_PERFECT_FILTER_REGS] = {
+    {&ETH->MACA1HR, &ETH->MACA1LR},
+    {&ETH->MACA2HR, &ETH->MACA2LR},
+    {&ETH->MACA3HR, &ETH->MACA3LR}
+};
+
+/// Write a MAC address into the given registers with the needed encoding
+static inline void writeMACAddress(const CompositeEMAC::MACAddress & mac, volatile uint32_t *addrHighReg, volatile uint32_t *addrLowReg)
+{
+    /* Set MAC addr bits 32 to 47 */
+    *addrHighReg = (static_cast<uint32_t>(mac[5]) << 8) | static_cast<uint32_t>(mac[4]) | ETH_MACA1HR_AE_Msk;
+    /* Set MAC addr bits 0 to 31 */
+    *addrLowReg = (static_cast<uint32_t>(mac[3]) << 24) | (static_cast<uint32_t>(mac[2]) << 16) |
+                  (static_cast<uint32_t>(mac[1]) << 8) | static_cast<uint32_t>(mac[0]);
+}
+
+/// Add a MAC address to the multicast hash filter.
+void addHashFilterMAC(ETH_TypeDef * base, const CompositeEMAC::MACAddress & mac) {
+#if defined(ETH_IP_VERSION_V2)
+    uint32_t volatile * hashRegs[] = {
+        &base->MACHT0R,
+        &base->MACHT1R
+    };
+#else
+    uint32_t volatile * hashRegs[] = {
+        &base->MACHTLR,
+        &base->MACHTHR
+    };
+#endif
+
+    // Note: as always, the datasheet description of how to do this CRC was vague and slightly wrong.
+    // This forum thread figured it out: https://community.st.com/t5/stm32-mcus-security/calculating-ethernet-multicast-filter-hash-value/td-p/416984
+    // What the datasheet SHOULD say is:
+    // Compute the Ethernet CRC-32 of the MAC address, with initial value of 1s, final XOR of ones, and input reflection on but output reflection off
+    // Then, take the upper 6 bits and use that to index the hash table.
+
+    mbed::MbedCRC<POLY_32BIT_ANSI> crcCalc(0xFFFFFFFF, 0xFFFFFFFF, true, false);
+
+    // Compute Ethernet CRC-32 of the MAC address
+    uint32_t crc;
+    crcCalc.compute(mac.data(), mac.size(), &crc);
+
+    // Take upper 6 bits
+    uint32_t hashVal = crc >> 26;
+
+    // Set correct bit in hash filter
+    *hashRegs[hashVal >> 5] |= (1 << (hashVal & 0x1F));
+}
+
+}