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

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