git.sur5r.net Git - freertos/blob - FreeRTOS/Source/include/queue.h

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