begriffs open source - freertos/blob - queue.c

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