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             ( ( UBaseType_t ) ( 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 = ( UBaseType_t ) ( 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 = ( UBaseType_t ) ( 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 = ( UBaseType_t ) ( 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 = ( UBaseType_t ) ( 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 = ( UBaseType_t ) ( 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 UBaseType_t uxQueueGetQueueLength( QueueHandle_t xQueue ) /* PRIVILEGED_FUNCTION */
2240 {
2241     return ( ( Queue_t * ) xQueue )->uxLength;
2242 }
2243 /*-----------------------------------------------------------*/
2244
2245 #if ( configUSE_MUTEXES == 1 )
2246
2247     static UBaseType_t prvGetDisinheritPriorityAfterTimeout( const Queue_t * const pxQueue )
2248     {
2249         UBaseType_t uxHighestPriorityOfWaitingTasks;
2250
2251         /* If a task waiting for a mutex causes the mutex holder to inherit a
2252          * priority, but the waiting task times out, then the holder should
2253          * disinherit the priority - but only down to the highest priority of any
2254          * other tasks that are waiting for the same mutex.  For this purpose,
2255          * return the priority of the highest priority task that is waiting for the
2256          * mutex. */
2257         if( listCURRENT_LIST_LENGTH( &( pxQueue->xTasksWaitingToReceive ) ) > 0U )
2258         {
2259             uxHighestPriorityOfWaitingTasks = ( UBaseType_t ) ( ( UBaseType_t ) configMAX_PRIORITIES - ( UBaseType_t ) listGET_ITEM_VALUE_OF_HEAD_ENTRY( &( pxQueue->xTasksWaitingToReceive ) ) );
2260         }
2261         else
2262         {
2263             uxHighestPriorityOfWaitingTasks = tskIDLE_PRIORITY;
2264         }
2265
2266         return uxHighestPriorityOfWaitingTasks;
2267     }
2268
2269 #endif /* configUSE_MUTEXES */
2270 /*-----------------------------------------------------------*/
2271
2272 static BaseType_t prvCopyDataToQueue( Queue_t * const pxQueue,
2273                                       const void * pvItemToQueue,
2274                                       const BaseType_t xPosition )
2275 {
2276     BaseType_t xReturn = pdFALSE;
2277     UBaseType_t uxMessagesWaiting;
2278
2279     /* This function is called from a critical section. */
2280
2281     uxMessagesWaiting = pxQueue->uxMessagesWaiting;
2282
2283     if( pxQueue->uxItemSize == ( UBaseType_t ) 0 )
2284     {
2285         #if ( configUSE_MUTEXES == 1 )
2286         {
2287             if( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX )
2288             {
2289                 /* The mutex is no longer being held. */
2290                 xReturn = xTaskPriorityDisinherit( pxQueue->u.xSemaphore.xMutexHolder );
2291                 pxQueue->u.xSemaphore.xMutexHolder = NULL;
2292             }
2293             else
2294             {
2295                 mtCOVERAGE_TEST_MARKER();
2296             }
2297         }
2298         #endif /* configUSE_MUTEXES */
2299     }
2300     else if( xPosition == queueSEND_TO_BACK )
2301     {
2302         ( 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. */
2303         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. */
2304
2305         if( pxQueue->pcWriteTo >= pxQueue->u.xQueue.pcTail )                                             /*lint !e946 MISRA exception justified as comparison of pointers is the cleanest solution. */
2306         {
2307             pxQueue->pcWriteTo = pxQueue->pcHead;
2308         }
2309         else
2310         {
2311             mtCOVERAGE_TEST_MARKER();
2312         }
2313     }
2314     else
2315     {
2316         ( 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. */
2317         pxQueue->u.xQueue.pcReadFrom -= pxQueue->uxItemSize;
2318
2319         if( pxQueue->u.xQueue.pcReadFrom < pxQueue->pcHead ) /*lint !e946 MISRA exception justified as comparison of pointers is the cleanest solution. */
2320         {
2321             pxQueue->u.xQueue.pcReadFrom = ( pxQueue->u.xQueue.pcTail - pxQueue->uxItemSize );
2322         }
2323         else
2324         {
2325             mtCOVERAGE_TEST_MARKER();
2326         }
2327
2328         if( xPosition == queueOVERWRITE )
2329         {
2330             if( uxMessagesWaiting > ( UBaseType_t ) 0 )
2331             {
2332                 /* An item is not being added but overwritten, so subtract
2333                  * one from the recorded number of items in the queue so when
2334                  * one is added again below the number of recorded items remains
2335                  * correct. */
2336                 --uxMessagesWaiting;
2337             }
2338             else
2339             {
2340                 mtCOVERAGE_TEST_MARKER();
2341             }
2342         }
2343         else
2344         {
2345             mtCOVERAGE_TEST_MARKER();
2346         }
2347     }
2348
2349     pxQueue->uxMessagesWaiting = ( UBaseType_t ) ( uxMessagesWaiting + ( UBaseType_t ) 1 );
2350
2351     return xReturn;
2352 }
2353 /*-----------------------------------------------------------*/
2354
2355 static void prvCopyDataFromQueue( Queue_t * const pxQueue,
2356                                   void * const pvBuffer )
2357 {
2358     if( pxQueue->uxItemSize != ( UBaseType_t ) 0 )
2359     {
2360         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. */
2361
2362         if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail ) /*lint !e946 MISRA exception justified as use of the relational operator is the cleanest solutions. */
2363         {
2364             pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2365         }
2366         else
2367         {
2368             mtCOVERAGE_TEST_MARKER();
2369         }
2370
2371         ( 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. */
2372     }
2373 }
2374 /*-----------------------------------------------------------*/
2375
2376 static void prvUnlockQueue( Queue_t * const pxQueue )
2377 {
2378     /* THIS FUNCTION MUST BE CALLED WITH THE SCHEDULER SUSPENDED. */
2379
2380     /* The lock counts contains the number of extra data items placed or
2381      * removed from the queue while the queue was locked.  When a queue is
2382      * locked items can be added or removed, but the event lists cannot be
2383      * updated. */
2384     taskENTER_CRITICAL();
2385     {
2386         int8_t cTxLock = pxQueue->cTxLock;
2387
2388         /* See if data was added to the queue while it was locked. */
2389         while( cTxLock > queueLOCKED_UNMODIFIED )
2390         {
2391             /* Data was posted while the queue was locked.  Are any tasks
2392              * blocked waiting for data to become available? */
2393             #if ( configUSE_QUEUE_SETS == 1 )
2394             {
2395                 if( pxQueue->pxQueueSetContainer != NULL )
2396                 {
2397                     if( prvNotifyQueueSetContainer( pxQueue ) != pdFALSE )
2398                     {
2399                         /* The queue is a member of a queue set, and posting to
2400                          * the queue set caused a higher priority task to unblock.
2401                          * A context switch is required. */
2402                         vTaskMissedYield();
2403                     }
2404                     else
2405                     {
2406                         mtCOVERAGE_TEST_MARKER();
2407                     }
2408                 }
2409                 else
2410                 {
2411                     /* Tasks that are removed from the event list will get
2412                      * added to the pending ready list as the scheduler is still
2413                      * suspended. */
2414                     if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2415                     {
2416                         if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2417                         {
2418                             /* The task waiting has a higher priority so record that a
2419                              * context switch is required. */
2420                             vTaskMissedYield();
2421                         }
2422                         else
2423                         {
2424                             mtCOVERAGE_TEST_MARKER();
2425                         }
2426                     }
2427                     else
2428                     {
2429                         break;
2430                     }
2431                 }
2432             }
2433             #else /* configUSE_QUEUE_SETS */
2434             {
2435                 /* Tasks that are removed from the event list will get added to
2436                  * the pending ready list as the scheduler is still suspended. */
2437                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2438                 {
2439                     if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2440                     {
2441                         /* The task waiting has a higher priority so record that
2442                          * a context switch is required. */
2443                         vTaskMissedYield();
2444                     }
2445                     else
2446                     {
2447                         mtCOVERAGE_TEST_MARKER();
2448                     }
2449                 }
2450                 else
2451                 {
2452                     break;
2453                 }
2454             }
2455             #endif /* configUSE_QUEUE_SETS */
2456
2457             --cTxLock;
2458         }
2459
2460         pxQueue->cTxLock = queueUNLOCKED;
2461     }
2462     taskEXIT_CRITICAL();
2463
2464     /* Do the same for the Rx lock. */
2465     taskENTER_CRITICAL();
2466     {
2467         int8_t cRxLock = pxQueue->cRxLock;
2468
2469         while( cRxLock > queueLOCKED_UNMODIFIED )
2470         {
2471             if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2472             {
2473                 if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2474                 {
2475                     vTaskMissedYield();
2476                 }
2477                 else
2478                 {
2479                     mtCOVERAGE_TEST_MARKER();
2480                 }
2481
2482                 --cRxLock;
2483             }
2484             else
2485             {
2486                 break;
2487             }
2488         }
2489
2490         pxQueue->cRxLock = queueUNLOCKED;
2491     }
2492     taskEXIT_CRITICAL();
2493 }
2494 /*-----------------------------------------------------------*/
2495
2496 static BaseType_t prvIsQueueEmpty( const Queue_t * pxQueue )
2497 {
2498     BaseType_t xReturn;
2499
2500     taskENTER_CRITICAL();
2501     {
2502         if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2503         {
2504             xReturn = pdTRUE;
2505         }
2506         else
2507         {
2508             xReturn = pdFALSE;
2509         }
2510     }
2511     taskEXIT_CRITICAL();
2512
2513     return xReturn;
2514 }
2515 /*-----------------------------------------------------------*/
2516
2517 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue )
2518 {
2519     BaseType_t xReturn;
2520     Queue_t * const pxQueue = xQueue;
2521
2522     configASSERT( pxQueue );
2523
2524     if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2525     {
2526         xReturn = pdTRUE;
2527     }
2528     else
2529     {
2530         xReturn = pdFALSE;
2531     }
2532
2533     return xReturn;
2534 } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2535 /*-----------------------------------------------------------*/
2536
2537 static BaseType_t prvIsQueueFull( const Queue_t * pxQueue )
2538 {
2539     BaseType_t xReturn;
2540
2541     taskENTER_CRITICAL();
2542     {
2543         if( pxQueue->uxMessagesWaiting == pxQueue->uxLength )
2544         {
2545             xReturn = pdTRUE;
2546         }
2547         else
2548         {
2549             xReturn = pdFALSE;
2550         }
2551     }
2552     taskEXIT_CRITICAL();
2553
2554     return xReturn;
2555 }
2556 /*-----------------------------------------------------------*/
2557
2558 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue )
2559 {
2560     BaseType_t xReturn;
2561     Queue_t * const pxQueue = xQueue;
2562
2563     configASSERT( pxQueue );
2564
2565     if( pxQueue->uxMessagesWaiting == pxQueue->uxLength )
2566     {
2567         xReturn = pdTRUE;
2568     }
2569     else
2570     {
2571         xReturn = pdFALSE;
2572     }
2573
2574     return xReturn;
2575 } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2576 /*-----------------------------------------------------------*/
2577
2578 #if ( configUSE_CO_ROUTINES == 1 )
2579
2580     BaseType_t xQueueCRSend( QueueHandle_t xQueue,
2581                              const void * pvItemToQueue,
2582                              TickType_t xTicksToWait )
2583     {
2584         BaseType_t xReturn;
2585         Queue_t * const pxQueue = xQueue;
2586
2587         /* If the queue is already full we may have to block.  A critical section
2588          * is required to prevent an interrupt removing something from the queue
2589          * between the check to see if the queue is full and blocking on the queue. */
2590         portDISABLE_INTERRUPTS();
2591         {
2592             if( prvIsQueueFull( pxQueue ) != pdFALSE )
2593             {
2594                 /* The queue is full - do we want to block or just leave without
2595                  * posting? */
2596                 if( xTicksToWait > ( TickType_t ) 0 )
2597                 {
2598                     /* As this is called from a coroutine we cannot block directly, but
2599                      * return indicating that we need to block. */
2600                     vCoRoutineAddToDelayedList( xTicksToWait, &( pxQueue->xTasksWaitingToSend ) );
2601                     portENABLE_INTERRUPTS();
2602                     return errQUEUE_BLOCKED;
2603                 }
2604                 else
2605                 {
2606                     portENABLE_INTERRUPTS();
2607                     return errQUEUE_FULL;
2608                 }
2609             }
2610         }
2611         portENABLE_INTERRUPTS();
2612
2613         portDISABLE_INTERRUPTS();
2614         {
2615             if( pxQueue->uxMessagesWaiting < pxQueue->uxLength )
2616             {
2617                 /* There is room in the queue, copy the data into the queue. */
2618                 prvCopyDataToQueue( pxQueue, pvItemToQueue, queueSEND_TO_BACK );
2619                 xReturn = pdPASS;
2620
2621                 /* Were any co-routines waiting for data to become available? */
2622                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2623                 {
2624                     /* In this instance the co-routine could be placed directly
2625                      * into the ready list as we are within a critical section.
2626                      * Instead the same pending ready list mechanism is used as if
2627                      * the event were caused from within an interrupt. */
2628                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2629                     {
2630                         /* The co-routine waiting has a higher priority so record
2631                          * that a yield might be appropriate. */
2632                         xReturn = errQUEUE_YIELD;
2633                     }
2634                     else
2635                     {
2636                         mtCOVERAGE_TEST_MARKER();
2637                     }
2638                 }
2639                 else
2640                 {
2641                     mtCOVERAGE_TEST_MARKER();
2642                 }
2643             }
2644             else
2645             {
2646                 xReturn = errQUEUE_FULL;
2647             }
2648         }
2649         portENABLE_INTERRUPTS();
2650
2651         return xReturn;
2652     }
2653
2654 #endif /* configUSE_CO_ROUTINES */
2655 /*-----------------------------------------------------------*/
2656
2657 #if ( configUSE_CO_ROUTINES == 1 )
2658
2659     BaseType_t xQueueCRReceive( QueueHandle_t xQueue,
2660                                 void * pvBuffer,
2661                                 TickType_t xTicksToWait )
2662     {
2663         BaseType_t xReturn;
2664         Queue_t * const pxQueue = xQueue;
2665
2666         /* If the queue is already empty we may have to block.  A critical section
2667          * is required to prevent an interrupt adding something to the queue
2668          * between the check to see if the queue is empty and blocking on the queue. */
2669         portDISABLE_INTERRUPTS();
2670         {
2671             if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0 )
2672             {
2673                 /* There are no messages in the queue, do we want to block or just
2674                  * leave with nothing? */
2675                 if( xTicksToWait > ( TickType_t ) 0 )
2676                 {
2677                     /* As this is a co-routine we cannot block directly, but return
2678                      * indicating that we need to block. */
2679                     vCoRoutineAddToDelayedList( xTicksToWait, &( pxQueue->xTasksWaitingToReceive ) );
2680                     portENABLE_INTERRUPTS();
2681                     return errQUEUE_BLOCKED;
2682                 }
2683                 else
2684                 {
2685                     portENABLE_INTERRUPTS();
2686                     return errQUEUE_FULL;
2687                 }
2688             }
2689             else
2690             {
2691                 mtCOVERAGE_TEST_MARKER();
2692             }
2693         }
2694         portENABLE_INTERRUPTS();
2695
2696         portDISABLE_INTERRUPTS();
2697         {
2698             if( pxQueue->uxMessagesWaiting > ( UBaseType_t ) 0 )
2699             {
2700                 /* Data is available from the queue. */
2701                 pxQueue->u.xQueue.pcReadFrom += pxQueue->uxItemSize;
2702
2703                 if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail )
2704                 {
2705                     pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2706                 }
2707                 else
2708                 {
2709                     mtCOVERAGE_TEST_MARKER();
2710                 }
2711
2712                 --( pxQueue->uxMessagesWaiting );
2713                 ( void ) memcpy( ( void * ) pvBuffer, ( void * ) pxQueue->u.xQueue.pcReadFrom, ( unsigned ) pxQueue->uxItemSize );
2714
2715                 xReturn = pdPASS;
2716
2717                 /* Were any co-routines waiting for space to become available? */
2718                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2719                 {
2720                     /* In this instance the co-routine could be placed directly
2721                      * into the ready list as we are within a critical section.
2722                      * Instead the same pending ready list mechanism is used as if
2723                      * the event were caused from within an interrupt. */
2724                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2725                     {
2726                         xReturn = errQUEUE_YIELD;
2727                     }
2728                     else
2729                     {
2730                         mtCOVERAGE_TEST_MARKER();
2731                     }
2732                 }
2733                 else
2734                 {
2735                     mtCOVERAGE_TEST_MARKER();
2736                 }
2737             }
2738             else
2739             {
2740                 xReturn = pdFAIL;
2741             }
2742         }
2743         portENABLE_INTERRUPTS();
2744
2745         return xReturn;
2746     }
2747
2748 #endif /* configUSE_CO_ROUTINES */
2749 /*-----------------------------------------------------------*/
2750
2751 #if ( configUSE_CO_ROUTINES == 1 )
2752
2753     BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue,
2754                                     const void * pvItemToQueue,
2755                                     BaseType_t xCoRoutinePreviouslyWoken )
2756     {
2757         Queue_t * const pxQueue = xQueue;
2758
2759         /* Cannot block within an ISR so if there is no space on the queue then
2760          * exit without doing anything. */
2761         if( pxQueue->uxMessagesWaiting < pxQueue->uxLength )
2762         {
2763             prvCopyDataToQueue( pxQueue, pvItemToQueue, queueSEND_TO_BACK );
2764
2765             /* We only want to wake one co-routine per ISR, so check that a
2766              * co-routine has not already been woken. */
2767             if( xCoRoutinePreviouslyWoken == pdFALSE )
2768             {
2769                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )
2770                 {
2771                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) != pdFALSE )
2772                     {
2773                         return pdTRUE;
2774                     }
2775                     else
2776                     {
2777                         mtCOVERAGE_TEST_MARKER();
2778                     }
2779                 }
2780                 else
2781                 {
2782                     mtCOVERAGE_TEST_MARKER();
2783                 }
2784             }
2785             else
2786             {
2787                 mtCOVERAGE_TEST_MARKER();
2788             }
2789         }
2790         else
2791         {
2792             mtCOVERAGE_TEST_MARKER();
2793         }
2794
2795         return xCoRoutinePreviouslyWoken;
2796     }
2797
2798 #endif /* configUSE_CO_ROUTINES */
2799 /*-----------------------------------------------------------*/
2800
2801 #if ( configUSE_CO_ROUTINES == 1 )
2802
2803     BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue,
2804                                        void * pvBuffer,
2805                                        BaseType_t * pxCoRoutineWoken )
2806     {
2807         BaseType_t xReturn;
2808         Queue_t * const pxQueue = xQueue;
2809
2810         /* We cannot block from an ISR, so check there is data available. If
2811          * not then just leave without doing anything. */
2812         if( pxQueue->uxMessagesWaiting > ( UBaseType_t ) 0 )
2813         {
2814             /* Copy the data from the queue. */
2815             pxQueue->u.xQueue.pcReadFrom += pxQueue->uxItemSize;
2816
2817             if( pxQueue->u.xQueue.pcReadFrom >= pxQueue->u.xQueue.pcTail )
2818             {
2819                 pxQueue->u.xQueue.pcReadFrom = pxQueue->pcHead;
2820             }
2821             else
2822             {
2823                 mtCOVERAGE_TEST_MARKER();
2824             }
2825
2826             --( pxQueue->uxMessagesWaiting );
2827             ( void ) memcpy( ( void * ) pvBuffer, ( void * ) pxQueue->u.xQueue.pcReadFrom, ( unsigned ) pxQueue->uxItemSize );
2828
2829             if( ( *pxCoRoutineWoken ) == pdFALSE )
2830             {
2831                 if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )
2832                 {
2833                     if( xCoRoutineRemoveFromEventList( &( pxQueue->xTasksWaitingToSend ) ) != pdFALSE )
2834                     {
2835                         *pxCoRoutineWoken = pdTRUE;
2836                     }
2837                     else
2838                     {
2839                         mtCOVERAGE_TEST_MARKER();
2840                     }
2841                 }
2842                 else
2843                 {
2844                     mtCOVERAGE_TEST_MARKER();
2845                 }
2846             }
2847             else
2848             {
2849                 mtCOVERAGE_TEST_MARKER();
2850             }
2851
2852             xReturn = pdPASS;
2853         }
2854         else
2855         {
2856             xReturn = pdFAIL;
2857         }
2858
2859         return xReturn;
2860     }
2861
2862 #endif /* configUSE_CO_ROUTINES */
2863 /*-----------------------------------------------------------*/
2864
2865 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2866
2867     void vQueueAddToRegistry( QueueHandle_t xQueue,
2868                               const char * pcQueueName ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2869     {
2870         UBaseType_t ux;
2871         QueueRegistryItem_t * pxEntryToWrite = NULL;
2872
2873         configASSERT( xQueue );
2874
2875         if( pcQueueName != NULL )
2876         {
2877             /* See if there is an empty space in the registry.  A NULL name denotes
2878              * a free slot. */
2879             for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2880             {
2881                 /* Replace an existing entry if the queue is already in the registry. */
2882                 if( xQueue == xQueueRegistry[ ux ].xHandle )
2883                 {
2884                     pxEntryToWrite = &( xQueueRegistry[ ux ] );
2885                     break;
2886                 }
2887                 /* Otherwise, store in the next empty location */
2888                 else if( ( pxEntryToWrite == NULL ) && ( xQueueRegistry[ ux ].pcQueueName == NULL ) )
2889                 {
2890                     pxEntryToWrite = &( xQueueRegistry[ ux ] );
2891                 }
2892                 else
2893                 {
2894                     mtCOVERAGE_TEST_MARKER();
2895                 }
2896             }
2897         }
2898
2899         if( pxEntryToWrite != NULL )
2900         {
2901             /* Store the information on this queue. */
2902             pxEntryToWrite->pcQueueName = pcQueueName;
2903             pxEntryToWrite->xHandle = xQueue;
2904
2905             traceQUEUE_REGISTRY_ADD( xQueue, pcQueueName );
2906         }
2907     }
2908
2909 #endif /* configQUEUE_REGISTRY_SIZE */
2910 /*-----------------------------------------------------------*/
2911
2912 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2913
2914     const char * pcQueueGetName( QueueHandle_t xQueue ) /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2915     {
2916         UBaseType_t ux;
2917         const char * pcReturn = NULL; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
2918
2919         configASSERT( xQueue );
2920
2921         /* Note there is nothing here to protect against another task adding or
2922          * removing entries from the registry while it is being searched. */
2923
2924         for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2925         {
2926             if( xQueueRegistry[ ux ].xHandle == xQueue )
2927             {
2928                 pcReturn = xQueueRegistry[ ux ].pcQueueName;
2929                 break;
2930             }
2931             else
2932             {
2933                 mtCOVERAGE_TEST_MARKER();
2934             }
2935         }
2936
2937         return pcReturn;
2938     } /*lint !e818 xQueue cannot be a pointer to const because it is a typedef. */
2939
2940 #endif /* configQUEUE_REGISTRY_SIZE */
2941 /*-----------------------------------------------------------*/
2942
2943 #if ( configQUEUE_REGISTRY_SIZE > 0 )
2944
2945     void vQueueUnregisterQueue( QueueHandle_t xQueue )
2946     {
2947         UBaseType_t ux;
2948
2949         configASSERT( xQueue );
2950
2951         /* See if the handle of the queue being unregistered in actually in the
2952          * registry. */
2953         for( ux = ( UBaseType_t ) 0U; ux < ( UBaseType_t ) configQUEUE_REGISTRY_SIZE; ux++ )
2954         {
2955             if( xQueueRegistry[ ux ].xHandle == xQueue )
2956             {
2957                 /* Set the name to NULL to show that this slot if free again. */
2958                 xQueueRegistry[ ux ].pcQueueName = NULL;
2959
2960                 /* Set the handle to NULL to ensure the same queue handle cannot
2961                  * appear in the registry twice if it is added, removed, then
2962                  * added again. */
2963                 xQueueRegistry[ ux ].xHandle = ( QueueHandle_t ) 0;
2964                 break;
2965             }
2966             else
2967             {
2968                 mtCOVERAGE_TEST_MARKER();
2969             }
2970         }
2971     } /*lint !e818 xQueue could not be pointer to const because it is a typedef. */
2972
2973 #endif /* configQUEUE_REGISTRY_SIZE */
2974 /*-----------------------------------------------------------*/
2975
2976 #if ( configUSE_TIMERS == 1 )
2977
2978     void vQueueWaitForMessageRestricted( QueueHandle_t xQueue,
2979                                          TickType_t xTicksToWait,
2980                                          const BaseType_t xWaitIndefinitely )
2981     {
2982         Queue_t * const pxQueue = xQueue;
2983
2984         /* This function should not be called by application code hence the
2985          * 'Restricted' in its name.  It is not part of the public API.  It is
2986          * designed for use by kernel code, and has special calling requirements.
2987          * It can result in vListInsert() being called on a list that can only
2988          * possibly ever have one item in it, so the list will be fast, but even
2989          * so it should be called with the scheduler locked and not from a critical
2990          * section. */
2991
2992         /* Only do anything if there are no messages in the queue.  This function
2993          *  will not actually cause the task to block, just place it on a blocked
2994          *  list.  It will not block until the scheduler is unlocked - at which
2995          *  time a yield will be performed.  If an item is added to the queue while
2996          *  the queue is locked, and the calling task blocks on the queue, then the
2997          *  calling task will be immediately unblocked when the queue is unlocked. */
2998         prvLockQueue( pxQueue );
2999
3000         if( pxQueue->uxMessagesWaiting == ( UBaseType_t ) 0U )
3001         {
3002             /* There is nothing in the queue, block for the specified period. */
3003             vTaskPlaceOnEventListRestricted( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait, xWaitIndefinitely );
3004         }
3005         else
3006         {
3007             mtCOVERAGE_TEST_MARKER();
3008         }
3009
3010         prvUnlockQueue( pxQueue );
3011     }
3012
3013 #endif /* configUSE_TIMERS */
3014 /*-----------------------------------------------------------*/
3015
3016 #if ( ( configUSE_QUEUE_SETS == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
3017
3018     QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength )
3019     {
3020         QueueSetHandle_t pxQueue;
3021
3022         pxQueue = xQueueGenericCreate( uxEventQueueLength, ( UBaseType_t ) sizeof( Queue_t * ), queueQUEUE_TYPE_SET );
3023
3024         return pxQueue;
3025     }
3026
3027 #endif /* configUSE_QUEUE_SETS */
3028 /*-----------------------------------------------------------*/
3029
3030 #if ( configUSE_QUEUE_SETS == 1 )
3031
3032     BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
3033                                QueueSetHandle_t xQueueSet )
3034     {
3035         BaseType_t xReturn;
3036
3037         taskENTER_CRITICAL();
3038         {
3039             if( ( ( Queue_t * ) xQueueOrSemaphore )->pxQueueSetContainer != NULL )
3040             {
3041                 /* Cannot add a queue/semaphore to more than one queue set. */
3042                 xReturn = pdFAIL;
3043             }
3044             else if( ( ( Queue_t * ) xQueueOrSemaphore )->uxMessagesWaiting != ( UBaseType_t ) 0 )
3045             {
3046                 /* Cannot add a queue/semaphore to a queue set if there are already
3047                  * items in the queue/semaphore. */
3048                 xReturn = pdFAIL;
3049             }
3050             else
3051             {
3052                 ( ( Queue_t * ) xQueueOrSemaphore )->pxQueueSetContainer = xQueueSet;
3053                 xReturn = pdPASS;
3054             }
3055         }
3056         taskEXIT_CRITICAL();
3057
3058         return xReturn;
3059     }
3060
3061 #endif /* configUSE_QUEUE_SETS */
3062 /*-----------------------------------------------------------*/
3063
3064 #if ( configUSE_QUEUE_SETS == 1 )
3065
3066     BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,
3067                                     QueueSetHandle_t xQueueSet )
3068     {
3069         BaseType_t xReturn;
3070         Queue_t * const pxQueueOrSemaphore = ( Queue_t * ) xQueueOrSemaphore;
3071
3072         if( pxQueueOrSemaphore->pxQueueSetContainer != xQueueSet )
3073         {
3074             /* The queue was not a member of the set. */
3075             xReturn = pdFAIL;
3076         }
3077         else if( pxQueueOrSemaphore->uxMessagesWaiting != ( UBaseType_t ) 0 )
3078         {
3079             /* It is dangerous to remove a queue from a set when the queue is
3080              * not empty because the queue set will still hold pending events for
3081              * the queue. */
3082             xReturn = pdFAIL;
3083         }
3084         else
3085         {
3086             taskENTER_CRITICAL();
3087             {
3088                 /* The queue is no longer contained in the set. */
3089                 pxQueueOrSemaphore->pxQueueSetContainer = NULL;
3090             }
3091             taskEXIT_CRITICAL();
3092             xReturn = pdPASS;
3093         }
3094
3095         return xReturn;
3096     } /*lint !e818 xQueueSet could not be declared as pointing to const as it is a typedef. */
3097
3098 #endif /* configUSE_QUEUE_SETS */
3099 /*-----------------------------------------------------------*/
3100
3101 #if ( configUSE_QUEUE_SETS == 1 )
3102
3103     QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
3104                                                 TickType_t const xTicksToWait )
3105     {
3106         QueueSetMemberHandle_t xReturn = NULL;
3107
3108         ( void ) xQueueReceive( ( QueueHandle_t ) xQueueSet, &xReturn, xTicksToWait ); /*lint !e961 Casting from one typedef to another is not redundant. */
3109         return xReturn;
3110     }
3111
3112 #endif /* configUSE_QUEUE_SETS */
3113 /*-----------------------------------------------------------*/
3114
3115 #if ( configUSE_QUEUE_SETS == 1 )
3116
3117     QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet )
3118     {
3119         QueueSetMemberHandle_t xReturn = NULL;
3120
3121         ( void ) xQueueReceiveFromISR( ( QueueHandle_t ) xQueueSet, &xReturn, NULL ); /*lint !e961 Casting from one typedef to another is not redundant. */
3122         return xReturn;
3123     }
3124
3125 #endif /* configUSE_QUEUE_SETS */
3126 /*-----------------------------------------------------------*/
3127
3128 #if ( configUSE_QUEUE_SETS == 1 )
3129
3130     static BaseType_t prvNotifyQueueSetContainer( const Queue_t * const pxQueue )
3131     {
3132         Queue_t * pxQueueSetContainer = pxQueue->pxQueueSetContainer;
3133         BaseType_t xReturn = pdFALSE;
3134
3135         /* This function must be called form a critical section. */
3136
3137         /* The following line is not reachable in unit tests because every call
3138          * to prvNotifyQueueSetContainer is preceded by a check that
3139          * pxQueueSetContainer != NULL */
3140         configASSERT( pxQueueSetContainer ); /* LCOV_EXCL_BR_LINE */
3141         configASSERT( pxQueueSetContainer->uxMessagesWaiting < pxQueueSetContainer->uxLength );
3142
3143         if( pxQueueSetContainer->uxMessagesWaiting < pxQueueSetContainer->uxLength )
3144         {
3145             const int8_t cTxLock = pxQueueSetContainer->cTxLock;
3146
3147             traceQUEUE_SET_SEND( pxQueueSetContainer );
3148
3149             /* The data copied is the handle of the queue that contains data. */
3150             xReturn = prvCopyDataToQueue( pxQueueSetContainer, &pxQueue, queueSEND_TO_BACK );
3151
3152             if( cTxLock == queueUNLOCKED )
3153             {
3154                 if( listLIST_IS_EMPTY( &( pxQueueSetContainer->xTasksWaitingToReceive ) ) == pdFALSE )
3155                 {
3156                     if( xTaskRemoveFromEventList( &( pxQueueSetContainer->xTasksWaitingToReceive ) ) != pdFALSE )
3157                     {
3158                         /* The task waiting has a higher priority. */
3159                         xReturn = pdTRUE;
3160                     }
3161                     else
3162                     {
3163                         mtCOVERAGE_TEST_MARKER();
3164                     }
3165                 }
3166                 else
3167                 {
3168                     mtCOVERAGE_TEST_MARKER();
3169                 }
3170             }
3171             else
3172             {
3173                 prvIncrementQueueTxLock( pxQueueSetContainer, cTxLock );
3174             }
3175         }
3176         else
3177         {
3178             mtCOVERAGE_TEST_MARKER();
3179         }
3180
3181         return xReturn;
3182     }
3183
3184 #endif /* configUSE_QUEUE_SETS */