[freertos] / FreeRTOS / Source / include / message_buffer.h

/*\r
 * FreeRTOS Kernel V10.2.0\r
 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
 *\r
 * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
 * this software and associated documentation files (the "Software"), to deal in\r
 * the Software without restriction, including without limitation the rights to\r
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
 * the Software, and to permit persons to whom the Software is furnished to do so,\r
 * subject to the following conditions:\r
 *\r
 * The above copyright notice and this permission notice shall be included in all\r
 * copies or substantial portions of the Software.\r
 *\r
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
 *\r
 * http://www.FreeRTOS.org\r
 * http://aws.amazon.com/freertos\r
 *\r
 * 1 tab == 4 spaces!\r
 */\r
\r
\r
/*\r
 * Message buffers build functionality on top of FreeRTOS stream buffers.\r
 * Whereas stream buffers are used to send a continuous stream of data from one\r
 * task or interrupt to another, message buffers are used to send variable\r
 * length discrete messages from one task or interrupt to another.  Their\r
 * implementation is light weight, making them particularly suited for interrupt\r
 * to task and core to core communication scenarios.\r
 *\r
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 * implementation (so also the message buffer implementation, as message buffers\r
 * are built on top of stream buffers) assumes there is only one task or\r
 * interrupt that will write to the buffer (the writer), and only one task or\r
 * interrupt that will read from the buffer (the reader).  It is safe for the\r
 * writer and reader to be different tasks or interrupts, but, unlike other\r
 * FreeRTOS objects, it is not safe to have multiple different writers or\r
 * multiple different readers.  If there are to be multiple different writers\r
 * then the application writer must place each call to a writing API function\r
 * (such as xMessageBufferSend()) inside a critical section and set the send\r
 * block time to 0.  Likewise, if there are to be multiple different readers\r
 * then the application writer must place each call to a reading API function\r
 * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 * timeout to 0.\r
 *\r
 * Message buffers hold variable length messages.  To enable that, when a\r
 * message is written to the message buffer an additional sizeof( size_t ) bytes\r
 * are also written to store the message's length (that happens internally, with\r
 * the API function).  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
 * architecture, so writing a 10 byte message to a message buffer on a 32-bit\r
 * architecture will actually reduce the available space in the message buffer\r
 * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length\r
 * of the message).\r
 */\r
\r
#ifndef FREERTOS_MESSAGE_BUFFER_H\r
#define FREERTOS_MESSAGE_BUFFER_H\r
\r
/* Message buffers are built onto of stream buffers. */\r
#include "stream_buffer.h"\r
\r
#if defined( __cplusplus )\r
extern "C" {\r
#endif\r
\r
/**\r
 * Type by which message buffers are referenced.  For example, a call to\r
 * xMessageBufferCreate() returns an MessageBufferHandle_t variable that can\r
 * then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(),\r
 * etc.\r
 */\r
typedef void * MessageBufferHandle_t;\r
\r
/*-----------------------------------------------------------*/\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );\r
</pre>\r
 *\r
 * Creates a new message buffer using dynamically allocated memory.  See\r
 * xMessageBufferCreateStatic() for a version that uses statically allocated\r
 * memory (memory that is allocated at compile time).\r
 *\r
 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in\r
 * FreeRTOSConfig.h for xMessageBufferCreate() to be available.\r
 *\r
 * @param xBufferSizeBytes The total number of bytes (not messages) the message\r
 * buffer will be able to hold at any one time.  When a message is written to\r
 * the message buffer an additional sizeof( size_t ) bytes are also written to\r
 * store the message's length.  sizeof( size_t ) is typically 4 bytes on a\r
 * 32-bit architecture, so on most 32-bit architectures a 10 byte message will\r
 * take up 14 bytes of message buffer space.\r
 *\r
 * @return If NULL is returned, then the message buffer cannot be created\r
 * because there is insufficient heap memory available for FreeRTOS to allocate\r
 * the message buffer data structures and storage area.  A non-NULL value being\r
 * returned indicates that the message buffer has been created successfully -\r
 * the returned value should be stored as the handle to the created message\r
 * buffer.\r
 *\r
 * Example use:\r
<pre>\r
\r
void vAFunction( void )\r
{\r
MessageBufferHandle_t xMessageBuffer;\r
const size_t xMessageBufferSizeBytes = 100;\r
\r
    // Create a message buffer that can hold 100 bytes.  The memory used to hold\r
    // both the message buffer structure and the messages themselves is allocated\r
    // dynamically.  Each message added to the buffer consumes an additional 4\r
    // bytes which are used to hold the lengh of the message.\r
    xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );\r
\r
    if( xMessageBuffer == NULL )\r
    {\r
        // There was not enough heap memory space available to create the\r
        // message buffer.\r
    }\r
    else\r
    {\r
        // The message buffer was created successfully and can now be used.\r
    }\r
\r
</pre>\r
 * \defgroup xMessageBufferCreate xMessageBufferCreate\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferCreate( xBufferSizeBytes ) ( MessageBufferHandle_t ) xStreamBufferGenericCreate( xBufferSizeBytes, ( size_t ) 0, pdTRUE )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,\r
                                                  uint8_t *pucMessageBufferStorageArea,\r
                                                  StaticMessageBuffer_t *pxStaticMessageBuffer );\r
</pre>\r
 * Creates a new message buffer using statically allocated memory.  See\r
 * xMessageBufferCreate() for a version that uses dynamically allocated memory.\r
 *\r
 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the\r
 * pucMessageBufferStorageArea parameter.  When a message is written to the\r
 * message buffer an additional sizeof( size_t ) bytes are also written to store\r
 * the message's length.  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
 * architecture, so on most 32-bit architecture a 10 byte message will take up\r
 * 14 bytes of message buffer space.  The maximum number of bytes that can be\r
 * stored in the message buffer is actually (xBufferSizeBytes - 1).\r
 *\r
 * @param pucMessageBufferStorageArea Must point to a uint8_t array that is at\r
 * least xBufferSizeBytes + 1 big.  This is the array to which messages are\r
 * copied when they are written to the message buffer.\r
 *\r
 * @param pxStaticMessageBuffer Must point to a variable of type\r
 * StaticMessageBuffer_t, which will be used to hold the message buffer's data\r
 * structure.\r
 *\r
 * @return If the message buffer is created successfully then a handle to the\r
 * created message buffer is returned. If either pucMessageBufferStorageArea or\r
 * pxStaticmessageBuffer are NULL then NULL is returned.\r
 *\r
 * Example use:\r
<pre>\r
\r
// Used to dimension the array used to hold the messages.  The available space\r
// will actually be one less than this, so 999.\r
#define STORAGE_SIZE_BYTES 1000\r
\r
// Defines the memory that will actually hold the messages within the message\r
// buffer.\r
static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];\r
\r
// The variable used to hold the message buffer structure.\r
StaticMessageBuffer_t xMessageBufferStruct;\r
\r
void MyFunction( void )\r
{\r
MessageBufferHandle_t xMessageBuffer;\r
\r
    xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),\r
                                                 ucBufferStorage,\r
                                                 &xMessageBufferStruct );\r
\r
    // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer\r
    // parameters were NULL, xMessageBuffer will not be NULL, and can be used to\r
    // reference the created message buffer in other message buffer API calls.\r
\r
    // Other code that uses the message buffer can go here.\r
}\r
\r
</pre>\r
 * \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) ( MessageBufferHandle_t ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, 0, pdTRUE, pucMessageBufferStorageArea, pxStaticMessageBuffer )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,\r
                           const void *pvTxData,\r
                           size_t xDataLengthBytes,\r
                           TickType_t xTicksToWait );\r
<pre>\r
 *\r
 * Sends a discrete message to the message buffer.  The message can be any\r
 * length that fits within the buffer's free space, and is copied into the\r
 * buffer.\r
 *\r
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 * implementation (so also the message buffer implementation, as message buffers\r
 * are built on top of stream buffers) assumes there is only one task or\r
 * interrupt that will write to the buffer (the writer), and only one task or\r
 * interrupt that will read from the buffer (the reader).  It is safe for the\r
 * writer and reader to be different tasks or interrupts, but, unlike other\r
 * FreeRTOS objects, it is not safe to have multiple different writers or\r
 * multiple different readers.  If there are to be multiple different writers\r
 * then the application writer must place each call to a writing API function\r
 * (such as xMessageBufferSend()) inside a critical section and set the send\r
 * block time to 0.  Likewise, if there are to be multiple different readers\r
 * then the application writer must place each call to a reading API function\r
 * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 * block time to 0.\r
 *\r
 * Use xMessageBufferSend() to write to a message buffer from a task.  Use\r
 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt\r
 * service routine (ISR).\r
 *\r
 * @param xMessageBuffer The handle of the message buffer to which a message is\r
 * being sent.\r
 *\r
 * @param pvTxData A pointer to the message that is to be copied into the\r
 * message buffer.\r
 *\r
 * @param xDataLengthBytes The length of the message.  That is, the number of\r
 * bytes to copy from pvTxData into the message buffer.  When a message is\r
 * written to the message buffer an additional sizeof( size_t ) bytes are also\r
 * written to store the message's length.  sizeof( size_t ) is typically 4 bytes\r
 * on a 32-bit architecture, so on most 32-bit architecture setting\r
 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24\r
 * bytes (20 bytes of message data and 4 bytes to hold the message length).\r
 *\r
 * @param xTicksToWait The maximum amount of time the calling task should remain\r
 * in the Blocked state to wait for enough space to become available in the\r
 * message buffer, should the message buffer have insufficient space when\r
 * xMessageBufferSend() is called.  The calling task will never block if\r
 * xTicksToWait is zero.  The block time is specified in tick periods, so the\r
 * absolute time it represents is dependent on the tick frequency.  The macro\r
 * pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into\r
 * a time specified in ticks.  Setting xTicksToWait to portMAX_DELAY will cause\r
 * the task to wait indefinitely (without timing out), provided\r
 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.  Tasks do not use any\r
 * CPU time when they are in the Blocked state.\r
 *\r
 * @return The number of bytes written to the message buffer.  If the call to\r
 * xMessageBufferSend() times out before there was enough space to write the\r
 * message into the message buffer then zero is returned.  If the call did not\r
 * time out then xDataLengthBytes is returned.\r
 *\r
 * Example use:\r
<pre>\r
void vAFunction( MessageBufferHandle_t xMessageBuffer )\r
{\r
size_t xBytesSent;\r
uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };\r
char *pcStringToSend = "String to send";\r
const TickType_t x100ms = pdMS_TO_TICKS( 100 );\r
\r
    // Send an array to the message buffer, blocking for a maximum of 100ms to\r
    // wait for enough space to be available in the message buffer.\r
    xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );\r
\r
    if( xBytesSent != sizeof( ucArrayToSend ) )\r
    {\r
        // The call to xMessageBufferSend() times out before there was enough\r
        // space in the buffer for the data to be written.\r
    }\r
\r
    // Send the string to the message buffer.  Return immediately if there is\r
    // not enough space in the buffer.\r
    xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );\r
\r
    if( xBytesSent != strlen( pcStringToSend ) )\r
    {\r
        // The string could not be added to the message buffer because there was\r
        // not enough free space in the buffer.\r
    }\r
}\r
</pre>\r
 * \defgroup xMessageBufferSend xMessageBufferSend\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) xStreamBufferSend( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,\r
                                  const void *pvTxData,\r
                                  size_t xDataLengthBytes,\r
                                  BaseType_t *pxHigherPriorityTaskWoken );\r
<pre>\r
 *\r
 * Interrupt safe version of the API function that sends a discrete message to\r
 * the message buffer.  The message can be any length that fits within the\r
 * buffer's free space, and is copied into the buffer.\r
 *\r
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 * implementation (so also the message buffer implementation, as message buffers\r
 * are built on top of stream buffers) assumes there is only one task or\r
 * interrupt that will write to the buffer (the writer), and only one task or\r
 * interrupt that will read from the buffer (the reader).  It is safe for the\r
 * writer and reader to be different tasks or interrupts, but, unlike other\r
 * FreeRTOS objects, it is not safe to have multiple different writers or\r
 * multiple different readers.  If there are to be multiple different writers\r
 * then the application writer must place each call to a writing API function\r
 * (such as xMessageBufferSend()) inside a critical section and set the send\r
 * block time to 0.  Likewise, if there are to be multiple different readers\r
 * then the application writer must place each call to a reading API function\r
 * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 * block time to 0.\r
 *\r
 * Use xMessageBufferSend() to write to a message buffer from a task.  Use\r
 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt\r
 * service routine (ISR).\r
 *\r
 * @param xMessageBuffer The handle of the message buffer to which a message is\r
 * being sent.\r
 *\r
 * @param pvTxData A pointer to the message that is to be copied into the\r
 * message buffer.\r
 *\r
 * @param xDataLengthBytes The length of the message.  That is, the number of\r
 * bytes to copy from pvTxData into the message buffer.  When a message is\r
 * written to the message buffer an additional sizeof( size_t ) bytes are also\r
 * written to store the message's length.  sizeof( size_t ) is typically 4 bytes\r
 * on a 32-bit architecture, so on most 32-bit architecture setting\r
 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24\r
 * bytes (20 bytes of message data and 4 bytes to hold the message length).\r
 *\r
 * @param pxHigherPriorityTaskWoken  It is possible that a message buffer will\r
 * have a task blocked on it waiting for data.  Calling\r
 * xMessageBufferSendFromISR() can make data available, and so cause a task that\r
 * was waiting for data to leave the Blocked state.  If calling\r
 * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the\r
 * unblocked task has a priority higher than the currently executing task (the\r
 * task that was interrupted), then, internally, xMessageBufferSendFromISR()\r
 * will set *pxHigherPriorityTaskWoken to pdTRUE.  If\r
 * xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a\r
 * context switch should be performed before the interrupt is exited.  This will\r
 * ensure that the interrupt returns directly to the highest priority Ready\r
 * state task.  *pxHigherPriorityTaskWoken should be set to pdFALSE before it\r
 * is passed into the function.  See the code example below for an example.\r
 *\r
 * @return The number of bytes actually written to the message buffer.  If the\r
 * message buffer didn't have enough free space for the message to be stored\r
 * then 0 is returned, otherwise xDataLengthBytes is returned.\r
 *\r
 * Example use:\r
<pre>\r
// A message buffer that has already been created.\r
MessageBufferHandle_t xMessageBuffer;\r
\r
void vAnInterruptServiceRoutine( void )\r
{\r
size_t xBytesSent;\r
char *pcStringToSend = "String to send";\r
BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.\r
\r
    // Attempt to send the string to the message buffer.\r
    xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,\r
                                            ( void * ) pcStringToSend,\r
                                            strlen( pcStringToSend ),\r
                                            &xHigherPriorityTaskWoken );\r
\r
    if( xBytesSent != strlen( pcStringToSend ) )\r
    {\r
        // The string could not be added to the message buffer because there was\r
        // not enough free space in the buffer.\r
    }\r
\r
    // If xHigherPriorityTaskWoken was set to pdTRUE inside\r
    // xMessageBufferSendFromISR() then a task that has a priority above the\r
    // priority of the currently executing task was unblocked and a context\r
    // switch should be performed to ensure the ISR returns to the unblocked\r
    // task.  In most FreeRTOS ports this is done by simply passing\r
    // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the\r
    // variables value, and perform the context switch if necessary.  Check the\r
    // documentation for the port in use for port specific instructions.\r
    taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );\r
}\r
</pre>\r
 * \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferSendFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,\r
                              void *pvRxData,\r
                              size_t xBufferLengthBytes,\r
                              TickType_t xTicksToWait );\r
</pre>\r
 *\r
 * Receives a discrete message from a message buffer.  Messages can be of\r
 * variable length and are copied out of the buffer.\r
 *\r
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 * implementation (so also the message buffer implementation, as message buffers\r
 * are built on top of stream buffers) assumes there is only one task or\r
 * interrupt that will write to the buffer (the writer), and only one task or\r
 * interrupt that will read from the buffer (the reader).  It is safe for the\r
 * writer and reader to be different tasks or interrupts, but, unlike other\r
 * FreeRTOS objects, it is not safe to have multiple different writers or\r
 * multiple different readers.  If there are to be multiple different writers\r
 * then the application writer must place each call to a writing API function\r
 * (such as xMessageBufferSend()) inside a critical section and set the send\r
 * block time to 0.  Likewise, if there are to be multiple different readers\r
 * then the application writer must place each call to a reading API function\r
 * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 * block time to 0.\r
 *\r
 * Use xMessageBufferReceive() to read from a message buffer from a task.  Use\r
 * xMessageBufferReceiveFromISR() to read from a message buffer from an\r
 * interrupt service routine (ISR).\r
 *\r
 * @param xMessageBuffer The handle of the message buffer from which a message\r
 * is being received.\r
 *\r
 * @param pvRxData A pointer to the buffer into which the received message is\r
 * to be copied.\r
 *\r
 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData\r
 * parameter.  This sets the maximum length of the message that can be received.\r
 * If xBufferLengthBytes is too small to hold the next message then the message\r
 * will be left in the message buffer and 0 will be returned.\r
 *\r
 * @param xTicksToWait The maximum amount of time the task should remain in the\r
 * Blocked state to wait for a message, should the message buffer be empty.\r
 * xMessageBufferReceive() will return immediately if xTicksToWait is zero and\r
 * the message buffer is empty.  The block time is specified in tick periods, so\r
 * the absolute time it represents is dependent on the tick frequency.  The\r
 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds\r
 * into a time specified in ticks.  Setting xTicksToWait to portMAX_DELAY will\r
 * cause the task to wait indefinitely (without timing out), provided\r
 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.  Tasks do not use any\r
 * CPU time when they are in the Blocked state.\r
 *\r
 * @return The length, in bytes, of the message read from the message buffer, if\r
 * any.  If xMessageBufferReceive() times out before a message became available\r
 * then zero is returned.  If the length of the message is greater than\r
 * xBufferLengthBytes then the message will be left in the message buffer and\r
 * zero is returned.\r
 *\r
 * Example use:\r
<pre>\r
void vAFunction( MessageBuffer_t xMessageBuffer )\r
{\r
uint8_t ucRxData[ 20 ];\r
size_t xReceivedBytes;\r
const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );\r
\r
    // Receive the next message from the message buffer.  Wait in the Blocked\r
    // state (so not using any CPU processing time) for a maximum of 100ms for\r
    // a message to become available.\r
    xReceivedBytes = xMessageBufferReceive( xMessageBuffer,\r
                                            ( void * ) ucRxData,\r
                                            sizeof( ucRxData ),\r
                                            xBlockTime );\r
\r
    if( xReceivedBytes > 0 )\r
    {\r
        // A ucRxData contains a message that is xReceivedBytes long.  Process\r
        // the message here....\r
    }\r
}\r
</pre>\r
 * \defgroup xMessageBufferReceive xMessageBufferReceive\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) xStreamBufferReceive( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait )\r
\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,\r
                                     void *pvRxData,\r
                                     size_t xBufferLengthBytes,\r
                                     BaseType_t *pxHigherPriorityTaskWoken );\r
</pre>\r
 *\r
 * An interrupt safe version of the API function that receives a discrete\r
 * message from a message buffer.  Messages can be of variable length and are\r
 * copied out of the buffer.\r
 *\r
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer\r
 * implementation (so also the message buffer implementation, as message buffers\r
 * are built on top of stream buffers) assumes there is only one task or\r
 * interrupt that will write to the buffer (the writer), and only one task or\r
 * interrupt that will read from the buffer (the reader).  It is safe for the\r
 * writer and reader to be different tasks or interrupts, but, unlike other\r
 * FreeRTOS objects, it is not safe to have multiple different writers or\r
 * multiple different readers.  If there are to be multiple different writers\r
 * then the application writer must place each call to a writing API function\r
 * (such as xMessageBufferSend()) inside a critical section and set the send\r
 * block time to 0.  Likewise, if there are to be multiple different readers\r
 * then the application writer must place each call to a reading API function\r
 * (such as xMessageBufferRead()) inside a critical section and set the receive\r
 * block time to 0.\r
 *\r
 * Use xMessageBufferReceive() to read from a message buffer from a task.  Use\r
 * xMessageBufferReceiveFromISR() to read from a message buffer from an\r
 * interrupt service routine (ISR).\r
 *\r
 * @param xMessageBuffer The handle of the message buffer from which a message\r
 * is being received.\r
 *\r
 * @param pvRxData A pointer to the buffer into which the received message is\r
 * to be copied.\r
 *\r
 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData\r
 * parameter.  This sets the maximum length of the message that can be received.\r
 * If xBufferLengthBytes is too small to hold the next message then the message\r
 * will be left in the message buffer and 0 will be returned.\r
 *\r
 * @param pxHigherPriorityTaskWoken  It is possible that a message buffer will\r
 * have a task blocked on it waiting for space to become available.  Calling\r
 * xMessageBufferReceiveFromISR() can make space available, and so cause a task\r
 * that is waiting for space to leave the Blocked state.  If calling\r
 * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and\r
 * the unblocked task has a priority higher than the currently executing task\r
 * (the task that was interrupted), then, internally,\r
 * xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.\r
 * If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a\r
 * context switch should be performed before the interrupt is exited.  That will\r
 * ensure the interrupt returns directly to the highest priority Ready state\r
 * task.  *pxHigherPriorityTaskWoken should be set to pdFALSE before it is\r
 * passed into the function.  See the code example below for an example.\r
 *\r
 * @return The length, in bytes, of the message read from the message buffer, if\r
 * any.\r
 *\r
 * Example use:\r
<pre>\r
// A message buffer that has already been created.\r
MessageBuffer_t xMessageBuffer;\r
\r
void vAnInterruptServiceRoutine( void )\r
{\r
uint8_t ucRxData[ 20 ];\r
size_t xReceivedBytes;\r
BaseType_t xHigherPriorityTaskWoken = pdFALSE;  // Initialised to pdFALSE.\r
\r
    // Receive the next message from the message buffer.\r
    xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,\r
                                                  ( void * ) ucRxData,\r
                                                  sizeof( ucRxData ),\r
                                                  &xHigherPriorityTaskWoken );\r
\r
    if( xReceivedBytes > 0 )\r
    {\r
        // A ucRxData contains a message that is xReceivedBytes long.  Process\r
        // the message here....\r
    }\r
\r
    // If xHigherPriorityTaskWoken was set to pdTRUE inside\r
    // xMessageBufferReceiveFromISR() then a task that has a priority above the\r
    // priority of the currently executing task was unblocked and a context\r
    // switch should be performed to ensure the ISR returns to the unblocked\r
    // task.  In most FreeRTOS ports this is done by simply passing\r
    // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the\r
    // variables value, and perform the context switch if necessary.  Check the\r
    // documentation for the port in use for port specific instructions.\r
    taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );\r
}\r
</pre>\r
 * \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferReceiveFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );\r
</pre>\r
 *\r
 * Deletes a message buffer that was previously created using a call to\r
 * xMessageBufferCreate() or xMessageBufferCreateStatic().  If the message\r
 * buffer was created using dynamic memory (that is, by xMessageBufferCreate()),\r
 * then the allocated memory is freed.\r
 *\r
 * A message buffer handle must not be used after the message buffer has been\r
 * deleted.\r
 *\r
 * @param xMessageBuffer The handle of the message buffer to be deleted.\r
 *\r
 */\r
#define vMessageBufferDelete( xMessageBuffer ) vStreamBufferDelete( ( StreamBufferHandle_t ) xMessageBuffer )\r
\r
/**\r
 * message_buffer.h\r
<pre>\r
BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ) );\r
</pre>\r
 *\r
 * Tests to see if a message buffer is full.  A message buffer is full if it\r
 * cannot accept any more messages, of any size, until space is made available\r
 * by a message being removed from the message buffer.\r
 *\r
 * @param xMessageBuffer The handle of the message buffer being queried.\r
 *\r
 * @return If the message buffer referenced by xMessageBuffer is full then\r
 * pdTRUE is returned.  Otherwise pdFALSE is returned.\r
 */\r
#define xMessageBufferIsFull( xMessageBuffer ) xStreamBufferIsFull( ( StreamBufferHandle_t ) xMessageBuffer )\r
\r
/**\r
 * message_buffer.h\r
<pre>\r
BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ) );\r
</pre>\r
 *\r
 * Tests to see if a message buffer is empty (does not contain any messages).\r
 *\r
 * @param xMessageBuffer The handle of the message buffer being queried.\r
 *\r
 * @return If the message buffer referenced by xMessageBuffer is empty then\r
 * pdTRUE is returned.  Otherwise pdFALSE is returned.\r
 *\r
 */\r
#define xMessageBufferIsEmpty( xMessageBuffer ) xStreamBufferIsEmpty( ( StreamBufferHandle_t ) xMessageBuffer )\r
\r
/**\r
 * message_buffer.h\r
<pre>\r
BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );\r
</pre>\r
 *\r
 * Resets a message buffer to its initial empty state, discarding any message it\r
 * contained.\r
 *\r
 * A message buffer can only be reset if there are no tasks blocked on it.\r
 *\r
 * @param xMessageBuffer The handle of the message buffer being reset.\r
 *\r
 * @return If the message buffer was reset then pdPASS is returned.  If the\r
 * message buffer could not be reset because either there was a task blocked on\r
 * the message queue to wait for space to become available, or to wait for a\r
 * a message to be available, then pdFAIL is returned.\r
 *\r
 * \defgroup xMessageBufferReset xMessageBufferReset\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferReset( xMessageBuffer ) xStreamBufferReset( ( StreamBufferHandle_t ) xMessageBuffer )\r
\r
\r
/**\r
 * message_buffer.h\r
<pre>\r
size_t xMessageBufferSpaceAvailable( MessageBufferHandle_t xMessageBuffer ) );\r
</pre>\r
 * Returns the number of bytes of free space in the message buffer.\r
 *\r
 * @param xMessageBuffer The handle of the message buffer being queried.\r
 *\r
 * @return The number of bytes that can be written to the message buffer before\r
 * the message buffer would be full.  When a message is written to the message\r
 * buffer an additional sizeof( size_t ) bytes are also written to store the\r
 * message's length.  sizeof( size_t ) is typically 4 bytes on a 32-bit\r
 * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size\r
 * of the largest message that can be written to the message buffer is 6 bytes.\r
 *\r
 * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferSpaceAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer )\r
\r
/**\r
 * message_buffer.h\r
 <pre>\r
 size_t xMessageBufferNextLengthBytes( MessageBufferHandle_t xMessageBuffer ) );\r
 </pre>\r
 * Returns the length (in bytes) of the next message in a message buffer.\r
 * Useful if xMessageBufferReceive() returned 0 because the size of the buffer\r
 * passed into xMessageBufferReceive() was too small to hold the next message.\r
 *\r
 * @param xMessageBuffer The handle of the message buffer being queried.\r
 *\r
 * @return The length (in bytes) of the next message in the message buffer, or 0\r
 * if the message buffer is empty.\r
 *\r
 * \defgroup xMessageBufferNextLengthBytes xMessageBufferNextLengthBytes\r
 * \ingroup MessageBufferManagement\r
 */\r
#define xMessageBufferNextLengthBytes( xMessageBuffer ) xStreamBufferNextMessageLengthBytes( ( StreamBufferHandle_t ) xMessageBuffer ) PRIVILEGED_FUNCTION;\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );\r
</pre>\r
 *\r
 * For advanced users only.\r
 *\r
 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when\r
 * data is sent to a message buffer or stream buffer.  If there was a task that\r
 * was blocked on the message or stream buffer waiting for data to arrive then\r
 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it\r
 * from the Blocked state.  xMessageBufferSendCompletedFromISR() does the same\r
 * thing.  It is provided to enable application writers to implement their own\r
 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.\r
 *\r
 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for\r
 * additional information.\r
 *\r
 * @param xStreamBuffer The handle of the stream buffer to which data was\r
 * written.\r
 *\r
 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be\r
 * initialised to pdFALSE before it is passed into\r
 * xMessageBufferSendCompletedFromISR().  If calling\r
 * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state,\r
 * and the task has a priority above the priority of the currently running task,\r
 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a\r
 * context switch should be performed before exiting the ISR.\r
 *\r
 * @return If a task was removed from the Blocked state then pdTRUE is returned.\r
 * Otherwise pdFALSE is returned.\r
 *\r
 * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR\r
 * \ingroup StreamBufferManagement\r
 */\r
#define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferSendCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )\r
\r
/**\r
 * message_buffer.h\r
 *\r
<pre>\r
BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );\r
</pre>\r
 *\r
 * For advanced users only.\r
 *\r
 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when\r
 * data is read out of a message buffer or stream buffer.  If there was a task\r
 * that was blocked on the message or stream buffer waiting for data to arrive\r
 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to\r
 * remove it from the Blocked state.  xMessageBufferReceiveCompletedFromISR()\r
 * does the same thing.  It is provided to enable application writers to\r
 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT\r
 * ANY OTHER TIME.\r
 *\r
 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for\r
 * additional information.\r
 *\r
 * @param xStreamBuffer The handle of the stream buffer from which data was\r
 * read.\r
 *\r
 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be\r
 * initialised to pdFALSE before it is passed into\r
 * xMessageBufferReceiveCompletedFromISR().  If calling\r
 * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state,\r
 * and the task has a priority above the priority of the currently running task,\r
 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a\r
 * context switch should be performed before exiting the ISR.\r
 *\r
 * @return If a task was removed from the Blocked state then pdTRUE is returned.\r
 * Otherwise pdFALSE is returned.\r
 *\r
 * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR\r
 * \ingroup StreamBufferManagement\r
 */\r
#define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferReceiveCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )\r
\r
#if defined( __cplusplus )\r
} /* extern "C" */\r
#endif\r
\r
#endif  /* !defined( FREERTOS_MESSAGE_BUFFER_H ) */\r