/* * FreeRTOS Kernel V10.1.1 * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do so, * subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * * http://www.FreeRTOS.org * http://aws.amazon.com/freertos * * 1 tab == 4 spaces! */ /* * Message buffers build functionality on top of FreeRTOS stream buffers. * Whereas stream buffers are used to send a continuous stream of data from one * task or interrupt to another, message buffers are used to send variable * length discrete messages from one task or interrupt to another. Their * implementation is light weight, making them particularly suited for interrupt * to task and core to core communication scenarios. * * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer * implementation (so also the message buffer implementation, as message buffers * are built on top of stream buffers) assumes there is only one task or * interrupt that will write to the buffer (the writer), and only one task or * interrupt that will read from the buffer (the reader). It is safe for the * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers * then the application writer must place each call to a writing API function * (such as xMessageBufferSend()) inside a critical section and set the send * block time to 0. Likewise, if there are to be multiple different readers * then the application writer must place each call to a reading API function * (such as xMessageBufferRead()) inside a critical section and set the receive * timeout to 0. * * Message buffers hold variable length messages. To enable that, when a * message is written to the message buffer an additional sizeof( size_t ) bytes * are also written to store the message's length (that happens internally, with * the API function). sizeof( size_t ) is typically 4 bytes on a 32-bit * architecture, so writing a 10 byte message to a message buffer on a 32-bit * architecture will actually reduce the available space in the message buffer * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length * of the message). */ #ifndef FREERTOS_MESSAGE_BUFFER_H #define FREERTOS_MESSAGE_BUFFER_H /* Message buffers are built onto of stream buffers. */ #include "stream_buffer.h" #if defined( __cplusplus ) extern "C" { #endif /** * Type by which message buffers are referenced. For example, a call to * xMessageBufferCreate() returns an MessageBufferHandle_t variable that can * then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(), * etc. */ typedef void * MessageBufferHandle_t; /*-----------------------------------------------------------*/ /** * message_buffer.h *
MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );
* * Creates a new message buffer using dynamically allocated memory. See * xMessageBufferCreateStatic() for a version that uses statically allocated * memory (memory that is allocated at compile time). * * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in * FreeRTOSConfig.h for xMessageBufferCreate() to be available. * * @param xBufferSizeBytes The total number of bytes (not messages) the message * buffer will be able to hold at any one time. When a message is written to * the message buffer an additional sizeof( size_t ) bytes are also written to * store the message's length. sizeof( size_t ) is typically 4 bytes on a * 32-bit architecture, so on most 32-bit architectures a 10 byte message will * take up 14 bytes of message buffer space. * * @return If NULL is returned, then the message buffer cannot be created * because there is insufficient heap memory available for FreeRTOS to allocate * the message buffer data structures and storage area. A non-NULL value being * returned indicates that the message buffer has been created successfully - * the returned value should be stored as the handle to the created message * buffer. * * Example use:

void vAFunction( void )
{
MessageBufferHandle_t xMessageBuffer;
const size_t xMessageBufferSizeBytes = 100;

    // Create a message buffer that can hold 100 bytes.  The memory used to hold
    // both the message buffer structure and the messages themselves is allocated
    // dynamically.  Each message added to the buffer consumes an additional 4
    // bytes which are used to hold the lengh of the message.
    xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );

    if( xMessageBuffer == NULL )
    {
        // There was not enough heap memory space available to create the
        // message buffer.
    }
    else
    {
        // The message buffer was created successfully and can now be used.
    }

* \defgroup xMessageBufferCreate xMessageBufferCreate * \ingroup MessageBufferManagement */ #define xMessageBufferCreate( xBufferSizeBytes ) ( MessageBufferHandle_t ) xStreamBufferGenericCreate( xBufferSizeBytes, ( size_t ) 0, pdTRUE ) /** * message_buffer.h *
MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
                                                  uint8_t *pucMessageBufferStorageArea,
                                                  StaticMessageBuffer_t *pxStaticMessageBuffer );
* Creates a new message buffer using statically allocated memory. See * xMessageBufferCreate() for a version that uses dynamically allocated memory. * * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the * pucMessageBufferStorageArea parameter. When a message is written to the * message buffer an additional sizeof( size_t ) bytes are also written to store * the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit * architecture, so on most 32-bit architecture a 10 byte message will take up * 14 bytes of message buffer space. The maximum number of bytes that can be * stored in the message buffer is actually (xBufferSizeBytes - 1). * * @param pucMessageBufferStorageArea Must point to a uint8_t array that is at * least xBufferSizeBytes + 1 big. This is the array to which messages are * copied when they are written to the message buffer. * * @param pxStaticMessageBuffer Must point to a variable of type * StaticMessageBuffer_t, which will be used to hold the message buffer's data * structure. * * @return If the message buffer is created successfully then a handle to the * created message buffer is returned. If either pucMessageBufferStorageArea or * pxStaticmessageBuffer are NULL then NULL is returned. * * Example use:

// Used to dimension the array used to hold the messages.  The available space
// will actually be one less than this, so 999.
#define STORAGE_SIZE_BYTES 1000

// Defines the memory that will actually hold the messages within the message
// buffer.
static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];

// The variable used to hold the message buffer structure.
StaticMessageBuffer_t xMessageBufferStruct;

void MyFunction( void )
{
MessageBufferHandle_t xMessageBuffer;

    xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),
                                                 ucBufferStorage,
                                                 &xMessageBufferStruct );

    // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer
    // parameters were NULL, xMessageBuffer will not be NULL, and can be used to
    // reference the created message buffer in other message buffer API calls.

    // Other code that uses the message buffer can go here.
}

* \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic * \ingroup MessageBufferManagement */ #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) ( MessageBufferHandle_t ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, 0, pdTRUE, pucMessageBufferStorageArea, pxStaticMessageBuffer ) /** * message_buffer.h *
size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
                           const void *pvTxData,
                           size_t xDataLengthBytes,
                           TickType_t xTicksToWait );
 *
 * Sends a discrete message to the message buffer.  The message can be any
 * length that fits within the buffer's free space, and is copied into the
 * buffer.
 *
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer
 * implementation (so also the message buffer implementation, as message buffers
 * are built on top of stream buffers) assumes there is only one task or
 * interrupt that will write to the buffer (the writer), and only one task or
 * interrupt that will read from the buffer (the reader).  It is safe for the
 * writer and reader to be different tasks or interrupts, but, unlike other
 * FreeRTOS objects, it is not safe to have multiple different writers or
 * multiple different readers.  If there are to be multiple different writers
 * then the application writer must place each call to a writing API function
 * (such as xMessageBufferSend()) inside a critical section and set the send
 * block time to 0.  Likewise, if there are to be multiple different readers
 * then the application writer must place each call to a reading API function
 * (such as xMessageBufferRead()) inside a critical section and set the receive
 * block time to 0.
 *
 * Use xMessageBufferSend() to write to a message buffer from a task.  Use
 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
 * service routine (ISR).
 *
 * @param xMessageBuffer The handle of the message buffer to which a message is
 * being sent.
 *
 * @param pvTxData A pointer to the message that is to be copied into the
 * message buffer.
 *
 * @param xDataLengthBytes The length of the message.  That is, the number of
 * bytes to copy from pvTxData into the message buffer.  When a message is
 * written to the message buffer an additional sizeof( size_t ) bytes are also
 * written to store the message's length.  sizeof( size_t ) is typically 4 bytes
 * on a 32-bit architecture, so on most 32-bit architecture setting
 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
 * bytes (20 bytes of message data and 4 bytes to hold the message length).
 *
 * @param xTicksToWait The maximum amount of time the calling task should remain
 * in the Blocked state to wait for enough space to become available in the
 * message buffer, should the message buffer have insufficient space when
 * xMessageBufferSend() is called.  The calling task will never block if
 * xTicksToWait is zero.  The block time is specified in tick periods, so the
 * absolute time it represents is dependent on the tick frequency.  The macro
 * pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into
 * a time specified in ticks.  Setting xTicksToWait to portMAX_DELAY will cause
 * the task to wait indefinitely (without timing out), provided
 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.  Tasks do not use any
 * CPU time when they are in the Blocked state.
 *
 * @return The number of bytes written to the message buffer.  If the call to
 * xMessageBufferSend() times out before there was enough space to write the
 * message into the message buffer then zero is returned.  If the call did not
 * time out then xDataLengthBytes is returned.
 *
 * Example use:
void vAFunction( MessageBufferHandle_t xMessageBuffer )
{
size_t xBytesSent;
uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
char *pcStringToSend = "String to send";
const TickType_t x100ms = pdMS_TO_TICKS( 100 );

    // Send an array to the message buffer, blocking for a maximum of 100ms to
    // wait for enough space to be available in the message buffer.
    xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );

    if( xBytesSent != sizeof( ucArrayToSend ) )
    {
        // The call to xMessageBufferSend() times out before there was enough
        // space in the buffer for the data to be written.
    }

    // Send the string to the message buffer.  Return immediately if there is
    // not enough space in the buffer.
    xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );

    if( xBytesSent != strlen( pcStringToSend ) )
    {
        // The string could not be added to the message buffer because there was
        // not enough free space in the buffer.
    }
}
* \defgroup xMessageBufferSend xMessageBufferSend * \ingroup MessageBufferManagement */ #define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) xStreamBufferSend( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) /** * message_buffer.h *
size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
                                  const void *pvTxData,
                                  size_t xDataLengthBytes,
                                  BaseType_t *pxHigherPriorityTaskWoken );
 *
 * Interrupt safe version of the API function that sends a discrete message to
 * the message buffer.  The message can be any length that fits within the
 * buffer's free space, and is copied into the buffer.
 *
 * ***NOTE***:  Uniquely among FreeRTOS objects, the stream buffer
 * implementation (so also the message buffer implementation, as message buffers
 * are built on top of stream buffers) assumes there is only one task or
 * interrupt that will write to the buffer (the writer), and only one task or
 * interrupt that will read from the buffer (the reader).  It is safe for the
 * writer and reader to be different tasks or interrupts, but, unlike other
 * FreeRTOS objects, it is not safe to have multiple different writers or
 * multiple different readers.  If there are to be multiple different writers
 * then the application writer must place each call to a writing API function
 * (such as xMessageBufferSend()) inside a critical section and set the send
 * block time to 0.  Likewise, if there are to be multiple different readers
 * then the application writer must place each call to a reading API function
 * (such as xMessageBufferRead()) inside a critical section and set the receive
 * block time to 0.
 *
 * Use xMessageBufferSend() to write to a message buffer from a task.  Use
 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
 * service routine (ISR).
 *
 * @param xMessageBuffer The handle of the message buffer to which a message is
 * being sent.
 *
 * @param pvTxData A pointer to the message that is to be copied into the
 * message buffer.
 *
 * @param xDataLengthBytes The length of the message.  That is, the number of
 * bytes to copy from pvTxData into the message buffer.  When a message is
 * written to the message buffer an additional sizeof( size_t ) bytes are also
 * written to store the message's length.  sizeof( size_t ) is typically 4 bytes
 * on a 32-bit architecture, so on most 32-bit architecture setting
 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
 * bytes (20 bytes of message data and 4 bytes to hold the message length).
 *
 * @param pxHigherPriorityTaskWoken  It is possible that a message buffer will
 * have a task blocked on it waiting for data.  Calling
 * xMessageBufferSendFromISR() can make data available, and so cause a task that
 * was waiting for data to leave the Blocked state.  If calling
 * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the
 * unblocked task has a priority higher than the currently executing task (the
 * task that was interrupted), then, internally, xMessageBufferSendFromISR()
 * will set *pxHigherPriorityTaskWoken to pdTRUE.  If
 * xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a
 * context switch should be performed before the interrupt is exited.  This will
 * ensure that the interrupt returns directly to the highest priority Ready
 * state task.  *pxHigherPriorityTaskWoken should be set to pdFALSE before it
 * is passed into the function.  See the code example below for an example.
 *
 * @return The number of bytes actually written to the message buffer.  If the
 * message buffer didn't have enough free space for the message to be stored
 * then 0 is returned, otherwise xDataLengthBytes is returned.
 *
 * Example use:
// A message buffer that has already been created.
MessageBufferHandle_t xMessageBuffer;

void vAnInterruptServiceRoutine( void )
{
size_t xBytesSent;
char *pcStringToSend = "String to send";
BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.

    // Attempt to send the string to the message buffer.
    xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
                                            ( void * ) pcStringToSend,
                                            strlen( pcStringToSend ),
                                            &xHigherPriorityTaskWoken );

    if( xBytesSent != strlen( pcStringToSend ) )
    {
        // The string could not be added to the message buffer because there was
        // not enough free space in the buffer.
    }

    // If xHigherPriorityTaskWoken was set to pdTRUE inside
    // xMessageBufferSendFromISR() then a task that has a priority above the
    // priority of the currently executing task was unblocked and a context
    // switch should be performed to ensure the ISR returns to the unblocked
    // task.  In most FreeRTOS ports this is done by simply passing
    // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
    // variables value, and perform the context switch if necessary.  Check the
    // documentation for the port in use for port specific instructions.
    taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
* \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR * \ingroup MessageBufferManagement */ #define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferSendFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) /** * message_buffer.h *
size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
                              void *pvRxData,
                              size_t xBufferLengthBytes,
                              TickType_t xTicksToWait );
* * Receives a discrete message from a message buffer. Messages can be of * variable length and are copied out of the buffer. * * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer * implementation (so also the message buffer implementation, as message buffers * are built on top of stream buffers) assumes there is only one task or * interrupt that will write to the buffer (the writer), and only one task or * interrupt that will read from the buffer (the reader). It is safe for the * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers * then the application writer must place each call to a writing API function * (such as xMessageBufferSend()) inside a critical section and set the send * block time to 0. Likewise, if there are to be multiple different readers * then the application writer must place each call to a reading API function * (such as xMessageBufferRead()) inside a critical section and set the receive * block time to 0. * * Use xMessageBufferReceive() to read from a message buffer from a task. Use * xMessageBufferReceiveFromISR() to read from a message buffer from an * interrupt service routine (ISR). * * @param xMessageBuffer The handle of the message buffer from which a message * is being received. * * @param pvRxData A pointer to the buffer into which the received message is * to be copied. * * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData * parameter. This sets the maximum length of the message that can be received. * If xBufferLengthBytes is too small to hold the next message then the message * will be left in the message buffer and 0 will be returned. * * @param xTicksToWait The maximum amount of time the task should remain in the * Blocked state to wait for a message, should the message buffer be empty. * xMessageBufferReceive() will return immediately if xTicksToWait is zero and * the message buffer is empty. The block time is specified in tick periods, so * the absolute time it represents is dependent on the tick frequency. The * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will * cause the task to wait indefinitely (without timing out), provided * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any * CPU time when they are in the Blocked state. * * @return The length, in bytes, of the message read from the message buffer, if * any. If xMessageBufferReceive() times out before a message became available * then zero is returned. If the length of the message is greater than * xBufferLengthBytes then the message will be left in the message buffer and * zero is returned. * * Example use:
void vAFunction( MessageBuffer_t xMessageBuffer )
{
uint8_t ucRxData[ 20 ];
size_t xReceivedBytes;
const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );

    // Receive the next message from the message buffer.  Wait in the Blocked
    // state (so not using any CPU processing time) for a maximum of 100ms for
    // a message to become available.
    xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
                                            ( void * ) ucRxData,
                                            sizeof( ucRxData ),
                                            xBlockTime );

    if( xReceivedBytes > 0 )
    {
        // A ucRxData contains a message that is xReceivedBytes long.  Process
        // the message here....
    }
}
* \defgroup xMessageBufferReceive xMessageBufferReceive * \ingroup MessageBufferManagement */ #define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) xStreamBufferReceive( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) /** * message_buffer.h *
size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
                                     void *pvRxData,
                                     size_t xBufferLengthBytes,
                                     BaseType_t *pxHigherPriorityTaskWoken );
* * An interrupt safe version of the API function that receives a discrete * message from a message buffer. Messages can be of variable length and are * copied out of the buffer. * * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer * implementation (so also the message buffer implementation, as message buffers * are built on top of stream buffers) assumes there is only one task or * interrupt that will write to the buffer (the writer), and only one task or * interrupt that will read from the buffer (the reader). It is safe for the * writer and reader to be different tasks or interrupts, but, unlike other * FreeRTOS objects, it is not safe to have multiple different writers or * multiple different readers. If there are to be multiple different writers * then the application writer must place each call to a writing API function * (such as xMessageBufferSend()) inside a critical section and set the send * block time to 0. Likewise, if there are to be multiple different readers * then the application writer must place each call to a reading API function * (such as xMessageBufferRead()) inside a critical section and set the receive * block time to 0. * * Use xMessageBufferReceive() to read from a message buffer from a task. Use * xMessageBufferReceiveFromISR() to read from a message buffer from an * interrupt service routine (ISR). * * @param xMessageBuffer The handle of the message buffer from which a message * is being received. * * @param pvRxData A pointer to the buffer into which the received message is * to be copied. * * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData * parameter. This sets the maximum length of the message that can be received. * If xBufferLengthBytes is too small to hold the next message then the message * will be left in the message buffer and 0 will be returned. * * @param pxHigherPriorityTaskWoken It is possible that a message buffer will * have a task blocked on it waiting for space to become available. Calling * xMessageBufferReceiveFromISR() can make space available, and so cause a task * that is waiting for space to leave the Blocked state. If calling * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and * the unblocked task has a priority higher than the currently executing task * (the task that was interrupted), then, internally, * xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. * If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a * context switch should be performed before the interrupt is exited. That will * ensure the interrupt returns directly to the highest priority Ready state * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is * passed into the function. See the code example below for an example. * * @return The length, in bytes, of the message read from the message buffer, if * any. * * Example use:
// A message buffer that has already been created.
MessageBuffer_t xMessageBuffer;

void vAnInterruptServiceRoutine( void )
{
uint8_t ucRxData[ 20 ];
size_t xReceivedBytes;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;  // Initialised to pdFALSE.

    // Receive the next message from the message buffer.
    xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
                                                  ( void * ) ucRxData,
                                                  sizeof( ucRxData ),
                                                  &xHigherPriorityTaskWoken );

    if( xReceivedBytes > 0 )
    {
        // A ucRxData contains a message that is xReceivedBytes long.  Process
        // the message here....
    }

    // If xHigherPriorityTaskWoken was set to pdTRUE inside
    // xMessageBufferReceiveFromISR() then a task that has a priority above the
    // priority of the currently executing task was unblocked and a context
    // switch should be performed to ensure the ISR returns to the unblocked
    // task.  In most FreeRTOS ports this is done by simply passing
    // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
    // variables value, and perform the context switch if necessary.  Check the
    // documentation for the port in use for port specific instructions.
    taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
* \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR * \ingroup MessageBufferManagement */ #define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferReceiveFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) /** * message_buffer.h *
void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );
* * Deletes a message buffer that was previously created using a call to * xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message * buffer was created using dynamic memory (that is, by xMessageBufferCreate()), * then the allocated memory is freed. * * A message buffer handle must not be used after the message buffer has been * deleted. * * @param xMessageBuffer The handle of the message buffer to be deleted. * */ #define vMessageBufferDelete( xMessageBuffer ) vStreamBufferDelete( ( StreamBufferHandle_t ) xMessageBuffer ) /** * message_buffer.h
BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ) );
* * Tests to see if a message buffer is full. A message buffer is full if it * cannot accept any more messages, of any size, until space is made available * by a message being removed from the message buffer. * * @param xMessageBuffer The handle of the message buffer being queried. * * @return If the message buffer referenced by xMessageBuffer is full then * pdTRUE is returned. Otherwise pdFALSE is returned. */ #define xMessageBufferIsFull( xMessageBuffer ) xStreamBufferIsFull( ( StreamBufferHandle_t ) xMessageBuffer ) /** * message_buffer.h
BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ) );
* * Tests to see if a message buffer is empty (does not contain any messages). * * @param xMessageBuffer The handle of the message buffer being queried. * * @return If the message buffer referenced by xMessageBuffer is empty then * pdTRUE is returned. Otherwise pdFALSE is returned. * */ #define xMessageBufferIsEmpty( xMessageBuffer ) xStreamBufferIsEmpty( ( StreamBufferHandle_t ) xMessageBuffer ) /** * message_buffer.h
BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );
* * Resets a message buffer to its initial empty state, discarding any message it * contained. * * A message buffer can only be reset if there are no tasks blocked on it. * * @param xMessageBuffer The handle of the message buffer being reset. * * @return If the message buffer was reset then pdPASS is returned. If the * message buffer could not be reset because either there was a task blocked on * the message queue to wait for space to become available, or to wait for a * a message to be available, then pdFAIL is returned. * * \defgroup xMessageBufferReset xMessageBufferReset * \ingroup MessageBufferManagement */ #define xMessageBufferReset( xMessageBuffer ) xStreamBufferReset( ( StreamBufferHandle_t ) xMessageBuffer ) /** * message_buffer.h
size_t xMessageBufferSpaceAvailable( MessageBufferHandle_t xMessageBuffer ) );
* Returns the number of bytes of free space in the message buffer. * * @param xMessageBuffer The handle of the message buffer being queried. * * @return The number of bytes that can be written to the message buffer before * the message buffer would be full. When a message is written to the message * buffer an additional sizeof( size_t ) bytes are also written to store the * message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size * of the largest message that can be written to the message buffer is 6 bytes. * * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable * \ingroup MessageBufferManagement */ #define xMessageBufferSpaceAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer ) /** * message_buffer.h
 size_t xMessageBufferNextLengthBytes( MessageBufferHandle_t xMessageBuffer ) );
 
* Returns the length (in bytes) of the next message in a message buffer. * Useful if xMessageBufferReceive() returned 0 because the size of the buffer * passed into xMessageBufferReceive() was too small to hold the next message. * * @param xMessageBuffer The handle of the message buffer being queried. * * @return The length (in bytes) of the next message in the message buffer, or 0 * if the message buffer is empty. * * \defgroup xMessageBufferNextLengthBytes xMessageBufferNextLengthBytes * \ingroup MessageBufferManagement */ #define xMessageBufferNextLengthBytes( xMessageBuffer ) xStreamBufferNextMessageLengthBytes( ( StreamBufferHandle_t ) xMessageBuffer ) PRIVILEGED_FUNCTION; /** * message_buffer.h *
BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
* * For advanced users only. * * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when * data is sent to a message buffer or stream buffer. If there was a task that * was blocked on the message or stream buffer waiting for data to arrive then * the sbSEND_COMPLETED() macro sends a notification to the task to remove it * from the Blocked state. xMessageBufferSendCompletedFromISR() does the same * thing. It is provided to enable application writers to implement their own * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME. * * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for * additional information. * * @param xStreamBuffer The handle of the stream buffer to which data was * written. * * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be * initialised to pdFALSE before it is passed into * xMessageBufferSendCompletedFromISR(). If calling * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state, * and the task has a priority above the priority of the currently running task, * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a * context switch should be performed before exiting the ISR. * * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR * \ingroup StreamBufferManagement */ #define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferSendCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken ) /** * message_buffer.h *
BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
* * For advanced users only. * * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when * data is read out of a message buffer or stream buffer. If there was a task * that was blocked on the message or stream buffer waiting for data to arrive * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to * remove it from the Blocked state. xMessageBufferReceiveCompletedFromISR() * does the same thing. It is provided to enable application writers to * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT * ANY OTHER TIME. * * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for * additional information. * * @param xStreamBuffer The handle of the stream buffer from which data was * read. * * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be * initialised to pdFALSE before it is passed into * xMessageBufferReceiveCompletedFromISR(). If calling * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state, * and the task has a priority above the priority of the currently running task, * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a * context switch should be performed before exiting the ISR. * * @return If a task was removed from the Blocked state then pdTRUE is returned. * Otherwise pdFALSE is returned. * * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR * \ingroup StreamBufferManagement */ #define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferReceiveCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken ) #if defined( __cplusplus ) } /* extern "C" */ #endif #endif /* !defined( FREERTOS_MESSAGE_BUFFER_H ) */