3 Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 this software and associated documentation files (the "Software"), to deal in
\r
7 the Software without restriction, including without limitation the rights to
\r
8 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 subject to the following conditions:
\r
12 The above copyright notice and this permission notice shall be included in all
\r
13 copies or substantial portions of the Software.
\r
15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 http://aws.amazon.com/freertos
\r
23 http://www.FreeRTOS.org
\r
26 /******************************************************************************
\r
28 * See the following web page for essential buffer allocation scheme usage and
\r
29 * configuration details:
\r
30 * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/Embedded_Ethernet_Buffer_Management.html
\r
32 ******************************************************************************/
\r
34 /* Standard includes. */
\r
37 /* FreeRTOS includes. */
\r
38 #include "FreeRTOS.h"
\r
43 /* FreeRTOS+TCP includes. */
\r
44 #include "FreeRTOS_IP.h"
\r
45 #include "FreeRTOS_IP_Private.h"
\r
46 #include "NetworkInterface.h"
\r
47 #include "NetworkBufferManagement.h"
\r
49 /* For an Ethernet interrupt to be able to obtain a network buffer there must
\r
50 be at least this number of buffers available. */
\r
51 #define baINTERRUPT_BUFFER_GET_THRESHOLD ( 3 )
\r
53 /* A list of free (available) NetworkBufferDescriptor_t structures. */
\r
54 static List_t xFreeBuffersList;
\r
56 /* Some statistics about the use of buffers. */
\r
57 static UBaseType_t uxMinimumFreeNetworkBuffers = 0u;
\r
59 /* Declares the pool of NetworkBufferDescriptor_t structures that are available
\r
60 to the system. All the network buffers referenced from xFreeBuffersList exist
\r
61 in this array. The array is not accessed directly except during initialisation,
\r
62 when the xFreeBuffersList is filled (as all the buffers are free when the system
\r
64 static NetworkBufferDescriptor_t xNetworkBuffers[ ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ];
\r
66 /* This constant is defined as true to let FreeRTOS_TCP_IP.c know that the
\r
67 network buffers have constant size, large enough to hold the biggest Ethernet
\r
68 packet. No resizing will be done. */
\r
69 const BaseType_t xBufferAllocFixedSize = pdTRUE;
\r
71 /* The semaphore used to obtain network buffers. */
\r
72 static SemaphoreHandle_t xNetworkBufferSemaphore = NULL;
\r
74 #if( ipconfigTCP_IP_SANITY != 0 )
\r
75 static char cIsLow = pdFALSE;
\r
76 UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc );
\r
78 static UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc );
\r
79 #endif /* ipconfigTCP_IP_SANITY */
\r
81 static void prvShowWarnings( void );
\r
83 /* The user can define their own ipconfigBUFFER_ALLOC_LOCK() and
\r
84 ipconfigBUFFER_ALLOC_UNLOCK() macros, especially for use form an ISR. If these
\r
85 are not defined then default them to call the normal enter/exit critical
\r
87 #if !defined( ipconfigBUFFER_ALLOC_LOCK )
\r
89 #define ipconfigBUFFER_ALLOC_INIT( ) do {} while (0)
\r
90 #define ipconfigBUFFER_ALLOC_LOCK_FROM_ISR() \
\r
91 UBaseType_t uxSavedInterruptStatus = ( UBaseType_t ) portSET_INTERRUPT_MASK_FROM_ISR(); \
\r
94 #define ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR() \
\r
95 portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus ); \
\r
98 #define ipconfigBUFFER_ALLOC_LOCK() taskENTER_CRITICAL()
\r
99 #define ipconfigBUFFER_ALLOC_UNLOCK() taskEXIT_CRITICAL()
\r
101 #endif /* ipconfigBUFFER_ALLOC_LOCK */
\r
103 /*-----------------------------------------------------------*/
\r
105 #if( ipconfigTCP_IP_SANITY != 0 )
\r
107 /* HT: SANITY code will be removed as soon as the library is stable
\r
108 * and and ready to become public
\r
109 * Function below gives information about the use of buffers */
\r
110 #define WARN_LOW ( 2 )
\r
111 #define WARN_HIGH ( ( 5 * ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ) / 10 )
\r
113 #endif /* ipconfigTCP_IP_SANITY */
\r
115 /*-----------------------------------------------------------*/
\r
117 #if( ipconfigTCP_IP_SANITY != 0 )
\r
119 BaseType_t prvIsFreeBuffer( const NetworkBufferDescriptor_t *pxDescr )
\r
121 return ( bIsValidNetworkDescriptor( pxDescr ) != 0 ) &&
\r
122 ( listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxDescr->xBufferListItem ) ) != 0 );
\r
124 /*-----------------------------------------------------------*/
\r
126 static void prvShowWarnings( void )
\r
128 UBaseType_t uxCount = uxGetNumberOfFreeNetworkBuffers( );
\r
129 if( ( ( cIsLow == 0 ) && ( uxCount <= WARN_LOW ) ) || ( ( cIsLow != 0 ) && ( uxCount >= WARN_HIGH ) ) )
\r
132 FreeRTOS_debug_printf( ( "*** Warning *** %s %lu buffers left\n", cIsLow ? "only" : "now", uxCount ) );
\r
135 /*-----------------------------------------------------------*/
\r
137 UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc )
\r
139 uint32_t offset = ( uint32_t ) ( ((const char *)pxDesc) - ((const char *)xNetworkBuffers) );
\r
140 if( ( offset >= sizeof( xNetworkBuffers ) ) ||
\r
141 ( ( offset % sizeof( xNetworkBuffers[0] ) ) != 0 ) )
\r
143 return (UBaseType_t) (pxDesc - xNetworkBuffers) + 1;
\r
145 /*-----------------------------------------------------------*/
\r
148 static UBaseType_t bIsValidNetworkDescriptor (const NetworkBufferDescriptor_t * pxDesc)
\r
151 return ( UBaseType_t ) pdTRUE;
\r
153 /*-----------------------------------------------------------*/
\r
155 static void prvShowWarnings( void )
\r
158 /*-----------------------------------------------------------*/
\r
160 #endif /* ipconfigTCP_IP_SANITY */
\r
162 BaseType_t xNetworkBuffersInitialise( void )
\r
164 BaseType_t xReturn, x;
\r
166 /* Only initialise the buffers and their associated kernel objects if they
\r
167 have not been initialised before. */
\r
168 if( xNetworkBufferSemaphore == NULL )
\r
170 /* In case alternative locking is used, the mutexes can be initialised
\r
172 ipconfigBUFFER_ALLOC_INIT();
\r
174 xNetworkBufferSemaphore = xSemaphoreCreateCounting( ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS, ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS );
\r
175 configASSERT( xNetworkBufferSemaphore );
\r
177 if( xNetworkBufferSemaphore != NULL )
\r
179 vListInitialise( &xFreeBuffersList );
\r
181 /* Initialise all the network buffers. The buffer storage comes
\r
182 from the network interface, and different hardware has different
\r
184 vNetworkInterfaceAllocateRAMToBuffers( xNetworkBuffers );
\r
185 for( x = 0; x < ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS; x++ )
\r
187 /* Initialise and set the owner of the buffer list items. */
\r
188 vListInitialiseItem( &( xNetworkBuffers[ x ].xBufferListItem ) );
\r
189 listSET_LIST_ITEM_OWNER( &( xNetworkBuffers[ x ].xBufferListItem ), &xNetworkBuffers[ x ] );
\r
191 /* Currently, all buffers are available for use. */
\r
192 vListInsert( &xFreeBuffersList, &( xNetworkBuffers[ x ].xBufferListItem ) );
\r
195 uxMinimumFreeNetworkBuffers = ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS;
\r
199 if( xNetworkBufferSemaphore == NULL )
\r
210 /*-----------------------------------------------------------*/
\r
212 NetworkBufferDescriptor_t *pxGetNetworkBufferWithDescriptor( size_t xRequestedSizeBytes, TickType_t xBlockTimeTicks )
\r
214 NetworkBufferDescriptor_t *pxReturn = NULL;
\r
215 BaseType_t xInvalid = pdFALSE;
\r
216 UBaseType_t uxCount;
\r
218 /* The current implementation only has a single size memory block, so
\r
219 the requested size parameter is not used (yet). */
\r
220 ( void ) xRequestedSizeBytes;
\r
222 if( xNetworkBufferSemaphore != NULL )
\r
224 /* If there is a semaphore available, there is a network buffer
\r
226 if( xSemaphoreTake( xNetworkBufferSemaphore, xBlockTimeTicks ) == pdPASS )
\r
228 /* Protect the structure as they are accessed from tasks and
\r
230 ipconfigBUFFER_ALLOC_LOCK();
\r
232 pxReturn = ( NetworkBufferDescriptor_t * ) listGET_OWNER_OF_HEAD_ENTRY( &xFreeBuffersList );
\r
234 if( ( bIsValidNetworkDescriptor( pxReturn ) != pdFALSE_UNSIGNED ) &&
\r
235 listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxReturn->xBufferListItem ) ) )
\r
237 uxListRemove( &( pxReturn->xBufferListItem ) );
\r
244 ipconfigBUFFER_ALLOC_UNLOCK();
\r
246 if( xInvalid == pdTRUE )
\r
248 /* _RB_ Can printf() be called from an interrupt? (comment
\r
249 above says this can be called from an interrupt too) */
\r
250 /* _HT_ The function shall not be called from an ISR. Comment
\r
251 was indeed misleading. Hopefully clear now?
\r
252 So the printf()is OK here. */
\r
253 FreeRTOS_debug_printf( ( "pxGetNetworkBufferWithDescriptor: INVALID BUFFER: %p (valid %lu)\n",
\r
254 pxReturn, bIsValidNetworkDescriptor( pxReturn ) ) );
\r
259 /* Reading UBaseType_t, no critical section needed. */
\r
260 uxCount = listCURRENT_LIST_LENGTH( &xFreeBuffersList );
\r
262 /* For stats, latch the lowest number of network buffers since
\r
264 if( uxMinimumFreeNetworkBuffers > uxCount )
\r
266 uxMinimumFreeNetworkBuffers = uxCount;
\r
269 pxReturn->xDataLength = xRequestedSizeBytes;
\r
271 #if( ipconfigTCP_IP_SANITY != 0 )
\r
275 #endif /* ipconfigTCP_IP_SANITY */
\r
277 #if( ipconfigUSE_LINKED_RX_MESSAGES != 0 )
\r
279 /* make sure the buffer is not linked */
\r
280 pxReturn->pxNextBuffer = NULL;
\r
282 #endif /* ipconfigUSE_LINKED_RX_MESSAGES */
\r
284 if( xTCPWindowLoggingLevel > 3 )
\r
286 FreeRTOS_debug_printf( ( "BUF_GET[%ld]: %p (%p)\n",
\r
287 bIsValidNetworkDescriptor( pxReturn ),
\r
288 pxReturn, pxReturn->pucEthernetBuffer ) );
\r
291 iptraceNETWORK_BUFFER_OBTAINED( pxReturn );
\r
295 iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER();
\r
301 /*-----------------------------------------------------------*/
\r
303 NetworkBufferDescriptor_t *pxNetworkBufferGetFromISR( size_t xRequestedSizeBytes )
\r
305 NetworkBufferDescriptor_t *pxReturn = NULL;
\r
307 /* The current implementation only has a single size memory block, so
\r
308 the requested size parameter is not used (yet). */
\r
309 ( void ) xRequestedSizeBytes;
\r
311 /* If there is a semaphore available then there is a buffer available, but,
\r
312 as this is called from an interrupt, only take a buffer if there are at
\r
313 least baINTERRUPT_BUFFER_GET_THRESHOLD buffers remaining. This prevents,
\r
314 to a certain degree at least, a rapidly executing interrupt exhausting
\r
315 buffer and in so doing preventing tasks from continuing. */
\r
316 if( uxQueueMessagesWaitingFromISR( ( QueueHandle_t ) xNetworkBufferSemaphore ) > ( UBaseType_t ) baINTERRUPT_BUFFER_GET_THRESHOLD )
\r
318 if( xSemaphoreTakeFromISR( xNetworkBufferSemaphore, NULL ) == pdPASS )
\r
320 /* Protect the structure as it is accessed from tasks and interrupts. */
\r
321 ipconfigBUFFER_ALLOC_LOCK_FROM_ISR();
\r
323 pxReturn = ( NetworkBufferDescriptor_t * ) listGET_OWNER_OF_HEAD_ENTRY( &xFreeBuffersList );
\r
324 uxListRemove( &( pxReturn->xBufferListItem ) );
\r
326 ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR();
\r
328 iptraceNETWORK_BUFFER_OBTAINED_FROM_ISR( pxReturn );
\r
332 if( pxReturn == NULL )
\r
334 iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER_FROM_ISR();
\r
339 /*-----------------------------------------------------------*/
\r
341 BaseType_t vNetworkBufferReleaseFromISR( NetworkBufferDescriptor_t * const pxNetworkBuffer )
\r
343 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
\r
345 /* Ensure the buffer is returned to the list of free buffers before the
\r
346 counting semaphore is 'given' to say a buffer is available. */
\r
347 ipconfigBUFFER_ALLOC_LOCK_FROM_ISR();
\r
349 vListInsertEnd( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
\r
351 ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR();
\r
353 xSemaphoreGiveFromISR( xNetworkBufferSemaphore, &xHigherPriorityTaskWoken );
\r
354 iptraceNETWORK_BUFFER_RELEASED( pxNetworkBuffer );
\r
356 return xHigherPriorityTaskWoken;
\r
358 /*-----------------------------------------------------------*/
\r
360 void vReleaseNetworkBufferAndDescriptor( NetworkBufferDescriptor_t * const pxNetworkBuffer )
\r
362 BaseType_t xListItemAlreadyInFreeList;
\r
364 if( bIsValidNetworkDescriptor( pxNetworkBuffer ) == pdFALSE_UNSIGNED )
\r
366 FreeRTOS_debug_printf( ( "vReleaseNetworkBufferAndDescriptor: Invalid buffer %p\n", pxNetworkBuffer ) );
\r
369 /* Ensure the buffer is returned to the list of free buffers before the
\r
370 counting semaphore is 'given' to say a buffer is available. */
\r
371 ipconfigBUFFER_ALLOC_LOCK();
\r
374 xListItemAlreadyInFreeList = listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
\r
376 if( xListItemAlreadyInFreeList == pdFALSE )
\r
378 vListInsertEnd( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
\r
382 ipconfigBUFFER_ALLOC_UNLOCK();
\r
384 if( xListItemAlreadyInFreeList )
\r
386 FreeRTOS_debug_printf( ( "vReleaseNetworkBufferAndDescriptor: %p ALREADY RELEASED (now %lu)\n",
\r
387 pxNetworkBuffer, uxGetNumberOfFreeNetworkBuffers( ) ) );
\r
389 if( xListItemAlreadyInFreeList == pdFALSE )
\r
391 xSemaphoreGive( xNetworkBufferSemaphore );
\r
393 if( xTCPWindowLoggingLevel > 3 )
\r
394 FreeRTOS_debug_printf( ( "BUF_PUT[%ld]: %p (%p) (now %lu)\n",
\r
395 bIsValidNetworkDescriptor( pxNetworkBuffer ),
\r
396 pxNetworkBuffer, pxNetworkBuffer->pucEthernetBuffer,
\r
397 uxGetNumberOfFreeNetworkBuffers( ) ) );
\r
399 iptraceNETWORK_BUFFER_RELEASED( pxNetworkBuffer );
\r
401 /*-----------------------------------------------------------*/
\r
403 UBaseType_t uxGetMinimumFreeNetworkBuffers( void )
\r
405 return uxMinimumFreeNetworkBuffers;
\r
407 /*-----------------------------------------------------------*/
\r
409 UBaseType_t uxGetNumberOfFreeNetworkBuffers( void )
\r
411 return listCURRENT_LIST_LENGTH( &xFreeBuffersList );
\r
414 NetworkBufferDescriptor_t *pxResizeNetworkBufferWithDescriptor( NetworkBufferDescriptor_t * pxNetworkBuffer, size_t xNewSizeBytes )
\r
416 /* In BufferAllocation_1.c all network buffer are allocated with a
\r
417 maximum size of 'ipTOTAL_ETHERNET_FRAME_SIZE'.No need to resize the
\r
419 ( void ) xNewSizeBytes;
\r
420 return pxNetworkBuffer;
\r
423 /*#endif */ /* ipconfigINCLUDE_TEST_CODE */
\r