/*

	FreeRTOS.org V4.1.1 - Copyright (C) 2003-2006 Richard Barry.



	This file is part of the FreeRTOS.org distribution.



	FreeRTOS.org is free software; you can redistribute it and/or modify

	it under the terms of the GNU General Public License as published by

	the Free Software Foundation; either version 2 of the License, or

	(at your option) any later version.



	FreeRTOS.org is distributed in the hope that it will be useful,

	but WITHOUT ANY WARRANTY; without even the implied warranty of

	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

	GNU General Public License for more details.



	You should have received a copy of the GNU General Public License

	along with FreeRTOS.org; if not, write to the Free Software

	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA



	A special exception to the GPL can be applied should you wish to distribute

	a combined work that includes FreeRTOS.org, without being obliged to provide

	the source code for any proprietary components.  See the licensing section

	of http://www.FreeRTOS.org for full details of how and when the exception

	can be applied.



	***************************************************************************

	See http://www.FreeRTOS.org for documentation, latest information, license

	and contact details.  Please ensure to read the configuration and relevant

	port sections of the online documentation.

	***************************************************************************

*/

#ifndef CO_ROUTINE_H

#define CO_ROUTINE_H



#include "list.h"



/* Used to hide the implementation of the co-routine control block.  The

control block structure however has to be included in the header due to

the macro implementation of the co-routine functionality. */

typedef void * xCoRoutineHandle;



/* Defines the prototype to which co-routine functions must conform. */

typedef void (*crCOROUTINE_CODE)( xCoRoutineHandle, unsigned portBASE_TYPE );



typedef struct corCoRoutineControlBlock

{

	crCOROUTINE_CODE 		pxCoRoutineFunction;

	xListItem				xGenericListItem;	/*< List item used to place the CRCB in ready and blocked queues. */

	xListItem				xEventListItem;		/*< List item used to place the CRCB in event lists. */

	unsigned portBASE_TYPE 	uxPriority;			/*< The priority of the co-routine in relation to other co-routines. */

	unsigned portBASE_TYPE 	uxIndex;			/*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */

	unsigned portSHORT 		uxState;			/*< Used internally by the co-routine implementation. */

} corCRCB; /* Co-routine control block.  Note must be identical in size down to uxPriority with tskTCB. */



/**

 * croutine. h

 *<pre>

 portBASE_TYPE xCoRoutineCreate(

                                 crCOROUTINE_CODE pxCoRoutineCode,

                                 unsigned portBASE_TYPE uxPriority,

                                 unsigned portBASE_TYPE uxIndex

                               );</pre>

 *

 * Create a new co-routine and add it to the list of co-routines that are

 * ready to run.

 *

 * @param pxCoRoutineCode Pointer to the co-routine function.  Co-routine

 * functions require special syntax - see the co-routine section of the WEB

 * documentation for more information.

 *

 * @param uxPriority The priority with respect to other co-routines at which

 *  the co-routine will run.

 *

 * @param uxIndex Used to distinguish between different co-routines that

 * execute the same function.  See the example below and the co-routine section

 * of the WEB documentation for further information.

 *

 * @return pdPASS if the co-routine was successfully created and added to a ready

 * list, otherwise an error code defined with ProjDefs.h.

 *

 * Example usage:

   <pre>

 // Co-routine to be created.

 void vFlashCoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )

 {

 // Variables in co-routines must be declared static if they must maintain value across a blocking call.

 // This may not be necessary for const variables.

 static const char cLedToFlash[ 2 ] = { 5, 6 };

 static const portTickType xTimeToDelay[ 2 ] = { 200, 400 };



     // Must start every co-routine with a call to crSTART();

     crSTART( xHandle );



     for( ;; )

     {

         // This co-routine just delays for a fixed period, then toggles

         // an LED.  Two co-routines are created using this function, so

         // the uxIndex parameter is used to tell the co-routine which

         // LED to flash and how long to delay.  This assumes xQueue has

         // already been created.

         vParTestToggleLED( cLedToFlash[ uxIndex ] );

         crDELAY( xHandle, uxFlashRates[ uxIndex ] );

     }



     // Must end every co-routine with a call to crEND();

     crEND();

 }



 // Function that creates two co-routines.

 void vOtherFunction( void )

 {

 unsigned char ucParameterToPass;

 xTaskHandle xHandle;

		

     // Create two co-routines at priority 0.  The first is given index 0

     // so (from the code above) toggles LED 5 every 200 ticks.  The second

     // is given index 1 so toggles LED 6 every 400 ticks.

     for( uxIndex = 0; uxIndex < 2; uxIndex++ )

     {

         xCoRoutineCreate( vFlashCoRoutine, 0, uxIndex );

     }

 }

   </pre>

 * \defgroup xCoRoutineCreate xCoRoutineCreate

 * \ingroup Tasks

 */

signed portBASE_TYPE xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, unsigned portBASE_TYPE uxPriority, unsigned portBASE_TYPE uxIndex );





/**

 * croutine. h

 *<pre>

 void vCoRoutineSchedule( void );</pre>

 *

 * Run a co-routine.

 *

 * vCoRoutineSchedule() executes the highest priority co-routine that is able

 * to run.  The co-routine will execute until it either blocks, yields or is

 * preempted by a task.  Co-routines execute cooperatively so one

 * co-routine cannot be preempted by another, but can be preempted by a task.

 *

 * If an application comprises of both tasks and co-routines then

 * vCoRoutineSchedule should be called from the idle task (in an idle task

 * hook).

 *

 * Example usage:

   <pre>

 // This idle task hook will schedule a co-routine each time it is called.

 // The rest of the idle task will execute between co-routine calls.

 void vApplicationIdleHook( void )

 {

	vCoRoutineSchedule();

 }



 // Alternatively, if you do not require any other part of the idle task to

 // execute, the idle task hook can call vCoRoutineScheduler() within an

 // infinite loop.

 void vApplicationIdleHook( void )

 {

    for( ;; )

    {

        vCoRoutineSchedule();

    }

 }

 </pre>

 * \defgroup vCoRoutineSchedule vCoRoutineSchedule

 * \ingroup Tasks

 */

void vCoRoutineSchedule( void );



/**

 * croutine. h

 * <pre>

 crSTART( xCoRoutineHandle xHandle );</pre>

 *

 * This macro MUST always be called at the start of a co-routine function.

 *

 * Example usage:

   <pre>

 // Co-routine to be created.

 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )

 {

 // Variables in co-routines must be declared static if they must maintain value across a blocking call.

 static portLONG ulAVariable;



     // Must start every co-routine with a call to crSTART();

     crSTART( xHandle );



     for( ;; )

     {

          // Co-routine functionality goes here.

     }



     // Must end every co-routine with a call to crEND();

     crEND();

 }</pre>

 * \defgroup crSTART crSTART

 * \ingroup Tasks

 */

#define crSTART( pxCRCB ) switch( ( ( corCRCB * )pxCRCB )->uxState ) { case 0:



/**

 * croutine. h

 * <pre>

 crEND();</pre>

 *

 * This macro MUST always be called at the end of a co-routine function.

 *

 * Example usage:

   <pre>

 // Co-routine to be created.

 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )

 {

 // Variables in co-routines must be declared static if they must maintain value across a blocking call.

 static portLONG ulAVariable;



     // Must start every co-routine with a call to crSTART();

     crSTART( xHandle );



     for( ;; )

     {

          // Co-routine functionality goes here.

     }



     // Must end every co-routine with a call to crEND();

     crEND();

 }</pre>

 * \defgroup crSTART crSTART

 * \ingroup Tasks

 */

#define crEND() }



/*

 * These macros are intended for internal use by the co-routine implementation

 * only.  The macros should not be used directly by application writers.

 */

#define crSET_STATE0( xHandle ) ( ( corCRCB * )xHandle)->uxState = (__LINE__ * 2); return; case (__LINE__ * 2):

#define crSET_STATE1( xHandle ) ( ( corCRCB * )xHandle)->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1):



/**

 * croutine. h

 *<pre>

 crDELAY( xCoRoutineHandle xHandle, portTickType xTicksToDelay );</pre>

 *

 * Delay a co-routine for a fixed period of time.

 *

 * crDELAY can only be called from the co-routine function itself - not

 * from within a function called by the co-routine function.  This is because

 * co-routines do not maintain their own stack.

 *

 * @param xHandle The handle of the co-routine to delay.  This is the xHandle

 * parameter of the co-routine function.

 *

 * @param xTickToDelay The number of ticks that the co-routine should delay

 * for.  The actual amount of time this equates to is defined by

 * configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant portTICK_RATE_MS

 * can be used to convert ticks to milliseconds.

 *

 * Example usage:

   <pre>

 // Co-routine to be created.

 void vACoRoutine( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )

 {

 // Variables in co-routines must be declared static if they must maintain value across a blocking call.

 // This may not be necessary for const variables.

 // We are to delay for 200ms.

 static const xTickType xDelayTime = 200 / portTICK_RATE_MS;



     // Must start every co-routine with a call to crSTART();

     crSTART( xHandle );



     for( ;; )

     {

        // Delay for 200ms.

        crDELAY( xHandle, xDelayTime );



        // Do something here.

     }



     // Must end every co-routine with a call to crEND();

     crEND();

 }</pre>

 * \defgroup crDELAY crDELAY

 * \ingroup Tasks

 */

#define crDELAY( xHandle, xTicksToDelay )												\

	if( xTicksToDelay > 0 )																\

	{																					\

		vCoRoutineAddToDelayedList( xTicksToDelay, NULL );								\

	}																					\

	crSET_STATE0( xHandle );



/**

 * <pre>

 crQUEUE_SEND(

                  xCoRoutineHandle xHandle,

                  xQueueHandle pxQueue,

                  void *pvItemToQueue,

                  portTickType xTicksToWait,

                  portBASE_TYPE *pxResult

             )</pre>

 *

 * The macro's crQUEUE_SEND() and crQUEUE_RECEIVE() are the co-routine

 * equivalent to the xQueueSend() and xQueueReceive() functions used by tasks.

 *

 * crQUEUE_SEND and crQUEUE_RECEIVE can only be used from a co-routine whereas

 * xQueueSend() and xQueueReceive() can only be used from tasks.

 *

 * crQUEUE_SEND can only be called from the co-routine function itself - not

 * from within a function called by the co-routine function.  This is because

 * co-routines do not maintain their own stack.

 *

 * See the co-routine section of the WEB documentation for information on

 * passing data between tasks and co-routines and between ISR's and

 * co-routines.

 *

 * @param xHandle The handle of the calling co-routine.  This is the xHandle

 * parameter of the co-routine function.

 *

 * @param pxQueue The handle of the queue on which the data will be posted.

 * The handle is obtained as the return value when the queue is created using

 * the xQueueCreate() API function.

 *

 * @param pvItemToQueue A pointer to the data being posted onto the queue.

 * The number of bytes of each queued item is specified when the queue is

 * created.  This number of bytes is copied from pvItemToQueue into the queue

 * itself.

 *

 * @param xTickToDelay The number of ticks that the co-routine should block

 * to wait for space to become available on the queue, should space not be

 * available immediately. The actual amount of time this equates to is defined

 * by configTICK_RATE_HZ (set in FreeRTOSConfig.h).  The constant

 * portTICK_RATE_MS can be used to convert ticks to milliseconds (see example

 * below).

 *

 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if

 * data was successfully posted onto the queue, otherwise it will be set to an

 * error defined within ProjDefs.h.

 *

 * Example usage:

   <pre>

 // Co-routine function that blocks for a fixed period then posts a number onto

 // a queue.

 static void prvCoRoutineFlashTask( xCoRoutineHandle xHandle, unsigned portBASE_TYPE uxIndex )

 {

 // Variables in co-routines must be declared static if they must maintain value across a blocking call.

 static portBASE_TYPE xNumberToPost = 0;

 static portBASE_TYPE xResult;



    // Co-routines must begin with a call to crSTART().

    crSTART( xHandle );



    for( ;; )

    {

        // This assumes the queue has already been created.

        crQUEUE_SEND( xHandle, xCoRoutineQueue, &xNumberToPost, NO_DELAY, &xResult );