begriffs open source - cmsis-freertos/blob - Source/include/message_buffer.h

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