Skip to content

STM32: serialize TX submission with Ethernet state changes - #1371

Draft
kzorer wants to merge 1 commit into
FreeRTOS:mainfrom
kzorer:fix/stm32-tx-state-race
Draft

kzorer wants to merge 1 commit into
FreeRTOS:mainfrom
kzorer:fix/stm32-tx-state-race

Conversation

@kzorer

@kzorer kzorer commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Description

The STM32 network interface checks the PHY link and HAL Ethernet state before waiting for the TX descriptor semaphore and TX mutex. During that interval, the EMAC task can stop or reinitialize Ethernet without taking the TX mutex.

This permits the following task interleaving:

  1. The output function observes HAL_ETH_STATE_STARTED.
  2. The EMAC task processes a link-down or error event and changes the HAL
    state.
  3. The output function calls HAL_ETH_Transmit_IT().
  4. Transmission fails and the existing failure path asserts that the HAL
    state is still HAL_ETH_STATE_STARTED.

This change:

  • Uses the TX mutex to serialize packet submission with runtime HAL initialization, start, stop, and MAC reconfiguration.
  • Rechecks the PHY link, initialization status, and HAL state after acquiring the TX mutex.
  • Handles HAL_ETH_Transmit_IT() failures through the existing normal cleanup path instead of asserting.
  • Restores the TX descriptor semaphore when submission fails.
  • Leaves xReleaseAfterSend set so that the network buffer is released exactly once when HAL has not accepted it.
  • Calls prvReleaseTxPacket() outside the mutex because that function acquires the same mutex internally.

All modifications are isolated to
source/portable/NetworkInterface/STM32/NetworkInterface.c.

Test Steps

Reproduction before the change:

  1. Enable configASSERT.
  2. Generate continuous MCU-originated UDP traffic.
  3. Pause a TX operation after it has acquired xTxMutex.
  4. Allow the EMAC task to process a PHY link-down event and call HAL_ETH_Stop_IT().
  5. Resume TX and observe that HAL_ETH_Transmit_IT() fails and the HAL_ETH_STATE_STARTED assertion is triggered.

Validation for the change:

  1. Repeat the synchronized TX/link-down test.
  2. Verify that the EMAC task waits for xTxMutex.
  3. Verify that TX detects the changed link/state and returns pdFAIL without calling HAL_ETH_Transmit_IT().
  4. Verify that no assertion occurs.
  5. Verify that the network buffer is released exactly once.
  6. Verify that the TX descriptor semaphore returns to its original count.
  7. Reconnect Ethernet and verify that UDP transmission resumes.
  8. Repeat link-down/link-up cycles during continuous MCU-originated UDP traffic and verify that TX does not stall.

Static validation performed:

  • git diff --check passes.
  • The change is confined to the unified STM32 network-interface source.

STM32H745 hardware validation of the patched branch is still pending.

Checklist:

  • I have tested my changes. No regression in existing tests.
  • I have modified and/or added unit-tests to cover the code changes in this Pull Request.

The first item will be checked after completing the STM32H745 hardware validation described above. No STM32 network-interface unit-test harness is currently available in this repository.

Related Issue

None.

Protect runtime HAL init, start, stop, and MAC reconfiguration with the
TX mutex to prevent them from racing with packet submission.

Recheck the link and HAL state after acquiring the mutex, and handle
HAL_ETH_Transmit_IT failures through normal buffer and descriptor cleanup instead of asserting.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant