FreeRTOS代码阅读笔记：croutine

最近忙到死阿，简略的笔记下吧：

CONTENTS [hide]

croutine.h

#ifndef CO_ROUTINE_H
#define CO_ROUTINE_H
 
#ifndef INC_FREERTOS_H
    #error "include FreeRTOS.h must appear in source files before include croutine.h"
#endif
 
#include "list.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
croutine类似于task，可以进行类似的多任务调度。
它和task的区别在于croutine没有自己的栈空间，因此当进行多任务调度时，所有的局部变量都会无效，并且由于没有独立的栈空间，它的多任务调度也不能和task或者其他的通用性操作系统一样，通过压栈和切换栈的方式来进行多任务切换，croutine的切换方式很有意思，是通过swith的方式进行的，或者说是来模拟的。
*/
 
 
/* 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 * CoRoutineHandle_t;
 
/* Defines the prototype to which co-routine functions must conform. */
typedef void (*crCOROUTINE_CODE)( CoRoutineHandle_t, UBaseType_t );
 
typedef struct corCoRoutineControlBlock
{
    crCOROUTINE_CODE    pxCoRoutineFunction;
    ListItem_t          xGenericListItem;   /*< List item used to place the CRCB in ready and blocked queues. */
    ListItem_t          xEventListItem;     /*< List item used to place the CRCB in event lists. */
    UBaseType_t         uxPriority;         /*< The priority of the co-routine in relation to other co-routines. */
    UBaseType_t         uxIndex;            /*< Used to distinguish between co-routines when multiple co-routines use the same co-routine function. */
    uint16_t            uxState;            /*< Used internally by the co-routine implementation. */
} CRCB_t; /* Co-routine control block.  Note must be identical in size down to uxPriority with TCB_t. */
 
/**
 * croutine. h
 *<pre>
 BaseType_t xCoRoutineCreate(
                                 crCOROUTINE_CODE pxCoRoutineCode,
                                 UBaseType_t uxPriority,
                                 UBaseType_t 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( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
注意例子里的这个注释，如果要在croutine执行的函数中保存参数，
以便多任务切换后仍然使用，需要将这些参数全部保存为静态变量，
而不是局部变量，即放在数据区，而不是放在栈上。
  
 // 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 TickType_t uxFlashRates[ 2 ] = { 200, 400 };
 
croutine必须以crSTART开始，这样宏展开后就是一个大号的switch了
     // 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 int32_t to delay.  This assumes xQueue has
         // already been created.
         vParTestToggleLED( cLedToFlash[ uxIndex ] );
 
croutine进行多任务切换的唯一的方法就是调用crDELAY，这里宏展开后
是switch的一个case，并且会把xHandle的状态更新，这样当该任务重新调度后，
可以通过case跳转到这里，这就是croutine模拟多任务切换的核心，本质上是
任务函数的重新调用，这也是为什么参数不能用局部变量保存的原因。
         crDELAY( xHandle, uxFlashRates[ uxIndex ] );
     }
 
 
croutine必须以crEND结束，这样宏展开后就是一个大号的switch了
     // Must end every co-routine with a call to crEND();
     crEND();
 }
 
 // Function that creates two co-routines.
 void vOtherFunction( void )
 {
 uint8_t ucParameterToPass;
 TaskHandle_t 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
 */
 /*
创建一个croutine
pxCoRoutineCode:执行函数
uxPriority:优先级
uxIndex:当多个croutine执行相同的函数时，通过这个来区分不同的croutine
*/
BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, UBaseType_t uxPriority, UBaseType_t 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
 */
 /*
驱动croutine进行多任务调度
*/
void vCoRoutineSchedule( void );
 
/**
 * croutine. h
 * <pre>
 crSTART( CoRoutineHandle_t 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( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
 static int32_t 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
 */
 
/*
工具宏，在croutine函数的开始位置调用， 以便用来构造一个switch，来模拟多任务调度。
这里可以看到，当uxState = 0 时，会执行这里的case。
*/
#define crSTART( pxCRCB ) switch( ( ( CRCB_t * )( 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( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
 static int32_t 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
 */
 
/*
croutine必须以crEND结束，这样宏展开后就是一个大号的switch了
*/
#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.
 */
 /*
内部工具宏，注意这里uxState被赋值为__LINE__ * 2，并且返回，因此，当函数再次进入switch后，
会走到case (__LINE__ * 2)下面的代码，也就是这个宏的后面的代码。这样就可以模拟多
任务调度了
*/
#define crSET_STATE0( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = (__LINE__ * 2); return; case (__LINE__ * 2):
/*
同上
*/
#define crSET_STATE1( xHandle ) ( ( CRCB_t * )( xHandle ) )->uxState = ((__LINE__ * 2)+1); return; case ((__LINE__ * 2)+1):
 
/**
 * croutine. h
 *<pre>
 crDELAY( CoRoutineHandle_t xHandle, TickType_t 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_PERIOD_MS
 * can be used to convert ticks to milliseconds.
 *
 * Example usage:
   <pre>
 // Co-routine to be created.
 void vACoRoutine( CoRoutineHandle_t xHandle, UBaseType_t 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_PERIOD_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
 */
 /*
工具宏，用来模拟任务调度，调用此宏的croutine会主动让出处理器。
*/
#define crDELAY( xHandle, xTicksToDelay )                                               \
    if( ( xTicksToDelay ) > 0 )                                                          \
    {                                                                                   \
        vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL );                          \
    }                                                                                   \
    crSET_STATE0( ( xHandle ) );
 
/**
 * <pre>
 crQUEUE_SEND(
                  CoRoutineHandle_t xHandle,
                  QueueHandle_t pxQueue,
                  void *pvItemToQueue,
                  TickType_t xTicksToWait,
                  BaseType_t *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_PERIOD_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( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
 static BaseType_t xNumberToPost = 0;
 static BaseType_t 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 );
 
        if( xResult != pdPASS )
        {
            // The message was not posted!
        }
 
        // Increment the number to be posted onto the queue.
        xNumberToPost++;
 
        // Delay for 100 ticks.
        crDELAY( xHandle, 100 );
    }
 
    // Co-routines must end with a call to crEND().
    crEND();
 }</pre>
 * \defgroup crQUEUE_SEND crQUEUE_SEND
 * \ingroup Tasks
 */
#define crQUEUE_SEND( xHandle, pxQueue, pvItemToQueue, xTicksToWait, pxResult )         \
{                                                                                       \
    *( pxResult ) = xQueueCRSend( ( pxQueue) , ( pvItemToQueue) , ( xTicksToWait ) );   \
    if( *( pxResult ) == errQUEUE_BLOCKED )                                             \
    {                                                                                   \
        crSET_STATE0( ( xHandle ) );                                                    \
        *pxResult = xQueueCRSend( ( pxQueue ), ( pvItemToQueue ), 0 );                  \
    }                                                                                   \
    if( *pxResult == errQUEUE_YIELD )                                                   \
    {                                                                                   \
        crSET_STATE1( ( xHandle ) );                                                    \
        *pxResult = pdPASS;                                                             \
    }                                                                                   \
}
 
/**
 * croutine. h
 * <pre>
  crQUEUE_RECEIVE(
                     CoRoutineHandle_t xHandle,
                     QueueHandle_t pxQueue,
                     void *pvBuffer,
                     TickType_t xTicksToWait,
                     BaseType_t *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_RECEIVE 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 from which the data will be received.
 * The handle is obtained as the return value when the queue is created using
 * the xQueueCreate() API function.
 *
 * @param pvBuffer The buffer into which the received item is to be copied.
 * The number of bytes of each queued item is specified when the queue is
 * created.  This number of bytes is copied into pvBuffer.
 *
 * @param xTickToDelay The number of ticks that the co-routine should block
 * to wait for data to become available from the queue, should data 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_PERIOD_MS can be used to convert ticks to milliseconds (see the
 * crQUEUE_SEND example).
 *
 * @param pxResult The variable pointed to by pxResult will be set to pdPASS if
 * data was successfully retrieved from the queue, otherwise it will be set to
 * an error code as defined within ProjDefs.h.
 *
 * Example usage:
 <pre>
 // A co-routine receives the number of an LED to flash from a queue.  It
 // blocks on the queue until the number is received.
 static void prvCoRoutineFlashWorkTask( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 // Variables in co-routines must be declared static if they must maintain value across a blocking call.
 static BaseType_t xResult;
 static UBaseType_t uxLEDToFlash;
 
    // All co-routines must start with a call to crSTART().
    crSTART( xHandle );
 
    for( ;; )
    {
        // Wait for data to become available on the queue.
        crQUEUE_RECEIVE( xHandle, xCoRoutineQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
 
        if( xResult == pdPASS )
        {
            // We received the LED to flash - flash it!
            vParTestToggleLED( uxLEDToFlash );
        }
    }
 
    crEND();
 }</pre>
 * \defgroup crQUEUE_RECEIVE crQUEUE_RECEIVE
 * \ingroup Tasks
 */
#define crQUEUE_RECEIVE( xHandle, pxQueue, pvBuffer, xTicksToWait, pxResult )           \
{                                                                                       \
    *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), ( xTicksToWait ) );     \
    if( *( pxResult ) == errQUEUE_BLOCKED )                                             \
    {                                                                                   \
        crSET_STATE0( ( xHandle ) );                                                    \
        *( pxResult ) = xQueueCRReceive( ( pxQueue) , ( pvBuffer ), 0 );                \
    }                                                                                   \
    if( *( pxResult ) == errQUEUE_YIELD )                                               \
    {                                                                                   \
        crSET_STATE1( ( xHandle ) );                                                    \
        *( pxResult ) = pdPASS;                                                         \
    }                                                                                   \
}
 
/**
 * croutine. h
 * <pre>
  crQUEUE_SEND_FROM_ISR(
                            QueueHandle_t pxQueue,
                            void *pvItemToQueue,
                            BaseType_t xCoRoutinePreviouslyWoken
                       )</pre>
 *
 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
 * functions used by tasks.
 *
 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
 * xQueueReceiveFromISR() can only be used to pass data between a task and and
 * ISR.
 *
 * crQUEUE_SEND_FROM_ISR can only be called from an ISR to send data to a queue
 * that is being used from within a co-routine.
 *
 * 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 xQueue The handle to the queue on which the item is to be posted.
 *
 * @param pvItemToQueue A pointer to the item that is to be placed on the
 * queue.  The size of the items the queue will hold was defined when the
 * queue was created, so this many bytes will be copied from pvItemToQueue
 * into the queue storage area.
 *
 * @param xCoRoutinePreviouslyWoken This is included so an ISR can post onto
 * the same queue multiple times from a single interrupt.  The first call
 * should always pass in pdFALSE.  Subsequent calls should pass in
 * the value returned from the previous call.
 *
 * @return pdTRUE if a co-routine was woken by posting onto the queue.  This is
 * used by the ISR to determine if a context switch may be required following
 * the ISR.
 *
 * Example usage:
 <pre>
 // A co-routine that blocks on a queue waiting for characters to be received.
 static void vReceivingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 char cRxedChar;
 BaseType_t xResult;
 
     // All co-routines must start with a call to crSTART().
     crSTART( xHandle );
 
     for( ;; )
     {
         // Wait for data to become available on the queue.  This assumes the
         // queue xCommsRxQueue has already been created!
         crQUEUE_RECEIVE( xHandle, xCommsRxQueue, &uxLEDToFlash, portMAX_DELAY, &xResult );
 
         // Was a character received?
         if( xResult == pdPASS )
         {
             // Process the character here.
         }
     }
 
     // All co-routines must end with a call to crEND().
     crEND();
 }
 
 // An ISR that uses a queue to send characters received on a serial port to
 // a co-routine.
 void vUART_ISR( void )
 {
 char cRxedChar;
 BaseType_t xCRWokenByPost = pdFALSE;
 
     // We loop around reading characters until there are none left in the UART.
     while( UART_RX_REG_NOT_EMPTY() )
     {
         // Obtain the character from the UART.
         cRxedChar = UART_RX_REG;
 
         // Post the character onto a queue.  xCRWokenByPost will be pdFALSE
         // the first time around the loop.  If the post causes a co-routine
         // to be woken (unblocked) then xCRWokenByPost will be set to pdTRUE.
         // In this manner we can ensure that if more than one co-routine is
         // blocked on the queue only one is woken by this ISR no matter how
         // many characters are posted to the queue.
         xCRWokenByPost = crQUEUE_SEND_FROM_ISR( xCommsRxQueue, &cRxedChar, xCRWokenByPost );
     }
 }</pre>
 * \defgroup crQUEUE_SEND_FROM_ISR crQUEUE_SEND_FROM_ISR
 * \ingroup Tasks
 */
#define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) )
 
 
/**
 * croutine. h
 * <pre>
  crQUEUE_SEND_FROM_ISR(
                            QueueHandle_t pxQueue,
                            void *pvBuffer,
                            BaseType_t * pxCoRoutineWoken
                       )</pre>
 *
 * The macro's crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() are the
 * co-routine equivalent to the xQueueSendFromISR() and xQueueReceiveFromISR()
 * functions used by tasks.
 *
 * crQUEUE_SEND_FROM_ISR() and crQUEUE_RECEIVE_FROM_ISR() can only be used to
 * pass data between a co-routine and and ISR, whereas xQueueSendFromISR() and
 * xQueueReceiveFromISR() can only be used to pass data between a task and and
 * ISR.
 *
 * crQUEUE_RECEIVE_FROM_ISR can only be called from an ISR to receive data
 * from a queue that is being used from within a co-routine (a co-routine
 * posted to the queue).
 *
 * 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 xQueue The handle to the queue on which the item is to be posted.
 *
 * @param pvBuffer A pointer to a buffer into which the received item will be
 * placed.  The size of the items the queue will hold was defined when the
 * queue was created, so this many bytes will be copied from the queue into
 * pvBuffer.
 *
 * @param pxCoRoutineWoken A co-routine may be blocked waiting for space to become
 * available on the queue.  If crQUEUE_RECEIVE_FROM_ISR causes such a
 * co-routine to unblock *pxCoRoutineWoken will get set to pdTRUE, otherwise
 * *pxCoRoutineWoken will remain unchanged.
 *
 * @return pdTRUE an item was successfully received from the queue, otherwise
 * pdFALSE.
 *
 * Example usage:
 <pre>
 // A co-routine that posts a character to a queue then blocks for a fixed
 // period.  The character is incremented each time.
 static void vSendingCoRoutine( CoRoutineHandle_t xHandle, UBaseType_t uxIndex )
 {
 // cChar holds its value while this co-routine is blocked and must therefore
 // be declared static.
 static char cCharToTx = 'a';
 BaseType_t xResult;
 
     // All co-routines must start with a call to crSTART().
     crSTART( xHandle );
 
     for( ;; )
     {
         // Send the next character to the queue.
         crQUEUE_SEND( xHandle, xCoRoutineQueue, &cCharToTx, NO_DELAY, &xResult );
 
         if( xResult == pdPASS )
         {
             // The character was successfully posted to the queue.
         }
         else
         {
            // Could not post the character to the queue.
         }
 
         // Enable the UART Tx interrupt to cause an interrupt in this
         // hypothetical UART.  The interrupt will obtain the character
         // from the queue and send it.
         ENABLE_RX_INTERRUPT();
 
         // Increment to the next character then block for a fixed period.
         // cCharToTx will maintain its value across the delay as it is
         // declared static.
         cCharToTx++;
         if( cCharToTx > 'x' )
         {
            cCharToTx = 'a';
         }
         crDELAY( 100 );
     }
 
     // All co-routines must end with a call to crEND().
     crEND();
 }
 
 // An ISR that uses a queue to receive characters to send on a UART.
 void vUART_ISR( void )
 {
 char cCharToTx;
 BaseType_t xCRWokenByPost = pdFALSE;
 
     while( UART_TX_REG_EMPTY() )
     {
         // Are there any characters in the queue waiting to be sent?
         // xCRWokenByPost will automatically be set to pdTRUE if a co-routine
         // is woken by the post - ensuring that only a single co-routine is
         // woken no matter how many times we go around this loop.
         if( crQUEUE_RECEIVE_FROM_ISR( pxQueue, &cCharToTx, &xCRWokenByPost ) )
         {
             SEND_CHARACTER( cCharToTx );
         }
     }
 }</pre>
 * \defgroup crQUEUE_RECEIVE_FROM_ISR crQUEUE_RECEIVE_FROM_ISR
 * \ingroup Tasks
 */
#define crQUEUE_RECEIVE_FROM_ISR( pxQueue, pvBuffer, pxCoRoutineWoken ) xQueueCRReceiveFromISR( ( pxQueue ), ( pvBuffer ), ( pxCoRoutineWoken ) )
 
/*
 * This function is intended for internal use by the co-routine macros only.
 * The macro nature of the co-routine implementation requires that the
 * prototype appears here.  The function should not be used by application
 * writers.
 *
 * Removes the current co-routine from its ready list and places it in the
 * appropriate delayed list.
 */
void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay, List_t *pxEventList );
 
/*
 * This function is intended for internal use by the queue implementation only.
 * The function should not be used by application writers.
 *
 * Removes the highest priority co-routine from the event list and places it in
 * the pending ready list.
 */
BaseType_t xCoRoutineRemoveFromEventList( const List_t *pxEventList );
 
#ifdef __cplusplus
}
#endif
 
#endif /* CO_ROUTINE_H */

croutine.c

#include "FreeRTOS.h"
#include "task.h"
#include "croutine.h"
 
/* Remove the whole file is co-routines are not being used. */
#if( configUSE_CO_ROUTINES != 0 )
 
/*
 * Some kernel aware debuggers require data to be viewed to be global, rather
 * than file scope.
 */
#ifdef portREMOVE_STATIC_QUALIFIER
    #define static
#endif
 
 
/* Lists for ready and blocked co-routines. --------------------*/
static List_t pxReadyCoRoutineLists[ configMAX_CO_ROUTINE_PRIORITIES ]; /*< Prioritised ready co-routines. */
static List_t xDelayedCoRoutineList1;                                   /*< Delayed co-routines. */
static List_t xDelayedCoRoutineList2;                                   /*< Delayed co-routines (two lists are used - one for delays that have overflowed the current tick count. */
static List_t * pxDelayedCoRoutineList;                                 /*< Points to the delayed co-routine list currently being used. */
static List_t * pxOverflowDelayedCoRoutineList;                         /*< Points to the delayed co-routine list currently being used to hold co-routines that have overflowed the current tick count. */
static List_t xPendingReadyCoRoutineList;                               /*< Holds co-routines that have been readied by an external event.  They cannot be added directly to the ready lists as the ready lists cannot be accessed by interrupts. */
 
/* Other file private variables. --------------------------------*/
CRCB_t * pxCurrentCoRoutine = NULL;
static UBaseType_t uxTopCoRoutineReadyPriority = 0;
static TickType_t xCoRoutineTickCount = 0, xLastTickCount = 0, xPassedTicks = 0;
 
/* The initial state of the co-routine when it is created. */
#define corINITIAL_STATE    ( 0 )
 
/*
 * Place the co-routine represented by pxCRCB into the appropriate ready queue
 * for the priority.  It is inserted at the end of the list.
 *
 * This macro accesses the co-routine ready lists and therefore must not be
 * used from within an ISR.
 */
/*
根据croutine的优先级加入到对应的ready链表的末尾
*/
#define prvAddCoRoutineToReadyQueue( pxCRCB )                                                                       \
{                                                                                                       \
    if( pxCRCB->uxPriority > uxTopCoRoutineReadyPriority )                                                            \
    {                                                                                                               \
        uxTopCoRoutineReadyPriority = pxCRCB->uxPriority;                                                            \
    }                                                                                                               \
    vListInsertEnd( ( List_t * ) &( pxReadyCoRoutineLists[ pxCRCB->uxPriority ] ), &( pxCRCB->xGenericListItem ) );   \
}
 
/*
 * Utility to ready all the lists used by the scheduler.  This is called
 * automatically upon the creation of the first co-routine.
 */
static void prvInitialiseCoRoutineLists( void );
 
/*
 * Co-routines that are readied by an interrupt cannot be placed directly into
 * the ready lists (there is no mutual exclusion).  Instead they are placed in
 * in the pending ready list in order that they can later be moved to the ready
 * list by the co-routine scheduler.
 */
static void prvCheckPendingReadyList( void );
 
/*
 * Macro that looks at the list of co-routines that are currently delayed to
 * see if any require waking.
 *
 * Co-routines are stored in the queue in the order of their wake time -
 * meaning once one co-routine has been found whose timer has not expired
 * we need not look any further down the list.
 */
static void prvCheckDelayedList( void );
 
/*-----------------------------------------------------------*/
 /*
创建一个croutine
pxCoRoutineCode:执行函数
uxPriority:优先级
uxIndex:当多个croutine执行相同的函数时，通过这个来区分不同的croutine
*/
BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, UBaseType_t uxPriority, UBaseType_t uxIndex )
{
BaseType_t xReturn;
CRCB_t *pxCoRoutine;
 
    /* 
        首先申请一块内存，用来管理这个croutine
    */
    /* Allocate the memory that will store the co-routine control block. */
    pxCoRoutine = ( CRCB_t * ) pvPortMalloc( sizeof( CRCB_t ) );
    if( pxCoRoutine )
    {
 
        /*
        判断下当前的croutine是不是第一个申请的croutine，如果是第一个
        申请的croutine，就初始化croutine管理链表
        */
        /* If pxCurrentCoRoutine is NULL then this is the first co-routine to
        be created and the co-routine data structures need initialising. */
        if( pxCurrentCoRoutine == NULL )
        {
            pxCurrentCoRoutine = pxCoRoutine;
            prvInitialiseCoRoutineLists();
        }
 
        /* 校验下最高的优先级 */
        /* Check the priority is within limits. */
        if( uxPriority >= configMAX_CO_ROUTINE_PRIORITIES )
        {
            uxPriority = configMAX_CO_ROUTINE_PRIORITIES - 1;
        }
 
        /* 初始化结构体变量 */
        /* Fill out the co-routine control block from the function parameters. */
        pxCoRoutine->uxState = corINITIAL_STATE;
        pxCoRoutine->uxPriority = uxPriority;
        pxCoRoutine->uxIndex = uxIndex;
        pxCoRoutine->pxCoRoutineFunction = pxCoRoutineCode;
 
        /* Initialise all the other co-routine control block parameters. */
        vListInitialiseItem( &( pxCoRoutine->xGenericListItem ) );
        vListInitialiseItem( &( pxCoRoutine->xEventListItem ) );
 
        /* Set the co-routine control block as a link back from the ListItem_t.
        This is so we can get back to the containing CRCB from a generic item
        in a list. */
        listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xGenericListItem ), pxCoRoutine );
        listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xEventListItem ), pxCoRoutine );
 
        /* list的设计是升序排序设计，为了满足优先级越大越在前面，这里
        将value设置为 ( TickType_t ) configMAX_CO_ROUTINE_PRIORITIES - ( TickType_t ) uxPriority
        */
        /* Event lists are always in priority order. */
        listSET_LIST_ITEM_VALUE( &( pxCoRoutine->xEventListItem ), ( ( TickType_t ) configMAX_CO_ROUTINE_PRIORITIES - ( TickType_t ) uxPriority ) );
 
 
        /* 将croutine加入到管理链表中 */
        /* Now the co-routine has been initialised it can be added to the ready
        list at the correct priority. */
        prvAddCoRoutineToReadyQueue( pxCoRoutine );
 
        xReturn = pdPASS;
    }
    else
    {
        xReturn = errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY;
    }
 
    return xReturn;
}
/*-----------------------------------------------------------*/
/*
将croutine加入到等待链表中
*/
void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay, List_t *pxEventList )
{
TickType_t xTimeToWake;
 
    /* 根据管理croutine内部的定时器计算下该croutine需要醒来的时间 */
    /* Calculate the time to wake - this may overflow but this is
    not a problem. */
    xTimeToWake = xCoRoutineTickCount + xTicksToDelay;
 
    /* We must remove ourselves from the ready list before adding
    ourselves to the blocked list as the same list item is used for
    both lists. */
    /* 把croutine从原来的链表中能够删除 */
    ( void ) uxListRemove( ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 
    /* 
    等待队列是根据醒来的时间进行排序的，因此这里设置value为xTimeToWake
    */
    /* The list item will be inserted in wake time order. */
    listSET_LIST_ITEM_VALUE( &( pxCurrentCoRoutine->xGenericListItem ), xTimeToWake );
 
    /*xTimeToWake 溢出了，就把croutine加入到溢出后的链表中*/
    if( xTimeToWake < xCoRoutineTickCount )
    {
        /* Wake time has overflowed.  Place this item in the
        overflow list. */
        vListInsert( ( List_t * ) pxOverflowDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
    }
    else
    {
        /* The wake time has not overflowed, so we can use the
        current block list. */
        vListInsert( ( List_t * ) pxDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
    }
 
    /*
        如果还要等待特定的event，就也加入到event链表中
    */
    if( pxEventList )
    {
        /* Also add the co-routine to an event list.  If this is done then the
        function must be called with interrupts disabled. */
        vListInsert( pxEventList, &( pxCurrentCoRoutine->xEventListItem ) );
    }
}
/*-----------------------------------------------------------*/
 
static void prvCheckPendingReadyList( void )
{
    /* Are there any co-routines waiting to get moved to the ready list?  These
    are co-routines that have been readied by an ISR.  The ISR cannot access
    the ready lists itself. */
    /* 遍历下队列是否为空 */
    while( listLIST_IS_EMPTY( &xPendingReadyCoRoutineList ) == pdFALSE )
    {
        CRCB_t *pxUnblockedCRCB;
 
        /*
        将xPendingReadyCoRoutineList中的croutine转移到ready中
        */
 
        /* 这里禁掉中断,免得xPendingReadyCoRoutineList 被中断函数修改  */
        /* The pending ready list can be accessed by an ISR. */
        portDISABLE_INTERRUPTS();
        {
            pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( (&xPendingReadyCoRoutineList) );
            ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
        }
        portENABLE_INTERRUPTS();
 
        ( void ) uxListRemove( &( pxUnblockedCRCB->xGenericListItem ) );
        prvAddCoRoutineToReadyQueue( pxUnblockedCRCB );
    }
}
/*-----------------------------------------------------------*/
 
static void prvCheckDelayedList( void )
{
CRCB_t *pxCRCB;
 
    /*
    计算下上次调度和本次调度间的时间差。
    然后根据时间差单步遍历所有的croutine
    */ 
    xPassedTicks = xTaskGetTickCount() - xLastTickCount;
    while( xPassedTicks )
    {
        xCoRoutineTickCount++;//单步递增管理croutine内部的定时器
        xPassedTicks--;//单步递减时间差
 
        /* If the tick count has overflowed we need to swap the ready lists. */
        if( xCoRoutineTickCount == 0 )//管理croutine内部的定时器单步递增，因此溢出时会变为0
        {
            /* 定时器溢出后切换两个等待队列*/
            List_t * pxTemp;
 
            /* Tick count has overflowed so we need to swap the delay lists.  If there are
            any items in pxDelayedCoRoutineList here then there is an error! */
            pxTemp = pxDelayedCoRoutineList;
            pxDelayedCoRoutineList = pxOverflowDelayedCoRoutineList;
            pxOverflowDelayedCoRoutineList = pxTemp;
        }
 
        /* See if this tick has made a timeout expire. */
        while( listLIST_IS_EMPTY( pxDelayedCoRoutineList ) == pdFALSE )
        {
        /*
        等待队列的排列是按照等待的时间进行排序的，如果第一个的时间都
        大于当前管理croutine的内部的定时器，那么不用在查找了，不会有等待的
        croutine到达。     
        */
            pxCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxDelayedCoRoutineList );
 
            if( xCoRoutineTickCount < listGET_LIST_ITEM_VALUE( &( pxCRCB->xGenericListItem ) ) )
            {
                /* Timeout not yet expired. */
                break;
            }
            /*
            第一个等待的croutine时间到期了
            */
            //禁掉中断，免得链表被修改
            portDISABLE_INTERRUPTS();
            {
                /* The event could have occurred just before this critical
                section.  If this is the case then the generic list item will
                have been moved to the pending ready list and the following
                line is still valid.  Also the pvContainer parameter will have
                been set to NULL so the following lines are also valid. */
                ( void ) uxListRemove( &( pxCRCB->xGenericListItem ) );
 
                /* Is the co-routine waiting on an event also? */
                if( pxCRCB->xEventListItem.pvContainer )
                {
                    ( void ) uxListRemove( &( pxCRCB->xEventListItem ) );
                }
 
                /*
                将到期的croutine从等待链表转移到ready链表中
                */
                 
            }
            portENABLE_INTERRUPTS();
 
            prvAddCoRoutineToReadyQueue( pxCRCB );
        }
    }
 
    xLastTickCount = xCoRoutineTickCount;
}
/*-----------------------------------------------------------*/
 /*
驱动croutine进行多任务调度
*/
void vCoRoutineSchedule( void )
{
    /* 
    检查下是否有croutine可以转移到ready队列中
    */
    /* See if any co-routines readied by events need moving to the ready lists. */
    prvCheckPendingReadyList();
 
    /*
    检查下定时器是否已经溢出了
    */
    /* See if any delayed co-routines have timed out. */
    prvCheckDelayedList();
 
    /*
    找到一个最高的优先级，并且该优先级链表中有croutine
    */
    /* Find the highest priority queue that contains ready co-routines. */
    while( listLIST_IS_EMPTY( &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) ) )
    {
        if( uxTopCoRoutineReadyPriority == 0 )
        {
            /* No more co-routines to check. */
            return;
        }
        --uxTopCoRoutineReadyPriority;
    }
 
    /* listGET_OWNER_OF_NEXT_ENTRY walks through the list, so the co-routines
     of the same priority get an equal share of the processor time. */
    listGET_OWNER_OF_NEXT_ENTRY( pxCurrentCoRoutine, &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) );
 
    /* 执行该croutine */
    /* Call the co-routine. */
    ( pxCurrentCoRoutine->pxCoRoutineFunction )( pxCurrentCoRoutine, pxCurrentCoRoutine->uxIndex );
 
    return;
}
/*-----------------------------------------------------------*/
 
/*
内部工具函数，用来初始化管理croutine的所需的链表
*/
static void prvInitialiseCoRoutineLists( void )
{
UBaseType_t uxPriority;
 
    /*
    每一个优先级都初始化一个链表，这样croutine可以根据自己的优先级加入不同的链表
    */
    for( uxPriority = 0; uxPriority < configMAX_CO_ROUTINE_PRIORITIES; uxPriority++ )
    {
        vListInitialise( ( List_t * ) &( pxReadyCoRoutineLists[ uxPriority ] ) );
    }
 
    /*
        初始化等待队列。这里需要两个队列的原因是定时器可能会溢出。
        因此这里一个队列保存定时器溢出前到期的croutine，另一个保存定时器
        溢出后的定时器。
    */
     
    vListInitialise( ( List_t * ) &xDelayedCoRoutineList1 );
    vListInitialise( ( List_t * ) &xDelayedCoRoutineList2 );
    vListInitialise( ( List_t * ) &xPendingReadyCoRoutineList );
 
    /* Start with pxDelayedCoRoutineList using list1 and the
    pxOverflowDelayedCoRoutineList using list2. */
    pxDelayedCoRoutineList = &xDelayedCoRoutineList1;
    pxOverflowDelayedCoRoutineList = &xDelayedCoRoutineList2;
}
/*-----------------------------------------------------------*/
 
/*
将croutine从event链表中移除
*/
BaseType_t xCoRoutineRemoveFromEventList( const List_t *pxEventList )
{
CRCB_t *pxUnblockedCRCB;
BaseType_t xReturn;
 
    /*
    从event链表中找到第一个croutine，然后把它放到等待ready链表中。
    也就是这里一次只释放一个croutine。
    */
    /* This function is called from within an interrupt.  It can only access
    event lists and the pending ready list.  This function assumes that a
    check has already been made to ensure pxEventList is not empty. */
    pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxEventList );
    ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
    vListInsertEnd( ( List_t * ) &( xPendingReadyCoRoutineList ), &( pxUnblockedCRCB->xEventListItem ) );
 
    if( pxUnblockedCRCB->uxPriority >= pxCurrentCoRoutine->uxPriority )
    {
        xReturn = pdTRUE;
    }
    else
    {
        xReturn = pdFALSE;
    }
 
    return xReturn;
}
 
#endif /* configUSE_CO_ROUTINES == 0 */

一	二	三	四	五	六	日
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30

croutine.h

croutine.c

cstriker1407

发表评论取消回复

Contents

FreeRTOS代码阅读笔记：croutine

croutine.h

croutine.c

cstriker1407

发表评论 取消回复

标签

Contents

发表评论取消回复