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 serialize calls to writing API functions
  44  * (such as xStreamBufferSend()).  Likewise, if there are to be multiple
  45  * different readers then the application writer must serialize calls to reading
  46  * API functions (such as xStreamBufferReceive()).  One way to achieve such
  47  * serialization in single core or SMP kernel is to place each API call inside a
  48  * critical section and use a block time of 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 serialize calls to writing API functions
 518  * (such as xStreamBufferSend()).  Likewise, if there are to be multiple
 519  * different readers then the application writer must serialize calls to reading
 520  * API functions (such as xStreamBufferReceive()).  One way to achieve such
 521  * serialization in single core or SMP kernel is to place each API call inside a
 522  * critical section and use a block time of 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 serialize calls to writing API functions
 619  * (such as xStreamBufferSend()).  Likewise, if there are to be multiple
 620  * different readers then the application writer must serialize calls to reading
 621  * API functions (such as xStreamBufferReceive()).  One way to achieve such
 622  * serialization in single core or SMP kernel is to place each API call inside a
 623  * critical section and use a block time of 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 serialize calls to writing API functions
 722  * (such as xStreamBufferSend()).  Likewise, if there are to be multiple
 723  * different readers then the application writer must serialize calls to reading
 724  * API functions (such as xStreamBufferReceive()).  One way to achieve such
 725  * serialization in single core or SMP kernel is to place each API call inside a
 726  * critical section and use a block time of 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 ) */