croutine.h

Go to the documentation of this file.

/*
 * FreeRTOS Kernel V10.0.0
 * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software. If you wish to use our Amazon
 * FreeRTOS name, please do so in a fair use way that does not cause confusion.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * http://www.FreeRTOS.org
 * http://aws.amazon.com/freertos
 *
 * 1 tab == 4 spaces!
 */
 
#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
 
/* 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. */
 
BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode, UBaseType_t uxPriority, UBaseType_t uxIndex );
 
 
void vCoRoutineSchedule( void );
 
#define crSTART( pxCRCB ) switch( ( ( CRCB_t * )( pxCRCB ) )->uxState ) { case 0:
 
#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 ) ( ( 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):
 
#define crDELAY( xHandle, xTicksToDelay )                                               \
    if( ( xTicksToDelay ) > 0 )                                                         \
    {                                                                                   \
        vCoRoutineAddToDelayedList( ( xTicksToDelay ), NULL );                          \
    }                                                                                   \
    crSET_STATE0( ( xHandle ) );
 
#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;                                                             \
    }                                                                                   \
}
 
#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;                                                         \
    }                                                                                   \
}
 
#define crQUEUE_SEND_FROM_ISR( pxQueue, pvItemToQueue, xCoRoutinePreviouslyWoken ) xQueueCRSendFromISR( ( pxQueue ), ( pvItemToQueue ), ( xCoRoutinePreviouslyWoken ) )
 
 
#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 */