Espressif ESP32-S2 Programming Manual page 959

Chapter 2. API Reference
• 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.
xMessageBufferCreateStatic(xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMes-
Creates a new message buffer using statically allocated memory. See xMessageBufferCreate() for a version
that uses dynamically allocated memory.
Example use:
// Used to dimension the array used to hold the
// will actually be one less than this, so
#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
StaticMessageBuffer_t xMessageBufferStruct;
void MyFunction( void )
{
MessageBufferHandle_t xMessageBuffer;
xMessageBuffer
// As neither the pucMessageBufferStorageArea
// parameters were NULL, xMessageBuffer will
// reference the created message buffer
// Other code that uses the message buffer can go
}
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.
Parameters
• xBufferSizeBytes: The size, in bytes, of the buffer pointed to by the pucMessageBufferStor-
ageArea 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).
• pucMessageBufferStorageArea: Must point to a uint8_t array that is at least xBufferSize-
Bytes + 1 big. This is the array to which messages are copied when they are written to the message
buffer.
• pxStaticMessageBuffer: Must point to a variable of type StaticMessageBuffer_t, which will
be used to hold the message buffer's data structure.
xMessageBufferSend(xMessageBuffer, pvTxData, xDataLengthBytes, 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
Espressif Systems
sageBuffer)
= xMessageBufferCreateStatic( sizeof( ucBufferStorage ),
Submit Document Feedback
messages.
999.
structure.
ucBufferStorage,
&xMessageBufferStruct );
or pxStaticMessageBuffer
not be NULL,
in other message buffer API
here.
948
The available space
and can be used to
calls.
Release v4.4