rpp/lib/os/7.0.2_tms570/include/os/croutine.h

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