begriffs open source - freertos/blob - include/stream_buffer.h

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