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