begriffs open source - cmsis-freertos/blob - Source/queue.c

   1 /*
   2  * FreeRTOS Kernel V10.4.4
   3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
   4  *
   5  * SPDX-License-Identifier: MIT
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   8  * this software and associated documentation files (the "Software"), to deal in
   9  * the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11  * the Software, and to permit persons to whom the Software is furnished to do so,
  12  * subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in all
  15  * copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  *
  24  * https://www.FreeRTOS.org
  25  * https://github.com/FreeRTOS
  26  *
  27  */
  28
  29 #include <stdlib.h>
  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 #include "FreeRTOS.h"
  38 #include "task.h"
  39 #include "queue.h"
  40
  41 #if ( configUSE_CO_ROUTINES == 1 )
  42     #include "croutine.h"
  43 #endif
  44
  45 /* Lint e9021, e961 and e750 are suppressed as a MISRA exception justified
  46  * because the MPU ports require MPU_WRAPPERS_INCLUDED_FROM_API_FILE to be defined
  47  * for the header files above, but not in this file, in order to generate the
  48  * correct privileged Vs unprivileged linkage and placement. */
  49 #undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE /*lint !e961 !e750 !e9021. */
  50
  51
  52 /* Constants used with the cRxLock and cTxLock structure members. */
  53 #define queueUNLOCKED             ( ( int8_t ) -1 )
  54 #define queueLOCKED_UNMODIFIED    ( ( int8_t ) 0 )
  55 #define queueINT8_MAX             ( ( int8_t ) 127 )
  56
  57 /* When the Queue_t structure is used to represent a base queue its pcHead and
  58  * pcTail members are used as pointers into the queue storage area.  When the
  59  * Queue_t structure is used to represent a mutex pcHead and pcTail pointers are
  60  * not necessary, and the pcHead pointer is set to NULL to indicate that the
  61  * structure instead holds a pointer to the mutex holder (if any).  Map alternative
  62  * names to the pcHead and structure member to ensure the readability of the code
  63  * is maintained.  The QueuePointers_t and SemaphoreData_t types are used to form
  64  * a union as their usage is mutually exclusive dependent on what the queue is
  65  * being used for. */
  66 #define uxQueueType               pcHead
  67 #define queueQUEUE_IS_MUTEX       NULL
  68
  69 typedef struct QueuePointers
  70 {
  71     int8_t * pcTail;     /*< Points to the byte at the end of the queue storage area.  Once more byte is allocated than necessary to store the queue items, this is used as a marker. */
  72     int8_t * pcReadFrom; /*< Points to the last place that a queued item was read from when the structure is used as a queue. */
  73 } QueuePointers_t;
  74
  75 typedef struct SemaphoreData
  76 {
  77     TaskHandle_t xMutexHolder;        /*< The handle of the task that holds the mutex. */
  78     UBaseType_t uxRecursiveCallCount; /*< Maintains a count of the number of times a recursive mutex has been recursively 'taken' when the structure is used as a mutex. */
  79 } SemaphoreData_t;
  80
  81 /* Semaphores do not actually store or copy data, so have an item size of
  82  * zero. */
  83 #define queueSEMAPHORE_QUEUE_ITEM_LENGTH    ( ( UBaseType_t ) 0 )
  84 #define queueMUTEX_GIVE_BLOCK_TIME          ( ( TickType_t ) 0U )
  85
  86 #if ( configUSE_PREEMPTION == 0 )
  87
  88 /* If the cooperative scheduler is being used then a yield should not be
  89  * performed just because a higher priority task has been woken. */
  90     #define queueYIELD_IF_USING_PREEMPTION()
  91 #else
  92     #define queueYIELD_IF_USING_PREEMPTION()    portYIELD_WITHIN_API()
  93 #endif
  94
  95 /*
  96  * Definition of the queue used by the scheduler.
  97  * Items are queued by copy, not reference.  See the following link for the
  98  * rationale: https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
  99  */
 100 typedef struct QueueDefinition /* The old naming convention is used to prevent breaking kernel aware debuggers. */
 101 {
 102     int8_t * pcHead;           /*< Points to the beginning of the queue storage area. */
 103     int8_t * pcWriteTo;        /*< Points to the free next place in the storage area. */
 104
 105     union
 106     {
 107         QueuePointers_t xQueue;     /*< Data required exclusively when this structure is used as a queue. */
 108         SemaphoreData_t xSemaphore; /*< Data required exclusively when this structure is used as a semaphore. */
 109     } u;
 110
 111     List_t xTasksWaitingToSend;             /*< List of tasks that are blocked waiting to post onto this queue.  Stored in priority order. */
 112     List_t xTasksWaitingToReceive;          /*< List of tasks that are blocked waiting to read from this queue.  Stored in priority order. */
 113
 114     volatile UBaseType_t uxMessagesWaiting; /*< The number of items currently in the queue. */
 115     UBaseType_t uxLength;                   /*< The length of the queue defined as the number of items it will hold, not the number of bytes. */
 116     UBaseType_t uxItemSize;                 /*< The size of each items that the queue will hold. */
 117
 118     volatile int8_t cRxLock;                /*< Stores the number of items received from the queue (removed from the queue) while the queue was locked.  Set to queueUNLOCKED when the queue is not locked. */
 119     volatile int8_t cTxLock;                /*< Stores the number of items transmitted to the queue (added to the queue) while the queue was locked.  Set to queueUNLOCKED when the queue is not locked. */
 120
 121     #if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
 122         uint8_t ucStaticallyAllocated; /*< Set to pdTRUE if the memory used by the queue was statically allocated to ensure no attempt is made to free the memory. */
 123     #endif
 124
 125     #if ( configUSE_QUEUE_SETS == 1 )
 126         struct QueueDefinition * pxQueueSetContainer;
 127     #endif
 128
 129     #if ( configUSE_TRACE_FACILITY == 1 )
 130         UBaseType_t uxQueueNumber;
 131         uint8_t ucQueueType;
 132     #endif
 133 } xQUEUE;
 134
 135 /* The old xQUEUE name is maintained above then typedefed to the new Queue_t
 136  * name below to enable the use of older kernel aware debuggers. */
 137 typedef xQUEUE Queue_t;
 138
 139 /*-----------------------------------------------------------*/
 140
 141 /*
 142  * The queue registry is just a means for kernel aware debuggers to locate
 143  * queue structures.  It has no other purpose so is an optional component.
 144  */
 145 #if ( configQUEUE_REGISTRY_SIZE > 0 )
 146
 147 /* The type stored within the queue registry array.  This allows a name
 148  * to be assigned to each queue making kernel aware debugging a little
 149  * more user friendly. */
 150     typedef struct QUEUE_REGISTRY_ITEM
 151     {
 152         const char * pcQueueName; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
 153         QueueHandle_t xHandle;
 154     } xQueueRegistryItem;
 155
 156 /* The old xQueueRegistryItem name is maintained above then typedefed to the
 157  * new xQueueRegistryItem name below to enable the use of older kernel aware
 158  * debuggers. */
 159     typedef xQueueRegistryItem QueueRegistryItem_t;
 160
 161 /* The queue registry is simply an array of QueueRegistryItem_t structures.
 162  * The pcQueueName member of a structure being NULL is indicative of the
 163  * array position being vacant. */
 164     PRIVILEGED_DATA QueueRegistryItem_t xQueueRegistry[ configQUEUE_REGISTRY_SIZE ];
 165
 166 #endif /* configQUEUE_REGISTRY_SIZE */
 167
 168 /*
 169  * Unlocks a queue locked by a call to prvLockQueue.  Locking a queue does not
 170  * prevent an ISR from adding or removing items to the queue, but does prevent
 171  * an ISR from removing tasks from the queue event lists.  If an ISR finds a
 172  * queue is locked it will instead increment the appropriate queue lock count
 173  * to indicate that a task may require unblocking.  When the queue in unlocked
 174  * these lock counts are inspected, and the appropriate action taken.
 175  */
 176 static void prvUnlockQueue( Queue_t * const pxQueue ) PRIVILEGED_FUNCTION;
 177
 178 /*
 179  * Uses a critical section to determine if there is any data in a queue.
 180  *
 181  * @return pdTRUE if the queue contains no items, otherwise pdFALSE.
 182  */
 183 static BaseType_t prvIsQueueEmpty( const Queue_t * pxQueue ) PRIVILEGED_FUNCTION;
 184
 185 /*
 186  * Uses a critical section to determine if there is any space in a queue.
 187  *
 188  * @return pdTRUE if there is no space, otherwise pdFALSE;
 189  */
 190 static BaseType_t prvIsQueueFull( const Queue_t * pxQueue ) PRIVILEGED_FUNCTION;
 191
 192 /*
 193  * Copies an item into the queue, either at the front of the queue or the
 194  * back of the queue.
 195  */
 196 static BaseType_t prvCopyDataToQueue( Queue_t * const pxQueue,
 197                                       const void * pvItemToQueue,
 198                                       const BaseType_t xPosition ) PRIVILEGED_FUNCTION;
 199
 200 /*
 201  * Copies an item out of a queue.
 202  */
 203 static void prvCopyDataFromQueue( Queue_t * const pxQueue,
 204                                   void * const pvBuffer ) PRIVILEGED_FUNCTION;
 205
 206 #if ( configUSE_QUEUE_SETS == 1 )
 207
 208 /*
 209  * Checks to see if a queue is a member of a queue set, and if so, notifies
 210  * the queue set that the queue contains data.
 211  */
 212     static BaseType_t prvNotifyQueueSetContainer( const Queue_t * const pxQueue ) PRIVILEGED_FUNCTION;
 213 #endif
 214
 215 /*
 216  * Called after a Queue_t structure has been allocated either statically or
 217  * dynamically to fill in the structure's members.
 218  */
 219 static void prvInitialiseNewQueue( const UBaseType_t uxQueueLength,
 220                                    const UBaseType_t uxItemSize,
 221                                    uint8_t * pucQueueStorage,
 222                                    const uint8_t ucQueueType,
 223                                    Queue_t * pxNewQueue ) PRIVILEGED_FUNCTION;
 224
 225 /*
 226  * Mutexes are a special type of queue.  When a mutex is created, first the
 227  * queue is created, then prvInitialiseMutex() is called to configure the queue
 228  * as a mutex.
 229  */
 230 #if ( configUSE_MUTEXES == 1 )
 231     static void prvInitialiseMutex( Queue_t * pxNewQueue ) PRIVILEGED_FUNCTION;
 232 #endif
 233
 234 #if ( configUSE_MUTEXES == 1 )
 235
 236 /*
 237  * If a task waiting for a mutex causes the mutex holder to inherit a
 238  * priority, but the waiting task times out, then the holder should
 239  * disinherit the priority - but only down to the highest priority of any
 240  * other tasks that are waiting for the same mutex.  This function returns
 241  * that priority.
 242  */
 243     static UBaseType_t prvGetDisinheritPriorityAfterTimeout( const Queue_t * const pxQueue ) PRIVILEGED_FUNCTION;
 244 #endif
 245 /*-----------------------------------------------------------*/
 246
 247 /*
 248  * Macro to mark a queue as locked.  Locking a queue prevents an ISR from
 249  * accessing the queue event lists.
 250  */
 251 #define prvLockQueue( pxQueue )                            \
 252     taskENTER_CRITICAL();                                  \
 253     {                                                      \
 254         if( ( pxQueue )->cRxLock == queueUNLOCKED )        \
 255         {                                                  \
 256             ( pxQueue )->cRxLock = queueLOCKED_UNMODIFIED; \
 257         }                                                  \
 258         if( ( pxQueue )->cTxLock == queueUNLOCKED )        \
 259         {                                                  \
 260             ( pxQueue )->cTxLock = queueLOCKED_UNMODIFIED; \
 261         }                                                  \
 262     }                                                      \
 263     taskEXIT_CRITICAL()
 264 /*-----------------------------------------------------------*/
 265
 266 BaseType_t xQueueGenericReset( QueueHandle_t xQueue,
 267                                BaseType_t xNewQueue )
 268 {
 269     BaseType_t xReturn = pdPASS;
 270     Queue_t * const pxQueue = xQueue;
 271
 272     configASSERT( pxQueue );
 273
 274     if( ( pxQueue != NULL ) &&
 275         ( pxQueue->uxLength >= 1U ) &&
 276         /* Check for multiplication overflow. */
 277         ( ( SIZE_MAX / pxQueue->uxLength ) >= pxQueue->uxItemSize ) )
 278     {
 279         taskENTER_CRITICAL();
 280
 281         pxQueue->u.xQueue.pcTail = pxQueue->pcHead + ( pxQueue->uxLength * pxQueue->uxItemSize ); /*lint !e9016 Pointer arithmetic allowed on char types, especially when it assists conveying intent. */
 282         pxQueue->uxMessagesWaiting = ( UBaseType_t ) 0U;
 283         pxQueue->pcWriteTo = pxQueue->pcHead;
 284         pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead + ( ( pxQueue->uxLength - 1U ) * pxQueue->uxItemSize ); /*lint !e9016 Pointer arithmetic allowed on char types, especially when it assists conveying intent. */
 285         pxQueue->cRxLock = queueUNLOCKED;
 286         pxQueue->cTxLock = queueUNLOCKED;
 287
 288         if( xNewQueue == pdFALSE )
 289         {
 290             /* If there are tasks blocked waiting to read from the queue, then
 291              * the tasks will remain blocked as after this function exits the queue
 292              * will still be empty.  If there are tasks blocked waiting to write to
 293              * the queue, then one should be unblocked as after this function exits
 294              * it will be possible to write to it. */
 295             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
 296             {
 297                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
 298                 {
 299                     queueYIELD_IF_USING_PREEMPTION();
 300                 }
 301                 else
 302                 {
 303                     mtCOVERAGE_TEST_MARKER();
 304                 }
 305             }
 306             else
 307             {
 308                 mtCOVERAGE_TEST_MARKER();
 309             }
 310         }
 311         else
 312         {
 313             /* Ensure the event queues start in the correct state. */
 314             vListInitialise( &( pxQueue->xTasksWaitingToSend ) );
 315             vListInitialise( &( pxQueue->xTasksWaitingToReceive ) );
 316         }
 317         taskEXIT_CRITICAL();
 318     }
 319     else
 320     {
 321         xReturn = pdFAIL;
 322     }
 323
 324     configASSERT( xReturn != pdFAIL );
 325
 326     /* A value is returned for calling semantic consistency with previous
 327      * versions. */
 328     return xReturn;
 329 }
 330 /*-----------------------------------------------------------*/
 331
 332 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 333
 334     QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength,
 335                                              const UBaseType_t uxItemSize,
 336                                              uint8_t * pucQueueStorage,
 337                                              StaticQueue_t * pxStaticQueue,
 338                                              const uint8_t ucQueueType )
 339     {
 340         Queue_t * pxNewQueue = NULL;
 341
 342         /* The StaticQueue_t structure and the queue storage area must be
 343          * supplied. */
 344         configASSERT( pxStaticQueue );
 345
 346         if( ( uxQueueLength > ( UBaseType_t ) 0 ) &&
 347             ( pxStaticQueue != NULL ) &&
 348             /* A queue storage area should be provided if the item size is not 0, and
 349              * should not be provided if the item size is 0. */
 350             ( !( ( pucQueueStorage != NULL ) && ( uxItemSize == 0 ) ) ) &&
 351             ( !( ( pucQueueStorage == NULL ) && ( uxItemSize != 0 ) ) ) )
 352         {
 353
 354             #if ( configASSERT_DEFINED == 1 )
 355                 {
 356                     /* Sanity check that the size of the structure used to declare a
 357                      * variable of type StaticQueue_t or StaticSemaphore_t equals the size of
 358                      * the real queue and semaphore structures. */
 359                     volatile size_t xSize = sizeof( StaticQueue_t );
 360
 361                     /* This assertion cannot be branch covered in unit tests */
 362                     configASSERT( xSize == sizeof( Queue_t ) ); /* LCOV_EXCL_BR_LINE */
 363                     ( void ) xSize;                             /* Keeps lint quiet when configASSERT() is not defined. */
 364                 }
 365             #endif /* configASSERT_DEFINED */
 366
 367             /* The address of a statically allocated queue was passed in, use it.
 368              * The address of a statically allocated storage area was also passed in
 369              * but is already set. */
 370             pxNewQueue = ( Queue_t * ) pxStaticQueue; /*lint !e740 !e9087 Unusual cast is ok as the structures are designed to have the same alignment, and the size is checked by an assert. */
 371
 372             #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 373                 {
 374                     /* Queues can be allocated wither statically or dynamically, so
 375                      * note this queue was allocated statically in case the queue is
 376                      * later deleted. */
 377                     pxNewQueue->ucStaticallyAllocated = pdTRUE;
 378                 }
 379             #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 380
 381             prvInitialiseNewQueue( uxQueueLength, uxItemSize, pucQueueStorage, ucQueueType, pxNewQueue );
 382         }
 383         else
 384         {
 385             configASSERT( pxNewQueue );
 386             mtCOVERAGE_TEST_MARKER();
 387         }
 388
 389         return pxNewQueue;
 390     }
 391
 392 #endif /* configSUPPORT_STATIC_ALLOCATION */
 393 /*-----------------------------------------------------------*/
 394
 395 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 396
 397     QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength,
 398                                        const UBaseType_t uxItemSize,
 399                                        const uint8_t ucQueueType )
 400     {
 401         Queue_t * pxNewQueue = NULL;
 402         size_t xQueueSizeInBytes;
 403         uint8_t * pucQueueStorage;
 404
 405         if( ( uxQueueLength > ( UBaseType_t ) 0 ) &&
 406             /* Check for multiplication overflow. */
 407             ( ( SIZE_MAX / uxQueueLength ) >= uxItemSize ) &&
 408             /* Check for addition overflow. */
 409             ( ( SIZE_MAX - sizeof( Queue_t ) ) >= ( uxQueueLength * uxItemSize ) ) )
 410         {
 411             /* Allocate enough space to hold the maximum number of items that
 412              * can be in the queue at any time.  It is valid for uxItemSize to be
 413              * zero in the case the queue is used as a semaphore. */
 414             xQueueSizeInBytes = ( size_t ) ( uxQueueLength * uxItemSize ); /*lint !e961 MISRA exception as the casts are only redundant for some ports. */
 415
 416             /* Allocate the queue and storage area.  Justification for MISRA
 417              * deviation as follows:  pvPortMalloc() always ensures returned memory
 418              * blocks are aligned per the requirements of the MCU stack.  In this case
 419              * pvPortMalloc() must return a pointer that is guaranteed to meet the
 420              * alignment requirements of the Queue_t structure - which in this case
 421              * is an int8_t *.  Therefore, whenever the stack alignment requirements
 422              * are greater than or equal to the pointer to char requirements the cast
 423              * is safe.  In other cases alignment requirements are not strict (one or
 424              * two bytes). */
 425             pxNewQueue = ( Queue_t * ) pvPortMalloc( sizeof( Queue_t ) + xQueueSizeInBytes ); /*lint !e9087 !e9079 see comment above. */
 426
 427             if( pxNewQueue != NULL )
 428             {
 429                 /* Jump past the queue structure to find the location of the queue
 430                  * storage area. */
 431                 pucQueueStorage = ( uint8_t * ) pxNewQueue;
 432                 pucQueueStorage += sizeof( Queue_t ); /*lint !e9016 Pointer arithmetic allowed on char types, especially when it assists conveying intent. */
 433
 434                 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 435                     {
 436                         /* Queues can be created either statically or dynamically, so
 437                          * note this task was created dynamically in case it is later
 438                          * deleted. */
 439                         pxNewQueue->ucStaticallyAllocated = pdFALSE;
 440                     }
 441                 #endif /* configSUPPORT_STATIC_ALLOCATION */
 442
 443                 prvInitialiseNewQueue( uxQueueLength, uxItemSize, pucQueueStorage, ucQueueType, pxNewQueue );
 444             }
 445             else
 446             {
 447                 traceQUEUE_CREATE_FAILED( ucQueueType );
 448                 mtCOVERAGE_TEST_MARKER();
 449             }
 450         }
 451         else
 452         {
 453             configASSERT( pxNewQueue );
 454             mtCOVERAGE_TEST_MARKER();
 455         }
 456
 457         return pxNewQueue;
 458     }
 459
 460 #endif /* configSUPPORT_STATIC_ALLOCATION */
 461 /*-----------------------------------------------------------*/
 462
 463 static void prvInitialiseNewQueue( const UBaseType_t uxQueueLength,
 464                                    const UBaseType_t uxItemSize,
 465                                    uint8_t * pucQueueStorage,
 466                                    const uint8_t ucQueueType,
 467                                    Queue_t * pxNewQueue )
 468 {
 469     /* Remove compiler warnings about unused parameters should
 470      * configUSE_TRACE_FACILITY not be set to 1. */
 471     ( void ) ucQueueType;
 472
 473     if( uxItemSize == ( UBaseType_t ) 0 )
 474     {
 475         /* No RAM was allocated for the queue storage area, but PC head cannot
 476          * be set to NULL because NULL is used as a key to say the queue is used as
 477          * a mutex.  Therefore just set pcHead to point to the queue as a benign
 478          * value that is known to be within the memory map. */
 479         pxNewQueue->pcHead = ( int8_t * ) pxNewQueue;
 480     }
 481     else
 482     {
 483         /* Set the head to the start of the queue storage area. */
 484         pxNewQueue->pcHead = ( int8_t * ) pucQueueStorage;
 485     }
 486
 487     /* Initialise the queue members as described where the queue type is
 488      * defined. */
 489     pxNewQueue->uxLength = uxQueueLength;
 490     pxNewQueue->uxItemSize = uxItemSize;
 491     ( void ) xQueueGenericReset( pxNewQueue, pdTRUE );
 492
 493     #if ( configUSE_TRACE_FACILITY == 1 )
 494         {
 495             pxNewQueue->ucQueueType = ucQueueType;
 496         }
 497     #endif /* configUSE_TRACE_FACILITY */
 498
 499     #if ( configUSE_QUEUE_SETS == 1 )
 500         {
 501             pxNewQueue->pxQueueSetContainer = NULL;
 502         }
 503     #endif /* configUSE_QUEUE_SETS */
 504
 505     traceQUEUE_CREATE( pxNewQueue );
 506 }
 507 /*-----------------------------------------------------------*/
 508
 509 #if ( configUSE_MUTEXES == 1 )
 510
 511     static void prvInitialiseMutex( Queue_t * pxNewQueue )
 512     {
 513         if( pxNewQueue != NULL )
 514         {
 515             /* The queue create function will set all the queue structure members
 516             * correctly for a generic queue, but this function is creating a
 517             * mutex.  Overwrite those members that need to be set differently -
 518             * in particular the information required for priority inheritance. */
 519             pxNewQueue->u.xSemaphore.xMutexHolder = NULL;
 520             pxNewQueue->uxQueueType = queueQUEUE_IS_MUTEX;
 521
 522             /* In case this is a recursive mutex. */
 523             pxNewQueue->u.xSemaphore.uxRecursiveCallCount = 0;
 524
 525             traceCREATE_MUTEX( pxNewQueue );
 526
 527             /* Start with the semaphore in the expected state. */
 528             ( void ) xQueueGenericSend( pxNewQueue, NULL, ( TickType_t ) 0U, queueSEND_TO_BACK );
 529         }
 530         else
 531         {
 532             traceCREATE_MUTEX_FAILED();
 533         }
 534     }
 535
 536 #endif /* configUSE_MUTEXES */
 537 /*-----------------------------------------------------------*/
 538
 539 #if ( ( configUSE_MUTEXES == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
 540
 541     QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType )
 542     {
 543         QueueHandle_t xNewQueue;
 544         const UBaseType_t uxMutexLength = ( UBaseType_t ) 1, uxMutexSize = ( UBaseType_t ) 0;
 545
 546         xNewQueue = xQueueGenericCreate( uxMutexLength, uxMutexSize, ucQueueType );
 547         prvInitialiseMutex( ( Queue_t * ) xNewQueue );
 548
 549         return xNewQueue;
 550     }
 551
 552 #endif /* configUSE_MUTEXES */
 553 /*-----------------------------------------------------------*/
 554
 555 #if ( ( configUSE_MUTEXES == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
 556
 557     QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType,
 558                                            StaticQueue_t * pxStaticQueue )
 559     {
 560         QueueHandle_t xNewQueue;
 561         const UBaseType_t uxMutexLength = ( UBaseType_t ) 1, uxMutexSize = ( UBaseType_t ) 0;
 562
 563         /* Prevent compiler warnings about unused parameters if
 564          * configUSE_TRACE_FACILITY does not equal 1. */
 565         ( void ) ucQueueType;
 566
 567         xNewQueue = xQueueGenericCreateStatic( uxMutexLength, uxMutexSize, NULL, pxStaticQueue, ucQueueType );
 568         prvInitialiseMutex( ( Queue_t * ) xNewQueue );
 569
 570         return xNewQueue;
 571     }
 572
 573 #endif /* configUSE_MUTEXES */
 574 /*-----------------------------------------------------------*/
 575
 576 #if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) )
 577
 578     TaskHandle_t xQueueGetMutexHolder( QueueHandle_t xSemaphore )
 579     {
 580         TaskHandle_t pxReturn;
 581         Queue_t * const pxSemaphore = ( Queue_t * ) xSemaphore;
 582
 583         configASSERT( xSemaphore );
 584
 585         /* This function is called by xSemaphoreGetMutexHolder(), and should not
 586          * be called directly.  Note:  This is a good way of determining if the
 587          * calling task is the mutex holder, but not a good way of determining the
 588          * identity of the mutex holder, as the holder may change between the
 589          * following critical section exiting and the function returning. */
 590         taskENTER_CRITICAL();
 591         {
 592             if( pxSemaphore->uxQueueType == queueQUEUE_IS_MUTEX )
 593             {
 594                 pxReturn = pxSemaphore->u.xSemaphore.xMutexHolder;
 595             }
 596             else
 597             {
 598                 pxReturn = NULL;
 599             }
 600         }
 601         taskEXIT_CRITICAL();
 602
 603         return pxReturn;
 604     } /*lint !e818 xSemaphore cannot be a pointer to const because it is a typedef. */
 605
 606 #endif /* if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) */
 607 /*-----------------------------------------------------------*/
 608
 609 #if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) )
 610
 611     TaskHandle_t xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore )
 612     {
 613         TaskHandle_t pxReturn;
 614
 615         configASSERT( xSemaphore );
 616
 617         /* Mutexes cannot be used in interrupt service routines, so the mutex
 618          * holder should not change in an ISR, and therefore a critical section is
 619          * not required here. */
 620         if( ( ( Queue_t * ) xSemaphore )->uxQueueType == queueQUEUE_IS_MUTEX )
 621         {
 622             pxReturn = ( ( Queue_t * ) xSemaphore )->u.xSemaphore.xMutexHolder;
 623         }
 624         else
 625         {
 626             pxReturn = NULL;
 627         }
 628
 629         return pxReturn;
 630     } /*lint !e818 xSemaphore cannot be a pointer to const because it is a typedef. */
 631
 632 #endif /* if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) ) */
 633 /*-----------------------------------------------------------*/
 634
 635 #if ( configUSE_RECURSIVE_MUTEXES == 1 )
 636
 637     BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex )
 638     {
 639         BaseType_t xReturn;
 640         Queue_t * const pxMutex = ( Queue_t * ) xMutex;
 641
 642         configASSERT( pxMutex );
 643
 644         /* If this is the task that holds the mutex then xMutexHolder will not
 645          * change outside of this task.  If this task does not hold the mutex then
 646          * pxMutexHolder can never coincidentally equal the tasks handle, and as
 647          * this is the only condition we are interested in it does not matter if
 648          * pxMutexHolder is accessed simultaneously by another task.  Therefore no
 649          * mutual exclusion is required to test the pxMutexHolder variable. */
 650         if( pxMutex->u.xSemaphore.xMutexHolder == xTaskGetCurrentTaskHandle() )
 651         {
 652             traceGIVE_MUTEX_RECURSIVE( pxMutex );
 653
 654             /* uxRecursiveCallCount cannot be zero if xMutexHolder is equal to
 655              * the task handle, therefore no underflow check is required.  Also,
 656              * uxRecursiveCallCount is only modified by the mutex holder, and as
 657              * there can only be one, no mutual exclusion is required to modify the
 658              * uxRecursiveCallCount member. */
 659             ( pxMutex->u.xSemaphore.uxRecursiveCallCount )--;
 660
 661             /* Has the recursive call count unwound to 0? */
 662             if( pxMutex->u.xSemaphore.uxRecursiveCallCount == ( UBaseType_t ) 0 )
 663             {
 664                 /* Return the mutex.  This will automatically unblock any other
 665                  * task that might be waiting to access the mutex. */
 666                 ( void ) xQueueGenericSend( pxMutex, NULL, queueMUTEX_GIVE_BLOCK_TIME, queueSEND_TO_BACK );
 667             }
 668             else
 669             {
 670                 mtCOVERAGE_TEST_MARKER();
 671             }
 672
 673             xReturn = pdPASS;
 674         }
 675         else
 676         {
 677             /* The mutex cannot be given because the calling task is not the
 678              * holder. */
 679             xReturn = pdFAIL;
 680
 681             traceGIVE_MUTEX_RECURSIVE_FAILED( pxMutex );
 682         }
 683
 684         return xReturn;
 685     }
 686
 687 #endif /* configUSE_RECURSIVE_MUTEXES */
 688 /*-----------------------------------------------------------*/
 689
 690 #if ( configUSE_RECURSIVE_MUTEXES == 1 )
 691
 692     BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex,
 693                                          TickType_t xTicksToWait )
 694     {
 695         BaseType_t xReturn;
 696         Queue_t * const pxMutex = ( Queue_t * ) xMutex;
 697
 698         configASSERT( pxMutex );
 699
 700         /* Comments regarding mutual exclusion as per those within
 701          * xQueueGiveMutexRecursive(). */
 702
 703         traceTAKE_MUTEX_RECURSIVE( pxMutex );
 704
 705         if( pxMutex->u.xSemaphore.xMutexHolder == xTaskGetCurrentTaskHandle() )
 706         {
 707             ( pxMutex->u.xSemaphore.uxRecursiveCallCount )++;
 708             xReturn = pdPASS;
 709         }
 710         else
 711         {
 712             xReturn = xQueueSemaphoreTake( pxMutex, xTicksToWait );
 713
 714             /* pdPASS will only be returned if the mutex was successfully
 715              * obtained.  The calling task may have entered the Blocked state
 716              * before reaching here. */
 717             if( xReturn != pdFAIL )
 718             {
 719                 ( pxMutex->u.xSemaphore.uxRecursiveCallCount )++;
 720             }
 721             else
 722             {
 723                 traceTAKE_MUTEX_RECURSIVE_FAILED( pxMutex );
 724             }
 725         }
 726
 727         return xReturn;
 728     }
 729
 730 #endif /* configUSE_RECURSIVE_MUTEXES */
 731 /*-----------------------------------------------------------*/
 732
 733 #if ( ( configUSE_COUNTING_SEMAPHORES == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
 734
 735     QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount,
 736                                                        const UBaseType_t uxInitialCount,
 737                                                        StaticQueue_t * pxStaticQueue )
 738     {
 739         QueueHandle_t xHandle = NULL;
 740
 741         if( ( uxMaxCount != 0 ) &&
 742             ( uxInitialCount <= uxMaxCount ) )
 743         {
 744             xHandle = xQueueGenericCreateStatic( uxMaxCount, queueSEMAPHORE_QUEUE_ITEM_LENGTH, NULL, pxStaticQueue, queueQUEUE_TYPE_COUNTING_SEMAPHORE );
 745
 746             if( xHandle != NULL )
 747             {
 748                 ( ( Queue_t * ) xHandle )->uxMessagesWaiting = uxInitialCount;
 749
 750                 traceCREATE_COUNTING_SEMAPHORE();
 751             }
 752             else
 753             {
 754                 traceCREATE_COUNTING_SEMAPHORE_FAILED();
 755             }
 756         }
 757         else
 758         {
 759             configASSERT( xHandle );
 760             mtCOVERAGE_TEST_MARKER();
 761         }
 762
 763         return xHandle;
 764     }
 765
 766 #endif /* ( ( configUSE_COUNTING_SEMAPHORES == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) ) */
 767 /*-----------------------------------------------------------*/
 768
 769 #if ( ( configUSE_COUNTING_SEMAPHORES == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
 770
 771     QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount,
 772                                                  const UBaseType_t uxInitialCount )
 773     {
 774         QueueHandle_t xHandle = NULL;
 775
 776         if( ( uxMaxCount != 0 ) &&
 777             ( uxInitialCount <= uxMaxCount ) )
 778         {
 779             xHandle = xQueueGenericCreate( uxMaxCount, queueSEMAPHORE_QUEUE_ITEM_LENGTH, queueQUEUE_TYPE_COUNTING_SEMAPHORE );
 780
 781             if( xHandle != NULL )
 782             {
 783                 ( ( Queue_t * ) xHandle )->uxMessagesWaiting = uxInitialCount;
 784
 785                 traceCREATE_COUNTING_SEMAPHORE();
 786             }
 787             else
 788             {
 789                 traceCREATE_COUNTING_SEMAPHORE_FAILED();
 790             }
 791         }
 792         else
 793         {
 794             configASSERT( xHandle );
 795             mtCOVERAGE_TEST_MARKER();
 796         }
 797
 798         return xHandle;
 799     }
 800
 801 #endif /* ( ( configUSE_COUNTING_SEMAPHORES == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) ) */
 802 /*-----------------------------------------------------------*/
 803
 804 BaseType_t xQueueGenericSend( QueueHandle_t xQueue,
 805                               const void * const pvItemToQueue,
 806                               TickType_t xTicksToWait,
 807                               const BaseType_t xCopyPosition )
 808 {
 809     BaseType_t xEntryTimeSet = pdFALSE, xYieldRequired;
 810     TimeOut_t xTimeOut;
 811     Queue_t * const pxQueue = xQueue;
 812
 813     configASSERT( pxQueue );
 814     configASSERT( !( ( pvItemToQueue == NULL ) && ( pxQueue->uxItemSize != ( UBaseType_t ) 0U ) ) );
 815     configASSERT( !( ( xCopyPosition == queueOVERWRITE ) && ( pxQueue->uxLength != 1 ) ) );
 816     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
 817         {
 818             configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
 819         }
 820     #endif
 821
 822     /*lint -save -e904 This function relaxes the coding standard somewhat to
 823      * allow return statements within the function itself.  This is done in the
 824      * interest of execution time efficiency. */
 825     for( ; ; )
 826     {
 827         taskENTER_CRITICAL();
 828         {
 829             /* Is there room on the queue now?  The running task must be the
 830              * highest priority task wanting to access the queue.  If the head item
 831              * in the queue is to be overwritten then it does not matter if the
 832              * queue is full. */
 833             if( ( pxQueue->uxMessagesWaiting < pxQueue->uxLength ) || ( xCopyPosition == queueOVERWRITE ) )
 834             {
 835                 traceQUEUE_SEND( pxQueue );
 836
 837                 #if ( configUSE_QUEUE_SETS == 1 )
 838                     {
 839                         const UBaseType_t uxPreviousMessagesWaiting = pxQueue->uxMessagesWaiting;
 840
 841                         xYieldRequired = prvCopyDataToQueue( pxQueue, pvItemToQueue, xCopyPosition );
 842
 843                         if( pxQueue->pxQueueSetContainer != NULL )
 844                         {
 845                             if( ( xCopyPosition == queueOVERWRITE ) && ( uxPreviousMessagesWaiting != ( UBaseType_t ) 0 ) )
 846                             {
 847                                 /* Do not notify the queue set as an existing item
 848                                  * was overwritten in the queue so the number of items
 849                                  * in the queue has not changed. */
 850                                 mtCOVERAGE_TEST_MARKER();
 851                             }
 852                             else if( prvNotifyQueueSetContainer( pxQueue ) != pdFALSE )
 853                             {
 854                                 /* The queue is a member of a queue set, and posting
 855                                  * to the queue set caused a higher priority task to
 856                                  * unblock. A context switch is required. */
 857                                 queueYIELD_IF_USING_PREEMPTION();
 858                             }
 859                             else
 860                             {
 861                                 mtCOVERAGE_TEST_MARKER();
 862                             }
 863                         }
 864                         else
 865                         {
 866                             /* If there was a task waiting for data to arrive on the
 867                              * queue then unblock it now. */
 868                             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
 869                             {
 870                                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
 871                                 {
 872                                     /* The unblocked task has a priority higher than
 873                                      * our own so yield immediately.  Yes it is ok to
 874                                      * do this from within the critical section - the
 875                                      * kernel takes care of that. */
 876                                     queueYIELD_IF_USING_PREEMPTION();
 877                                 }
 878                                 else
 879                                 {
 880                                     mtCOVERAGE_TEST_MARKER();
 881                                 }
 882                             }
 883                             else if( xYieldRequired != pdFALSE )
 884                             {
 885                                 /* This path is a special case that will only get
 886                                  * executed if the task was holding multiple mutexes
 887                                  * and the mutexes were given back in an order that is
 888                                  * different to that in which they were taken. */
 889                                 queueYIELD_IF_USING_PREEMPTION();
 890                             }
 891                             else
 892                             {
 893                                 mtCOVERAGE_TEST_MARKER();
 894                             }
 895                         }
 896                     }
 897                 #else /* configUSE_QUEUE_SETS */
 898                     {
 899                         xYieldRequired = prvCopyDataToQueue( pxQueue, pvItemToQueue, xCopyPosition );
 900
 901                         /* If there was a task waiting for data to arrive on the
 902                          * queue then unblock it now. */
 903                         if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
 904                         {
 905                             if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
 906                             {
 907                                 /* The unblocked task has a priority higher than
 908                                  * our own so yield immediately.  Yes it is ok to do
 909                                  * this from within the critical section - the kernel
 910                                  * takes care of that. */
 911                                 queueYIELD_IF_USING_PREEMPTION();
 912                             }
 913                             else
 914                             {
 915                                 mtCOVERAGE_TEST_MARKER();
 916                             }
 917                         }
 918                         else if( xYieldRequired != pdFALSE )
 919                         {
 920                             /* This path is a special case that will only get
 921                              * executed if the task was holding multiple mutexes and
 922                              * the mutexes were given back in an order that is
 923                              * different to that in which they were taken. */
 924                             queueYIELD_IF_USING_PREEMPTION();
 925                         }
 926                         else
 927                         {
 928                             mtCOVERAGE_TEST_MARKER();
 929                         }
 930                     }
 931                 #endif /* configUSE_QUEUE_SETS */
 932
 933                 taskEXIT_CRITICAL();
 934                 return pdPASS;
 935             }
 936             else
 937             {
 938                 if( xTicksToWait == ( TickType_t ) 0 )
 939                 {
 940                     /* The queue was full and no block time is specified (or
 941                      * the block time has expired) so leave now. */
 942                     taskEXIT_CRITICAL();
 943
 944                     /* Return to the original privilege level before exiting
 945                      * the function. */
 946                     traceQUEUE_SEND_FAILED( pxQueue );
 947                     return errQUEUE_FULL;
 948                 }
 949                 else if( xEntryTimeSet == pdFALSE )
 950                 {
 951                     /* The queue was full and a block time was specified so
 952                      * configure the timeout structure. */
 953                     vTaskInternalSetTimeOutState( &xTimeOut );
 954                     xEntryTimeSet = pdTRUE;
 955                 }
 956                 else
 957                 {
 958                     /* Entry time was already set. */
 959                     mtCOVERAGE_TEST_MARKER();
 960                 }
 961             }
 962         }
 963         taskEXIT_CRITICAL();
 964
 965         /* Interrupts and other tasks can send to and receive from the queue
 966          * now the critical section has been exited. */
 967
 968         vTaskSuspendAll();
 969         prvLockQueue( pxQueue );
 970
 971         /* Update the timeout state to see if it has expired yet. */
 972         if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )
 973         {
 974             if( prvIsQueueFull( pxQueue ) != pdFALSE )
 975             {
 976                 traceBLOCKING_ON_QUEUE_SEND( pxQueue );
 977                 vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToSend ), xTicksToWait );
 978
 979                 /* Unlocking the queue means queue events can effect the
 980                  * event list. It is possible that interrupts occurring now
 981                  * remove this task from the event list again - but as the
 982                  * scheduler is suspended the task will go onto the pending
 983                  * ready list instead of the actual ready list. */
 984                 prvUnlockQueue( pxQueue );
 985
 986                 /* Resuming the scheduler will move tasks from the pending
 987                  * ready list into the ready list - so it is feasible that this
 988                  * task is already in the ready list before it yields - in which
 989                  * case the yield will not cause a context switch unless there
 990                  * is also a higher priority task in the pending ready list. */
 991                 if( xTaskResumeAll() == pdFALSE )
 992                 {
 993                     portYIELD_WITHIN_API();
 994                 }
 995             }
 996             else
 997             {
 998                 /* Try again. */
 999                 prvUnlockQueue( pxQueue );
1000                 ( void ) xTaskResumeAll();
1001             }
1002         }
1003         else
1004         {
1005             /* The timeout has expired. */
1006             prvUnlockQueue( pxQueue );
1007             ( void ) xTaskResumeAll();
1008
1009             traceQUEUE_SEND_FAILED( pxQueue );
1010             return errQUEUE_FULL;
1011         }
1012     } /*lint -restore */
1013 }
1014 /*-----------------------------------------------------------*/
1015
1016 BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue,
1017                                      const void * const pvItemToQueue,
1018                                      BaseType_t * const pxHigherPriorityTaskWoken,
1019                                      const BaseType_t xCopyPosition )
1020 {
1021     BaseType_t xReturn;
1022     UBaseType_t uxSavedInterruptStatus;
1023     Queue_t * const pxQueue = xQueue;
1024
1025     configASSERT( pxQueue );
1026     configASSERT( !( ( pvItemToQueue == NULL ) && ( pxQueue->uxItemSize != ( UBaseType_t ) 0U ) ) );
1027     configASSERT( !( ( xCopyPosition == queueOVERWRITE ) && ( pxQueue->uxLength != 1 ) ) );
1028
1029     /* RTOS ports that support interrupt nesting have the concept of a maximum
1030      * system call (or maximum API call) interrupt priority.  Interrupts that are
1031      * above the maximum system call priority are kept permanently enabled, even
1032      * when the RTOS kernel is in a critical section, but cannot make any calls to
1033      * FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h
1034      * then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion
1035      * failure if a FreeRTOS API function is called from an interrupt that has been
1036      * assigned a priority above the configured maximum system call priority.
1037      * Only FreeRTOS functions that end in FromISR can be called from interrupts
1038      * that have been assigned a priority at or (logically) below the maximum
1039      * system call interrupt priority.  FreeRTOS maintains a separate interrupt
1040      * safe API to ensure interrupt entry is as fast and as simple as possible.
1041      * More information (albeit Cortex-M specific) is provided on the following
1042      * link: https://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html */
1043     portASSERT_IF_INTERRUPT_PRIORITY_INVALID();
1044
1045     /* Similar to xQueueGenericSend, except without blocking if there is no room
1046      * in the queue.  Also don't directly wake a task that was blocked on a queue
1047      * read, instead return a flag to say whether a context switch is required or
1048      * not (i.e. has a task with a higher priority than us been woken by this
1049      * post). */
1050     uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
1051     {
1052         if( ( pxQueue->uxMessagesWaiting < pxQueue->uxLength ) || ( xCopyPosition == queueOVERWRITE ) )
1053         {
1054             const int8_t cTxLock = pxQueue->cTxLock;
1055             const UBaseType_t uxPreviousMessagesWaiting = pxQueue->uxMessagesWaiting;
1056
1057             traceQUEUE_SEND_FROM_ISR( pxQueue );
1058
1059             /* Semaphores use xQueueGiveFromISR(), so pxQueue will not be a
1060              *  semaphore or mutex.  That means prvCopyDataToQueue() cannot result
1061              *  in a task disinheriting a priority and prvCopyDataToQueue() can be
1062              *  called here even though the disinherit function does not check if
1063              *  the scheduler is suspended before accessing the ready lists. */
1064             ( void ) prvCopyDataToQueue( pxQueue, pvItemToQueue, xCopyPosition );
1065
1066             /* The event list is not altered if the queue is locked.  This will
1067              * be done when the queue is unlocked later. */
1068             if( cTxLock == queueUNLOCKED )
1069             {
1070                 #if ( configUSE_QUEUE_SETS == 1 )
1071                     {
1072                         if( pxQueue->pxQueueSetContainer != NULL )
1073                         {
1074                             if( ( xCopyPosition == queueOVERWRITE ) && ( uxPreviousMessagesWaiting != ( UBaseType_t ) 0 ) )
1075                             {
1076                                 /* Do not notify the queue set as an existing item
1077                                  * was overwritten in the queue so the number of items
1078                                  * in the queue has not changed. */
1079                                 mtCOVERAGE_TEST_MARKER();
1080                             }
1081                             else if( prvNotifyQueueSetContainer( pxQueue ) != pdFALSE )
1082                             {
1083                                 /* The queue is a member of a queue set, and posting
1084                                  * to the queue set caused a higher priority task to
1085                                  * unblock.  A context switch is required. */
1086                                 if( pxHigherPriorityTaskWoken != NULL )
1087                                 {
1088                                     *pxHigherPriorityTaskWoken = pdTRUE;
1089                                 }
1090                                 else
1091                                 {
1092                                     mtCOVERAGE_TEST_MARKER();
1093                                 }
1094                             }
1095                             else
1096                             {
1097                                 mtCOVERAGE_TEST_MARKER();
1098                             }
1099                         }
1100                         else
1101                         {
1102                             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
1103                             {
1104                                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
1105                                 {
1106                                     /* The task waiting has a higher priority so
1107                                      *  record that a context switch is required. */
1108                                     if( pxHigherPriorityTaskWoken != NULL )
1109                                     {
1110                                         *pxHigherPriorityTaskWoken = pdTRUE;
1111                                     }
1112                                     else
1113                                     {
1114                                         mtCOVERAGE_TEST_MARKER();
1115                                     }
1116                                 }
1117                                 else
1118                                 {
1119                                     mtCOVERAGE_TEST_MARKER();
1120                                 }
1121                             }
1122                             else
1123                             {
1124                                 mtCOVERAGE_TEST_MARKER();
1125                             }
1126                         }
1127                     }
1128                 #else /* configUSE_QUEUE_SETS */
1129                     {
1130                         if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
1131                         {
1132                             if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
1133                             {
1134                                 /* The task waiting has a higher priority so record that a
1135                                  * context switch is required. */
1136                                 if( pxHigherPriorityTaskWoken != NULL )
1137                                 {
1138                                     *pxHigherPriorityTaskWoken = pdTRUE;
1139                                 }
1140                                 else
1141                                 {
1142                                     mtCOVERAGE_TEST_MARKER();
1143                                 }
1144                             }
1145                             else
1146                             {
1147                                 mtCOVERAGE_TEST_MARKER();
1148                             }
1149                         }
1150                         else
1151                         {
1152                             mtCOVERAGE_TEST_MARKER();
1153                         }
1154
1155                         /* Not used in this path. */
1156                         ( void ) uxPreviousMessagesWaiting;
1157                     }
1158                 #endif /* configUSE_QUEUE_SETS */
1159             }
1160             else
1161             {
1162                 /* Increment the lock count so the task that unlocks the queue
1163                  * knows that data was posted while it was locked. */
1164                 configASSERT( cTxLock != queueINT8_MAX );
1165
1166                 pxQueue->cTxLock = ( int8_t ) ( cTxLock + 1 );
1167             }
1168
1169             xReturn = pdPASS;
1170         }
1171         else
1172         {
1173             traceQUEUE_SEND_FROM_ISR_FAILED( pxQueue );
1174             xReturn = errQUEUE_FULL;
1175         }
1176     }
1177     portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
1178
1179     return xReturn;
1180 }
1181 /*-----------------------------------------------------------*/
1182
1183 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue,
1184                               BaseType_t * const pxHigherPriorityTaskWoken )
1185 {
1186     BaseType_t xReturn;
1187     UBaseType_t uxSavedInterruptStatus;
1188     Queue_t * const pxQueue = xQueue;
1189
1190     /* Similar to xQueueGenericSendFromISR() but used with semaphores where the
1191      * item size is 0.  Don't directly wake a task that was blocked on a queue
1192      * read, instead return a flag to say whether a context switch is required or
1193      * not (i.e. has a task with a higher priority than us been woken by this
1194      * post). */
1195
1196     configASSERT( pxQueue );
1197
1198     /* xQueueGenericSendFromISR() should be used instead of xQueueGiveFromISR()
1199      * if the item size is not 0. */
1200     configASSERT( pxQueue->uxItemSize == 0 );
1201
1202     /* Normally a mutex would not be given from an interrupt, especially if
1203      * there is a mutex holder, as priority inheritance makes no sense for an
1204      * interrupts, only tasks. */
1205     configASSERT( !( ( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX ) && ( pxQueue->u.xSemaphore.xMutexHolder != NULL ) ) );
1206
1207     /* RTOS ports that support interrupt nesting have the concept of a maximum
1208      * system call (or maximum API call) interrupt priority.  Interrupts that are
1209      * above the maximum system call priority are kept permanently enabled, even
1210      * when the RTOS kernel is in a critical section, but cannot make any calls to
1211      * FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h
1212      * then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion
1213      * failure if a FreeRTOS API function is called from an interrupt that has been
1214      * assigned a priority above the configured maximum system call priority.
1215      * Only FreeRTOS functions that end in FromISR can be called from interrupts
1216      * that have been assigned a priority at or (logically) below the maximum
1217      * system call interrupt priority.  FreeRTOS maintains a separate interrupt
1218      * safe API to ensure interrupt entry is as fast and as simple as possible.
1219      * More information (albeit Cortex-M specific) is provided on the following
1220      * link: https://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html */
1221     portASSERT_IF_INTERRUPT_PRIORITY_INVALID();
1222
1223     uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
1224     {
1225         const UBaseType_t uxMessagesWaiting = pxQueue->uxMessagesWaiting;
1226
1227         /* When the queue is used to implement a semaphore no data is ever
1228          * moved through the queue but it is still valid to see if the queue 'has
1229          * space'. */
1230         if( uxMessagesWaiting < pxQueue->uxLength )
1231         {
1232             const int8_t cTxLock = pxQueue->cTxLock;
1233
1234             traceQUEUE_SEND_FROM_ISR( pxQueue );
1235
1236             /* A task can only have an inherited priority if it is a mutex
1237              * holder - and if there is a mutex holder then the mutex cannot be
1238              * given from an ISR.  As this is the ISR version of the function it
1239              * can be assumed there is no mutex holder and no need to determine if
1240              * priority disinheritance is needed.  Simply increase the count of
1241              * messages (semaphores) available. */
1242             pxQueue->uxMessagesWaiting = uxMessagesWaiting + ( UBaseType_t ) 1;
1243
1244             /* The event list is not altered if the queue is locked.  This will
1245              * be done when the queue is unlocked later. */
1246             if( cTxLock == queueUNLOCKED )
1247             {
1248                 #if ( configUSE_QUEUE_SETS == 1 )
1249                     {
1250                         if( pxQueue->pxQueueSetContainer != NULL )
1251                         {
1252                             if( prvNotifyQueueSetContainer( pxQueue ) != pdFALSE )
1253                             {
1254                                 /* The semaphore is a member of a queue set, and
1255                                  * posting to the queue set caused a higher priority
1256                                  * task to unblock.  A context switch is required. */
1257                                 if( pxHigherPriorityTaskWoken != NULL )
1258                                 {
1259                                     *pxHigherPriorityTaskWoken = pdTRUE;
1260                                 }
1261                                 else
1262                                 {
1263                                     mtCOVERAGE_TEST_MARKER();
1264                                 }
1265                             }
1266                             else
1267                             {
1268                                 mtCOVERAGE_TEST_MARKER();
1269                             }
1270                         }
1271                         else
1272                         {
1273                             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
1274                             {
1275                                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
1276                                 {
1277                                     /* The task waiting has a higher priority so
1278                                      *  record that a context switch is required. */
1279                                     if( pxHigherPriorityTaskWoken != NULL )
1280                                     {
1281                                         *pxHigherPriorityTaskWoken = pdTRUE;
1282                                     }
1283                                     else
1284                                     {
1285                                         mtCOVERAGE_TEST_MARKER();
1286                                     }
1287                                 }
1288                                 else
1289                                 {
1290                                     mtCOVERAGE_TEST_MARKER();
1291                                 }
1292                             }
1293                             else
1294                             {
1295                                 mtCOVERAGE_TEST_MARKER();
1296                             }
1297                         }
1298                     }
1299                 #else /* configUSE_QUEUE_SETS */
1300                     {
1301                         if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
1302                         {
1303                             if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
1304                             {
1305                                 /* The task waiting has a higher priority so record that a
1306                                  * context switch is required. */
1307                                 if( pxHigherPriorityTaskWoken != NULL )
1308                                 {
1309                                     *pxHigherPriorityTaskWoken = pdTRUE;
1310                                 }
1311                                 else
1312                                 {
1313                                     mtCOVERAGE_TEST_MARKER();
1314                                 }
1315                             }
1316                             else
1317                             {
1318                                 mtCOVERAGE_TEST_MARKER();
1319                             }
1320                         }
1321                         else
1322                         {
1323                             mtCOVERAGE_TEST_MARKER();
1324                         }
1325                     }
1326                 #endif /* configUSE_QUEUE_SETS */
1327             }
1328             else
1329             {
1330                 /* Increment the lock count so the task that unlocks the queue
1331                  * knows that data was posted while it was locked. */
1332                 configASSERT( cTxLock != queueINT8_MAX );
1333
1334                 pxQueue->cTxLock = ( int8_t ) ( cTxLock + 1 );
1335             }
1336
1337             xReturn = pdPASS;
1338         }
1339         else
1340         {
1341             traceQUEUE_SEND_FROM_ISR_FAILED( pxQueue );
1342             xReturn = errQUEUE_FULL;
1343         }
1344     }
1345     portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
1346
1347     return xReturn;
1348 }
1349 /*-----------------------------------------------------------*/
1350
1351 BaseType_t xQueueReceive( QueueHandle_t xQueue,
1352                           void * const pvBuffer,
1353                           TickType_t xTicksToWait )
1354 {
1355     BaseType_t xEntryTimeSet = pdFALSE;
1356     TimeOut_t xTimeOut;
1357     Queue_t * const pxQueue = xQueue;
1358
1359     /* Check the pointer is not NULL. */
1360     configASSERT( ( pxQueue ) );
1361
1362     /* The buffer into which data is received can only be NULL if the data size
1363      * is zero (so no data is copied into the buffer). */
1364     configASSERT( !( ( ( pvBuffer ) == NULL ) && ( ( pxQueue )->uxItemSize != ( UBaseType_t ) 0U ) ) );
1365
1366     /* Cannot block if the scheduler is suspended. */
1367     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
1368         {
1369             configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
1370         }
1371     #endif
1372
1373     /*lint -save -e904  This function relaxes the coding standard somewhat to
1374      * allow return statements within the function itself.  This is done in the
1375      * interest of execution time efficiency. */
1376     for( ; ; )
1377     {
1378         taskENTER_CRITICAL();
1379         {
1380             const UBaseType_t uxMessagesWaiting = pxQueue->uxMessagesWaiting;
1381
1382             /* Is there data in the queue now?  To be running the calling task
1383              * must be the highest priority task wanting to access the queue. */
1384             if( uxMessagesWaiting > ( UBaseType_t ) 0 )
1385             {
1386                 /* Data available, remove one item. */
1387                 prvCopyDataFromQueue( pxQueue, pvBuffer );
1388                 traceQUEUE_RECEIVE( pxQueue );
1389                 pxQueue->uxMessagesWaiting = uxMessagesWaiting - ( UBaseType_t ) 1;
1390
1391                 /* There is now space in the queue, were any tasks waiting to
1392                  * post to the queue?  If so, unblock the highest priority waiting
1393                  * task. */
1394                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
1395                 {
1396                     if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
1397                     {
1398                         queueYIELD_IF_USING_PREEMPTION();
1399                     }
1400                     else
1401                     {
1402                         mtCOVERAGE_TEST_MARKER();
1403                     }
1404                 }
1405                 else
1406                 {
1407                     mtCOVERAGE_TEST_MARKER();
1408                 }
1409
1410                 taskEXIT_CRITICAL();
1411                 return pdPASS;
1412             }
1413             else
1414             {
1415                 if( xTicksToWait == ( TickType_t ) 0 )
1416                 {
1417                     /* The queue was empty and no block time is specified (or
1418                      * the block time has expired) so leave now. */
1419                     taskEXIT_CRITICAL();
1420                     traceQUEUE_RECEIVE_FAILED( pxQueue );
1421                     return errQUEUE_EMPTY;
1422                 }
1423                 else if( xEntryTimeSet == pdFALSE )
1424                 {
1425                     /* The queue was empty and a block time was specified so
1426                      * configure the timeout structure. */
1427                     vTaskInternalSetTimeOutState( &xTimeOut );
1428                     xEntryTimeSet = pdTRUE;
1429                 }
1430                 else
1431                 {
1432                     /* Entry time was already set. */
1433                     mtCOVERAGE_TEST_MARKER();
1434                 }
1435             }
1436         }
1437         taskEXIT_CRITICAL();
1438
1439         /* Interrupts and other tasks can send to and receive from the queue
1440          * now the critical section has been exited. */
1441
1442         vTaskSuspendAll();
1443         prvLockQueue( pxQueue );
1444
1445         /* Update the timeout state to see if it has expired yet. */
1446         if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )
1447         {
1448             /* The timeout has not expired.  If the queue is still empty place
1449              * the task on the list of tasks waiting to receive from the queue. */
1450             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1451             {
1452                 traceBLOCKING_ON_QUEUE_RECEIVE( pxQueue );
1453                 vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait );
1454                 prvUnlockQueue( pxQueue );
1455
1456                 if( xTaskResumeAll() == pdFALSE )
1457                 {
1458                     portYIELD_WITHIN_API();
1459                 }
1460                 else
1461                 {
1462                     mtCOVERAGE_TEST_MARKER();
1463                 }
1464             }
1465             else
1466             {
1467                 /* The queue contains data again.  Loop back to try and read the
1468                  * data. */
1469                 prvUnlockQueue( pxQueue );
1470                 ( void ) xTaskResumeAll();
1471             }
1472         }
1473         else
1474         {
1475             /* Timed out.  If there is no data in the queue exit, otherwise loop
1476              * back and attempt to read the data. */
1477             prvUnlockQueue( pxQueue );
1478             ( void ) xTaskResumeAll();
1479
1480             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1481             {
1482                 traceQUEUE_RECEIVE_FAILED( pxQueue );
1483                 return errQUEUE_EMPTY;
1484             }
1485             else
1486             {
1487                 mtCOVERAGE_TEST_MARKER();
1488             }
1489         }
1490     } /*lint -restore */
1491 }
1492 /*-----------------------------------------------------------*/
1493
1494 BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue,
1495                                 TickType_t xTicksToWait )
1496 {
1497     BaseType_t xEntryTimeSet = pdFALSE;
1498     TimeOut_t xTimeOut;
1499     Queue_t * const pxQueue = xQueue;
1500
1501     #if ( configUSE_MUTEXES == 1 )
1502         BaseType_t xInheritanceOccurred = pdFALSE;
1503     #endif
1504
1505     /* Check the queue pointer is not NULL. */
1506     configASSERT( ( pxQueue ) );
1507
1508     /* Check this really is a semaphore, in which case the item size will be
1509      * 0. */
1510     configASSERT( pxQueue->uxItemSize == 0 );
1511
1512     /* Cannot block if the scheduler is suspended. */
1513     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
1514         {
1515             configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
1516         }
1517     #endif
1518
1519     /*lint -save -e904 This function relaxes the coding standard somewhat to allow return
1520      * statements within the function itself.  This is done in the interest
1521      * of execution time efficiency. */
1522     for( ; ; )
1523     {
1524         taskENTER_CRITICAL();
1525         {
1526             /* Semaphores are queues with an item size of 0, and where the
1527              * number of messages in the queue is the semaphore's count value. */
1528             const UBaseType_t uxSemaphoreCount = pxQueue->uxMessagesWaiting;
1529
1530             /* Is there data in the queue now?  To be running the calling task
1531              * must be the highest priority task wanting to access the queue. */
1532             if( uxSemaphoreCount > ( UBaseType_t ) 0 )
1533             {
1534                 traceQUEUE_RECEIVE( pxQueue );
1535
1536                 /* Semaphores are queues with a data size of zero and where the
1537                  * messages waiting is the semaphore's count.  Reduce the count. */
1538                 pxQueue->uxMessagesWaiting = uxSemaphoreCount - ( UBaseType_t ) 1;
1539
1540                 #if ( configUSE_MUTEXES == 1 )
1541                     {
1542                         if( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX )
1543                         {
1544                             /* Record the information required to implement
1545                              * priority inheritance should it become necessary. */
1546                             pxQueue->u.xSemaphore.xMutexHolder = pvTaskIncrementMutexHeldCount();
1547                         }
1548                         else
1549                         {
1550                             mtCOVERAGE_TEST_MARKER();
1551                         }
1552                     }
1553                 #endif /* configUSE_MUTEXES */
1554
1555                 /* Check to see if other tasks are blocked waiting to give the
1556                  * semaphore, and if so, unblock the highest priority such task. */
1557                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
1558                 {
1559                     if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
1560                     {
1561                         queueYIELD_IF_USING_PREEMPTION();
1562                     }
1563                     else
1564                     {
1565                         mtCOVERAGE_TEST_MARKER();
1566                     }
1567                 }
1568                 else
1569                 {
1570                     mtCOVERAGE_TEST_MARKER();
1571                 }
1572
1573                 taskEXIT_CRITICAL();
1574                 return pdPASS;
1575             }
1576             else
1577             {
1578                 if( xTicksToWait == ( TickType_t ) 0 )
1579                 {
1580                     /* For inheritance to have occurred there must have been an
1581                      * initial timeout, and an adjusted timeout cannot become 0, as
1582                      * if it were 0 the function would have exited. */
1583                     #if ( configUSE_MUTEXES == 1 )
1584                         {
1585                             configASSERT( xInheritanceOccurred == pdFALSE );
1586                         }
1587                     #endif /* configUSE_MUTEXES */
1588
1589                     /* The semaphore count was 0 and no block time is specified
1590                      * (or the block time has expired) so exit now. */
1591                     taskEXIT_CRITICAL();
1592                     traceQUEUE_RECEIVE_FAILED( pxQueue );
1593                     return errQUEUE_EMPTY;
1594                 }
1595                 else if( xEntryTimeSet == pdFALSE )
1596                 {
1597                     /* The semaphore count was 0 and a block time was specified
1598                      * so configure the timeout structure ready to block. */
1599                     vTaskInternalSetTimeOutState( &xTimeOut );
1600                     xEntryTimeSet = pdTRUE;
1601                 }
1602                 else
1603                 {
1604                     /* Entry time was already set. */
1605                     mtCOVERAGE_TEST_MARKER();
1606                 }
1607             }
1608         }
1609         taskEXIT_CRITICAL();
1610
1611         /* Interrupts and other tasks can give to and take from the semaphore
1612          * now the critical section has been exited. */
1613
1614         vTaskSuspendAll();
1615         prvLockQueue( pxQueue );
1616
1617         /* Update the timeout state to see if it has expired yet. */
1618         if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )
1619         {
1620             /* A block time is specified and not expired.  If the semaphore
1621              * count is 0 then enter the Blocked state to wait for a semaphore to
1622              * become available.  As semaphores are implemented with queues the
1623              * queue being empty is equivalent to the semaphore count being 0. */
1624             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1625             {
1626                 traceBLOCKING_ON_QUEUE_RECEIVE( pxQueue );
1627
1628                 #if ( configUSE_MUTEXES == 1 )
1629                     {
1630                         if( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX )
1631                         {
1632                             taskENTER_CRITICAL();
1633                             {
1634                                 xInheritanceOccurred = xTaskPriorityInherit( pxQueue->u.xSemaphore.xMutexHolder );
1635                             }
1636                             taskEXIT_CRITICAL();
1637                         }
1638                         else
1639                         {
1640                             mtCOVERAGE_TEST_MARKER();
1641                         }
1642                     }
1643                 #endif /* if ( configUSE_MUTEXES == 1 ) */
1644
1645                 vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait );
1646                 prvUnlockQueue( pxQueue );
1647
1648                 if( xTaskResumeAll() == pdFALSE )
1649                 {
1650                     portYIELD_WITHIN_API();
1651                 }
1652                 else
1653                 {
1654                     mtCOVERAGE_TEST_MARKER();
1655                 }
1656             }
1657             else
1658             {
1659                 /* There was no timeout and the semaphore count was not 0, so
1660                  * attempt to take the semaphore again. */
1661                 prvUnlockQueue( pxQueue );
1662                 ( void ) xTaskResumeAll();
1663             }
1664         }
1665         else
1666         {
1667             /* Timed out. */
1668             prvUnlockQueue( pxQueue );
1669             ( void ) xTaskResumeAll();
1670
1671             /* If the semaphore count is 0 exit now as the timeout has
1672              * expired.  Otherwise return to attempt to take the semaphore that is
1673              * known to be available.  As semaphores are implemented by queues the
1674              * queue being empty is equivalent to the semaphore count being 0. */
1675             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1676             {
1677                 #if ( configUSE_MUTEXES == 1 )
1678                     {
1679                         /* xInheritanceOccurred could only have be set if
1680                          * pxQueue->uxQueueType == queueQUEUE_IS_MUTEX so no need to
1681                          * test the mutex type again to check it is actually a mutex. */
1682                         if( xInheritanceOccurred != pdFALSE )
1683                         {
1684                             taskENTER_CRITICAL();
1685                             {
1686                                 UBaseType_t uxHighestWaitingPriority;
1687
1688                                 /* This task blocking on the mutex caused another
1689                                  * task to inherit this task's priority.  Now this task
1690                                  * has timed out the priority should be disinherited
1691                                  * again, but only as low as the next highest priority
1692                                  * task that is waiting for the same mutex. */
1693                                 uxHighestWaitingPriority = prvGetDisinheritPriorityAfterTimeout( pxQueue );
1694                                 vTaskPriorityDisinheritAfterTimeout( pxQueue->u.xSemaphore.xMutexHolder, uxHighestWaitingPriority );
1695                             }
1696                             taskEXIT_CRITICAL();
1697                         }
1698                     }
1699                 #endif /* configUSE_MUTEXES */
1700
1701                 traceQUEUE_RECEIVE_FAILED( pxQueue );
1702                 return errQUEUE_EMPTY;
1703             }
1704             else
1705             {
1706                 mtCOVERAGE_TEST_MARKER();
1707             }
1708         }
1709     } /*lint -restore */
1710 }
1711 /*-----------------------------------------------------------*/
1712
1713 BaseType_t xQueuePeek( QueueHandle_t xQueue,
1714                        void * const pvBuffer,
1715                        TickType_t xTicksToWait )
1716 {
1717     BaseType_t xEntryTimeSet = pdFALSE;
1718     TimeOut_t xTimeOut;
1719     int8_t * pcOriginalReadPosition;
1720     Queue_t * const pxQueue = xQueue;
1721
1722     /* Check the pointer is not NULL. */
1723     configASSERT( ( pxQueue ) );
1724
1725     /* The buffer into which data is received can only be NULL if the data size
1726      * is zero (so no data is copied into the buffer. */
1727     configASSERT( !( ( ( pvBuffer ) == NULL ) && ( ( pxQueue )->uxItemSize != ( UBaseType_t ) 0U ) ) );
1728
1729     /* Cannot block if the scheduler is suspended. */
1730     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
1731         {
1732             configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
1733         }
1734     #endif
1735
1736     /*lint -save -e904  This function relaxes the coding standard somewhat to
1737      * allow return statements within the function itself.  This is done in the
1738      * interest of execution time efficiency. */
1739     for( ; ; )
1740     {
1741         taskENTER_CRITICAL();
1742         {
1743             const UBaseType_t uxMessagesWaiting = pxQueue->uxMessagesWaiting;
1744
1745             /* Is there data in the queue now?  To be running the calling task
1746              * must be the highest priority task wanting to access the queue. */
1747             if( uxMessagesWaiting > ( UBaseType_t ) 0 )
1748             {
1749                 /* Remember the read position so it can be reset after the data
1750                  * is read from the queue as this function is only peeking the
1751                  * data, not removing it. */
1752                 pcOriginalReadPosition = pxQueue->u.xQueue.pcReadFrom;
1753
1754                 prvCopyDataFromQueue( pxQueue, pvBuffer );
1755                 traceQUEUE_PEEK( pxQueue );
1756
1757                 /* The data is not being removed, so reset the read pointer. */
1758                 pxQueue->u.xQueue.pcReadFrom = pcOriginalReadPosition;
1759
1760                 /* The data is being left in the queue, so see if there are
1761                  * any other tasks waiting for the data. */
1762                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
1763                 {
1764                     if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
1765                     {
1766                         /* The task waiting has a higher priority than this task. */
1767                         queueYIELD_IF_USING_PREEMPTION();
1768                     }
1769                     else
1770                     {
1771                         mtCOVERAGE_TEST_MARKER();
1772                     }
1773                 }
1774                 else
1775                 {
1776                     mtCOVERAGE_TEST_MARKER();
1777                 }
1778
1779                 taskEXIT_CRITICAL();
1780                 return pdPASS;
1781             }
1782             else
1783             {
1784                 if( xTicksToWait == ( TickType_t ) 0 )
1785                 {
1786                     /* The queue was empty and no block time is specified (or
1787                      * the block time has expired) so leave now. */
1788                     taskEXIT_CRITICAL();
1789                     traceQUEUE_PEEK_FAILED( pxQueue );
1790                     return errQUEUE_EMPTY;
1791                 }
1792                 else if( xEntryTimeSet == pdFALSE )
1793                 {
1794                     /* The queue was empty and a block time was specified so
1795                      * configure the timeout structure ready to enter the blocked
1796                      * state. */
1797                     vTaskInternalSetTimeOutState( &xTimeOut );
1798                     xEntryTimeSet = pdTRUE;
1799                 }
1800                 else
1801                 {
1802                     /* Entry time was already set. */
1803                     mtCOVERAGE_TEST_MARKER();
1804                 }
1805             }
1806         }
1807         taskEXIT_CRITICAL();
1808
1809         /* Interrupts and other tasks can send to and receive from the queue
1810          * now that the critical section has been exited. */
1811
1812         vTaskSuspendAll();
1813         prvLockQueue( pxQueue );
1814
1815         /* Update the timeout state to see if it has expired yet. */
1816         if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )
1817         {
1818             /* Timeout has not expired yet, check to see if there is data in the
1819             * queue now, and if not enter the Blocked state to wait for data. */
1820             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1821             {
1822                 traceBLOCKING_ON_QUEUE_PEEK( pxQueue );
1823                 vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait );
1824                 prvUnlockQueue( pxQueue );
1825
1826                 if( xTaskResumeAll() == pdFALSE )
1827                 {
1828                     portYIELD_WITHIN_API();
1829                 }
1830                 else
1831                 {
1832                     mtCOVERAGE_TEST_MARKER();
1833                 }
1834             }
1835             else
1836             {
1837                 /* There is data in the queue now, so don't enter the blocked
1838                  * state, instead return to try and obtain the data. */
1839                 prvUnlockQueue( pxQueue );
1840                 ( void ) xTaskResumeAll();
1841             }
1842         }
1843         else
1844         {
1845             /* The timeout has expired.  If there is still no data in the queue
1846              * exit, otherwise go back and try to read the data again. */
1847             prvUnlockQueue( pxQueue );
1848             ( void ) xTaskResumeAll();
1849
1850             if( prvIsQueueEmpty( pxQueue ) != pdFALSE )
1851             {
1852                 traceQUEUE_PEEK_FAILED( pxQueue );
1853                 return errQUEUE_EMPTY;
1854             }
1855             else
1856             {
1857                 mtCOVERAGE_TEST_MARKER();
1858             }
1859         }
1860     } /*lint -restore */
1861 }
1862 /*-----------------------------------------------------------*/
1863
1864 BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,
1865                                  void * const pvBuffer,
1866                                  BaseType_t * const pxHigherPriorityTaskWoken )
1867 {
1868     BaseType_t xReturn;
1869     UBaseType_t uxSavedInterruptStatus;
1870     Queue_t * const pxQueue = xQueue;
1871
1872     configASSERT( pxQueue );
1873     configASSERT( !( ( pvBuffer == NULL ) && ( pxQueue->uxItemSize != ( UBaseType_t ) 0U ) ) );
1874
1875     /* RTOS ports that support interrupt nesting have the concept of a maximum
1876      * system call (or maximum API call) interrupt priority.  Interrupts that are
1877      * above the maximum system call priority are kept permanently enabled, even
1878      * when the RTOS kernel is in a critical section, but cannot make any calls to
1879      * FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h
1880      * then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion
1881      * failure if a FreeRTOS API function is called from an interrupt that has been
1882      * assigned a priority above the configured maximum system call priority.
1883      * Only FreeRTOS functions that end in FromISR can be called from interrupts
1884      * that have been assigned a priority at or (logically) below the maximum
1885      * system call interrupt priority.  FreeRTOS maintains a separate interrupt
1886      * safe API to ensure interrupt entry is as fast and as simple as possible.
1887      * More information (albeit Cortex-M specific) is provided on the following
1888      * link: https://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html */
1889     portASSERT_IF_INTERRUPT_PRIORITY_INVALID();
1890
1891     uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
1892     {
1893         const UBaseType_t uxMessagesWaiting = pxQueue->uxMessagesWaiting;
1894
1895         /* Cannot block in an ISR, so check there is data available. */
1896         if( uxMessagesWaiting > ( UBaseType_t ) 0 )
1897         {
1898             const int8_t cRxLock = pxQueue->cRxLock;
1899
1900             traceQUEUE_RECEIVE_FROM_ISR( pxQueue );
1901
1902             prvCopyDataFromQueue( pxQueue, pvBuffer );
1903             pxQueue->uxMessagesWaiting = uxMessagesWaiting - ( UBaseType_t ) 1;
1904
1905             /* If the queue is locked the event list will not be modified.
1906              * Instead update the lock count so the task that unlocks the queue
1907              * will know that an ISR has removed data while the queue was
1908              * locked. */
1909             if( cRxLock == queueUNLOCKED )
1910             {
1911                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
1912                 {
1913                     if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
1914                     {
1915                         /* The task waiting has a higher priority than us so
1916                          * force a context switch. */
1917                         if( pxHigherPriorityTaskWoken != NULL )
1918                         {
1919                             *pxHigherPriorityTaskWoken = pdTRUE;
1920                         }
1921                         else
1922                         {
1923                             mtCOVERAGE_TEST_MARKER();
1924                         }
1925                     }
1926                     else
1927                     {
1928                         mtCOVERAGE_TEST_MARKER();
1929                     }
1930                 }
1931                 else
1932                 {
1933                     mtCOVERAGE_TEST_MARKER();
1934                 }
1935             }
1936             else
1937             {
1938                 /* Increment the lock count so the task that unlocks the queue
1939                  * knows that data was removed while it was locked. */
1940                 configASSERT( cRxLock != queueINT8_MAX );
1941
1942                 pxQueue->cRxLock = ( int8_t ) ( cRxLock + 1 );
1943             }
1944
1945             xReturn = pdPASS;
1946         }
1947         else
1948         {
1949             xReturn = pdFAIL;
1950             traceQUEUE_RECEIVE_FROM_ISR_FAILED( pxQueue );
1951         }
1952     }
1953     portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
1954
1955     return xReturn;
1956 }
1957 /*-----------------------------------------------------------*/
1958
1959 BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue,
1960                               void * const pvBuffer )
1961 {
1962     BaseType_t xReturn;
1963     UBaseType_t uxSavedInterruptStatus;
1964     int8_t * pcOriginalReadPosition;
1965     Queue_t * const pxQueue = xQueue;
1966
1967     configASSERT( pxQueue );
1968     configASSERT( !( ( pvBuffer == NULL ) && ( pxQueue->uxItemSize != ( UBaseType_t ) 0U ) ) );
1969     configASSERT( pxQueue->uxItemSize != 0 ); /* Can't peek a semaphore. */
1970
1971     /* RTOS ports that support interrupt nesting have the concept of a maximum
1972      * system call (or maximum API call) interrupt priority.  Interrupts that are
1973      * above the maximum system call priority are kept permanently enabled, even
1974      * when the RTOS kernel is in a critical section, but cannot make any calls to
1975      * FreeRTOS API functions.  If configASSERT() is defined in FreeRTOSConfig.h
1976      * then portASSERT_IF_INTERRUPT_PRIORITY_INVALID() will result in an assertion
1977      * failure if a FreeRTOS API function is called from an interrupt that has been
1978      * assigned a priority above the configured maximum system call priority.
1979      * Only FreeRTOS functions that end in FromISR can be called from interrupts
1980      * that have been assigned a priority at or (logically) below the maximum
1981      * system call interrupt priority.  FreeRTOS maintains a separate interrupt
1982      * safe API to ensure interrupt entry is as fast and as simple as possible.
1983      * More information (albeit Cortex-M specific) is provided on the following
1984      * link: https://www.FreeRTOS.org/RTOS-Cortex-M3-M4.html */
1985     portASSERT_IF_INTERRUPT_PRIORITY_INVALID();
1986
1987     uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
1988     {
1989         /* Cannot block in an ISR, so check there is data available. */
1990         if( pxQueue->uxMessagesWaiting > ( UBaseType_t ) 0 )
1991         {
1992             traceQUEUE_PEEK_FROM_ISR( pxQueue );
1993
1994             /* Remember the read position so it can be reset as nothing is
1995              * actually being removed from the queue. */
1996             pcOriginalReadPosition = pxQueue->u.xQueue.pcReadFrom;
1997             prvCopyDataFromQueue( pxQueue, pvBuffer );
1998             pxQueue->u.xQueue.pcReadFrom = pcOriginalReadPosition;
1999
2000             xReturn = pdPASS;
2001         }
2002         else
2003         {
2004             xReturn = pdFAIL;
2005             traceQUEUE_PEEK_FROM_ISR_FAILED( pxQueue );
2006         }
2007     }
2008     portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
2009
2010     return xReturn;
2011 }
2012 /*-----------------------------------------------------------*/
2013
2014 UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue )
2015 {
2016     UBaseType_t uxReturn;
2017
2018     configASSERT( xQueue );
2019
2020     taskENTER_CRITICAL();
2021     {
2022         uxReturn = ( ( Queue_t * ) xQueue )->uxMessagesWaiting;
2023     }
2024     taskEXIT_CRITICAL();
2025
2026     return uxReturn;
2027 } /*lint !e818 Pointer cannot be declared const as xQueue is a typedef not pointer. */
2028 /*-----------------------------------------------------------*/
2029
2030 UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue )
2031 {
2032     UBaseType_t uxReturn;
2033     Queue_t * const pxQueue = xQueue;
2034
2035     configASSERT( pxQueue );
2036
2037     taskENTER_CRITICAL();
2038     {
2039         uxReturn = pxQueue->uxLength - pxQueue->uxMessagesWaiting;
2040     }
2041     taskEXIT_CRITICAL();
2042
2043     return uxReturn;
2044 } /*lint !e818 Pointer cannot be declared const as xQueue is a typedef not pointer. */
2045 /*-----------------------------------------------------------*/
2046
2047 UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue )
2048 {
2049     UBaseType_t uxReturn;
2050     Queue_t * const pxQueue = xQueue;
2051
2052     configASSERT( pxQueue );
2053     uxReturn = pxQueue->uxMessagesWaiting;
2054
2055     return uxReturn;
2056 } /*lint !e818 Pointer cannot be declared const as xQueue is a typedef not pointer. */
2057 /*-----------------------------------------------------------*/
2058
2059 void vQueueDelete( QueueHandle_t xQueue )
2060 {
2061     Queue_t * const pxQueue = xQueue;
2062
2063     configASSERT( pxQueue );
2064     traceQUEUE_DELETE( pxQueue );
2065
2066     #if ( configQUEUE_REGISTRY_SIZE > 0 )
2067         {
2068             vQueueUnregisterQueue( pxQueue );
2069         }
2070     #endif
2071
2072     #if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 0 ) )
2073         {
2074             /* The queue can only have been allocated dynamically - free it
2075              * again. */
2076             vPortFree( pxQueue );
2077         }
2078     #elif ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
2079         {
2080             /* The queue could have been allocated statically or dynamically, so
2081              * check before attempting to free the memory. */
2082             if( pxQueue->ucStaticallyAllocated == ( uint8_t ) pdFALSE )
2083             {
2084                 vPortFree( pxQueue );
2085             }
2086             else
2087             {
2088                 mtCOVERAGE_TEST_MARKER();
2089             }
2090         }
2091     #else /* if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 0 ) ) */
2092         {
2093             /* The queue must have been statically allocated, so is not going to be
2094              * deleted.  Avoid compiler warnings about the unused parameter. */
2095             ( void ) pxQueue;
2096         }
2097     #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
2098 }
2099 /*-----------------------------------------------------------*/
2100
2101 #if ( configUSE_TRACE_FACILITY == 1 )
2102
2103     UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue )
2104     {
2105         return ( ( Queue_t * ) xQueue )->uxQueueNumber;
2106     }
2107
2108 #endif /* configUSE_TRACE_FACILITY */
2109 /*-----------------------------------------------------------*/
2110
2111 #if ( configUSE_TRACE_FACILITY == 1 )
2112
2113     void vQueueSetQueueNumber( QueueHandle_t xQueue,
2114                                UBaseType_t uxQueueNumber )
2115     {
2116         ( ( Queue_t * ) xQueue )->uxQueueNumber = uxQueueNumber;
2117     }
2118
2119 #endif /* configUSE_TRACE_FACILITY */
2120 /*-----------------------------------------------------------*/
2121
2122 #if ( configUSE_TRACE_FACILITY == 1 )
2123
2124     uint8_t ucQueueGetQueueType( QueueHandle_t xQueue )
2125     {
2126         return ( ( Queue_t * ) xQueue )->ucQueueType;
2127     }
2128
2129 #endif /* configUSE_TRACE_FACILITY */
2130 /*-----------------------------------------------------------*/
2131
2132 #if ( configUSE_MUTEXES == 1 )
2133
2134     static UBaseType_t prvGetDisinheritPriorityAfterTimeout( const Queue_t * const pxQueue )
2135     {
2136         UBaseType_t uxHighestPriorityOfWaitingTasks;
2137
2138         /* If a task waiting for a mutex causes the mutex holder to inherit a
2139          * priority, but the waiting task times out, then the holder should
2140          * disinherit the priority - but only down to the highest priority of any
2141          * other tasks that are waiting for the same mutex.  For this purpose,
2142          * return the priority of the highest priority task that is waiting for the
2143          * mutex. */
2144         if( listCURRENT_LIST_LENGTH( &( pxQueue->xTasksWaitingToReceive ) ) > 0U )
2145         {
2146             uxHighestPriorityOfWaitingTasks = ( UBaseType_t ) configMAX_PRIORITIES - ( UBaseType_t ) listGET_ITEM_VALUE_OF_HEAD_ENTRY( &( pxQueue->xTasksWaitingToReceive ) );
2147         }
2148         else
2149         {
2150             uxHighestPriorityOfWaitingTasks = tskIDLE_PRIORITY;
2151         }
2152
2153         return uxHighestPriorityOfWaitingTasks;
2154     }
2155
2156 #endif /* configUSE_MUTEXES */
2157 /*-----------------------------------------------------------*/
2158
2159 static BaseType_t prvCopyDataToQueue( Queue_t * const pxQueue,
2160                                       const void * pvItemToQueue,
2161                                       const BaseType_t xPosition )
2162 {
2163     BaseType_t xReturn = pdFALSE;
2164     UBaseType_t uxMessagesWaiting;
2165
2166     /* This function is called from a critical section. */
2167
2168     uxMessagesWaiting = pxQueue->uxMessagesWaiting;
2169
2170     if( pxQueue->uxItemSize == ( UBaseType_t ) 0 )
2171     {
2172         #if ( configUSE_MUTEXES == 1 )
2173             {
2174                 if( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX )
2175                 {
2176                     /* The mutex is no longer being held. */
2177                     xReturn = xTaskPriorityDisinherit( pxQueue->u.xSemaphore.xMutexHolder );
2178                     pxQueue->u.xSemaphore.xMutexHolder = NULL;
2179                 }
2180                 else
2181                 {
2182                     mtCOVERAGE_TEST_MARKER();
2183                 }
2184             }
2185         #endif /* configUSE_MUTEXES */
2186     }
2187     else if( xPosition == queueSEND_TO_BACK )
2188     {
2189         ( void ) memcpy( ( void * ) pxQueue->pcWriteTo, pvItemToQueue, ( size_t ) pxQueue->uxItemSize ); /*lint !e961 !e418 !e9087 MISRA exception as the casts are only redundant for some ports, plus previous logic ensures a null pointer can only be passed to memcpy() if the copy size is 0.  Cast to void required by function signature and safe as no alignment requirement and copy length specified in bytes. */
2190         pxQueue->pcWriteTo += pxQueue->uxItemSize;                                                       /*lint !e9016 Pointer arithmetic on char types ok, especially in this use case where it is the clearest way of conveying intent. */
2191
2192         if( pxQueue->pcWriteTo >= pxQueue->u.xQueue.pcTail )                                             /*lint !e946 MISRA exception justified as comparison of pointers is the cleanest solution. */
2193         {
2194             pxQueue->pcWriteTo = pxQueue->pcHead;
2195         }
2196         else
2197         {
2198             mtCOVERAGE_TEST_MARKER();
2199         }
2200     }
2201     else
2202     {
2203         ( void ) memcpy( ( void * ) pxQueue->u.xQueue.pcReadFrom, pvItemToQueue, ( size_t ) pxQueue->uxItemSize ); /*lint !e961 !e9087 !e418 MISRA exception as the casts are only redundant for some ports.  Cast to void required by function signature and safe as no alignment requirement and copy length specified in bytes.  Assert checks null pointer only used when length is 0. */
2204         pxQueue->u.xQueue.pcReadFrom -= pxQueue->uxItemSize;
2205
2206         if( pxQueue->u.xQueue.pcReadFrom < pxQueue->pcHead ) /*lint !e946 MISRA exception justified as comparison of pointers is the cleanest solution. */
2207         {
2208             pxQueue->u.xQueue.pcReadFrom = ( pxQueue->u.xQueue.pcTail - pxQueue->uxItemSize );
2209         }
2210         else
2211         {
2212             mtCOVERAGE_TEST_MARKER();
2213         }
2214
2215         if( xPosition == queueOVERWRITE )
2216         {
2217             if( uxMessagesWaiting > ( UBaseType_t ) 0 )
2218             {
2219                 /* An item is not being added but overwritten, so subtract
2220                  * one from the recorded number of items in the queue so when
2221                  * one is added again below the number of recorded items remains
2222                  * correct. */
2223                 --uxMessagesWaiting;
2224             }
2225             else
2226             {
2227                 mtCOVERAGE_TEST_MARKER();
2228             }
2229         }
2230         else
2231         {
2232             mtCOVERAGE_TEST_MARKER();
2233         }
2234     }
2235
2236     pxQueue->uxMessagesWaiting = uxMessagesWaiting + ( UBaseType_t ) 1;
2237
2238     return xReturn;
2239 }
2240 /*-----------------------------------------------------------*/
2241
2242 static void prvCopyDataFromQueue( Queue_t * const pxQueue,
2243                                   void * const pvBuffer )
2244 {
2245     if( pxQueue->uxItemSize != ( UBaseType_t ) 0 )
2246     {
2247         pxQueue->u.xQueue.pcReadFrom += pxQueue->uxItemSize;           /*lint !e9016 Pointer arithmetic on char types ok, especially in this use case where it is the clearest way of conveying intent. */
2248
2249         if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail ) /*lint !e946 MISRA exception justified as use of the relational operator is the cleanest solutions. */
2250         {
2251             pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2252         }
2253         else
2254         {
2255             mtCOVERAGE_TEST_MARKER();
2256         }
2257
2258         ( void ) memcpy( ( void * ) pvBuffer, ( void * ) pxQueue->u.xQueue.pcReadFrom, ( size_t ) pxQueue->uxItemSize ); /*lint !e961 !e418 !e9087 MISRA exception as the casts are only redundant for some ports.  Also previous logic ensures a null pointer can only be passed to memcpy() when the count is 0.  Cast to void required by function signature and safe as no alignment requirement and copy length specified in bytes. */
2259     }
2260 }
2261 /*-----------------------------------------------------------*/
2262
2263 static void prvUnlockQueue( Queue_t * const pxQueue )
2264 {
2265     /* THIS FUNCTION MUST BE CALLED WITH THE SCHEDULER SUSPENDED. */
2266
2267     /* The lock counts contains the number of extra data items placed or
2268      * removed from the queue while the queue was locked.  When a queue is
2269      * locked items can be added or removed, but the event lists cannot be
2270      * updated. */
2271     taskENTER_CRITICAL();
2272     {
2273         int8_t cTxLock = pxQueue->cTxLock;
2274
2275         /* See if data was added to the queue while it was locked. */
2276         while( cTxLock > queueLOCKED_UNMODIFIED )
2277         {
2278             /* Data was posted while the queue was locked.  Are any tasks
2279              * blocked waiting for data to become available? */
2280             #if ( configUSE_QUEUE_SETS == 1 )
2281                 {
2282                     if( pxQueue->pxQueueSetContainer != NULL )
2283                     {
2284                         if( prvNotifyQueueSetContainer( pxQueue ) != pdFALSE )
2285                         {
2286                             /* The queue is a member of a queue set, and posting to
2287                              * the queue set caused a higher priority task to unblock.
2288                              * A context switch is required. */
2289                             vTaskMissedYield();
2290                         }
2291                         else
2292                         {
2293                             mtCOVERAGE_TEST_MARKER();
2294                         }
2295                     }
2296                     else
2297                     {
2298                         /* Tasks that are removed from the event list will get
2299                          * added to the pending ready list as the scheduler is still
2300                          * suspended. */
2301                         if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2302                         {
2303                             if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2304                             {
2305                                 /* The task waiting has a higher priority so record that a
2306                                  * context switch is required. */
2307                                 vTaskMissedYield();
2308                             }
2309                             else
2310                             {
2311                                 mtCOVERAGE_TEST_MARKER();
2312                             }
2313                         }
2314                         else
2315                         {
2316                             break;
2317                         }
2318                     }
2319                 }
2320             #else /* configUSE_QUEUE_SETS */
2321                 {
2322                     /* Tasks that are removed from the event list will get added to
2323                      * the pending ready list as the scheduler is still suspended. */
2324                     if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2325                     {
2326                         if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2327                         {
2328                             /* The task waiting has a higher priority so record that
2329                              * a context switch is required. */
2330                             vTaskMissedYield();
2331                         }
2332                         else
2333                         {
2334                             mtCOVERAGE_TEST_MARKER();
2335                         }
2336                     }
2337                     else
2338                     {
2339                         break;
2340                     }
2341                 }
2342             #endif /* configUSE_QUEUE_SETS */
2343
2344             --cTxLock;
2345         }
2346
2347         pxQueue->cTxLock = queueUNLOCKED;
2348     }
2349     taskEXIT_CRITICAL();
2350
2351     /* Do the same for the Rx lock. */
2352     taskENTER_CRITICAL();
2353     {
2354         int8_t cRxLock = pxQueue->cRxLock;
2355
2356         while( cRxLock > queueLOCKED_UNMODIFIED )
2357         {
2358             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2359             {
2360                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2361                 {
2362                     vTaskMissedYield();
2363                 }
2364                 else
2365                 {
2366                     mtCOVERAGE_TEST_MARKER();
2367                 }
2368
2369                 --cRxLock;
2370             }
2371             else
2372             {
2373                 break;
2374             }
2375         }
2376
2377         pxQueue->cRxLock = queueUNLOCKED;
2378     }
2379     taskEXIT_CRITICAL();
2380 }
2381 /*-----------------------------------------------------------*/
2382
2383 static BaseType_t prvIsQueueEmpty( const Queue_t * pxQueue )
2384 {
2385     BaseType_t xReturn;
2386
2387     taskENTER_CRITICAL();
2388     {
2389         if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2390         {
2391             xReturn = pdTRUE;
2392         }
2393         else
2394         {
2395             xReturn = pdFALSE;
2396         }
2397     }
2398     taskEXIT_CRITICAL();
2399
2400     return xReturn;
2401 }
2402 /*-----------------------------------------------------------*/
2403
2404 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue )
2405 {
2406     BaseType_t xReturn;
2407     Queue_t * const pxQueue = xQueue;
2408
2409     configASSERT( pxQueue );
2410
2411     if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2412     {
2413         xReturn = pdTRUE;
2414     }
2415     else
2416     {
2417         xReturn = pdFALSE;
2418     }
2419
2420     return xReturn;
2421 } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2422 /*-----------------------------------------------------------*/
2423
2424 static BaseType_t prvIsQueueFull( const Queue_t * pxQueue )
2425 {
2426     BaseType_t xReturn;
2427
2428     taskENTER_CRITICAL();
2429     {
2430         if( pxQueue->uxMessagesWaiting == pxQueue->uxLength )
2431         {
2432             xReturn = pdTRUE;
2433         }
2434         else
2435         {
2436             xReturn = pdFALSE;
2437         }
2438     }
2439     taskEXIT_CRITICAL();
2440
2441     return xReturn;
2442 }
2443 /*-----------------------------------------------------------*/
2444
2445 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue )
2446 {
2447     BaseType_t xReturn;
2448     Queue_t * const pxQueue = xQueue;
2449
2450     configASSERT( pxQueue );
2451
2452     if( pxQueue->uxMessagesWaiting == pxQueue->uxLength )
2453     {
2454         xReturn = pdTRUE;
2455     }
2456     else
2457     {
2458         xReturn = pdFALSE;
2459     }
2460
2461     return xReturn;
2462 } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2463 /*-----------------------------------------------------------*/
2464
2465 #if ( configUSE_CO_ROUTINES == 1 )
2466
2467     BaseType_t xQueueCRSend( QueueHandle_t xQueue,
2468                              const void * pvItemToQueue,
2469                              TickType_t xTicksToWait )
2470     {
2471         BaseType_t xReturn;
2472         Queue_t * const pxQueue = xQueue;
2473
2474         /* If the queue is already full we may have to block.  A critical section
2475          * is required to prevent an interrupt removing something from the queue
2476          * between the check to see if the queue is full and blocking on the queue. */
2477         portDISABLE_INTERRUPTS();
2478         {
2479             if( prvIsQueueFull( pxQueue ) != pdFALSE )
2480             {
2481                 /* The queue is full - do we want to block or just leave without
2482                  * posting? */
2483                 if( xTicksToWait > ( TickType_t ) 0 )
2484                 {
2485                     /* As this is called from a coroutine we cannot block directly, but
2486                      * return indicating that we need to block. */
2487                     vCoRoutineAddToDelayedList( xTicksToWait, &( pxQueue->xTasksWaitingToSend ) );
2488                     portENABLE_INTERRUPTS();
2489                     return errQUEUE_BLOCKED;
2490                 }
2491                 else
2492                 {
2493                     portENABLE_INTERRUPTS();
2494                     return errQUEUE_FULL;
2495                 }
2496             }
2497         }
2498         portENABLE_INTERRUPTS();
2499
2500         portDISABLE_INTERRUPTS();
2501         {
2502             if( pxQueue->uxMessagesWaiting < pxQueue->uxLength )
2503             {
2504                 /* There is room in the queue, copy the data into the queue. */
2505                 prvCopyDataToQueue( pxQueue, pvItemToQueue, queueSEND_TO_BACK );
2506                 xReturn = pdPASS;
2507
2508                 /* Were any co-routines waiting for data to become available? */
2509                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2510                 {
2511                     /* In this instance the co-routine could be placed directly
2512                      * into the ready list as we are within a critical section.
2513                      * Instead the same pending ready list mechanism is used as if
2514                      * the event were caused from within an interrupt. */
2515                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2516                     {
2517                         /* The co-routine waiting has a higher priority so record
2518                          * that a yield might be appropriate. */
2519                         xReturn = errQUEUE_YIELD;
2520                     }
2521                     else
2522                     {
2523                         mtCOVERAGE_TEST_MARKER();
2524                     }
2525                 }
2526                 else
2527                 {
2528                     mtCOVERAGE_TEST_MARKER();
2529                 }
2530             }
2531             else
2532             {
2533                 xReturn = errQUEUE_FULL;
2534             }
2535         }
2536         portENABLE_INTERRUPTS();
2537
2538         return xReturn;
2539     }
2540
2541 #endif /* configUSE_CO_ROUTINES */
2542 /*-----------------------------------------------------------*/
2543
2544 #if ( configUSE_CO_ROUTINES == 1 )
2545
2546     BaseType_t xQueueCRReceive( QueueHandle_t xQueue,
2547                                 void * pvBuffer,
2548                                 TickType_t xTicksToWait )
2549     {
2550         BaseType_t xReturn;
2551         Queue_t * const pxQueue = xQueue;
2552
2553         /* If the queue is already empty we may have to block.  A critical section
2554          * is required to prevent an interrupt adding something to the queue
2555          * between the check to see if the queue is empty and blocking on the queue. */
2556         portDISABLE_INTERRUPTS();
2557         {
2558             if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2559             {
2560                 /* There are no messages in the queue, do we want to block or just
2561                  * leave with nothing? */
2562                 if( xTicksToWait > ( TickType_t ) 0 )
2563                 {
2564                     /* As this is a co-routine we cannot block directly, but return
2565                      * indicating that we need to block. */
2566                     vCoRoutineAddToDelayedList( xTicksToWait, &( pxQueue->xTasksWaitingToReceive ) );
2567                     portENABLE_INTERRUPTS();
2568                     return errQUEUE_BLOCKED;
2569                 }
2570                 else
2571                 {
2572                     portENABLE_INTERRUPTS();
2573                     return errQUEUE_FULL;
2574                 }
2575             }
2576             else
2577             {
2578                 mtCOVERAGE_TEST_MARKER();
2579             }
2580         }
2581         portENABLE_INTERRUPTS();
2582
2583         portDISABLE_INTERRUPTS();
2584         {
2585             if( pxQueue->uxMessagesWaiting > ( UBaseType_t ) 0 )
2586             {
2587                 /* Data is available from the queue. */
2588                 pxQueue->u.xQueue.pcReadFrom += pxQueue->uxItemSize;
2589
2590                 if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail )
2591                 {
2592                     pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2593                 }
2594                 else
2595                 {
2596                     mtCOVERAGE_TEST_MARKER();
2597                 }
2598
2599                 --( pxQueue->uxMessagesWaiting );
2600                 ( void ) memcpy( ( void * ) pvBuffer, ( void * ) pxQueue->u.xQueue.pcReadFrom, ( unsigned ) pxQueue->uxItemSize );
2601
2602                 xReturn = pdPASS;
2603
2604                 /* Were any co-routines waiting for space to become available? */
2605                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2606                 {
2607                     /* In this instance the co-routine could be placed directly
2608                      * into the ready list as we are within a critical section.
2609                      * Instead the same pending ready list mechanism is used as if
2610                      * the event were caused from within an interrupt. */
2611                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2612                     {
2613                         xReturn = errQUEUE_YIELD;
2614                     }
2615                     else
2616                     {
2617                         mtCOVERAGE_TEST_MARKER();
2618                     }
2619                 }
2620                 else
2621                 {
2622                     mtCOVERAGE_TEST_MARKER();
2623                 }
2624             }
2625             else
2626             {
2627                 xReturn = pdFAIL;
2628             }
2629         }
2630         portENABLE_INTERRUPTS();
2631
2632         return xReturn;
2633     }
2634
2635 #endif /* configUSE_CO_ROUTINES */
2636 /*-----------------------------------------------------------*/
2637
2638 #if ( configUSE_CO_ROUTINES == 1 )
2639
2640     BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue,
2641                                     const void * pvItemToQueue,
2642                                     BaseType_t xCoRoutinePreviouslyWoken )
2643     {
2644         Queue_t * const pxQueue = xQueue;
2645
2646         /* Cannot block within an ISR so if there is no space on the queue then
2647          * exit without doing anything. */
2648         if( pxQueue->uxMessagesWaiting < pxQueue->uxLength )
2649         {
2650             prvCopyDataToQueue( pxQueue, pvItemToQueue, queueSEND_TO_BACK );
2651
2652             /* We only want to wake one co-routine per ISR, so check that a
2653              * co-routine has not already been woken. */
2654             if( xCoRoutinePreviouslyWoken == pdFALSE )
2655             {
2656                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2657                 {
2658                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2659                     {
2660                         return pdTRUE;
2661                     }
2662                     else
2663                     {
2664                         mtCOVERAGE_TEST_MARKER();
2665                     }
2666                 }
2667                 else
2668                 {
2669                     mtCOVERAGE_TEST_MARKER();
2670                 }
2671             }
2672             else
2673             {
2674                 mtCOVERAGE_TEST_MARKER();
2675             }
2676         }
2677         else
2678         {
2679             mtCOVERAGE_TEST_MARKER();
2680         }
2681
2682         return xCoRoutinePreviouslyWoken;
2683     }
2684
2685 #endif /* configUSE_CO_ROUTINES */
2686 /*-----------------------------------------------------------*/
2687
2688 #if ( configUSE_CO_ROUTINES == 1 )
2689
2690     BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue,
2691                                        void * pvBuffer,
2692                                        BaseType_t * pxCoRoutineWoken )
2693     {
2694         BaseType_t xReturn;
2695         Queue_t * const pxQueue = xQueue;
2696
2697         /* We cannot block from an ISR, so check there is data available. If
2698          * not then just leave without doing anything. */
2699         if( pxQueue->uxMessagesWaiting > ( UBaseType_t ) 0 )
2700         {
2701             /* Copy the data from the queue. */
2702             pxQueue->u.xQueue.pcReadFrom += pxQueue->uxItemSize;
2703
2704             if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail )
2705             {
2706                 pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2707             }
2708             else
2709             {
2710                 mtCOVERAGE_TEST_MARKER();
2711             }
2712
2713             --( pxQueue->uxMessagesWaiting );
2714             ( void ) memcpy( ( void * ) pvBuffer, ( void * ) pxQueue->u.xQueue.pcReadFrom, ( unsigned ) pxQueue->uxItemSize );
2715
2716             if( ( *pxCoRoutineWoken ) == pdFALSE )
2717             {
2718                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2719                 {
2720                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2721                     {
2722                         *pxCoRoutineWoken = pdTRUE;
2723                     }
2724                     else
2725                     {
2726                         mtCOVERAGE_TEST_MARKER();
2727                     }
2728                 }
2729                 else
2730                 {
2731                     mtCOVERAGE_TEST_MARKER();
2732                 }
2733             }
2734             else
2735             {
2736                 mtCOVERAGE_TEST_MARKER();
2737             }
2738
2739             xReturn = pdPASS;
2740         }
2741         else
2742         {
2743             xReturn = pdFAIL;
2744         }
2745
2746         return xReturn;
2747     }
2748
2749 #endif /* configUSE_CO_ROUTINES */
2750 /*-----------------------------------------------------------*/
2751
2752 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2753
2754     void vQueueAddToRegistry( QueueHandle_t xQueue,
2755                               const char * pcQueueName ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2756     {
2757         UBaseType_t ux;
2758
2759         configASSERT( xQueue );
2760
2761         QueueRegistryItem_t * pxEntryToWrite = NULL;
2762
2763         if( pcQueueName != NULL )
2764         {
2765             /* See if there is an empty space in the registry.  A NULL name denotes
2766              * a free slot. */
2767             for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2768             {
2769                 /* Replace an existing entry if the queue is already in the registry. */
2770                 if( xQueue == xQueueRegistry[ ux ].xHandle )
2771                 {
2772                     pxEntryToWrite = &( xQueueRegistry[ ux ] );
2773                     break;
2774                 }
2775                 /* Otherwise, store in the next empty location */
2776                 else if( ( pxEntryToWrite == NULL ) && ( xQueueRegistry[ ux ].pcQueueName == NULL ) )
2777                 {
2778                     pxEntryToWrite = &( xQueueRegistry[ ux ] );
2779                 }
2780                 else
2781                 {
2782                     mtCOVERAGE_TEST_MARKER();
2783                 }
2784             }
2785         }
2786
2787         if( pxEntryToWrite != NULL )
2788         {
2789             /* Store the information on this queue. */
2790             pxEntryToWrite->pcQueueName = pcQueueName;
2791             pxEntryToWrite->xHandle = xQueue;
2792
2793             traceQUEUE_REGISTRY_ADD( xQueue, pcQueueName );
2794         }
2795     }
2796
2797 #endif /* configQUEUE_REGISTRY_SIZE */
2798 /*-----------------------------------------------------------*/
2799
2800 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2801
2802     const char * pcQueueGetName( QueueHandle_t xQueue ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2803     {
2804         UBaseType_t ux;
2805         const char * pcReturn = NULL; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2806
2807         configASSERT( xQueue );
2808
2809         /* Note there is nothing here to protect against another task adding or
2810          * removing entries from the registry while it is being searched. */
2811
2812         for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2813         {
2814             if( xQueueRegistry[ ux ].xHandle == xQueue )
2815             {
2816                 pcReturn = xQueueRegistry[ ux ].pcQueueName;
2817                 break;
2818             }
2819             else
2820             {
2821                 mtCOVERAGE_TEST_MARKER();
2822             }
2823         }
2824
2825         return pcReturn;
2826     } /*lint !e818 xQueue cannot be a pointer to const because it is a typedef. */
2827
2828 #endif /* configQUEUE_REGISTRY_SIZE */
2829 /*-----------------------------------------------------------*/
2830
2831 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2832
2833     void vQueueUnregisterQueue( QueueHandle_t xQueue )
2834     {
2835         UBaseType_t ux;
2836
2837         configASSERT( xQueue );
2838
2839         /* See if the handle of the queue being unregistered in actually in the
2840          * registry. */
2841         for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2842         {
2843             if( xQueueRegistry[ ux ].xHandle == xQueue )
2844             {
2845                 /* Set the name to NULL to show that this slot if free again. */
2846                 xQueueRegistry[ ux ].pcQueueName = NULL;
2847
2848                 /* Set the handle to NULL to ensure the same queue handle cannot
2849                  * appear in the registry twice if it is added, removed, then
2850                  * added again. */
2851                 xQueueRegistry[ ux ].xHandle = ( QueueHandle_t ) 0;
2852                 break;
2853             }
2854             else
2855             {
2856                 mtCOVERAGE_TEST_MARKER();
2857             }
2858         }
2859     } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2860
2861 #endif /* configQUEUE_REGISTRY_SIZE */
2862 /*-----------------------------------------------------------*/
2863
2864 #if ( configUSE_TIMERS == 1 )
2865
2866     void vQueueWaitForMessageRestricted( QueueHandle_t xQueue,
2867                                          TickType_t xTicksToWait,
2868                                          const BaseType_t xWaitIndefinitely )
2869     {
2870         Queue_t * const pxQueue = xQueue;
2871
2872         /* This function should not be called by application code hence the
2873          * 'Restricted' in its name.  It is not part of the public API.  It is
2874          * designed for use by kernel code, and has special calling requirements.
2875          * It can result in vListInsert() being called on a list that can only
2876          * possibly ever have one item in it, so the list will be fast, but even
2877          * so it should be called with the scheduler locked and not from a critical
2878          * section. */
2879
2880         /* Only do anything if there are no messages in the queue.  This function
2881          *  will not actually cause the task to block, just place it on a blocked
2882          *  list.  It will not block until the scheduler is unlocked - at which
2883          *  time a yield will be performed.  If an item is added to the queue while
2884          *  the queue is locked, and the calling task blocks on the queue, then the
2885          *  calling task will be immediately unblocked when the queue is unlocked. */
2886         prvLockQueue( pxQueue );
2887
2888         if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0U )
2889         {
2890             /* There is nothing in the queue, block for the specified period. */
2891             vTaskPlaceOnEventListRestricted( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait, xWaitIndefinitely );
2892         }
2893         else
2894         {
2895             mtCOVERAGE_TEST_MARKER();
2896         }
2897
2898         prvUnlockQueue( pxQueue );
2899     }
2900
2901 #endif /* configUSE_TIMERS */
2902 /*-----------------------------------------------------------*/
2903
2904 #if ( ( configUSE_QUEUE_SETS == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
2905
2906     QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength )
2907     {
2908         QueueSetHandle_t pxQueue;
2909
2910         pxQueue = xQueueGenericCreate( uxEventQueueLength, ( UBaseType_t ) sizeof( Queue_t * ), queueQUEUE_TYPE_SET );
2911
2912         return pxQueue;
2913     }
2914
2915 #endif /* configUSE_QUEUE_SETS */
2916 /*-----------------------------------------------------------*/
2917
2918 #if ( configUSE_QUEUE_SETS == 1 )
2919
2920     BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
2921                                QueueSetHandle_t xQueueSet )
2922     {
2923         BaseType_t xReturn;
2924
2925         taskENTER_CRITICAL();
2926         {
2927             if( ( ( Queue_t * ) xQueueOrSemaphore )->pxQueueSetContainer != NULL )
2928             {
2929                 /* Cannot add a queue/semaphore to more than one queue set. */
2930                 xReturn = pdFAIL;
2931             }
2932             else if( ( ( Queue_t * ) xQueueOrSemaphore )->uxMessagesWaiting != ( UBaseType_t ) 0 )
2933             {
2934                 /* Cannot add a queue/semaphore to a queue set if there are already
2935                  * items in the queue/semaphore. */
2936                 xReturn = pdFAIL;
2937             }
2938             else
2939             {
2940                 ( ( Queue_t * ) xQueueOrSemaphore )->pxQueueSetContainer = xQueueSet;
2941                 xReturn = pdPASS;
2942             }
2943         }
2944         taskEXIT_CRITICAL();
2945
2946         return xReturn;
2947     }
2948
2949 #endif /* configUSE_QUEUE_SETS */
2950 /*-----------------------------------------------------------*/
2951
2952 #if ( configUSE_QUEUE_SETS == 1 )
2953
2954     BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,
2955                                     QueueSetHandle_t xQueueSet )
2956     {
2957         BaseType_t xReturn;
2958         Queue_t * const pxQueueOrSemaphore = ( Queue_t * ) xQueueOrSemaphore;
2959
2960         if( pxQueueOrSemaphore->pxQueueSetContainer != xQueueSet )
2961         {
2962             /* The queue was not a member of the set. */
2963             xReturn = pdFAIL;
2964         }
2965         else if( pxQueueOrSemaphore->uxMessagesWaiting != ( UBaseType_t ) 0 )
2966         {
2967             /* It is dangerous to remove a queue from a set when the queue is
2968              * not empty because the queue set will still hold pending events for
2969              * the queue. */
2970             xReturn = pdFAIL;
2971         }
2972         else
2973         {
2974             taskENTER_CRITICAL();
2975             {
2976                 /* The queue is no longer contained in the set. */
2977                 pxQueueOrSemaphore->pxQueueSetContainer = NULL;
2978             }
2979             taskEXIT_CRITICAL();
2980             xReturn = pdPASS;
2981         }
2982
2983         return xReturn;
2984     } /*lint !e818 xQueueSet could not be declared as pointing to const as it is a typedef. */
2985
2986 #endif /* configUSE_QUEUE_SETS */
2987 /*-----------------------------------------------------------*/
2988
2989 #if ( configUSE_QUEUE_SETS == 1 )
2990
2991     QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
2992                                                 TickType_t const xTicksToWait )
2993     {
2994         QueueSetMemberHandle_t xReturn = NULL;
2995
2996         ( void ) xQueueReceive( ( QueueHandle_t ) xQueueSet, &xReturn, xTicksToWait ); /*lint !e961 Casting from one typedef to another is not redundant. */
2997         return xReturn;
2998     }
2999
3000 #endif /* configUSE_QUEUE_SETS */
3001 /*-----------------------------------------------------------*/
3002
3003 #if ( configUSE_QUEUE_SETS == 1 )
3004
3005     QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet )
3006     {
3007         QueueSetMemberHandle_t xReturn = NULL;
3008
3009         ( void ) xQueueReceiveFromISR( ( QueueHandle_t ) xQueueSet, &xReturn, NULL ); /*lint !e961 Casting from one typedef to another is not redundant. */
3010         return xReturn;
3011     }
3012
3013 #endif /* configUSE_QUEUE_SETS */
3014 /*-----------------------------------------------------------*/
3015
3016 #if ( configUSE_QUEUE_SETS == 1 )
3017
3018     static BaseType_t prvNotifyQueueSetContainer( const Queue_t * const pxQueue )
3019     {
3020         Queue_t * pxQueueSetContainer = pxQueue->pxQueueSetContainer;
3021         BaseType_t xReturn = pdFALSE;
3022
3023         /* This function must be called form a critical section. */
3024
3025         /* The following line is not reachable in unit tests because every call
3026          * to prvNotifyQueueSetContainer is preceded by a check that
3027          * pxQueueSetContainer != NULL */
3028         configASSERT( pxQueueSetContainer ); /* LCOV_EXCL_BR_LINE */
3029         configASSERT( pxQueueSetContainer->uxMessagesWaiting < pxQueueSetContainer->uxLength );
3030
3031         if( pxQueueSetContainer->uxMessagesWaiting < pxQueueSetContainer->uxLength )
3032         {
3033             const int8_t cTxLock = pxQueueSetContainer->cTxLock;
3034
3035             traceQUEUE_SET_SEND( pxQueueSetContainer );
3036
3037             /* The data copied is the handle of the queue that contains data. */
3038             xReturn = prvCopyDataToQueue( pxQueueSetContainer, &pxQueue, queueSEND_TO_BACK );
3039
3040             if( cTxLock == queueUNLOCKED )
3041             {
3042                 if( listLIST_IS_EMPTY( &( pxQueueSetContainer->xTasksWaitingToReceive ) ) == pdFALSE )
3043                 {
3044                     if( xTaskRemoveFromEventList( &( pxQueueSetContainer->xTasksWaitingToReceive ) ) != pdFALSE )
3045                     {
3046                         /* The task waiting has a higher priority. */
3047                         xReturn = pdTRUE;
3048                     }
3049                     else
3050                     {
3051                         mtCOVERAGE_TEST_MARKER();
3052                     }
3053                 }
3054                 else
3055                 {
3056                     mtCOVERAGE_TEST_MARKER();
3057                 }
3058             }
3059             else
3060             {
3061                 configASSERT( cTxLock != queueINT8_MAX );
3062
3063                 pxQueueSetContainer->cTxLock = ( int8_t ) ( cTxLock + 1 );
3064             }
3065         }
3066         else
3067         {
3068             mtCOVERAGE_TEST_MARKER();
3069         }
3070
3071         return xReturn;
3072     }
3073
3074 #endif /* configUSE_QUEUE_SETS */