git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP/portable/BufferManagement/BufferAllocation_1.c

   1 /*
   2 FreeRTOS+TCP V2.0.11
   3 Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
   4
   5 Permission is hereby granted, free of charge, to any person obtaining a copy of
   6 this software and associated documentation files (the "Software"), to deal in
   7 the Software without restriction, including without limitation the rights to
   8 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
   9 the Software, and to permit persons to whom the Software is furnished to do so,
  10 subject to the following conditions:
  11
  12 The above copyright notice and this permission notice shall be included in all
  13 copies or substantial portions of the Software.
  14
  15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  17 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  18 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  19 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21
  22  http://aws.amazon.com/freertos
  23  http://www.FreeRTOS.org
  24 */
  25
  26 /******************************************************************************
  27  *
  28  * See the following web page for essential buffer allocation scheme usage and
  29  * configuration details:
  30  * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/Embedded_Ethernet_Buffer_Management.html
  31  *
  32  ******************************************************************************/
  33
  34 /* Standard includes. */
  35 #include <stdint.h>
  36
  37 /* FreeRTOS includes. */
  38 #include "FreeRTOS.h"
  39 #include "task.h"
  40 #include "queue.h"
  41 #include "semphr.h"
  42
  43 /* FreeRTOS+TCP includes. */
  44 #include "FreeRTOS_IP.h"
  45 #include "FreeRTOS_IP_Private.h"
  46 #include "NetworkInterface.h"
  47 #include "NetworkBufferManagement.h"
  48
  49 /* For an Ethernet interrupt to be able to obtain a network buffer there must
  50 be at least this number of buffers available. */
  51 #define baINTERRUPT_BUFFER_GET_THRESHOLD        ( 3 )
  52
  53 /* A list of free (available) NetworkBufferDescriptor_t structures. */
  54 static List_t xFreeBuffersList;
  55
  56 /* Some statistics about the use of buffers. */
  57 static UBaseType_t uxMinimumFreeNetworkBuffers = 0u;
  58
  59 /* Declares the pool of NetworkBufferDescriptor_t structures that are available
  60 to the system.  All the network buffers referenced from xFreeBuffersList exist
  61 in this array.  The array is not accessed directly except during initialisation,
  62 when the xFreeBuffersList is filled (as all the buffers are free when the system
  63 is booted). */
  64 static NetworkBufferDescriptor_t xNetworkBuffers[ ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ];
  65
  66 /* This constant is defined as true to let FreeRTOS_TCP_IP.c know that the
  67 network buffers have constant size, large enough to hold the biggest Ethernet
  68 packet. No resizing will be done. */
  69 const BaseType_t xBufferAllocFixedSize = pdTRUE;
  70
  71 /* The semaphore used to obtain network buffers. */
  72 static SemaphoreHandle_t xNetworkBufferSemaphore = NULL;
  73
  74 #if( ipconfigTCP_IP_SANITY != 0 )
  75         static char cIsLow = pdFALSE;
  76         UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc );
  77 #else
  78         static UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc );
  79 #endif /* ipconfigTCP_IP_SANITY */
  80
  81 static void prvShowWarnings( void );
  82
  83 /* The user can define their own ipconfigBUFFER_ALLOC_LOCK() and
  84 ipconfigBUFFER_ALLOC_UNLOCK() macros, especially for use form an ISR.  If these
  85 are not defined then default them to call the normal enter/exit critical
  86 section macros. */
  87 #if !defined( ipconfigBUFFER_ALLOC_LOCK )
  88
  89         #define ipconfigBUFFER_ALLOC_INIT( ) do {} while (0)
  90         #define ipconfigBUFFER_ALLOC_LOCK_FROM_ISR()            \
  91                 UBaseType_t uxSavedInterruptStatus = ( UBaseType_t ) portSET_INTERRUPT_MASK_FROM_ISR(); \
  92                 {
  93
  94         #define ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR()          \
  95                         portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus ); \
  96                 }
  97
  98         #define ipconfigBUFFER_ALLOC_LOCK()                                     taskENTER_CRITICAL()
  99         #define ipconfigBUFFER_ALLOC_UNLOCK()                           taskEXIT_CRITICAL()
 100
 101 #endif /* ipconfigBUFFER_ALLOC_LOCK */
 102
 103 /*-----------------------------------------------------------*/
 104
 105 #if( ipconfigTCP_IP_SANITY != 0 )
 106
 107         /* HT: SANITY code will be removed as soon as the library is stable
 108          * and and ready to become public
 109          * Function below gives information about the use of buffers */
 110         #define WARN_LOW                ( 2 )
 111         #define WARN_HIGH               ( ( 5 * ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS ) / 10 )
 112
 113 #endif /* ipconfigTCP_IP_SANITY */
 114
 115 /*-----------------------------------------------------------*/
 116
 117 #if( ipconfigTCP_IP_SANITY != 0 )
 118
 119         BaseType_t prvIsFreeBuffer( const NetworkBufferDescriptor_t *pxDescr )
 120         {
 121                 return ( bIsValidNetworkDescriptor( pxDescr ) != 0 ) &&
 122                         ( listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxDescr->xBufferListItem ) ) != 0 );
 123         }
 124         /*-----------------------------------------------------------*/
 125
 126         static void prvShowWarnings( void )
 127         {
 128                 UBaseType_t uxCount = uxGetNumberOfFreeNetworkBuffers( );
 129                 if( ( ( cIsLow == 0 ) && ( uxCount <= WARN_LOW ) ) || ( ( cIsLow != 0 ) && ( uxCount >= WARN_HIGH ) ) )
 130                 {
 131                         cIsLow = !cIsLow;
 132                         FreeRTOS_debug_printf( ( "*** Warning *** %s %lu buffers left\n", cIsLow ? "only" : "now", uxCount ) );
 133                 }
 134         }
 135         /*-----------------------------------------------------------*/
 136
 137         UBaseType_t bIsValidNetworkDescriptor( const NetworkBufferDescriptor_t * pxDesc )
 138         {
 139                 uint32_t offset = ( uint32_t ) ( ((const char *)pxDesc) - ((const char *)xNetworkBuffers) );
 140                 if( ( offset >= sizeof( xNetworkBuffers ) ) ||
 141                         ( ( offset % sizeof( xNetworkBuffers[0] ) ) != 0 ) )
 142                         return pdFALSE;
 143                 return (UBaseType_t) (pxDesc - xNetworkBuffers) + 1;
 144         }
 145         /*-----------------------------------------------------------*/
 146
 147 #else
 148         static UBaseType_t bIsValidNetworkDescriptor (const NetworkBufferDescriptor_t * pxDesc)
 149         {
 150                 ( void ) pxDesc;
 151                 return ( UBaseType_t ) pdTRUE;
 152         }
 153         /*-----------------------------------------------------------*/
 154
 155         static void prvShowWarnings( void )
 156         {
 157         }
 158         /*-----------------------------------------------------------*/
 159
 160 #endif /* ipconfigTCP_IP_SANITY */
 161
 162 BaseType_t xNetworkBuffersInitialise( void )
 163 {
 164 BaseType_t xReturn, x;
 165
 166         /* Only initialise the buffers and their associated kernel objects if they
 167         have not been initialised before. */
 168         if( xNetworkBufferSemaphore == NULL )
 169         {
 170                 /* In case alternative locking is used, the mutexes can be initialised
 171                 here */
 172                 ipconfigBUFFER_ALLOC_INIT();
 173
 174                 xNetworkBufferSemaphore = xSemaphoreCreateCounting( ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS, ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS );
 175                 configASSERT( xNetworkBufferSemaphore );
 176
 177                 if( xNetworkBufferSemaphore != NULL )
 178                 {
 179                         vListInitialise( &xFreeBuffersList );
 180
 181                         /* Initialise all the network buffers.  The buffer storage comes
 182                         from the network interface, and different hardware has different
 183                         requirements. */
 184                         vNetworkInterfaceAllocateRAMToBuffers( xNetworkBuffers );
 185                         for( x = 0; x < ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS; x++ )
 186                         {
 187                                 /* Initialise and set the owner of the buffer list items. */
 188                                 vListInitialiseItem( &( xNetworkBuffers[ x ].xBufferListItem ) );
 189                                 listSET_LIST_ITEM_OWNER( &( xNetworkBuffers[ x ].xBufferListItem ), &xNetworkBuffers[ x ] );
 190
 191                                 /* Currently, all buffers are available for use. */
 192                                 vListInsert( &xFreeBuffersList, &( xNetworkBuffers[ x ].xBufferListItem ) );
 193                         }
 194
 195                         uxMinimumFreeNetworkBuffers = ( UBaseType_t ) ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS;
 196                 }
 197         }
 198
 199         if( xNetworkBufferSemaphore == NULL )
 200         {
 201                 xReturn = pdFAIL;
 202         }
 203         else
 204         {
 205                 xReturn = pdPASS;
 206         }
 207
 208         return xReturn;
 209 }
 210 /*-----------------------------------------------------------*/
 211
 212 NetworkBufferDescriptor_t *pxGetNetworkBufferWithDescriptor( size_t xRequestedSizeBytes, TickType_t xBlockTimeTicks )
 213 {
 214 NetworkBufferDescriptor_t *pxReturn = NULL;
 215 BaseType_t xInvalid = pdFALSE;
 216 UBaseType_t uxCount;
 217
 218         /* The current implementation only has a single size memory block, so
 219         the requested size parameter is not used (yet). */
 220         ( void ) xRequestedSizeBytes;
 221
 222         if( xNetworkBufferSemaphore != NULL )
 223         {
 224                 /* If there is a semaphore available, there is a network buffer
 225                 available. */
 226                 if( xSemaphoreTake( xNetworkBufferSemaphore, xBlockTimeTicks ) == pdPASS )
 227                 {
 228                         /* Protect the structure as they are accessed from tasks and
 229                         interrupts. */
 230                         ipconfigBUFFER_ALLOC_LOCK();
 231                         {
 232                                 pxReturn = ( NetworkBufferDescriptor_t * ) listGET_OWNER_OF_HEAD_ENTRY( &xFreeBuffersList );
 233
 234                                 if( ( bIsValidNetworkDescriptor( pxReturn ) != pdFALSE_UNSIGNED ) &&
 235                                         listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxReturn->xBufferListItem ) ) )
 236                                 {
 237                                         uxListRemove( &( pxReturn->xBufferListItem ) );
 238                                 }
 239                                 else
 240                                 {
 241                                         xInvalid = pdTRUE;
 242                                 }
 243                         }
 244                         ipconfigBUFFER_ALLOC_UNLOCK();
 245
 246                         if( xInvalid == pdTRUE )
 247                         {
 248                                 /* _RB_ Can printf() be called from an interrupt?  (comment
 249                                 above says this can be called from an interrupt too) */
 250                                 /* _HT_ The function shall not be called from an ISR. Comment
 251                                 was indeed misleading. Hopefully clear now?
 252                                 So the printf()is OK here. */
 253                                 FreeRTOS_debug_printf( ( "pxGetNetworkBufferWithDescriptor: INVALID BUFFER: %p (valid %lu)\n",
 254                                         pxReturn, bIsValidNetworkDescriptor( pxReturn ) ) );
 255                                 pxReturn = NULL;
 256                         }
 257                         else
 258                         {
 259                                 /* Reading UBaseType_t, no critical section needed. */
 260                                 uxCount = listCURRENT_LIST_LENGTH( &xFreeBuffersList );
 261
 262                                 /* For stats, latch the lowest number of network buffers since
 263                                 booting. */
 264                                 if( uxMinimumFreeNetworkBuffers > uxCount )
 265                                 {
 266                                         uxMinimumFreeNetworkBuffers = uxCount;
 267                                 }
 268
 269                                 pxReturn->xDataLength = xRequestedSizeBytes;
 270
 271                                 #if( ipconfigTCP_IP_SANITY != 0 )
 272                                 {
 273                                         prvShowWarnings();
 274                                 }
 275                                 #endif /* ipconfigTCP_IP_SANITY */
 276
 277                                 #if( ipconfigUSE_LINKED_RX_MESSAGES != 0 )
 278                                 {
 279                                         /* make sure the buffer is not linked */
 280                                         pxReturn->pxNextBuffer = NULL;
 281                                 }
 282                                 #endif /* ipconfigUSE_LINKED_RX_MESSAGES */
 283                         }
 284                         iptraceNETWORK_BUFFER_OBTAINED( pxReturn );
 285                 }
 286                 else
 287                 {
 288                         iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER();
 289                 }
 290         }
 291
 292         return pxReturn;
 293 }
 294 /*-----------------------------------------------------------*/
 295
 296 NetworkBufferDescriptor_t *pxNetworkBufferGetFromISR( size_t xRequestedSizeBytes )
 297 {
 298 NetworkBufferDescriptor_t *pxReturn = NULL;
 299
 300         /* The current implementation only has a single size memory block, so
 301         the requested size parameter is not used (yet). */
 302         ( void ) xRequestedSizeBytes;
 303
 304         /* If there is a semaphore available then there is a buffer available, but,
 305         as this is called from an interrupt, only take a buffer if there are at
 306         least baINTERRUPT_BUFFER_GET_THRESHOLD buffers remaining.  This prevents,
 307         to a certain degree at least, a rapidly executing interrupt exhausting
 308         buffer and in so doing preventing tasks from continuing. */
 309         if( uxQueueMessagesWaitingFromISR( ( QueueHandle_t ) xNetworkBufferSemaphore ) > ( UBaseType_t ) baINTERRUPT_BUFFER_GET_THRESHOLD )
 310         {
 311                 if( xSemaphoreTakeFromISR( xNetworkBufferSemaphore, NULL ) == pdPASS )
 312                 {
 313                         /* Protect the structure as it is accessed from tasks and interrupts. */
 314                         ipconfigBUFFER_ALLOC_LOCK_FROM_ISR();
 315                         {
 316                                 pxReturn = ( NetworkBufferDescriptor_t * ) listGET_OWNER_OF_HEAD_ENTRY( &xFreeBuffersList );
 317                                 uxListRemove( &( pxReturn->xBufferListItem ) );
 318                         }
 319                         ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR();
 320
 321                         iptraceNETWORK_BUFFER_OBTAINED_FROM_ISR( pxReturn );
 322                 }
 323         }
 324
 325         if( pxReturn == NULL )
 326         {
 327                 iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER_FROM_ISR();
 328         }
 329
 330         return pxReturn;
 331 }
 332 /*-----------------------------------------------------------*/
 333
 334 BaseType_t vNetworkBufferReleaseFromISR( NetworkBufferDescriptor_t * const pxNetworkBuffer )
 335 {
 336 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
 337
 338         /* Ensure the buffer is returned to the list of free buffers before the
 339         counting semaphore is 'given' to say a buffer is available. */
 340         ipconfigBUFFER_ALLOC_LOCK_FROM_ISR();
 341         {
 342                 vListInsertEnd( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
 343         }
 344         ipconfigBUFFER_ALLOC_UNLOCK_FROM_ISR();
 345
 346         xSemaphoreGiveFromISR( xNetworkBufferSemaphore, &xHigherPriorityTaskWoken );
 347         iptraceNETWORK_BUFFER_RELEASED( pxNetworkBuffer );
 348
 349         return xHigherPriorityTaskWoken;
 350 }
 351 /*-----------------------------------------------------------*/
 352
 353 void vReleaseNetworkBufferAndDescriptor( NetworkBufferDescriptor_t * const pxNetworkBuffer )
 354 {
 355 BaseType_t xListItemAlreadyInFreeList;
 356
 357         if( bIsValidNetworkDescriptor( pxNetworkBuffer ) == pdFALSE_UNSIGNED )
 358         {
 359                 FreeRTOS_debug_printf( ( "vReleaseNetworkBufferAndDescriptor: Invalid buffer %p\n", pxNetworkBuffer ) );
 360                 return ;
 361         }
 362         /* Ensure the buffer is returned to the list of free buffers before the
 363         counting semaphore is 'given' to say a buffer is available. */
 364         ipconfigBUFFER_ALLOC_LOCK();
 365         {
 366                 {
 367                         xListItemAlreadyInFreeList = listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
 368
 369                         if( xListItemAlreadyInFreeList == pdFALSE )
 370                         {
 371                                 vListInsertEnd( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );
 372                         }
 373                 }
 374         }
 375         ipconfigBUFFER_ALLOC_UNLOCK();
 376
 377         if( xListItemAlreadyInFreeList )
 378         {
 379                 FreeRTOS_debug_printf( ( "vReleaseNetworkBufferAndDescriptor: %p ALREADY RELEASED (now %lu)\n",
 380                         pxNetworkBuffer, uxGetNumberOfFreeNetworkBuffers( ) ) );
 381         }
 382         if( xListItemAlreadyInFreeList == pdFALSE )
 383         {
 384                 xSemaphoreGive( xNetworkBufferSemaphore );
 385                 prvShowWarnings();
 386         }
 387         iptraceNETWORK_BUFFER_RELEASED( pxNetworkBuffer );
 388 }
 389 /*-----------------------------------------------------------*/
 390
 391 UBaseType_t uxGetMinimumFreeNetworkBuffers( void )
 392 {
 393         return uxMinimumFreeNetworkBuffers;
 394 }
 395 /*-----------------------------------------------------------*/
 396
 397 UBaseType_t uxGetNumberOfFreeNetworkBuffers( void )
 398 {
 399         return listCURRENT_LIST_LENGTH( &xFreeBuffersList );
 400 }
 401
 402 NetworkBufferDescriptor_t *pxResizeNetworkBufferWithDescriptor( NetworkBufferDescriptor_t * pxNetworkBuffer, size_t xNewSizeBytes )
 403 {
 404         /* In BufferAllocation_1.c all network buffer are allocated with a
 405         maximum size of 'ipTOTAL_ETHERNET_FRAME_SIZE'.No need to resize the
 406         network buffer. */
 407         ( void ) xNewSizeBytes;
 408         return pxNetworkBuffer;
 409 }
 410
 411 /*#endif */ /* ipconfigINCLUDE_TEST_CODE */