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

   1 /*\r
   2         FreeRTOS.org V5.0.4 - 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.  The\r
 155  * time is defined in tick periods so the constant portTICK_RATE_MS\r
 156  * 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.  The\r
 237  * time is defined in tick periods so the constant portTICK_RATE_MS\r
 238  * 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.  The\r
 321  * time is defined in tick periods so the constant portTICK_RATE_MS\r
 322  * 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.  The\r
 405  * time is defined in tick periods so the constant portTICK_RATE_MS\r
 406  * 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  *\r
 496  * @return pdTRUE if an item was successfully received from the queue,\r
 497  * otherwise pdFALSE.\r
 498  *\r
 499  * Example usage:\r
 500    <pre>\r
 501  struct AMessage\r
 502  {\r
 503     portCHAR ucMessageID;\r
 504     portCHAR ucData[ 20 ];\r
 505  } xMessage;\r
 506 \r
 507  xQueueHandle xQueue;\r
 508 \r
 509  // Task to create a queue and post a value.\r
 510  void vATask( void *pvParameters )\r
 511  {\r
 512  struct AMessage *pxMessage;\r
 513 \r
 514     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 515     // These should be passed by pointer as they contain a lot of data.\r
 516     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 517     if( xQueue == 0 )\r
 518     {\r
 519         // Failed to create the queue.\r
 520     }\r
 521 \r
 522     // ...\r
 523 \r
 524     // Send a pointer to a struct AMessage object.  Don't block if the\r
 525     // queue is already full.\r
 526     pxMessage = & xMessage;\r
 527     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 528 \r
 529         // ... Rest of task code.\r
 530  }\r
 531 \r
 532  // Task to peek the data from the queue.\r
 533  void vADifferentTask( void *pvParameters )\r
 534  {\r
 535  struct AMessage *pxRxedMessage;\r
 536 \r
 537     if( xQueue != 0 )\r
 538     {\r
 539         // Peek a message on the created queue.  Block for 10 ticks if a\r
 540         // message is not immediately available.\r
 541         if( xQueuePeek( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 542         {\r
 543             // pcRxedMessage now points to the struct AMessage variable posted\r
 544             // by vATask, but the item still remains on the queue.\r
 545         }\r
 546     }\r
 547 \r
 548         // ... Rest of task code.\r
 549  }\r
 550  </pre>\r
 551  * \defgroup xQueueReceive xQueueReceive\r
 552  * \ingroup QueueManagement\r
 553  */\r
 554 #define xQueuePeek( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
 555 \r
 556 /**\r
 557  * queue. h\r
 558  * <pre>\r
 559  portBASE_TYPE xQueueReceive(\r
 560                                  xQueueHandle xQueue,\r
 561                                  void *pvBuffer,\r
 562                                  portTickType xTicksToWait\r
 563                             );</pre>\r
 564  *\r
 565  * This is a macro that calls the xQueueGenericReceive() function.\r
 566  *\r
 567  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 568  * adequate size must be provided.  The number of bytes copied into the buffer\r
 569  * was defined when the queue was created.\r
 570  *\r
 571  * Successfully received items are removed from the queue.\r
 572  *\r
 573  * This function must not be used in an interrupt service routine.  See\r
 574  * xQueueReceiveFromISR for an alternative that can.\r
 575  *\r
 576  * @param pxQueue The handle to the queue from which the item is to be\r
 577  * received.\r
 578  *\r
 579  * @param pvBuffer Pointer to the buffer into which the received item will\r
 580  * be copied.\r
 581  *\r
 582  * @param xTicksToWait The maximum amount of time the task should block\r
 583  * waiting for an item to receive should the queue be empty at the time\r
 584  * of the call.    The time is defined in tick periods so the constant\r
 585  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 586  *\r
 587  * @return pdTRUE if an item was successfully received from the queue,\r
 588  * otherwise pdFALSE.\r
 589  *\r
 590  * Example usage:\r
 591    <pre>\r
 592  struct AMessage\r
 593  {\r
 594     portCHAR ucMessageID;\r
 595     portCHAR ucData[ 20 ];\r
 596  } xMessage;\r
 597 \r
 598  xQueueHandle xQueue;\r
 599 \r
 600  // Task to create a queue and post a value.\r
 601  void vATask( void *pvParameters )\r
 602  {\r
 603  struct AMessage *pxMessage;\r
 604 \r
 605     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 606     // These should be passed by pointer as they contain a lot of data.\r
 607     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 608     if( xQueue == 0 )\r
 609     {\r
 610         // Failed to create the queue.\r
 611     }\r
 612 \r
 613     // ...\r
 614 \r
 615     // Send a pointer to a struct AMessage object.  Don't block if the\r
 616     // queue is already full.\r
 617     pxMessage = & xMessage;\r
 618     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 619 \r
 620         // ... Rest of task code.\r
 621  }\r
 622 \r
 623  // Task to receive from the queue.\r
 624  void vADifferentTask( void *pvParameters )\r
 625  {\r
 626  struct AMessage *pxRxedMessage;\r
 627 \r
 628     if( xQueue != 0 )\r
 629     {\r
 630         // Receive a message on the created queue.  Block for 10 ticks if a\r
 631         // message is not immediately available.\r
 632         if( xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 633         {\r
 634             // pcRxedMessage now points to the struct AMessage variable posted\r
 635             // by vATask.\r
 636         }\r
 637     }\r
 638 \r
 639         // ... Rest of task code.\r
 640  }\r
 641  </pre>\r
 642  * \defgroup xQueueReceive xQueueReceive\r
 643  * \ingroup QueueManagement\r
 644  */\r
 645 #define xQueueReceive( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
 646 \r
 647 \r
 648 /**\r
 649  * queue. h\r
 650  * <pre>\r
 651  portBASE_TYPE xQueueGenericReceive(\r
 652                                        xQueueHandle xQueue,\r
 653                                        void *pvBuffer,\r
 654                                        portTickType xTicksToWait\r
 655                                        portBASE_TYPE xJustPeek\r
 656                                     );</pre>\r
 657  *\r
 658  * It is preferred that the macro xQueueReceive() be used rather than calling\r
 659  * this function directly.\r
 660  *\r
 661  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 662  * adequate size must be provided.  The number of bytes copied into the buffer\r
 663  * was defined when the queue was created.\r
 664  *\r
 665  * This function must not be used in an interrupt service routine.  See\r
 666  * xQueueReceiveFromISR for an alternative that can.\r
 667  *\r
 668  * @param pxQueue The handle to the queue from which the item is to be\r
 669  * received.\r
 670  *\r
 671  * @param pvBuffer Pointer to the buffer into which the received item will\r
 672  * be copied.\r
 673  *\r
 674  * @param xTicksToWait The maximum amount of time the task should block\r
 675  * waiting for an item to receive should the queue be empty at the time\r
 676  * of the call.    The time is defined in tick periods so the constant\r
 677  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 678  *\r
 679  * @param xJustPeek When set to true, the item received from the queue is not\r
 680  * actually removed from the queue - meaning a subsequent call to\r
 681  * xQueueReceive() will return the same item.  When set to false, the item\r
 682  * being received from the queue is also removed from the queue.\r
 683  *\r
 684  * @return pdTRUE if an item was successfully received from the queue,\r
 685  * otherwise pdFALSE.\r
 686  *\r
 687  * Example usage:\r
 688    <pre>\r
 689  struct AMessage\r
 690  {\r
 691     portCHAR ucMessageID;\r
 692     portCHAR ucData[ 20 ];\r
 693  } xMessage;\r
 694 \r
 695  xQueueHandle xQueue;\r
 696 \r
 697  // Task to create a queue and post a value.\r
 698  void vATask( void *pvParameters )\r
 699  {\r
 700  struct AMessage *pxMessage;\r
 701 \r
 702     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 703     // These should be passed by pointer as they contain a lot of data.\r
 704     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 705     if( xQueue == 0 )\r
 706     {\r
 707         // Failed to create the queue.\r
 708     }\r
 709 \r
 710     // ...\r
 711 \r
 712     // Send a pointer to a struct AMessage object.  Don't block if the\r
 713     // queue is already full.\r
 714     pxMessage = & xMessage;\r
 715     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 716 \r
 717         // ... Rest of task code.\r
 718  }\r
 719 \r
 720  // Task to receive from the queue.\r
 721  void vADifferentTask( void *pvParameters )\r
 722  {\r
 723  struct AMessage *pxRxedMessage;\r
 724 \r
 725     if( xQueue != 0 )\r
 726     {\r
 727         // Receive a message on the created queue.  Block for 10 ticks if a\r
 728         // message is not immediately available.\r
 729         if( xQueueGenericReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 730         {\r
 731             // pcRxedMessage now points to the struct AMessage variable posted\r
 732             // by vATask.\r
 733         }\r
 734     }\r
 735 \r
 736         // ... Rest of task code.\r
 737  }\r
 738  </pre>\r
 739  * \defgroup xQueueReceive xQueueReceive\r
 740  * \ingroup QueueManagement\r
 741  */\r
 742 signed portBASE_TYPE xQueueGenericReceive( xQueueHandle xQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeek );\r
 743 \r
 744 /**\r
 745  * queue. h\r
 746  * <pre>unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );</pre>\r
 747  *\r
 748  * Return the number of messages stored in a queue.\r
 749  *\r
 750  * @param xQueue A handle to the queue being queried.\r
 751  *\r
 752  * @return The number of messages available in the queue.\r
 753  *\r
 754  * \page uxQueueMessagesWaiting uxQueueMessagesWaiting\r
 755  * \ingroup QueueManagement\r
 756  */\r
 757 unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );\r
 758 \r
 759 /**\r
 760  * queue. h\r
 761  * <pre>void vQueueDelete( xQueueHandle xQueue );</pre>\r
 762  *\r
 763  * Delete a queue - freeing all the memory allocated for storing of items\r
 764  * placed on the queue.\r
 765  *\r
 766  * @param xQueue A handle to the queue to be deleted.\r
 767  *\r
 768  * \page vQueueDelete vQueueDelete\r
 769  * \ingroup QueueManagement\r
 770  */\r
 771 void vQueueDelete( xQueueHandle xQueue );\r
 772 \r
 773 /**\r
 774  * queue. h\r
 775  * <pre>\r
 776  portBASE_TYPE xQueueSendToFrontFromISR(\r
 777                                          xQueueHandle pxQueue,\r
 778                                          const void *pvItemToQueue,\r
 779                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 780                                       );\r
 781  </pre>\r
 782  *\r
 783  * This is a macro that calls xQueueGenericSendFromISR().\r
 784  *\r
 785  * Post an item to the front of a queue.  It is safe to use this macro from\r
 786  * within an interrupt service routine.\r
 787  *\r
 788  * Items are queued by copy not reference so it is preferable to only\r
 789  * queue small items, especially when called from an ISR.  In most cases\r
 790  * it would be preferable to store a pointer to the item being queued.\r
 791  *\r
 792  * @param xQueue The handle to the queue on which the item is to be posted.\r
 793  *\r
 794  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 795  * queue.  The size of the items the queue will hold was defined when the\r
 796  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 797  * into the queue storage area.\r
 798  *\r
 799  * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set\r
 800  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 801  * to unblock, and the unblocked task has a priority higher than the currently\r
 802  * running task.  If xQueueSendToFromFromISR() sets this value to pdTRUE then\r
 803  * a context switch should be requested before the interrupt is exited.\r
 804  *\r
 805  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 806  * errQUEUE_FULL.\r
 807  *\r
 808  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 809  * per call):\r
 810    <pre>\r
 811  void vBufferISR( void )\r
 812  {\r
 813  portCHAR cIn;\r
 814  portBASE_TYPE xHigherPrioritTaskWoken;\r
 815 \r
 816     // We have not woken a task at the start of the ISR.\r
 817     xHigherPriorityTaskWoken = pdFALSE;\r
 818 \r
 819     // Loop until the buffer is empty.\r
 820     do\r
 821     {\r
 822         // Obtain a byte from the buffer.\r
 823         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 824 \r
 825         // Post the byte.  \r
 826         xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 827 \r
 828     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 829 \r
 830     // Now the buffer is empty we can switch context if necessary.\r
 831     if( xHigherPriorityTaskWoken )\r
 832     {\r
 833         taskYIELD ();\r
 834     }\r
 835  }\r
 836  </pre>\r
 837  *\r
 838  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 839  * \ingroup QueueManagement\r
 840  */\r
 841 #define xQueueSendToFrontFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_FRONT )\r
 842 \r
 843 \r
 844 /**\r
 845  * queue. h\r
 846  * <pre>\r
 847  portBASE_TYPE xQueueSendToBackFromISR(\r
 848                                          xQueueHandle pxQueue,\r
 849                                          const void *pvItemToQueue,\r
 850                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 851                                       );\r
 852  </pre>\r
 853  *\r
 854  * This is a macro that calls xQueueGenericSendFromISR().\r
 855  *\r
 856  * Post an item to the back of a queue.  It is safe to use this macro from\r
 857  * within an interrupt service routine.\r
 858  *\r
 859  * Items are queued by copy not reference so it is preferable to only\r
 860  * queue small items, especially when called from an ISR.  In most cases\r
 861  * it would be preferable to store a pointer to the item being queued.\r
 862  *\r
 863  * @param xQueue The handle to the queue on which the item is to be posted.\r
 864  *\r
 865  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 866  * queue.  The size of the items the queue will hold was defined when the\r
 867  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 868  * into the queue storage area.\r
 869  *\r
 870  * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set\r
 871  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 872  * to unblock, and the unblocked task has a priority higher than the currently\r
 873  * running task.  If xQueueSendToBackFromISR() sets this value to pdTRUE then\r
 874  * a context switch should be requested before the interrupt is exited.\r
 875  *\r
 876  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 877  * errQUEUE_FULL.\r
 878  *\r
 879  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 880  * per call):\r
 881    <pre>\r
 882  void vBufferISR( void )\r
 883  {\r
 884  portCHAR cIn;\r
 885  portBASE_TYPE xHigherPriorityTaskWoken;\r
 886 \r
 887     // We have not woken a task at the start of the ISR.\r
 888     xHigherPriorityTaskWoken = pdFALSE;\r
 889 \r
 890     // Loop until the buffer is empty.\r
 891     do\r
 892     {\r
 893         // Obtain a byte from the buffer.\r
 894         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 895 \r
 896         // Post the byte.\r
 897         xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 898 \r
 899     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 900 \r
 901     // Now the buffer is empty we can switch context if necessary.\r
 902     if( xHigherPriorityTaskWoken )\r
 903     {\r
 904         taskYIELD ();\r
 905     }\r
 906  }\r
 907  </pre>\r
 908  *\r
 909  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 910  * \ingroup QueueManagement\r
 911  */\r
 912 #define xQueueSendToBackFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 913 \r
 914 /**\r
 915  * queue. h\r
 916  * <pre>\r
 917  portBASE_TYPE xQueueSendFromISR(\r
 918                                      xQueueHandle pxQueue,\r
 919                                      const void *pvItemToQueue,\r
 920                                      portBASE_TYPE *pxHigherPriorityTaskWoken\r
 921                                 );\r
 922  </pre>\r
 923  *\r
 924  * This is a macro that calls xQueueGenericSendFromISR().  It is included\r
 925  * for backward compatibility with versions of FreeRTOS.org that did not\r
 926  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()\r
 927  * macros.\r
 928  *\r
 929  * Post an item to the back of a queue.  It is safe to use this function from\r
 930  * within an interrupt service routine.\r
 931  *\r
 932  * Items are queued by copy not reference so it is preferable to only\r
 933  * queue small items, especially when called from an ISR.  In most cases\r
 934  * it would be preferable to store a pointer to the item being queued.\r
 935  *\r
 936  * @param xQueue The handle to the queue on which the item is to be posted.\r
 937  *\r
 938  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 939  * queue.  The size of the items the queue will hold was defined when the\r
 940  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 941  * into the queue storage area.\r
 942  *\r
 943  * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set\r
 944  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 945  * to unblock, and the unblocked task has a priority higher than the currently\r
 946  * running task.  If xQueueSendFromISR() sets this value to pdTRUE then\r
 947  * a context switch should be requested before the interrupt is exited.\r
 948  *\r
 949  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 950  * errQUEUE_FULL.\r
 951  *\r
 952  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 953  * per call):\r
 954    <pre>\r
 955  void vBufferISR( void )\r
 956  {\r
 957  portCHAR cIn;\r
 958  portBASE_TYPE xHigherPriorityTaskWoken;\r
 959 \r
 960     // We have not woken a task at the start of the ISR.\r
 961     xHigherPriorityTaskWoken = pdFALSE;\r
 962 \r
 963     // Loop until the buffer is empty.\r
 964     do\r
 965     {\r
 966         // Obtain a byte from the buffer.\r
 967         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 968 \r
 969         // Post the byte.  \r
 970         xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 971 \r
 972     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 973 \r
 974     // Now the buffer is empty we can switch context if necessary.\r
 975     if( xHigherPriorityTaskWoken )\r
 976     {\r
 977         // Actual macro used here is port specific.\r
 978         taskYIELD_FROM_ISR ();\r
 979     }\r
 980  }\r
 981  </pre>\r
 982  *\r
 983  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 984  * \ingroup QueueManagement\r
 985  */\r
 986 #define xQueueSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 987 \r
 988 /**\r
 989  * queue. h\r
 990  * <pre>\r
 991  portBASE_TYPE xQueueGenericSendFromISR(\r
 992                                            xQueueHandle pxQueue,\r
 993                                            const void *pvItemToQueue,\r
 994                                            portBASE_TYPE *pxHigherPriorityTaskWoken,\r
 995                                                                                    portBASE_TYPE xCopyPosition\r
 996                                        );\r
 997  </pre>\r
 998  *\r
 999  * It is preferred that the macros xQueueSendFromISR(),\r
1000  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place\r
1001  * of calling this function directly.\r
1002  *\r
1003  * Post an item on a queue.  It is safe to use this function from within an\r
1004  * interrupt service routine.\r
1005  *\r
1006  * Items are queued by copy not reference so it is preferable to only\r
1007  * queue small items, especially when called from an ISR.  In most cases\r
1008  * it would be preferable to store a pointer to the item being queued.\r
1009  *\r
1010  * @param xQueue The handle to the queue on which the item is to be posted.\r
1011  *\r
1012  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1013  * queue.  The size of the items the queue will hold was defined when the\r
1014  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1015  * into the queue storage area.\r
1016  *\r
1017  * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set\r
1018  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1019  * to unblock, and the unblocked task has a priority higher than the currently\r
1020  * running task.  If xQueueGenericSendFromISR() sets this value to pdTRUE then\r
1021  * a context switch should be requested before the interrupt is exited.\r
1022  *\r
1023  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
1024  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
1025  * at the front of the queue (for high priority messages).\r
1026  *\r
1027  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1028  * errQUEUE_FULL.\r
1029  *\r
1030  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1031  * per call):\r
1032    <pre>\r
1033  void vBufferISR( void )\r
1034  {\r
1035  portCHAR cIn;\r
1036  portBASE_TYPE xHigherPriorityTaskWokenByPost;\r
1037 \r
1038     // We have not woken a task at the start of the ISR.\r
1039     xHigherPriorityTaskWokenByPost = pdFALSE;\r
1040 \r
1041     // Loop until the buffer is empty.\r
1042     do\r
1043     {\r
1044         // Obtain a byte from the buffer.\r
1045         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
1046 \r
1047         // Post each byte.\r
1048         xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );\r
1049 \r
1050     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1051 \r
1052     // Now the buffer is empty we can switch context if necessary.  Note that the\r
1053     // name of the yield function required is port specific.\r
1054     if( xHigherPriorityTaskWokenByPost )\r
1055     {\r
1056         taskYIELD_YIELD_FROM_ISR();\r
1057     }\r
1058  }\r
1059  </pre>\r
1060  *\r
1061  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1062  * \ingroup QueueManagement\r
1063  */\r
1064 signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle pxQueue, const void * const pvItemToQueue, signed portBASE_TYPE *pxHigherPriorityTaskWoken, portBASE_TYPE xCopyPosition );\r
1065 \r
1066 /**\r
1067  * queue. h\r
1068  * <pre>\r
1069  portBASE_TYPE xQueueReceiveFromISR(\r
1070                                        xQueueHandle pxQueue,\r
1071                                        void *pvBuffer,\r
1072                                        portBASE_TYPE *pxTaskWoken\r
1073                                    );\r
1074  * </pre>\r
1075  *\r
1076  * Receive an item from a queue.  It is safe to use this function from within an\r
1077  * interrupt service routine.\r
1078  *\r
1079  * @param pxQueue The handle to the queue from which the item is to be\r
1080  * received.\r
1081  *\r
1082  * @param pvBuffer Pointer to the buffer into which the received item will\r
1083  * be copied.\r
1084  *\r
1085  * @param pxTaskWoken A task may be blocked waiting for space to become\r
1086  * available on the queue.  If xQueueReceiveFromISR causes such a task to\r
1087  * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will\r
1088  * remain unchanged.\r
1089  *\r
1090  * @return pdTRUE if an item was successfully received from the queue,\r
1091  * otherwise pdFALSE.\r
1092  *\r
1093  * Example usage:\r
1094    <pre>\r
1095 \r
1096  xQueueHandle xQueue;\r
1097 \r
1098  // Function to create a queue and post some values.\r
1099  void vAFunction( void *pvParameters )\r
1100  {\r
1101  portCHAR cValueToPost;\r
1102  const portTickType xBlockTime = ( portTickType )0xff;\r
1103 \r
1104     // Create a queue capable of containing 10 characters.\r
1105     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );\r
1106     if( xQueue == 0 )\r
1107     {\r
1108         // Failed to create the queue.\r
1109     }\r
1110 \r
1111     // ...\r
1112 \r
1113     // Post some characters that will be used within an ISR.  If the queue\r
1114     // is full then this task will block for xBlockTime ticks.\r
1115     cValueToPost = 'a';\r
1116     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1117     cValueToPost = 'b';\r
1118     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1119 \r
1120     // ... keep posting characters ... this task may block when the queue\r
1121     // becomes full.\r
1122 \r
1123     cValueToPost = 'c';\r
1124     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1125  }\r
1126 \r
1127  // ISR that outputs all the characters received on the queue.\r
1128  void vISR_Routine( void )\r
1129  {\r
1130  portBASE_TYPE xTaskWokenByReceive = pdFALSE;\r
1131  portCHAR cRxedChar;\r
1132 \r
1133     while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )\r
1134     {\r
1135         // A character was received.  Output the character now.\r
1136         vOutputCharacter( cRxedChar );\r
1137 \r
1138         // If removing the character from the queue woke the task that was\r
1139         // posting onto the queue cTaskWokenByReceive will have been set to\r
1140         // pdTRUE.  No matter how many times this loop iterates only one\r
1141         // task will be woken.\r
1142     }\r
1143 \r
1144     if( cTaskWokenByPost != ( portCHAR ) pdFALSE;\r
1145     {\r
1146         taskYIELD ();\r
1147     }\r
1148  }\r
1149  </pre>\r
1150  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR\r
1151  * \ingroup QueueManagement\r
1152  */\r
1153 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, void * const pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1154 \r
1155 /*\r
1156  * Utilities to query queue that are safe to use from an ISR.  These utilities\r
1157  * should be used only from witin an ISR, or within a critical section.\r
1158  */\r
1159 signed portBASE_TYPE xQueueIsQueueEmptyFromISR( const xQueueHandle pxQueue );\r
1160 signed portBASE_TYPE xQueueIsQueueFullFromISR( const xQueueHandle pxQueue );\r
1161 unsigned portBASE_TYPE uxQueueMessagesWaitingFromISR( const xQueueHandle pxQueue );\r
1162 \r
1163 \r
1164 /* \r
1165  * xQueueAltGenericSend() is an alternative version of xQueueGenericSend().\r
1166  * Likewise xQueueAltGenericReceive() is an alternative version of\r
1167  * xQueueGenericReceive().\r
1168  *\r
1169  * The source code that implements the alternative (Alt) API is much \r
1170  * simpler      because it executes everything from within a critical section.  \r
1171  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
1172  * preferred fully featured API too.  The fully featured API has more \r
1173  * complex      code that takes longer to execute, but makes much less use of \r
1174  * critical sections.  Therefore the alternative API sacrifices interrupt \r
1175  * responsiveness to gain execution speed, whereas the fully featured API\r
1176  * sacrifices execution speed to ensure better interrupt responsiveness.\r
1177  */\r
1178 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle pxQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
1179 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle pxQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking );\r
1180 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
1181 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
1182 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
1183 #define xQueueAltPeek( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
1184 \r
1185 /*\r
1186  * The functions defined above are for passing data to and from tasks.  The\r
1187  * functions below are the equivalents for passing data to and from\r
1188  * co-routines.\r
1189  *\r
1190  * These functions are called from the co-routine macro implementation and\r
1191  * should not be called directly from application code.  Instead use the macro\r
1192  * wrappers defined within croutine.h.\r
1193  */\r
1194 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken );\r
1195 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1196 signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQueue, portTickType xTicksToWait );\r
1197 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );\r
1198 \r
1199 /*\r
1200  * For internal use only.  Use xSemaphoreCreateMutex() or\r
1201  * xSemaphoreCreateCounting() instead of calling these functions directly.\r
1202  */\r
1203 xQueueHandle xQueueCreateMutex( void );\r
1204 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue, unsigned portBASE_TYPE uxInitialCount );\r
1205 \r
1206 /*\r
1207  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or\r
1208  * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.\r
1209  */\r
1210 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle xMutex, portTickType xBlockTime );\r
1211 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle xMutex );\r
1212 \r
1213 /*\r
1214  * The registry is provided as a means for kernel aware debuggers to\r
1215  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
1216  * a queue, semaphore or mutex handle to the registry if you want the handle \r
1217  * to be available to a kernel aware debugger.  If you are not using a kernel \r
1218  * aware debugger then this function can be ignored.\r
1219  *\r
1220  * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the\r
1221  * registry can hold.  configQUEUE_REGISTRY_SIZE must be greater than 0 \r
1222  * within FreeRTOSConfig.h for the registry to be available.  Its value\r
1223  * does not effect the number of queues, semaphores and mutexes that can be \r
1224  * created - just the number that the registry can hold.\r
1225  *\r
1226  * @param xQueue The handle of the queue being added to the registry.  This\r
1227  * is the handle returned by a call to xQueueCreate().  Semaphore and mutex\r
1228  * handles can also be passed in here.\r
1229  *\r
1230  * @param pcName The name to be associated with the handle.  This is the\r
1231  * name that the kernel aware debugger will display.\r
1232  */\r
1233 #if configQUEUE_REGISTRY_SIZE > 0\r
1234         void vQueueAddToRegistry( xQueueHandle xQueue, signed portCHAR *pcName );\r
1235 #endif\r
1236 \r
1237 \r
1238 \r
1239 \r
1240 #ifdef __cplusplus\r
1241 }\r
1242 #endif\r
1243 \r
1244 #endif /* QUEUE_H */\r
1245 \r