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