begriffs open source - freertos/blob - stream_buffer.c

   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 /* Standard includes. */
  30 #include <string.h>
  31
  32 /* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
  33  * all the API functions to use the MPU wrappers.  That should only be done when
  34  * task.h is included from an application file. */
  35 #define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
  36
  37 /* FreeRTOS includes. */
  38 #include "FreeRTOS.h"
  39 #include "task.h"
  40 #include "stream_buffer.h"
  41
  42 #if ( configUSE_TASK_NOTIFICATIONS != 1 )
  43     #error configUSE_TASK_NOTIFICATIONS must be set to 1 to build stream_buffer.c
  44 #endif
  45
  46 #if ( INCLUDE_xTaskGetCurrentTaskHandle != 1 )
  47     #error INCLUDE_xTaskGetCurrentTaskHandle must be set to 1 to build stream_buffer.c
  48 #endif
  49
  50 /* The MPU ports require MPU_WRAPPERS_INCLUDED_FROM_API_FILE to be defined
  51  * for the header files above, but not in this file, in order to generate the
  52  * correct privileged Vs unprivileged linkage and placement. */
  53 #undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE
  54
  55 /* If the user has not provided application specific Rx notification macros,
  56  * or #defined the notification macros away, then provide default implementations
  57  * that uses task notifications. */
  58 #ifndef sbRECEIVE_COMPLETED
  59     #define sbRECEIVE_COMPLETED( pxStreamBuffer )                                     \
  60     do                                                                                \
  61     {                                                                                 \
  62         vTaskSuspendAll();                                                            \
  63         {                                                                             \
  64             if( ( pxStreamBuffer )->xTaskWaitingToSend != NULL )                      \
  65             {                                                                         \
  66                 ( void ) xTaskNotifyIndexed( ( pxStreamBuffer )->xTaskWaitingToSend,  \
  67                                              ( pxStreamBuffer )->uxNotificationIndex, \
  68                                              ( uint32_t ) 0,                          \
  69                                              eNoAction );                             \
  70                 ( pxStreamBuffer )->xTaskWaitingToSend = NULL;                        \
  71             }                                                                         \
  72         }                                                                             \
  73         ( void ) xTaskResumeAll();                                                    \
  74     } while( 0 )
  75 #endif /* sbRECEIVE_COMPLETED */
  76
  77 /* If user has provided a per-instance receive complete callback, then
  78  * invoke the callback else use the receive complete macro which is provided by default for all instances.
  79  */
  80 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
  81     #define prvRECEIVE_COMPLETED( pxStreamBuffer )                                               \
  82     do {                                                                                         \
  83         if( ( pxStreamBuffer )->pxReceiveCompletedCallback != NULL )                             \
  84         {                                                                                        \
  85             ( pxStreamBuffer )->pxReceiveCompletedCallback( ( pxStreamBuffer ), pdFALSE, NULL ); \
  86         }                                                                                        \
  87         else                                                                                     \
  88         {                                                                                        \
  89             sbRECEIVE_COMPLETED( ( pxStreamBuffer ) );                                           \
  90         }                                                                                        \
  91     } while( 0 )
  92 #else /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
  93     #define prvRECEIVE_COMPLETED( pxStreamBuffer )    sbRECEIVE_COMPLETED( ( pxStreamBuffer ) )
  94 #endif /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
  95
  96 #ifndef sbRECEIVE_COMPLETED_FROM_ISR
  97     #define sbRECEIVE_COMPLETED_FROM_ISR( pxStreamBuffer,                                    \
  98                                           pxHigherPriorityTaskWoken )                        \
  99     do {                                                                                     \
 100         UBaseType_t uxSavedInterruptStatus;                                                  \
 101                                                                                              \
 102         uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();                              \
 103         {                                                                                    \
 104             if( ( pxStreamBuffer )->xTaskWaitingToSend != NULL )                             \
 105             {                                                                                \
 106                 ( void ) xTaskNotifyIndexedFromISR( ( pxStreamBuffer )->xTaskWaitingToSend,  \
 107                                                     ( pxStreamBuffer )->uxNotificationIndex, \
 108                                                     ( uint32_t ) 0,                          \
 109                                                     eNoAction,                               \
 110                                                     ( pxHigherPriorityTaskWoken ) );         \
 111                 ( pxStreamBuffer )->xTaskWaitingToSend = NULL;                               \
 112             }                                                                                \
 113         }                                                                                    \
 114         taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );                                \
 115     } while( 0 )
 116 #endif /* sbRECEIVE_COMPLETED_FROM_ISR */
 117
 118 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
 119     #define prvRECEIVE_COMPLETED_FROM_ISR( pxStreamBuffer,                                                               \
 120                                            pxHigherPriorityTaskWoken )                                                   \
 121     do {                                                                                                                 \
 122         if( ( pxStreamBuffer )->pxReceiveCompletedCallback != NULL )                                                     \
 123         {                                                                                                                \
 124             ( pxStreamBuffer )->pxReceiveCompletedCallback( ( pxStreamBuffer ), pdTRUE, ( pxHigherPriorityTaskWoken ) ); \
 125         }                                                                                                                \
 126         else                                                                                                             \
 127         {                                                                                                                \
 128             sbRECEIVE_COMPLETED_FROM_ISR( ( pxStreamBuffer ), ( pxHigherPriorityTaskWoken ) );                           \
 129         }                                                                                                                \
 130     } while( 0 )
 131 #else /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 132     #define prvRECEIVE_COMPLETED_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken ) \
 133     sbRECEIVE_COMPLETED_FROM_ISR( ( pxStreamBuffer ), ( pxHigherPriorityTaskWoken ) )
 134 #endif /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 135
 136 /* If the user has not provided an application specific Tx notification macro,
 137  * or #defined the notification macro away, then provide a default
 138  * implementation that uses task notifications.
 139  */
 140 #ifndef sbSEND_COMPLETED
 141     #define sbSEND_COMPLETED( pxStreamBuffer )                                      \
 142     vTaskSuspendAll();                                                              \
 143     {                                                                               \
 144         if( ( pxStreamBuffer )->xTaskWaitingToReceive != NULL )                     \
 145         {                                                                           \
 146             ( void ) xTaskNotifyIndexed( ( pxStreamBuffer )->xTaskWaitingToReceive, \
 147                                          ( pxStreamBuffer )->uxNotificationIndex,   \
 148                                          ( uint32_t ) 0,                            \
 149                                          eNoAction );                               \
 150             ( pxStreamBuffer )->xTaskWaitingToReceive = NULL;                       \
 151         }                                                                           \
 152     }                                                                               \
 153     ( void ) xTaskResumeAll()
 154 #endif /* sbSEND_COMPLETED */
 155
 156 /* If user has provided a per-instance send completed callback, then
 157  * invoke the callback else use the send complete macro which is provided by default for all instances.
 158  */
 159 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
 160     #define prvSEND_COMPLETED( pxStreamBuffer )                                               \
 161     do {                                                                                      \
 162         if( ( pxStreamBuffer )->pxSendCompletedCallback != NULL )                             \
 163         {                                                                                     \
 164             ( pxStreamBuffer )->pxSendCompletedCallback( ( pxStreamBuffer ), pdFALSE, NULL ); \
 165         }                                                                                     \
 166         else                                                                                  \
 167         {                                                                                     \
 168             sbSEND_COMPLETED( ( pxStreamBuffer ) );                                           \
 169         }                                                                                     \
 170     } while( 0 )
 171 #else /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 172     #define prvSEND_COMPLETED( pxStreamBuffer )    sbSEND_COMPLETED( ( pxStreamBuffer ) )
 173 #endif /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 174
 175
 176 #ifndef sbSEND_COMPLETE_FROM_ISR
 177     #define sbSEND_COMPLETE_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken )              \
 178     do {                                                                                       \
 179         UBaseType_t uxSavedInterruptStatus;                                                    \
 180                                                                                                \
 181         uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();                                \
 182         {                                                                                      \
 183             if( ( pxStreamBuffer )->xTaskWaitingToReceive != NULL )                            \
 184             {                                                                                  \
 185                 ( void ) xTaskNotifyIndexedFromISR( ( pxStreamBuffer )->xTaskWaitingToReceive, \
 186                                                     ( pxStreamBuffer )->uxNotificationIndex,   \
 187                                                     ( uint32_t ) 0,                            \
 188                                                     eNoAction,                                 \
 189                                                     ( pxHigherPriorityTaskWoken ) );           \
 190                 ( pxStreamBuffer )->xTaskWaitingToReceive = NULL;                              \
 191             }                                                                                  \
 192         }                                                                                      \
 193         taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );                                  \
 194     } while( 0 )
 195 #endif /* sbSEND_COMPLETE_FROM_ISR */
 196
 197
 198 #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
 199     #define prvSEND_COMPLETE_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken )                                    \
 200     do {                                                                                                              \
 201         if( ( pxStreamBuffer )->pxSendCompletedCallback != NULL )                                                     \
 202         {                                                                                                             \
 203             ( pxStreamBuffer )->pxSendCompletedCallback( ( pxStreamBuffer ), pdTRUE, ( pxHigherPriorityTaskWoken ) ); \
 204         }                                                                                                             \
 205         else                                                                                                          \
 206         {                                                                                                             \
 207             sbSEND_COMPLETE_FROM_ISR( ( pxStreamBuffer ), ( pxHigherPriorityTaskWoken ) );                            \
 208         }                                                                                                             \
 209     } while( 0 )
 210 #else /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 211     #define prvSEND_COMPLETE_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken ) \
 212     sbSEND_COMPLETE_FROM_ISR( ( pxStreamBuffer ), ( pxHigherPriorityTaskWoken ) )
 213 #endif /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
 214
 215 /* The number of bytes used to hold the length of a message in the buffer. */
 216 #define sbBYTES_TO_STORE_MESSAGE_LENGTH    ( sizeof( configMESSAGE_BUFFER_LENGTH_TYPE ) )
 217
 218 /* Bits stored in the ucFlags field of the stream buffer. */
 219 #define sbFLAGS_IS_MESSAGE_BUFFER          ( ( uint8_t ) 1 ) /* Set if the stream buffer was created as a message buffer, in which case it holds discrete messages rather than a stream. */
 220 #define sbFLAGS_IS_STATICALLY_ALLOCATED    ( ( uint8_t ) 2 ) /* Set if the stream buffer was created using statically allocated memory. */
 221
 222 /*-----------------------------------------------------------*/
 223
 224 /* Structure that hold state information on the buffer. */
 225 typedef struct StreamBufferDef_t
 226 {
 227     volatile size_t xTail;                       /* Index to the next item to read within the buffer. */
 228     volatile size_t xHead;                       /* Index to the next item to write within the buffer. */
 229     size_t xLength;                              /* The length of the buffer pointed to by pucBuffer. */
 230     size_t xTriggerLevelBytes;                   /* The number of bytes that must be in the stream buffer before a task that is waiting for data is unblocked. */
 231     volatile TaskHandle_t xTaskWaitingToReceive; /* Holds the handle of a task waiting for data, or NULL if no tasks are waiting. */
 232     volatile TaskHandle_t xTaskWaitingToSend;    /* Holds the handle of a task waiting to send data to a message buffer that is full. */
 233     uint8_t * pucBuffer;                         /* Points to the buffer itself - that is - the RAM that stores the data passed through the buffer. */
 234     uint8_t ucFlags;
 235
 236     #if ( configUSE_TRACE_FACILITY == 1 )
 237         UBaseType_t uxStreamBufferNumber; /* Used for tracing purposes. */
 238     #endif
 239
 240     #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
 241         StreamBufferCallbackFunction_t pxSendCompletedCallback;    /* Optional callback called on send complete. sbSEND_COMPLETED is called if this is NULL. */
 242         StreamBufferCallbackFunction_t pxReceiveCompletedCallback; /* Optional callback called on receive complete.  sbRECEIVE_COMPLETED is called if this is NULL. */
 243     #endif
 244     UBaseType_t uxNotificationIndex;                               /* The index we are using for notification, by default tskDEFAULT_INDEX_TO_NOTIFY. */
 245 } StreamBuffer_t;
 246
 247 /*
 248  * The number of bytes available to be read from the buffer.
 249  */
 250 static size_t prvBytesInBuffer( const StreamBuffer_t * const pxStreamBuffer ) PRIVILEGED_FUNCTION;
 251
 252 /*
 253  * Add xCount bytes from pucData into the pxStreamBuffer's data storage area.
 254  * This function does not update the buffer's xHead pointer, so multiple writes
 255  * may be chained together "atomically". This is useful for Message Buffers where
 256  * the length and data bytes are written in two separate chunks, and we don't want
 257  * the reader to see the buffer as having grown until after all data is copied over.
 258  * This function takes a custom xHead value to indicate where to write to (necessary
 259  * for chaining) and returns the the resulting xHead position.
 260  * To mark the write as complete, manually set the buffer's xHead field with the
 261  * returned xHead from this function.
 262  */
 263 static size_t prvWriteBytesToBuffer( StreamBuffer_t * const pxStreamBuffer,
 264                                      const uint8_t * pucData,
 265                                      size_t xCount,
 266                                      size_t xHead ) PRIVILEGED_FUNCTION;
 267
 268 /*
 269  * If the stream buffer is being used as a message buffer, then reads an entire
 270  * message out of the buffer.  If the stream buffer is being used as a stream
 271  * buffer then read as many bytes as possible from the buffer.
 272  * prvReadBytesFromBuffer() is called to actually extract the bytes from the
 273  * buffer's data storage area.
 274  */
 275 static size_t prvReadMessageFromBuffer( StreamBuffer_t * pxStreamBuffer,
 276                                         void * pvRxData,
 277                                         size_t xBufferLengthBytes,
 278                                         size_t xBytesAvailable ) PRIVILEGED_FUNCTION;
 279
 280 /*
 281  * If the stream buffer is being used as a message buffer, then writes an entire
 282  * message to the buffer.  If the stream buffer is being used as a stream
 283  * buffer then write as many bytes as possible to the buffer.
 284  * prvWriteBytestoBuffer() is called to actually send the bytes to the buffer's
 285  * data storage area.
 286  */
 287 static size_t prvWriteMessageToBuffer( StreamBuffer_t * const pxStreamBuffer,
 288                                        const void * pvTxData,
 289                                        size_t xDataLengthBytes,
 290                                        size_t xSpace,
 291                                        size_t xRequiredSpace ) PRIVILEGED_FUNCTION;
 292
 293 /*
 294  * Copies xCount bytes from the pxStreamBuffer's data storage area to pucData.
 295  * This function does not update the buffer's xTail pointer, so multiple reads
 296  * may be chained together "atomically". This is useful for Message Buffers where
 297  * the length and data bytes are read in two separate chunks, and we don't want
 298  * the writer to see the buffer as having more free space until after all data is
 299  * copied over, especially if we have to abort the read due to insufficient receiving space.
 300  * This function takes a custom xTail value to indicate where to read from (necessary
 301  * for chaining) and returns the the resulting xTail position.
 302  * To mark the read as complete, manually set the buffer's xTail field with the
 303  * returned xTail from this function.
 304  */
 305 static size_t prvReadBytesFromBuffer( StreamBuffer_t * pxStreamBuffer,
 306                                       uint8_t * pucData,
 307                                       size_t xCount,
 308                                       size_t xTail ) PRIVILEGED_FUNCTION;
 309
 310 /*
 311  * Called by both pxStreamBufferCreate() and pxStreamBufferCreateStatic() to
 312  * initialise the members of the newly created stream buffer structure.
 313  */
 314 static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
 315                                           uint8_t * const pucBuffer,
 316                                           size_t xBufferSizeBytes,
 317                                           size_t xTriggerLevelBytes,
 318                                           uint8_t ucFlags,
 319                                           StreamBufferCallbackFunction_t pxSendCompletedCallback,
 320                                           StreamBufferCallbackFunction_t pxReceiveCompletedCallback ) PRIVILEGED_FUNCTION;
 321
 322 /*-----------------------------------------------------------*/
 323 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 324     StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
 325                                                      size_t xTriggerLevelBytes,
 326                                                      BaseType_t xIsMessageBuffer,
 327                                                      StreamBufferCallbackFunction_t pxSendCompletedCallback,
 328                                                      StreamBufferCallbackFunction_t pxReceiveCompletedCallback )
 329     {
 330         void * pvAllocatedMemory;
 331         uint8_t ucFlags;
 332
 333         traceENTER_xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback );
 334
 335         /* In case the stream buffer is going to be used as a message buffer
 336          * (that is, it will hold discrete messages with a little meta data that
 337          * says how big the next message is) check the buffer will be large enough
 338          * to hold at least one message. */
 339         if( xIsMessageBuffer == pdTRUE )
 340         {
 341             /* Is a message buffer but not statically allocated. */
 342             ucFlags = sbFLAGS_IS_MESSAGE_BUFFER;
 343             configASSERT( xBufferSizeBytes > sbBYTES_TO_STORE_MESSAGE_LENGTH );
 344         }
 345         else
 346         {
 347             /* Not a message buffer and not statically allocated. */
 348             ucFlags = 0;
 349             configASSERT( xBufferSizeBytes > 0 );
 350         }
 351
 352         configASSERT( xTriggerLevelBytes <= xBufferSizeBytes );
 353
 354         /* A trigger level of 0 would cause a waiting task to unblock even when
 355          * the buffer was empty. */
 356         if( xTriggerLevelBytes == ( size_t ) 0 )
 357         {
 358             xTriggerLevelBytes = ( size_t ) 1;
 359         }
 360
 361         /* A stream buffer requires a StreamBuffer_t structure and a buffer.
 362          * Both are allocated in a single call to pvPortMalloc().  The
 363          * StreamBuffer_t structure is placed at the start of the allocated memory
 364          * and the buffer follows immediately after.  The requested size is
 365          * incremented so the free space is returned as the user would expect -
 366          * this is a quirk of the implementation that means otherwise the free
 367          * space would be reported as one byte smaller than would be logically
 368          * expected. */
 369         if( xBufferSizeBytes < ( xBufferSizeBytes + 1U + sizeof( StreamBuffer_t ) ) )
 370         {
 371             xBufferSizeBytes++;
 372             pvAllocatedMemory = pvPortMalloc( xBufferSizeBytes + sizeof( StreamBuffer_t ) );
 373         }
 374         else
 375         {
 376             pvAllocatedMemory = NULL;
 377         }
 378
 379         if( pvAllocatedMemory != NULL )
 380         {
 381             /* MISRA Ref 11.5.1 [Malloc memory assignment] */
 382             /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-115 */
 383             /* coverity[misra_c_2012_rule_11_5_violation] */
 384             prvInitialiseNewStreamBuffer( ( StreamBuffer_t * ) pvAllocatedMemory,                         /* Structure at the start of the allocated memory. */
 385                                                                                                           /* MISRA Ref 11.5.1 [Malloc memory assignment] */
 386                                                                                                           /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-115 */
 387                                                                                                           /* coverity[misra_c_2012_rule_11_5_violation] */
 388                                           ( ( uint8_t * ) pvAllocatedMemory ) + sizeof( StreamBuffer_t ), /* Storage area follows. */
 389                                           xBufferSizeBytes,
 390                                           xTriggerLevelBytes,
 391                                           ucFlags,
 392                                           pxSendCompletedCallback,
 393                                           pxReceiveCompletedCallback );
 394
 395             traceSTREAM_BUFFER_CREATE( ( ( StreamBuffer_t * ) pvAllocatedMemory ), xIsMessageBuffer );
 396         }
 397         else
 398         {
 399             traceSTREAM_BUFFER_CREATE_FAILED( xIsMessageBuffer );
 400         }
 401
 402         traceRETURN_xStreamBufferGenericCreate( pvAllocatedMemory );
 403
 404         /* MISRA Ref 11.5.1 [Malloc memory assignment] */
 405         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-115 */
 406         /* coverity[misra_c_2012_rule_11_5_violation] */
 407         return ( StreamBufferHandle_t ) pvAllocatedMemory;
 408     }
 409 #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 410 /*-----------------------------------------------------------*/
 411
 412 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 413
 414     StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
 415                                                            size_t xTriggerLevelBytes,
 416                                                            BaseType_t xIsMessageBuffer,
 417                                                            uint8_t * const pucStreamBufferStorageArea,
 418                                                            StaticStreamBuffer_t * const pxStaticStreamBuffer,
 419                                                            StreamBufferCallbackFunction_t pxSendCompletedCallback,
 420                                                            StreamBufferCallbackFunction_t pxReceiveCompletedCallback )
 421     {
 422         /* MISRA Ref 11.3.1 [Misaligned access] */
 423         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-113 */
 424         /* coverity[misra_c_2012_rule_11_3_violation] */
 425         StreamBuffer_t * const pxStreamBuffer = ( StreamBuffer_t * ) pxStaticStreamBuffer;
 426         StreamBufferHandle_t xReturn;
 427         uint8_t ucFlags;
 428
 429         traceENTER_xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, xIsMessageBuffer, pucStreamBufferStorageArea, pxStaticStreamBuffer, pxSendCompletedCallback, pxReceiveCompletedCallback );
 430
 431         configASSERT( pucStreamBufferStorageArea );
 432         configASSERT( pxStaticStreamBuffer );
 433         configASSERT( xTriggerLevelBytes <= xBufferSizeBytes );
 434
 435         /* A trigger level of 0 would cause a waiting task to unblock even when
 436          * the buffer was empty. */
 437         if( xTriggerLevelBytes == ( size_t ) 0 )
 438         {
 439             xTriggerLevelBytes = ( size_t ) 1;
 440         }
 441
 442         /* In case the stream buffer is going to be used as a message buffer
 443          * (that is, it will hold discrete messages with a little meta data that
 444          * says how big the next message is) check the buffer will be large enough
 445          * to hold at least one message. */
 446
 447         if( xIsMessageBuffer != pdFALSE )
 448         {
 449             /* Statically allocated message buffer. */
 450             ucFlags = sbFLAGS_IS_MESSAGE_BUFFER | sbFLAGS_IS_STATICALLY_ALLOCATED;
 451             configASSERT( xBufferSizeBytes > sbBYTES_TO_STORE_MESSAGE_LENGTH );
 452         }
 453         else
 454         {
 455             /* Statically allocated stream buffer. */
 456             ucFlags = sbFLAGS_IS_STATICALLY_ALLOCATED;
 457         }
 458
 459         #if ( configASSERT_DEFINED == 1 )
 460         {
 461             /* Sanity check that the size of the structure used to declare a
 462              * variable of type StaticStreamBuffer_t equals the size of the real
 463              * message buffer structure. */
 464             volatile size_t xSize = sizeof( StaticStreamBuffer_t );
 465             configASSERT( xSize == sizeof( StreamBuffer_t ) );
 466         }
 467         #endif /* configASSERT_DEFINED */
 468
 469         if( ( pucStreamBufferStorageArea != NULL ) && ( pxStaticStreamBuffer != NULL ) )
 470         {
 471             prvInitialiseNewStreamBuffer( pxStreamBuffer,
 472                                           pucStreamBufferStorageArea,
 473                                           xBufferSizeBytes,
 474                                           xTriggerLevelBytes,
 475                                           ucFlags,
 476                                           pxSendCompletedCallback,
 477                                           pxReceiveCompletedCallback );
 478
 479             /* Remember this was statically allocated in case it is ever deleted
 480              * again. */
 481             pxStreamBuffer->ucFlags |= sbFLAGS_IS_STATICALLY_ALLOCATED;
 482
 483             traceSTREAM_BUFFER_CREATE( pxStreamBuffer, xIsMessageBuffer );
 484
 485             /* MISRA Ref 11.3.1 [Misaligned access] */
 486             /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-113 */
 487             /* coverity[misra_c_2012_rule_11_3_violation] */
 488             xReturn = ( StreamBufferHandle_t ) pxStaticStreamBuffer;
 489         }
 490         else
 491         {
 492             xReturn = NULL;
 493             traceSTREAM_BUFFER_CREATE_STATIC_FAILED( xReturn, xIsMessageBuffer );
 494         }
 495
 496         traceRETURN_xStreamBufferGenericCreateStatic( xReturn );
 497
 498         return xReturn;
 499     }
 500 #endif /* ( configSUPPORT_STATIC_ALLOCATION == 1 ) */
 501 /*-----------------------------------------------------------*/
 502
 503 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 504     BaseType_t xStreamBufferGetStaticBuffers( StreamBufferHandle_t xStreamBuffer,
 505                                               uint8_t ** ppucStreamBufferStorageArea,
 506                                               StaticStreamBuffer_t ** ppxStaticStreamBuffer )
 507     {
 508         BaseType_t xReturn;
 509         StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 510
 511         traceENTER_xStreamBufferGetStaticBuffers( xStreamBuffer, ppucStreamBufferStorageArea, ppxStaticStreamBuffer );
 512
 513         configASSERT( pxStreamBuffer );
 514         configASSERT( ppucStreamBufferStorageArea );
 515         configASSERT( ppxStaticStreamBuffer );
 516
 517         if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_STATICALLY_ALLOCATED ) != ( uint8_t ) 0 )
 518         {
 519             *ppucStreamBufferStorageArea = pxStreamBuffer->pucBuffer;
 520             /* MISRA Ref 11.3.1 [Misaligned access] */
 521             /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-113 */
 522             /* coverity[misra_c_2012_rule_11_3_violation] */
 523             *ppxStaticStreamBuffer = ( StaticStreamBuffer_t * ) pxStreamBuffer;
 524             xReturn = pdTRUE;
 525         }
 526         else
 527         {
 528             xReturn = pdFALSE;
 529         }
 530
 531         traceRETURN_xStreamBufferGetStaticBuffers( xReturn );
 532
 533         return xReturn;
 534     }
 535 #endif /* configSUPPORT_STATIC_ALLOCATION */
 536 /*-----------------------------------------------------------*/
 537
 538 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer )
 539 {
 540     StreamBuffer_t * pxStreamBuffer = xStreamBuffer;
 541
 542     traceENTER_vStreamBufferDelete( xStreamBuffer );
 543
 544     configASSERT( pxStreamBuffer );
 545
 546     traceSTREAM_BUFFER_DELETE( xStreamBuffer );
 547
 548     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_STATICALLY_ALLOCATED ) == ( uint8_t ) pdFALSE )
 549     {
 550         #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 551         {
 552             /* Both the structure and the buffer were allocated using a single call
 553             * to pvPortMalloc(), hence only one call to vPortFree() is required. */
 554             vPortFree( ( void * ) pxStreamBuffer );
 555         }
 556         #else
 557         {
 558             /* Should not be possible to get here, ucFlags must be corrupt.
 559              * Force an assert. */
 560             configASSERT( xStreamBuffer == ( StreamBufferHandle_t ) ~0 );
 561         }
 562         #endif
 563     }
 564     else
 565     {
 566         /* The structure and buffer were not allocated dynamically and cannot be
 567          * freed - just scrub the structure so future use will assert. */
 568         ( void ) memset( pxStreamBuffer, 0x00, sizeof( StreamBuffer_t ) );
 569     }
 570
 571     traceRETURN_vStreamBufferDelete();
 572 }
 573 /*-----------------------------------------------------------*/
 574
 575 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer )
 576 {
 577     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 578     BaseType_t xReturn = pdFAIL;
 579     StreamBufferCallbackFunction_t pxSendCallback = NULL, pxReceiveCallback = NULL;
 580
 581     #if ( configUSE_TRACE_FACILITY == 1 )
 582         UBaseType_t uxStreamBufferNumber;
 583     #endif
 584
 585     traceENTER_xStreamBufferReset( xStreamBuffer );
 586
 587     configASSERT( pxStreamBuffer );
 588
 589     #if ( configUSE_TRACE_FACILITY == 1 )
 590     {
 591         /* Store the stream buffer number so it can be restored after the
 592          * reset. */
 593         uxStreamBufferNumber = pxStreamBuffer->uxStreamBufferNumber;
 594     }
 595     #endif
 596
 597     /* Can only reset a message buffer if there are no tasks blocked on it. */
 598     taskENTER_CRITICAL();
 599     {
 600         if( ( pxStreamBuffer->xTaskWaitingToReceive == NULL ) && ( pxStreamBuffer->xTaskWaitingToSend == NULL ) )
 601         {
 602             #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
 603             {
 604                 pxSendCallback = pxStreamBuffer->pxSendCompletedCallback;
 605                 pxReceiveCallback = pxStreamBuffer->pxReceiveCompletedCallback;
 606             }
 607             #endif
 608
 609             prvInitialiseNewStreamBuffer( pxStreamBuffer,
 610                                           pxStreamBuffer->pucBuffer,
 611                                           pxStreamBuffer->xLength,
 612                                           pxStreamBuffer->xTriggerLevelBytes,
 613                                           pxStreamBuffer->ucFlags,
 614                                           pxSendCallback,
 615                                           pxReceiveCallback );
 616
 617             #if ( configUSE_TRACE_FACILITY == 1 )
 618             {
 619                 pxStreamBuffer->uxStreamBufferNumber = uxStreamBufferNumber;
 620             }
 621             #endif
 622
 623             traceSTREAM_BUFFER_RESET( xStreamBuffer );
 624
 625             xReturn = pdPASS;
 626         }
 627     }
 628     taskEXIT_CRITICAL();
 629
 630     traceRETURN_xStreamBufferReset( xReturn );
 631
 632     return xReturn;
 633 }
 634 /*-----------------------------------------------------------*/
 635
 636 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
 637                                          size_t xTriggerLevel )
 638 {
 639     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 640     BaseType_t xReturn;
 641
 642     traceENTER_xStreamBufferSetTriggerLevel( xStreamBuffer, xTriggerLevel );
 643
 644     configASSERT( pxStreamBuffer );
 645
 646     /* It is not valid for the trigger level to be 0. */
 647     if( xTriggerLevel == ( size_t ) 0 )
 648     {
 649         xTriggerLevel = ( size_t ) 1;
 650     }
 651
 652     /* The trigger level is the number of bytes that must be in the stream
 653      * buffer before a task that is waiting for data is unblocked. */
 654     if( xTriggerLevel < pxStreamBuffer->xLength )
 655     {
 656         pxStreamBuffer->xTriggerLevelBytes = xTriggerLevel;
 657         xReturn = pdPASS;
 658     }
 659     else
 660     {
 661         xReturn = pdFALSE;
 662     }
 663
 664     traceRETURN_xStreamBufferSetTriggerLevel( xReturn );
 665
 666     return xReturn;
 667 }
 668 /*-----------------------------------------------------------*/
 669
 670 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer )
 671 {
 672     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 673     size_t xSpace;
 674     size_t xOriginalTail;
 675
 676     traceENTER_xStreamBufferSpacesAvailable( xStreamBuffer );
 677
 678     configASSERT( pxStreamBuffer );
 679
 680     /* The code below reads xTail and then xHead.  This is safe if the stream
 681      * buffer is updated once between the two reads - but not if the stream buffer
 682      * is updated more than once between the two reads - hence the loop. */
 683     do
 684     {
 685         xOriginalTail = pxStreamBuffer->xTail;
 686         xSpace = pxStreamBuffer->xLength + pxStreamBuffer->xTail;
 687         xSpace -= pxStreamBuffer->xHead;
 688     } while( xOriginalTail != pxStreamBuffer->xTail );
 689
 690     xSpace -= ( size_t ) 1;
 691
 692     if( xSpace >= pxStreamBuffer->xLength )
 693     {
 694         xSpace -= pxStreamBuffer->xLength;
 695     }
 696     else
 697     {
 698         mtCOVERAGE_TEST_MARKER();
 699     }
 700
 701     traceRETURN_xStreamBufferSpacesAvailable( xSpace );
 702
 703     return xSpace;
 704 }
 705 /*-----------------------------------------------------------*/
 706
 707 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer )
 708 {
 709     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 710     size_t xReturn;
 711
 712     traceENTER_xStreamBufferBytesAvailable( xStreamBuffer );
 713
 714     configASSERT( pxStreamBuffer );
 715
 716     xReturn = prvBytesInBuffer( pxStreamBuffer );
 717
 718     traceRETURN_xStreamBufferBytesAvailable( xReturn );
 719
 720     return xReturn;
 721 }
 722 /*-----------------------------------------------------------*/
 723
 724 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
 725                           const void * pvTxData,
 726                           size_t xDataLengthBytes,
 727                           TickType_t xTicksToWait )
 728 {
 729     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 730     size_t xReturn, xSpace = 0;
 731     size_t xRequiredSpace = xDataLengthBytes;
 732     TimeOut_t xTimeOut;
 733     size_t xMaxReportedSpace = 0;
 734
 735     traceENTER_xStreamBufferSend( xStreamBuffer, pvTxData, xDataLengthBytes, xTicksToWait );
 736
 737     configASSERT( pvTxData );
 738     configASSERT( pxStreamBuffer );
 739
 740     /* The maximum amount of space a stream buffer will ever report is its length
 741      * minus 1. */
 742     xMaxReportedSpace = pxStreamBuffer->xLength - ( size_t ) 1;
 743
 744     /* This send function is used to write to both message buffers and stream
 745      * buffers.  If this is a message buffer then the space needed must be
 746      * increased by the amount of bytes needed to store the length of the
 747      * message. */
 748     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
 749     {
 750         xRequiredSpace += sbBYTES_TO_STORE_MESSAGE_LENGTH;
 751
 752         /* Overflow? */
 753         configASSERT( xRequiredSpace > xDataLengthBytes );
 754
 755         /* If this is a message buffer then it must be possible to write the
 756          * whole message. */
 757         if( xRequiredSpace > xMaxReportedSpace )
 758         {
 759             /* The message would not fit even if the entire buffer was empty,
 760              * so don't wait for space. */
 761             xTicksToWait = ( TickType_t ) 0;
 762         }
 763         else
 764         {
 765             mtCOVERAGE_TEST_MARKER();
 766         }
 767     }
 768     else
 769     {
 770         /* If this is a stream buffer then it is acceptable to write only part
 771          * of the message to the buffer.  Cap the length to the total length of
 772          * the buffer. */
 773         if( xRequiredSpace > xMaxReportedSpace )
 774         {
 775             xRequiredSpace = xMaxReportedSpace;
 776         }
 777         else
 778         {
 779             mtCOVERAGE_TEST_MARKER();
 780         }
 781     }
 782
 783     if( xTicksToWait != ( TickType_t ) 0 )
 784     {
 785         vTaskSetTimeOutState( &xTimeOut );
 786
 787         do
 788         {
 789             /* Wait until the required number of bytes are free in the message
 790              * buffer. */
 791             taskENTER_CRITICAL();
 792             {
 793                 xSpace = xStreamBufferSpacesAvailable( pxStreamBuffer );
 794
 795                 if( xSpace < xRequiredSpace )
 796                 {
 797                     /* Clear notification state as going to wait for space. */
 798                     ( void ) xTaskNotifyStateClearIndexed( NULL, pxStreamBuffer->uxNotificationIndex );
 799
 800                     /* Should only be one writer. */
 801                     configASSERT( pxStreamBuffer->xTaskWaitingToSend == NULL );
 802                     pxStreamBuffer->xTaskWaitingToSend = xTaskGetCurrentTaskHandle();
 803                 }
 804                 else
 805                 {
 806                     taskEXIT_CRITICAL();
 807                     break;
 808                 }
 809             }
 810             taskEXIT_CRITICAL();
 811
 812             traceBLOCKING_ON_STREAM_BUFFER_SEND( xStreamBuffer );
 813             ( void ) xTaskNotifyWaitIndexed( pxStreamBuffer->uxNotificationIndex, ( uint32_t ) 0, ( uint32_t ) 0, NULL, xTicksToWait );
 814             pxStreamBuffer->xTaskWaitingToSend = NULL;
 815         } while( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE );
 816     }
 817     else
 818     {
 819         mtCOVERAGE_TEST_MARKER();
 820     }
 821
 822     if( xSpace == ( size_t ) 0 )
 823     {
 824         xSpace = xStreamBufferSpacesAvailable( pxStreamBuffer );
 825     }
 826     else
 827     {
 828         mtCOVERAGE_TEST_MARKER();
 829     }
 830
 831     xReturn = prvWriteMessageToBuffer( pxStreamBuffer, pvTxData, xDataLengthBytes, xSpace, xRequiredSpace );
 832
 833     if( xReturn > ( size_t ) 0 )
 834     {
 835         traceSTREAM_BUFFER_SEND( xStreamBuffer, xReturn );
 836
 837         /* Was a task waiting for the data? */
 838         if( prvBytesInBuffer( pxStreamBuffer ) >= pxStreamBuffer->xTriggerLevelBytes )
 839         {
 840             prvSEND_COMPLETED( pxStreamBuffer );
 841         }
 842         else
 843         {
 844             mtCOVERAGE_TEST_MARKER();
 845         }
 846     }
 847     else
 848     {
 849         mtCOVERAGE_TEST_MARKER();
 850         traceSTREAM_BUFFER_SEND_FAILED( xStreamBuffer );
 851     }
 852
 853     traceRETURN_xStreamBufferSend( xReturn );
 854
 855     return xReturn;
 856 }
 857 /*-----------------------------------------------------------*/
 858
 859 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
 860                                  const void * pvTxData,
 861                                  size_t xDataLengthBytes,
 862                                  BaseType_t * const pxHigherPriorityTaskWoken )
 863 {
 864     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 865     size_t xReturn, xSpace;
 866     size_t xRequiredSpace = xDataLengthBytes;
 867
 868     traceENTER_xStreamBufferSendFromISR( xStreamBuffer, pvTxData, xDataLengthBytes, pxHigherPriorityTaskWoken );
 869
 870     configASSERT( pvTxData );
 871     configASSERT( pxStreamBuffer );
 872
 873     /* This send function is used to write to both message buffers and stream
 874      * buffers.  If this is a message buffer then the space needed must be
 875      * increased by the amount of bytes needed to store the length of the
 876      * message. */
 877     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
 878     {
 879         xRequiredSpace += sbBYTES_TO_STORE_MESSAGE_LENGTH;
 880     }
 881     else
 882     {
 883         mtCOVERAGE_TEST_MARKER();
 884     }
 885
 886     xSpace = xStreamBufferSpacesAvailable( pxStreamBuffer );
 887     xReturn = prvWriteMessageToBuffer( pxStreamBuffer, pvTxData, xDataLengthBytes, xSpace, xRequiredSpace );
 888
 889     if( xReturn > ( size_t ) 0 )
 890     {
 891         /* Was a task waiting for the data? */
 892         if( prvBytesInBuffer( pxStreamBuffer ) >= pxStreamBuffer->xTriggerLevelBytes )
 893         {
 894             prvSEND_COMPLETE_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken );
 895         }
 896         else
 897         {
 898             mtCOVERAGE_TEST_MARKER();
 899         }
 900     }
 901     else
 902     {
 903         mtCOVERAGE_TEST_MARKER();
 904     }
 905
 906     traceSTREAM_BUFFER_SEND_FROM_ISR( xStreamBuffer, xReturn );
 907     traceRETURN_xStreamBufferSendFromISR( xReturn );
 908
 909     return xReturn;
 910 }
 911 /*-----------------------------------------------------------*/
 912
 913 static size_t prvWriteMessageToBuffer( StreamBuffer_t * const pxStreamBuffer,
 914                                        const void * pvTxData,
 915                                        size_t xDataLengthBytes,
 916                                        size_t xSpace,
 917                                        size_t xRequiredSpace )
 918 {
 919     size_t xNextHead = pxStreamBuffer->xHead;
 920     configMESSAGE_BUFFER_LENGTH_TYPE xMessageLength;
 921
 922     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
 923     {
 924         /* This is a message buffer, as opposed to a stream buffer. */
 925
 926         /* Convert xDataLengthBytes to the message length type. */
 927         xMessageLength = ( configMESSAGE_BUFFER_LENGTH_TYPE ) xDataLengthBytes;
 928
 929         /* Ensure the data length given fits within configMESSAGE_BUFFER_LENGTH_TYPE. */
 930         configASSERT( ( size_t ) xMessageLength == xDataLengthBytes );
 931
 932         if( xSpace >= xRequiredSpace )
 933         {
 934             /* There is enough space to write both the message length and the message
 935              * itself into the buffer.  Start by writing the length of the data, the data
 936              * itself will be written later in this function. */
 937             xNextHead = prvWriteBytesToBuffer( pxStreamBuffer, ( const uint8_t * ) &( xMessageLength ), sbBYTES_TO_STORE_MESSAGE_LENGTH, xNextHead );
 938         }
 939         else
 940         {
 941             /* Not enough space, so do not write data to the buffer. */
 942             xDataLengthBytes = 0;
 943         }
 944     }
 945     else
 946     {
 947         /* This is a stream buffer, as opposed to a message buffer, so writing a
 948          * stream of bytes rather than discrete messages.  Plan to write as many
 949          * bytes as possible. */
 950         xDataLengthBytes = configMIN( xDataLengthBytes, xSpace );
 951     }
 952
 953     if( xDataLengthBytes != ( size_t ) 0 )
 954     {
 955         /* Write the data to the buffer. */
 956         /* MISRA Ref 11.5.5 [Void pointer assignment] */
 957         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-115 */
 958         /* coverity[misra_c_2012_rule_11_5_violation] */
 959         pxStreamBuffer->xHead = prvWriteBytesToBuffer( pxStreamBuffer, ( const uint8_t * ) pvTxData, xDataLengthBytes, xNextHead );
 960     }
 961
 962     return xDataLengthBytes;
 963 }
 964 /*-----------------------------------------------------------*/
 965
 966 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
 967                              void * pvRxData,
 968                              size_t xBufferLengthBytes,
 969                              TickType_t xTicksToWait )
 970 {
 971     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
 972     size_t xReceivedLength = 0, xBytesAvailable, xBytesToStoreMessageLength;
 973
 974     traceENTER_xStreamBufferReceive( xStreamBuffer, pvRxData, xBufferLengthBytes, xTicksToWait );
 975
 976     configASSERT( pvRxData );
 977     configASSERT( pxStreamBuffer );
 978
 979     /* This receive function is used by both message buffers, which store
 980      * discrete messages, and stream buffers, which store a continuous stream of
 981      * bytes.  Discrete messages include an additional
 982      * sbBYTES_TO_STORE_MESSAGE_LENGTH bytes that hold the length of the
 983      * message. */
 984     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
 985     {
 986         xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH;
 987     }
 988     else
 989     {
 990         xBytesToStoreMessageLength = 0;
 991     }
 992
 993     if( xTicksToWait != ( TickType_t ) 0 )
 994     {
 995         /* Checking if there is data and clearing the notification state must be
 996          * performed atomically. */
 997         taskENTER_CRITICAL();
 998         {
 999             xBytesAvailable = prvBytesInBuffer( pxStreamBuffer );
1000
1001             /* If this function was invoked by a message buffer read then
1002              * xBytesToStoreMessageLength holds the number of bytes used to hold
1003              * the length of the next discrete message.  If this function was
1004              * invoked by a stream buffer read then xBytesToStoreMessageLength will
1005              * be 0. */
1006             if( xBytesAvailable <= xBytesToStoreMessageLength )
1007             {
1008                 /* Clear notification state as going to wait for data. */
1009                 ( void ) xTaskNotifyStateClearIndexed( NULL, pxStreamBuffer->uxNotificationIndex );
1010
1011                 /* Should only be one reader. */
1012                 configASSERT( pxStreamBuffer->xTaskWaitingToReceive == NULL );
1013                 pxStreamBuffer->xTaskWaitingToReceive = xTaskGetCurrentTaskHandle();
1014             }
1015             else
1016             {
1017                 mtCOVERAGE_TEST_MARKER();
1018             }
1019         }
1020         taskEXIT_CRITICAL();
1021
1022         if( xBytesAvailable <= xBytesToStoreMessageLength )
1023         {
1024             /* Wait for data to be available. */
1025             traceBLOCKING_ON_STREAM_BUFFER_RECEIVE( xStreamBuffer );
1026             ( void ) xTaskNotifyWaitIndexed( pxStreamBuffer->uxNotificationIndex, ( uint32_t ) 0, ( uint32_t ) 0, NULL, xTicksToWait );
1027             pxStreamBuffer->xTaskWaitingToReceive = NULL;
1028
1029             /* Recheck the data available after blocking. */
1030             xBytesAvailable = prvBytesInBuffer( pxStreamBuffer );
1031         }
1032         else
1033         {
1034             mtCOVERAGE_TEST_MARKER();
1035         }
1036     }
1037     else
1038     {
1039         xBytesAvailable = prvBytesInBuffer( pxStreamBuffer );
1040     }
1041
1042     /* Whether receiving a discrete message (where xBytesToStoreMessageLength
1043      * holds the number of bytes used to store the message length) or a stream of
1044      * bytes (where xBytesToStoreMessageLength is zero), the number of bytes
1045      * available must be greater than xBytesToStoreMessageLength to be able to
1046      * read bytes from the buffer. */
1047     if( xBytesAvailable > xBytesToStoreMessageLength )
1048     {
1049         xReceivedLength = prvReadMessageFromBuffer( pxStreamBuffer, pvRxData, xBufferLengthBytes, xBytesAvailable );
1050
1051         /* Was a task waiting for space in the buffer? */
1052         if( xReceivedLength != ( size_t ) 0 )
1053         {
1054             traceSTREAM_BUFFER_RECEIVE( xStreamBuffer, xReceivedLength );
1055             prvRECEIVE_COMPLETED( xStreamBuffer );
1056         }
1057         else
1058         {
1059             mtCOVERAGE_TEST_MARKER();
1060         }
1061     }
1062     else
1063     {
1064         traceSTREAM_BUFFER_RECEIVE_FAILED( xStreamBuffer );
1065         mtCOVERAGE_TEST_MARKER();
1066     }
1067
1068     traceRETURN_xStreamBufferReceive( xReceivedLength );
1069
1070     return xReceivedLength;
1071 }
1072 /*-----------------------------------------------------------*/
1073
1074 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer )
1075 {
1076     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1077     size_t xReturn, xBytesAvailable;
1078     configMESSAGE_BUFFER_LENGTH_TYPE xTempReturn;
1079
1080     traceENTER_xStreamBufferNextMessageLengthBytes( xStreamBuffer );
1081
1082     configASSERT( pxStreamBuffer );
1083
1084     /* Ensure the stream buffer is being used as a message buffer. */
1085     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
1086     {
1087         xBytesAvailable = prvBytesInBuffer( pxStreamBuffer );
1088
1089         if( xBytesAvailable > sbBYTES_TO_STORE_MESSAGE_LENGTH )
1090         {
1091             /* The number of bytes available is greater than the number of bytes
1092              * required to hold the length of the next message, so another message
1093              * is available. */
1094             ( void ) prvReadBytesFromBuffer( pxStreamBuffer, ( uint8_t * ) &xTempReturn, sbBYTES_TO_STORE_MESSAGE_LENGTH, pxStreamBuffer->xTail );
1095             xReturn = ( size_t ) xTempReturn;
1096         }
1097         else
1098         {
1099             /* The minimum amount of bytes in a message buffer is
1100              * ( sbBYTES_TO_STORE_MESSAGE_LENGTH + 1 ), so if xBytesAvailable is
1101              * less than sbBYTES_TO_STORE_MESSAGE_LENGTH the only other valid
1102              * value is 0. */
1103             configASSERT( xBytesAvailable == 0 );
1104             xReturn = 0;
1105         }
1106     }
1107     else
1108     {
1109         xReturn = 0;
1110     }
1111
1112     traceRETURN_xStreamBufferNextMessageLengthBytes( xReturn );
1113
1114     return xReturn;
1115 }
1116 /*-----------------------------------------------------------*/
1117
1118 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
1119                                     void * pvRxData,
1120                                     size_t xBufferLengthBytes,
1121                                     BaseType_t * const pxHigherPriorityTaskWoken )
1122 {
1123     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1124     size_t xReceivedLength = 0, xBytesAvailable, xBytesToStoreMessageLength;
1125
1126     traceENTER_xStreamBufferReceiveFromISR( xStreamBuffer, pvRxData, xBufferLengthBytes, pxHigherPriorityTaskWoken );
1127
1128     configASSERT( pvRxData );
1129     configASSERT( pxStreamBuffer );
1130
1131     /* This receive function is used by both message buffers, which store
1132      * discrete messages, and stream buffers, which store a continuous stream of
1133      * bytes.  Discrete messages include an additional
1134      * sbBYTES_TO_STORE_MESSAGE_LENGTH bytes that hold the length of the
1135      * message. */
1136     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
1137     {
1138         xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH;
1139     }
1140     else
1141     {
1142         xBytesToStoreMessageLength = 0;
1143     }
1144
1145     xBytesAvailable = prvBytesInBuffer( pxStreamBuffer );
1146
1147     /* Whether receiving a discrete message (where xBytesToStoreMessageLength
1148      * holds the number of bytes used to store the message length) or a stream of
1149      * bytes (where xBytesToStoreMessageLength is zero), the number of bytes
1150      * available must be greater than xBytesToStoreMessageLength to be able to
1151      * read bytes from the buffer. */
1152     if( xBytesAvailable > xBytesToStoreMessageLength )
1153     {
1154         xReceivedLength = prvReadMessageFromBuffer( pxStreamBuffer, pvRxData, xBufferLengthBytes, xBytesAvailable );
1155
1156         /* Was a task waiting for space in the buffer? */
1157         if( xReceivedLength != ( size_t ) 0 )
1158         {
1159             prvRECEIVE_COMPLETED_FROM_ISR( pxStreamBuffer, pxHigherPriorityTaskWoken );
1160         }
1161         else
1162         {
1163             mtCOVERAGE_TEST_MARKER();
1164         }
1165     }
1166     else
1167     {
1168         mtCOVERAGE_TEST_MARKER();
1169     }
1170
1171     traceSTREAM_BUFFER_RECEIVE_FROM_ISR( xStreamBuffer, xReceivedLength );
1172     traceRETURN_xStreamBufferReceiveFromISR( xReceivedLength );
1173
1174     return xReceivedLength;
1175 }
1176 /*-----------------------------------------------------------*/
1177
1178 static size_t prvReadMessageFromBuffer( StreamBuffer_t * pxStreamBuffer,
1179                                         void * pvRxData,
1180                                         size_t xBufferLengthBytes,
1181                                         size_t xBytesAvailable )
1182 {
1183     size_t xCount, xNextMessageLength;
1184     configMESSAGE_BUFFER_LENGTH_TYPE xTempNextMessageLength;
1185     size_t xNextTail = pxStreamBuffer->xTail;
1186
1187     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
1188     {
1189         /* A discrete message is being received.  First receive the length
1190          * of the message. */
1191         xNextTail = prvReadBytesFromBuffer( pxStreamBuffer, ( uint8_t * ) &xTempNextMessageLength, sbBYTES_TO_STORE_MESSAGE_LENGTH, xNextTail );
1192         xNextMessageLength = ( size_t ) xTempNextMessageLength;
1193
1194         /* Reduce the number of bytes available by the number of bytes just
1195          * read out. */
1196         xBytesAvailable -= sbBYTES_TO_STORE_MESSAGE_LENGTH;
1197
1198         /* Check there is enough space in the buffer provided by the
1199          * user. */
1200         if( xNextMessageLength > xBufferLengthBytes )
1201         {
1202             /* The user has provided insufficient space to read the message. */
1203             xNextMessageLength = 0;
1204         }
1205         else
1206         {
1207             mtCOVERAGE_TEST_MARKER();
1208         }
1209     }
1210     else
1211     {
1212         /* A stream of bytes is being received (as opposed to a discrete
1213          * message), so read as many bytes as possible. */
1214         xNextMessageLength = xBufferLengthBytes;
1215     }
1216
1217     /* Use the minimum of the wanted bytes and the available bytes. */
1218     xCount = configMIN( xNextMessageLength, xBytesAvailable );
1219
1220     if( xCount != ( size_t ) 0 )
1221     {
1222         /* Read the actual data and update the tail to mark the data as officially consumed. */
1223         /* MISRA Ref 11.5.5 [Void pointer assignment] */
1224         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-115 */
1225         /* coverity[misra_c_2012_rule_11_5_violation] */
1226         pxStreamBuffer->xTail = prvReadBytesFromBuffer( pxStreamBuffer, ( uint8_t * ) pvRxData, xCount, xNextTail );
1227     }
1228
1229     return xCount;
1230 }
1231 /*-----------------------------------------------------------*/
1232
1233 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer )
1234 {
1235     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1236     BaseType_t xReturn;
1237     size_t xTail;
1238
1239     traceENTER_xStreamBufferIsEmpty( xStreamBuffer );
1240
1241     configASSERT( pxStreamBuffer );
1242
1243     /* True if no bytes are available. */
1244     xTail = pxStreamBuffer->xTail;
1245
1246     if( pxStreamBuffer->xHead == xTail )
1247     {
1248         xReturn = pdTRUE;
1249     }
1250     else
1251     {
1252         xReturn = pdFALSE;
1253     }
1254
1255     traceRETURN_xStreamBufferIsEmpty( xReturn );
1256
1257     return xReturn;
1258 }
1259 /*-----------------------------------------------------------*/
1260
1261 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer )
1262 {
1263     BaseType_t xReturn;
1264     size_t xBytesToStoreMessageLength;
1265     const StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1266
1267     traceENTER_xStreamBufferIsFull( xStreamBuffer );
1268
1269     configASSERT( pxStreamBuffer );
1270
1271     /* This generic version of the receive function is used by both message
1272      * buffers, which store discrete messages, and stream buffers, which store a
1273      * continuous stream of bytes.  Discrete messages include an additional
1274      * sbBYTES_TO_STORE_MESSAGE_LENGTH bytes that hold the length of the message. */
1275     if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != ( uint8_t ) 0 )
1276     {
1277         xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH;
1278     }
1279     else
1280     {
1281         xBytesToStoreMessageLength = 0;
1282     }
1283
1284     /* True if the available space equals zero. */
1285     if( xStreamBufferSpacesAvailable( xStreamBuffer ) <= xBytesToStoreMessageLength )
1286     {
1287         xReturn = pdTRUE;
1288     }
1289     else
1290     {
1291         xReturn = pdFALSE;
1292     }
1293
1294     traceRETURN_xStreamBufferIsFull( xReturn );
1295
1296     return xReturn;
1297 }
1298 /*-----------------------------------------------------------*/
1299
1300 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer,
1301                                               BaseType_t * pxHigherPriorityTaskWoken )
1302 {
1303     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1304     BaseType_t xReturn;
1305     UBaseType_t uxSavedInterruptStatus;
1306
1307     traceENTER_xStreamBufferSendCompletedFromISR( xStreamBuffer, pxHigherPriorityTaskWoken );
1308
1309     configASSERT( pxStreamBuffer );
1310
1311     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
1312     {
1313         if( ( pxStreamBuffer )->xTaskWaitingToReceive != NULL )
1314         {
1315             ( void ) xTaskNotifyIndexedFromISR( ( pxStreamBuffer )->xTaskWaitingToReceive,
1316                                                 ( pxStreamBuffer )->uxNotificationIndex,
1317                                                 ( uint32_t ) 0,
1318                                                 eNoAction,
1319                                                 pxHigherPriorityTaskWoken );
1320             ( pxStreamBuffer )->xTaskWaitingToReceive = NULL;
1321             xReturn = pdTRUE;
1322         }
1323         else
1324         {
1325             xReturn = pdFALSE;
1326         }
1327     }
1328     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
1329
1330     traceRETURN_xStreamBufferSendCompletedFromISR( xReturn );
1331
1332     return xReturn;
1333 }
1334 /*-----------------------------------------------------------*/
1335
1336 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer,
1337                                                  BaseType_t * pxHigherPriorityTaskWoken )
1338 {
1339     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1340     BaseType_t xReturn;
1341     UBaseType_t uxSavedInterruptStatus;
1342
1343     traceENTER_xStreamBufferReceiveCompletedFromISR( xStreamBuffer, pxHigherPriorityTaskWoken );
1344
1345     configASSERT( pxStreamBuffer );
1346
1347     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
1348     {
1349         if( ( pxStreamBuffer )->xTaskWaitingToSend != NULL )
1350         {
1351             ( void ) xTaskNotifyIndexedFromISR( ( pxStreamBuffer )->xTaskWaitingToSend,
1352                                                 ( pxStreamBuffer )->uxNotificationIndex,
1353                                                 ( uint32_t ) 0,
1354                                                 eNoAction,
1355                                                 pxHigherPriorityTaskWoken );
1356             ( pxStreamBuffer )->xTaskWaitingToSend = NULL;
1357             xReturn = pdTRUE;
1358         }
1359         else
1360         {
1361             xReturn = pdFALSE;
1362         }
1363     }
1364     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
1365
1366     traceRETURN_xStreamBufferReceiveCompletedFromISR( xReturn );
1367
1368     return xReturn;
1369 }
1370 /*-----------------------------------------------------------*/
1371
1372 static size_t prvWriteBytesToBuffer( StreamBuffer_t * const pxStreamBuffer,
1373                                      const uint8_t * pucData,
1374                                      size_t xCount,
1375                                      size_t xHead )
1376 {
1377     size_t xFirstLength;
1378
1379     configASSERT( xCount > ( size_t ) 0 );
1380
1381     /* Calculate the number of bytes that can be added in the first write -
1382      * which may be less than the total number of bytes that need to be added if
1383      * the buffer will wrap back to the beginning. */
1384     xFirstLength = configMIN( pxStreamBuffer->xLength - xHead, xCount );
1385
1386     /* Write as many bytes as can be written in the first write. */
1387     configASSERT( ( xHead + xFirstLength ) <= pxStreamBuffer->xLength );
1388     ( void ) memcpy( ( void * ) ( &( pxStreamBuffer->pucBuffer[ xHead ] ) ), ( const void * ) pucData, xFirstLength );
1389
1390     /* If the number of bytes written was less than the number that could be
1391      * written in the first write... */
1392     if( xCount > xFirstLength )
1393     {
1394         /* ...then write the remaining bytes to the start of the buffer. */
1395         configASSERT( ( xCount - xFirstLength ) <= pxStreamBuffer->xLength );
1396         ( void ) memcpy( ( void * ) pxStreamBuffer->pucBuffer, ( const void * ) &( pucData[ xFirstLength ] ), xCount - xFirstLength );
1397     }
1398     else
1399     {
1400         mtCOVERAGE_TEST_MARKER();
1401     }
1402
1403     xHead += xCount;
1404
1405     if( xHead >= pxStreamBuffer->xLength )
1406     {
1407         xHead -= pxStreamBuffer->xLength;
1408     }
1409     else
1410     {
1411         mtCOVERAGE_TEST_MARKER();
1412     }
1413
1414     return xHead;
1415 }
1416 /*-----------------------------------------------------------*/
1417
1418 static size_t prvReadBytesFromBuffer( StreamBuffer_t * pxStreamBuffer,
1419                                       uint8_t * pucData,
1420                                       size_t xCount,
1421                                       size_t xTail )
1422 {
1423     size_t xFirstLength;
1424
1425     configASSERT( xCount != ( size_t ) 0 );
1426
1427     /* Calculate the number of bytes that can be read - which may be
1428      * less than the number wanted if the data wraps around to the start of
1429      * the buffer. */
1430     xFirstLength = configMIN( pxStreamBuffer->xLength - xTail, xCount );
1431
1432     /* Obtain the number of bytes it is possible to obtain in the first
1433      * read.  Asserts check bounds of read and write. */
1434     configASSERT( xFirstLength <= xCount );
1435     configASSERT( ( xTail + xFirstLength ) <= pxStreamBuffer->xLength );
1436     ( void ) memcpy( ( void * ) pucData, ( const void * ) &( pxStreamBuffer->pucBuffer[ xTail ] ), xFirstLength );
1437
1438     /* If the total number of wanted bytes is greater than the number
1439      * that could be read in the first read... */
1440     if( xCount > xFirstLength )
1441     {
1442         /* ...then read the remaining bytes from the start of the buffer. */
1443         ( void ) memcpy( ( void * ) &( pucData[ xFirstLength ] ), ( void * ) ( pxStreamBuffer->pucBuffer ), xCount - xFirstLength );
1444     }
1445     else
1446     {
1447         mtCOVERAGE_TEST_MARKER();
1448     }
1449
1450     /* Move the tail pointer to effectively remove the data read from the buffer. */
1451     xTail += xCount;
1452
1453     if( xTail >= pxStreamBuffer->xLength )
1454     {
1455         xTail -= pxStreamBuffer->xLength;
1456     }
1457
1458     return xTail;
1459 }
1460 /*-----------------------------------------------------------*/
1461
1462 static size_t prvBytesInBuffer( const StreamBuffer_t * const pxStreamBuffer )
1463 {
1464 /* Returns the distance between xTail and xHead. */
1465     size_t xCount;
1466
1467     xCount = pxStreamBuffer->xLength + pxStreamBuffer->xHead;
1468     xCount -= pxStreamBuffer->xTail;
1469
1470     if( xCount >= pxStreamBuffer->xLength )
1471     {
1472         xCount -= pxStreamBuffer->xLength;
1473     }
1474     else
1475     {
1476         mtCOVERAGE_TEST_MARKER();
1477     }
1478
1479     return xCount;
1480 }
1481 /*-----------------------------------------------------------*/
1482
1483 static void prvInitialiseNewStreamBuffer( StreamBuffer_t * const pxStreamBuffer,
1484                                           uint8_t * const pucBuffer,
1485                                           size_t xBufferSizeBytes,
1486                                           size_t xTriggerLevelBytes,
1487                                           uint8_t ucFlags,
1488                                           StreamBufferCallbackFunction_t pxSendCompletedCallback,
1489                                           StreamBufferCallbackFunction_t pxReceiveCompletedCallback )
1490 {
1491     /* Assert here is deliberately writing to the entire buffer to ensure it can
1492      * be written to without generating exceptions, and is setting the buffer to a
1493      * known value to assist in development/debugging. */
1494     #if ( configASSERT_DEFINED == 1 )
1495     {
1496         /* The value written just has to be identifiable when looking at the
1497          * memory.  Don't use 0xA5 as that is the stack fill value and could
1498          * result in confusion as to what is actually being observed. */
1499     #define STREAM_BUFFER_BUFFER_WRITE_VALUE    ( 0x55 )
1500         configASSERT( memset( pucBuffer, ( int ) STREAM_BUFFER_BUFFER_WRITE_VALUE, xBufferSizeBytes ) == pucBuffer );
1501     }
1502     #endif
1503
1504     ( void ) memset( ( void * ) pxStreamBuffer, 0x00, sizeof( StreamBuffer_t ) );
1505     pxStreamBuffer->pucBuffer = pucBuffer;
1506     pxStreamBuffer->xLength = xBufferSizeBytes;
1507     pxStreamBuffer->xTriggerLevelBytes = xTriggerLevelBytes;
1508     pxStreamBuffer->ucFlags = ucFlags;
1509     pxStreamBuffer->uxNotificationIndex = tskDEFAULT_INDEX_TO_NOTIFY;
1510     #if ( configUSE_SB_COMPLETED_CALLBACK == 1 )
1511     {
1512         pxStreamBuffer->pxSendCompletedCallback = pxSendCompletedCallback;
1513         pxStreamBuffer->pxReceiveCompletedCallback = pxReceiveCompletedCallback;
1514     }
1515     #else
1516     {
1517         /* MISRA Ref 11.1.1 [Object type casting] */
1518         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-111 */
1519         /* coverity[misra_c_2012_rule_11_1_violation] */
1520         ( void ) pxSendCompletedCallback;
1521
1522         /* MISRA Ref 11.1.1 [Object type casting] */
1523         /* More details at: https://github.com/FreeRTOS/FreeRTOS-Kernel/blob/main/MISRA.md#rule-111 */
1524         /* coverity[misra_c_2012_rule_11_1_violation] */
1525         ( void ) pxReceiveCompletedCallback;
1526     }
1527     #endif /* if ( configUSE_SB_COMPLETED_CALLBACK == 1 ) */
1528 }
1529 /*-----------------------------------------------------------*/
1530
1531 UBaseType_t uxStreamBufferGetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer )
1532 {
1533     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1534
1535     traceENTER_uxStreamBufferGetStreamBufferNotificationIndex( xStreamBuffer );
1536
1537     configASSERT( pxStreamBuffer );
1538
1539     traceRETURN_uxStreamBufferGetStreamBufferNotificationIndex( pxStreamBuffer->uxNotificationIndex );
1540
1541     return pxStreamBuffer->uxNotificationIndex;
1542 }
1543 /*-----------------------------------------------------------*/
1544
1545 void vStreamBufferSetStreamBufferNotificationIndex( StreamBufferHandle_t xStreamBuffer,
1546                                                     UBaseType_t uxNotificationIndex )
1547 {
1548     StreamBuffer_t * const pxStreamBuffer = xStreamBuffer;
1549
1550     traceENTER_vStreamBufferSetStreamBufferNotificationIndex( xStreamBuffer, uxNotificationIndex );
1551
1552     configASSERT( pxStreamBuffer );
1553
1554     /* There should be no task waiting otherwise we'd never resume them. */
1555     configASSERT( pxStreamBuffer->xTaskWaitingToReceive == NULL );
1556     configASSERT( pxStreamBuffer->xTaskWaitingToSend == NULL );
1557
1558     /* Check that the task notification index is valid. */
1559     configASSERT( uxNotificationIndex < configTASK_NOTIFICATION_ARRAY_ENTRIES );
1560
1561     pxStreamBuffer->uxNotificationIndex = uxNotificationIndex;
1562
1563     traceRETURN_vStreamBufferSetStreamBufferNotificationIndex();
1564 }
1565 /*-----------------------------------------------------------*/
1566
1567 #if ( configUSE_TRACE_FACILITY == 1 )
1568
1569     UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer )
1570     {
1571         traceENTER_uxStreamBufferGetStreamBufferNumber( xStreamBuffer );
1572
1573         traceRETURN_uxStreamBufferGetStreamBufferNumber( xStreamBuffer->uxStreamBufferNumber );
1574
1575         return xStreamBuffer->uxStreamBufferNumber;
1576     }
1577
1578 #endif /* configUSE_TRACE_FACILITY */
1579 /*-----------------------------------------------------------*/
1580
1581 #if ( configUSE_TRACE_FACILITY == 1 )
1582
1583     void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer,
1584                                              UBaseType_t uxStreamBufferNumber )
1585     {
1586         traceENTER_vStreamBufferSetStreamBufferNumber( xStreamBuffer, uxStreamBufferNumber );
1587
1588         xStreamBuffer->uxStreamBufferNumber = uxStreamBufferNumber;
1589
1590         traceRETURN_vStreamBufferSetStreamBufferNumber();
1591     }
1592
1593 #endif /* configUSE_TRACE_FACILITY */
1594 /*-----------------------------------------------------------*/
1595
1596 #if ( configUSE_TRACE_FACILITY == 1 )
1597
1598     uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer )
1599     {
1600         traceENTER_ucStreamBufferGetStreamBufferType( xStreamBuffer );
1601
1602         traceRETURN_ucStreamBufferGetStreamBufferType( ( uint8_t ) ( xStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) );
1603
1604         return( ( uint8_t ) ( xStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) );
1605     }
1606
1607 #endif /* configUSE_TRACE_FACILITY */
1608 /*-----------------------------------------------------------*/