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