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

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