git.sur5r.net Git - freertos/blob - FreeRTOS/Source/include/message_buffer.h

   1 /*\r
   2  * FreeRTOS Kernel V10.0.0\r
   3  * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\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
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software. If you wish to use our Amazon\r
  14  * FreeRTOS name, please do so in a fair use way that does not cause confusion.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * http://www.FreeRTOS.org\r
  24  * http://aws.amazon.com/freertos\r
  25  *\r
  26  * 1 tab == 4 spaces!\r
  27  */\r
  28 \r
  29 \r
  30 /*\r
  31  * Message buffers build functionality on top of FreeRTOS stream buffers.\r
  32  * Whereas stream buffers are used to send a continuous stream of data from one\r
  33  * task or interrupt to another, message buffers are used to send variable\r
  34  * length discrete messages from one task or interrupt to another.  Their\r
  35  * implementation is light weight, making them particularly suited for interrupt\r
  36  * to task and core to core communication scenarios.\r
  37  *\r
  38  * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
  39  * implementation (so also the message buffer implementation, as message buffers\r
  40  * are built on top of stream buffers) assumes there is only one task or\r
  41  * interrupt that will write to the buffer (the writer), and only one task or\r
  42  * interrupt that will read from the buffer (the reader).  It is safe for the\r
  43  * writer and reader to be different tasks or interrupts, but, unlike other\r
  44  * FreeRTOS objects, it is not safe to have multiple different writers or\r
  45  * multiple different readers.  If there are to be multiple different writers\r
  46  * then the application writer must place each call to a writing API function\r
  47  * (such as xMessageBufferSend()) inside a critical section and set the send\r
  48  * block time to 0.  Likewise, if there are to be multiple different readers\r
  49  * then the application writer must place each call to a reading API function\r
  50  * (such as xMessageBufferRead()) inside a critical section and set the receive\r
  51  * timeout to 0.\r
  52  *\r
  53  * Message buffers hold variable length messages.  To enable that, when a\r
  54  * message is written to the message buffer an additional sizeof( size_t ) bytes\r
  55  * are also written to store the message's length (that happens internally, with\r
  56  * the API function).  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
  57  * architecture, so writing a 10 byte message to a message buffer on a 32-bit\r
  58  * architecture will actually reduce the available space in the message buffer\r
  59  * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length\r
  60  * of the message).\r
  61  */\r
  62 \r
  63 #ifndef FREERTOS_MESSAGE_BUFFER_H\r
  64 #define FREERTOS_MESSAGE_BUFFER_H\r
  65 \r
  66 /* Message buffers are built onto of stream buffers. */\r
  67 #include "stream_buffer.h"\r
  68 \r
  69 #if defined( __cplusplus )\r
  70 extern "C" {\r
  71 #endif\r
  72 \r
  73 /**\r
  74  * Type by which message buffers are referenced.  For example, a call to\r
  75  * xMessageBufferCreate() returns an MessageBufferHandle_t variable that can\r
  76  * then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(),\r
  77  * etc.\r
  78  */\r
  79 typedef void * MessageBufferHandle_t;\r
  80 \r
  81 /*-----------------------------------------------------------*/\r
  82 \r
  83 /**\r
  84  * message_buffer.h\r
  85  *\r
  86 <pre>\r
  87 MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );\r
  88 </pre>\r
  89  *\r
  90  * Creates a new message buffer using dynamically allocated memory.  See\r
  91  * xMessageBufferCreateStatic() for a version that uses statically allocated\r
  92  * memory (memory that is allocated at compile time).\r
  93  *\r
  94  * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in\r
  95  * FreeRTOSConfig.h for xMessageBufferCreate() to be available.\r
  96  *\r
  97  * @param xBufferSizeBytes The total number of bytes (not messages) the message\r
  98  * buffer will be able to hold at any one time.  When a message is written to\r
  99  * the message buffer an additional sizeof( size_t ) bytes are also written to\r
 100  * store the message's length.  sizeof( size_t ) is typically 4 bytes on a\r
 101  * 32-bit architecture, so on most 32-bit architectures a 10 byte message will\r
 102  * take up 14 bytes of message buffer space.\r
 103  *\r
 104  * @return If NULL is returned, then the message buffer cannot be created\r
 105  * because there is insufficient heap memory available for FreeRTOS to allocate\r
 106  * the message buffer data structures and storage area.  A non-NULL value being\r
 107  * returned indicates that the message buffer has been created successfully -\r
 108  * the returned value should be stored as the handle to the created message\r
 109  * buffer.\r
 110  *\r
 111  * Example use:\r
 112 <pre>\r
 113 \r
 114 void vAFunction( void )\r
 115 {\r
 116 MessageBufferHandle_t xMessageBuffer;\r
 117 const size_t xMessageBufferSizeBytes = 100;\r
 118 \r
 119     // Create a message buffer that can hold 100 bytes.  The memory used to hold\r
 120     // both the message buffer structure and the messages themselves is allocated\r
 121     // dynamically.  Each message added to the buffer consumes an additional 4\r
 122     // bytes which are used to hold the lengh of the message.\r
 123     xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );\r
 124 \r
 125     if( xMessageBuffer == NULL )\r
 126     {\r
 127         // There was not enough heap memory space available to create the\r
 128         // message buffer.\r
 129     }\r
 130     else\r
 131     {\r
 132         // The message buffer was created successfully and can now be used.\r
 133     }\r
 134 \r
 135 </pre>\r
 136  * \defgroup xMessageBufferCreate xMessageBufferCreate\r
 137  * \ingroup MessageBufferManagement\r
 138  */\r
 139 #define xMessageBufferCreate( xBufferSizeBytes ) ( MessageBufferHandle_t ) xStreamBufferGenericCreate( xBufferSizeBytes, ( size_t ) 0, pdTRUE )\r
 140 \r
 141 /**\r
 142  * message_buffer.h\r
 143  *\r
 144 <pre>\r
 145 MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,\r
 146                                                   uint8_t *pucMessageBufferStorageArea,\r
 147                                                   StaticMessageBuffer_t *pxStaticMessageBuffer );\r
 148 </pre>\r
 149  * Creates a new message buffer using statically allocated memory.  See\r
 150  * xMessageBufferCreate() for a version that uses dynamically allocated memory.\r
 151  *\r
 152  * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the\r
 153  * pucMessageBufferStorageArea parameter.  When a message is written to the\r
 154  * message buffer an additional sizeof( size_t ) bytes are also written to store\r
 155  * the message's length.  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
 156  * architecture, so on most 32-bit architecture a 10 byte message will take up\r
 157  * 14 bytes of message buffer space.  The maximum number of bytes that can be\r
 158  * stored in the message buffer is actually (xBufferSizeBytes - 1).\r
 159  *\r
 160  * @param pucMessageBufferStorageArea Must point to a uint8_t array that is at\r
 161  * least xBufferSizeBytes + 1 big.  This is the array to which messages are\r
 162  * copied when they are written to the message buffer.\r
 163  *\r
 164  * @param pxStaticMessageBuffer Must point to a variable of type\r
 165  * StaticMessageBuffer_t, which will be used to hold the message buffer's data\r
 166  * structure.\r
 167  *\r
 168  * @return If the message buffer is created successfully then a handle to the\r
 169  * created message buffer is returned. If either pucMessageBufferStorageArea or\r
 170  * pxStaticmessageBuffer are NULL then NULL is returned.\r
 171  *\r
 172  * Example use:\r
 173 <pre>\r
 174 \r
 175 // Used to dimension the array used to hold the messages.  The available space\r
 176 // will actually be one less than this, so 999.\r
 177 #define STORAGE_SIZE_BYTES 1000\r
 178 \r
 179 // Defines the memory that will actually hold the messages within the message\r
 180 // buffer.\r
 181 static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];\r
 182 \r
 183 // The variable used to hold the message buffer structure.\r
 184 StaticMessageBuffer_t xMessageBufferStruct;\r
 185 \r
 186 void MyFunction( void )\r
 187 {\r
 188 MessageBufferHandle_t xMessageBuffer;\r
 189 \r
 190     xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),\r
 191                                                  ucBufferStorage,\r
 192                                                  &xMessageBufferStruct );\r
 193 \r
 194     // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer\r
 195     // parameters were NULL, xMessageBuffer will not be NULL, and can be used to\r
 196     // reference the created message buffer in other message buffer API calls.\r
 197 \r
 198     // Other code that uses the message buffer can go here.\r
 199 }\r
 200 \r
 201 </pre>\r
 202  * \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic\r
 203  * \ingroup MessageBufferManagement\r
 204  */\r
 205 #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) ( MessageBufferHandle_t ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, 0, pdTRUE, pucMessageBufferStorageArea, pxStaticMessageBuffer )\r
 206 \r
 207 /**\r
 208  * message_buffer.h\r
 209  *\r
 210 <pre>\r
 211 size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,\r
 212                            const void *pvTxData,\r
 213                            size_t xDataLengthBytes,\r
 214                            TickType_t xTicksToWait );\r
 215 <pre>\r
 216  *\r
 217  * Sends a discrete message to the message buffer.  The message can be any\r
 218  * length that fits within the buffer's free space, and is copied into the\r
 219  * buffer.\r
 220  *\r
 221  * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 222  * implementation (so also the message buffer implementation, as message buffers\r
 223  * are built on top of stream buffers) assumes there is only one task or\r
 224  * interrupt that will write to the buffer (the writer), and only one task or\r
 225  * interrupt that will read from the buffer (the reader).  It is safe for the\r
 226  * writer and reader to be different tasks or interrupts, but, unlike other\r
 227  * FreeRTOS objects, it is not safe to have multiple different writers or\r
 228  * multiple different readers.  If there are to be multiple different writers\r
 229  * then the application writer must place each call to a writing API function\r
 230  * (such as xMessageBufferSend()) inside a critical section and set the send\r
 231  * block time to 0.  Likewise, if there are to be multiple different readers\r
 232  * then the application writer must place each call to a reading API function\r
 233  * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 234  * block time to 0.\r
 235  *\r
 236  * Use xMessageBufferSend() to write to a message buffer from a task.  Use\r
 237  * xMessageBufferSendFromISR() to write to a message buffer from an interrupt\r
 238  * service routine (ISR).\r
 239  *\r
 240  * @param xMessageBuffer The handle of the message buffer to which a message is\r
 241  * being sent.\r
 242  *\r
 243  * @param pvTxData A pointer to the message that is to be copied into the\r
 244  * message buffer.\r
 245  *\r
 246  * @param xDataLengthBytes The length of the message.  That is, the number of\r
 247  * bytes to copy from pvTxData into the message buffer.  When a message is\r
 248  * written to the message buffer an additional sizeof( size_t ) bytes are also\r
 249  * written to store the message's length.  sizeof( size_t ) is typically 4 bytes\r
 250  * on a 32-bit architecture, so on most 32-bit architecture setting\r
 251  * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24\r
 252  * bytes (20 bytes of message data and 4 bytes to hold the message length).\r
 253  *\r
 254  * @param xTicksToWait The maximum amount of time the calling task should remain\r
 255  * in the Blocked state to wait for enough space to become available in the\r
 256  * message buffer, should the message buffer have insufficient space when\r
 257  * xMessageBufferSend() is called.  The calling task will never block if\r
 258  * xTicksToWait is zero.  The block time is specified in tick periods, so the\r
 259  * absolute time it represents is dependent on the tick frequency.  The macro\r
 260  * pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into\r
 261  * a time specified in ticks.  Setting xTicksToWait to portMAX_DELAY will cause\r
 262  * the task to wait indefinitely (without timing out), provided\r
 263  * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.  Tasks do not use any\r
 264  * CPU time when they are in the Blocked state.\r
 265  *\r
 266  * @return The number of bytes written to the message buffer.  If the call to\r
 267  * xMessageBufferSend() times out before there was enough space to write the\r
 268  * message into the message buffer then zero is returned.  If the call did not\r
 269  * time out then xDataLengthBytes is returned.\r
 270  *\r
 271  * Example use:\r
 272 <pre>\r
 273 void vAFunction( MessageBufferHandle_t xMessageBuffer )\r
 274 {\r
 275 size_t xBytesSent;\r
 276 uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };\r
 277 char *pcStringToSend = "String to send";\r
 278 const TickType_t x100ms = pdMS_TO_TICKS( 100 );\r
 279 \r
 280     // Send an array to the message buffer, blocking for a maximum of 100ms to\r
 281     // wait for enough space to be available in the message buffer.\r
 282     xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );\r
 283 \r
 284     if( xBytesSent != sizeof( ucArrayToSend ) )\r
 285     {\r
 286         // The call to xMessageBufferSend() times out before there was enough\r
 287         // space in the buffer for the data to be written.\r
 288     }\r
 289 \r
 290     // Send the string to the message buffer.  Return immediately if there is\r
 291     // not enough space in the buffer.\r
 292     xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );\r
 293 \r
 294     if( xBytesSent != strlen( pcStringToSend ) )\r
 295     {\r
 296         // The string could not be added to the message buffer because there was\r
 297         // not enough free space in the buffer.\r
 298     }\r
 299 }\r
 300 </pre>\r
 301  * \defgroup xMessageBufferSend xMessageBufferSend\r
 302  * \ingroup MessageBufferManagement\r
 303  */\r
 304 #define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) xStreamBufferSend( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait )\r
 305 \r
 306 /**\r
 307  * message_buffer.h\r
 308  *\r
 309 <pre>\r
 310 size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,\r
 311                                   const void *pvTxData,\r
 312                                   size_t xDataLengthBytes,\r
 313                                   BaseType_t *pxHigherPriorityTaskWoken );\r
 314 <pre>\r
 315  *\r
 316  * Interrupt safe version of the API function that sends a discrete message to\r
 317  * the message buffer.  The message can be any length that fits within the\r
 318  * buffer's free space, and is copied into the buffer.\r
 319  *\r
 320  * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 321  * implementation (so also the message buffer implementation, as message buffers\r
 322  * are built on top of stream buffers) assumes there is only one task or\r
 323  * interrupt that will write to the buffer (the writer), and only one task or\r
 324  * interrupt that will read from the buffer (the reader).  It is safe for the\r
 325  * writer and reader to be different tasks or interrupts, but, unlike other\r
 326  * FreeRTOS objects, it is not safe to have multiple different writers or\r
 327  * multiple different readers.  If there are to be multiple different writers\r
 328  * then the application writer must place each call to a writing API function\r
 329  * (such as xMessageBufferSend()) inside a critical section and set the send\r
 330  * block time to 0.  Likewise, if there are to be multiple different readers\r
 331  * then the application writer must place each call to a reading API function\r
 332  * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 333  * block time to 0.\r
 334  *\r
 335  * Use xMessageBufferSend() to write to a message buffer from a task.  Use\r
 336  * xMessageBufferSendFromISR() to write to a message buffer from an interrupt\r
 337  * service routine (ISR).\r
 338  *\r
 339  * @param xMessageBuffer The handle of the message buffer to which a message is\r
 340  * being sent.\r
 341  *\r
 342  * @param pvTxData A pointer to the message that is to be copied into the\r
 343  * message buffer.\r
 344  *\r
 345  * @param xDataLengthBytes The length of the message.  That is, the number of\r
 346  * bytes to copy from pvTxData into the message buffer.  When a message is\r
 347  * written to the message buffer an additional sizeof( size_t ) bytes are also\r
 348  * written to store the message's length.  sizeof( size_t ) is typically 4 bytes\r
 349  * on a 32-bit architecture, so on most 32-bit architecture setting\r
 350  * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24\r
 351  * bytes (20 bytes of message data and 4 bytes to hold the message length).\r
 352  *\r
 353  * @param pxHigherPriorityTaskWoken  It is possible that a message buffer will\r
 354  * have a task blocked on it waiting for data.  Calling\r
 355  * xMessageBufferSendFromISR() can make data available, and so cause a task that\r
 356  * was waiting for data to leave the Blocked state.  If calling\r
 357  * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the\r
 358  * unblocked task has a priority higher than the currently executing task (the\r
 359  * task that was interrupted), then, internally, xMessageBufferSendFromISR()\r
 360  * will set *pxHigherPriorityTaskWoken to pdTRUE.  If\r
 361  * xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a\r
 362  * context switch should be performed before the interrupt is exited.  This will\r
 363  * ensure that the interrupt returns directly to the highest priority Ready\r
 364  * state task.  *pxHigherPriorityTaskWoken should be set to pdFALSE before it\r
 365  * is passed into the function.  See the code example below for an example.\r
 366  *\r
 367  * @return The number of bytes actually written to the message buffer.  If the\r
 368  * message buffer didn't have enough free space for the message to be stored\r
 369  * then 0 is returned, otherwise xDataLengthBytes is returned.\r
 370  *\r
 371  * Example use:\r
 372 <pre>\r
 373 // A message buffer that has already been created.\r
 374 MessageBufferHandle_t xMessageBuffer;\r
 375 \r
 376 void vAnInterruptServiceRoutine( void )\r
 377 {\r
 378 size_t xBytesSent;\r
 379 char *pcStringToSend = "String to send";\r
 380 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.\r
 381 \r
 382     // Attempt to send the string to the message buffer.\r
 383     xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,\r
 384                                             ( void * ) pcStringToSend,\r
 385                                             strlen( pcStringToSend ),\r
 386                                             &xHigherPriorityTaskWoken );\r
 387 \r
 388     if( xBytesSent != strlen( pcStringToSend ) )\r
 389     {\r
 390         // The string could not be added to the message buffer because there was\r
 391         // not enough free space in the buffer.\r
 392     }\r
 393 \r
 394     // If xHigherPriorityTaskWoken was set to pdTRUE inside\r
 395     // xMessageBufferSendFromISR() then a task that has a priority above the\r
 396     // priority of the currently executing task was unblocked and a context\r
 397     // switch should be performed to ensure the ISR returns to the unblocked\r
 398     // task.  In most FreeRTOS ports this is done by simply passing\r
 399     // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the\r
 400     // variables value, and perform the context switch if necessary.  Check the\r
 401     // documentation for the port in use for port specific instructions.\r
 402     taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );\r
 403 }\r
 404 </pre>\r
 405  * \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR\r
 406  * \ingroup MessageBufferManagement\r
 407  */\r
 408 #define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferSendFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken )\r
 409 \r
 410 /**\r
 411  * message_buffer.h\r
 412  *\r
 413 <pre>\r
 414 size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,\r
 415                               void *pvRxData,\r
 416                               size_t xBufferLengthBytes,\r
 417                               TickType_t xTicksToWait );\r
 418 </pre>\r
 419  *\r
 420  * Receives a discrete message from a message buffer.  Messages can be of\r
 421  * variable length and are copied out of the buffer.\r
 422  *\r
 423  * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 424  * implementation (so also the message buffer implementation, as message buffers\r
 425  * are built on top of stream buffers) assumes there is only one task or\r
 426  * interrupt that will write to the buffer (the writer), and only one task or\r
 427  * interrupt that will read from the buffer (the reader).  It is safe for the\r
 428  * writer and reader to be different tasks or interrupts, but, unlike other\r
 429  * FreeRTOS objects, it is not safe to have multiple different writers or\r
 430  * multiple different readers.  If there are to be multiple different writers\r
 431  * then the application writer must place each call to a writing API function\r
 432  * (such as xMessageBufferSend()) inside a critical section and set the send\r
 433  * block time to 0.  Likewise, if there are to be multiple different readers\r
 434  * then the application writer must place each call to a reading API function\r
 435  * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 436  * block time to 0.\r
 437  *\r
 438  * Use xMessageBufferReceive() to read from a message buffer from a task.  Use\r
 439  * xMessageBufferReceiveFromISR() to read from a message buffer from an\r
 440  * interrupt service routine (ISR).\r
 441  *\r
 442  * @param xMessageBuffer The handle of the message buffer from which a message\r
 443  * is being received.\r
 444  *\r
 445  * @param pvRxData A pointer to the buffer into which the received message is\r
 446  * to be copied.\r
 447  *\r
 448  * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData\r
 449  * parameter.  This sets the maximum length of the message that can be received.\r
 450  * If xBufferLengthBytes is too small to hold the next message then the message\r
 451  * will be left in the message buffer and 0 will be returned.\r
 452  *\r
 453  * @param xTicksToWait The maximum amount of time the task should remain in the\r
 454  * Blocked state to wait for a message, should the message buffer be empty.\r
 455  * xMessageBufferReceive() will return immediately if xTicksToWait is zero and\r
 456  * the message buffer is empty.  The block time is specified in tick periods, so\r
 457  * the absolute time it represents is dependent on the tick frequency.  The\r
 458  * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds\r
 459  * into a time specified in ticks.  Setting xTicksToWait to portMAX_DELAY will\r
 460  * cause the task to wait indefinitely (without timing out), provided\r
 461  * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.  Tasks do not use any\r
 462  * CPU time when they are in the Blocked state.\r
 463  *\r
 464  * @return The length, in bytes, of the message read from the message buffer, if\r
 465  * any.  If xMessageBufferReceive() times out before a message became available\r
 466  * then zero is returned.  If the length of the message is greater than\r
 467  * xBufferLengthBytes then the message will be left in the message buffer and\r
 468  * zero is returned.\r
 469  *\r
 470  * Example use:\r
 471 <pre>\r
 472 void vAFunction( MessageBuffer_t xMessageBuffer )\r
 473 {\r
 474 uint8_t ucRxData[ 20 ];\r
 475 size_t xReceivedBytes;\r
 476 const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );\r
 477 \r
 478     // Receive the next message from the message buffer.  Wait in the Blocked\r
 479     // state (so not using any CPU processing time) for a maximum of 100ms for\r
 480     // a message to become available.\r
 481     xReceivedBytes = xMessageBufferReceive( xMessageBuffer,\r
 482                                             ( void * ) ucRxData,\r
 483                                             sizeof( ucRxData ),\r
 484                                             xBlockTime );\r
 485 \r
 486     if( xReceivedBytes > 0 )\r
 487     {\r
 488         // A ucRxData contains a message that is xReceivedBytes long.  Process\r
 489         // the message here....\r
 490     }\r
 491 }\r
 492 </pre>\r
 493  * \defgroup xMessageBufferReceive xMessageBufferReceive\r
 494  * \ingroup MessageBufferManagement\r
 495  */\r
 496 #define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) xStreamBufferReceive( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait )\r
 497 \r
 498 \r
 499 /**\r
 500  * message_buffer.h\r
 501  *\r
 502 <pre>\r
 503 size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,\r
 504                                      void *pvRxData,\r
 505                                      size_t xBufferLengthBytes,\r
 506                                      BaseType_t *pxHigherPriorityTaskWoken );\r
 507 </pre>\r
 508  *\r
 509  * An interrupt safe version of the API function that receives a discrete\r
 510  * message from a message buffer.  Messages can be of variable length and are\r
 511  * copied out of the buffer.\r
 512  *\r
 513  * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 514  * implementation (so also the message buffer implementation, as message buffers\r
 515  * are built on top of stream buffers) assumes there is only one task or\r
 516  * interrupt that will write to the buffer (the writer), and only one task or\r
 517  * interrupt that will read from the buffer (the reader).  It is safe for the\r
 518  * writer and reader to be different tasks or interrupts, but, unlike other\r
 519  * FreeRTOS objects, it is not safe to have multiple different writers or\r
 520  * multiple different readers.  If there are to be multiple different writers\r
 521  * then the application writer must place each call to a writing API function\r
 522  * (such as xMessageBufferSend()) inside a critical section and set the send\r
 523  * block time to 0.  Likewise, if there are to be multiple different readers\r
 524  * then the application writer must place each call to a reading API function\r
 525  * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 526  * block time to 0.\r
 527  *\r
 528  * Use xMessageBufferReceive() to read from a message buffer from a task.  Use\r
 529  * xMessageBufferReceiveFromISR() to read from a message buffer from an\r
 530  * interrupt service routine (ISR).\r
 531  *\r
 532  * @param xMessageBuffer The handle of the message buffer from which a message\r
 533  * is being received.\r
 534  *\r
 535  * @param pvRxData A pointer to the buffer into which the received message is\r
 536  * to be copied.\r
 537  *\r
 538  * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData\r
 539  * parameter.  This sets the maximum length of the message that can be received.\r
 540  * If xBufferLengthBytes is too small to hold the next message then the message\r
 541  * will be left in the message buffer and 0 will be returned.\r
 542  *\r
 543  * @param pxHigherPriorityTaskWoken  It is possible that a message buffer will\r
 544  * have a task blocked on it waiting for space to become available.  Calling\r
 545  * xMessageBufferReceiveFromISR() can make space available, and so cause a task\r
 546  * that is waiting for space to leave the Blocked state.  If calling\r
 547  * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and\r
 548  * the unblocked task has a priority higher than the currently executing task\r
 549  * (the task that was interrupted), then, internally,\r
 550  * xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.\r
 551  * If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a\r
 552  * context switch should be performed before the interrupt is exited.  That will\r
 553  * ensure the interrupt returns directly to the highest priority Ready state\r
 554  * task.  *pxHigherPriorityTaskWoken should be set to pdFALSE before it is\r
 555  * passed into the function.  See the code example below for an example.\r
 556  *\r
 557  * @return The length, in bytes, of the message read from the message buffer, if\r
 558  * any.\r
 559  *\r
 560  * Example use:\r
 561 <pre>\r
 562 // A message buffer that has already been created.\r
 563 MessageBuffer_t xMessageBuffer;\r
 564 \r
 565 void vAnInterruptServiceRoutine( void )\r
 566 {\r
 567 uint8_t ucRxData[ 20 ];\r
 568 size_t xReceivedBytes;\r
 569 BaseType_t xHigherPriorityTaskWoken = pdFALSE;  // Initialised to pdFALSE.\r
 570 \r
 571     // Receive the next message from the message buffer.\r
 572     xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,\r
 573                                                   ( void * ) ucRxData,\r
 574                                                   sizeof( ucRxData ),\r
 575                                                   &xHigherPriorityTaskWoken );\r
 576 \r
 577     if( xReceivedBytes > 0 )\r
 578     {\r
 579         // A ucRxData contains a message that is xReceivedBytes long.  Process\r
 580         // the message here....\r
 581     }\r
 582 \r
 583     // If xHigherPriorityTaskWoken was set to pdTRUE inside\r
 584     // xMessageBufferReceiveFromISR() then a task that has a priority above the\r
 585     // priority of the currently executing task was unblocked and a context\r
 586     // switch should be performed to ensure the ISR returns to the unblocked\r
 587     // task.  In most FreeRTOS ports this is done by simply passing\r
 588     // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the\r
 589     // variables value, and perform the context switch if necessary.  Check the\r
 590     // documentation for the port in use for port specific instructions.\r
 591     taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );\r
 592 }\r
 593 </pre>\r
 594  * \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR\r
 595  * \ingroup MessageBufferManagement\r
 596  */\r
 597 #define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferReceiveFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken )\r
 598 \r
 599 /**\r
 600  * message_buffer.h\r
 601  *\r
 602 <pre>\r
 603 void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );\r
 604 </pre>\r
 605  *\r
 606  * Deletes a message buffer that was previously created using a call to\r
 607  * xMessageBufferCreate() or xMessageBufferCreateStatic().  If the message\r
 608  * buffer was created using dynamic memory (that is, by xMessageBufferCreate()),\r
 609  * then the allocated memory is freed.\r
 610  *\r
 611  * A message buffer handle must not be used after the message buffer has been\r
 612  * deleted.\r
 613  *\r
 614  * @param xMessageBuffer The handle of the message buffer to be deleted.\r
 615  *\r
 616  */\r
 617 #define vMessageBufferDelete( xMessageBuffer ) vStreamBufferDelete( ( StreamBufferHandle_t ) xMessageBuffer )\r
 618 \r
 619 /**\r
 620  * message_buffer.h\r
 621 <pre>\r
 622 BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ) );\r
 623 </pre>\r
 624  *\r
 625  * Tests to see if a message buffer is full.  A message buffer is full if it\r
 626  * cannot accept any more messages, of any size, until space is made available\r
 627  * by a message being removed from the message buffer.\r
 628  *\r
 629  * @param xMessageBuffer The handle of the message buffer being queried.\r
 630  *\r
 631  * @return If the message buffer referenced by xMessageBuffer is full then\r
 632  * pdTRUE is returned.  Otherwise pdFALSE is returned.\r
 633  */\r
 634 #define xMessageBufferIsFull( xMessageBuffer ) xStreamBufferIsFull( ( StreamBufferHandle_t ) xMessageBuffer )\r
 635 \r
 636 /**\r
 637  * message_buffer.h\r
 638 <pre>\r
 639 BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ) );\r
 640 </pre>\r
 641  *\r
 642  * Tests to see if a message buffer is empty (does not contain any messages).\r
 643  *\r
 644  * @param xMessageBuffer The handle of the message buffer being queried.\r
 645  *\r
 646  * @return If the message buffer referenced by xMessageBuffer is empty then\r
 647  * pdTRUE is returned.  Otherwise pdFALSE is returned.\r
 648  *\r
 649  */\r
 650 #define xMessageBufferIsEmpty( xMessageBuffer ) xStreamBufferIsEmpty( ( StreamBufferHandle_t ) xMessageBuffer )\r
 651 \r
 652 /**\r
 653  * message_buffer.h\r
 654 <pre>\r
 655 BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );\r
 656 </pre>\r
 657  *\r
 658  * Resets a message buffer to its initial empty state, discarding any message it\r
 659  * contained.\r
 660  *\r
 661  * A message buffer can only be reset if there are no tasks blocked on it.\r
 662  *\r
 663  * @param xMessageBuffer The handle of the message buffer being reset.\r
 664  *\r
 665  * @return If the message buffer was reset then pdPASS is returned.  If the\r
 666  * message buffer could not be reset because either there was a task blocked on\r
 667  * the message queue to wait for space to become available, or to wait for a\r
 668  * a message to be available, then pdFAIL is returned.\r
 669  *\r
 670  * \defgroup xMessageBufferReset xMessageBufferReset\r
 671  * \ingroup MessageBufferManagement\r
 672  */\r
 673 #define xMessageBufferReset( xMessageBuffer ) xStreamBufferReset( ( StreamBufferHandle_t ) xMessageBuffer )\r
 674 \r
 675 \r
 676 /**\r
 677  * message_buffer.h\r
 678 <pre>\r
 679 size_t xMessageBufferSpaceAvailable( MessageBufferHandle_t xMessageBuffer ) );\r
 680 </pre>\r
 681  * Returns the number of bytes of free space in the message buffer.\r
 682  *\r
 683  * @param xMessageBuffer The handle of the message buffer being queried.\r
 684  *\r
 685  * @return The number of bytes that can be written to the message buffer before\r
 686  * the message buffer would be full.  When a message is written to the message\r
 687  * buffer an additional sizeof( size_t ) bytes are also written to store the\r
 688  * message's length.  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
 689  * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size\r
 690  * of the largest message that can be written to the message buffer is 6 bytes.\r
 691  *\r
 692  * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable\r
 693  * \ingroup MessageBufferManagement\r
 694  */\r
 695 #define xMessageBufferSpaceAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer )\r
 696 \r
 697 /**\r
 698  * message_buffer.h\r
 699  *\r
 700 <pre>\r
 701 BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );\r
 702 </pre>\r
 703  *\r
 704  * For advanced users only.\r
 705  *\r
 706  * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when\r
 707  * data is sent to a message buffer or stream buffer.  If there was a task that\r
 708  * was blocked on the message or stream buffer waiting for data to arrive then\r
 709  * the sbSEND_COMPLETED() macro sends a notification to the task to remove it\r
 710  * from the Blocked state.  xMessageBufferSendCompletedFromISR() does the same\r
 711  * thing.  It is provided to enable application writers to implement their own\r
 712  * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.\r
 713  *\r
 714  * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for\r
 715  * additional information.\r
 716  *\r
 717  * @param xStreamBuffer The handle of the stream buffer to which data was\r
 718  * written.\r
 719  *\r
 720  * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be\r
 721  * initialised to pdFALSE before it is passed into\r
 722  * xMessageBufferSendCompletedFromISR().  If calling\r
 723  * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state,\r
 724  * and the task has a priority above the priority of the currently running task,\r
 725  * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a\r
 726  * context switch should be performed before exiting the ISR.\r
 727  *\r
 728  * @return If a task was removed from the Blocked state then pdTRUE is returned.\r
 729  * Otherwise pdFALSE is returned.\r
 730  *\r
 731  * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR\r
 732  * \ingroup StreamBufferManagement\r
 733  */\r
 734 #define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferSendCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )\r
 735 \r
 736 /**\r
 737  * message_buffer.h\r
 738  *\r
 739 <pre>\r
 740 BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );\r
 741 </pre>\r
 742  *\r
 743  * For advanced users only.\r
 744  *\r
 745  * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when\r
 746  * data is read out of a message buffer or stream buffer.  If there was a task\r
 747  * that was blocked on the message or stream buffer waiting for data to arrive\r
 748  * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to\r
 749  * remove it from the Blocked state.  xMessageBufferReceiveCompletedFromISR()\r
 750  * does the same thing.  It is provided to enable application writers to\r
 751  * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT\r
 752  * ANY OTHER TIME.\r
 753  *\r
 754  * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for\r
 755  * additional information.\r
 756  *\r
 757  * @param xStreamBuffer The handle of the stream buffer from which data was\r
 758  * read.\r
 759  *\r
 760  * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be\r
 761  * initialised to pdFALSE before it is passed into\r
 762  * xMessageBufferReceiveCompletedFromISR().  If calling\r
 763  * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state,\r
 764  * and the task has a priority above the priority of the currently running task,\r
 765  * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a\r
 766  * context switch should be performed before exiting the ISR.\r
 767  *\r
 768  * @return If a task was removed from the Blocked state then pdTRUE is returned.\r
 769  * Otherwise pdFALSE is returned.\r
 770  *\r
 771  * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR\r
 772  * \ingroup StreamBufferManagement\r
 773  */\r
 774 #define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferReceiveCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )\r
 775 \r
 776 #if defined( __cplusplus )\r
 777 } /* extern "C" */\r
 778 #endif\r
 779 \r
 780 #endif  /* !defined( FREERTOS_MESSAGE_BUFFER_H ) */\r