FreeRTOS Real Time Operating System, Modified from Kenji Arai's initial port. See freertos.org for full documentation.

Fork of FreeRTOS_on_mbed_v1 by Kenji Arai

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers croutine.h Source File

croutine.h

00001 /*
00002     FreeRTOS V6.0.3 - Copyright (C) 2010 Real Time Engineers Ltd.
00003 
00004     ***************************************************************************
00005     *                                                                         *
00006     * If you are:                                                             *
00007     *                                                                         *
00008     *    + New to FreeRTOS,                                                   *
00009     *    + Wanting to learn FreeRTOS or multitasking in general quickly       *
00010     *    + Looking for basic training,                                        *
00011     *    + Wanting to improve your FreeRTOS skills and productivity           *
00012     *                                                                         *
00013     * then take a look at the FreeRTOS eBook                                  *
00014     *                                                                         *
00015     *        "Using the FreeRTOS Real Time Kernel - a Practical Guide"        *
00016     *                  http://www.FreeRTOS.org/Documentation                  *
00017     *                                                                         *
00018     * A pdf reference manual is also available.  Both are usually delivered   *
00019     * to your inbox within 20 minutes to two hours when purchased between 8am *
00020     * and 8pm GMT (although please allow up to 24 hours in case of            *
00021     * exceptional circumstances).  Thank you for your support!                *
00022     *                                                                         *
00023     ***************************************************************************
00024 
00025     This file is part of the FreeRTOS distribution.
00026 
00027     FreeRTOS is free software; you can redistribute it and/or modify it under
00028     the terms of the GNU General Public License (version 2) as published by the
00029     Free Software Foundation AND MODIFIED BY the FreeRTOS exception.
00030     ***NOTE*** The exception to the GPL is included to allow you to distribute
00031     a combined work that includes FreeRTOS without being obliged to provide the
00032     source code for proprietary components outside of the FreeRTOS kernel.
00033     FreeRTOS is distributed in the hope that it will be useful, but WITHOUT
00034     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00035     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
00036     more details. You should have received a copy of the GNU General Public 
00037     License and the FreeRTOS license exception along with FreeRTOS; if not it 
00038     can be viewed here: http://www.freertos.org/a00114.html and also obtained 
00039     by writing to Richard Barry, contact details for whom are available on the
00040     FreeRTOS WEB site.
00041 
00042     1 tab == 4 spaces!
00043 
00044     http://www.FreeRTOS.org - Documentation, latest information, license and
00045     contact details.
00046 
00047     http://www.SafeRTOS.com - A version that is certified for use in safety
00048     critical systems.
00049 
00050     http://www.OpenRTOS.com - Commercial support, development, porting,
00051     licensing and training services.
00052 */
00053 
00054 #ifndef INC_FREERTOS_H
00055     #error "#include FreeRTOS.h" must appear in source files before "#include croutine.h"
00056 #endif
00057 
00058 
00059 
00060 
00061 #ifndef CO_ROUTINE_H
00062 #define CO_ROUTINE_H
00063 
00064 #include "list.h"
00065 
00066 #ifdef __cplusplus
00067 extern "C" {
00068 #endif
00069 
00070 /* Used to hide the implementation of the co-routine control block.  The
00071 control block structure however has to be included in the header due to
00072 the macro implementation of the co-routine functionality. */
00073 typedef void * xCoRoutineHandle;
00074 
00075 /* Defines the prototype to which co-routine functions must conform. */
00076 typedef void (*crCOROUTINE_CODE)( xCoRoutineHandle, unsigned portBASE_TYPE );
00077 
00078 typedef struct corCoRoutineControlBlock
00079 {
00080     crCOROUTINE_CODE         pxCoRoutineFunction;
00081     xListItem                xGenericListItem;    /*< List item used to place the CRCB in ready and blocked queues. */
00082     xListItem                xEventListItem;        /*< List item used to place the CRCB in event lists. */
00083     unsigned portBASE_TYPE     uxPriority;            /*< The priority of the co-routine in relation to other co-routines. */
00084     unsigned portBASE_TYPE     uxIndex;            /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */
00085     unsigned short         uxState;            /*< Used internally by the co-routine implementation. */
00086 } corCRCB; /* Co-routine control block.  Note must be identical in size down to uxPriority with tskTCB. */
00087 
00088 /**
00089  * croutine. h
00090  *<pre>
00091  portBASE_TYPE xCoRoutineCreate(
00092                                  crCOROUTINE_CODE pxCoRoutineCode,
00093                                  unsigned portBASE_TYPE uxPriority,
00094                                  unsigned portBASE_TYPE uxIndex
00095                                );</pre>
00096  *
00097  * Create a new co-routine and add it to the list of co-routines that are
00098  * ready to run.
00099  *
00100  * @param pxCoRoutineCode Pointer to the co-routine function.  Co-routine
00101  * functions require special syntax - see the co-routine section of the WEB
00102  * documentation for more information.
00103  *
00104  * @param uxPriority The priority with respect to other co-routines at which
00105  *  the co-routine will run.
00106  *
00107  * @param uxIndex Used to distinguish between different co-routines that
00108  * execute the same function.  See the example below and the co-routine section
00109  * of the WEB documentation for further information.
00110  *
00111  * @return pdPASS if the co-routine was successfully created and added to a ready
00112  * list, otherwise an error code defined with ProjDefs.h.
00113  *
00114  * Example usage:
00115    <pre>
00116  // Co-routine to be created.
00117  void vFlashCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00118  {
00119  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00120  // This may not be necessary for const variables.
00121  static const char cLedToFlash[ 2 ] = { 5, 6 };
00122  static const portTickType xTimeToDelay[ 2 ] = { 200, 400 };
00123 
00124      // Must start every co-routine with a call to crSTART();
00125      crSTART( xHandle );
00126 
00127      for( ;; )
00128      {
00129          // This co-routine just delays for a fixed period, then toggles
00130          // an LED.  Two co-routines are created using this function, so
00131          // the uxIndex parameter is used to tell the co-routine which
00132          // LED to flash and how long to delay.  This assumes xQueue has
00133          // already been created.
00134          vParTestToggleLED( cLedToFlash[ uxIndex ] );
00135          crDELAY( xHandle, uxFlashRates[ uxIndex ] );
00136      }
00137 
00138      // Must end every co-routine with a call to crEND();
00139      crEND();
00140  }
00141 
00142  // Function that creates two co-routines.
00143  void vOtherFunction( void )
00144  {
00145  unsigned char ucParameterToPass;
00146  xTaskHandle xHandle;
00147         
00148      // Create two co-routines at priority 0.  The first is given index 0
00149      // so (from the code above) toggles LED 5 every 200 ticks.  The second
00150      // is given index 1 so toggles LED 6 every 400 ticks.
00151      for( uxIndex = 0; uxIndex < 2; uxIndex++ )
00152      {
00153          xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex );
00154      }
00155  }
00156    </pre>
00157  * \defgroup xCoRoutineCreate xCoRoutineCreate
00158  * \ingroup Tasks
00159  */
00160 signed portBASE_TYPE xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, unsigned portBASE_TYPE uxPriority, unsigned portBASE_TYPE uxIndex );
00161 
00162 
00163 /**
00164  * croutine. h
00165  *<pre>
00166  void vCoRoutineSchedule( void );</pre>
00167  *
00168  * Run a co-routine.
00169  *
00170  * vCoRoutineSchedule() executes the highest priority co-routine that is able
00171  * to run.  The co-routine will execute until it either blocks, yields or is
00172  * preempted by a task.  Co-routines execute cooperatively so one
00173  * co-routine cannot be preempted by another, but can be preempted by a task.
00174  *
00175  * If an application comprises of both tasks and co-routines then
00176  * vCoRoutineSchedule should be called from the idle task (in an idle task
00177  * hook).
00178  *
00179  * Example usage:
00180    <pre>
00181  // This idle task hook will schedule a co-routine each time it is called.
00182  // The rest of the idle task will execute between co-routine calls.
00183  void vApplicationIdleHook( void )
00184  {
00185     vCoRoutineSchedule();
00186  }
00187 
00188  // Alternatively, if you do not require any other part of the idle task to
00189  // execute, the idle task hook can call vCoRoutineScheduler() within an
00190  // infinite loop.
00191  void vApplicationIdleHook( void )
00192  {
00193     for( ;; )
00194     {
00195         vCoRoutineSchedule();
00196     }
00197  }
00198  </pre>
00199  * \defgroup vCoRoutineSchedule vCoRoutineSchedule
00200  * \ingroup Tasks
00201  */
00202 void vCoRoutineSchedule( void );
00203 
00204 /**
00205  * croutine. h
00206  * <pre>
00207  crSTART( xCoRoutineHandle xHandle );</pre>
00208  *
00209  * This macro MUST always be called at the start of a co-routine function.
00210  *
00211  * Example usage:
00212    <pre>
00213  // Co-routine to be created.
00214  void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00215  {
00216  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00217  static long ulAVariable;
00218 
00219      // Must start every co-routine with a call to crSTART();
00220      crSTART( xHandle );
00221 
00222      for( ;; )
00223      {
00224           // Co-routine functionality goes here.
00225      }
00226 
00227      // Must end every co-routine with a call to crEND();
00228      crEND();
00229  }</pre>
00230  * \defgroup crSTART crSTART
00231  * \ingroup Tasks
00232  */
00233 #define crSTART( pxCRCB ) switch( ( ( corCRCB * )pxCRCB )->uxState ) { case 0:
00234 
00235 /**
00236  * croutine. h
00237  * <pre>
00238  crEND();</pre>
00239  *
00240  * This macro MUST always be called at the end of a co-routine function.
00241  *
00242  * Example usage:
00243    <pre>
00244  // Co-routine to be created.
00245  void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00246  {
00247  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00248  static long ulAVariable;
00249 
00250      // Must start every co-routine with a call to crSTART();
00251      crSTART( xHandle );
00252 
00253      for( ;; )
00254      {
00255           // Co-routine functionality goes here.
00256      }
00257 
00258      // Must end every co-routine with a call to crEND();
00259      crEND();
00260  }</pre>
00261  * \defgroup crSTART crSTART
00262  * \ingroup Tasks
00263  */
00264 #define crEND() }
00265 
00266 /*
00267  * These macros are intended for internal use by the co-routine implementation
00268  * only.  The macros should not be used directly by application writers.
00269  */
00270 #define crSET_STATE0( xHandle ) ( ( corCRCB * )xHandle)->uxState = (__LINE__ * 2); return; case (__LINE__ * 2):
00271 #define crSET_STATE1( xHandle ) ( ( corCRCB * )xHandle)->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1):
00272 
00273 /**
00274  * croutine. h
00275  *<pre>
00276  crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay );</pre>
00277  *
00278  * Delay a co-routine for a fixed period of time.
00279  *
00280  * crDELAY can only be called from the co-routine function itself - not
00281  * from within a function called by the co-routine function.  This is because
00282  * co-routines do not maintain their own stack.
00283  *
00284  * @param xHandle The handle of the co-routine to delay.  This is the xHandle
00285  * parameter of the co-routine function.
00286  *
00287  * @param xTickToDelay The number of ticks that the co-routine should delay
00288  * for.  The actual amount of time this equates to is defined by
00289  * configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant portTICK_RATE_MS
00290  * can be used to convert ticks to milliseconds.
00291  *
00292  * Example usage:
00293    <pre>
00294  // Co-routine to be created.
00295  void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00296  {
00297  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00298  // This may not be necessary for const variables.
00299  // We are to delay for 200ms.
00300  static const xTickType xDelayTime = 200 / portTICK_RATE_MS;
00301 
00302      // Must start every co-routine with a call to crSTART();
00303      crSTART( xHandle );
00304 
00305      for( ;; )
00306      {
00307         // Delay for 200ms.
00308         crDELAY( xHandle, xDelayTime );
00309 
00310         // Do something here.
00311      }
00312 
00313      // Must end every co-routine with a call to crEND();
00314      crEND();
00315  }</pre>
00316  * \defgroup crDELAY crDELAY
00317  * \ingroup Tasks
00318  */
00319 #define crDELAY( xHandle, xTicksToDelay )                                                \
00320     if( xTicksToDelay > 0 )                                                                \
00321     {                                                                                    \
00322         vCoRoutineAddToDelayedList( xTicksToDelay, NULL );                                \
00323     }                                                                                    \
00324     crSET_STATE0( xHandle );
00325 
00326 /**
00327  * <pre>
00328  crQUEUE_SEND(
00329                   xCoRoutineHandle xHandle,
00330                   xQueueHandle pxQueue,
00331                   void *pvItemToQueue,
00332                   portTickType xTicksToWait,
00333                   portBASE_TYPE *pxResult
00334              )</pre>
00335  *
00336  * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
00337  * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
00338  *
00339  * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
00340  * xQueueSend() and xQueueReceive() can only be used from tasks.
00341  *
00342  * crQUEUE_SEND can only be called from the co-routine function itself - not
00343  * from within a function called by the co-routine function.  This is because
00344  * co-routines do not maintain their own stack.
00345  *
00346  * See the co-routine section of the WEB documentation for information on
00347  * passing data between tasks and co-routines and between ISR's and
00348  * co-routines.
00349  *
00350  * @param xHandle The handle of the calling co-routine.  This is the xHandle
00351  * parameter of the co-routine function.
00352  *
00353  * @param pxQueue The handle of the queue on which the data will be posted.
00354  * The handle is obtained as the return value when the queue is created using
00355  * the xQueueCreate() API function.
00356  *
00357  * @param pvItemToQueue A pointer to the data being posted onto the queue.
00358  * The number of bytes of each queued item is specified when the queue is
00359  * created.  This number of bytes is copied from pvItemToQueue into the queue
00360  * itself.
00361  *
00362  * @param xTickToDelay The number of ticks that the co-routine should block
00363  * to wait for space to become available on the queue, should space not be
00364  * available immediately. The actual amount of time this equates to is defined
00365  * by configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant
00366  * portTICK_RATE_MS can be used to convert ticks to milliseconds (see example
00367  * below).
00368  *
00369  * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
00370  * data was successfully posted onto the queue, otherwise it will be set to an
00371  * error defined within ProjDefs.h.
00372  *
00373  * Example usage:
00374    <pre>
00375  // Co-routine function that blocks for a fixed period then posts a number onto
00376  // a queue.
00377  static void prvCoRoutineFlashTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00378  {
00379  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00380  static portBASE_TYPE xNumberToPost = 0;
00381  static portBASE_TYPE xResult;
00382 
00383     // Co-routines must begin with a call to crSTART().
00384     crSTART( xHandle );
00385 
00386     for( ;; )
00387     {
00388         // This assumes the queue has already been created.
00389         crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult );
00390 
00391         if( xResult != pdPASS )
00392         {
00393             // The message was not posted!
00394         }
00395 
00396         // Increment the number to be posted onto the queue.
00397         xNumberToPost++;
00398 
00399         // Delay for 100 ticks.
00400         crDELAY( xHandle, 100 );
00401     }
00402 
00403     // Co-routines must end with a call to crEND().
00404     crEND();
00405  }</pre>
00406  * \defgroup crQUEUE_SEND crQUEUE_SEND
00407  * \ingroup Tasks
00408  */
00409 #define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult )            \
00410 {                                                                                        \
00411     *pxResult = xQueueCRSend( pxQueue, pvItemToQueue, xTicksToWait );                    \
00412     if( *pxResult == errQUEUE_BLOCKED )                                                    \
00413     {                                                                                    \
00414         crSET_STATE0( xHandle );                                                        \
00415         *pxResult = xQueueCRSend( pxQueue, pvItemToQueue, 0 );                            \
00416     }                                                                                    \
00417     if( *pxResult == errQUEUE_YIELD )                                                    \
00418     {                                                                                    \
00419         crSET_STATE1( xHandle );                                                        \
00420         *pxResult = pdPASS;                                                                \
00421     }                                                                                    \
00422 }
00423 
00424 /**
00425  * croutine. h
00426  * <pre>
00427   crQUEUE_RECEIVE(
00428                      xCoRoutineHandle xHandle,
00429                      xQueueHandle pxQueue,
00430                      void *pvBuffer,
00431                      portTickType xTicksToWait,
00432                      portBASE_TYPE *pxResult
00433                  )</pre>
00434  *
00435  * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine
00436  * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.
00437  *
00438  * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas
00439  * xQueueSend() and xQueueReceive() can only be used from tasks.
00440  *
00441  * crQUEUE_RECEIVE can only be called from the co-routine function itself - not
00442  * from within a function called by the co-routine function.  This is because
00443  * co-routines do not maintain their own stack.
00444  *
00445  * See the co-routine section of the WEB documentation for information on
00446  * passing data between tasks and co-routines and between ISR's and
00447  * co-routines.
00448  *
00449  * @param xHandle The handle of the calling co-routine.  This is the xHandle
00450  * parameter of the co-routine function.
00451  *
00452  * @param pxQueue The handle of the queue from which the data will be received.
00453  * The handle is obtained as the return value when the queue is created using
00454  * the xQueueCreate() API function.
00455  *
00456  * @param pvBuffer The buffer into which the received item is to be copied.
00457  * The number of bytes of each queued item is specified when the queue is
00458  * created.  This number of bytes is copied into pvBuffer.
00459  *
00460  * @param xTickToDelay The number of ticks that the co-routine should block
00461  * to wait for data to become available from the queue, should data not be
00462  * available immediately. The actual amount of time this equates to is defined
00463  * by configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant
00464  * portTICK_RATE_MS can be used to convert ticks to milliseconds (see the
00465  * crQUEUE_SEND example).
00466  *
00467  * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
00468  * data was successfully retrieved from the queue, otherwise it will be set to
00469  * an error code as defined within ProjDefs.h.
00470  *
00471  * Example usage:
00472  <pre>
00473  // A co-routine receives the number of an LED to flash from a queue.  It
00474  // blocks on the queue until the number is received.
00475  static void prvCoRoutineFlashWorkTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00476  {
00477  // Variables in co-routines must be declared static if they must maintain value across a blocking call.
00478  static portBASE_TYPE xResult;
00479  static unsigned portBASE_TYPE uxLEDToFlash;
00480 
00481     // All co-routines must start with a call to crSTART().
00482     crSTART( xHandle );
00483 
00484     for( ;; )
00485     {
00486         // Wait for data to become available on the queue.
00487         crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
00488 
00489         if( xResult == pdPASS )
00490         {
00491             // We received the LED to flash - flash it!
00492             vParTestToggleLED( uxLEDToFlash );
00493         }
00494     }
00495 
00496     crEND();
00497  }</pre>
00498  * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE
00499  * \ingroup Tasks
00500  */
00501 #define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult )            \
00502 {                                                                                        \
00503     *pxResult = xQueueCRReceive( pxQueue, pvBuffer, xTicksToWait );                        \
00504     if( *pxResult == errQUEUE_BLOCKED )                                                 \
00505     {                                                                                    \
00506         crSET_STATE0( xHandle );                                                        \
00507         *pxResult = xQueueCRReceive( pxQueue, pvBuffer, 0 );                            \
00508     }                                                                                    \
00509     if( *pxResult == errQUEUE_YIELD )                                                    \
00510     {                                                                                    \
00511         crSET_STATE1( xHandle );                                                        \
00512         *pxResult = pdPASS;                                                                \
00513     }                                                                                    \
00514 }
00515 
00516 /**
00517  * croutine. h
00518  * <pre>
00519   crQUEUE_SEND_FROM_ISR(
00520                             xQueueHandle pxQueue,
00521                             void *pvItemToQueue,
00522                             portBASE_TYPE xCoRoutinePreviouslyWoken
00523                        )</pre>
00524  *
00525  * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
00526  * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
00527  * functions used by tasks.
00528  *
00529  * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
00530  * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
00531  * xQueueReceiveFromISR() can only be used to pass data between a task and and
00532  * ISR.
00533  *
00534  * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue
00535  * that is being used from within a co-routine.
00536  *
00537  * See the co-routine section of the WEB documentation for information on
00538  * passing data between tasks and co-routines and between ISR's and
00539  * co-routines.
00540  *
00541  * @param xQueue The handle to the queue on which the item is to be posted.
00542  *
00543  * @param pvItemToQueue A pointer to the item that is to be placed on the
00544  * queue.  The size of the items the queue will hold was defined when the
00545  * queue was created, so this many bytes will be copied from pvItemToQueue
00546  * into the queue storage area.
00547  *
00548  * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto
00549  * the same queue multiple times from a single interrupt.  The first call
00550  * should always pass in pdFALSE.  Subsequent calls should pass in
00551  * the value returned from the previous call.
00552  *
00553  * @return pdTRUE if a co-routine was woken by posting onto the queue.  This is
00554  * used by the ISR to determine if a context switch may be required following
00555  * the ISR.
00556  *
00557  * Example usage:
00558  <pre>
00559  // A co-routine that blocks on a queue waiting for characters to be received.
00560  static void vReceivingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00561  {
00562  char cRxedChar;
00563  portBASE_TYPE xResult;
00564 
00565      // All co-routines must start with a call to crSTART().
00566      crSTART( xHandle );
00567 
00568      for( ;; )
00569      {
00570          // Wait for data to become available on the queue.  This assumes the
00571          // queue xCommsRxQueue has already been created!
00572          crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
00573 
00574          // Was a character received?
00575          if( xResult == pdPASS )
00576          {
00577              // Process the character here.
00578          }
00579      }
00580 
00581      // All co-routines must end with a call to crEND().
00582      crEND();
00583  }
00584 
00585  // An ISR that uses a queue to send characters received on a serial port to
00586  // a co-routine.
00587  void vUART_ISR( void )
00588  {
00589  char cRxedChar;
00590  portBASE_TYPE xCRWokenByPost = pdFALSE;
00591 
00592      // We loop around reading characters until there are none left in the UART.
00593      while( UART_RX_REG_NOT_EMPTY() )
00594      {
00595          // Obtain the character from the UART.
00596          cRxedChar = UART_RX_REG;
00597 
00598          // Post the character onto a queue.  xCRWokenByPost will be pdFALSE
00599          // the first time around the loop.  If the post causes a co-routine
00600          // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE.
00601          // In this manner we can ensure that if more than one co-routine is
00602          // blocked on the queue only one is woken by this ISR no matter how
00603          // many characters are posted to the queue.
00604          xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost );
00605      }
00606  }</pre>
00607  * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR
00608  * \ingroup Tasks
00609  */
00610 #define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken )
00611 
00612 
00613 /**
00614  * croutine. h
00615  * <pre>
00616   crQUEUE_SEND_FROM_ISR(
00617                             xQueueHandle pxQueue,
00618                             void *pvBuffer,
00619                             portBASE_TYPE * pxCoRoutineWoken
00620                        )</pre>
00621  *
00622  * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
00623  * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
00624  * functions used by tasks.
00625  *
00626  * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
00627  * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
00628  * xQueueReceiveFromISR() can only be used to pass data between a task and and
00629  * ISR.
00630  *
00631  * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data
00632  * from a queue that is being used from within a co-routine (a co-routine
00633  * posted to the queue).
00634  *
00635  * See the co-routine section of the WEB documentation for information on
00636  * passing data between tasks and co-routines and between ISR's and
00637  * co-routines.
00638  *
00639  * @param xQueue The handle to the queue on which the item is to be posted.
00640  *
00641  * @param pvBuffer A pointer to a buffer into which the received item will be
00642  * placed.  The size of the items the queue will hold was defined when the
00643  * queue was created, so this many bytes will be copied from the queue into
00644  * pvBuffer.
00645  *
00646  * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become
00647  * available on the queue.  If crQUEUE_RECEIVE_FROM_ISR causes such a
00648  * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise
00649  * *pxCoRoutineWoken will remain unchanged.
00650  *
00651  * @return pdTRUE an item was successfully received from the queue, otherwise
00652  * pdFALSE.
00653  *
00654  * Example usage:
00655  <pre>
00656  // A co-routine that posts a character to a queue then blocks for a fixed
00657  // period.  The character is incremented each time.
00658  static void vSendingCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )
00659  {
00660  // cChar holds its value while this co-routine is blocked and must therefore
00661  // be declared static.
00662  static char cCharToTx = 'a';
00663  portBASE_TYPE xResult;
00664 
00665      // All co-routines must start with a call to crSTART().
00666      crSTART( xHandle );
00667 
00668      for( ;; )
00669      {
00670          // Send the next character to the queue.
00671          crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult );
00672 
00673          if( xResult == pdPASS )
00674          {
00675              // The character was successfully posted to the queue.
00676          }
00677          else
00678          {
00679             // Could not post the character to the queue.
00680          }
00681 
00682          // Enable the UART Tx interrupt to cause an interrupt in this
00683          // hypothetical UART.  The interrupt will obtain the character
00684          // from the queue and send it.
00685          ENABLE_RX_INTERRUPT();
00686 
00687          // Increment to the next character then block for a fixed period.
00688          // cCharToTx will maintain its value across the delay as it is
00689          // declared static.
00690          cCharToTx++;
00691          if( cCharToTx > 'x' )
00692          {
00693             cCharToTx = 'a';
00694          }
00695          crDELAY( 100 );
00696      }
00697 
00698      // All co-routines must end with a call to crEND().
00699      crEND();
00700  }
00701 
00702  // An ISR that uses a queue to receive characters to send on a UART.
00703  void vUART_ISR( void )
00704  {
00705  char cCharToTx;
00706  portBASE_TYPE xCRWokenByPost = pdFALSE;
00707 
00708      while( UART_TX_REG_EMPTY() )
00709      {
00710          // Are there any characters in the queue waiting to be sent?
00711          // xCRWokenByPost will automatically be set to pdTRUE if a co-routine
00712          // is woken by the post - ensuring that only a single co-routine is
00713          // woken no matter how many times we go around this loop.
00714          if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) )
00715          {
00716              SEND_CHARACTER( cCharToTx );
00717          }
00718      }
00719  }</pre>
00720  * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR
00721  * \ingroup Tasks
00722  */
00723 #define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( pxQueue, pvBuffer, pxCoRoutineWoken )
00724 
00725 /*
00726  * This function is intended for internal use by the co-routine macros only.
00727  * The macro nature of the co-routine implementation requires that the
00728  * prototype appears here.  The function should not be used by application
00729  * writers.
00730  *
00731  * Removes the current co-routine from its ready list and places it in the
00732  * appropriate delayed list.
00733  */
00734 void vCoRoutineAddToDelayedList( portTickType xTicksToDelay, xList *pxEventList );
00735 
00736 /*
00737  * This function is intended for internal use by the queue implementation only.
00738  * The function should not be used by application writers.
00739  *
00740  * Removes the highest priority co-routine from the event list and places it in
00741  * the pending ready list.
00742  */
00743 signed portBASE_TYPE xCoRoutineRemoveFromEventList( const xList *pxEventList );
00744 
00745 #ifdef __cplusplus
00746 }
00747 #endif
00748 
00749 #endif /* CO_ROUTINE_H */