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