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

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