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

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