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

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