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