2 * FreeRTOS Kernel V10.3.0
\r
3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://www.FreeRTOS.org
\r
23 * http://aws.amazon.com/freertos
\r
25 * 1 tab == 4 spaces!
\r
30 * Message buffers build functionality on top of FreeRTOS stream buffers.
\r
31 * Whereas stream buffers are used to send a continuous stream of data from one
\r
32 * task or interrupt to another, message buffers are used to send variable
\r
33 * length discrete messages from one task or interrupt to another. Their
\r
34 * implementation is light weight, making them particularly suited for interrupt
\r
35 * to task and core to core communication scenarios.
\r
37 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
38 * implementation (so also the message buffer implementation, as message buffers
\r
39 * are built on top of stream buffers) assumes there is only one task or
\r
40 * interrupt that will write to the buffer (the writer), and only one task or
\r
41 * interrupt that will read from the buffer (the reader). It is safe for the
\r
42 * writer and reader to be different tasks or interrupts, but, unlike other
\r
43 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
44 * multiple different readers. If there are to be multiple different writers
\r
45 * then the application writer must place each call to a writing API function
\r
46 * (such as xMessageBufferSend()) inside a critical section and set the send
\r
47 * block time to 0. Likewise, if there are to be multiple different readers
\r
48 * then the application writer must place each call to a reading API function
\r
49 * (such as xMessageBufferRead()) inside a critical section and set the receive
\r
52 * Message buffers hold variable length messages. To enable that, when a
\r
53 * message is written to the message buffer an additional sizeof( size_t ) bytes
\r
54 * are also written to store the message's length (that happens internally, with
\r
55 * the API function). sizeof( size_t ) is typically 4 bytes on a 32-bit
\r
56 * architecture, so writing a 10 byte message to a message buffer on a 32-bit
\r
57 * architecture will actually reduce the available space in the message buffer
\r
58 * by 14 bytes (10 byte are used by the message, and 4 bytes to hold the length
\r
62 #ifndef FREERTOS_MESSAGE_BUFFER_H
\r
63 #define FREERTOS_MESSAGE_BUFFER_H
\r
65 #ifndef INC_FREERTOS_H
\r
66 #error "include FreeRTOS.h must appear in source files before include message_buffer.h"
\r
69 /* Message buffers are built onto of stream buffers. */
\r
70 #include "stream_buffer.h"
\r
72 #if defined( __cplusplus )
\r
77 * Type by which message buffers are referenced. For example, a call to
\r
78 * xMessageBufferCreate() returns an MessageBufferHandle_t variable that can
\r
79 * then be used as a parameter to xMessageBufferSend(), xMessageBufferReceive(),
\r
82 typedef void * MessageBufferHandle_t;
\r
84 /*-----------------------------------------------------------*/
\r
90 MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );
\r
93 * Creates a new message buffer using dynamically allocated memory. See
\r
94 * xMessageBufferCreateStatic() for a version that uses statically allocated
\r
95 * memory (memory that is allocated at compile time).
\r
97 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
\r
98 * FreeRTOSConfig.h for xMessageBufferCreate() to be available.
\r
100 * @param xBufferSizeBytes The total number of bytes (not messages) the message
\r
101 * buffer will be able to hold at any one time. When a message is written to
\r
102 * the message buffer an additional sizeof( size_t ) bytes are also written to
\r
103 * store the message's length. sizeof( size_t ) is typically 4 bytes on a
\r
104 * 32-bit architecture, so on most 32-bit architectures a 10 byte message will
\r
105 * take up 14 bytes of message buffer space.
\r
107 * @return If NULL is returned, then the message buffer cannot be created
\r
108 * because there is insufficient heap memory available for FreeRTOS to allocate
\r
109 * the message buffer data structures and storage area. A non-NULL value being
\r
110 * returned indicates that the message buffer has been created successfully -
\r
111 * the returned value should be stored as the handle to the created message
\r
117 void vAFunction( void )
\r
119 MessageBufferHandle_t xMessageBuffer;
\r
120 const size_t xMessageBufferSizeBytes = 100;
\r
122 // Create a message buffer that can hold 100 bytes. The memory used to hold
\r
123 // both the message buffer structure and the messages themselves is allocated
\r
124 // dynamically. Each message added to the buffer consumes an additional 4
\r
125 // bytes which are used to hold the lengh of the message.
\r
126 xMessageBuffer = xMessageBufferCreate( xMessageBufferSizeBytes );
\r
128 if( xMessageBuffer == NULL )
\r
130 // There was not enough heap memory space available to create the
\r
135 // The message buffer was created successfully and can now be used.
\r
139 * \defgroup xMessageBufferCreate xMessageBufferCreate
\r
140 * \ingroup MessageBufferManagement
\r
142 #define xMessageBufferCreate( xBufferSizeBytes ) ( MessageBufferHandle_t ) xStreamBufferGenericCreate( xBufferSizeBytes, ( size_t ) 0, pdTRUE )
\r
148 MessageBufferHandle_t xMessageBufferCreateStatic( size_t xBufferSizeBytes,
\r
149 uint8_t *pucMessageBufferStorageArea,
\r
150 StaticMessageBuffer_t *pxStaticMessageBuffer );
\r
152 * Creates a new message buffer using statically allocated memory. See
\r
153 * xMessageBufferCreate() for a version that uses dynamically allocated memory.
\r
155 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
\r
156 * pucMessageBufferStorageArea parameter. When a message is written to the
\r
157 * message buffer an additional sizeof( size_t ) bytes are also written to store
\r
158 * the message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit
\r
159 * architecture, so on most 32-bit architecture a 10 byte message will take up
\r
160 * 14 bytes of message buffer space. The maximum number of bytes that can be
\r
161 * stored in the message buffer is actually (xBufferSizeBytes - 1).
\r
163 * @param pucMessageBufferStorageArea Must point to a uint8_t array that is at
\r
164 * least xBufferSizeBytes + 1 big. This is the array to which messages are
\r
165 * copied when they are written to the message buffer.
\r
167 * @param pxStaticMessageBuffer Must point to a variable of type
\r
168 * StaticMessageBuffer_t, which will be used to hold the message buffer's data
\r
171 * @return If the message buffer is created successfully then a handle to the
\r
172 * created message buffer is returned. If either pucMessageBufferStorageArea or
\r
173 * pxStaticmessageBuffer are NULL then NULL is returned.
\r
178 // Used to dimension the array used to hold the messages. The available space
\r
179 // will actually be one less than this, so 999.
\r
180 #define STORAGE_SIZE_BYTES 1000
\r
182 // Defines the memory that will actually hold the messages within the message
\r
184 static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
\r
186 // The variable used to hold the message buffer structure.
\r
187 StaticMessageBuffer_t xMessageBufferStruct;
\r
189 void MyFunction( void )
\r
191 MessageBufferHandle_t xMessageBuffer;
\r
193 xMessageBuffer = xMessageBufferCreateStatic( sizeof( ucBufferStorage ),
\r
195 &xMessageBufferStruct );
\r
197 // As neither the pucMessageBufferStorageArea or pxStaticMessageBuffer
\r
198 // parameters were NULL, xMessageBuffer will not be NULL, and can be used to
\r
199 // reference the created message buffer in other message buffer API calls.
\r
201 // Other code that uses the message buffer can go here.
\r
205 * \defgroup xMessageBufferCreateStatic xMessageBufferCreateStatic
\r
206 * \ingroup MessageBufferManagement
\r
208 #define xMessageBufferCreateStatic( xBufferSizeBytes, pucMessageBufferStorageArea, pxStaticMessageBuffer ) ( MessageBufferHandle_t ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, 0, pdTRUE, pucMessageBufferStorageArea, pxStaticMessageBuffer )
\r
214 size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
\r
215 const void *pvTxData,
\r
216 size_t xDataLengthBytes,
\r
217 TickType_t xTicksToWait );
\r
220 * Sends a discrete message to the message buffer. The message can be any
\r
221 * length that fits within the buffer's free space, and is copied into the
\r
224 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
225 * implementation (so also the message buffer implementation, as message buffers
\r
226 * are built on top of stream buffers) assumes there is only one task or
\r
227 * interrupt that will write to the buffer (the writer), and only one task or
\r
228 * interrupt that will read from the buffer (the reader). It is safe for the
\r
229 * writer and reader to be different tasks or interrupts, but, unlike other
\r
230 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
231 * multiple different readers. If there are to be multiple different writers
\r
232 * then the application writer must place each call to a writing API function
\r
233 * (such as xMessageBufferSend()) inside a critical section and set the send
\r
234 * block time to 0. Likewise, if there are to be multiple different readers
\r
235 * then the application writer must place each call to a reading API function
\r
236 * (such as xMessageBufferRead()) inside a critical section and set the receive
\r
239 * Use xMessageBufferSend() to write to a message buffer from a task. Use
\r
240 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
\r
241 * service routine (ISR).
\r
243 * @param xMessageBuffer The handle of the message buffer to which a message is
\r
246 * @param pvTxData A pointer to the message that is to be copied into the
\r
249 * @param xDataLengthBytes The length of the message. That is, the number of
\r
250 * bytes to copy from pvTxData into the message buffer. When a message is
\r
251 * written to the message buffer an additional sizeof( size_t ) bytes are also
\r
252 * written to store the message's length. sizeof( size_t ) is typically 4 bytes
\r
253 * on a 32-bit architecture, so on most 32-bit architecture setting
\r
254 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
\r
255 * bytes (20 bytes of message data and 4 bytes to hold the message length).
\r
257 * @param xTicksToWait The maximum amount of time the calling task should remain
\r
258 * in the Blocked state to wait for enough space to become available in the
\r
259 * message buffer, should the message buffer have insufficient space when
\r
260 * xMessageBufferSend() is called. The calling task will never block if
\r
261 * xTicksToWait is zero. The block time is specified in tick periods, so the
\r
262 * absolute time it represents is dependent on the tick frequency. The macro
\r
263 * pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into
\r
264 * a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will cause
\r
265 * the task to wait indefinitely (without timing out), provided
\r
266 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any
\r
267 * CPU time when they are in the Blocked state.
\r
269 * @return The number of bytes written to the message buffer. If the call to
\r
270 * xMessageBufferSend() times out before there was enough space to write the
\r
271 * message into the message buffer then zero is returned. If the call did not
\r
272 * time out then xDataLengthBytes is returned.
\r
276 void vAFunction( MessageBufferHandle_t xMessageBuffer )
\r
279 uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
\r
280 char *pcStringToSend = "String to send";
\r
281 const TickType_t x100ms = pdMS_TO_TICKS( 100 );
\r
283 // Send an array to the message buffer, blocking for a maximum of 100ms to
\r
284 // wait for enough space to be available in the message buffer.
\r
285 xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
\r
287 if( xBytesSent != sizeof( ucArrayToSend ) )
\r
289 // The call to xMessageBufferSend() times out before there was enough
\r
290 // space in the buffer for the data to be written.
\r
293 // Send the string to the message buffer. Return immediately if there is
\r
294 // not enough space in the buffer.
\r
295 xBytesSent = xMessageBufferSend( xMessageBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
\r
297 if( xBytesSent != strlen( pcStringToSend ) )
\r
299 // The string could not be added to the message buffer because there was
\r
300 // not enough free space in the buffer.
\r
304 * \defgroup xMessageBufferSend xMessageBufferSend
\r
305 * \ingroup MessageBufferManagement
\r
307 #define xMessageBufferSend( xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait ) xStreamBufferSend( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, xTicksToWait )
\r
313 size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
\r
314 const void *pvTxData,
\r
315 size_t xDataLengthBytes,
\r
316 BaseType_t *pxHigherPriorityTaskWoken );
\r
319 * Interrupt safe version of the API function that sends a discrete message to
\r
320 * the message buffer. The message can be any length that fits within the
\r
321 * buffer's free space, and is copied into the buffer.
\r
323 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
324 * implementation (so also the message buffer implementation, as message buffers
\r
325 * are built on top of stream buffers) assumes there is only one task or
\r
326 * interrupt that will write to the buffer (the writer), and only one task or
\r
327 * interrupt that will read from the buffer (the reader). It is safe for the
\r
328 * writer and reader to be different tasks or interrupts, but, unlike other
\r
329 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
330 * multiple different readers. If there are to be multiple different writers
\r
331 * then the application writer must place each call to a writing API function
\r
332 * (such as xMessageBufferSend()) inside a critical section and set the send
\r
333 * block time to 0. Likewise, if there are to be multiple different readers
\r
334 * then the application writer must place each call to a reading API function
\r
335 * (such as xMessageBufferRead()) inside a critical section and set the receive
\r
338 * Use xMessageBufferSend() to write to a message buffer from a task. Use
\r
339 * xMessageBufferSendFromISR() to write to a message buffer from an interrupt
\r
340 * service routine (ISR).
\r
342 * @param xMessageBuffer The handle of the message buffer to which a message is
\r
345 * @param pvTxData A pointer to the message that is to be copied into the
\r
348 * @param xDataLengthBytes The length of the message. That is, the number of
\r
349 * bytes to copy from pvTxData into the message buffer. When a message is
\r
350 * written to the message buffer an additional sizeof( size_t ) bytes are also
\r
351 * written to store the message's length. sizeof( size_t ) is typically 4 bytes
\r
352 * on a 32-bit architecture, so on most 32-bit architecture setting
\r
353 * xDataLengthBytes to 20 will reduce the free space in the message buffer by 24
\r
354 * bytes (20 bytes of message data and 4 bytes to hold the message length).
\r
356 * @param pxHigherPriorityTaskWoken It is possible that a message buffer will
\r
357 * have a task blocked on it waiting for data. Calling
\r
358 * xMessageBufferSendFromISR() can make data available, and so cause a task that
\r
359 * was waiting for data to leave the Blocked state. If calling
\r
360 * xMessageBufferSendFromISR() causes a task to leave the Blocked state, and the
\r
361 * unblocked task has a priority higher than the currently executing task (the
\r
362 * task that was interrupted), then, internally, xMessageBufferSendFromISR()
\r
363 * will set *pxHigherPriorityTaskWoken to pdTRUE. If
\r
364 * xMessageBufferSendFromISR() sets this value to pdTRUE, then normally a
\r
365 * context switch should be performed before the interrupt is exited. This will
\r
366 * ensure that the interrupt returns directly to the highest priority Ready
\r
367 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
\r
368 * is passed into the function. See the code example below for an example.
\r
370 * @return The number of bytes actually written to the message buffer. If the
\r
371 * message buffer didn't have enough free space for the message to be stored
\r
372 * then 0 is returned, otherwise xDataLengthBytes is returned.
\r
376 // A message buffer that has already been created.
\r
377 MessageBufferHandle_t xMessageBuffer;
\r
379 void vAnInterruptServiceRoutine( void )
\r
382 char *pcStringToSend = "String to send";
\r
383 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
385 // Attempt to send the string to the message buffer.
\r
386 xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
\r
387 ( void * ) pcStringToSend,
\r
388 strlen( pcStringToSend ),
\r
389 &xHigherPriorityTaskWoken );
\r
391 if( xBytesSent != strlen( pcStringToSend ) )
\r
393 // The string could not be added to the message buffer because there was
\r
394 // not enough free space in the buffer.
\r
397 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
398 // xMessageBufferSendFromISR() then a task that has a priority above the
\r
399 // priority of the currently executing task was unblocked and a context
\r
400 // switch should be performed to ensure the ISR returns to the unblocked
\r
401 // task. In most FreeRTOS ports this is done by simply passing
\r
402 // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
\r
403 // variables value, and perform the context switch if necessary. Check the
\r
404 // documentation for the port in use for port specific instructions.
\r
405 portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
408 * \defgroup xMessageBufferSendFromISR xMessageBufferSendFromISR
\r
409 * \ingroup MessageBufferManagement
\r
411 #define xMessageBufferSendFromISR( xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferSendFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken )
\r
417 size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
\r
419 size_t xBufferLengthBytes,
\r
420 TickType_t xTicksToWait );
\r
423 * Receives a discrete message from a message buffer. Messages can be of
\r
424 * variable length and are copied out of the buffer.
\r
426 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
427 * implementation (so also the message buffer implementation, as message buffers
\r
428 * are built on top of stream buffers) assumes there is only one task or
\r
429 * interrupt that will write to the buffer (the writer), and only one task or
\r
430 * interrupt that will read from the buffer (the reader). It is safe for the
\r
431 * writer and reader to be different tasks or interrupts, but, unlike other
\r
432 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
433 * multiple different readers. If there are to be multiple different writers
\r
434 * then the application writer must place each call to a writing API function
\r
435 * (such as xMessageBufferSend()) inside a critical section and set the send
\r
436 * block time to 0. Likewise, if there are to be multiple different readers
\r
437 * then the application writer must place each call to a reading API function
\r
438 * (such as xMessageBufferRead()) inside a critical section and set the receive
\r
441 * Use xMessageBufferReceive() to read from a message buffer from a task. Use
\r
442 * xMessageBufferReceiveFromISR() to read from a message buffer from an
\r
443 * interrupt service routine (ISR).
\r
445 * @param xMessageBuffer The handle of the message buffer from which a message
\r
446 * is being received.
\r
448 * @param pvRxData A pointer to the buffer into which the received message is
\r
451 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
\r
452 * parameter. This sets the maximum length of the message that can be received.
\r
453 * If xBufferLengthBytes is too small to hold the next message then the message
\r
454 * will be left in the message buffer and 0 will be returned.
\r
456 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
457 * Blocked state to wait for a message, should the message buffer be empty.
\r
458 * xMessageBufferReceive() will return immediately if xTicksToWait is zero and
\r
459 * the message buffer is empty. The block time is specified in tick periods, so
\r
460 * the absolute time it represents is dependent on the tick frequency. The
\r
461 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
\r
462 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
\r
463 * cause the task to wait indefinitely (without timing out), provided
\r
464 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. Tasks do not use any
\r
465 * CPU time when they are in the Blocked state.
\r
467 * @return The length, in bytes, of the message read from the message buffer, if
\r
468 * any. If xMessageBufferReceive() times out before a message became available
\r
469 * then zero is returned. If the length of the message is greater than
\r
470 * xBufferLengthBytes then the message will be left in the message buffer and
\r
471 * zero is returned.
\r
475 void vAFunction( MessageBuffer_t xMessageBuffer )
\r
477 uint8_t ucRxData[ 20 ];
\r
478 size_t xReceivedBytes;
\r
479 const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
\r
481 // Receive the next message from the message buffer. Wait in the Blocked
\r
482 // state (so not using any CPU processing time) for a maximum of 100ms for
\r
483 // a message to become available.
\r
484 xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
\r
485 ( void * ) ucRxData,
\r
486 sizeof( ucRxData ),
\r
489 if( xReceivedBytes > 0 )
\r
491 // A ucRxData contains a message that is xReceivedBytes long. Process
\r
492 // the message here....
\r
496 * \defgroup xMessageBufferReceive xMessageBufferReceive
\r
497 * \ingroup MessageBufferManagement
\r
499 #define xMessageBufferReceive( xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait ) xStreamBufferReceive( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, xTicksToWait )
\r
506 size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
\r
508 size_t xBufferLengthBytes,
\r
509 BaseType_t *pxHigherPriorityTaskWoken );
\r
512 * An interrupt safe version of the API function that receives a discrete
\r
513 * message from a message buffer. Messages can be of variable length and are
\r
514 * copied out of the buffer.
\r
516 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
517 * implementation (so also the message buffer implementation, as message buffers
\r
518 * are built on top of stream buffers) assumes there is only one task or
\r
519 * interrupt that will write to the buffer (the writer), and only one task or
\r
520 * interrupt that will read from the buffer (the reader). It is safe for the
\r
521 * writer and reader to be different tasks or interrupts, but, unlike other
\r
522 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
523 * multiple different readers. If there are to be multiple different writers
\r
524 * then the application writer must place each call to a writing API function
\r
525 * (such as xMessageBufferSend()) inside a critical section and set the send
\r
526 * block time to 0. Likewise, if there are to be multiple different readers
\r
527 * then the application writer must place each call to a reading API function
\r
528 * (such as xMessageBufferRead()) inside a critical section and set the receive
\r
531 * Use xMessageBufferReceive() to read from a message buffer from a task. Use
\r
532 * xMessageBufferReceiveFromISR() to read from a message buffer from an
\r
533 * interrupt service routine (ISR).
\r
535 * @param xMessageBuffer The handle of the message buffer from which a message
\r
536 * is being received.
\r
538 * @param pvRxData A pointer to the buffer into which the received message is
\r
541 * @param xBufferLengthBytes The length of the buffer pointed to by the pvRxData
\r
542 * parameter. This sets the maximum length of the message that can be received.
\r
543 * If xBufferLengthBytes is too small to hold the next message then the message
\r
544 * will be left in the message buffer and 0 will be returned.
\r
546 * @param pxHigherPriorityTaskWoken It is possible that a message buffer will
\r
547 * have a task blocked on it waiting for space to become available. Calling
\r
548 * xMessageBufferReceiveFromISR() can make space available, and so cause a task
\r
549 * that is waiting for space to leave the Blocked state. If calling
\r
550 * xMessageBufferReceiveFromISR() causes a task to leave the Blocked state, and
\r
551 * the unblocked task has a priority higher than the currently executing task
\r
552 * (the task that was interrupted), then, internally,
\r
553 * xMessageBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
\r
554 * If xMessageBufferReceiveFromISR() sets this value to pdTRUE, then normally a
\r
555 * context switch should be performed before the interrupt is exited. That will
\r
556 * ensure the interrupt returns directly to the highest priority Ready state
\r
557 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
\r
558 * passed into the function. See the code example below for an example.
\r
560 * @return The length, in bytes, of the message read from the message buffer, if
\r
565 // A message buffer that has already been created.
\r
566 MessageBuffer_t xMessageBuffer;
\r
568 void vAnInterruptServiceRoutine( void )
\r
570 uint8_t ucRxData[ 20 ];
\r
571 size_t xReceivedBytes;
\r
572 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
574 // Receive the next message from the message buffer.
\r
575 xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
\r
576 ( void * ) ucRxData,
\r
577 sizeof( ucRxData ),
\r
578 &xHigherPriorityTaskWoken );
\r
580 if( xReceivedBytes > 0 )
\r
582 // A ucRxData contains a message that is xReceivedBytes long. Process
\r
583 // the message here....
\r
586 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
587 // xMessageBufferReceiveFromISR() then a task that has a priority above the
\r
588 // priority of the currently executing task was unblocked and a context
\r
589 // switch should be performed to ensure the ISR returns to the unblocked
\r
590 // task. In most FreeRTOS ports this is done by simply passing
\r
591 // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the
\r
592 // variables value, and perform the context switch if necessary. Check the
\r
593 // documentation for the port in use for port specific instructions.
\r
594 portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
597 * \defgroup xMessageBufferReceiveFromISR xMessageBufferReceiveFromISR
\r
598 * \ingroup MessageBufferManagement
\r
600 #define xMessageBufferReceiveFromISR( xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken ) xStreamBufferReceiveFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken )
\r
606 void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );
\r
609 * Deletes a message buffer that was previously created using a call to
\r
610 * xMessageBufferCreate() or xMessageBufferCreateStatic(). If the message
\r
611 * buffer was created using dynamic memory (that is, by xMessageBufferCreate()),
\r
612 * then the allocated memory is freed.
\r
614 * A message buffer handle must not be used after the message buffer has been
\r
617 * @param xMessageBuffer The handle of the message buffer to be deleted.
\r
620 #define vMessageBufferDelete( xMessageBuffer ) vStreamBufferDelete( ( StreamBufferHandle_t ) xMessageBuffer )
\r
625 BaseType_t xMessageBufferIsFull( MessageBufferHandle_t xMessageBuffer ) );
\r
628 * Tests to see if a message buffer is full. A message buffer is full if it
\r
629 * cannot accept any more messages, of any size, until space is made available
\r
630 * by a message being removed from the message buffer.
\r
632 * @param xMessageBuffer The handle of the message buffer being queried.
\r
634 * @return If the message buffer referenced by xMessageBuffer is full then
\r
635 * pdTRUE is returned. Otherwise pdFALSE is returned.
\r
637 #define xMessageBufferIsFull( xMessageBuffer ) xStreamBufferIsFull( ( StreamBufferHandle_t ) xMessageBuffer )
\r
642 BaseType_t xMessageBufferIsEmpty( MessageBufferHandle_t xMessageBuffer ) );
\r
645 * Tests to see if a message buffer is empty (does not contain any messages).
\r
647 * @param xMessageBuffer The handle of the message buffer being queried.
\r
649 * @return If the message buffer referenced by xMessageBuffer is empty then
\r
650 * pdTRUE is returned. Otherwise pdFALSE is returned.
\r
653 #define xMessageBufferIsEmpty( xMessageBuffer ) xStreamBufferIsEmpty( ( StreamBufferHandle_t ) xMessageBuffer )
\r
658 BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );
\r
661 * Resets a message buffer to its initial empty state, discarding any message it
\r
664 * A message buffer can only be reset if there are no tasks blocked on it.
\r
666 * @param xMessageBuffer The handle of the message buffer being reset.
\r
668 * @return If the message buffer was reset then pdPASS is returned. If the
\r
669 * message buffer could not be reset because either there was a task blocked on
\r
670 * the message queue to wait for space to become available, or to wait for a
\r
671 * a message to be available, then pdFAIL is returned.
\r
673 * \defgroup xMessageBufferReset xMessageBufferReset
\r
674 * \ingroup MessageBufferManagement
\r
676 #define xMessageBufferReset( xMessageBuffer ) xStreamBufferReset( ( StreamBufferHandle_t ) xMessageBuffer )
\r
682 size_t xMessageBufferSpaceAvailable( MessageBufferHandle_t xMessageBuffer ) );
\r
684 * Returns the number of bytes of free space in the message buffer.
\r
686 * @param xMessageBuffer The handle of the message buffer being queried.
\r
688 * @return The number of bytes that can be written to the message buffer before
\r
689 * the message buffer would be full. When a message is written to the message
\r
690 * buffer an additional sizeof( size_t ) bytes are also written to store the
\r
691 * message's length. sizeof( size_t ) is typically 4 bytes on a 32-bit
\r
692 * architecture, so if xMessageBufferSpacesAvailable() returns 10, then the size
\r
693 * of the largest message that can be written to the message buffer is 6 bytes.
\r
695 * \defgroup xMessageBufferSpaceAvailable xMessageBufferSpaceAvailable
\r
696 * \ingroup MessageBufferManagement
\r
698 #define xMessageBufferSpaceAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer )
\r
699 #define xMessageBufferSpacesAvailable( xMessageBuffer ) xStreamBufferSpacesAvailable( ( StreamBufferHandle_t ) xMessageBuffer ) /* Corrects typo in original macro name. */
\r
704 size_t xMessageBufferNextLengthBytes( MessageBufferHandle_t xMessageBuffer ) );
\r
706 * Returns the length (in bytes) of the next message in a message buffer.
\r
707 * Useful if xMessageBufferReceive() returned 0 because the size of the buffer
\r
708 * passed into xMessageBufferReceive() was too small to hold the next message.
\r
710 * @param xMessageBuffer The handle of the message buffer being queried.
\r
712 * @return The length (in bytes) of the next message in the message buffer, or 0
\r
713 * if the message buffer is empty.
\r
715 * \defgroup xMessageBufferNextLengthBytes xMessageBufferNextLengthBytes
\r
716 * \ingroup MessageBufferManagement
\r
718 #define xMessageBufferNextLengthBytes( xMessageBuffer ) xStreamBufferNextMessageLengthBytes( ( StreamBufferHandle_t ) xMessageBuffer ) PRIVILEGED_FUNCTION;
\r
724 BaseType_t xMessageBufferSendCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
727 * For advanced users only.
\r
729 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
730 * data is sent to a message buffer or stream buffer. If there was a task that
\r
731 * was blocked on the message or stream buffer waiting for data to arrive then
\r
732 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
\r
733 * from the Blocked state. xMessageBufferSendCompletedFromISR() does the same
\r
734 * thing. It is provided to enable application writers to implement their own
\r
735 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
\r
737 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
738 * additional information.
\r
740 * @param xStreamBuffer The handle of the stream buffer to which data was
\r
743 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
744 * initialised to pdFALSE before it is passed into
\r
745 * xMessageBufferSendCompletedFromISR(). If calling
\r
746 * xMessageBufferSendCompletedFromISR() removes a task from the Blocked state,
\r
747 * and the task has a priority above the priority of the currently running task,
\r
748 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
749 * context switch should be performed before exiting the ISR.
\r
751 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
752 * Otherwise pdFALSE is returned.
\r
754 * \defgroup xMessageBufferSendCompletedFromISR xMessageBufferSendCompletedFromISR
\r
755 * \ingroup StreamBufferManagement
\r
757 #define xMessageBufferSendCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferSendCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )
\r
763 BaseType_t xMessageBufferReceiveCompletedFromISR( MessageBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
766 * For advanced users only.
\r
768 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
769 * data is read out of a message buffer or stream buffer. If there was a task
\r
770 * that was blocked on the message or stream buffer waiting for data to arrive
\r
771 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
\r
772 * remove it from the Blocked state. xMessageBufferReceiveCompletedFromISR()
\r
773 * does the same thing. It is provided to enable application writers to
\r
774 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
\r
777 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
778 * additional information.
\r
780 * @param xStreamBuffer The handle of the stream buffer from which data was
\r
783 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
784 * initialised to pdFALSE before it is passed into
\r
785 * xMessageBufferReceiveCompletedFromISR(). If calling
\r
786 * xMessageBufferReceiveCompletedFromISR() removes a task from the Blocked state,
\r
787 * and the task has a priority above the priority of the currently running task,
\r
788 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
789 * context switch should be performed before exiting the ISR.
\r
791 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
792 * Otherwise pdFALSE is returned.
\r
794 * \defgroup xMessageBufferReceiveCompletedFromISR xMessageBufferReceiveCompletedFromISR
\r
795 * \ingroup StreamBufferManagement
\r
797 #define xMessageBufferReceiveCompletedFromISR( xMessageBuffer, pxHigherPriorityTaskWoken ) xStreamBufferReceiveCompletedFromISR( ( StreamBufferHandle_t ) xMessageBuffer, pxHigherPriorityTaskWoken )
\r
799 #if defined( __cplusplus )
\r
803 #endif /* !defined( FREERTOS_MESSAGE_BUFFER_H ) */
\r