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

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