begriffs open source - cmsis-freertos/blob - Source/include/croutine.h

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