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

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