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

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