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

   1 /*\r
   2  * FreeRTOS Kernel V10.3.1\r
   3  * Copyright (C) 2020 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,\r
 651                                   const void * const pvItemToQueue,\r
 652                                   TickType_t xTicksToWait,\r
 653                                   const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;\r
 654 \r
 655 /**\r
 656  * queue. h\r
 657  * <pre>\r
 658  * BaseType_t xQueuePeek(\r
 659  *                           QueueHandle_t xQueue,\r
 660  *                           void * const pvBuffer,\r
 661  *                           TickType_t xTicksToWait\r
 662  *                       );</pre>\r
 663  *\r
 664  * Receive an item from a queue without removing the item from the queue.\r
 665  * The item is received by copy so a buffer of adequate size must be\r
 666  * provided.  The number of bytes copied into the buffer was defined when\r
 667  * the queue was created.\r
 668  *\r
 669  * Successfully received items remain on the queue so will be returned again\r
 670  * by the next call, or a call to xQueueReceive().\r
 671  *\r
 672  * This macro must not be used in an interrupt service routine.  See\r
 673  * xQueuePeekFromISR() for an alternative that can be called from an interrupt\r
 674  * service routine.\r
 675  *\r
 676  * @param xQueue The handle to the queue from which the item is to be\r
 677  * received.\r
 678  *\r
 679  * @param pvBuffer Pointer to the buffer into which the received item will\r
 680  * be copied.\r
 681  *\r
 682  * @param xTicksToWait The maximum amount of time the task should block\r
 683  * waiting for an item to receive should the queue be empty at the time\r
 684  * of the call.  The time is defined in tick periods so the constant\r
 685  * portTICK_PERIOD_MS should be used to convert to real time if this is required.\r
 686  * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue\r
 687  * is empty.\r
 688  *\r
 689  * @return pdTRUE if an item was successfully received from the queue,\r
 690  * otherwise pdFALSE.\r
 691  *\r
 692  * Example usage:\r
 693  * <pre>\r
 694  * struct AMessage\r
 695  * {\r
 696  *  char ucMessageID;\r
 697  *  char ucData[ 20 ];\r
 698  * } xMessage;\r
 699  *\r
 700  * QueueHandle_t xQueue;\r
 701  *\r
 702  * // Task to create a queue and post a value.\r
 703  * void vATask( void *pvParameters )\r
 704  * {\r
 705  * struct AMessage *pxMessage;\r
 706  *\r
 707  *  // Create a queue capable of containing 10 pointers to AMessage structures.\r
 708  *  // These should be passed by pointer as they contain a lot of data.\r
 709  *  xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 710  *  if( xQueue == 0 )\r
 711  *  {\r
 712  *      // Failed to create the queue.\r
 713  *  }\r
 714  *\r
 715  *  // ...\r
 716  *\r
 717  *  // Send a pointer to a struct AMessage object.  Don't block if the\r
 718  *  // queue is already full.\r
 719  *  pxMessage = & xMessage;\r
 720  *  xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );\r
 721  *\r
 722  *  // ... Rest of task code.\r
 723  * }\r
 724  *\r
 725  * // Task to peek the data from the queue.\r
 726  * void vADifferentTask( void *pvParameters )\r
 727  * {\r
 728  * struct AMessage *pxRxedMessage;\r
 729  *\r
 730  *  if( xQueue != 0 )\r
 731  *  {\r
 732  *      // Peek a message on the created queue.  Block for 10 ticks if a\r
 733  *      // message is not immediately available.\r
 734  *      if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )\r
 735  *      {\r
 736  *          // pcRxedMessage now points to the struct AMessage variable posted\r
 737  *          // by vATask, but the item still remains on the queue.\r
 738  *      }\r
 739  *  }\r
 740  *\r
 741  *  // ... Rest of task code.\r
 742  * }\r
 743  * </pre>\r
 744  * \defgroup xQueuePeek xQueuePeek\r
 745  * \ingroup QueueManagement\r
 746  */\r
 747     BaseType_t xQueuePeek( QueueHandle_t xQueue,\r
 748                            void * const pvBuffer,\r
 749                            TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
 750 \r
 751 /**\r
 752  * queue. h\r
 753  * <pre>\r
 754  * BaseType_t xQueuePeekFromISR(\r
 755  *                                  QueueHandle_t xQueue,\r
 756  *                                  void *pvBuffer,\r
 757  *                              );</pre>\r
 758  *\r
 759  * A version of xQueuePeek() that can be called from an interrupt service\r
 760  * routine (ISR).\r
 761  *\r
 762  * Receive an item from a queue without removing the item from the queue.\r
 763  * The item is received by copy so a buffer of adequate size must be\r
 764  * provided.  The number of bytes copied into the buffer was defined when\r
 765  * the queue was created.\r
 766  *\r
 767  * Successfully received items remain on the queue so will be returned again\r
 768  * by the next call, or a call to xQueueReceive().\r
 769  *\r
 770  * @param xQueue The handle to the queue from which the item is to be\r
 771  * received.\r
 772  *\r
 773  * @param pvBuffer Pointer to the buffer into which the received item will\r
 774  * be copied.\r
 775  *\r
 776  * @return pdTRUE if an item was successfully received from the queue,\r
 777  * otherwise pdFALSE.\r
 778  *\r
 779  * \defgroup xQueuePeekFromISR xQueuePeekFromISR\r
 780  * \ingroup QueueManagement\r
 781  */\r
 782     BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue,\r
 783                                   void * const pvBuffer ) PRIVILEGED_FUNCTION;\r
 784 \r
 785 /**\r
 786  * queue. h\r
 787  * <pre>\r
 788  * BaseType_t xQueueReceive(\r
 789  *                               QueueHandle_t xQueue,\r
 790  *                               void *pvBuffer,\r
 791  *                               TickType_t xTicksToWait\r
 792  *                          );</pre>\r
 793  *\r
 794  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 795  * adequate size must be provided.  The number of bytes copied into the buffer\r
 796  * was defined when the queue was created.\r
 797  *\r
 798  * Successfully received items are removed from the queue.\r
 799  *\r
 800  * This function must not be used in an interrupt service routine.  See\r
 801  * xQueueReceiveFromISR for an alternative that can.\r
 802  *\r
 803  * @param xQueue The handle to the queue from which the item is to be\r
 804  * received.\r
 805  *\r
 806  * @param pvBuffer Pointer to the buffer into which the received item will\r
 807  * be copied.\r
 808  *\r
 809  * @param xTicksToWait The maximum amount of time the task should block\r
 810  * waiting for an item to receive should the queue be empty at the time\r
 811  * of the call.  xQueueReceive() will return immediately if xTicksToWait\r
 812  * is zero and the queue is empty.  The time is defined in tick periods so the\r
 813  * constant portTICK_PERIOD_MS should be used to convert to real time if this is\r
 814  * required.\r
 815  *\r
 816  * @return pdTRUE if an item was successfully received from the queue,\r
 817  * otherwise pdFALSE.\r
 818  *\r
 819  * Example usage:\r
 820  * <pre>\r
 821  * struct AMessage\r
 822  * {\r
 823  *  char ucMessageID;\r
 824  *  char ucData[ 20 ];\r
 825  * } xMessage;\r
 826  *\r
 827  * QueueHandle_t xQueue;\r
 828  *\r
 829  * // Task to create a queue and post a value.\r
 830  * void vATask( void *pvParameters )\r
 831  * {\r
 832  * struct AMessage *pxMessage;\r
 833  *\r
 834  *  // Create a queue capable of containing 10 pointers to AMessage structures.\r
 835  *  // These should be passed by pointer as they contain a lot of data.\r
 836  *  xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 837  *  if( xQueue == 0 )\r
 838  *  {\r
 839  *      // Failed to create the queue.\r
 840  *  }\r
 841  *\r
 842  *  // ...\r
 843  *\r
 844  *  // Send a pointer to a struct AMessage object.  Don't block if the\r
 845  *  // queue is already full.\r
 846  *  pxMessage = & xMessage;\r
 847  *  xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );\r
 848  *\r
 849  *  // ... Rest of task code.\r
 850  * }\r
 851  *\r
 852  * // Task to receive from the queue.\r
 853  * void vADifferentTask( void *pvParameters )\r
 854  * {\r
 855  * struct AMessage *pxRxedMessage;\r
 856  *\r
 857  *  if( xQueue != 0 )\r
 858  *  {\r
 859  *      // Receive a message on the created queue.  Block for 10 ticks if a\r
 860  *      // message is not immediately available.\r
 861  *      if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )\r
 862  *      {\r
 863  *          // pcRxedMessage now points to the struct AMessage variable posted\r
 864  *          // by vATask.\r
 865  *      }\r
 866  *  }\r
 867  *\r
 868  *  // ... Rest of task code.\r
 869  * }\r
 870  * </pre>\r
 871  * \defgroup xQueueReceive xQueueReceive\r
 872  * \ingroup QueueManagement\r
 873  */\r
 874     BaseType_t xQueueReceive( QueueHandle_t xQueue,\r
 875                               void * const pvBuffer,\r
 876                               TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
 877 \r
 878 /**\r
 879  * queue. h\r
 880  * <pre>UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );</pre>\r
 881  *\r
 882  * Return the number of messages stored in a queue.\r
 883  *\r
 884  * @param xQueue A handle to the queue being queried.\r
 885  *\r
 886  * @return The number of messages available in the queue.\r
 887  *\r
 888  * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting\r
 889  * \ingroup QueueManagement\r
 890  */\r
 891     UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
 892 \r
 893 /**\r
 894  * queue. h\r
 895  * <pre>UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );</pre>\r
 896  *\r
 897  * Return the number of free spaces available in a queue.  This is equal to the\r
 898  * number of items that can be sent to the queue before the queue becomes full\r
 899  * if no items are removed.\r
 900  *\r
 901  * @param xQueue A handle to the queue being queried.\r
 902  *\r
 903  * @return The number of spaces available in the queue.\r
 904  *\r
 905  * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting\r
 906  * \ingroup QueueManagement\r
 907  */\r
 908     UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
 909 \r
 910 /**\r
 911  * queue. h\r
 912  * <pre>void vQueueDelete( QueueHandle_t xQueue );</pre>\r
 913  *\r
 914  * Delete a queue - freeing all the memory allocated for storing of items\r
 915  * placed on the queue.\r
 916  *\r
 917  * @param xQueue A handle to the queue to be deleted.\r
 918  *\r
 919  * \defgroup vQueueDelete vQueueDelete\r
 920  * \ingroup QueueManagement\r
 921  */\r
 922     void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
 923 \r
 924 /**\r
 925  * queue. h\r
 926  * <pre>\r
 927  * BaseType_t xQueueSendToFrontFromISR(\r
 928  *                                       QueueHandle_t xQueue,\r
 929  *                                       const void *pvItemToQueue,\r
 930  *                                       BaseType_t *pxHigherPriorityTaskWoken\r
 931  *                                    );\r
 932  * </pre>\r
 933  *\r
 934  * This is a macro that calls xQueueGenericSendFromISR().\r
 935  *\r
 936  * Post an item to the front of a queue.  It is safe to use this macro from\r
 937  * within an interrupt service routine.\r
 938  *\r
 939  * Items are queued by copy not reference so it is preferable to only\r
 940  * queue small items, especially when called from an ISR.  In most cases\r
 941  * it would be preferable to store a pointer to the item being queued.\r
 942  *\r
 943  * @param xQueue The handle to the queue on which the item is to be posted.\r
 944  *\r
 945  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 946  * queue.  The size of the items the queue will hold was defined when the\r
 947  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 948  * into the queue storage area.\r
 949  *\r
 950  * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set\r
 951  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 952  * to unblock, and the unblocked task has a priority higher than the currently\r
 953  * running task.  If xQueueSendToFromFromISR() sets this value to pdTRUE then\r
 954  * a context switch should be requested before the interrupt is exited.\r
 955  *\r
 956  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 957  * errQUEUE_FULL.\r
 958  *\r
 959  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 960  * per call):\r
 961  * <pre>\r
 962  * void vBufferISR( void )\r
 963  * {\r
 964  * char cIn;\r
 965  * BaseType_t xHigherPrioritTaskWoken;\r
 966  *\r
 967  *  // We have not woken a task at the start of the ISR.\r
 968  *  xHigherPriorityTaskWoken = pdFALSE;\r
 969  *\r
 970  *  // Loop until the buffer is empty.\r
 971  *  do\r
 972  *  {\r
 973  *      // Obtain a byte from the buffer.\r
 974  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );\r
 975  *\r
 976  *      // Post the byte.\r
 977  *      xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 978  *\r
 979  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 980  *\r
 981  *  // Now the buffer is empty we can switch context if necessary.\r
 982  *  if( xHigherPriorityTaskWoken )\r
 983  *  {\r
 984  *      taskYIELD ();\r
 985  *  }\r
 986  * }\r
 987  * </pre>\r
 988  *\r
 989  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 990  * \ingroup QueueManagement\r
 991  */\r
 992     #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken )    xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT )\r
 993 \r
 994 \r
 995 /**\r
 996  * queue. h\r
 997  * <pre>\r
 998  * BaseType_t xQueueSendToBackFromISR(\r
 999  *                                       QueueHandle_t xQueue,\r
1000  *                                       const void *pvItemToQueue,\r
1001  *                                       BaseType_t *pxHigherPriorityTaskWoken\r
1002  *                                    );\r
1003  * </pre>\r
1004  *\r
1005  * This is a macro that calls xQueueGenericSendFromISR().\r
1006  *\r
1007  * Post an item to the back of a queue.  It is safe to use this macro from\r
1008  * within an interrupt service routine.\r
1009  *\r
1010  * Items are queued by copy not reference so it is preferable to only\r
1011  * queue small items, especially when called from an ISR.  In most cases\r
1012  * it would be preferable to store a pointer to the item being queued.\r
1013  *\r
1014  * @param xQueue The handle to the queue on which the item is to be posted.\r
1015  *\r
1016  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1017  * queue.  The size of the items the queue will hold was defined when the\r
1018  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1019  * into the queue storage area.\r
1020  *\r
1021  * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set\r
1022  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1023  * to unblock, and the unblocked task has a priority higher than the currently\r
1024  * running task.  If xQueueSendToBackFromISR() sets this value to pdTRUE then\r
1025  * a context switch should be requested before the interrupt is exited.\r
1026  *\r
1027  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1028  * errQUEUE_FULL.\r
1029  *\r
1030  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1031  * per call):\r
1032  * <pre>\r
1033  * void vBufferISR( void )\r
1034  * {\r
1035  * char cIn;\r
1036  * BaseType_t xHigherPriorityTaskWoken;\r
1037  *\r
1038  *  // We have not woken a task at the start of the ISR.\r
1039  *  xHigherPriorityTaskWoken = pdFALSE;\r
1040  *\r
1041  *  // Loop until the buffer is empty.\r
1042  *  do\r
1043  *  {\r
1044  *      // Obtain a byte from the buffer.\r
1045  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );\r
1046  *\r
1047  *      // Post the byte.\r
1048  *      xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
1049  *\r
1050  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1051  *\r
1052  *  // Now the buffer is empty we can switch context if necessary.\r
1053  *  if( xHigherPriorityTaskWoken )\r
1054  *  {\r
1055  *      taskYIELD ();\r
1056  *  }\r
1057  * }\r
1058  * </pre>\r
1059  *\r
1060  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1061  * \ingroup QueueManagement\r
1062  */\r
1063     #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken )    xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )\r
1064 \r
1065 /**\r
1066  * queue. h\r
1067  * <pre>\r
1068  * BaseType_t xQueueOverwriteFromISR(\r
1069  *                            QueueHandle_t xQueue,\r
1070  *                            const void * pvItemToQueue,\r
1071  *                            BaseType_t *pxHigherPriorityTaskWoken\r
1072  *                       );\r
1073  * </pre>\r
1074  *\r
1075  * A version of xQueueOverwrite() that can be used in an interrupt service\r
1076  * routine (ISR).\r
1077  *\r
1078  * Only for use with queues that can hold a single item - so the queue is either\r
1079  * empty or full.\r
1080  *\r
1081  * Post an item on a queue.  If the queue is already full then overwrite the\r
1082  * value held in the queue.  The item is queued by copy, not by reference.\r
1083  *\r
1084  * @param xQueue The handle to the queue on which the item is to be posted.\r
1085  *\r
1086  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1087  * queue.  The size of the items the queue will hold was defined when the\r
1088  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1089  * into the queue storage area.\r
1090  *\r
1091  * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set\r
1092  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1093  * to unblock, and the unblocked task has a priority higher than the currently\r
1094  * running task.  If xQueueOverwriteFromISR() sets this value to pdTRUE then\r
1095  * a context switch should be requested before the interrupt is exited.\r
1096  *\r
1097  * @return xQueueOverwriteFromISR() is a macro that calls\r
1098  * xQueueGenericSendFromISR(), and therefore has the same return values as\r
1099  * xQueueSendToFrontFromISR().  However, pdPASS is the only value that can be\r
1100  * returned because xQueueOverwriteFromISR() will write to the queue even when\r
1101  * the queue is already full.\r
1102  *\r
1103  * Example usage:\r
1104  * <pre>\r
1105  *\r
1106  * QueueHandle_t xQueue;\r
1107  *\r
1108  * void vFunction( void *pvParameters )\r
1109  * {\r
1110  *  // Create a queue to hold one uint32_t value.  It is strongly\r
1111  *  // recommended *not* to use xQueueOverwriteFromISR() on queues that can\r
1112  *  // contain more than one value, and doing so will trigger an assertion\r
1113  *  // if configASSERT() is defined.\r
1114  *  xQueue = xQueueCreate( 1, sizeof( uint32_t ) );\r
1115  * }\r
1116  *\r
1117  * void vAnInterruptHandler( void )\r
1118  * {\r
1119  * // xHigherPriorityTaskWoken must be set to pdFALSE before it is used.\r
1120  * BaseType_t xHigherPriorityTaskWoken = pdFALSE;\r
1121  * uint32_t ulVarToSend, ulValReceived;\r
1122  *\r
1123  *  // Write the value 10 to the queue using xQueueOverwriteFromISR().\r
1124  *  ulVarToSend = 10;\r
1125  *  xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );\r
1126  *\r
1127  *  // The queue is full, but calling xQueueOverwriteFromISR() again will still\r
1128  *  // pass because the value held in the queue will be overwritten with the\r
1129  *  // new value.\r
1130  *  ulVarToSend = 100;\r
1131  *  xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );\r
1132  *\r
1133  *  // Reading from the queue will now return 100.\r
1134  *\r
1135  *  // ...\r
1136  *\r
1137  *  if( xHigherPrioritytaskWoken == pdTRUE )\r
1138  *  {\r
1139  *      // Writing to the queue caused a task to unblock and the unblocked task\r
1140  *      // has a priority higher than or equal to the priority of the currently\r
1141  *      // executing task (the task this interrupt interrupted).  Perform a context\r
1142  *      // switch so this interrupt returns directly to the unblocked task.\r
1143  *      portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.\r
1144  *  }\r
1145  * }\r
1146  * </pre>\r
1147  * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR\r
1148  * \ingroup QueueManagement\r
1149  */\r
1150     #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken )     xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE )\r
1151 \r
1152 /**\r
1153  * queue. h\r
1154  * <pre>\r
1155  * BaseType_t xQueueSendFromISR(\r
1156  *                                   QueueHandle_t xQueue,\r
1157  *                                   const void *pvItemToQueue,\r
1158  *                                   BaseType_t *pxHigherPriorityTaskWoken\r
1159  *                              );\r
1160  * </pre>\r
1161  *\r
1162  * This is a macro that calls xQueueGenericSendFromISR().  It is included\r
1163  * for backward compatibility with versions of FreeRTOS.org that did not\r
1164  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()\r
1165  * macros.\r
1166  *\r
1167  * Post an item to the back of a queue.  It is safe to use this function from\r
1168  * within an interrupt service routine.\r
1169  *\r
1170  * Items are queued by copy not reference so it is preferable to only\r
1171  * queue small items, especially when called from an ISR.  In most cases\r
1172  * it would be preferable to store a pointer to the item being queued.\r
1173  *\r
1174  * @param xQueue The handle to the queue on which the item is to be posted.\r
1175  *\r
1176  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1177  * queue.  The size of the items the queue will hold was defined when the\r
1178  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1179  * into the queue storage area.\r
1180  *\r
1181  * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set\r
1182  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1183  * to unblock, and the unblocked task has a priority higher than the currently\r
1184  * running task.  If xQueueSendFromISR() sets this value to pdTRUE then\r
1185  * a context switch should be requested before the interrupt is exited.\r
1186  *\r
1187  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1188  * errQUEUE_FULL.\r
1189  *\r
1190  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1191  * per call):\r
1192  * <pre>\r
1193  * void vBufferISR( void )\r
1194  * {\r
1195  * char cIn;\r
1196  * BaseType_t xHigherPriorityTaskWoken;\r
1197  *\r
1198  *  // We have not woken a task at the start of the ISR.\r
1199  *  xHigherPriorityTaskWoken = pdFALSE;\r
1200  *\r
1201  *  // Loop until the buffer is empty.\r
1202  *  do\r
1203  *  {\r
1204  *      // Obtain a byte from the buffer.\r
1205  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );\r
1206  *\r
1207  *      // Post the byte.\r
1208  *      xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
1209  *\r
1210  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1211  *\r
1212  *  // Now the buffer is empty we can switch context if necessary.\r
1213  *  if( xHigherPriorityTaskWoken )\r
1214  *  {\r
1215  *      // Actual macro used here is port specific.\r
1216  *      portYIELD_FROM_ISR ();\r
1217  *  }\r
1218  * }\r
1219  * </pre>\r
1220  *\r
1221  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1222  * \ingroup QueueManagement\r
1223  */\r
1224     #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken )          xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )\r
1225 \r
1226 /**\r
1227  * queue. h\r
1228  * <pre>\r
1229  * BaseType_t xQueueGenericSendFromISR(\r
1230  *                                         QueueHandle_t                xQueue,\r
1231  *                                         const        void    *pvItemToQueue,\r
1232  *                                         BaseType_t   *pxHigherPriorityTaskWoken,\r
1233  *                                         BaseType_t   xCopyPosition\r
1234  *                                     );\r
1235  * </pre>\r
1236  *\r
1237  * It is preferred that the macros xQueueSendFromISR(),\r
1238  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place\r
1239  * of calling this function directly.  xQueueGiveFromISR() is an\r
1240  * equivalent for use by semaphores that don't actually copy any data.\r
1241  *\r
1242  * Post an item on a queue.  It is safe to use this function from within an\r
1243  * interrupt service routine.\r
1244  *\r
1245  * Items are queued by copy not reference so it is preferable to only\r
1246  * queue small items, especially when called from an ISR.  In most cases\r
1247  * it would be preferable to store a pointer to the item being queued.\r
1248  *\r
1249  * @param xQueue The handle to the queue on which the item is to be posted.\r
1250  *\r
1251  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1252  * queue.  The size of the items the queue will hold was defined when the\r
1253  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1254  * into the queue storage area.\r
1255  *\r
1256  * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set\r
1257  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1258  * to unblock, and the unblocked task has a priority higher than the currently\r
1259  * running task.  If xQueueGenericSendFromISR() sets this value to pdTRUE then\r
1260  * a context switch should be requested before the interrupt is exited.\r
1261  *\r
1262  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
1263  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
1264  * at the front of the queue (for high priority messages).\r
1265  *\r
1266  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1267  * errQUEUE_FULL.\r
1268  *\r
1269  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1270  * per call):\r
1271  * <pre>\r
1272  * void vBufferISR( void )\r
1273  * {\r
1274  * char cIn;\r
1275  * BaseType_t xHigherPriorityTaskWokenByPost;\r
1276  *\r
1277  *  // We have not woken a task at the start of the ISR.\r
1278  *  xHigherPriorityTaskWokenByPost = pdFALSE;\r
1279  *\r
1280  *  // Loop until the buffer is empty.\r
1281  *  do\r
1282  *  {\r
1283  *      // Obtain a byte from the buffer.\r
1284  *      cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );\r
1285  *\r
1286  *      // Post each byte.\r
1287  *      xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );\r
1288  *\r
1289  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1290  *\r
1291  *  // Now the buffer is empty we can switch context if necessary.  Note that the\r
1292  *  // name of the yield function required is port specific.\r
1293  *  if( xHigherPriorityTaskWokenByPost )\r
1294  *  {\r
1295  *      portYIELD_FROM_ISR();\r
1296  *  }\r
1297  * }\r
1298  * </pre>\r
1299  *\r
1300  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1301  * \ingroup QueueManagement\r
1302  */\r
1303     BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue,\r
1304                                          const void * const pvItemToQueue,\r
1305                                          BaseType_t * const pxHigherPriorityTaskWoken,\r
1306                                          const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;\r
1307     BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue,\r
1308                                   BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;\r
1309 \r
1310 /**\r
1311  * queue. h\r
1312  * <pre>\r
1313  * BaseType_t xQueueReceiveFromISR(\r
1314  *                                     QueueHandle_t    xQueue,\r
1315  *                                     void     *pvBuffer,\r
1316  *                                     BaseType_t *pxTaskWoken\r
1317  *                                 );\r
1318  * </pre>\r
1319  *\r
1320  * Receive an item from a queue.  It is safe to use this function from within an\r
1321  * interrupt service routine.\r
1322  *\r
1323  * @param xQueue The handle to the queue from which the item is to be\r
1324  * received.\r
1325  *\r
1326  * @param pvBuffer Pointer to the buffer into which the received item will\r
1327  * be copied.\r
1328  *\r
1329  * @param pxTaskWoken A task may be blocked waiting for space to become\r
1330  * available on the queue.  If xQueueReceiveFromISR causes such a task to\r
1331  * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will\r
1332  * remain unchanged.\r
1333  *\r
1334  * @return pdTRUE if an item was successfully received from the queue,\r
1335  * otherwise pdFALSE.\r
1336  *\r
1337  * Example usage:\r
1338  * <pre>\r
1339  *\r
1340  * QueueHandle_t xQueue;\r
1341  *\r
1342  * // Function to create a queue and post some values.\r
1343  * void vAFunction( void *pvParameters )\r
1344  * {\r
1345  * char cValueToPost;\r
1346  * const TickType_t xTicksToWait = ( TickType_t )0xff;\r
1347  *\r
1348  *  // Create a queue capable of containing 10 characters.\r
1349  *  xQueue = xQueueCreate( 10, sizeof( char ) );\r
1350  *  if( xQueue == 0 )\r
1351  *  {\r
1352  *      // Failed to create the queue.\r
1353  *  }\r
1354  *\r
1355  *  // ...\r
1356  *\r
1357  *  // Post some characters that will be used within an ISR.  If the queue\r
1358  *  // is full then this task will block for xTicksToWait ticks.\r
1359  *  cValueToPost = 'a';\r
1360  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );\r
1361  *  cValueToPost = 'b';\r
1362  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );\r
1363  *\r
1364  *  // ... keep posting characters ... this task may block when the queue\r
1365  *  // becomes full.\r
1366  *\r
1367  *  cValueToPost = 'c';\r
1368  *  xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );\r
1369  * }\r
1370  *\r
1371  * // ISR that outputs all the characters received on the queue.\r
1372  * void vISR_Routine( void )\r
1373  * {\r
1374  * BaseType_t xTaskWokenByReceive = pdFALSE;\r
1375  * char cRxedChar;\r
1376  *\r
1377  *  while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )\r
1378  *  {\r
1379  *      // A character was received.  Output the character now.\r
1380  *      vOutputCharacter( cRxedChar );\r
1381  *\r
1382  *      // If removing the character from the queue woke the task that was\r
1383  *      // posting onto the queue cTaskWokenByReceive will have been set to\r
1384  *      // pdTRUE.  No matter how many times this loop iterates only one\r
1385  *      // task will be woken.\r
1386  *  }\r
1387  *\r
1388  *  if( cTaskWokenByPost != ( char ) pdFALSE;\r
1389  *  {\r
1390  *      taskYIELD ();\r
1391  *  }\r
1392  * }\r
1393  * </pre>\r
1394  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR\r
1395  * \ingroup QueueManagement\r
1396  */\r
1397     BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,\r
1398                                      void * const pvBuffer,\r
1399                                      BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;\r
1400 \r
1401 /*\r
1402  * Utilities to query queues that are safe to use from an ISR.  These utilities\r
1403  * should be used only from witin an ISR, or within a critical section.\r
1404  */\r
1405     BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1406     BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1407     UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1408 \r
1409 /*\r
1410  * The functions defined above are for passing data to and from tasks.  The\r
1411  * functions below are the equivalents for passing data to and from\r
1412  * co-routines.\r
1413  *\r
1414  * These functions are called from the co-routine macro implementation and\r
1415  * should not be called directly from application code.  Instead use the macro\r
1416  * wrappers defined within croutine.h.\r
1417  */\r
1418     BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue,\r
1419                                     const void * pvItemToQueue,\r
1420                                     BaseType_t xCoRoutinePreviouslyWoken );\r
1421     BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue,\r
1422                                        void * pvBuffer,\r
1423                                        BaseType_t * pxTaskWoken );\r
1424     BaseType_t xQueueCRSend( QueueHandle_t xQueue,\r
1425                              const void * pvItemToQueue,\r
1426                              TickType_t xTicksToWait );\r
1427     BaseType_t xQueueCRReceive( QueueHandle_t xQueue,\r
1428                                 void * pvBuffer,\r
1429                                 TickType_t xTicksToWait );\r
1430 \r
1431 /*\r
1432  * For internal use only.  Use xSemaphoreCreateMutex(),\r
1433  * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling\r
1434  * these functions directly.\r
1435  */\r
1436     QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;\r
1437     QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType,\r
1438                                            StaticQueue_t * pxStaticQueue ) PRIVILEGED_FUNCTION;\r
1439     QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount,\r
1440                                                  const UBaseType_t uxInitialCount ) PRIVILEGED_FUNCTION;\r
1441     QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount,\r
1442                                                        const UBaseType_t uxInitialCount,\r
1443                                                        StaticQueue_t * pxStaticQueue ) PRIVILEGED_FUNCTION;\r
1444     BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue,\r
1445                                     TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
1446     TaskHandle_t xQueueGetMutexHolder( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;\r
1447     TaskHandle_t xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;\r
1448 \r
1449 /*\r
1450  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or\r
1451  * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.\r
1452  */\r
1453     BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex,\r
1454                                          TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
1455     BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;\r
1456 \r
1457 /*\r
1458  * Reset a queue back to its original empty state.  The return value is now\r
1459  * obsolete and is always set to pdPASS.\r
1460  */\r
1461     #define xQueueReset( xQueue )    xQueueGenericReset( xQueue, pdFALSE )\r
1462 \r
1463 /*\r
1464  * The registry is provided as a means for kernel aware debuggers to\r
1465  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
1466  * a queue, semaphore or mutex handle to the registry if you want the handle\r
1467  * to be available to a kernel aware debugger.  If you are not using a kernel\r
1468  * aware debugger then this function can be ignored.\r
1469  *\r
1470  * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the\r
1471  * registry can hold.  configQUEUE_REGISTRY_SIZE must be greater than 0\r
1472  * within FreeRTOSConfig.h for the registry to be available.  Its value\r
1473  * does not effect the number of queues, semaphores and mutexes that can be\r
1474  * created - just the number that the registry can hold.\r
1475  *\r
1476  * @param xQueue The handle of the queue being added to the registry.  This\r
1477  * is the handle returned by a call to xQueueCreate().  Semaphore and mutex\r
1478  * handles can also be passed in here.\r
1479  *\r
1480  * @param pcName The name to be associated with the handle.  This is the\r
1481  * name that the kernel aware debugger will display.  The queue registry only\r
1482  * stores a pointer to the string - so the string must be persistent (global or\r
1483  * preferably in ROM/Flash), not on the stack.\r
1484  */\r
1485     #if ( configQUEUE_REGISTRY_SIZE > 0 )\r
1486         void vQueueAddToRegistry( QueueHandle_t xQueue,\r
1487                                   const char * pcQueueName ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
1488     #endif\r
1489 \r
1490 /*\r
1491  * The registry is provided as a means for kernel aware debuggers to\r
1492  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
1493  * a queue, semaphore or mutex handle to the registry if you want the handle\r
1494  * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to\r
1495  * remove the queue, semaphore or mutex from the register.  If you are not using\r
1496  * a kernel aware debugger then this function can be ignored.\r
1497  *\r
1498  * @param xQueue The handle of the queue being removed from the registry.\r
1499  */\r
1500     #if ( configQUEUE_REGISTRY_SIZE > 0 )\r
1501         void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1502     #endif\r
1503 \r
1504 /*\r
1505  * The queue registry is provided as a means for kernel aware debuggers to\r
1506  * locate queues, semaphores and mutexes.  Call pcQueueGetName() to look\r
1507  * up and return the name of a queue in the queue registry from the queue's\r
1508  * handle.\r
1509  *\r
1510  * @param xQueue The handle of the queue the name of which will be returned.\r
1511  * @return If the queue is in the registry then a pointer to the name of the\r
1512  * queue is returned.  If the queue is not in the registry then NULL is\r
1513  * returned.\r
1514  */\r
1515     #if ( configQUEUE_REGISTRY_SIZE > 0 )\r
1516         const char * pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */\r
1517     #endif\r
1518 \r
1519 /*\r
1520  * Generic version of the function used to creaet a queue using dynamic memory\r
1521  * allocation.  This is called by other functions and macros that create other\r
1522  * RTOS objects that use the queue structure as their base.\r
1523  */\r
1524     #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )\r
1525         QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength,\r
1526                                            const UBaseType_t uxItemSize,\r
1527                                            const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;\r
1528     #endif\r
1529 \r
1530 /*\r
1531  * Generic version of the function used to creaet a queue using dynamic memory\r
1532  * allocation.  This is called by other functions and macros that create other\r
1533  * RTOS objects that use the queue structure as their base.\r
1534  */\r
1535     #if ( configSUPPORT_STATIC_ALLOCATION == 1 )\r
1536         QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength,\r
1537                                                  const UBaseType_t uxItemSize,\r
1538                                                  uint8_t * pucQueueStorage,\r
1539                                                  StaticQueue_t * pxStaticQueue,\r
1540                                                  const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;\r
1541     #endif\r
1542 \r
1543 /*\r
1544  * Queue sets provide a mechanism to allow a task to block (pend) on a read\r
1545  * operation from multiple queues or semaphores simultaneously.\r
1546  *\r
1547  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this\r
1548  * function.\r
1549  *\r
1550  * A queue set must be explicitly created using a call to xQueueCreateSet()\r
1551  * before it can be used.  Once created, standard FreeRTOS queues and semaphores\r
1552  * can be added to the set using calls to xQueueAddToSet().\r
1553  * xQueueSelectFromSet() is then used to determine which, if any, of the queues\r
1554  * or semaphores contained in the set is in a state where a queue read or\r
1555  * semaphore take operation would be successful.\r
1556  *\r
1557  * Note 1:  See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html\r
1558  * for reasons why queue sets are very rarely needed in practice as there are\r
1559  * simpler methods of blocking on multiple objects.\r
1560  *\r
1561  * Note 2:  Blocking on a queue set that contains a mutex will not cause the\r
1562  * mutex holder to inherit the priority of the blocked task.\r
1563  *\r
1564  * Note 3:  An additional 4 bytes of RAM is required for each space in a every\r
1565  * queue added to a queue set.  Therefore counting semaphores that have a high\r
1566  * maximum count value should not be added to a queue set.\r
1567  *\r
1568  * Note 4:  A receive (in the case of a queue) or take (in the case of a\r
1569  * semaphore) operation must not be performed on a member of a queue set unless\r
1570  * a call to xQueueSelectFromSet() has first returned a handle to that set member.\r
1571  *\r
1572  * @param uxEventQueueLength Queue sets store events that occur on\r
1573  * the queues and semaphores contained in the set.  uxEventQueueLength specifies\r
1574  * the maximum number of events that can be queued at once.  To be absolutely\r
1575  * certain that events are not lost uxEventQueueLength should be set to the\r
1576  * total sum of the length of the queues added to the set, where binary\r
1577  * semaphores and mutexes have a length of 1, and counting semaphores have a\r
1578  * length set by their maximum count value.  Examples:\r
1579  *  + If a queue set is to hold a queue of length 5, another queue of length 12,\r
1580  *    and a binary semaphore, then uxEventQueueLength should be set to\r
1581  *    (5 + 12 + 1), or 18.\r
1582  *  + If a queue set is to hold three binary semaphores then uxEventQueueLength\r
1583  *    should be set to (1 + 1 + 1 ), or 3.\r
1584  *  + If a queue set is to hold a counting semaphore that has a maximum count of\r
1585  *    5, and a counting semaphore that has a maximum count of 3, then\r
1586  *    uxEventQueueLength should be set to (5 + 3), or 8.\r
1587  *\r
1588  * @return If the queue set is created successfully then a handle to the created\r
1589  * queue set is returned.  Otherwise NULL is returned.\r
1590  */\r
1591     QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION;\r
1592 \r
1593 /*\r
1594  * Adds a queue or semaphore to a queue set that was previously created by a\r
1595  * call to xQueueCreateSet().\r
1596  *\r
1597  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this\r
1598  * function.\r
1599  *\r
1600  * Note 1:  A receive (in the case of a queue) or take (in the case of a\r
1601  * semaphore) operation must not be performed on a member of a queue set unless\r
1602  * a call to xQueueSelectFromSet() has first returned a handle to that set member.\r
1603  *\r
1604  * @param xQueueOrSemaphore The handle of the queue or semaphore being added to\r
1605  * the queue set (cast to an QueueSetMemberHandle_t type).\r
1606  *\r
1607  * @param xQueueSet The handle of the queue set to which the queue or semaphore\r
1608  * is being added.\r
1609  *\r
1610  * @return If the queue or semaphore was successfully added to the queue set\r
1611  * then pdPASS is returned.  If the queue could not be successfully added to the\r
1612  * queue set because it is already a member of a different queue set then pdFAIL\r
1613  * is returned.\r
1614  */\r
1615     BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore,\r
1616                                QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;\r
1617 \r
1618 /*\r
1619  * Removes a queue or semaphore from a queue set.  A queue or semaphore can only\r
1620  * be removed from a set if the queue or semaphore is empty.\r
1621  *\r
1622  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this\r
1623  * function.\r
1624  *\r
1625  * @param xQueueOrSemaphore The handle of the queue or semaphore being removed\r
1626  * from the queue set (cast to an QueueSetMemberHandle_t type).\r
1627  *\r
1628  * @param xQueueSet The handle of the queue set in which the queue or semaphore\r
1629  * is included.\r
1630  *\r
1631  * @return If the queue or semaphore was successfully removed from the queue set\r
1632  * then pdPASS is returned.  If the queue was not in the queue set, or the\r
1633  * queue (or semaphore) was not empty, then pdFAIL is returned.\r
1634  */\r
1635     BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore,\r
1636                                     QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;\r
1637 \r
1638 /*\r
1639  * xQueueSelectFromSet() selects from the members of a queue set a queue or\r
1640  * semaphore that either contains data (in the case of a queue) or is available\r
1641  * to take (in the case of a semaphore).  xQueueSelectFromSet() effectively\r
1642  * allows a task to block (pend) on a read operation on all the queues and\r
1643  * semaphores in a queue set simultaneously.\r
1644  *\r
1645  * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this\r
1646  * function.\r
1647  *\r
1648  * Note 1:  See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html\r
1649  * for reasons why queue sets are very rarely needed in practice as there are\r
1650  * simpler methods of blocking on multiple objects.\r
1651  *\r
1652  * Note 2:  Blocking on a queue set that contains a mutex will not cause the\r
1653  * mutex holder to inherit the priority of the blocked task.\r
1654  *\r
1655  * Note 3:  A receive (in the case of a queue) or take (in the case of a\r
1656  * semaphore) operation must not be performed on a member of a queue set unless\r
1657  * a call to xQueueSelectFromSet() has first returned a handle to that set member.\r
1658  *\r
1659  * @param xQueueSet The queue set on which the task will (potentially) block.\r
1660  *\r
1661  * @param xTicksToWait The maximum time, in ticks, that the calling task will\r
1662  * remain in the Blocked state (with other tasks executing) to wait for a member\r
1663  * of the queue set to be ready for a successful queue read or semaphore take\r
1664  * operation.\r
1665  *\r
1666  * @return xQueueSelectFromSet() will return the handle of a queue (cast to\r
1667  * a QueueSetMemberHandle_t type) contained in the queue set that contains data,\r
1668  * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained\r
1669  * in the queue set that is available, or NULL if no such queue or semaphore\r
1670  * exists before before the specified block time expires.\r
1671  */\r
1672     QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet,\r
1673                                                 const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;\r
1674 \r
1675 /*\r
1676  * A version of xQueueSelectFromSet() that can be used from an ISR.\r
1677  */\r
1678     QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;\r
1679 \r
1680 /* Not public API functions. */\r
1681     void vQueueWaitForMessageRestricted( QueueHandle_t xQueue,\r
1682                                          TickType_t xTicksToWait,\r
1683                                          const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;\r
1684     BaseType_t xQueueGenericReset( QueueHandle_t xQueue,\r
1685                                    BaseType_t xNewQueue ) PRIVILEGED_FUNCTION;\r
1686     void vQueueSetQueueNumber( QueueHandle_t xQueue,\r
1687                                UBaseType_t uxQueueNumber ) PRIVILEGED_FUNCTION;\r
1688     UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1689     uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;\r
1690 \r
1691 \r
1692     #ifdef __cplusplus\r
1693         }\r
1694     #endif\r
1695 \r
1696 #endif /* QUEUE_H */\r