git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-UDP/portable/BufferManagement/BufferAllocation_2.c

   1 /*\r
   2  * FreeRTOS+UDP V1.0.0 (C) 2013 Real Time Engineers ltd.\r
   3  *\r
   4  * FreeRTOS+UDP is an add-on component to FreeRTOS.  It is not, in itself, part\r
   5  * of the FreeRTOS kernel.  FreeRTOS+UDP is licensed separately from FreeRTOS,\r
   6  * and uses a different license to FreeRTOS.  FreeRTOS+UDP uses a dual license\r
   7  * model, information on which is provided below:\r
   8  *\r
   9  * - Open source licensing -\r
  10  * FreeRTOS+UDP is a free download and may be used, modified and distributed\r
  11  * without charge provided the user adheres to version two of the GNU General\r
  12  * Public license (GPL) and does not remove the copyright notice or this text.\r
  13  * The GPL V2 text is available on the gnu.org web site, and on the following\r
  14  * URL: http://www.FreeRTOS.org/gpl-2.0.txt\r
  15  *\r
  16  * - Commercial licensing -\r
  17  * Businesses and individuals who wish to incorporate FreeRTOS+UDP into\r
  18  * proprietary software for redistribution in any form must first obtain a\r
  19  * (very) low cost commercial license - and in-so-doing support the maintenance,\r
  20  * support and further development of the FreeRTOS+UDP product.  Commercial\r
  21  * licenses can be obtained from http://shop.freertos.org and do not require any\r
  22  * source files to be changed.\r
  23  *\r
  24  * FreeRTOS+UDP is distributed in the hope that it will be useful.  You cannot\r
  25  * use FreeRTOS+UDP unless you agree that you use the software 'as is'.\r
  26  * FreeRTOS+UDP is provided WITHOUT ANY WARRANTY; without even the implied\r
  27  * warranties of NON-INFRINGEMENT, MERCHANTABILITY or FITNESS FOR A PARTICULAR\r
  28  * PURPOSE. Real Time Engineers Ltd. disclaims all conditions and terms, be they\r
  29  * implied, expressed, or statutory.\r
  30  *\r
  31  * 1 tab == 4 spaces!\r
  32  *\r
  33  * http://www.FreeRTOS.org\r
  34  * http://www.FreeRTOS.org/udp\r
  35  *\r
  36  */\r
  37 \r
  38 /******************************************************************************\r
  39  *\r
  40  * See the following web page for essential buffer allocation scheme usage and \r
  41  * configuration details:\r
  42  * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_UDP/Embedded_Ethernet_Buffer_Management.shtml\r
  43  *\r
  44  ******************************************************************************/\r
  45 \r
  46 /* THIS FILE SHOULD NOT BE USED IF THE PROJECT INCLUDES A MEMORY ALLOCATOR\r
  47 THAT WILL FRAGMENT THE HEAP MEMORY.  For example, heap_2 must not be used,\r
  48 heap_4 can be used. */\r
  49 \r
  50 \r
  51 /* Standard includes. */\r
  52 #include <stdint.h>\r
  53 \r
  54 /* FreeRTOS includes. */\r
  55 #include "FreeRTOS.h"\r
  56 #include "task.h"\r
  57 #include "semphr.h"\r
  58 \r
  59 /* FreeRTOS+UDP includes. */\r
  60 #include "FreeRTOS_UDP_IP.h"\r
  61 #include "FreeRTOS_IP_Private.h"\r
  62 #include "NetworkInterface.h"\r
  63 \r
  64 /* For an Ethernet interrupt to be able to obtain a network buffer there must\r
  65 be at least this number of buffers available. */\r
  66 #define ipINTERRUPT_BUFFER_GET_THRESHOLD        ( 3 )\r
  67 \r
  68 /* A list of free (available) xNetworkBufferDescriptor_t structures. */\r
  69 static xList xFreeBuffersList;\r
  70 \r
  71 /* Declares the pool of xNetworkBufferDescriptor_t structures that are available to the\r
  72 system.  All the network buffers referenced from xFreeBuffersList exist in this\r
  73 array.  The array is not accessed directly except during initialisation, when\r
  74 the xFreeBuffersList is filled (as all the buffers are free when the system is\r
  75 booted). */\r
  76 static xNetworkBufferDescriptor_t xNetworkBuffers[ ipconfigNUM_NETWORK_BUFFERS ];\r
  77 \r
  78 /* The semaphore used to obtain network buffers. */\r
  79 static xSemaphoreHandle xNetworkBufferSemaphore = NULL;\r
  80 \r
  81 /*-----------------------------------------------------------*/\r
  82 \r
  83 portBASE_TYPE xNetworkBuffersInitialise( void )\r
  84 {\r
  85 portBASE_TYPE xReturn, x;\r
  86 \r
  87         /* Only initialise the buffers and their associated kernel objects if they\r
  88         have not been initialised before. */\r
  89         if( xNetworkBufferSemaphore == NULL )\r
  90         {\r
  91                 xNetworkBufferSemaphore = xSemaphoreCreateCounting( ipconfigNUM_NETWORK_BUFFERS, ipconfigNUM_NETWORK_BUFFERS );\r
  92                 configASSERT( xNetworkBufferSemaphore );\r
  93                 vQueueAddToRegistry( xNetworkBufferSemaphore, ( signed char * ) "NetBufSem" );\r
  94 \r
  95                 /* If the trace recorder code is included name the semaphore for viewing\r
  96                 in FreeRTOS+Trace.  */\r
  97                 #if ipconfigINCLUDE_EXAMPLE_FREERTOS_PLUS_TRACE_CALLS == 1\r
  98                 {\r
  99                         extern xQueueHandle xNetworkEventQueue;\r
 100                         vTraceSetQueueName( xNetworkEventQueue, "IPStackEvent" );\r
 101                         vTraceSetQueueName( xNetworkBufferSemaphore, "NetworkBufferCount" );\r
 102                 }\r
 103                 #endif /*  ipconfigINCLUDE_EXAMPLE_FREERTOS_PLUS_TRACE_CALLS == 1 */\r
 104 \r
 105                 if( xNetworkBufferSemaphore != NULL )\r
 106                 {\r
 107                         vListInitialise( &xFreeBuffersList );\r
 108 \r
 109                         /* Initialise all the network buffers.  No storage is allocated to\r
 110                         the buffers yet. */\r
 111                         for( x = 0; x < ipconfigNUM_NETWORK_BUFFERS; x++ )\r
 112                         {\r
 113                                 /* Initialise and set the owner of the buffer list items. */\r
 114                                 xNetworkBuffers[ x ].pucEthernetBuffer = NULL;\r
 115                                 vListInitialiseItem( &( xNetworkBuffers[ x ].xBufferListItem ) );\r
 116                                 listSET_LIST_ITEM_OWNER( &( xNetworkBuffers[ x ].xBufferListItem ), &xNetworkBuffers[ x ] );\r
 117 \r
 118                                 /* Currently, all buffers are available for use. */\r
 119                                 vListInsert( &xFreeBuffersList, &( xNetworkBuffers[ x ].xBufferListItem ) );\r
 120                         }\r
 121                 }\r
 122         }\r
 123 \r
 124         if( xNetworkBufferSemaphore == NULL )\r
 125         {\r
 126                 xReturn = pdFAIL;\r
 127         }\r
 128         else\r
 129         {\r
 130                 xReturn = pdPASS;\r
 131         }\r
 132 \r
 133         return xReturn;\r
 134 }\r
 135 /*-----------------------------------------------------------*/\r
 136 \r
 137 uint8_t *pucEthernetBufferGet( size_t *pxRequestedSizeBytes )\r
 138 {\r
 139 uint8_t *pucEthernetBuffer;\r
 140 \r
 141         if( *pxRequestedSizeBytes < sizeof( xARPPacket_t ) )\r
 142         {\r
 143                 /* Buffers must be at least large enough to hold ARP packets, otherwise\r
 144                 nothing can be done. */\r
 145                 *pxRequestedSizeBytes = sizeof( xARPPacket_t );\r
 146         }\r
 147 \r
 148         /* Allocate a buffer large enough to store the requested Ethernet frame size\r
 149         and a pointer to a network buffer structure (hence the addition of\r
 150         ipBUFFER_PADDING bytes). */\r
 151         pucEthernetBuffer = ( uint8_t * ) pvPortMalloc( *pxRequestedSizeBytes + ipBUFFER_PADDING );\r
 152 \r
 153         /* Enough space is left at the start of the buffer to place a pointer to\r
 154         the network buffer structure that references this Ethernet buffer.  Return\r
 155         a pointer to the start of the Ethernet buffer itself. */\r
 156         pucEthernetBuffer += ipBUFFER_PADDING;\r
 157 \r
 158         return pucEthernetBuffer;\r
 159 }\r
 160 /*-----------------------------------------------------------*/\r
 161 \r
 162 void vEthernetBufferRelease( uint8_t *pucEthernetBuffer )\r
 163 {\r
 164         /* There is space before the Ethernet buffer in which a pointer to the\r
 165         network buffer that references this Ethernet buffer is stored.  Remove the\r
 166         space before freeing the buffer. */\r
 167         if( pucEthernetBuffer != NULL )\r
 168         {\r
 169                 pucEthernetBuffer -= ipBUFFER_PADDING;\r
 170                 vPortFree( ( void * ) pucEthernetBuffer );\r
 171         }\r
 172 }\r
 173 /*-----------------------------------------------------------*/\r
 174 \r
 175 xNetworkBufferDescriptor_t *pxNetworkBufferGet( size_t xRequestedSizeBytes, portTickType xBlockTimeTicks )\r
 176 {\r
 177 xNetworkBufferDescriptor_t *pxReturn = NULL;\r
 178 \r
 179         if( ( xRequestedSizeBytes != 0 ) && ( xRequestedSizeBytes < sizeof( xARPPacket_t ) ) )\r
 180         {\r
 181                 /* ARP packets can replace application packets, so the storage must be\r
 182                 at least large enough to hold an ARP. */\r
 183                 xRequestedSizeBytes = sizeof( xARPPacket_t );\r
 184         }\r
 185 \r
 186         /* If there is a semaphore available, there is a network buffer available. */\r
 187         if( xSemaphoreTake( xNetworkBufferSemaphore, xBlockTimeTicks ) == pdPASS )\r
 188         {\r
 189                 /* Protect the structure as it is accessed from tasks and interrupts. */\r
 190                 taskENTER_CRITICAL();\r
 191                 {\r
 192                         pxReturn = ( xNetworkBufferDescriptor_t * ) listGET_OWNER_OF_HEAD_ENTRY( &xFreeBuffersList );\r
 193                         uxListRemove( &( pxReturn->xBufferListItem ) );\r
 194                 }\r
 195                 taskEXIT_CRITICAL();\r
 196 \r
 197                 /* Allocate storage of exactly the requested size to the buffer. */\r
 198                 configASSERT( pxReturn->pucEthernetBuffer == NULL );\r
 199                 if( xRequestedSizeBytes > 0 )\r
 200                 {\r
 201                         /* Extra space is obtained so a pointer to the network buffer can\r
 202                         be stored at the beginning of the buffer. */\r
 203                         pxReturn->pucEthernetBuffer = ( uint8_t * ) pvPortMalloc( xRequestedSizeBytes + ipBUFFER_PADDING );\r
 204 \r
 205                         if( pxReturn->pucEthernetBuffer == NULL )\r
 206                         {\r
 207                                 /* The attempt to allocate storage for the buffer payload failed,\r
 208                                 so the network buffer structure cannot be used and must be\r
 209                                 released. */\r
 210                                 vNetworkBufferRelease( pxReturn );\r
 211                                 pxReturn = NULL;\r
 212                         }\r
 213                         else\r
 214                         {\r
 215                                 /* Store a pointer to the network buffer structure in the\r
 216                                 buffer storage area, then move the buffer pointer on past the\r
 217                                 stored pointer so the pointer value is not overwritten by the\r
 218                                 application when the buffer is used. */\r
 219                                 *( ( xNetworkBufferDescriptor_t ** ) ( pxReturn->pucEthernetBuffer ) ) = pxReturn;\r
 220                                 pxReturn->pucEthernetBuffer += ipBUFFER_PADDING;\r
 221                                 iptraceNETWORK_BUFFER_OBTAINED( pxReturn );\r
 222 \r
 223                                 /* Store the actual size of the allocated buffer, which may be\r
 224                                 greater than the requested size. */\r
 225                                 pxReturn->xDataLength = xRequestedSizeBytes;\r
 226                         }\r
 227                 }\r
 228                 else\r
 229                 {\r
 230                         iptraceNETWORK_BUFFER_OBTAINED( pxReturn );\r
 231                 }\r
 232         }\r
 233 \r
 234         if( pxReturn == NULL )\r
 235         {\r
 236                 iptraceFAILED_TO_OBTAIN_NETWORK_BUFFER();\r
 237         }\r
 238 \r
 239         return pxReturn;\r
 240 }\r
 241 /*-----------------------------------------------------------*/\r
 242 \r
 243 void vNetworkBufferRelease( xNetworkBufferDescriptor_t * const pxNetworkBuffer )\r
 244 {\r
 245 portBASE_TYPE xListItemAlreadyInFreeList;\r
 246 \r
 247         /* Ensure the buffer is returned to the list of free buffers before the\r
 248         counting semaphore is 'given' to say a buffer is available.  Release the\r
 249         storage allocated to the buffer payload.  THIS FILE SHOULD NOT BE USED\r
 250         IF THE PROJECT INCLUDES A MEMORY ALLOCATOR THAT WILL FRAGMENT THE HEAP\r
 251         MEMORY.  For example, heap_2 must not be used, heap_4 can be used. */\r
 252         vEthernetBufferRelease( pxNetworkBuffer->pucEthernetBuffer );\r
 253         pxNetworkBuffer->pucEthernetBuffer = NULL;\r
 254 \r
 255         taskENTER_CRITICAL();\r
 256         {\r
 257                 xListItemAlreadyInFreeList = listIS_CONTAINED_WITHIN( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );\r
 258 \r
 259                 if( xListItemAlreadyInFreeList == pdFALSE )\r
 260                 {\r
 261                         vListInsertEnd( &xFreeBuffersList, &( pxNetworkBuffer->xBufferListItem ) );\r
 262                 }\r
 263 \r
 264                 configASSERT( xListItemAlreadyInFreeList == pdFALSE );\r
 265         }\r
 266         taskEXIT_CRITICAL();\r
 267 \r
 268         xSemaphoreGive( xNetworkBufferSemaphore );\r
 269         iptraceNETWORK_BUFFER_RELEASED( pxNetworkBuffer );\r
 270 }\r
 271 /*-----------------------------------------------------------*/\r
 272 \r
 273 #if( ipconfigINCLUDE_TEST_CODE == 1 )\r
 274 \r
 275 unsigned portBASE_TYPE uxGetNumberOfFreeNetworkBuffers( void )\r
 276 {\r
 277         return listCURRENT_LIST_LENGTH( &xFreeBuffersList );\r
 278 }\r
 279 \r
 280 #endif /* ipconfigINCLUDE_TEST_CODE */\r