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

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