begriffs open source - freertos/blob - stream_buffer.c

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