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

   1 /*\r
   2         FreeRTOS.org V5.1.0 - Copyright (C) 2003-2008 Richard Barry.\r
   3 \r
   4         This file is part of the FreeRTOS.org distribution.\r
   5 \r
   6         FreeRTOS.org is free software; you can redistribute it and/or modify\r
   7         it under the terms of the GNU General Public License as published by\r
   8         the Free Software Foundation; either version 2 of the License, or\r
   9         (at your option) any later version.\r
  10 \r
  11         FreeRTOS.org is distributed in the hope that it will be useful,\r
  12         but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  13         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  14         GNU General Public License for more details.\r
  15 \r
  16         You should have received a copy of the GNU General Public License\r
  17         along with FreeRTOS.org; if not, write to the Free Software\r
  18         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\r
  19 \r
  20         A special exception to the GPL can be applied should you wish to distribute\r
  21         a combined work that includes FreeRTOS.org, without being obliged to provide\r
  22         the source code for any proprietary components.  See the licensing section\r
  23         of http://www.FreeRTOS.org for full details of how and when the exception\r
  24         can be applied.\r
  25 \r
  26     ***************************************************************************\r
  27     ***************************************************************************\r
  28     *                                                                         *\r
  29     * SAVE TIME AND MONEY!  We can port FreeRTOS.org to your own hardware,    *\r
  30     * and even write all or part of your application on your behalf.          *\r
  31     * See http://www.OpenRTOS.com for details of the services we provide to   *\r
  32     * expedite your project.                                                  *\r
  33     *                                                                         *\r
  34     ***************************************************************************\r
  35     ***************************************************************************\r
  36 \r
  37         Please ensure to read the configuration and relevant port sections of the\r
  38         online documentation.\r
  39 \r
  40         http://www.FreeRTOS.org - Documentation, latest information, license and \r
  41         contact details.\r
  42 \r
  43         http://www.SafeRTOS.com - A version that is certified for use in safety \r
  44         critical systems.\r
  45 \r
  46         http://www.OpenRTOS.com - Commercial support, development, porting, \r
  47         licensing and training services.\r
  48 */\r
  49 \r
  50 #ifndef INC_FREERTOS_H\r
  51         #error "#include FreeRTOS.h" must appear in source files before "#include queue.h"\r
  52 #endif\r
  53 \r
  54 \r
  55 \r
  56 \r
  57 #ifndef QUEUE_H\r
  58 #define QUEUE_H\r
  59 \r
  60 #ifdef __cplusplus\r
  61 extern "C" {\r
  62 #endif\r
  63 typedef void * xQueueHandle;\r
  64 \r
  65 /* For internal use only. */\r
  66 #define queueSEND_TO_BACK       ( 0 )\r
  67 #define queueSEND_TO_FRONT      ( 1 )\r
  68 \r
  69 \r
  70 /**\r
  71  * queue. h\r
  72  * <pre>\r
  73  xQueueHandle xQueueCreate(\r
  74                               unsigned portBASE_TYPE uxQueueLength,\r
  75                               unsigned portBASE_TYPE uxItemSize\r
  76                           );\r
  77  * </pre>\r
  78  *\r
  79  * Creates a new queue instance.  This allocates the storage required by the\r
  80  * new queue and returns a handle for the queue.\r
  81  *\r
  82  * @param uxQueueLength The maximum number of items that the queue can contain.\r
  83  *\r
  84  * @param uxItemSize The number of bytes each item in the queue will require.\r
  85  * Items are queued by copy, not by reference, so this is the number of bytes\r
  86  * that will be copied for each posted item.  Each item on the queue must be\r
  87  * the same size.\r
  88  *\r
  89  * @return If the queue is successfully create then a handle to the newly\r
  90  * created queue is returned.  If the queue cannot be created then 0 is\r
  91  * returned.\r
  92  *\r
  93  * Example usage:\r
  94    <pre>\r
  95  struct AMessage\r
  96  {\r
  97     portCHAR ucMessageID;\r
  98     portCHAR ucData[ 20 ];\r
  99  };\r
 100 \r
 101  void vATask( void *pvParameters )\r
 102  {\r
 103  xQueueHandle xQueue1, xQueue2;\r
 104 \r
 105     // Create a queue capable of containing 10 unsigned long values.\r
 106     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 107     if( xQueue1 == 0 )\r
 108     {\r
 109         // Queue was not created and must not be used.\r
 110     }\r
 111 \r
 112     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 113     // These should be passed by pointer as they contain a lot of data.\r
 114     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 115     if( xQueue2 == 0 )\r
 116     {\r
 117         // Queue was not created and must not be used.\r
 118     }\r
 119 \r
 120     // ... Rest of task code.\r
 121  }\r
 122  </pre>\r
 123  * \defgroup xQueueCreate xQueueCreate\r
 124  * \ingroup QueueManagement\r
 125  */\r
 126 xQueueHandle xQueueCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize );\r
 127 \r
 128 /**\r
 129  * queue. h\r
 130  * <pre>\r
 131  portBASE_TYPE xQueueSendToToFront(\r
 132                                    xQueueHandle xQueue,\r
 133                                    const void * pvItemToQueue,\r
 134                                    portTickType xTicksToWait\r
 135                                );\r
 136  * </pre>\r
 137  *\r
 138  * This is a macro that calls xQueueGenericSend().\r
 139  *\r
 140  * Post an item to the front of a queue.  The item is queued by copy, not by\r
 141  * reference.  This function must not be called from an interrupt service\r
 142  * routine.  See xQueueSendFromISR () for an alternative which may be used\r
 143  * in an ISR.\r
 144  *\r
 145  * @param xQueue The handle to the queue on which the item is to be posted.\r
 146  *\r
 147  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 148  * queue.  The size of the items the queue will hold was defined when the\r
 149  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 150  * into the queue storage area.\r
 151  *\r
 152  * @param xTicksToWait The maximum amount of time the task should block\r
 153  * waiting for space to become available on the queue, should it already\r
 154  * be full.  The call will return immediately if this is set to 0 and the\r
 155  * queue is full.  The time is defined in tick periods so the constant \r
 156  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 157  *\r
 158  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 159  *\r
 160  * Example usage:\r
 161    <pre>\r
 162  struct AMessage\r
 163  {\r
 164     portCHAR ucMessageID;\r
 165     portCHAR ucData[ 20 ];\r
 166  } xMessage;\r
 167 \r
 168  unsigned portLONG ulVar = 10UL;\r
 169 \r
 170  void vATask( void *pvParameters )\r
 171  {\r
 172  xQueueHandle xQueue1, xQueue2;\r
 173  struct AMessage *pxMessage;\r
 174 \r
 175     // Create a queue capable of containing 10 unsigned long values.\r
 176     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 177 \r
 178     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 179     // These should be passed by pointer as they contain a lot of data.\r
 180     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 181 \r
 182     // ...\r
 183 \r
 184     if( xQueue1 != 0 )\r
 185     {\r
 186         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 187         // available if necessary.\r
 188         if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 189         {\r
 190             // Failed to post the message, even after 10 ticks.\r
 191         }\r
 192     }\r
 193 \r
 194     if( xQueue2 != 0 )\r
 195     {\r
 196         // Send a pointer to a struct AMessage object.  Don't block if the\r
 197         // queue is already full.\r
 198         pxMessage = & xMessage;\r
 199         xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 200     }\r
 201 \r
 202         // ... Rest of task code.\r
 203  }\r
 204  </pre>\r
 205  * \defgroup xQueueSend xQueueSend\r
 206  * \ingroup QueueManagement\r
 207  */\r
 208 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
 209 \r
 210 /**\r
 211  * queue. h\r
 212  * <pre>\r
 213  portBASE_TYPE xQueueSendToBack(\r
 214                                    xQueueHandle xQueue,\r
 215                                    const void * pvItemToQueue,\r
 216                                    portTickType xTicksToWait\r
 217                                );\r
 218  * </pre>\r
 219  *\r
 220  * This is a macro that calls xQueueGenericSend().\r
 221  *\r
 222  * Post an item to the back of a queue.  The item is queued by copy, not by\r
 223  * reference.  This function must not be called from an interrupt service\r
 224  * routine.  See xQueueSendFromISR () for an alternative which may be used\r
 225  * in an ISR.\r
 226  *\r
 227  * @param xQueue The handle to the queue on which the item is to be posted.\r
 228  *\r
 229  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 230  * queue.  The size of the items the queue will hold was defined when the\r
 231  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 232  * into the queue storage area.\r
 233  *\r
 234  * @param xTicksToWait The maximum amount of time the task should block\r
 235  * waiting for space to become available on the queue, should it already\r
 236  * be full.  The call will return immediately if this is set to 0 and the queue\r
 237  * is full.  The  time is defined in tick periods so the constant \r
 238  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 239  *\r
 240  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 241  *\r
 242  * Example usage:\r
 243    <pre>\r
 244  struct AMessage\r
 245  {\r
 246     portCHAR ucMessageID;\r
 247     portCHAR ucData[ 20 ];\r
 248  } xMessage;\r
 249 \r
 250  unsigned portLONG ulVar = 10UL;\r
 251 \r
 252  void vATask( void *pvParameters )\r
 253  {\r
 254  xQueueHandle xQueue1, xQueue2;\r
 255  struct AMessage *pxMessage;\r
 256 \r
 257     // Create a queue capable of containing 10 unsigned long values.\r
 258     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 259 \r
 260     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 261     // These should be passed by pointer as they contain a lot of data.\r
 262     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 263 \r
 264     // ...\r
 265 \r
 266     if( xQueue1 != 0 )\r
 267     {\r
 268         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 269         // available if necessary.\r
 270         if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 271         {\r
 272             // Failed to post the message, even after 10 ticks.\r
 273         }\r
 274     }\r
 275 \r
 276     if( xQueue2 != 0 )\r
 277     {\r
 278         // Send a pointer to a struct AMessage object.  Don't block if the\r
 279         // queue is already full.\r
 280         pxMessage = & xMessage;\r
 281         xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 282     }\r
 283 \r
 284         // ... Rest of task code.\r
 285  }\r
 286  </pre>\r
 287  * \defgroup xQueueSend xQueueSend\r
 288  * \ingroup QueueManagement\r
 289  */\r
 290 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
 291 \r
 292 /**\r
 293  * queue. h\r
 294  * <pre>\r
 295  portBASE_TYPE xQueueSend(\r
 296                               xQueueHandle xQueue,\r
 297                               const void * pvItemToQueue,\r
 298                               portTickType xTicksToWait\r
 299                          );\r
 300  * </pre>\r
 301  *\r
 302  * This is a macro that calls xQueueGenericSend().  It is included for\r
 303  * backward compatibility with versions of FreeRTOS.org that did not\r
 304  * include the xQueueSendToFront() and xQueueSendToBack() macros.  It is\r
 305  * equivalent to xQueueSendToBack().\r
 306  *\r
 307  * Post an item on a queue.  The item is queued by copy, not by reference.\r
 308  * This function must not be called from an interrupt service routine.\r
 309  * See xQueueSendFromISR () for an alternative which may be used in an ISR.\r
 310  *\r
 311  * @param xQueue The handle to the queue on which the item is to be posted.\r
 312  *\r
 313  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 314  * queue.  The size of the items the queue will hold was defined when the\r
 315  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 316  * into the queue storage area.\r
 317  *\r
 318  * @param xTicksToWait The maximum amount of time the task should block\r
 319  * waiting for space to become available on the queue, should it already\r
 320  * be full.  The call will return immediately if this is set to 0 and the\r
 321  * queue is full.  The time is defined in tick periods so the constant \r
 322  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 323  *\r
 324  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 325  *\r
 326  * Example usage:\r
 327    <pre>\r
 328  struct AMessage\r
 329  {\r
 330     portCHAR ucMessageID;\r
 331     portCHAR ucData[ 20 ];\r
 332  } xMessage;\r
 333 \r
 334  unsigned portLONG ulVar = 10UL;\r
 335 \r
 336  void vATask( void *pvParameters )\r
 337  {\r
 338  xQueueHandle xQueue1, xQueue2;\r
 339  struct AMessage *pxMessage;\r
 340 \r
 341     // Create a queue capable of containing 10 unsigned long values.\r
 342     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 343 \r
 344     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 345     // These should be passed by pointer as they contain a lot of data.\r
 346     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 347 \r
 348     // ...\r
 349 \r
 350     if( xQueue1 != 0 )\r
 351     {\r
 352         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 353         // available if necessary.\r
 354         if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 355         {\r
 356             // Failed to post the message, even after 10 ticks.\r
 357         }\r
 358     }\r
 359 \r
 360     if( xQueue2 != 0 )\r
 361     {\r
 362         // Send a pointer to a struct AMessage object.  Don't block if the\r
 363         // queue is already full.\r
 364         pxMessage = & xMessage;\r
 365         xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 366     }\r
 367 \r
 368         // ... Rest of task code.\r
 369  }\r
 370  </pre>\r
 371  * \defgroup xQueueSend xQueueSend\r
 372  * \ingroup QueueManagement\r
 373  */\r
 374 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
 375 \r
 376 \r
 377 /**\r
 378  * queue. h\r
 379  * <pre>\r
 380  portBASE_TYPE xQueueGenericSend(\r
 381                                                                         xQueueHandle xQueue,\r
 382                                                                         const void * pvItemToQueue,\r
 383                                                                         portTickType xTicksToWait\r
 384                                                                         portBASE_TYPE xCopyPosition\r
 385                                                                 );\r
 386  * </pre>\r
 387  *\r
 388  * It is preferred that the macros xQueueSend(), xQueueSendToFront() and\r
 389  * xQueueSendToBack() are used in place of calling this function directly.\r
 390  *\r
 391  * Post an item on a queue.  The item is queued by copy, not by reference.\r
 392  * This function must not be called from an interrupt service routine.\r
 393  * See xQueueSendFromISR () for an alternative which may be used in an ISR.\r
 394  *\r
 395  * @param xQueue The handle to the queue on which the item is to be posted.\r
 396  *\r
 397  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 398  * queue.  The size of the items the queue will hold was defined when the\r
 399  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 400  * into the queue storage area.\r
 401  *\r
 402  * @param xTicksToWait The maximum amount of time the task should block\r
 403  * waiting for space to become available on the queue, should it already\r
 404  * be full.  The call will return immediately if this is set to 0 and the\r
 405  * queue is full.  The time is defined in tick periods so the constant \r
 406  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 407  *\r
 408  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
 409  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
 410  * at the front of the queue (for high priority messages).\r
 411  *\r
 412  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 413  *\r
 414  * Example usage:\r
 415    <pre>\r
 416  struct AMessage\r
 417  {\r
 418     portCHAR ucMessageID;\r
 419     portCHAR ucData[ 20 ];\r
 420  } xMessage;\r
 421 \r
 422  unsigned portLONG ulVar = 10UL;\r
 423 \r
 424  void vATask( void *pvParameters )\r
 425  {\r
 426  xQueueHandle xQueue1, xQueue2;\r
 427  struct AMessage *pxMessage;\r
 428 \r
 429     // Create a queue capable of containing 10 unsigned long values.\r
 430     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 431 \r
 432     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 433     // These should be passed by pointer as they contain a lot of data.\r
 434     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 435 \r
 436     // ...\r
 437 \r
 438     if( xQueue1 != 0 )\r
 439     {\r
 440         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 441         // available if necessary.\r
 442         if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10, queueSEND_TO_BACK ) != pdPASS )\r
 443         {\r
 444             // Failed to post the message, even after 10 ticks.\r
 445         }\r
 446     }\r
 447 \r
 448     if( xQueue2 != 0 )\r
 449     {\r
 450         // Send a pointer to a struct AMessage object.  Don't block if the\r
 451         // queue is already full.\r
 452         pxMessage = & xMessage;\r
 453         xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0, queueSEND_TO_BACK );\r
 454     }\r
 455 \r
 456         // ... Rest of task code.\r
 457  }\r
 458  </pre>\r
 459  * \defgroup xQueueSend xQueueSend\r
 460  * \ingroup QueueManagement\r
 461  */\r
 462 signed portBASE_TYPE xQueueGenericSend( xQueueHandle xQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
 463 \r
 464 /**\r
 465  * queue. h\r
 466  * <pre>\r
 467  portBASE_TYPE xQueuePeek(\r
 468                              xQueueHandle xQueue,\r
 469                              void *pvBuffer,\r
 470                              portTickType xTicksToWait\r
 471                          );</pre>\r
 472  *\r
 473  * This is a macro that calls the xQueueGenericReceive() function.\r
 474  *\r
 475  * Receive an item from a queue without removing the item from the queue.\r
 476  * The item is received by copy so a buffer of adequate size must be\r
 477  * provided.  The number of bytes copied into the buffer was defined when\r
 478  * the queue was created.\r
 479  *\r
 480  * Successfully received items remain on the queue so will be returned again\r
 481  * by the next call, or a call to xQueueReceive().\r
 482  *\r
 483  * This macro must not be used in an interrupt service routine.\r
 484  *\r
 485  * @param pxQueue The handle to the queue from which the item is to be\r
 486  * received.\r
 487  *\r
 488  * @param pvBuffer Pointer to the buffer into which the received item will\r
 489  * be copied.\r
 490  *\r
 491  * @param xTicksToWait The maximum amount of time the task should block\r
 492  * waiting for an item to receive should the queue be empty at the time\r
 493  * of the call.    The time is defined in tick periods so the constant\r
 494  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 495  * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue\r
 496  * is empty.\r
 497  *\r
 498  * @return pdTRUE if an item was successfully received from the queue,\r
 499  * otherwise pdFALSE.\r
 500  *\r
 501  * Example usage:\r
 502    <pre>\r
 503  struct AMessage\r
 504  {\r
 505     portCHAR ucMessageID;\r
 506     portCHAR ucData[ 20 ];\r
 507  } xMessage;\r
 508 \r
 509  xQueueHandle xQueue;\r
 510 \r
 511  // Task to create a queue and post a value.\r
 512  void vATask( void *pvParameters )\r
 513  {\r
 514  struct AMessage *pxMessage;\r
 515 \r
 516     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 517     // These should be passed by pointer as they contain a lot of data.\r
 518     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 519     if( xQueue == 0 )\r
 520     {\r
 521         // Failed to create the queue.\r
 522     }\r
 523 \r
 524     // ...\r
 525 \r
 526     // Send a pointer to a struct AMessage object.  Don't block if the\r
 527     // queue is already full.\r
 528     pxMessage = & xMessage;\r
 529     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 530 \r
 531         // ... Rest of task code.\r
 532  }\r
 533 \r
 534  // Task to peek the data from the queue.\r
 535  void vADifferentTask( void *pvParameters )\r
 536  {\r
 537  struct AMessage *pxRxedMessage;\r
 538 \r
 539     if( xQueue != 0 )\r
 540     {\r
 541         // Peek a message on the created queue.  Block for 10 ticks if a\r
 542         // message is not immediately available.\r
 543         if( xQueuePeek( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 544         {\r
 545             // pcRxedMessage now points to the struct AMessage variable posted\r
 546             // by vATask, but the item still remains on the queue.\r
 547         }\r
 548     }\r
 549 \r
 550         // ... Rest of task code.\r
 551  }\r
 552  </pre>\r
 553  * \defgroup xQueueReceive xQueueReceive\r
 554  * \ingroup QueueManagement\r
 555  */\r
 556 #define xQueuePeek( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
 557 \r
 558 /**\r
 559  * queue. h\r
 560  * <pre>\r
 561  portBASE_TYPE xQueueReceive(\r
 562                                  xQueueHandle xQueue,\r
 563                                  void *pvBuffer,\r
 564                                  portTickType xTicksToWait\r
 565                             );</pre>\r
 566  *\r
 567  * This is a macro that calls the xQueueGenericReceive() function.\r
 568  *\r
 569  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 570  * adequate size must be provided.  The number of bytes copied into the buffer\r
 571  * was defined when the queue was created.\r
 572  *\r
 573  * Successfully received items are removed from the queue.\r
 574  *\r
 575  * This function must not be used in an interrupt service routine.  See\r
 576  * xQueueReceiveFromISR for an alternative that can.\r
 577  *\r
 578  * @param pxQueue The handle to the queue from which the item is to be\r
 579  * received.\r
 580  *\r
 581  * @param pvBuffer Pointer to the buffer into which the received item will\r
 582  * be copied.\r
 583  *\r
 584  * @param xTicksToWait The maximum amount of time the task should block\r
 585  * waiting for an item to receive should the queue be empty at the time\r
 586  * of the call.    xQueueReceive() will return immediately if xTicksToWait\r
 587  * is zero and the queue is empty.  The time is defined in tick periods so the \r
 588  * constant portTICK_RATE_MS should be used to convert to real time if this is \r
 589  * required.\r
 590  *\r
 591  * @return pdTRUE if an item was successfully received from the queue,\r
 592  * otherwise pdFALSE.\r
 593  *\r
 594  * Example usage:\r
 595    <pre>\r
 596  struct AMessage\r
 597  {\r
 598     portCHAR ucMessageID;\r
 599     portCHAR ucData[ 20 ];\r
 600  } xMessage;\r
 601 \r
 602  xQueueHandle xQueue;\r
 603 \r
 604  // Task to create a queue and post a value.\r
 605  void vATask( void *pvParameters )\r
 606  {\r
 607  struct AMessage *pxMessage;\r
 608 \r
 609     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 610     // These should be passed by pointer as they contain a lot of data.\r
 611     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 612     if( xQueue == 0 )\r
 613     {\r
 614         // Failed to create the queue.\r
 615     }\r
 616 \r
 617     // ...\r
 618 \r
 619     // Send a pointer to a struct AMessage object.  Don't block if the\r
 620     // queue is already full.\r
 621     pxMessage = & xMessage;\r
 622     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 623 \r
 624         // ... Rest of task code.\r
 625  }\r
 626 \r
 627  // Task to receive from the queue.\r
 628  void vADifferentTask( void *pvParameters )\r
 629  {\r
 630  struct AMessage *pxRxedMessage;\r
 631 \r
 632     if( xQueue != 0 )\r
 633     {\r
 634         // Receive a message on the created queue.  Block for 10 ticks if a\r
 635         // message is not immediately available.\r
 636         if( xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 637         {\r
 638             // pcRxedMessage now points to the struct AMessage variable posted\r
 639             // by vATask.\r
 640         }\r
 641     }\r
 642 \r
 643         // ... Rest of task code.\r
 644  }\r
 645  </pre>\r
 646  * \defgroup xQueueReceive xQueueReceive\r
 647  * \ingroup QueueManagement\r
 648  */\r
 649 #define xQueueReceive( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
 650 \r
 651 \r
 652 /**\r
 653  * queue. h\r
 654  * <pre>\r
 655  portBASE_TYPE xQueueGenericReceive(\r
 656                                        xQueueHandle xQueue,\r
 657                                        void *pvBuffer,\r
 658                                        portTickType xTicksToWait\r
 659                                        portBASE_TYPE xJustPeek\r
 660                                     );</pre>\r
 661  *\r
 662  * It is preferred that the macro xQueueReceive() be used rather than calling\r
 663  * this function directly.\r
 664  *\r
 665  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 666  * adequate size must be provided.  The number of bytes copied into the buffer\r
 667  * was defined when the queue was created.\r
 668  *\r
 669  * This function must not be used in an interrupt service routine.  See\r
 670  * xQueueReceiveFromISR for an alternative that can.\r
 671  *\r
 672  * @param pxQueue The handle to the queue from which the item is to be\r
 673  * received.\r
 674  *\r
 675  * @param pvBuffer Pointer to the buffer into which the received item will\r
 676  * be copied.\r
 677  *\r
 678  * @param xTicksToWait The maximum amount of time the task should block\r
 679  * waiting for an item to receive should the queue be empty at the time\r
 680  * of the call.    The time is defined in tick periods so the constant\r
 681  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 682  * xQueueGenericReceive() will return immediately if the queue is empty and\r
 683  * xTicksToWait is 0.\r
 684  *\r
 685  * @param xJustPeek When set to true, the item received from the queue is not\r
 686  * actually removed from the queue - meaning a subsequent call to\r
 687  * xQueueReceive() will return the same item.  When set to false, the item\r
 688  * being received from the queue is also removed from the queue.\r
 689  *\r
 690  * @return pdTRUE if an item was successfully received from the queue,\r
 691  * otherwise pdFALSE.\r
 692  *\r
 693  * Example usage:\r
 694    <pre>\r
 695  struct AMessage\r
 696  {\r
 697     portCHAR ucMessageID;\r
 698     portCHAR ucData[ 20 ];\r
 699  } xMessage;\r
 700 \r
 701  xQueueHandle xQueue;\r
 702 \r
 703  // Task to create a queue and post a value.\r
 704  void vATask( void *pvParameters )\r
 705  {\r
 706  struct AMessage *pxMessage;\r
 707 \r
 708     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 709     // These should be passed by pointer as they contain a lot of data.\r
 710     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 711     if( xQueue == 0 )\r
 712     {\r
 713         // Failed to create the queue.\r
 714     }\r
 715 \r
 716     // ...\r
 717 \r
 718     // Send a pointer to a struct AMessage object.  Don't block if the\r
 719     // queue is already full.\r
 720     pxMessage = & xMessage;\r
 721     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 722 \r
 723         // ... Rest of task code.\r
 724  }\r
 725 \r
 726  // Task to receive from the queue.\r
 727  void vADifferentTask( void *pvParameters )\r
 728  {\r
 729  struct AMessage *pxRxedMessage;\r
 730 \r
 731     if( xQueue != 0 )\r
 732     {\r
 733         // Receive a message on the created queue.  Block for 10 ticks if a\r
 734         // message is not immediately available.\r
 735         if( xQueueGenericReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 736         {\r
 737             // pcRxedMessage now points to the struct AMessage variable posted\r
 738             // by vATask.\r
 739         }\r
 740     }\r
 741 \r
 742         // ... Rest of task code.\r
 743  }\r
 744  </pre>\r
 745  * \defgroup xQueueReceive xQueueReceive\r
 746  * \ingroup QueueManagement\r
 747  */\r
 748 signed portBASE_TYPE xQueueGenericReceive( xQueueHandle xQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeek );\r
 749 \r
 750 /**\r
 751  * queue. h\r
 752  * <pre>unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );</pre>\r
 753  *\r
 754  * Return the number of messages stored in a queue.\r
 755  *\r
 756  * @param xQueue A handle to the queue being queried.\r
 757  *\r
 758  * @return The number of messages available in the queue.\r
 759  *\r
 760  * \page uxQueueMessagesWaiting uxQueueMessagesWaiting\r
 761  * \ingroup QueueManagement\r
 762  */\r
 763 unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );\r
 764 \r
 765 /**\r
 766  * queue. h\r
 767  * <pre>void vQueueDelete( xQueueHandle xQueue );</pre>\r
 768  *\r
 769  * Delete a queue - freeing all the memory allocated for storing of items\r
 770  * placed on the queue.\r
 771  *\r
 772  * @param xQueue A handle to the queue to be deleted.\r
 773  *\r
 774  * \page vQueueDelete vQueueDelete\r
 775  * \ingroup QueueManagement\r
 776  */\r
 777 void vQueueDelete( xQueueHandle xQueue );\r
 778 \r
 779 /**\r
 780  * queue. h\r
 781  * <pre>\r
 782  portBASE_TYPE xQueueSendToFrontFromISR(\r
 783                                          xQueueHandle pxQueue,\r
 784                                          const void *pvItemToQueue,\r
 785                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 786                                       );\r
 787  </pre>\r
 788  *\r
 789  * This is a macro that calls xQueueGenericSendFromISR().\r
 790  *\r
 791  * Post an item to the front of a queue.  It is safe to use this macro from\r
 792  * within an interrupt service routine.\r
 793  *\r
 794  * Items are queued by copy not reference so it is preferable to only\r
 795  * queue small items, especially when called from an ISR.  In most cases\r
 796  * it would be preferable to store a pointer to the item being queued.\r
 797  *\r
 798  * @param xQueue The handle to the queue on which the item is to be posted.\r
 799  *\r
 800  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 801  * queue.  The size of the items the queue will hold was defined when the\r
 802  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 803  * into the queue storage area.\r
 804  *\r
 805  * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set\r
 806  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 807  * to unblock, and the unblocked task has a priority higher than the currently\r
 808  * running task.  If xQueueSendToFromFromISR() sets this value to pdTRUE then\r
 809  * a context switch should be requested before the interrupt is exited.\r
 810  *\r
 811  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 812  * errQUEUE_FULL.\r
 813  *\r
 814  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 815  * per call):\r
 816    <pre>\r
 817  void vBufferISR( void )\r
 818  {\r
 819  portCHAR cIn;\r
 820  portBASE_TYPE xHigherPrioritTaskWoken;\r
 821 \r
 822     // We have not woken a task at the start of the ISR.\r
 823     xHigherPriorityTaskWoken = pdFALSE;\r
 824 \r
 825     // Loop until the buffer is empty.\r
 826     do\r
 827     {\r
 828         // Obtain a byte from the buffer.\r
 829         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 830 \r
 831         // Post the byte.  \r
 832         xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 833 \r
 834     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 835 \r
 836     // Now the buffer is empty we can switch context if necessary.\r
 837     if( xHigherPriorityTaskWoken )\r
 838     {\r
 839         taskYIELD ();\r
 840     }\r
 841  }\r
 842  </pre>\r
 843  *\r
 844  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 845  * \ingroup QueueManagement\r
 846  */\r
 847 #define xQueueSendToFrontFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_FRONT )\r
 848 \r
 849 \r
 850 /**\r
 851  * queue. h\r
 852  * <pre>\r
 853  portBASE_TYPE xQueueSendToBackFromISR(\r
 854                                          xQueueHandle pxQueue,\r
 855                                          const void *pvItemToQueue,\r
 856                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 857                                       );\r
 858  </pre>\r
 859  *\r
 860  * This is a macro that calls xQueueGenericSendFromISR().\r
 861  *\r
 862  * Post an item to the back of a queue.  It is safe to use this macro from\r
 863  * within an interrupt service routine.\r
 864  *\r
 865  * Items are queued by copy not reference so it is preferable to only\r
 866  * queue small items, especially when called from an ISR.  In most cases\r
 867  * it would be preferable to store a pointer to the item being queued.\r
 868  *\r
 869  * @param xQueue The handle to the queue on which the item is to be posted.\r
 870  *\r
 871  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 872  * queue.  The size of the items the queue will hold was defined when the\r
 873  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 874  * into the queue storage area.\r
 875  *\r
 876  * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set\r
 877  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 878  * to unblock, and the unblocked task has a priority higher than the currently\r
 879  * running task.  If xQueueSendToBackFromISR() sets this value to pdTRUE then\r
 880  * a context switch should be requested before the interrupt is exited.\r
 881  *\r
 882  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 883  * errQUEUE_FULL.\r
 884  *\r
 885  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 886  * per call):\r
 887    <pre>\r
 888  void vBufferISR( void )\r
 889  {\r
 890  portCHAR cIn;\r
 891  portBASE_TYPE xHigherPriorityTaskWoken;\r
 892 \r
 893     // We have not woken a task at the start of the ISR.\r
 894     xHigherPriorityTaskWoken = pdFALSE;\r
 895 \r
 896     // Loop until the buffer is empty.\r
 897     do\r
 898     {\r
 899         // Obtain a byte from the buffer.\r
 900         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 901 \r
 902         // Post the byte.\r
 903         xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 904 \r
 905     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 906 \r
 907     // Now the buffer is empty we can switch context if necessary.\r
 908     if( xHigherPriorityTaskWoken )\r
 909     {\r
 910         taskYIELD ();\r
 911     }\r
 912  }\r
 913  </pre>\r
 914  *\r
 915  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 916  * \ingroup QueueManagement\r
 917  */\r
 918 #define xQueueSendToBackFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 919 \r
 920 /**\r
 921  * queue. h\r
 922  * <pre>\r
 923  portBASE_TYPE xQueueSendFromISR(\r
 924                                      xQueueHandle pxQueue,\r
 925                                      const void *pvItemToQueue,\r
 926                                      portBASE_TYPE *pxHigherPriorityTaskWoken\r
 927                                 );\r
 928  </pre>\r
 929  *\r
 930  * This is a macro that calls xQueueGenericSendFromISR().  It is included\r
 931  * for backward compatibility with versions of FreeRTOS.org that did not\r
 932  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()\r
 933  * macros.\r
 934  *\r
 935  * Post an item to the back of a queue.  It is safe to use this function 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 xQueueSendFromISR() 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 xQueueSendFromISR() 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  portCHAR cIn;\r
 964  portBASE_TYPE xHigherPriorityTaskWoken;\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         xQueueSendFromISR( 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         // Actual macro used here is port specific.\r
 984         taskYIELD_FROM_ISR ();\r
 985     }\r
 986  }\r
 987  </pre>\r
 988  *\r
 989  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 990  * \ingroup QueueManagement\r
 991  */\r
 992 #define xQueueSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 993 \r
 994 /**\r
 995  * queue. h\r
 996  * <pre>\r
 997  portBASE_TYPE xQueueGenericSendFromISR(\r
 998                                            xQueueHandle pxQueue,\r
 999                                            const void *pvItemToQueue,\r
1000                                            portBASE_TYPE *pxHigherPriorityTaskWoken,\r
1001                                                                                    portBASE_TYPE xCopyPosition\r
1002                                        );\r
1003  </pre>\r
1004  *\r
1005  * It is preferred that the macros xQueueSendFromISR(),\r
1006  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place\r
1007  * of calling this function directly.\r
1008  *\r
1009  * Post an item on a queue.  It is safe to use this function from within an\r
1010  * interrupt service routine.\r
1011  *\r
1012  * Items are queued by copy not reference so it is preferable to only\r
1013  * queue small items, especially when called from an ISR.  In most cases\r
1014  * it would be preferable to store a pointer to the item being queued.\r
1015  *\r
1016  * @param xQueue The handle to the queue on which the item is to be posted.\r
1017  *\r
1018  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1019  * queue.  The size of the items the queue will hold was defined when the\r
1020  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1021  * into the queue storage area.\r
1022  *\r
1023  * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set\r
1024  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1025  * to unblock, and the unblocked task has a priority higher than the currently\r
1026  * running task.  If xQueueGenericSendFromISR() sets this value to pdTRUE then\r
1027  * a context switch should be requested before the interrupt is exited.\r
1028  *\r
1029  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
1030  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
1031  * at the front of the queue (for high priority messages).\r
1032  *\r
1033  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1034  * errQUEUE_FULL.\r
1035  *\r
1036  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1037  * per call):\r
1038    <pre>\r
1039  void vBufferISR( void )\r
1040  {\r
1041  portCHAR cIn;\r
1042  portBASE_TYPE xHigherPriorityTaskWokenByPost;\r
1043 \r
1044     // We have not woken a task at the start of the ISR.\r
1045     xHigherPriorityTaskWokenByPost = pdFALSE;\r
1046 \r
1047     // Loop until the buffer is empty.\r
1048     do\r
1049     {\r
1050         // Obtain a byte from the buffer.\r
1051         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
1052 \r
1053         // Post each byte.\r
1054         xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );\r
1055 \r
1056     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1057 \r
1058     // Now the buffer is empty we can switch context if necessary.  Note that the\r
1059     // name of the yield function required is port specific.\r
1060     if( xHigherPriorityTaskWokenByPost )\r
1061     {\r
1062         taskYIELD_YIELD_FROM_ISR();\r
1063     }\r
1064  }\r
1065  </pre>\r
1066  *\r
1067  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1068  * \ingroup QueueManagement\r
1069  */\r
1070 signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle pxQueue, const void * const pvItemToQueue, signed portBASE_TYPE *pxHigherPriorityTaskWoken, portBASE_TYPE xCopyPosition );\r
1071 \r
1072 /**\r
1073  * queue. h\r
1074  * <pre>\r
1075  portBASE_TYPE xQueueReceiveFromISR(\r
1076                                        xQueueHandle pxQueue,\r
1077                                        void *pvBuffer,\r
1078                                        portBASE_TYPE *pxTaskWoken\r
1079                                    );\r
1080  * </pre>\r
1081  *\r
1082  * Receive an item from a queue.  It is safe to use this function from within an\r
1083  * interrupt service routine.\r
1084  *\r
1085  * @param pxQueue The handle to the queue from which the item is to be\r
1086  * received.\r
1087  *\r
1088  * @param pvBuffer Pointer to the buffer into which the received item will\r
1089  * be copied.\r
1090  *\r
1091  * @param pxTaskWoken A task may be blocked waiting for space to become\r
1092  * available on the queue.  If xQueueReceiveFromISR causes such a task to\r
1093  * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will\r
1094  * remain unchanged.\r
1095  *\r
1096  * @return pdTRUE if an item was successfully received from the queue,\r
1097  * otherwise pdFALSE.\r
1098  *\r
1099  * Example usage:\r
1100    <pre>\r
1101 \r
1102  xQueueHandle xQueue;\r
1103 \r
1104  // Function to create a queue and post some values.\r
1105  void vAFunction( void *pvParameters )\r
1106  {\r
1107  portCHAR cValueToPost;\r
1108  const portTickType xBlockTime = ( portTickType )0xff;\r
1109 \r
1110     // Create a queue capable of containing 10 characters.\r
1111     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );\r
1112     if( xQueue == 0 )\r
1113     {\r
1114         // Failed to create the queue.\r
1115     }\r
1116 \r
1117     // ...\r
1118 \r
1119     // Post some characters that will be used within an ISR.  If the queue\r
1120     // is full then this task will block for xBlockTime ticks.\r
1121     cValueToPost = 'a';\r
1122     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1123     cValueToPost = 'b';\r
1124     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1125 \r
1126     // ... keep posting characters ... this task may block when the queue\r
1127     // becomes full.\r
1128 \r
1129     cValueToPost = 'c';\r
1130     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1131  }\r
1132 \r
1133  // ISR that outputs all the characters received on the queue.\r
1134  void vISR_Routine( void )\r
1135  {\r
1136  portBASE_TYPE xTaskWokenByReceive = pdFALSE;\r
1137  portCHAR cRxedChar;\r
1138 \r
1139     while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )\r
1140     {\r
1141         // A character was received.  Output the character now.\r
1142         vOutputCharacter( cRxedChar );\r
1143 \r
1144         // If removing the character from the queue woke the task that was\r
1145         // posting onto the queue cTaskWokenByReceive will have been set to\r
1146         // pdTRUE.  No matter how many times this loop iterates only one\r
1147         // task will be woken.\r
1148     }\r
1149 \r
1150     if( cTaskWokenByPost != ( portCHAR ) pdFALSE;\r
1151     {\r
1152         taskYIELD ();\r
1153     }\r
1154  }\r
1155  </pre>\r
1156  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR\r
1157  * \ingroup QueueManagement\r
1158  */\r
1159 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, void * const pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1160 \r
1161 /*\r
1162  * Utilities to query queue that are safe to use from an ISR.  These utilities\r
1163  * should be used only from witin an ISR, or within a critical section.\r
1164  */\r
1165 signed portBASE_TYPE xQueueIsQueueEmptyFromISR( const xQueueHandle pxQueue );\r
1166 signed portBASE_TYPE xQueueIsQueueFullFromISR( const xQueueHandle pxQueue );\r
1167 unsigned portBASE_TYPE uxQueueMessagesWaitingFromISR( const xQueueHandle pxQueue );\r
1168 \r
1169 \r
1170 /* \r
1171  * xQueueAltGenericSend() is an alternative version of xQueueGenericSend().\r
1172  * Likewise xQueueAltGenericReceive() is an alternative version of\r
1173  * xQueueGenericReceive().\r
1174  *\r
1175  * The source code that implements the alternative (Alt) API is much \r
1176  * simpler      because it executes everything from within a critical section.  \r
1177  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
1178  * preferred fully featured API too.  The fully featured API has more \r
1179  * complex      code that takes longer to execute, but makes much less use of \r
1180  * critical sections.  Therefore the alternative API sacrifices interrupt \r
1181  * responsiveness to gain execution speed, whereas the fully featured API\r
1182  * sacrifices execution speed to ensure better interrupt responsiveness.\r
1183  */\r
1184 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle pxQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
1185 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle pxQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking );\r
1186 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
1187 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
1188 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
1189 #define xQueueAltPeek( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
1190 \r
1191 /*\r
1192  * The functions defined above are for passing data to and from tasks.  The\r
1193  * functions below are the equivalents for passing data to and from\r
1194  * co-routines.\r
1195  *\r
1196  * These functions are called from the co-routine macro implementation and\r
1197  * should not be called directly from application code.  Instead use the macro\r
1198  * wrappers defined within croutine.h.\r
1199  */\r
1200 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken );\r
1201 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1202 signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQueue, portTickType xTicksToWait );\r
1203 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );\r
1204 \r
1205 /*\r
1206  * For internal use only.  Use xSemaphoreCreateMutex() or\r
1207  * xSemaphoreCreateCounting() instead of calling these functions directly.\r
1208  */\r
1209 xQueueHandle xQueueCreateMutex( void );\r
1210 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue, unsigned portBASE_TYPE uxInitialCount );\r
1211 \r
1212 /*\r
1213  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or\r
1214  * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.\r
1215  */\r
1216 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle xMutex, portTickType xBlockTime );\r
1217 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle xMutex );\r
1218 \r
1219 /*\r
1220  * The registry is provided as a means for kernel aware debuggers to\r
1221  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
1222  * a queue, semaphore or mutex handle to the registry if you want the handle \r
1223  * to be available to a kernel aware debugger.  If you are not using a kernel \r
1224  * aware debugger then this function can be ignored.\r
1225  *\r
1226  * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the\r
1227  * registry can hold.  configQUEUE_REGISTRY_SIZE must be greater than 0 \r
1228  * within FreeRTOSConfig.h for the registry to be available.  Its value\r
1229  * does not effect the number of queues, semaphores and mutexes that can be \r
1230  * created - just the number that the registry can hold.\r
1231  *\r
1232  * @param xQueue The handle of the queue being added to the registry.  This\r
1233  * is the handle returned by a call to xQueueCreate().  Semaphore and mutex\r
1234  * handles can also be passed in here.\r
1235  *\r
1236  * @param pcName The name to be associated with the handle.  This is the\r
1237  * name that the kernel aware debugger will display.\r
1238  */\r
1239 #if configQUEUE_REGISTRY_SIZE > 0\r
1240         void vQueueAddToRegistry( xQueueHandle xQueue, signed portCHAR *pcName );\r
1241 #endif\r
1242 \r
1243 \r
1244 \r
1245 \r
1246 #ifdef __cplusplus\r
1247 }\r
1248 #endif\r
1249 \r
1250 #endif /* QUEUE_H */\r
1251 \r