[BUG]

[kzorer]

Reopen: Zero‑copy RX driver fails to allocate buffers on STM32H7xxx due to padding logic

Description

When building FreeRTOS+TCP with ipconfigZERO_COPY_RX_DRIVER=1 on STM32H7xxx, pucGetRXBuffer() always returns NULL and triggers the configASSERT() in the zero‑copy path. The failure appears to stem from the way buffers are sliced up in uxNetworkInterfaceAllocateRAMToBuffers():

size_t uxNetworkInterfaceAllocateRAMToBuffers( NetworkBufferDescriptor_t pxNetworkBuffers[ ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ] )
{
    uint8_t * ucRAMBuffer = ucNetworkPackets;
    for( uint32_t ul = 0; ul < ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS; ul++ )
    {
        pxNetworkBuffers[ ul ].pucEthernetBuffer = ucRAMBuffer + ipBUFFER_PADDING;
        *( ( unsigned * ) ucRAMBuffer ) = ( unsigned ) ( &( pxNetworkBuffers[ ul ] ) );
        ucRAMBuffer += ETH_RX_BUF_SIZE;
    }
    return( ETH_RX_BUF_SIZE - ipBUFFER_PADDING );
}

Because ipBUFFER_PADDING = 8 + ipconfigPACKET_FILLER_SIZE, each descriptor’s “usable” buffer pointer gets offset in a way that, combined with STM32H7 DMA/cache requirements, results in no valid buffers being handed out, so pucGetRXBuffer() always returns NULL.

Note: It appears that this issue affects version 4.2.4 in the LTS release—using the LTS version is broken.

Steps to Reproduce

1. In FreeRTOSIPConfig.h, set:

#define ipconfigZERO_COPY_RX_DRIVER 1
#define ipconfigPACKET_FILLER_SIZE 2
#define ipconfigBUFFER_PADDING 0
#define ETH_RX_BUF_SIZE 1536
#define ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS  64

2. Place the ucNetworkPackets[] buffer array in DTCM or mark SRAM as non‑cacheable via the MPU.
3. Call FreeRTOS_IPInit(), then generate Ethernet traffic into the STM32H7 MAC.
4. Observe the assertion:

pucBuffer = pucGetRXBuffer( ETH_RX_BUF_SIZE );
configASSERT( pucBuffer != NULL );  // << fails here

Expected behavior

pucGetRXBuffer() should return a valid pointer to the received Ethernet frame buffer, and the zero‑copy path should hand it off to the HAL without triggering an assertion.

Actual Behavior

pucGetRXBuffer() returns NULL immediately, causing the configASSERT() to fire and preventing any packets from being processed.

Environment

MCU: STM32H7xxx (e.g. STM32H743ZI)
FreeRTOS+TCP: v4.2.4 (LTS release)

[jasonpcarroll]

Hi @kzorer,
Would you want to open a PR fixing the issue?
Best,
Jason

[htibosch]

pucGetRXBuffer() will return NULL when all network buffers have been taken by pxGetNetworkBufferWithDescriptor().
This can be caused by a configuration problem, or by not releasing buffers.

What is the value of ETH_RX_DESC_CNT / ETH_TX_DESC_CNT? Can you trace the usage of buffers? How many time did pucGetRXBuffer() return a buffer?

The famous +2 offset and Ethernet:

In most Ethernet peripherals, a 32-bit aligned pointer +2 bytes is passed to Ethernet DMA. The reason is that later 32-bit fields (IP/TCP/UDP/ICMP etc) get well aligned.

In other Ethernet peripherals, an aligned pointer is sent to DMA, and the first 2 bytes remain unused.

The FreeRTOS IP-stack assumes that 4-byte values are well aligned.

The header looks like this:

    intptr_t owner;         // A pointer to the struct owning this buffer
    uint32_t filler_32;
    uint16_t filler_16;
/* pucEthernetBuffer points to here. */
    uint8_t ethernet_dest[6];
    uint8_t ethernet_source[6];
    uint16_t frame_type;
/* 32-bit aligned /
    uint8_t ucVersionHeaderLength;        /**< The version field + internet header length 0 + 1 =  1 */
    uint8_t ucDifferentiatedServicesCode; /**< Differentiated services code point + ECN   1 + 1 =  2 */
    uint16_t usLength;                    /**< Entire Packet size, ex. Ethernet header.   2 + 2 =  4 */

[kzorer]

Our Ethernet configuration is unchanged from before—only the FreeRTOS+TCP version was bumped from v4.2.2 to v4.2.4. Below are the relevant settings:

/* ########################### Ethernet Configuration ######################### */
#define ETH_TX_DESC_CNT    16U   /* number of Ethernet Tx DMA descriptors */
#define ETH_RX_DESC_CNT     8U   /* number of Ethernet Rx DMA descriptors */

• FreeRTOSIPConfig.h: No values were modified after the upgrade.
• Observed behavior: Immediately after switching to v4.2.4, the very first call to pucGetRXBuffer() returns NULL under identical load conditions.

Could you please confirm whether any changes were introduced in v4.2.4 related to buffer management—such as descriptor counts, alignment offsets, or allocation logic—that might explain this issue?

[htibosch]

Your wrote:

/* ########################### Ethernet Configuration ######################### */
#define ETH_TX_DESC_CNT    16U   /* number of Ethernet Tx DMA descriptors */
#define ETH_RX_DESC_CNT     8U   /* number of Ethernet Rx DMA descriptors */

The following values are preferred:

#define ETH_TX_DESC_CNT    2U
#define ETH_RX_DESC_CNT   12U

That will not solve the problem, but it is more efficient.
Transmission: when the DMA queue has 2 descriptors, there will rarely be a shortage. And if both descriptors are found occupied, the program will wait in xSemaphoreTake():

if( xSemaphoreTake( xTxDescSem, pdMS_TO_TICKS( niEMAC_DESCRIPTOR_WAIT_TIME_MS ) ) == pdFALSE )
{
    FreeRTOS_debug_printf( ( "xNetworkInterfaceOutput: No Descriptors Available\n" ) );
    break;
}

It is much more useful to have enough RX descriptors. Incoming packets will be discarded when all RX descriptors are found full.

I tend to tune the value for ETH_RX_DESC_CNT: in the Legacy version it remembers the highest usage of RX descriptors.

The above probably won't solve your problem. I will download the 2 versions and see if I find a problematic change.

[htibosch]

I think that here things go wrong:

NetworkBufferDescriptor_t * pxGetNetworkBufferWithDescriptor( size_t xRequestedSizeBytes,
                                                              TickType_t xBlockTimeTicks )
{
    NetworkBufferDescriptor_t * pxReturn = NULL;
    BaseType_t xInvalid = pdFALSE;
    UBaseType_t uxCount;

    if( ( xNetworkBufferSemaphore != NULL ) &&
        ( xRequestedSizeBytes <= uxMaxNetworkInterfaceAllocatedSizeBytes ) )
    {
        'uxMaxNetworkInterfaceAllocatedSizeBytes' is set at 1526 bytes, which is
        the buffer size - 'ipBUFFER_PADDING'
    }
    else
    {
        /* My program lands here */
        /* semaphore not or created, or requesting too many bytes,
		1536 in stead of the maximum 1526. */
    }

I propose to change the following in the function xSTM32H_NetworkInterfaceInitialise():

 /* Assign Rx memory buffers to a DMA Rx descriptor */
 for( uxIndex = 0; uxIndex < ETH_RX_DESC_CNT; uxIndex++ )
 {
     uint8_t * pucBuffer;
 
     #if ( ipconfigZERO_COPY_RX_DRIVER != 0 )
     {
-        pucBuffer = pucGetRXBuffer( ETH_RX_BUF_SIZE );
+        pucBuffer = pucGetRXBuffer( ETH_RX_BUF_SIZE - ipBUFFER_PADDING );
         configASSERT( pucBuffer != NULL );
     }
     #else
     {
         pucBuffer = Rx_Buff[ uxIndex ];
     }
     #endif

In the function uxNetworkInterfaceAllocateRAMToBuffers(), we allocate memory for all network buffers.
Each block is 1536 (ETH_RX_BUF_SIZE) bytes, but the first 10 bytes (ipBUFFER_PADDING) are reserved for administration.
So the following function is enitrely correct:

size_t uxNetworkInterfaceAllocateRAMToBuffers( NetworkBufferDescriptor_t pxNetworkBuffers[ ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ] )
{
    uint8_t * ucRAMBuffer = ucNetworkPackets;
    uint32_t ul;

    for( ul = 0; ul < ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS; ul++ )
    {
        pxNetworkBuffers[ ul ].pucEthernetBuffer = ucRAMBuffer + ipBUFFER_PADDING;
        *( ( unsigned * ) ucRAMBuffer ) = ( unsigned ) ( &( pxNetworkBuffers[ ul ] ) );
        ucRAMBuffer += ETH_RX_BUF_SIZE;
    }

    return( ETH_RX_BUF_SIZE - ipBUFFER_PADDING );
}
/*-----------------------------------------------------------*/

EDIT Before turning this into a PR, I will check the changes and run it on my STM32H7.

[htibosch]

One more change will be necessary to make the zero-copy-rx method working:

 static BaseType_t prvNetworkInterfaceInput( void )
 {
     ...
     #if ( ipconfigZERO_COPY_RX_DRIVER != 0 )
     {
         /* Reserve the maximum length for the next reception. */
-        uxLength = ETH_RX_BUF_SIZE;
+        uxLength = ETH_RX_BUF_SIZE - ipBUFFER_PADDING;

        if( data_buffer.buffer != NULL )
        {
        }
     }
     ...
}

The above change should be applied to NetworkInterface/STM32Hxx/NetworkInterface.c in release 4.2.4

Just te be sure, here is the version that I used while testing:

STM32H7_NetworkInterface.zip

History:

V4.3.999 today
V4.3.3   Jun 10
V4.2.4   Jun 10 FreeRTOSv202406.03-LTS
V4.2.3   Jun 5
V4.3.2   Jun 4  queries with very long DNS names
V4.3.1   Dec 17, 2024

As far as I can see, the problem started in June this year when uxNetworkInterfaceAllocateRAMToBuffers() started returning the nett buffer length, which was a good change of course.

The good thing: this is a bug that always shows up within the first minute. And it is fatal.

Some warning would have saved a lot of debug time though:

     if( ( xNetworkBufferSemaphore != NULL ) &&
         ( xRequestedSizeBytes <= uxMaxNetworkInterfaceAllocatedSizeBytes ) )
     {
     }
     else
     {
         /* lint wants to see at least a comment. */
         iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER();
+        FreeRTOS_printf( ( "pxGetNetworkBufferWithDescriptor: size check failed\n" ) );
    }

@kzorer, thank you for reporting this bug.
Could you test your project with the 2 changes mentioned here above? Then we can proceed and create a PR.

[kzorer]

Hi @htibosch,

I’ve applied both of your patches on top of release 4.2.4—the reduction of uxLength by ipBUFFER_PADDING in prvNetworkInterfaceInput(), and the extra FreeRTOS_printf() in the buffer‐allocation failure path. I can confirm that no configASSERT() ever fires now, so that part looks good.

However, in our application we have a hardware watchdog that must be “kicked” at a regular interval, and after integrating your changes the MCU now always resets when the watchdog timeout expires. It seems like somewhere in the modified network code the scheduler is being held too long (or a key task is being starved) so that our watchdog‐feeding hook never gets a chance to run.

A few possibilities I’m looking at:

• Zero‑copy RX path: by shrinking uxLength we may have inadvertently changed the timing of packet reception or buffer release—if the network task loops without yielding, lower‐priority hooks (like our watchdog feeder) could be blocked.
• Buffer release timing: if vReleaseNetworkBufferAndDescriptor() now happens later (or under different conditions), it could delay the TCP/IP stack’s own internal housekeeping, which in turn might prevent the timer‐service task from running.

Could you advise:

• Have you observed any long, unbroken execution paths in the zero‑copy receive routine that might starve lower‑priority work?
• Would you recommend adding an explicit taskYIELD() or vTaskDelay(0) in prvNetworkInterfaceInput() after processing a packet?

Any pointers would be greatly appreciated. Thanks!

[kzorer]

Hi again @htibosch,

I found the problem: because of the missing call ipconfigEMAC_WATCHDOG_TIMER(), the hardware watchdog isn’t being serviced. As I recall, I added it in earlier versions. May I open a PR to restore it so that everything works correctly?

...
            else
            {
                /* Something has changed to a Link Status, need re-check. */
                prvEthernetUpdateConfig( pdFALSE );
            }
        }
        ipconfigEMAC_WATCHDOG_TIMER();
    }
}
...

[htibosch]

May I open a PR to restore it so that everything works correctly?

Go ahead. And why not give is to these files as well:

\STM32\Legacy\STM32Fxx\NetworkInterface.c
\STM32\NetworkInterface.c

Thanks for reporting and cooperating while debugging.

Hein

[kzorer]

Hi @htibosch,

I’ve fixed the Ethernet issue for STM32 in version v4.2.4 and pushed my changes to a branch called fix-v4.2.4 in my forked repository. Could you please advise on the best way to open a pull request from this branch into the v4.2.4 branch? When I try to merge into the main branch, I encounter many conflicts.

• Should I target the v4.2.4 tag directly?
• Is there a specific branch naming or workflow convention I should follow?

Thanks in advance for your help!