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 * Stream buffers are used to send a continuous stream of data from one task or 31 * interrupt to another. Their implementation is light weight, making them 32 * particularly suited for interrupt to task and core to core communication 33 * scenarios. 34 * 35 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer 36 * implementation (so also the message buffer implementation, as message buffers 37 * are built on top of stream buffers) assumes there is only one task or 38 * interrupt that will write to the buffer (the writer), and only one task or 39 * interrupt that will read from the buffer (the reader). It is safe for the 40 * writer and reader to be different tasks or interrupts, but, unlike other 41 * FreeRTOS objects, it is not safe to have multiple different writers or 42 * multiple different readers. If there are to be multiple different writers 43 * then the application writer must place each call to a writing API function 44 * (such as xStreamBufferSend()) inside a critical section and set the send 45 * block time to 0. Likewise, if there are to be multiple different readers 46 * then the application writer must place each call to a reading API function 47 * (such as xStreamBufferReceive()) inside a critical section section and set the 48 * receive block time to 0. 49 * 50 */ 51 52 #ifndef STREAM_BUFFER_H 53 #define STREAM_BUFFER_H 54 55 #ifndef INC_FREERTOS_H 56 #error "include FreeRTOS.h must appear in source files before include stream_buffer.h" 57 #endif 58 59 /* *INDENT-OFF* */ 60 #if defined( __cplusplus ) 61 extern "C" { 62 #endif 63 /* *INDENT-ON* */ 64 65 /** 66 * Type of stream buffer. For internal use only. 67 */ 68 #define sbTYPE_STREAM_BUFFER ( ( BaseType_t ) 0 ) 69 #define sbTYPE_MESSAGE_BUFFER ( ( BaseType_t ) 1 ) 70 #define sbTYPE_STREAM_BATCHING_BUFFER ( ( BaseType_t ) 2 ) 71 72 /** 73 * Type by which stream buffers are referenced. For example, a call to 74 * xStreamBufferCreate() returns an StreamBufferHandle_t variable that can 75 * then be used as a parameter to xStreamBufferSend(), xStreamBufferReceive(), 76 * etc. 77 */ 78 struct StreamBufferDef_t; 79 typedef struct StreamBufferDef_t * StreamBufferHandle_t; 80 81 /** 82 * Type used as a stream buffer's optional callback. 83 */ 84 typedef void (* StreamBufferCallbackFunction_t)( StreamBufferHandle_t xStreamBuffer, 85 BaseType_t xIsInsideISR, 86 BaseType_t * const pxHigherPriorityTaskWoken ); 87 88 /** 89 * stream_buffer.h 90 * 91 * @code{c} 92 * StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes ); 93 * @endcode 94 * 95 * Creates a new stream buffer using dynamically allocated memory. See 96 * xStreamBufferCreateStatic() for a version that uses statically allocated 97 * memory (memory that is allocated at compile time). 98 * 99 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in 100 * FreeRTOSConfig.h for xStreamBufferCreate() to be available. 101 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 102 * xStreamBufferCreate() to be available. 103 * 104 * @param xBufferSizeBytes The total number of bytes the stream buffer will be 105 * able to hold at any one time. 106 * 107 * @param xTriggerLevelBytes The number of bytes that must be in the stream 108 * buffer before a task that is blocked on the stream buffer to wait for data is 109 * moved out of the blocked state. For example, if a task is blocked on a read 110 * of an empty stream buffer that has a trigger level of 1 then the task will be 111 * unblocked when a single byte is written to the buffer or the task's block 112 * time expires. As another example, if a task is blocked on a read of an empty 113 * stream buffer that has a trigger level of 10 then the task will not be 114 * unblocked until the stream buffer contains at least 10 bytes or the task's 115 * block time expires. If a reading task's block time expires before the 116 * trigger level is reached then the task will still receive however many bytes 117 * are actually available. Setting a trigger level of 0 will result in a 118 * trigger level of 1 being used. It is not valid to specify a trigger level 119 * that is greater than the buffer size. 120 * 121 * @param pxSendCompletedCallback Callback invoked when number of bytes at least equal to 122 * trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default 123 * implementation provided by sbSEND_COMPLETED macro. To enable the callback, 124 * configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h. 125 * 126 * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes are read from a 127 * stream buffer. If the parameter is NULL, it will use the default 128 * implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback, 129 * configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h. 130 * 131 * @return If NULL is returned, then the stream buffer cannot be created 132 * because there is insufficient heap memory available for FreeRTOS to allocate 133 * the stream buffer data structures and storage area. A non-NULL value being 134 * returned indicates that the stream buffer has been created successfully - 135 * the returned value should be stored as the handle to the created stream 136 * buffer. 137 * 138 * Example use: 139 * @code{c} 140 * 141 * void vAFunction( void ) 142 * { 143 * StreamBufferHandle_t xStreamBuffer; 144 * const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10; 145 * 146 * // Create a stream buffer that can hold 100 bytes. The memory used to hold 147 * // both the stream buffer structure and the data in the stream buffer is 148 * // allocated dynamically. 149 * xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel ); 150 * 151 * if( xStreamBuffer == NULL ) 152 * { 153 * // There was not enough heap memory space available to create the 154 * // stream buffer. 155 * } 156 * else 157 * { 158 * // The stream buffer was created successfully and can now be used. 159 * } 160 * } 161 * @endcode 162 * \defgroup xStreamBufferCreate xStreamBufferCreate 163 * \ingroup StreamBufferManagement 164 */ 165 166 #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \ 167 xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, NULL, NULL ) 168 169 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) 170 #define xStreamBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ 171 xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) 172 #endif 173 174 /** 175 * stream_buffer.h 176 * 177 * @code{c} 178 * StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes, 179 * size_t xTriggerLevelBytes, 180 * uint8_t *pucStreamBufferStorageArea, 181 * StaticStreamBuffer_t *pxStaticStreamBuffer ); 182 * @endcode 183 * Creates a new stream buffer using statically allocated memory. See 184 * xStreamBufferCreate() for a version that uses dynamically allocated memory. 185 * 186 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for 187 * xStreamBufferCreateStatic() to be available. configUSE_STREAM_BUFFERS must be 188 * set to 1 in for FreeRTOSConfig.h for xStreamBufferCreateStatic() to be 189 * available. 190 * 191 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the 192 * pucStreamBufferStorageArea parameter. 193 * 194 * @param xTriggerLevelBytes The number of bytes that must be in the stream 195 * buffer before a task that is blocked on the stream buffer to wait for data is 196 * moved out of the blocked state. For example, if a task is blocked on a read 197 * of an empty stream buffer that has a trigger level of 1 then the task will be 198 * unblocked when a single byte is written to the buffer or the task's block 199 * time expires. As another example, if a task is blocked on a read of an empty 200 * stream buffer that has a trigger level of 10 then the task will not be 201 * unblocked until the stream buffer contains at least 10 bytes or the task's 202 * block time expires. If a reading task's block time expires before the 203 * trigger level is reached then the task will still receive however many bytes 204 * are actually available. Setting a trigger level of 0 will result in a 205 * trigger level of 1 being used. It is not valid to specify a trigger level 206 * that is greater than the buffer size. 207 * 208 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at 209 * least xBufferSizeBytes big. This is the array to which streams are 210 * copied when they are written to the stream buffer. 211 * 212 * @param pxStaticStreamBuffer Must point to a variable of type 213 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data 214 * structure. 215 * 216 * @param pxSendCompletedCallback Callback invoked when number of bytes at least equal to 217 * trigger level is sent to the stream buffer. If the parameter is NULL, it will use the default 218 * implementation provided by sbSEND_COMPLETED macro. To enable the callback, 219 * configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h. 220 * 221 * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes are read from a 222 * stream buffer. If the parameter is NULL, it will use the default 223 * implementation provided by sbRECEIVE_COMPLETED macro. To enable the callback, 224 * configUSE_SB_COMPLETED_CALLBACK must be set to 1 in FreeRTOSConfig.h. 225 * 226 * @return If the stream buffer is created successfully then a handle to the 227 * created stream buffer is returned. If either pucStreamBufferStorageArea or 228 * pxStaticstreamBuffer are NULL then NULL is returned. 229 * 230 * Example use: 231 * @code{c} 232 * 233 * // Used to dimension the array used to hold the streams. The available space 234 * // will actually be one less than this, so 999. 235 #define STORAGE_SIZE_BYTES 1000 236 * 237 * // Defines the memory that will actually hold the streams within the stream 238 * // buffer. 239 * static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ]; 240 * 241 * // The variable used to hold the stream buffer structure. 242 * StaticStreamBuffer_t xStreamBufferStruct; 243 * 244 * void MyFunction( void ) 245 * { 246 * StreamBufferHandle_t xStreamBuffer; 247 * const size_t xTriggerLevel = 1; 248 * 249 * xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucStorageBuffer ), 250 * xTriggerLevel, 251 * ucStorageBuffer, 252 * &xStreamBufferStruct ); 253 * 254 * // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer 255 * // parameters were NULL, xStreamBuffer will not be NULL, and can be used to 256 * // reference the created stream buffer in other stream buffer API calls. 257 * 258 * // Other code that uses the stream buffer can go here. 259 * } 260 * 261 * @endcode 262 * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic 263 * \ingroup StreamBufferManagement 264 */ 265 266 #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \ 267 xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) 268 269 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) 270 #define xStreamBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ 271 xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) 272 #endif 273 274 /** 275 * stream_buffer.h 276 * 277 * @code{c} 278 * StreamBufferHandle_t xStreamBatchingBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes ); 279 * @endcode 280 * 281 * Creates a new stream batching buffer using dynamically allocated memory. See 282 * xStreamBatchingBufferCreateStatic() for a version that uses statically 283 * allocated memory (memory that is allocated at compile time). 284 * 285 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in 286 * FreeRTOSConfig.h for xStreamBatchingBufferCreate() to be available. 287 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 288 * xStreamBatchingBufferCreate() to be available. 289 * 290 * The difference between a stream buffer and a stream batching buffer is when 291 * a task performs read on a non-empty buffer: 292 * - The task reading from a non-empty stream buffer returns immediately 293 * regardless of the amount of data in the buffer. 294 * - The task reading from a non-empty steam batching buffer blocks until the 295 * amount of data in the buffer exceeds the trigger level or the block time 296 * expires. 297 * 298 * @param xBufferSizeBytes The total number of bytes the stream batching buffer 299 * will be able to hold at any one time. 300 * 301 * @param xTriggerLevelBytes The number of bytes that must be in the stream 302 * batching buffer to unblock a task calling xStreamBufferReceive before the 303 * block time expires. 304 * 305 * @param pxSendCompletedCallback Callback invoked when number of bytes at least 306 * equal to trigger level is sent to the stream batching buffer. If the 307 * parameter is NULL, it will use the default implementation provided by 308 * sbSEND_COMPLETED macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK 309 * must be set to 1 in FreeRTOSConfig.h. 310 * 311 * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes 312 * are read from a stream batching buffer. If the parameter is NULL, it will use 313 * the default implementation provided by sbRECEIVE_COMPLETED macro. To enable 314 * the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in 315 * FreeRTOSConfig.h. 316 * 317 * @return If NULL is returned, then the stream batching buffer cannot be created 318 * because there is insufficient heap memory available for FreeRTOS to allocate 319 * the stream batching buffer data structures and storage area. A non-NULL value 320 * being returned indicates that the stream batching buffer has been created 321 * successfully - the returned value should be stored as the handle to the 322 * created stream batching buffer. 323 * 324 * Example use: 325 * @code{c} 326 * 327 * void vAFunction( void ) 328 * { 329 * StreamBufferHandle_t xStreamBatchingBuffer; 330 * const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10; 331 * 332 * // Create a stream batching buffer that can hold 100 bytes. The memory used 333 * // to hold both the stream batching buffer structure and the data in the stream 334 * // batching buffer is allocated dynamically. 335 * xStreamBatchingBuffer = xStreamBatchingBufferCreate( xStreamBufferSizeBytes, xTriggerLevel ); 336 * 337 * if( xStreamBatchingBuffer == NULL ) 338 * { 339 * // There was not enough heap memory space available to create the 340 * // stream batching buffer. 341 * } 342 * else 343 * { 344 * // The stream batching buffer was created successfully and can now be used. 345 * } 346 * } 347 * @endcode 348 * \defgroup xStreamBatchingBufferCreate xStreamBatchingBufferCreate 349 * \ingroup StreamBatchingBufferManagement 350 */ 351 352 #define xStreamBatchingBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) \ 353 xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, NULL, NULL ) 354 355 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) 356 #define xStreamBatchingBufferCreateWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ 357 xStreamBufferGenericCreate( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) 358 #endif 359 360 /** 361 * stream_buffer.h 362 * 363 * @code{c} 364 * StreamBufferHandle_t xStreamBatchingBufferCreateStatic( size_t xBufferSizeBytes, 365 * size_t xTriggerLevelBytes, 366 * uint8_t *pucStreamBufferStorageArea, 367 * StaticStreamBuffer_t *pxStaticStreamBuffer ); 368 * @endcode 369 * Creates a new stream batching buffer using statically allocated memory. See 370 * xStreamBatchingBufferCreate() for a version that uses dynamically allocated 371 * memory. 372 * 373 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for 374 * xStreamBatchingBufferCreateStatic() to be available. configUSE_STREAM_BUFFERS 375 * must be set to 1 in for FreeRTOSConfig.h for xStreamBatchingBufferCreateStatic() 376 * to be available. 377 * 378 * The difference between a stream buffer and a stream batching buffer is when 379 * a task performs read on a non-empty buffer: 380 * - The task reading from a non-empty stream buffer returns immediately 381 * regardless of the amount of data in the buffer. 382 * - The task reading from a non-empty steam batching buffer blocks until the 383 * amount of data in the buffer exceeds the trigger level or the block time 384 * expires. 385 * 386 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the 387 * pucStreamBufferStorageArea parameter. 388 * 389 * @param xTriggerLevelBytes The number of bytes that must be in the stream 390 * batching buffer to unblock a task calling xStreamBufferReceive before the 391 * block time expires. 392 * 393 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at 394 * least xBufferSizeBytes big. This is the array to which streams are 395 * copied when they are written to the stream batching buffer. 396 * 397 * @param pxStaticStreamBuffer Must point to a variable of type 398 * StaticStreamBuffer_t, which will be used to hold the stream batching buffer's 399 * data structure. 400 * 401 * @param pxSendCompletedCallback Callback invoked when number of bytes at least 402 * equal to trigger level is sent to the stream batching buffer. If the parameter 403 * is NULL, it will use the default implementation provided by sbSEND_COMPLETED 404 * macro. To enable the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 405 * 1 in FreeRTOSConfig.h. 406 * 407 * @param pxReceiveCompletedCallback Callback invoked when more than zero bytes 408 * are read from a stream batching buffer. If the parameter is NULL, it will use 409 * the default implementation provided by sbRECEIVE_COMPLETED macro. To enable 410 * the callback, configUSE_SB_COMPLETED_CALLBACK must be set to 1 in 411 * FreeRTOSConfig.h. 412 * 413 * @return If the stream batching buffer is created successfully then a handle 414 * to the created stream batching buffer is returned. If either pucStreamBufferStorageArea 415 * or pxStaticstreamBuffer are NULL then NULL is returned. 416 * 417 * Example use: 418 * @code{c} 419 * 420 * // Used to dimension the array used to hold the streams. The available space 421 * // will actually be one less than this, so 999. 422 * #define STORAGE_SIZE_BYTES 1000 423 * 424 * // Defines the memory that will actually hold the streams within the stream 425 * // batching buffer. 426 * static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ]; 427 * 428 * // The variable used to hold the stream batching buffer structure. 429 * StaticStreamBuffer_t xStreamBufferStruct; 430 * 431 * void MyFunction( void ) 432 * { 433 * StreamBufferHandle_t xStreamBatchingBuffer; 434 * const size_t xTriggerLevel = 1; 435 * 436 * xStreamBatchingBuffer = xStreamBatchingBufferCreateStatic( sizeof( ucStorageBuffer ), 437 * xTriggerLevel, 438 * ucStorageBuffer, 439 * &xStreamBufferStruct ); 440 * 441 * // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer 442 * // parameters were NULL, xStreamBatchingBuffer will not be NULL, and can be 443 * // used to reference the created stream batching buffer in other stream 444 * // buffer API calls. 445 * 446 * // Other code that uses the stream batching buffer can go here. 447 * } 448 * 449 * @endcode 450 * \defgroup xStreamBatchingBufferCreateStatic xStreamBatchingBufferCreateStatic 451 * \ingroup StreamBatchingBufferManagement 452 */ 453 454 #define xStreamBatchingBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \ 455 xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), NULL, NULL ) 456 457 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) 458 #define xStreamBatchingBufferCreateStaticWithCallback( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback ) \ 459 xStreamBufferGenericCreateStatic( ( xBufferSizeBytes ), ( xTriggerLevelBytes ), sbTYPE_STREAM_BATCHING_BUFFER, ( pucStreamBufferStorageArea ), ( pxStaticStreamBuffer ), ( pxSendCompletedCallback ), ( pxReceiveCompletedCallback ) ) 460 #endif 461 462 /** 463 * stream_buffer.h 464 * 465 * @code{c} 466 * BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer, 467 * uint8_t ** ppucStreamBufferStorageArea, 468 * StaticStreamBuffer_t ** ppxStaticStreamBuffer ); 469 * @endcode 470 * 471 * Retrieve pointers to a statically created stream buffer's data structure 472 * buffer and storage area buffer. These are the same buffers that are supplied 473 * at the time of creation. 474 * 475 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 476 * xStreamBufferGetStaticBuffers() to be available. 477 * 478 * @param xStreamBuffer The stream buffer for which to retrieve the buffers. 479 * 480 * @param ppucStreamBufferStorageArea Used to return a pointer to the stream 481 * buffer's storage area buffer. 482 * 483 * @param ppxStaticStreamBuffer Used to return a pointer to the stream 484 * buffer's data structure buffer. 485 * 486 * @return pdTRUE if buffers were retrieved, pdFALSE otherwise. 487 * 488 * \defgroup xStreamBufferGetStaticBuffers xStreamBufferGetStaticBuffers 489 * \ingroup StreamBufferManagement 490 */ 491 #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) 492 BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer, 493 uint8_t ** ppucStreamBufferStorageArea, 494 StaticStreamBuffer_t ** ppxStaticStreamBuffer ) PRIVILEGED_FUNCTION; 495 #endif /* configSUPPORT_STATIC_ALLOCATION */ 496 497 /** 498 * stream_buffer.h 499 * 500 * @code{c} 501 * size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, 502 * const void *pvTxData, 503 * size_t xDataLengthBytes, 504 * TickType_t xTicksToWait ); 505 * @endcode 506 * 507 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer. 508 * 509 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer 510 * implementation (so also the message buffer implementation, as message buffers 511 * are built on top of stream buffers) assumes there is only one task or 512 * interrupt that will write to the buffer (the writer), and only one task or 513 * interrupt that will read from the buffer (the reader). It is safe for the 514 * writer and reader to be different tasks or interrupts, but, unlike other 515 * FreeRTOS objects, it is not safe to have multiple different writers or 516 * multiple different readers. If there are to be multiple different writers 517 * then the application writer must place each call to a writing API function 518 * (such as xStreamBufferSend()) inside a critical section and set the send 519 * block time to 0. Likewise, if there are to be multiple different readers 520 * then the application writer must place each call to a reading API function 521 * (such as xStreamBufferReceive()) inside a critical section and set the receive 522 * block time to 0. 523 * 524 * Use xStreamBufferSend() to write to a stream buffer from a task. Use 525 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt 526 * service routine (ISR). 527 * 528 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 529 * xStreamBufferSend() to be available. 530 * 531 * @param xStreamBuffer The handle of the stream buffer to which a stream is 532 * being sent. 533 * 534 * @param pvTxData A pointer to the buffer that holds the bytes to be copied 535 * into the stream buffer. 536 * 537 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData 538 * into the stream buffer. 539 * 540 * @param xTicksToWait The maximum amount of time the task should remain in the 541 * Blocked state to wait for enough space to become available in the stream 542 * buffer, should the stream buffer contain too little space to hold the 543 * another xDataLengthBytes bytes. The block time is specified in tick periods, 544 * so the absolute time it represents is dependent on the tick frequency. The 545 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds 546 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will 547 * cause the task to wait indefinitely (without timing out), provided 548 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out 549 * before it can write all xDataLengthBytes into the buffer it will still write 550 * as many bytes as possible. A task does not use any CPU time when it is in 551 * the blocked state. 552 * 553 * @return The number of bytes written to the stream buffer. If a task times 554 * out before it can write all xDataLengthBytes into the buffer it will still 555 * write as many bytes as possible. 556 * 557 * Example use: 558 * @code{c} 559 * void vAFunction( StreamBufferHandle_t xStreamBuffer ) 560 * { 561 * size_t xBytesSent; 562 * uint8_t ucArrayToSend[] = { 0, 1, 2, 3 }; 563 * char *pcStringToSend = "String to send"; 564 * const TickType_t x100ms = pdMS_TO_TICKS( 100 ); 565 * 566 * // Send an array to the stream buffer, blocking for a maximum of 100ms to 567 * // wait for enough space to be available in the stream buffer. 568 * xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms ); 569 * 570 * if( xBytesSent != sizeof( ucArrayToSend ) ) 571 * { 572 * // The call to xStreamBufferSend() times out before there was enough 573 * // space in the buffer for the data to be written, but it did 574 * // successfully write xBytesSent bytes. 575 * } 576 * 577 * // Send the string to the stream buffer. Return immediately if there is not 578 * // enough space in the buffer. 579 * xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 ); 580 * 581 * if( xBytesSent != strlen( pcStringToSend ) ) 582 * { 583 * // The entire string could not be added to the stream buffer because 584 * // there was not enough free space in the buffer, but xBytesSent bytes 585 * // were sent. Could try again to send the remaining bytes. 586 * } 587 * } 588 * @endcode 589 * \defgroup xStreamBufferSend xStreamBufferSend 590 * \ingroup StreamBufferManagement 591 */ 592 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer, 593 const void * pvTxData, 594 size_t xDataLengthBytes, 595 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 596 597 /** 598 * stream_buffer.h 599 * 600 * @code{c} 601 * size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, 602 * const void *pvTxData, 603 * size_t xDataLengthBytes, 604 * BaseType_t *pxHigherPriorityTaskWoken ); 605 * @endcode 606 * 607 * Interrupt safe version of the API function that sends a stream of bytes to 608 * the stream buffer. 609 * 610 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer 611 * implementation (so also the message buffer implementation, as message buffers 612 * are built on top of stream buffers) assumes there is only one task or 613 * interrupt that will write to the buffer (the writer), and only one task or 614 * interrupt that will read from the buffer (the reader). It is safe for the 615 * writer and reader to be different tasks or interrupts, but, unlike other 616 * FreeRTOS objects, it is not safe to have multiple different writers or 617 * multiple different readers. If there are to be multiple different writers 618 * then the application writer must place each call to a writing API function 619 * (such as xStreamBufferSend()) inside a critical section and set the send 620 * block time to 0. Likewise, if there are to be multiple different readers 621 * then the application writer must place each call to a reading API function 622 * (such as xStreamBufferReceive()) inside a critical section and set the receive 623 * block time to 0. 624 * 625 * Use xStreamBufferSend() to write to a stream buffer from a task. Use 626 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt 627 * service routine (ISR). 628 * 629 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 630 * xStreamBufferSendFromISR() to be available. 631 * 632 * @param xStreamBuffer The handle of the stream buffer to which a stream is 633 * being sent. 634 * 635 * @param pvTxData A pointer to the data that is to be copied into the stream 636 * buffer. 637 * 638 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData 639 * into the stream buffer. 640 * 641 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will 642 * have a task blocked on it waiting for data. Calling 643 * xStreamBufferSendFromISR() can make data available, and so cause a task that 644 * was waiting for data to leave the Blocked state. If calling 645 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the 646 * unblocked task has a priority higher than the currently executing task (the 647 * task that was interrupted), then, internally, xStreamBufferSendFromISR() 648 * will set *pxHigherPriorityTaskWoken to pdTRUE. If 649 * xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a 650 * context switch should be performed before the interrupt is exited. This will 651 * ensure that the interrupt returns directly to the highest priority Ready 652 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it 653 * is passed into the function. See the example code below for an example. 654 * 655 * @return The number of bytes actually written to the stream buffer, which will 656 * be less than xDataLengthBytes if the stream buffer didn't have enough free 657 * space for all the bytes to be written. 658 * 659 * Example use: 660 * @code{c} 661 * // A stream buffer that has already been created. 662 * StreamBufferHandle_t xStreamBuffer; 663 * 664 * void vAnInterruptServiceRoutine( void ) 665 * { 666 * size_t xBytesSent; 667 * char *pcStringToSend = "String to send"; 668 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE. 669 * 670 * // Attempt to send the string to the stream buffer. 671 * xBytesSent = xStreamBufferSendFromISR( xStreamBuffer, 672 * ( void * ) pcStringToSend, 673 * strlen( pcStringToSend ), 674 * &xHigherPriorityTaskWoken ); 675 * 676 * if( xBytesSent != strlen( pcStringToSend ) ) 677 * { 678 * // There was not enough free space in the stream buffer for the entire 679 * // string to be written, ut xBytesSent bytes were written. 680 * } 681 * 682 * // If xHigherPriorityTaskWoken was set to pdTRUE inside 683 * // xStreamBufferSendFromISR() then a task that has a priority above the 684 * // priority of the currently executing task was unblocked and a context 685 * // switch should be performed to ensure the ISR returns to the unblocked 686 * // task. In most FreeRTOS ports this is done by simply passing 687 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the 688 * // variables value, and perform the context switch if necessary. Check the 689 * // documentation for the port in use for port specific instructions. 690 * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); 691 * } 692 * @endcode 693 * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR 694 * \ingroup StreamBufferManagement 695 */ 696 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer, 697 const void * pvTxData, 698 size_t xDataLengthBytes, 699 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 700 701 /** 702 * stream_buffer.h 703 * 704 * @code{c} 705 * size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, 706 * void *pvRxData, 707 * size_t xBufferLengthBytes, 708 * TickType_t xTicksToWait ); 709 * @endcode 710 * 711 * Receives bytes from a stream buffer. 712 * 713 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer 714 * implementation (so also the message buffer implementation, as message buffers 715 * are built on top of stream buffers) assumes there is only one task or 716 * interrupt that will write to the buffer (the writer), and only one task or 717 * interrupt that will read from the buffer (the reader). It is safe for the 718 * writer and reader to be different tasks or interrupts, but, unlike other 719 * FreeRTOS objects, it is not safe to have multiple different writers or 720 * multiple different readers. If there are to be multiple different writers 721 * then the application writer must place each call to a writing API function 722 * (such as xStreamBufferSend()) inside a critical section and set the send 723 * block time to 0. Likewise, if there are to be multiple different readers 724 * then the application writer must place each call to a reading API function 725 * (such as xStreamBufferReceive()) inside a critical section and set the receive 726 * block time to 0. 727 * 728 * Use xStreamBufferReceive() to read from a stream buffer from a task. Use 729 * xStreamBufferReceiveFromISR() to read from a stream buffer from an 730 * interrupt service routine (ISR). 731 * 732 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 733 * xStreamBufferReceive() to be available. 734 * 735 * @param xStreamBuffer The handle of the stream buffer from which bytes are to 736 * be received. 737 * 738 * @param pvRxData A pointer to the buffer into which the received bytes will be 739 * copied. 740 * 741 * @param xBufferLengthBytes The length of the buffer pointed to by the 742 * pvRxData parameter. This sets the maximum number of bytes to receive in one 743 * call. xStreamBufferReceive will return as many bytes as possible up to a 744 * maximum set by xBufferLengthBytes. 745 * 746 * @param xTicksToWait The maximum amount of time the task should remain in the 747 * Blocked state to wait for data to become available if the stream buffer is 748 * empty. xStreamBufferReceive() will return immediately if xTicksToWait is 749 * zero. The block time is specified in tick periods, so the absolute time it 750 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can 751 * be used to convert a time specified in milliseconds into a time specified in 752 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait 753 * indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 754 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the 755 * Blocked state. 756 * 757 * @return The number of bytes actually read from the stream buffer, which will 758 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed 759 * out before xBufferLengthBytes were available. 760 * 761 * Example use: 762 * @code{c} 763 * void vAFunction( StreamBuffer_t xStreamBuffer ) 764 * { 765 * uint8_t ucRxData[ 20 ]; 766 * size_t xReceivedBytes; 767 * const TickType_t xBlockTime = pdMS_TO_TICKS( 20 ); 768 * 769 * // Receive up to another sizeof( ucRxData ) bytes from the stream buffer. 770 * // Wait in the Blocked state (so not using any CPU processing time) for a 771 * // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be 772 * // available. 773 * xReceivedBytes = xStreamBufferReceive( xStreamBuffer, 774 * ( void * ) ucRxData, 775 * sizeof( ucRxData ), 776 * xBlockTime ); 777 * 778 * if( xReceivedBytes > 0 ) 779 * { 780 * // A ucRxData contains another xReceivedBytes bytes of data, which can 781 * // be processed here.... 782 * } 783 * } 784 * @endcode 785 * \defgroup xStreamBufferReceive xStreamBufferReceive 786 * \ingroup StreamBufferManagement 787 */ 788 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer, 789 void * pvRxData, 790 size_t xBufferLengthBytes, 791 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 792 793 /** 794 * stream_buffer.h 795 * 796 * @code{c} 797 * size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, 798 * void *pvRxData, 799 * size_t xBufferLengthBytes, 800 * BaseType_t *pxHigherPriorityTaskWoken ); 801 * @endcode 802 * 803 * An interrupt safe version of the API function that receives bytes from a 804 * stream buffer. 805 * 806 * Use xStreamBufferReceive() to read bytes from a stream buffer from a task. 807 * Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an 808 * interrupt service routine (ISR). 809 * 810 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 811 * xStreamBufferReceiveFromISR() to be available. 812 * 813 * @param xStreamBuffer The handle of the stream buffer from which a stream 814 * is being received. 815 * 816 * @param pvRxData A pointer to the buffer into which the received bytes are 817 * copied. 818 * 819 * @param xBufferLengthBytes The length of the buffer pointed to by the 820 * pvRxData parameter. This sets the maximum number of bytes to receive in one 821 * call. xStreamBufferReceive will return as many bytes as possible up to a 822 * maximum set by xBufferLengthBytes. 823 * 824 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will 825 * have a task blocked on it waiting for space to become available. Calling 826 * xStreamBufferReceiveFromISR() can make space available, and so cause a task 827 * that is waiting for space to leave the Blocked state. If calling 828 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and 829 * the unblocked task has a priority higher than the currently executing task 830 * (the task that was interrupted), then, internally, 831 * xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE. 832 * If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a 833 * context switch should be performed before the interrupt is exited. That will 834 * ensure the interrupt returns directly to the highest priority Ready state 835 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is 836 * passed into the function. See the code example below for an example. 837 * 838 * @return The number of bytes read from the stream buffer, if any. 839 * 840 * Example use: 841 * @code{c} 842 * // A stream buffer that has already been created. 843 * StreamBuffer_t xStreamBuffer; 844 * 845 * void vAnInterruptServiceRoutine( void ) 846 * { 847 * uint8_t ucRxData[ 20 ]; 848 * size_t xReceivedBytes; 849 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE. 850 * 851 * // Receive the next stream from the stream buffer. 852 * xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer, 853 * ( void * ) ucRxData, 854 * sizeof( ucRxData ), 855 * &xHigherPriorityTaskWoken ); 856 * 857 * if( xReceivedBytes > 0 ) 858 * { 859 * // ucRxData contains xReceivedBytes read from the stream buffer. 860 * // Process the stream here.... 861 * } 862 * 863 * // If xHigherPriorityTaskWoken was set to pdTRUE inside 864 * // xStreamBufferReceiveFromISR() then a task that has a priority above the 865 * // priority of the currently executing task was unblocked and a context 866 * // switch should be performed to ensure the ISR returns to the unblocked 867 * // task. In most FreeRTOS ports this is done by simply passing 868 * // xHigherPriorityTaskWoken into portYIELD_FROM_ISR(), which will test the 869 * // variables value, and perform the context switch if necessary. Check the 870 * // documentation for the port in use for port specific instructions. 871 * portYIELD_FROM_ISR( xHigherPriorityTaskWoken ); 872 * } 873 * @endcode 874 * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR 875 * \ingroup StreamBufferManagement 876 */ 877 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer, 878 void * pvRxData, 879 size_t xBufferLengthBytes, 880 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 881 882 /** 883 * stream_buffer.h 884 * 885 * @code{c} 886 * void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ); 887 * @endcode 888 * 889 * Deletes a stream buffer that was previously created using a call to 890 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream 891 * buffer was created using dynamic memory (that is, by xStreamBufferCreate()), 892 * then the allocated memory is freed. 893 * 894 * A stream buffer handle must not be used after the stream buffer has been 895 * deleted. 896 * 897 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 898 * vStreamBufferDelete() to be available. 899 * 900 * @param xStreamBuffer The handle of the stream buffer to be deleted. 901 * 902 * \defgroup vStreamBufferDelete vStreamBufferDelete 903 * \ingroup StreamBufferManagement 904 */ 905 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 906 907 /** 908 * stream_buffer.h 909 * 910 * @code{c} 911 * BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ); 912 * @endcode 913 * 914 * Queries a stream buffer to see if it is full. A stream buffer is full if it 915 * does not have any free space, and therefore cannot accept any more data. 916 * 917 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 918 * xStreamBufferIsFull() to be available. 919 * 920 * @param xStreamBuffer The handle of the stream buffer being queried. 921 * 922 * @return If the stream buffer is full then pdTRUE is returned. Otherwise 923 * pdFALSE is returned. 924 * 925 * \defgroup xStreamBufferIsFull xStreamBufferIsFull 926 * \ingroup StreamBufferManagement 927 */ 928 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 929 930 /** 931 * stream_buffer.h 932 * 933 * @code{c} 934 * BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ); 935 * @endcode 936 * 937 * Queries a stream buffer to see if it is empty. A stream buffer is empty if 938 * it does not contain any data. 939 * 940 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 941 * xStreamBufferIsEmpty() to be available. 942 * 943 * @param xStreamBuffer The handle of the stream buffer being queried. 944 * 945 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise 946 * pdFALSE is returned. 947 * 948 * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty 949 * \ingroup StreamBufferManagement 950 */ 951 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 952 953 /** 954 * stream_buffer.h 955 * 956 * @code{c} 957 * BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ); 958 * @endcode 959 * 960 * Resets a stream buffer to its initial, empty, state. Any data that was in 961 * the stream buffer is discarded. A stream buffer can only be reset if there 962 * are no tasks blocked waiting to either send to or receive from the stream 963 * buffer. 964 * 965 * Use xStreamBufferReset() to reset a stream buffer from a task. 966 * Use xStreamBufferResetFromISR() to reset a stream buffer from an 967 * interrupt service routine (ISR). 968 * 969 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 970 * xStreamBufferReset() to be available. 971 * 972 * @param xStreamBuffer The handle of the stream buffer being reset. 973 * 974 * @return If the stream buffer is reset then pdPASS is returned. If there was 975 * a task blocked waiting to send to or read from the stream buffer then the 976 * stream buffer is not reset and pdFAIL is returned. 977 * 978 * \defgroup xStreamBufferReset xStreamBufferReset 979 * \ingroup StreamBufferManagement 980 */ 981 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 982 983 /** 984 * stream_buffer.h 985 * 986 * @code{c} 987 * BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ); 988 * @endcode 989 * 990 * An interrupt safe version of the API function that resets the stream buffer. 991 * 992 * Resets a stream buffer to its initial, empty, state. Any data that was in 993 * the stream buffer is discarded. A stream buffer can only be reset if there 994 * are no tasks blocked waiting to either send to or receive from the stream 995 * buffer. 996 * 997 * Use xStreamBufferReset() to reset a stream buffer from a task. 998 * Use xStreamBufferResetFromISR() to reset a stream buffer from an 999 * interrupt service routine (ISR). 1000 * 1001 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1002 * xStreamBufferResetFromISR() to be available. 1003 * 1004 * @param xStreamBuffer The handle of the stream buffer being reset. 1005 * 1006 * @return If the stream buffer is reset then pdPASS is returned. If there was 1007 * a task blocked waiting to send to or read from the stream buffer then the 1008 * stream buffer is not reset and pdFAIL is returned. 1009 * 1010 * \defgroup xStreamBufferResetFromISR xStreamBufferResetFromISR 1011 * \ingroup StreamBufferManagement 1012 */ 1013 BaseType_t xStreamBufferResetFromISR( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1014 1015 /** 1016 * stream_buffer.h 1017 * 1018 * @code{c} 1019 * size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ); 1020 * @endcode 1021 * 1022 * Queries a stream buffer to see how much free space it contains, which is 1023 * equal to the amount of data that can be sent to the stream buffer before it 1024 * is full. 1025 * 1026 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1027 * xStreamBufferSpacesAvailable() to be available. 1028 * 1029 * @param xStreamBuffer The handle of the stream buffer being queried. 1030 * 1031 * @return The number of bytes that can be written to the stream buffer before 1032 * the stream buffer would be full. 1033 * 1034 * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable 1035 * \ingroup StreamBufferManagement 1036 */ 1037 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1038 1039 /** 1040 * stream_buffer.h 1041 * 1042 * @code{c} 1043 * size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ); 1044 * @endcode 1045 * 1046 * Queries a stream buffer to see how much data it contains, which is equal to 1047 * the number of bytes that can be read from the stream buffer before the stream 1048 * buffer would be empty. 1049 * 1050 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1051 * xStreamBufferBytesAvailable() to be available. 1052 * 1053 * @param xStreamBuffer The handle of the stream buffer being queried. 1054 * 1055 * @return The number of bytes that can be read from the stream buffer before 1056 * the stream buffer would be empty. 1057 * 1058 * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable 1059 * \ingroup StreamBufferManagement 1060 */ 1061 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1062 1063 /** 1064 * stream_buffer.h 1065 * 1066 * @code{c} 1067 * BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ); 1068 * @endcode 1069 * 1070 * A stream buffer's trigger level is the number of bytes that must be in the 1071 * stream buffer before a task that is blocked on the stream buffer to 1072 * wait for data is moved out of the blocked state. For example, if a task is 1073 * blocked on a read of an empty stream buffer that has a trigger level of 1 1074 * then the task will be unblocked when a single byte is written to the buffer 1075 * or the task's block time expires. As another example, if a task is blocked 1076 * on a read of an empty stream buffer that has a trigger level of 10 then the 1077 * task will not be unblocked until the stream buffer contains at least 10 bytes 1078 * or the task's block time expires. If a reading task's block time expires 1079 * before the trigger level is reached then the task will still receive however 1080 * many bytes are actually available. Setting a trigger level of 0 will result 1081 * in a trigger level of 1 being used. It is not valid to specify a trigger 1082 * level that is greater than the buffer size. 1083 * 1084 * A trigger level is set when the stream buffer is created, and can be modified 1085 * using xStreamBufferSetTriggerLevel(). 1086 * 1087 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1088 * xStreamBufferSetTriggerLevel() to be available. 1089 * 1090 * @param xStreamBuffer The handle of the stream buffer being updated. 1091 * 1092 * @param xTriggerLevel The new trigger level for the stream buffer. 1093 * 1094 * @return If xTriggerLevel was less than or equal to the stream buffer's length 1095 * then the trigger level will be updated and pdTRUE is returned. Otherwise 1096 * pdFALSE is returned. 1097 * 1098 * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel 1099 * \ingroup StreamBufferManagement 1100 */ 1101 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, 1102 size_t xTriggerLevel ) PRIVILEGED_FUNCTION; 1103 1104 /** 1105 * stream_buffer.h 1106 * 1107 * @code{c} 1108 * BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); 1109 * @endcode 1110 * 1111 * For advanced users only. 1112 * 1113 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when 1114 * data is sent to a message buffer or stream buffer. If there was a task that 1115 * was blocked on the message or stream buffer waiting for data to arrive then 1116 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it 1117 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same 1118 * thing. It is provided to enable application writers to implement their own 1119 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME. 1120 * 1121 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for 1122 * additional information. 1123 * 1124 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1125 * xStreamBufferSendCompletedFromISR() to be available. 1126 * 1127 * @param xStreamBuffer The handle of the stream buffer to which data was 1128 * written. 1129 * 1130 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be 1131 * initialised to pdFALSE before it is passed into 1132 * xStreamBufferSendCompletedFromISR(). If calling 1133 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state, 1134 * and the task has a priority above the priority of the currently running task, 1135 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a 1136 * context switch should be performed before exiting the ISR. 1137 * 1138 * @return If a task was removed from the Blocked state then pdTRUE is returned. 1139 * Otherwise pdFALSE is returned. 1140 * 1141 * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR 1142 * \ingroup StreamBufferManagement 1143 */ 1144 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, 1145 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1146 1147 /** 1148 * stream_buffer.h 1149 * 1150 * @code{c} 1151 * BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ); 1152 * @endcode 1153 * 1154 * For advanced users only. 1155 * 1156 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when 1157 * data is read out of a message buffer or stream buffer. If there was a task 1158 * that was blocked on the message or stream buffer waiting for data to arrive 1159 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to 1160 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR() 1161 * does the same thing. It is provided to enable application writers to 1162 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT 1163 * ANY OTHER TIME. 1164 * 1165 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for 1166 * additional information. 1167 * 1168 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1169 * xStreamBufferReceiveCompletedFromISR() to be available. 1170 * 1171 * @param xStreamBuffer The handle of the stream buffer from which data was 1172 * read. 1173 * 1174 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be 1175 * initialised to pdFALSE before it is passed into 1176 * xStreamBufferReceiveCompletedFromISR(). If calling 1177 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state, 1178 * and the task has a priority above the priority of the currently running task, 1179 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a 1180 * context switch should be performed before exiting the ISR. 1181 * 1182 * @return If a task was removed from the Blocked state then pdTRUE is returned. 1183 * Otherwise pdFALSE is returned. 1184 * 1185 * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR 1186 * \ingroup StreamBufferManagement 1187 */ 1188 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, 1189 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1190 1191 /** 1192 * stream_buffer.h 1193 * 1194 * @code{c} 1195 * UBaseType_t uxStreamBufferGetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer ); 1196 * @endcode 1197 * 1198 * Get the task notification index used for the supplied stream buffer which can 1199 * be set using vStreamBufferSetStreamBufferNotificationIndex. If the task 1200 * notification index for the stream buffer is not changed using 1201 * vStreamBufferSetStreamBufferNotificationIndex, this function returns the 1202 * default value (tskDEFAULT_INDEX_TO_NOTIFY). 1203 * 1204 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1205 * uxStreamBufferGetStreamBufferNotificationIndex() to be available. 1206 * 1207 * @param xStreamBuffer The handle of the stream buffer for which the task 1208 * notification index is retrieved. 1209 * 1210 * @return The task notification index for the stream buffer. 1211 * 1212 * \defgroup uxStreamBufferGetStreamBufferNotificationIndex uxStreamBufferGetStreamBufferNotificationIndex 1213 * \ingroup StreamBufferManagement 1214 */ 1215 UBaseType_t uxStreamBufferGetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1216 1217 /** 1218 * stream_buffer.h 1219 * 1220 * @code{c} 1221 * void vStreamBufferSetStreamBufferNotificationIndex ( StreamBuffer_t xStreamBuffer, UBaseType_t uxNotificationIndex ); 1222 * @endcode 1223 * 1224 * Set the task notification index used for the supplied stream buffer. 1225 * Successive calls to stream buffer APIs (like xStreamBufferSend or 1226 * xStreamBufferReceive) for this stream buffer will use this new index for 1227 * their task notifications. 1228 * 1229 * If this function is not called, the default index (tskDEFAULT_INDEX_TO_NOTIFY) 1230 * is used for task notifications. It is recommended to call this function 1231 * before attempting to send or receive data from the stream buffer to avoid 1232 * inconsistencies. 1233 * 1234 * configUSE_STREAM_BUFFERS must be set to 1 in for FreeRTOSConfig.h for 1235 * vStreamBufferSetStreamBufferNotificationIndex() to be available. 1236 * 1237 * @param xStreamBuffer The handle of the stream buffer for which the task 1238 * notification index is set. 1239 * 1240 * @param uxNotificationIndex The task notification index to set. 1241 * 1242 * \defgroup vStreamBufferSetStreamBufferNotificationIndex vStreamBufferSetStreamBufferNotificationIndex 1243 * \ingroup StreamBufferManagement 1244 */ 1245 void vStreamBufferSetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer, 1246 UBaseType_t uxNotificationIndex ) PRIVILEGED_FUNCTION; 1247 1248 /* Functions below here are not part of the public API. */ 1249 StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes, 1250 size_t xTriggerLevelBytes, 1251 BaseType_t xStreamBufferType, 1252 StreamBufferCallbackFunction_t pxSendCompletedCallback, 1253 StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION; 1254 1255 #if ( configSUPPORT_STATIC_ALLOCATION == 1 ) 1256 StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes, 1257 size_t xTriggerLevelBytes, 1258 BaseType_t xStreamBufferType, 1259 uint8_t * const pucStreamBufferStorageArea, 1260 StaticStreamBuffer_t * const pxStaticStreamBuffer, 1261 StreamBufferCallbackFunction_t pxSendCompletedCallback, 1262 StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION; 1263 #endif 1264 1265 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1266 1267 #if ( configUSE_TRACE_FACILITY == 1 ) 1268 void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer, 1269 UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION; 1270 UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1271 uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION; 1272 #endif 1273 1274 /* *INDENT-OFF* */ 1275 #if defined( __cplusplus ) 1276 } 1277 #endif 1278 /* *INDENT-ON* */ 1279 1280 #endif /* !defined( STREAM_BUFFER_H ) */ 1281
