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

   1 /*\r
   2     FreeRTOS V8.2.0rc1 - Copyright (C) 2014 Real Time Engineers Ltd.\r
   3     All rights reserved\r
   4 \r
   5     VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.\r
   6 \r
   7     This file is part of the FreeRTOS distribution.\r
   8 \r
   9     FreeRTOS is free software; you can redistribute it and/or modify it under\r
  10     the terms of the GNU General Public License (version 2) as published by the\r
  11     Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.\r
  12 \r
  13     >>!   NOTE: The modification to the GPL is included to allow you to     !<<\r
  14     >>!   distribute a combined work that includes FreeRTOS without being   !<<\r
  15     >>!   obliged to provide the source code for proprietary components     !<<\r
  16     >>!   outside of the FreeRTOS kernel.                                   !<<\r
  17 \r
  18     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY\r
  19     WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS\r
  20     FOR A PARTICULAR PURPOSE.  Full license text is available on the following\r
  21     link: http://www.freertos.org/a00114.html\r
  22 \r
  23     1 tab == 4 spaces!\r
  24 \r
  25     ***************************************************************************\r
  26      *                                                                       *\r
  27      *    Having a problem?  Start by reading the FAQ "My application does   *\r
  28      *    not run, what could be wrong?".  Have you defined configASSERT()?  *\r
  29      *                                                                       *\r
  30      *    http://www.FreeRTOS.org/FAQHelp.html                               *\r
  31      *                                                                       *\r
  32     ***************************************************************************\r
  33 \r
  34     ***************************************************************************\r
  35      *                                                                       *\r
  36      *    FreeRTOS provides completely free yet professionally developed,    *\r
  37      *    robust, strictly quality controlled, supported, and cross          *\r
  38      *    platform software that is more than just the market leader, it     *\r
  39      *    is the industry's de facto standard.                               *\r
  40      *                                                                       *\r
  41      *    Help yourself get started quickly while simultaneously helping     *\r
  42      *    to support the FreeRTOS project by purchasing a FreeRTOS           *\r
  43      *    tutorial book, reference manual, or both:                          *\r
  44      *    http://www.FreeRTOS.org/Documentation                              *\r
  45      *                                                                       *\r
  46     ***************************************************************************\r
  47 \r
  48     ***************************************************************************\r
  49      *                                                                       *\r
  50      *   Investing in training allows your team to be as productive as       *\r
  51      *   possible as early as possible, lowering your overall development    *\r
  52      *   cost, and enabling you to bring a more robust product to market     *\r
  53      *   earlier than would otherwise be possible.  Richard Barry is both    *\r
  54      *   the architect and key author of FreeRTOS, and so also the world's   *\r
  55      *   leading authority on what is the world's most popular real time     *\r
  56      *   kernel for deeply embedded MCU designs.  Obtaining your training    *\r
  57      *   from Richard ensures your team will gain directly from his in-depth *\r
  58      *   product knowledge and years of usage experience.  Contact Real Time *\r
  59      *   Engineers Ltd to enquire about the FreeRTOS Masterclass, presented  *\r
  60      *   by Richard Barry:  http://www.FreeRTOS.org/contact\r
  61      *                                                                       *\r
  62     ***************************************************************************\r
  63 \r
  64     ***************************************************************************\r
  65      *                                                                       *\r
  66      *    You are receiving this top quality software for free.  Please play *\r
  67      *    fair and reciprocate by reporting any suspected issues and         *\r
  68      *    participating in the community forum:                              *\r
  69      *    http://www.FreeRTOS.org/support                                    *\r
  70      *                                                                       *\r
  71      *    Thank you!                                                         *\r
  72      *                                                                       *\r
  73     ***************************************************************************\r
  74 \r
  75     http://www.FreeRTOS.org - Documentation, books, training, latest versions,\r
  76     license and Real Time Engineers Ltd. contact details.\r
  77 \r
  78     http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,\r
  79     including FreeRTOS+Trace - an indispensable productivity tool, a DOS\r
  80     compatible FAT file system, and our tiny thread aware UDP/IP stack.\r
  81 \r
  82     http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.\r
  83     Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.\r
  84 \r
  85     http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High\r
  86     Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS\r
  87     licenses offer ticketed support, indemnification and commercial middleware.\r
  88 \r
  89     http://www.SafeRTOS.com - High Integrity Systems also provide a safety\r
  90     engineered and independently SIL3 certified version for use in safety and\r
  91     mission critical applications that require provable dependability.\r
  92 \r
  93     1 tab == 4 spaces!\r
  94 */\r
  95 \r
  96 #ifndef CO_ROUTINE_H\r
  97 #define CO_ROUTINE_H\r
  98 \r
  99 #ifndef INC_FREERTOS_H\r
 100         #error "include FreeRTOS.h must appear in source files before include croutine.h"\r
 101 #endif\r
 102 \r
 103 #include "list.h"\r
 104 \r
 105 #ifdef __cplusplus\r
 106 extern "C" {\r
 107 #endif\r
 108 \r
 109 /* Used to hide the implementation of the co-routine control block.  The\r
 110 control block structure however has to be included in the header due to\r
 111 the macro implementation of the co-routine functionality. */\r
 112 typedef void * CoRoutineHandle_t;\r
 113 \r
 114 /* Defines the prototype to which co-routine functions must conform. */\r
 115 typedef void (*crCOROUTINE_CODE)( CoRoutineHandle_t, UBaseType_t );\r
 116 \r
 117 typedef struct corCoRoutineControlBlock\r
 118 {\r
 119         crCOROUTINE_CODE        pxCoRoutineFunction;\r
 120         ListItem_t                      xGenericListItem;       /*< List item used to place the CRCB in ready and blocked queues. */\r
 121         ListItem_t                      xEventListItem;         /*< List item used to place the CRCB in event lists. */\r
 122         UBaseType_t             uxPriority;                     /*< The priority of the co-routine in relation to other co-routines. */\r
 123         UBaseType_t             uxIndex;                        /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */\r
 124         uint16_t                        uxState;                        /*< Used internally by the co-routine implementation. */\r
 125 } CRCB_t; /* Co-routine control block.  Note must be identical in size down to uxPriority with TCB_t. */\r
 126 \r
 127 /**\r
 128  * croutine. h\r
 129  *<pre>\r
 130  BaseType_t xCoRoutineCreate(\r
 131                                  crCOROUTINE_CODE pxCoRoutineCode,\r
 132                                  UBaseType_t uxPriority,\r
 133                                  UBaseType_t uxIndex\r
 134                                );</pre>\r
 135  *\r
 136  * Create a new co-routine and add it to the list of co-routines that are\r
 137  * ready to run.\r
 138  *\r
 139  * @param pxCoRoutineCode Pointer to the co-routine function.  Co-routine\r
 140  * functions require special syntax - see the co-routine section of the WEB\r
 141  * documentation for more information.\r
 142  *\r
 143  * @param uxPriority The priority with respect to other co-routines at which\r
 144  *  the co-routine will run.\r
 145  *\r
 146  * @param uxIndex Used to distinguish between different co-routines that\r
 147  * execute the same function.  See the example below and the co-routine section\r
 148  * of the WEB documentation for further information.\r
 149  *\r
 150  * @return pdPASS if the co-routine was successfully created and added to a ready\r
 151  * list, otherwise an error code defined with ProjDefs.h.\r
 152  *\r
 153  * Example usage:\r
 154    <pre>\r
 155  // Co-routine to be created.\r
 156  void vFlashCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 157  {\r
 158  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 159  // This may not be necessary for const variables.\r
 160  static const char cLedToFlash[ 2 ] = { 5, 6 };\r
 161  static const TickType_t uxFlashRates[ 2 ] = { 200, 400 };\r
 162 \r
 163      // Must start every co-routine with a call to crSTART();\r
 164      crSTART( xHandle );\r
 165 \r
 166      for( ;; )\r
 167      {\r
 168          // This co-routine just delays for a fixed period, then toggles\r
 169          // an LED.  Two co-routines are created using this function, so\r
 170          // the uxIndex parameter is used to tell the co-routine which\r
 171          // LED to flash and how int32_t to delay.  This assumes xQueue has\r
 172          // already been created.\r
 173          vParTestToggleLED( cLedToFlash[ uxIndex ] );\r
 174          crDELAY( xHandle, uxFlashRates[ uxIndex ] );\r
 175      }\r
 176 \r
 177      // Must end every co-routine with a call to crEND();\r
 178      crEND();\r
 179  }\r
 180 \r
 181  // Function that creates two co-routines.\r
 182  void vOtherFunction( void )\r
 183  {\r
 184  uint8_t ucParameterToPass;\r
 185  TaskHandle_t xHandle;\r
 186 \r
 187      // Create two co-routines at priority 0.  The first is given index 0\r
 188      // so (from the code above) toggles LED 5 every 200 ticks.  The second\r
 189      // is given index 1 so toggles LED 6 every 400 ticks.\r
 190      for( uxIndex = 0; uxIndex < 2; uxIndex++ )\r
 191      {\r
 192          xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex );\r
 193      }\r
 194  }\r
 195    </pre>\r
 196  * \defgroup xCoRoutineCreate xCoRoutineCreate\r
 197  * \ingroup Tasks\r
 198  */\r
 199 BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, UBaseType_t uxPriority, UBaseType_t uxIndex );\r
 200 \r
 201 \r
 202 /**\r
 203  * croutine. h\r
 204  *<pre>\r
 205  void vCoRoutineSchedule( void );</pre>\r
 206  *\r
 207  * Run a co-routine.\r
 208  *\r
 209  * vCoRoutineSchedule() executes the highest priority co-routine that is able\r
 210  * to run.  The co-routine will execute until it either blocks, yields or is\r
 211  * preempted by a task.  Co-routines execute cooperatively so one\r
 212  * co-routine cannot be preempted by another, but can be preempted by a task.\r
 213  *\r
 214  * If an application comprises of both tasks and co-routines then\r
 215  * vCoRoutineSchedule should be called from the idle task (in an idle task\r
 216  * hook).\r
 217  *\r
 218  * Example usage:\r
 219    <pre>\r
 220  // This idle task hook will schedule a co-routine each time it is called.\r
 221  // The rest of the idle task will execute between co-routine calls.\r
 222  void vApplicationIdleHook( void )\r
 223  {\r
 224         vCoRoutineSchedule();\r
 225  }\r
 226 \r
 227  // Alternatively, if you do not require any other part of the idle task to\r
 228  // execute, the idle task hook can call vCoRoutineScheduler() within an\r
 229  // infinite loop.\r
 230  void vApplicationIdleHook( void )\r
 231  {\r
 232     for( ;; )\r
 233     {\r
 234         vCoRoutineSchedule();\r
 235     }\r
 236  }\r
 237  </pre>\r
 238  * \defgroup vCoRoutineSchedule vCoRoutineSchedule\r
 239  * \ingroup Tasks\r
 240  */\r
 241 void vCoRoutineSchedule( void );\r
 242 \r
 243 /**\r
 244  * croutine. h\r
 245  * <pre>\r
 246  crSTART( CoRoutineHandle_t xHandle );</pre>\r
 247  *\r
 248  * This macro MUST always be called at the start of a co-routine function.\r
 249  *\r
 250  * Example usage:\r
 251    <pre>\r
 252  // Co-routine to be created.\r
 253  void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 254  {\r
 255  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 256  static int32_t ulAVariable;\r
 257 \r
 258      // Must start every co-routine with a call to crSTART();\r
 259      crSTART( xHandle );\r
 260 \r
 261      for( ;; )\r
 262      {\r
 263           // Co-routine functionality goes here.\r
 264      }\r
 265 \r
 266      // Must end every co-routine with a call to crEND();\r
 267      crEND();\r
 268  }</pre>\r
 269  * \defgroup crSTART crSTART\r
 270  * \ingroup Tasks\r
 271  */\r
 272 #define crSTART( pxCRCB ) switch( ( ( CRCB_t * )( pxCRCB ) )->uxState ) { case 0:\r
 273 \r
 274 /**\r
 275  * croutine. h\r
 276  * <pre>\r
 277  crEND();</pre>\r
 278  *\r
 279  * This macro MUST always be called at the end of a co-routine function.\r
 280  *\r
 281  * Example usage:\r
 282    <pre>\r
 283  // Co-routine to be created.\r
 284  void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 285  {\r
 286  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 287  static int32_t ulAVariable;\r
 288 \r
 289      // Must start every co-routine with a call to crSTART();\r
 290      crSTART( xHandle );\r
 291 \r
 292      for( ;; )\r
 293      {\r
 294           // Co-routine functionality goes here.\r
 295      }\r
 296 \r
 297      // Must end every co-routine with a call to crEND();\r
 298      crEND();\r
 299  }</pre>\r
 300  * \defgroup crSTART crSTART\r
 301  * \ingroup Tasks\r
 302  */\r
 303 #define crEND() }\r
 304 \r
 305 /*\r
 306  * These macros are intended for internal use by the co-routine implementation\r
 307  * only.  The macros should not be used directly by application writers.\r
 308  */\r
 309 #define crSET_STATE0( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = (__LINE__ * 2); return; case (__LINE__ * 2):\r
 310 #define crSET_STATE1( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1):\r
 311 \r
 312 /**\r
 313  * croutine. h\r
 314  *<pre>\r
 315  crDELAY( CoRoutineHandle_t xHandle, TickType_t xTicksToDelay );</pre>\r
 316  *\r
 317  * Delay a co-routine for a fixed period of time.\r
 318  *\r
 319  * crDELAY can only be called from the co-routine function itself - not\r
 320  * from within a function called by the co-routine function.  This is because\r
 321  * co-routines do not maintain their own stack.\r
 322  *\r
 323  * @param xHandle The handle of the co-routine to delay.  This is the xHandle\r
 324  * parameter of the co-routine function.\r
 325  *\r
 326  * @param xTickToDelay The number of ticks that the co-routine should delay\r
 327  * for.  The actual amount of time this equates to is defined by\r
 328  * configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant portTICK_PERIOD_MS\r
 329  * can be used to convert ticks to milliseconds.\r
 330  *\r
 331  * Example usage:\r
 332    <pre>\r
 333  // Co-routine to be created.\r
 334  void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 335  {\r
 336  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 337  // This may not be necessary for const variables.\r
 338  // We are to delay for 200ms.\r
 339  static const xTickType xDelayTime = 200 / portTICK_PERIOD_MS;\r
 340 \r
 341      // Must start every co-routine with a call to crSTART();\r
 342      crSTART( xHandle );\r
 343 \r
 344      for( ;; )\r
 345      {\r
 346         // Delay for 200ms.\r
 347         crDELAY( xHandle, xDelayTime );\r
 348 \r
 349         // Do something here.\r
 350      }\r
 351 \r
 352      // Must end every co-routine with a call to crEND();\r
 353      crEND();\r
 354  }</pre>\r
 355  * \defgroup crDELAY crDELAY\r
 356  * \ingroup Tasks\r
 357  */\r
 358 #define crDELAY( xHandle, xTicksToDelay )                                                                                               \\r
 359         if( ( xTicksToDelay ) > 0 )                                                                                                                     \\r
 360         {                                                                                                                                                                       \\r
 361                 vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL );                                                  \\r
 362         }                                                                                                                                                                       \\r
 363         crSET_STATE0( ( xHandle ) );\r
 364 \r
 365 /**\r
 366  * <pre>\r
 367  crQUEUE_SEND(\r
 368                   CoRoutineHandle_t xHandle,\r
 369                   QueueHandle_t pxQueue,\r
 370                   void *pvItemToQueue,\r
 371                   TickType_t xTicksToWait,\r
 372                   BaseType_t *pxResult\r
 373              )</pre>\r
 374  *\r
 375  * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine\r
 376  * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.\r
 377  *\r
 378  * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas\r
 379  * xQueueSend() and xQueueReceive() can only be used from tasks.\r
 380  *\r
 381  * crQUEUE_SEND can only be called from the co-routine function itself - not\r
 382  * from within a function called by the co-routine function.  This is because\r
 383  * co-routines do not maintain their own stack.\r
 384  *\r
 385  * See the co-routine section of the WEB documentation for information on\r
 386  * passing data between tasks and co-routines and between ISR's and\r
 387  * co-routines.\r
 388  *\r
 389  * @param xHandle The handle of the calling co-routine.  This is the xHandle\r
 390  * parameter of the co-routine function.\r
 391  *\r
 392  * @param pxQueue The handle of the queue on which the data will be posted.\r
 393  * The handle is obtained as the return value when the queue is created using\r
 394  * the xQueueCreate() API function.\r
 395  *\r
 396  * @param pvItemToQueue A pointer to the data being posted onto the queue.\r
 397  * The number of bytes of each queued item is specified when the queue is\r
 398  * created.  This number of bytes is copied from pvItemToQueue into the queue\r
 399  * itself.\r
 400  *\r
 401  * @param xTickToDelay The number of ticks that the co-routine should block\r
 402  * to wait for space to become available on the queue, should space not be\r
 403  * available immediately. The actual amount of time this equates to is defined\r
 404  * by configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant\r
 405  * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see example\r
 406  * below).\r
 407  *\r
 408  * @param pxResult The variable pointed to by pxResult will be set to pdPASS if\r
 409  * data was successfully posted onto the queue, otherwise it will be set to an\r
 410  * error defined within ProjDefs.h.\r
 411  *\r
 412  * Example usage:\r
 413    <pre>\r
 414  // Co-routine function that blocks for a fixed period then posts a number onto\r
 415  // a queue.\r
 416  static void prvCoRoutineFlashTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 417  {\r
 418  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 419  static BaseType_t xNumberToPost = 0;\r
 420  static BaseType_t xResult;\r
 421 \r
 422     // Co-routines must begin with a call to crSTART().\r
 423     crSTART( xHandle );\r
 424 \r
 425     for( ;; )\r
 426     {\r
 427         // This assumes the queue has already been created.\r
 428         crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult );\r
 429 \r
 430         if( xResult != pdPASS )\r
 431         {\r
 432             // The message was not posted!\r
 433         }\r
 434 \r
 435         // Increment the number to be posted onto the queue.\r
 436         xNumberToPost++;\r
 437 \r
 438         // Delay for 100 ticks.\r
 439         crDELAY( xHandle, 100 );\r
 440     }\r
 441 \r
 442     // Co-routines must end with a call to crEND().\r
 443     crEND();\r
 444  }</pre>\r
 445  * \defgroup crQUEUE_SEND crQUEUE_SEND\r
 446  * \ingroup Tasks\r
 447  */\r
 448 #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult )                 \\r
 449 {                                                                                                                                                                               \\r
 450         *( pxResult ) = xQueueCRSend( ( pxQueue) , ( pvItemToQueue) , ( xTicksToWait ) );       \\r
 451         if( *( pxResult ) == errQUEUE_BLOCKED )                                                                                         \\r
 452         {                                                                                                                                                                       \\r
 453                 crSET_STATE0( ( xHandle ) );                                                                                                    \\r
 454                 *pxResult = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), 0 );                                  \\r
 455         }                                                                                                                                                                       \\r
 456         if( *pxResult == errQUEUE_YIELD )                                                                                                       \\r
 457         {                                                                                                                                                                       \\r
 458                 crSET_STATE1( ( xHandle ) );                                                                                                    \\r
 459                 *pxResult = pdPASS;                                                                                                                             \\r
 460         }                                                                                                                                                                       \\r
 461 }\r
 462 \r
 463 /**\r
 464  * croutine. h\r
 465  * <pre>\r
 466   crQUEUE_RECEIVE(\r
 467                      CoRoutineHandle_t xHandle,\r
 468                      QueueHandle_t pxQueue,\r
 469                      void *pvBuffer,\r
 470                      TickType_t xTicksToWait,\r
 471                      BaseType_t *pxResult\r
 472                  )</pre>\r
 473  *\r
 474  * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine\r
 475  * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.\r
 476  *\r
 477  * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas\r
 478  * xQueueSend() and xQueueReceive() can only be used from tasks.\r
 479  *\r
 480  * crQUEUE_RECEIVE can only be called from the co-routine function itself - not\r
 481  * from within a function called by the co-routine function.  This is because\r
 482  * co-routines do not maintain their own stack.\r
 483  *\r
 484  * See the co-routine section of the WEB documentation for information on\r
 485  * passing data between tasks and co-routines and between ISR's and\r
 486  * co-routines.\r
 487  *\r
 488  * @param xHandle The handle of the calling co-routine.  This is the xHandle\r
 489  * parameter of the co-routine function.\r
 490  *\r
 491  * @param pxQueue The handle of the queue from which the data will be received.\r
 492  * The handle is obtained as the return value when the queue is created using\r
 493  * the xQueueCreate() API function.\r
 494  *\r
 495  * @param pvBuffer The buffer into which the received item is to be copied.\r
 496  * The number of bytes of each queued item is specified when the queue is\r
 497  * created.  This number of bytes is copied into pvBuffer.\r
 498  *\r
 499  * @param xTickToDelay The number of ticks that the co-routine should block\r
 500  * to wait for data to become available from the queue, should data not be\r
 501  * available immediately. The actual amount of time this equates to is defined\r
 502  * by configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant\r
 503  * portTICK_PERIOD_MS can be used to convert ticks to milliseconds (see the\r
 504  * crQUEUE_SEND example).\r
 505  *\r
 506  * @param pxResult The variable pointed to by pxResult will be set to pdPASS if\r
 507  * data was successfully retrieved from the queue, otherwise it will be set to\r
 508  * an error code as defined within ProjDefs.h.\r
 509  *\r
 510  * Example usage:\r
 511  <pre>\r
 512  // A co-routine receives the number of an LED to flash from a queue.  It\r
 513  // blocks on the queue until the number is received.\r
 514  static void prvCoRoutineFlashWorkTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 515  {\r
 516  // Variables in co-routines must be declared static if they must maintain value across a blocking call.\r
 517  static BaseType_t xResult;\r
 518  static UBaseType_t uxLEDToFlash;\r
 519 \r
 520     // All co-routines must start with a call to crSTART().\r
 521     crSTART( xHandle );\r
 522 \r
 523     for( ;; )\r
 524     {\r
 525         // Wait for data to become available on the queue.\r
 526         crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );\r
 527 \r
 528         if( xResult == pdPASS )\r
 529         {\r
 530             // We received the LED to flash - flash it!\r
 531             vParTestToggleLED( uxLEDToFlash );\r
 532         }\r
 533     }\r
 534 \r
 535     crEND();\r
 536  }</pre>\r
 537  * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE\r
 538  * \ingroup Tasks\r
 539  */\r
 540 #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult )                   \\r
 541 {                                                                                                                                                                               \\r
 542         *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), ( xTicksToWait ) );         \\r
 543         if( *( pxResult ) == errQUEUE_BLOCKED )                                                                                         \\r
 544         {                                                                                                                                                                       \\r
 545                 crSET_STATE0( ( xHandle ) );                                                                                                    \\r
 546                 *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), 0 );                                \\r
 547         }                                                                                                                                                                       \\r
 548         if( *( pxResult ) == errQUEUE_YIELD )                                                                                           \\r
 549         {                                                                                                                                                                       \\r
 550                 crSET_STATE1( ( xHandle ) );                                                                                                    \\r
 551                 *( pxResult ) = pdPASS;                                                                                                                 \\r
 552         }                                                                                                                                                                       \\r
 553 }\r
 554 \r
 555 /**\r
 556  * croutine. h\r
 557  * <pre>\r
 558   crQUEUE_SEND_FROM_ISR(\r
 559                             QueueHandle_t pxQueue,\r
 560                             void *pvItemToQueue,\r
 561                             BaseType_t xCoRoutinePreviouslyWoken\r
 562                        )</pre>\r
 563  *\r
 564  * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the\r
 565  * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()\r
 566  * functions used by tasks.\r
 567  *\r
 568  * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to\r
 569  * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and\r
 570  * xQueueReceiveFromISR() can only be used to pass data between a task and and\r
 571  * ISR.\r
 572  *\r
 573  * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue\r
 574  * that is being used from within a co-routine.\r
 575  *\r
 576  * See the co-routine section of the WEB documentation for information on\r
 577  * passing data between tasks and co-routines and between ISR's and\r
 578  * co-routines.\r
 579  *\r
 580  * @param xQueue The handle to the queue on which the item is to be posted.\r
 581  *\r
 582  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 583  * queue.  The size of the items the queue will hold was defined when the\r
 584  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 585  * into the queue storage area.\r
 586  *\r
 587  * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto\r
 588  * the same queue multiple times from a single interrupt.  The first call\r
 589  * should always pass in pdFALSE.  Subsequent calls should pass in\r
 590  * the value returned from the previous call.\r
 591  *\r
 592  * @return pdTRUE if a co-routine was woken by posting onto the queue.  This is\r
 593  * used by the ISR to determine if a context switch may be required following\r
 594  * the ISR.\r
 595  *\r
 596  * Example usage:\r
 597  <pre>\r
 598  // A co-routine that blocks on a queue waiting for characters to be received.\r
 599  static void vReceivingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 600  {\r
 601  char cRxedChar;\r
 602  BaseType_t xResult;\r
 603 \r
 604      // All co-routines must start with a call to crSTART().\r
 605      crSTART( xHandle );\r
 606 \r
 607      for( ;; )\r
 608      {\r
 609          // Wait for data to become available on the queue.  This assumes the\r
 610          // queue xCommsRxQueue has already been created!\r
 611          crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );\r
 612 \r
 613          // Was a character received?\r
 614          if( xResult == pdPASS )\r
 615          {\r
 616              // Process the character here.\r
 617          }\r
 618      }\r
 619 \r
 620      // All co-routines must end with a call to crEND().\r
 621      crEND();\r
 622  }\r
 623 \r
 624  // An ISR that uses a queue to send characters received on a serial port to\r
 625  // a co-routine.\r
 626  void vUART_ISR( void )\r
 627  {\r
 628  char cRxedChar;\r
 629  BaseType_t xCRWokenByPost = pdFALSE;\r
 630 \r
 631      // We loop around reading characters until there are none left in the UART.\r
 632      while( UART_RX_REG_NOT_EMPTY() )\r
 633      {\r
 634          // Obtain the character from the UART.\r
 635          cRxedChar = UART_RX_REG;\r
 636 \r
 637          // Post the character onto a queue.  xCRWokenByPost will be pdFALSE\r
 638          // the first time around the loop.  If the post causes a co-routine\r
 639          // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE.\r
 640          // In this manner we can ensure that if more than one co-routine is\r
 641          // blocked on the queue only one is woken by this ISR no matter how\r
 642          // many characters are posted to the queue.\r
 643          xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost );\r
 644      }\r
 645  }</pre>\r
 646  * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR\r
 647  * \ingroup Tasks\r
 648  */\r
 649 #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) )\r
 650 \r
 651 \r
 652 /**\r
 653  * croutine. h\r
 654  * <pre>\r
 655   crQUEUE_SEND_FROM_ISR(\r
 656                             QueueHandle_t pxQueue,\r
 657                             void *pvBuffer,\r
 658                             BaseType_t * pxCoRoutineWoken\r
 659                        )</pre>\r
 660  *\r
 661  * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the\r
 662  * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()\r
 663  * functions used by tasks.\r
 664  *\r
 665  * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to\r
 666  * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and\r
 667  * xQueueReceiveFromISR() can only be used to pass data between a task and and\r
 668  * ISR.\r
 669  *\r
 670  * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data\r
 671  * from a queue that is being used from within a co-routine (a co-routine\r
 672  * posted to the queue).\r
 673  *\r
 674  * See the co-routine section of the WEB documentation for information on\r
 675  * passing data between tasks and co-routines and between ISR's and\r
 676  * co-routines.\r
 677  *\r
 678  * @param xQueue The handle to the queue on which the item is to be posted.\r
 679  *\r
 680  * @param pvBuffer A pointer to a buffer into which the received item will be\r
 681  * placed.  The size of the items the queue will hold was defined when the\r
 682  * queue was created, so this many bytes will be copied from the queue into\r
 683  * pvBuffer.\r
 684  *\r
 685  * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become\r
 686  * available on the queue.  If crQUEUE_RECEIVE_FROM_ISR causes such a\r
 687  * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise\r
 688  * *pxCoRoutineWoken will remain unchanged.\r
 689  *\r
 690  * @return pdTRUE an item was successfully received from the queue, otherwise\r
 691  * pdFALSE.\r
 692  *\r
 693  * Example usage:\r
 694  <pre>\r
 695  // A co-routine that posts a character to a queue then blocks for a fixed\r
 696  // period.  The character is incremented each time.\r
 697  static void vSendingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )\r
 698  {\r
 699  // cChar holds its value while this co-routine is blocked and must therefore\r
 700  // be declared static.\r
 701  static char cCharToTx = 'a';\r
 702  BaseType_t xResult;\r
 703 \r
 704      // All co-routines must start with a call to crSTART().\r
 705      crSTART( xHandle );\r
 706 \r
 707      for( ;; )\r
 708      {\r
 709          // Send the next character to the queue.\r
 710          crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult );\r
 711 \r
 712          if( xResult == pdPASS )\r
 713          {\r
 714              // The character was successfully posted to the queue.\r
 715          }\r
 716                  else\r
 717                  {\r
 718                         // Could not post the character to the queue.\r
 719                  }\r
 720 \r
 721          // Enable the UART Tx interrupt to cause an interrupt in this\r
 722                  // hypothetical UART.  The interrupt will obtain the character\r
 723                  // from the queue and send it.\r
 724                  ENABLE_RX_INTERRUPT();\r
 725 \r
 726                  // Increment to the next character then block for a fixed period.\r
 727                  // cCharToTx will maintain its value across the delay as it is\r
 728                  // declared static.\r
 729                  cCharToTx++;\r
 730                  if( cCharToTx > 'x' )\r
 731                  {\r
 732                         cCharToTx = 'a';\r
 733                  }\r
 734                  crDELAY( 100 );\r
 735      }\r
 736 \r
 737      // All co-routines must end with a call to crEND().\r
 738      crEND();\r
 739  }\r
 740 \r
 741  // An ISR that uses a queue to receive characters to send on a UART.\r
 742  void vUART_ISR( void )\r
 743  {\r
 744  char cCharToTx;\r
 745  BaseType_t xCRWokenByPost = pdFALSE;\r
 746 \r
 747      while( UART_TX_REG_EMPTY() )\r
 748      {\r
 749          // Are there any characters in the queue waiting to be sent?\r
 750                  // xCRWokenByPost will automatically be set to pdTRUE if a co-routine\r
 751                  // is woken by the post - ensuring that only a single co-routine is\r
 752                  // woken no matter how many times we go around this loop.\r
 753          if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) )\r
 754                  {\r
 755                          SEND_CHARACTER( cCharToTx );\r
 756                  }\r
 757      }\r
 758  }</pre>\r
 759  * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR\r
 760  * \ingroup Tasks\r
 761  */\r
 762 #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( ( pxQueue ), ( pvBuffer ), ( pxCoRoutineWoken ) )\r
 763 \r
 764 /*\r
 765  * This function is intended for internal use by the co-routine macros only.\r
 766  * The macro nature of the co-routine implementation requires that the\r
 767  * prototype appears here.  The function should not be used by application\r
 768  * writers.\r
 769  *\r
 770  * Removes the current co-routine from its ready list and places it in the\r
 771  * appropriate delayed list.\r
 772  */\r
 773 void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay, List_t *pxEventList );\r
 774 \r
 775 /*\r
 776  * This function is intended for internal use by the queue implementation only.\r
 777  * The function should not be used by application writers.\r
 778  *\r
 779  * Removes the highest priority co-routine from the event list and places it in\r
 780  * the pending ready list.\r
 781  */\r
 782 BaseType_t xCoRoutineRemoveFromEventList( const List_t *pxEventList );\r
 783 \r
 784 #ifdef __cplusplus\r
 785 }\r
 786 #endif\r
 787 \r
 788 #endif /* CO_ROUTINE_H */\r