begriffs open source - freertos/blob - include/queue.h

   1 /*
   2  * FreeRTOS Kernel V11.1.0
   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
  30 #ifndef QUEUE_H
  31 #define QUEUE_H
  32
  33 #ifndef INC_FREERTOS_H
  34     #error "include FreeRTOS.h" must appear in source files before "include queue.h"
  35 #endif
  36
  37 /* *INDENT-OFF* */
  38 #ifdef __cplusplus
  39     extern "C" {
  40 #endif
  41 /* *INDENT-ON* */
  42
  43 #include "task.h"
  44
  45 /**
  46  * Type by which queues are referenced.  For example, a call to xQueueCreate()
  47  * returns an QueueHandle_t variable that can then be used as a parameter to
  48  * xQueueSend(), xQueueReceive(), etc.
  49  */
  50 struct QueueDefinition; /* Using old naming convention so as not to break kernel aware debuggers. */
  51 typedef struct QueueDefinition   * QueueHandle_t;
  52
  53 /**
  54  * Type by which queue sets are referenced.  For example, a call to
  55  * xQueueCreateSet() returns an xQueueSet variable that can then be used as a
  56  * parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc.
  57  */
  58 typedef struct QueueDefinition   * QueueSetHandle_t;
  59
  60 /**
  61  * Queue sets can contain both queues and semaphores, so the
  62  * QueueSetMemberHandle_t is defined as a type to be used where a parameter or
  63  * return value can be either an QueueHandle_t or an SemaphoreHandle_t.
  64  */
  65 typedef struct QueueDefinition   * QueueSetMemberHandle_t;
  66
  67 /* For internal use only. */
  68 #define queueSEND_TO_BACK                     ( ( BaseType_t ) 0 )
  69 #define queueSEND_TO_FRONT                    ( ( BaseType_t ) 1 )
  70 #define queueOVERWRITE                        ( ( BaseType_t ) 2 )
  71
  72 /* For internal use only.  These definitions *must* match those in queue.c. */
  73 #define queueQUEUE_TYPE_BASE                  ( ( uint8_t ) 0U )
  74 #define queueQUEUE_TYPE_SET                   ( ( uint8_t ) 0U )
  75 #define queueQUEUE_TYPE_MUTEX                 ( ( uint8_t ) 1U )
  76 #define queueQUEUE_TYPE_COUNTING_SEMAPHORE    ( ( uint8_t ) 2U )
  77 #define queueQUEUE_TYPE_BINARY_SEMAPHORE      ( ( uint8_t ) 3U )
  78 #define queueQUEUE_TYPE_RECURSIVE_MUTEX       ( ( uint8_t ) 4U )
  79
  80 /**
  81  * queue. h
  82  * @code{c}
  83  * QueueHandle_t xQueueCreate(
  84  *                            UBaseType_t uxQueueLength,
  85  *                            UBaseType_t uxItemSize
  86  *                        );
  87  * @endcode
  88  *
  89  * Creates a new queue instance, and returns a handle by which the new queue
  90  * can be referenced.
  91  *
  92  * Internally, within the FreeRTOS implementation, queues use two blocks of
  93  * memory.  The first block is used to hold the queue's data structures.  The
  94  * second block is used to hold items placed into the queue.  If a queue is
  95  * created using xQueueCreate() then both blocks of memory are automatically
  96  * dynamically allocated inside the xQueueCreate() function.  (see
  97  * https://www.FreeRTOS.org/a00111.html).  If a queue is created using
  98  * xQueueCreateStatic() then the application writer must provide the memory that
  99  * will get used by the queue.  xQueueCreateStatic() therefore allows a queue to
 100  * be created without using any dynamic memory allocation.
 101  *
 102  * https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
 103  *
 104  * @param uxQueueLength The maximum number of items that the queue can contain.
 105  *
 106  * @param uxItemSize The number of bytes each item in the queue will require.
 107  * Items are queued by copy, not by reference, so this is the number of bytes
 108  * that will be copied for each posted item.  Each item on the queue must be
 109  * the same size.
 110  *
 111  * @return If the queue is successfully create then a handle to the newly
 112  * created queue is returned.  If the queue cannot be created then 0 is
 113  * returned.
 114  *
 115  * Example usage:
 116  * @code{c}
 117  * struct AMessage
 118  * {
 119  *  char ucMessageID;
 120  *  char ucData[ 20 ];
 121  * };
 122  *
 123  * void vATask( void *pvParameters )
 124  * {
 125  * QueueHandle_t xQueue1, xQueue2;
 126  *
 127  *  // Create a queue capable of containing 10 uint32_t values.
 128  *  xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
 129  *  if( xQueue1 == 0 )
 130  *  {
 131  *      // Queue was not created and must not be used.
 132  *  }
 133  *
 134  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 135  *  // These should be passed by pointer as they contain a lot of data.
 136  *  xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
 137  *  if( xQueue2 == 0 )
 138  *  {
 139  *      // Queue was not created and must not be used.
 140  *  }
 141  *
 142  *  // ... Rest of task code.
 143  * }
 144  * @endcode
 145  * \defgroup xQueueCreate xQueueCreate
 146  * \ingroup QueueManagement
 147  */
 148 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 149     #define xQueueCreate( uxQueueLength, uxItemSize )    xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )
 150 #endif
 151
 152 /**
 153  * queue. h
 154  * @code{c}
 155  * QueueHandle_t xQueueCreateStatic(
 156  *                            UBaseType_t uxQueueLength,
 157  *                            UBaseType_t uxItemSize,
 158  *                            uint8_t *pucQueueStorage,
 159  *                            StaticQueue_t *pxQueueBuffer
 160  *                        );
 161  * @endcode
 162  *
 163  * Creates a new queue instance, and returns a handle by which the new queue
 164  * can be referenced.
 165  *
 166  * Internally, within the FreeRTOS implementation, queues use two blocks of
 167  * memory.  The first block is used to hold the queue's data structures.  The
 168  * second block is used to hold items placed into the queue.  If a queue is
 169  * created using xQueueCreate() then both blocks of memory are automatically
 170  * dynamically allocated inside the xQueueCreate() function.  (see
 171  * https://www.FreeRTOS.org/a00111.html).  If a queue is created using
 172  * xQueueCreateStatic() then the application writer must provide the memory that
 173  * will get used by the queue.  xQueueCreateStatic() therefore allows a queue to
 174  * be created without using any dynamic memory allocation.
 175  *
 176  * https://www.FreeRTOS.org/Embedded-RTOS-Queues.html
 177  *
 178  * @param uxQueueLength The maximum number of items that the queue can contain.
 179  *
 180  * @param uxItemSize The number of bytes each item in the queue will require.
 181  * Items are queued by copy, not by reference, so this is the number of bytes
 182  * that will be copied for each posted item.  Each item on the queue must be
 183  * the same size.
 184  *
 185  * @param pucQueueStorage If uxItemSize is not zero then
 186  * pucQueueStorage must point to a uint8_t array that is at least large
 187  * enough to hold the maximum number of items that can be in the queue at any
 188  * one time - which is ( uxQueueLength * uxItemsSize ) bytes.  If uxItemSize is
 189  * zero then pucQueueStorage can be NULL.
 190  *
 191  * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which
 192  * will be used to hold the queue's data structure.
 193  *
 194  * @return If the queue is created then a handle to the created queue is
 195  * returned.  If pxQueueBuffer is NULL then NULL is returned.
 196  *
 197  * Example usage:
 198  * @code{c}
 199  * struct AMessage
 200  * {
 201  *  char ucMessageID;
 202  *  char ucData[ 20 ];
 203  * };
 204  *
 205  #define QUEUE_LENGTH 10
 206  #define ITEM_SIZE sizeof( uint32_t )
 207  *
 208  * // xQueueBuffer will hold the queue structure.
 209  * StaticQueue_t xQueueBuffer;
 210  *
 211  * // ucQueueStorage will hold the items posted to the queue.  Must be at least
 212  * // [(queue length) * ( queue item size)] bytes long.
 213  * uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
 214  *
 215  * void vATask( void *pvParameters )
 216  * {
 217  *  QueueHandle_t xQueue1;
 218  *
 219  *  // Create a queue capable of containing 10 uint32_t values.
 220  *  xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold.
 221  *                          ITEM_SIZE     // The size of each item in the queue
 222  *                          &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the queue.
 223  *                          &xQueueBuffer ); // The buffer that will hold the queue structure.
 224  *
 225  *  // The queue is guaranteed to be created successfully as no dynamic memory
 226  *  // allocation is used.  Therefore xQueue1 is now a handle to a valid queue.
 227  *
 228  *  // ... Rest of task code.
 229  * }
 230  * @endcode
 231  * \defgroup xQueueCreateStatic xQueueCreateStatic
 232  * \ingroup QueueManagement
 233  */
 234 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 235     #define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer )    xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )
 236 #endif /* configSUPPORT_STATIC_ALLOCATION */
 237
 238 /**
 239  * queue. h
 240  * @code{c}
 241  * BaseType_t xQueueGetStaticBuffers( QueueHandle_t xQueue,
 242  *                                    uint8_t ** ppucQueueStorage,
 243  *                                    StaticQueue_t ** ppxStaticQueue );
 244  * @endcode
 245  *
 246  * Retrieve pointers to a statically created queue's data structure buffer
 247  * and storage area buffer. These are the same buffers that are supplied
 248  * at the time of creation.
 249  *
 250  * @param xQueue The queue for which to retrieve the buffers.
 251  *
 252  * @param ppucQueueStorage Used to return a pointer to the queue's storage
 253  * area buffer.
 254  *
 255  * @param ppxStaticQueue Used to return a pointer to the queue's data
 256  * structure buffer.
 257  *
 258  * @return pdTRUE if buffers were retrieved, pdFALSE otherwise.
 259  *
 260  * \defgroup xQueueGetStaticBuffers xQueueGetStaticBuffers
 261  * \ingroup QueueManagement
 262  */
 263 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 264     #define xQueueGetStaticBuffers( xQueue, ppucQueueStorage, ppxStaticQueue )    xQueueGenericGetStaticBuffers( ( xQueue ), ( ppucQueueStorage ), ( ppxStaticQueue ) )
 265 #endif /* configSUPPORT_STATIC_ALLOCATION */
 266
 267 /**
 268  * queue. h
 269  * @code{c}
 270  * BaseType_t xQueueSendToFront(
 271  *                                 QueueHandle_t    xQueue,
 272  *                                 const void       *pvItemToQueue,
 273  *                                 TickType_t       xTicksToWait
 274  *                             );
 275  * @endcode
 276  *
 277  * Post an item to the front of a queue.  The item is queued by copy, not by
 278  * reference.  This function must not be called from an interrupt service
 279  * routine.  See xQueueSendFromISR () for an alternative which may be used
 280  * in an ISR.
 281  *
 282  * @param xQueue The handle to the queue on which the item is to be posted.
 283  *
 284  * @param pvItemToQueue A pointer to the item that is to be placed on the
 285  * queue.  The size of the items the queue will hold was defined when the
 286  * queue was created, so this many bytes will be copied from pvItemToQueue
 287  * into the queue storage area.
 288  *
 289  * @param xTicksToWait The maximum amount of time the task should block
 290  * waiting for space to become available on the queue, should it already
 291  * be full.  The call will return immediately if this is set to 0 and the
 292  * queue is full.  The time is defined in tick periods so the constant
 293  * portTICK_PERIOD_MS should be used to convert to real time if this is required.
 294  *
 295  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
 296  *
 297  * Example usage:
 298  * @code{c}
 299  * struct AMessage
 300  * {
 301  *  char ucMessageID;
 302  *  char ucData[ 20 ];
 303  * } xMessage;
 304  *
 305  * uint32_t ulVar = 10U;
 306  *
 307  * void vATask( void *pvParameters )
 308  * {
 309  * QueueHandle_t xQueue1, xQueue2;
 310  * struct AMessage *pxMessage;
 311  *
 312  *  // Create a queue capable of containing 10 uint32_t values.
 313  *  xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
 314  *
 315  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 316  *  // These should be passed by pointer as they contain a lot of data.
 317  *  xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
 318  *
 319  *  // ...
 320  *
 321  *  if( xQueue1 != 0 )
 322  *  {
 323  *      // Send an uint32_t.  Wait for 10 ticks for space to become
 324  *      // available if necessary.
 325  *      if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
 326  *      {
 327  *          // Failed to post the message, even after 10 ticks.
 328  *      }
 329  *  }
 330  *
 331  *  if( xQueue2 != 0 )
 332  *  {
 333  *      // Send a pointer to a struct AMessage object.  Don't block if the
 334  *      // queue is already full.
 335  *      pxMessage = & xMessage;
 336  *      xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
 337  *  }
 338  *
 339  *  // ... Rest of task code.
 340  * }
 341  * @endcode
 342  * \defgroup xQueueSend xQueueSend
 343  * \ingroup QueueManagement
 344  */
 345 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) \
 346     xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT )
 347
 348 /**
 349  * queue. h
 350  * @code{c}
 351  * BaseType_t xQueueSendToBack(
 352  *                                 QueueHandle_t    xQueue,
 353  *                                 const void       *pvItemToQueue,
 354  *                                 TickType_t       xTicksToWait
 355  *                             );
 356  * @endcode
 357  *
 358  * This is a macro that calls xQueueGenericSend().
 359  *
 360  * Post an item to the back of a queue.  The item is queued by copy, not by
 361  * reference.  This function must not be called from an interrupt service
 362  * routine.  See xQueueSendFromISR () for an alternative which may be used
 363  * in an ISR.
 364  *
 365  * @param xQueue The handle to the queue on which the item is to be posted.
 366  *
 367  * @param pvItemToQueue A pointer to the item that is to be placed on the
 368  * queue.  The size of the items the queue will hold was defined when the
 369  * queue was created, so this many bytes will be copied from pvItemToQueue
 370  * into the queue storage area.
 371  *
 372  * @param xTicksToWait The maximum amount of time the task should block
 373  * waiting for space to become available on the queue, should it already
 374  * be full.  The call will return immediately if this is set to 0 and the queue
 375  * is full.  The  time is defined in tick periods so the constant
 376  * portTICK_PERIOD_MS should be used to convert to real time if this is required.
 377  *
 378  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
 379  *
 380  * Example usage:
 381  * @code{c}
 382  * struct AMessage
 383  * {
 384  *  char ucMessageID;
 385  *  char ucData[ 20 ];
 386  * } xMessage;
 387  *
 388  * uint32_t ulVar = 10U;
 389  *
 390  * void vATask( void *pvParameters )
 391  * {
 392  * QueueHandle_t xQueue1, xQueue2;
 393  * struct AMessage *pxMessage;
 394  *
 395  *  // Create a queue capable of containing 10 uint32_t values.
 396  *  xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
 397  *
 398  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 399  *  // These should be passed by pointer as they contain a lot of data.
 400  *  xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
 401  *
 402  *  // ...
 403  *
 404  *  if( xQueue1 != 0 )
 405  *  {
 406  *      // Send an uint32_t.  Wait for 10 ticks for space to become
 407  *      // available if necessary.
 408  *      if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
 409  *      {
 410  *          // Failed to post the message, even after 10 ticks.
 411  *      }
 412  *  }
 413  *
 414  *  if( xQueue2 != 0 )
 415  *  {
 416  *      // Send a pointer to a struct AMessage object.  Don't block if the
 417  *      // queue is already full.
 418  *      pxMessage = & xMessage;
 419  *      xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
 420  *  }
 421  *
 422  *  // ... Rest of task code.
 423  * }
 424  * @endcode
 425  * \defgroup xQueueSend xQueueSend
 426  * \ingroup QueueManagement
 427  */
 428 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) \
 429     xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
 430
 431 /**
 432  * queue. h
 433  * @code{c}
 434  * BaseType_t xQueueSend(
 435  *                            QueueHandle_t xQueue,
 436  *                            const void * pvItemToQueue,
 437  *                            TickType_t xTicksToWait
 438  *                       );
 439  * @endcode
 440  *
 441  * This is a macro that calls xQueueGenericSend().  It is included for
 442  * backward compatibility with versions of FreeRTOS.org that did not
 443  * include the xQueueSendToFront() and xQueueSendToBack() macros.  It is
 444  * equivalent to xQueueSendToBack().
 445  *
 446  * Post an item on a queue.  The item is queued by copy, not by reference.
 447  * This function must not be called from an interrupt service routine.
 448  * See xQueueSendFromISR () for an alternative which may be used in an ISR.
 449  *
 450  * @param xQueue The handle to the queue on which the item is to be posted.
 451  *
 452  * @param pvItemToQueue A pointer to the item that is to be placed on the
 453  * queue.  The size of the items the queue will hold was defined when the
 454  * queue was created, so this many bytes will be copied from pvItemToQueue
 455  * into the queue storage area.
 456  *
 457  * @param xTicksToWait The maximum amount of time the task should block
 458  * waiting for space to become available on the queue, should it already
 459  * be full.  The call will return immediately if this is set to 0 and the
 460  * queue is full.  The time is defined in tick periods so the constant
 461  * portTICK_PERIOD_MS should be used to convert to real time if this is required.
 462  *
 463  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
 464  *
 465  * Example usage:
 466  * @code{c}
 467  * struct AMessage
 468  * {
 469  *  char ucMessageID;
 470  *  char ucData[ 20 ];
 471  * } xMessage;
 472  *
 473  * uint32_t ulVar = 10U;
 474  *
 475  * void vATask( void *pvParameters )
 476  * {
 477  * QueueHandle_t xQueue1, xQueue2;
 478  * struct AMessage *pxMessage;
 479  *
 480  *  // Create a queue capable of containing 10 uint32_t values.
 481  *  xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
 482  *
 483  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 484  *  // These should be passed by pointer as they contain a lot of data.
 485  *  xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
 486  *
 487  *  // ...
 488  *
 489  *  if( xQueue1 != 0 )
 490  *  {
 491  *      // Send an uint32_t.  Wait for 10 ticks for space to become
 492  *      // available if necessary.
 493  *      if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
 494  *      {
 495  *          // Failed to post the message, even after 10 ticks.
 496  *      }
 497  *  }
 498  *
 499  *  if( xQueue2 != 0 )
 500  *  {
 501  *      // Send a pointer to a struct AMessage object.  Don't block if the
 502  *      // queue is already full.
 503  *      pxMessage = & xMessage;
 504  *      xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
 505  *  }
 506  *
 507  *  // ... Rest of task code.
 508  * }
 509  * @endcode
 510  * \defgroup xQueueSend xQueueSend
 511  * \ingroup QueueManagement
 512  */
 513 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) \
 514     xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
 515
 516 /**
 517  * queue. h
 518  * @code{c}
 519  * BaseType_t xQueueOverwrite(
 520  *                            QueueHandle_t xQueue,
 521  *                            const void * pvItemToQueue
 522  *                       );
 523  * @endcode
 524  *
 525  * Only for use with queues that have a length of one - so the queue is either
 526  * empty or full.
 527  *
 528  * Post an item on a queue.  If the queue is already full then overwrite the
 529  * value held in the queue.  The item is queued by copy, not by reference.
 530  *
 531  * This function must not be called from an interrupt service routine.
 532  * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR.
 533  *
 534  * @param xQueue The handle of the queue to which the data is being sent.
 535  *
 536  * @param pvItemToQueue A pointer to the item that is to be placed on the
 537  * queue.  The size of the items the queue will hold was defined when the
 538  * queue was created, so this many bytes will be copied from pvItemToQueue
 539  * into the queue storage area.
 540  *
 541  * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and
 542  * therefore has the same return values as xQueueSendToFront().  However, pdPASS
 543  * is the only value that can be returned because xQueueOverwrite() will write
 544  * to the queue even when the queue is already full.
 545  *
 546  * Example usage:
 547  * @code{c}
 548  *
 549  * void vFunction( void *pvParameters )
 550  * {
 551  * QueueHandle_t xQueue;
 552  * uint32_t ulVarToSend, ulValReceived;
 553  *
 554  *  // Create a queue to hold one uint32_t value.  It is strongly
 555  *  // recommended *not* to use xQueueOverwrite() on queues that can
 556  *  // contain more than one value, and doing so will trigger an assertion
 557  *  // if configASSERT() is defined.
 558  *  xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
 559  *
 560  *  // Write the value 10 to the queue using xQueueOverwrite().
 561  *  ulVarToSend = 10;
 562  *  xQueueOverwrite( xQueue, &ulVarToSend );
 563  *
 564  *  // Peeking the queue should now return 10, but leave the value 10 in
 565  *  // the queue.  A block time of zero is used as it is known that the
 566  *  // queue holds a value.
 567  *  ulValReceived = 0;
 568  *  xQueuePeek( xQueue, &ulValReceived, 0 );
 569  *
 570  *  if( ulValReceived != 10 )
 571  *  {
 572  *      // Error unless the item was removed by a different task.
 573  *  }
 574  *
 575  *  // The queue is still full.  Use xQueueOverwrite() to overwrite the
 576  *  // value held in the queue with 100.
 577  *  ulVarToSend = 100;
 578  *  xQueueOverwrite( xQueue, &ulVarToSend );
 579  *
 580  *  // This time read from the queue, leaving the queue empty once more.
 581  *  // A block time of 0 is used again.
 582  *  xQueueReceive( xQueue, &ulValReceived, 0 );
 583  *
 584  *  // The value read should be the last value written, even though the
 585  *  // queue was already full when the value was written.
 586  *  if( ulValReceived != 100 )
 587  *  {
 588  *      // Error!
 589  *  }
 590  *
 591  *  // ...
 592  * }
 593  * @endcode
 594  * \defgroup xQueueOverwrite xQueueOverwrite
 595  * \ingroup QueueManagement
 596  */
 597 #define xQueueOverwrite( xQueue, pvItemToQueue ) \
 598     xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE )
 599
 600
 601 /**
 602  * queue. h
 603  * @code{c}
 604  * BaseType_t xQueueGenericSend(
 605  *                                  QueueHandle_t xQueue,
 606  *                                  const void * pvItemToQueue,
 607  *                                  TickType_t xTicksToWait
 608  *                                  BaseType_t xCopyPosition
 609  *                              );
 610  * @endcode
 611  *
 612  * It is preferred that the macros xQueueSend(), xQueueSendToFront() and
 613  * xQueueSendToBack() are used in place of calling this function directly.
 614  *
 615  * Post an item on a queue.  The item is queued by copy, not by reference.
 616  * This function must not be called from an interrupt service routine.
 617  * See xQueueSendFromISR () for an alternative which may be used in an ISR.
 618  *
 619  * @param xQueue The handle to the queue on which the item is to be posted.
 620  *
 621  * @param pvItemToQueue A pointer to the item that is to be placed on the
 622  * queue.  The size of the items the queue will hold was defined when the
 623  * queue was created, so this many bytes will be copied from pvItemToQueue
 624  * into the queue storage area.
 625  *
 626  * @param xTicksToWait The maximum amount of time the task should block
 627  * waiting for space to become available on the queue, should it already
 628  * be full.  The call will return immediately if this is set to 0 and the
 629  * queue is full.  The time is defined in tick periods so the constant
 630  * portTICK_PERIOD_MS should be used to convert to real time if this is required.
 631  *
 632  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
 633  * item at the back of the queue, or queueSEND_TO_FRONT to place the item
 634  * at the front of the queue (for high priority messages).
 635  *
 636  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
 637  *
 638  * Example usage:
 639  * @code{c}
 640  * struct AMessage
 641  * {
 642  *  char ucMessageID;
 643  *  char ucData[ 20 ];
 644  * } xMessage;
 645  *
 646  * uint32_t ulVar = 10U;
 647  *
 648  * void vATask( void *pvParameters )
 649  * {
 650  * QueueHandle_t xQueue1, xQueue2;
 651  * struct AMessage *pxMessage;
 652  *
 653  *  // Create a queue capable of containing 10 uint32_t values.
 654  *  xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
 655  *
 656  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 657  *  // These should be passed by pointer as they contain a lot of data.
 658  *  xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
 659  *
 660  *  // ...
 661  *
 662  *  if( xQueue1 != 0 )
 663  *  {
 664  *      // Send an uint32_t.  Wait for 10 ticks for space to become
 665  *      // available if necessary.
 666  *      if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10, queueSEND_TO_BACK ) != pdPASS )
 667  *      {
 668  *          // Failed to post the message, even after 10 ticks.
 669  *      }
 670  *  }
 671  *
 672  *  if( xQueue2 != 0 )
 673  *  {
 674  *      // Send a pointer to a struct AMessage object.  Don't block if the
 675  *      // queue is already full.
 676  *      pxMessage = & xMessage;
 677  *      xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0, queueSEND_TO_BACK );
 678  *  }
 679  *
 680  *  // ... Rest of task code.
 681  * }
 682  * @endcode
 683  * \defgroup xQueueSend xQueueSend
 684  * \ingroup QueueManagement
 685  */
 686 BaseType_t xQueueGenericSend( QueueHandle_t xQueue,
 687                               const void * const pvItemToQueue,
 688                               TickType_t xTicksToWait,
 689                               const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
 690
 691 /**
 692  * queue. h
 693  * @code{c}
 694  * BaseType_t xQueuePeek(
 695  *                           QueueHandle_t xQueue,
 696  *                           void * const pvBuffer,
 697  *                           TickType_t xTicksToWait
 698  *                       );
 699  * @endcode
 700  *
 701  * Receive an item from a queue without removing the item from the queue.
 702  * The item is received by copy so a buffer of adequate size must be
 703  * provided.  The number of bytes copied into the buffer was defined when
 704  * the queue was created.
 705  *
 706  * Successfully received items remain on the queue so will be returned again
 707  * by the next call, or a call to xQueueReceive().
 708  *
 709  * This macro must not be used in an interrupt service routine.  See
 710  * xQueuePeekFromISR() for an alternative that can be called from an interrupt
 711  * service routine.
 712  *
 713  * @param xQueue The handle to the queue from which the item is to be
 714  * received.
 715  *
 716  * @param pvBuffer Pointer to the buffer into which the received item will
 717  * be copied.
 718  *
 719  * @param xTicksToWait The maximum amount of time the task should block
 720  * waiting for an item to receive should the queue be empty at the time
 721  * of the call. The time is defined in tick periods so the constant
 722  * portTICK_PERIOD_MS should be used to convert to real time if this is required.
 723  * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue
 724  * is empty.
 725  *
 726  * @return pdTRUE if an item was successfully received from the queue,
 727  * otherwise pdFALSE.
 728  *
 729  * Example usage:
 730  * @code{c}
 731  * struct AMessage
 732  * {
 733  *  char ucMessageID;
 734  *  char ucData[ 20 ];
 735  * } xMessage;
 736  *
 737  * QueueHandle_t xQueue;
 738  *
 739  * // Task to create a queue and post a value.
 740  * void vATask( void *pvParameters )
 741  * {
 742  * struct AMessage *pxMessage;
 743  *
 744  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 745  *  // These should be passed by pointer as they contain a lot of data.
 746  *  xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
 747  *  if( xQueue == 0 )
 748  *  {
 749  *      // Failed to create the queue.
 750  *  }
 751  *
 752  *  // ...
 753  *
 754  *  // Send a pointer to a struct AMessage object.  Don't block if the
 755  *  // queue is already full.
 756  *  pxMessage = & xMessage;
 757  *  xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
 758  *
 759  *  // ... Rest of task code.
 760  * }
 761  *
 762  * // Task to peek the data from the queue.
 763  * void vADifferentTask( void *pvParameters )
 764  * {
 765  * struct AMessage *pxRxedMessage;
 766  *
 767  *  if( xQueue != 0 )
 768  *  {
 769  *      // Peek a message on the created queue.  Block for 10 ticks if a
 770  *      // message is not immediately available.
 771  *      if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
 772  *      {
 773  *          // pcRxedMessage now points to the struct AMessage variable posted
 774  *          // by vATask, but the item still remains on the queue.
 775  *      }
 776  *  }
 777  *
 778  *  // ... Rest of task code.
 779  * }
 780  * @endcode
 781  * \defgroup xQueuePeek xQueuePeek
 782  * \ingroup QueueManagement
 783  */
 784 BaseType_t xQueuePeek( QueueHandle_t xQueue,
 785                        void * const pvBuffer,
 786                        TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 787
 788 /**
 789  * queue. h
 790  * @code{c}
 791  * BaseType_t xQueuePeekFromISR(
 792  *                                  QueueHandle_t xQueue,
 793  *                                  void *pvBuffer,
 794  *                              );
 795  * @endcode
 796  *
 797  * A version of xQueuePeek() that can be called from an interrupt service
 798  * routine (ISR).
 799  *
 800  * Receive an item from a queue without removing the item from the queue.
 801  * The item is received by copy so a buffer of adequate size must be
 802  * provided.  The number of bytes copied into the buffer was defined when
 803  * the queue was created.
 804  *
 805  * Successfully received items remain on the queue so will be returned again
 806  * by the next call, or a call to xQueueReceive().
 807  *
 808  * @param xQueue The handle to the queue from which the item is to be
 809  * received.
 810  *
 811  * @param pvBuffer Pointer to the buffer into which the received item will
 812  * be copied.
 813  *
 814  * @return pdTRUE if an item was successfully received from the queue,
 815  * otherwise pdFALSE.
 816  *
 817  * \defgroup xQueuePeekFromISR xQueuePeekFromISR
 818  * \ingroup QueueManagement
 819  */
 820 BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue,
 821                               void * const pvBuffer ) PRIVILEGED_FUNCTION;
 822
 823 /**
 824  * queue. h
 825  * @code{c}
 826  * BaseType_t xQueueReceive(
 827  *                               QueueHandle_t xQueue,
 828  *                               void *pvBuffer,
 829  *                               TickType_t xTicksToWait
 830  *                          );
 831  * @endcode
 832  *
 833  * Receive an item from a queue.  The item is received by copy so a buffer of
 834  * adequate size must be provided.  The number of bytes copied into the buffer
 835  * was defined when the queue was created.
 836  *
 837  * Successfully received items are removed from the queue.
 838  *
 839  * This function must not be used in an interrupt service routine.  See
 840  * xQueueReceiveFromISR for an alternative that can.
 841  *
 842  * @param xQueue The handle to the queue from which the item is to be
 843  * received.
 844  *
 845  * @param pvBuffer Pointer to the buffer into which the received item will
 846  * be copied.
 847  *
 848  * @param xTicksToWait The maximum amount of time the task should block
 849  * waiting for an item to receive should the queue be empty at the time
 850  * of the call. xQueueReceive() will return immediately if xTicksToWait
 851  * is zero and the queue is empty.  The time is defined in tick periods so the
 852  * constant portTICK_PERIOD_MS should be used to convert to real time if this is
 853  * required.
 854  *
 855  * @return pdTRUE if an item was successfully received from the queue,
 856  * otherwise pdFALSE.
 857  *
 858  * Example usage:
 859  * @code{c}
 860  * struct AMessage
 861  * {
 862  *  char ucMessageID;
 863  *  char ucData[ 20 ];
 864  * } xMessage;
 865  *
 866  * QueueHandle_t xQueue;
 867  *
 868  * // Task to create a queue and post a value.
 869  * void vATask( void *pvParameters )
 870  * {
 871  * struct AMessage *pxMessage;
 872  *
 873  *  // Create a queue capable of containing 10 pointers to AMessage structures.
 874  *  // These should be passed by pointer as they contain a lot of data.
 875  *  xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
 876  *  if( xQueue == 0 )
 877  *  {
 878  *      // Failed to create the queue.
 879  *  }
 880  *
 881  *  // ...
 882  *
 883  *  // Send a pointer to a struct AMessage object.  Don't block if the
 884  *  // queue is already full.
 885  *  pxMessage = & xMessage;
 886  *  xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
 887  *
 888  *  // ... Rest of task code.
 889  * }
 890  *
 891  * // Task to receive from the queue.
 892  * void vADifferentTask( void *pvParameters )
 893  * {
 894  * struct AMessage *pxRxedMessage;
 895  *
 896  *  if( xQueue != 0 )
 897  *  {
 898  *      // Receive a message on the created queue.  Block for 10 ticks if a
 899  *      // message is not immediately available.
 900  *      if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
 901  *      {
 902  *          // pcRxedMessage now points to the struct AMessage variable posted
 903  *          // by vATask.
 904  *      }
 905  *  }
 906  *
 907  *  // ... Rest of task code.
 908  * }
 909  * @endcode
 910  * \defgroup xQueueReceive xQueueReceive
 911  * \ingroup QueueManagement
 912  */
 913 BaseType_t xQueueReceive( QueueHandle_t xQueue,
 914                           void * const pvBuffer,
 915                           TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 916
 917 /**
 918  * queue. h
 919  * @code{c}
 920  * UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );
 921  * @endcode
 922  *
 923  * Return the number of messages stored in a queue.
 924  *
 925  * @param xQueue A handle to the queue being queried.
 926  *
 927  * @return The number of messages available in the queue.
 928  *
 929  * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
 930  * \ingroup QueueManagement
 931  */
 932 UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
 933
 934 /**
 935  * queue. h
 936  * @code{c}
 937  * UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );
 938  * @endcode
 939  *
 940  * Return the number of free spaces available in a queue.  This is equal to the
 941  * number of items that can be sent to the queue before the queue becomes full
 942  * if no items are removed.
 943  *
 944  * @param xQueue A handle to the queue being queried.
 945  *
 946  * @return The number of spaces available in the queue.
 947  *
 948  * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
 949  * \ingroup QueueManagement
 950  */
 951 UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
 952
 953 /**
 954  * queue. h
 955  * @code{c}
 956  * void vQueueDelete( QueueHandle_t xQueue );
 957  * @endcode
 958  *
 959  * Delete a queue - freeing all the memory allocated for storing of items
 960  * placed on the queue.
 961  *
 962  * @param xQueue A handle to the queue to be deleted.
 963  *
 964  * \defgroup vQueueDelete vQueueDelete
 965  * \ingroup QueueManagement
 966  */
 967 void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
 968
 969 /**
 970  * queue. h
 971  * @code{c}
 972  * BaseType_t xQueueSendToFrontFromISR(
 973  *                                       QueueHandle_t xQueue,
 974  *                                       const void *pvItemToQueue,
 975  *                                       BaseType_t *pxHigherPriorityTaskWoken
 976  *                                    );
 977  * @endcode
 978  *
 979  * This is a macro that calls xQueueGenericSendFromISR().
 980  *
 981  * Post an item to the front of a queue.  It is safe to use this macro from
 982  * within an interrupt service routine.
 983  *
 984  * Items are queued by copy not reference so it is preferable to only
 985  * queue small items, especially when called from an ISR.  In most cases
 986  * it would be preferable to store a pointer to the item being queued.
 987  *
 988  * @param xQueue The handle to the queue on which the item is to be posted.
 989  *
 990  * @param pvItemToQueue A pointer to the item that is to be placed on the
 991  * queue.  The size of the items the queue will hold was defined when the
 992  * queue was created, so this many bytes will be copied from pvItemToQueue
 993  * into the queue storage area.
 994  *
 995  * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set
 996  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
 997  * to unblock, and the unblocked task has a priority higher than the currently
 998  * running task.  If xQueueSendToFrontFromISR() sets this value to pdTRUE then
 999  * a context switch should be requested before the interrupt is exited.
1000  *
1001  * @return pdTRUE if the data was successfully sent to the queue, otherwise
1002  * errQUEUE_FULL.
1003  *
1004  * Example usage for buffered IO (where the ISR can obtain more than one value
1005  * per call):
1006  * @code{c}
1007  * void vBufferISR( void )
1008  * {
1009  * char cIn;
1010  * BaseType_t xHigherPriorityTaskWoken;
1011  *
1012  *  // We have not woken a task at the start of the ISR.
1013  *  xHigherPriorityTaskWoken = pdFALSE;
1014  *
1015  *  // Loop until the buffer is empty.
1016  *  do
1017  *  {
1018  *      // Obtain a byte from the buffer.
1019  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
1020  *
1021  *      // Post the byte.
1022  *      xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
1023  *
1024  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );
1025  *
1026  *  // Now the buffer is empty we can switch context if necessary.
1027  *  if( xHigherPriorityTaskWoken )
1028  *  {
1029  *      taskYIELD ();
1030  *  }
1031  * }
1032  * @endcode
1033  *
1034  * \defgroup xQueueSendFromISR xQueueSendFromISR
1035  * \ingroup QueueManagement
1036  */
1037 #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \
1038     xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT )
1039
1040
1041 /**
1042  * queue. h
1043  * @code{c}
1044  * BaseType_t xQueueSendToBackFromISR(
1045  *                                       QueueHandle_t xQueue,
1046  *                                       const void *pvItemToQueue,
1047  *                                       BaseType_t *pxHigherPriorityTaskWoken
1048  *                                    );
1049  * @endcode
1050  *
1051  * This is a macro that calls xQueueGenericSendFromISR().
1052  *
1053  * Post an item to the back of a queue.  It is safe to use this macro from
1054  * within an interrupt service routine.
1055  *
1056  * Items are queued by copy not reference so it is preferable to only
1057  * queue small items, especially when called from an ISR.  In most cases
1058  * it would be preferable to store a pointer to the item being queued.
1059  *
1060  * @param xQueue The handle to the queue on which the item is to be posted.
1061  *
1062  * @param pvItemToQueue A pointer to the item that is to be placed on the
1063  * queue.  The size of the items the queue will hold was defined when the
1064  * queue was created, so this many bytes will be copied from pvItemToQueue
1065  * into the queue storage area.
1066  *
1067  * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set
1068  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1069  * to unblock, and the unblocked task has a priority higher than the currently
1070  * running task.  If xQueueSendToBackFromISR() sets this value to pdTRUE then
1071  * a context switch should be requested before the interrupt is exited.
1072  *
1073  * @return pdTRUE if the data was successfully sent to the queue, otherwise
1074  * errQUEUE_FULL.
1075  *
1076  * Example usage for buffered IO (where the ISR can obtain more than one value
1077  * per call):
1078  * @code{c}
1079  * void vBufferISR( void )
1080  * {
1081  * char cIn;
1082  * BaseType_t xHigherPriorityTaskWoken;
1083  *
1084  *  // We have not woken a task at the start of the ISR.
1085  *  xHigherPriorityTaskWoken = pdFALSE;
1086  *
1087  *  // Loop until the buffer is empty.
1088  *  do
1089  *  {
1090  *      // Obtain a byte from the buffer.
1091  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
1092  *
1093  *      // Post the byte.
1094  *      xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
1095  *
1096  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );
1097  *
1098  *  // Now the buffer is empty we can switch context if necessary.
1099  *  if( xHigherPriorityTaskWoken )
1100  *  {
1101  *      taskYIELD ();
1102  *  }
1103  * }
1104  * @endcode
1105  *
1106  * \defgroup xQueueSendFromISR xQueueSendFromISR
1107  * \ingroup QueueManagement
1108  */
1109 #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \
1110     xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
1111
1112 /**
1113  * queue. h
1114  * @code{c}
1115  * BaseType_t xQueueOverwriteFromISR(
1116  *                            QueueHandle_t xQueue,
1117  *                            const void * pvItemToQueue,
1118  *                            BaseType_t *pxHigherPriorityTaskWoken
1119  *                       );
1120  * @endcode
1121  *
1122  * A version of xQueueOverwrite() that can be used in an interrupt service
1123  * routine (ISR).
1124  *
1125  * Only for use with queues that can hold a single item - so the queue is either
1126  * empty or full.
1127  *
1128  * Post an item on a queue.  If the queue is already full then overwrite the
1129  * value held in the queue.  The item is queued by copy, not by reference.
1130  *
1131  * @param xQueue The handle to the queue on which the item is to be posted.
1132  *
1133  * @param pvItemToQueue A pointer to the item that is to be placed on the
1134  * queue.  The size of the items the queue will hold was defined when the
1135  * queue was created, so this many bytes will be copied from pvItemToQueue
1136  * into the queue storage area.
1137  *
1138  * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set
1139  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1140  * to unblock, and the unblocked task has a priority higher than the currently
1141  * running task.  If xQueueOverwriteFromISR() sets this value to pdTRUE then
1142  * a context switch should be requested before the interrupt is exited.
1143  *
1144  * @return xQueueOverwriteFromISR() is a macro that calls
1145  * xQueueGenericSendFromISR(), and therefore has the same return values as
1146  * xQueueSendToFrontFromISR().  However, pdPASS is the only value that can be
1147  * returned because xQueueOverwriteFromISR() will write to the queue even when
1148  * the queue is already full.
1149  *
1150  * Example usage:
1151  * @code{c}
1152  *
1153  * QueueHandle_t xQueue;
1154  *
1155  * void vFunction( void *pvParameters )
1156  * {
1157  *  // Create a queue to hold one uint32_t value.  It is strongly
1158  *  // recommended *not* to use xQueueOverwriteFromISR() on queues that can
1159  *  // contain more than one value, and doing so will trigger an assertion
1160  *  // if configASSERT() is defined.
1161  *  xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
1162  * }
1163  *
1164  * void vAnInterruptHandler( void )
1165  * {
1166  * // xHigherPriorityTaskWoken must be set to pdFALSE before it is used.
1167  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;
1168  * uint32_t ulVarToSend, ulValReceived;
1169  *
1170  *  // Write the value 10 to the queue using xQueueOverwriteFromISR().
1171  *  ulVarToSend = 10;
1172  *  xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
1173  *
1174  *  // The queue is full, but calling xQueueOverwriteFromISR() again will still
1175  *  // pass because the value held in the queue will be overwritten with the
1176  *  // new value.
1177  *  ulVarToSend = 100;
1178  *  xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
1179  *
1180  *  // Reading from the queue will now return 100.
1181  *
1182  *  // ...
1183  *
1184  *  if( xHigherPrioritytaskWoken == pdTRUE )
1185  *  {
1186  *      // Writing to the queue caused a task to unblock and the unblocked task
1187  *      // has a priority higher than or equal to the priority of the currently
1188  *      // executing task (the task this interrupt interrupted). Perform a context
1189  *      // switch so this interrupt returns directly to the unblocked task.
1190  *      // The macro used is port specific and will be either
1191  *      // portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to the documentation
1192  *      // page for the port being used.
1193  *      portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
1194  *  }
1195  * }
1196  * @endcode
1197  * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR
1198  * \ingroup QueueManagement
1199  */
1200 #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \
1201     xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE )
1202
1203 /**
1204  * queue. h
1205  * @code{c}
1206  * BaseType_t xQueueSendFromISR(
1207  *                                   QueueHandle_t xQueue,
1208  *                                   const void *pvItemToQueue,
1209  *                                   BaseType_t *pxHigherPriorityTaskWoken
1210  *                              );
1211  * @endcode
1212  *
1213  * This is a macro that calls xQueueGenericSendFromISR().  It is included
1214  * for backward compatibility with versions of FreeRTOS.org that did not
1215  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()
1216  * macros.
1217  *
1218  * Post an item to the back of a queue.  It is safe to use this function from
1219  * within an interrupt service routine.
1220  *
1221  * Items are queued by copy not reference so it is preferable to only
1222  * queue small items, especially when called from an ISR.  In most cases
1223  * it would be preferable to store a pointer to the item being queued.
1224  *
1225  * @param xQueue The handle to the queue on which the item is to be posted.
1226  *
1227  * @param pvItemToQueue A pointer to the item that is to be placed on the
1228  * queue.  The size of the items the queue will hold was defined when the
1229  * queue was created, so this many bytes will be copied from pvItemToQueue
1230  * into the queue storage area.
1231  *
1232  * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set
1233  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1234  * to unblock, and the unblocked task has a priority higher than the currently
1235  * running task.  If xQueueSendFromISR() sets this value to pdTRUE then
1236  * a context switch should be requested before the interrupt is exited.
1237  *
1238  * @return pdTRUE if the data was successfully sent to the queue, otherwise
1239  * errQUEUE_FULL.
1240  *
1241  * Example usage for buffered IO (where the ISR can obtain more than one value
1242  * per call):
1243  * @code{c}
1244  * void vBufferISR( void )
1245  * {
1246  * char cIn;
1247  * BaseType_t xHigherPriorityTaskWoken;
1248  *
1249  *  // We have not woken a task at the start of the ISR.
1250  *  xHigherPriorityTaskWoken = pdFALSE;
1251  *
1252  *  // Loop until the buffer is empty.
1253  *  do
1254  *  {
1255  *      // Obtain a byte from the buffer.
1256  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
1257  *
1258  *      // Post the byte.
1259  *      xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
1260  *
1261  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );
1262  *
1263  *  // Now the buffer is empty we can switch context if necessary.
1264  *  if( xHigherPriorityTaskWoken )
1265  *  {
1266  *       // As xHigherPriorityTaskWoken is now set to pdTRUE then a context
1267  *       // switch should be requested. The macro used is port specific and
1268  *       // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
1269  *       // refer to the documentation page for the port being used.
1270  *       portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
1271  *  }
1272  * }
1273  * @endcode
1274  *
1275  * \defgroup xQueueSendFromISR xQueueSendFromISR
1276  * \ingroup QueueManagement
1277  */
1278 #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) \
1279     xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
1280
1281 /**
1282  * queue. h
1283  * @code{c}
1284  * BaseType_t xQueueGenericSendFromISR(
1285  *                                         QueueHandle_t    xQueue,
1286  *                                         const    void    *pvItemToQueue,
1287  *                                         BaseType_t  *pxHigherPriorityTaskWoken,
1288  *                                         BaseType_t  xCopyPosition
1289  *                                     );
1290  * @endcode
1291  *
1292  * It is preferred that the macros xQueueSendFromISR(),
1293  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place
1294  * of calling this function directly.  xQueueGiveFromISR() is an
1295  * equivalent for use by semaphores that don't actually copy any data.
1296  *
1297  * Post an item on a queue.  It is safe to use this function from within an
1298  * interrupt service routine.
1299  *
1300  * Items are queued by copy not reference so it is preferable to only
1301  * queue small items, especially when called from an ISR.  In most cases
1302  * it would be preferable to store a pointer to the item being queued.
1303  *
1304  * @param xQueue The handle to the queue on which the item is to be posted.
1305  *
1306  * @param pvItemToQueue A pointer to the item that is to be placed on the
1307  * queue.  The size of the items the queue will hold was defined when the
1308  * queue was created, so this many bytes will be copied from pvItemToQueue
1309  * into the queue storage area.
1310  *
1311  * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set
1312  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1313  * to unblock, and the unblocked task has a priority higher than the currently
1314  * running task.  If xQueueGenericSendFromISR() sets this value to pdTRUE then
1315  * a context switch should be requested before the interrupt is exited.
1316  *
1317  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
1318  * item at the back of the queue, or queueSEND_TO_FRONT to place the item
1319  * at the front of the queue (for high priority messages).
1320  *
1321  * @return pdTRUE if the data was successfully sent to the queue, otherwise
1322  * errQUEUE_FULL.
1323  *
1324  * Example usage for buffered IO (where the ISR can obtain more than one value
1325  * per call):
1326  * @code{c}
1327  * void vBufferISR( void )
1328  * {
1329  * char cIn;
1330  * BaseType_t xHigherPriorityTaskWokenByPost;
1331  *
1332  *  // We have not woken a task at the start of the ISR.
1333  *  xHigherPriorityTaskWokenByPost = pdFALSE;
1334  *
1335  *  // Loop until the buffer is empty.
1336  *  do
1337  *  {
1338  *      // Obtain a byte from the buffer.
1339  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
1340  *
1341  *      // Post each byte.
1342  *      xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );
1343  *
1344  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );
1345  *
1346  *  // Now the buffer is empty we can switch context if necessary.
1347  *  if( xHigherPriorityTaskWokenByPost )
1348  *  {
1349  *       // As xHigherPriorityTaskWokenByPost is now set to pdTRUE then a context
1350  *       // switch should be requested. The macro used is port specific and
1351  *       // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
1352  *       // refer to the documentation page for the port being used.
1353  *       portYIELD_FROM_ISR( xHigherPriorityTaskWokenByPost );
1354  *  }
1355  * }
1356  * @endcode
1357  *
1358  * \defgroup xQueueSendFromISR xQueueSendFromISR
1359  * \ingroup QueueManagement
1360  */
1361 BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue,
1362                                      const void * const pvItemToQueue,
1363                                      BaseType_t * const pxHigherPriorityTaskWoken,
1364                                      const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
1365 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue,
1366                               BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
1367
1368 /**
1369  * queue. h
1370  * @code{c}
1371  * BaseType_t xQueueReceiveFromISR(
1372  *                                     QueueHandle_t    xQueue,
1373  *                                     void             *pvBuffer,
1374  *                                     BaseType_t       *pxTaskWoken
1375  *                                 );
1376  * @endcode
1377  *
1378  * Receive an item from a queue.  It is safe to use this function from within an
1379  * interrupt service routine.
1380  *
1381  * @param xQueue The handle to the queue from which the item is to be
1382  * received.
1383  *
1384  * @param pvBuffer Pointer to the buffer into which the received item will
1385  * be copied.
1386  *
1387  * @param pxHigherPriorityTaskWoken A task may be blocked waiting for space to
1388  * become available on the queue.  If xQueueReceiveFromISR causes such a task
1389  * to unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will
1390  * remain unchanged.
1391  *
1392  * @return pdTRUE if an item was successfully received from the queue,
1393  * otherwise pdFALSE.
1394  *
1395  * Example usage:
1396  * @code{c}
1397  *
1398  * QueueHandle_t xQueue;
1399  *
1400  * // Function to create a queue and post some values.
1401  * void vAFunction( void *pvParameters )
1402  * {
1403  * char cValueToPost;
1404  * const TickType_t xTicksToWait = ( TickType_t )0xff;
1405  *
1406  *  // Create a queue capable of containing 10 characters.
1407  *  xQueue = xQueueCreate( 10, sizeof( char ) );
1408  *  if( xQueue == 0 )
1409  *  {
1410  *      // Failed to create the queue.
1411  *  }
1412  *
1413  *  // ...
1414  *
1415  *  // Post some characters that will be used within an ISR.  If the queue
1416  *  // is full then this task will block for xTicksToWait ticks.
1417  *  cValueToPost = 'a';
1418  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
1419  *  cValueToPost = 'b';
1420  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
1421  *
1422  *  // ... keep posting characters ... this task may block when the queue
1423  *  // becomes full.
1424  *
1425  *  cValueToPost = 'c';
1426  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
1427  * }
1428  *
1429  * // ISR that outputs all the characters received on the queue.
1430  * void vISR_Routine( void )
1431  * {
1432  * BaseType_t xTaskWokenByReceive = pdFALSE;
1433  * char cRxedChar;
1434  *
1435  *  while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )
1436  *  {
1437  *      // A character was received.  Output the character now.
1438  *      vOutputCharacter( cRxedChar );
1439  *
1440  *      // If removing the character from the queue woke the task that was
1441  *      // posting onto the queue xTaskWokenByReceive will have been set to
1442  *      // pdTRUE.  No matter how many times this loop iterates only one
1443  *      // task will be woken.
1444  *  }
1445  *
1446  *  if( xTaskWokenByReceive != ( char ) pdFALSE;
1447  *  {
1448  *      taskYIELD ();
1449  *  }
1450  * }
1451  * @endcode
1452  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR
1453  * \ingroup QueueManagement
1454  */
1455 BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,
1456                                  void * const pvBuffer,
1457                                  BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
1458
1459 /*
1460  * Utilities to query queues that are safe to use from an ISR.  These utilities
1461  * should be used only from within an ISR, or within a critical section.
1462  */
1463 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1464 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1465 UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1466
1467 #if ( configUSE_CO_ROUTINES == 1 )
1468
1469 /*
1470  * The functions defined above are for passing data to and from tasks.  The
1471  * functions below are the equivalents for passing data to and from
1472  * co-routines.
1473  *
1474  * These functions are called from the co-routine macro implementation and
1475  * should not be called directly from application code.  Instead use the macro
1476  * wrappers defined within croutine.h.
1477  */
1478     BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue,
1479                                     const void * pvItemToQueue,
1480                                     BaseType_t xCoRoutinePreviouslyWoken );
1481     BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue,
1482                                        void * pvBuffer,
1483                                        BaseType_t * pxTaskWoken );
1484     BaseType_t xQueueCRSend( QueueHandle_t xQueue,
1485                              const void * pvItemToQueue,
1486                              TickType_t xTicksToWait );
1487     BaseType_t xQueueCRReceive( QueueHandle_t xQueue,
1488                                 void * pvBuffer,
1489                                 TickType_t xTicksToWait );
1490
1491 #endif /* if ( configUSE_CO_ROUTINES == 1 ) */
1492
1493 /*
1494  * For internal use only.  Use xSemaphoreCreateMutex(),
1495  * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling
1496  * these functions directly.
1497  */
1498 QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
1499
1500 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1501     QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType,
1502                                            StaticQueue_t * pxStaticQueue ) PRIVILEGED_FUNCTION;
1503 #endif
1504
1505 #if ( configUSE_COUNTING_SEMAPHORES == 1 )
1506     QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount,
1507                                                  const UBaseType_t uxInitialCount ) PRIVILEGED_FUNCTION;
1508 #endif
1509
1510 #if ( ( configUSE_COUNTING_SEMAPHORES == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
1511     QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount,
1512                                                        const UBaseType_t uxInitialCount,
1513                                                        StaticQueue_t * pxStaticQueue ) PRIVILEGED_FUNCTION;
1514 #endif
1515
1516 BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue,
1517                                 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1518
1519 #if ( ( configUSE_MUTEXES == 1 ) && ( INCLUDE_xSemaphoreGetMutexHolder == 1 ) )
1520     TaskHandle_t xQueueGetMutexHolder( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
1521     TaskHandle_t xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
1522 #endif
1523
1524 /*
1525  * For internal use only.  Use xSemaphoreTakeRecursive() or
1526  * xSemaphoreGiveRecursive() instead of calling these functions directly.
1527  */
1528 BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex,
1529                                      TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1530 BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;
1531
1532 /*
1533  * Reset a queue back to its original empty state.  The return value is now
1534  * obsolete and is always set to pdPASS.
1535  */
1536 #define xQueueReset( xQueue )    xQueueGenericReset( ( xQueue ), pdFALSE )
1537
1538 /*
1539  * The registry is provided as a means for kernel aware debuggers to
1540  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add
1541  * a queue, semaphore or mutex handle to the registry if you want the handle
1542  * to be available to a kernel aware debugger.  If you are not using a kernel
1543  * aware debugger then this function can be ignored.
1544  *
1545  * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the
1546  * registry can hold.  configQUEUE_REGISTRY_SIZE must be greater than 0
1547  * within FreeRTOSConfig.h for the registry to be available.  Its value
1548  * does not affect the number of queues, semaphores and mutexes that can be
1549  * created - just the number that the registry can hold.
1550  *
1551  * If vQueueAddToRegistry is called more than once with the same xQueue
1552  * parameter, the registry will store the pcQueueName parameter from the
1553  * most recent call to vQueueAddToRegistry.
1554  *
1555  * @param xQueue The handle of the queue being added to the registry.  This
1556  * is the handle returned by a call to xQueueCreate().  Semaphore and mutex
1557  * handles can also be passed in here.
1558  *
1559  * @param pcQueueName The name to be associated with the handle.  This is the
1560  * name that the kernel aware debugger will display.  The queue registry only
1561  * stores a pointer to the string - so the string must be persistent (global or
1562  * preferably in ROM/Flash), not on the stack.
1563  */
1564 #if ( configQUEUE_REGISTRY_SIZE > 0 )
1565     void vQueueAddToRegistry( QueueHandle_t xQueue,
1566                               const char * pcQueueName ) PRIVILEGED_FUNCTION;
1567 #endif
1568
1569 /*
1570  * The registry is provided as a means for kernel aware debuggers to
1571  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add
1572  * a queue, semaphore or mutex handle to the registry if you want the handle
1573  * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to
1574  * remove the queue, semaphore or mutex from the register.  If you are not using
1575  * a kernel aware debugger then this function can be ignored.
1576  *
1577  * @param xQueue The handle of the queue being removed from the registry.
1578  */
1579 #if ( configQUEUE_REGISTRY_SIZE > 0 )
1580     void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1581 #endif
1582
1583 /*
1584  * The queue registry is provided as a means for kernel aware debuggers to
1585  * locate queues, semaphores and mutexes.  Call pcQueueGetName() to look
1586  * up and return the name of a queue in the queue registry from the queue's
1587  * handle.
1588  *
1589  * @param xQueue The handle of the queue the name of which will be returned.
1590  * @return If the queue is in the registry then a pointer to the name of the
1591  * queue is returned.  If the queue is not in the registry then NULL is
1592  * returned.
1593  */
1594 #if ( configQUEUE_REGISTRY_SIZE > 0 )
1595     const char * pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1596 #endif
1597
1598 /*
1599  * Generic version of the function used to create a queue using dynamic memory
1600  * allocation.  This is called by other functions and macros that create other
1601  * RTOS objects that use the queue structure as their base.
1602  */
1603 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
1604     QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength,
1605                                        const UBaseType_t uxItemSize,
1606                                        const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
1607 #endif
1608
1609 /*
1610  * Generic version of the function used to create a queue using dynamic memory
1611  * allocation.  This is called by other functions and macros that create other
1612  * RTOS objects that use the queue structure as their base.
1613  */
1614 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1615     QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength,
1616                                              const UBaseType_t uxItemSize,
1617                                              uint8_t * pucQueueStorage,
1618                                              StaticQueue_t * pxStaticQueue,
1619                                              const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
1620 #endif
1621
1622 /*
1623  * Generic version of the function used to retrieve the buffers of statically
1624  * created queues. This is called by other functions and macros that retrieve
1625  * the buffers of other statically created RTOS objects that use the queue
1626  * structure as their base.
1627  */
1628 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
1629     BaseType_t xQueueGenericGetStaticBuffers( QueueHandle_t xQueue,
1630                                               uint8_t ** ppucQueueStorage,
1631                                               StaticQueue_t ** ppxStaticQueue ) PRIVILEGED_FUNCTION;
1632 #endif
1633
1634 /*
1635  * Queue sets provide a mechanism to allow a task to block (pend) on a read
1636  * operation from multiple queues or semaphores simultaneously.
1637  *
1638  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
1639  * function.
1640  *
1641  * A queue set must be explicitly created using a call to xQueueCreateSet()
1642  * before it can be used.  Once created, standard FreeRTOS queues and semaphores
1643  * can be added to the set using calls to xQueueAddToSet().
1644  * xQueueSelectFromSet() is then used to determine which, if any, of the queues
1645  * or semaphores contained in the set is in a state where a queue read or
1646  * semaphore take operation would be successful.
1647  *
1648  * Note 1:  See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html
1649  * for reasons why queue sets are very rarely needed in practice as there are
1650  * simpler methods of blocking on multiple objects.
1651  *
1652  * Note 2:  Blocking on a queue set that contains a mutex will not cause the
1653  * mutex holder to inherit the priority of the blocked task.
1654  *
1655  * Note 3:  An additional 4 bytes of RAM is required for each space in a every
1656  * queue added to a queue set.  Therefore counting semaphores that have a high
1657  * maximum count value should not be added to a queue set.
1658  *
1659  * Note 4:  A receive (in the case of a queue) or take (in the case of a
1660  * semaphore) operation must not be performed on a member of a queue set unless
1661  * a call to xQueueSelectFromSet() has first returned a handle to that set member.
1662  *
1663  * @param uxEventQueueLength Queue sets store events that occur on
1664  * the queues and semaphores contained in the set.  uxEventQueueLength specifies
1665  * the maximum number of events that can be queued at once.  To be absolutely
1666  * certain that events are not lost uxEventQueueLength should be set to the
1667  * total sum of the length of the queues added to the set, where binary
1668  * semaphores and mutexes have a length of 1, and counting semaphores have a
1669  * length set by their maximum count value.  Examples:
1670  *  + If a queue set is to hold a queue of length 5, another queue of length 12,
1671  *    and a binary semaphore, then uxEventQueueLength should be set to
1672  *    (5 + 12 + 1), or 18.
1673  *  + If a queue set is to hold three binary semaphores then uxEventQueueLength
1674  *    should be set to (1 + 1 + 1 ), or 3.
1675  *  + If a queue set is to hold a counting semaphore that has a maximum count of
1676  *    5, and a counting semaphore that has a maximum count of 3, then
1677  *    uxEventQueueLength should be set to (5 + 3), or 8.
1678  *
1679  * @return If the queue set is created successfully then a handle to the created
1680  * queue set is returned.  Otherwise NULL is returned.
1681  */
1682 #if ( ( configUSE_QUEUE_SETS == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
1683     QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION;
1684 #endif
1685
1686 /*
1687  * Adds a queue or semaphore to a queue set that was previously created by a
1688  * call to xQueueCreateSet().
1689  *
1690  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
1691  * function.
1692  *
1693  * Note 1:  A receive (in the case of a queue) or take (in the case of a
1694  * semaphore) operation must not be performed on a member of a queue set unless
1695  * a call to xQueueSelectFromSet() has first returned a handle to that set member.
1696  *
1697  * @param xQueueOrSemaphore The handle of the queue or semaphore being added to
1698  * the queue set (cast to an QueueSetMemberHandle_t type).
1699  *
1700  * @param xQueueSet The handle of the queue set to which the queue or semaphore
1701  * is being added.
1702  *
1703  * @return If the queue or semaphore was successfully added to the queue set
1704  * then pdPASS is returned.  If the queue could not be successfully added to the
1705  * queue set because it is already a member of a different queue set then pdFAIL
1706  * is returned.
1707  */
1708 #if ( configUSE_QUEUE_SETS == 1 )
1709     BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,
1710                                QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
1711 #endif
1712
1713 /*
1714  * Removes a queue or semaphore from a queue set.  A queue or semaphore can only
1715  * be removed from a set if the queue or semaphore is empty.
1716  *
1717  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
1718  * function.
1719  *
1720  * @param xQueueOrSemaphore The handle of the queue or semaphore being removed
1721  * from the queue set (cast to an QueueSetMemberHandle_t type).
1722  *
1723  * @param xQueueSet The handle of the queue set in which the queue or semaphore
1724  * is included.
1725  *
1726  * @return If the queue or semaphore was successfully removed from the queue set
1727  * then pdPASS is returned.  If the queue was not in the queue set, or the
1728  * queue (or semaphore) was not empty, then pdFAIL is returned.
1729  */
1730 #if ( configUSE_QUEUE_SETS == 1 )
1731     BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,
1732                                     QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
1733 #endif
1734
1735 /*
1736  * xQueueSelectFromSet() selects from the members of a queue set a queue or
1737  * semaphore that either contains data (in the case of a queue) or is available
1738  * to take (in the case of a semaphore).  xQueueSelectFromSet() effectively
1739  * allows a task to block (pend) on a read operation on all the queues and
1740  * semaphores in a queue set simultaneously.
1741  *
1742  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
1743  * function.
1744  *
1745  * Note 1:  See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html
1746  * for reasons why queue sets are very rarely needed in practice as there are
1747  * simpler methods of blocking on multiple objects.
1748  *
1749  * Note 2:  Blocking on a queue set that contains a mutex will not cause the
1750  * mutex holder to inherit the priority of the blocked task.
1751  *
1752  * Note 3:  A receive (in the case of a queue) or take (in the case of a
1753  * semaphore) operation must not be performed on a member of a queue set unless
1754  * a call to xQueueSelectFromSet() has first returned a handle to that set member.
1755  *
1756  * @param xQueueSet The queue set on which the task will (potentially) block.
1757  *
1758  * @param xTicksToWait The maximum time, in ticks, that the calling task will
1759  * remain in the Blocked state (with other tasks executing) to wait for a member
1760  * of the queue set to be ready for a successful queue read or semaphore take
1761  * operation.
1762  *
1763  * @return xQueueSelectFromSet() will return the handle of a queue (cast to
1764  * a QueueSetMemberHandle_t type) contained in the queue set that contains data,
1765  * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained
1766  * in the queue set that is available, or NULL if no such queue or semaphore
1767  * exists before before the specified block time expires.
1768  */
1769 #if ( configUSE_QUEUE_SETS == 1 )
1770     QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,
1771                                                 const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
1772 #endif
1773
1774 /*
1775  * A version of xQueueSelectFromSet() that can be used from an ISR.
1776  */
1777 #if ( configUSE_QUEUE_SETS == 1 )
1778     QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
1779 #endif
1780
1781 /* Not public API functions. */
1782 void vQueueWaitForMessageRestricted( QueueHandle_t xQueue,
1783                                      TickType_t xTicksToWait,
1784                                      const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
1785 BaseType_t xQueueGenericReset( QueueHandle_t xQueue,
1786                                BaseType_t xNewQueue ) PRIVILEGED_FUNCTION;
1787
1788 #if ( configUSE_TRACE_FACILITY == 1 )
1789     void vQueueSetQueueNumber( QueueHandle_t xQueue,
1790                                UBaseType_t uxQueueNumber ) PRIVILEGED_FUNCTION;
1791 #endif
1792
1793 #if ( configUSE_TRACE_FACILITY == 1 )
1794     UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1795 #endif
1796
1797 #if ( configUSE_TRACE_FACILITY == 1 )
1798     uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1799 #endif
1800
1801 UBaseType_t uxQueueGetQueueItemSize( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1802 UBaseType_t uxQueueGetQueueLength( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
1803
1804 /* *INDENT-OFF* */
1805 #ifdef __cplusplus
1806     }
1807 #endif
1808 /* *INDENT-ON* */
1809
1810 #endif /* QUEUE_H */