begriffs open source - freertos/blob - croutine.c

   1 /*
   2  * FreeRTOS Kernel V10.6.2
   3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
   4  *
   5  * SPDX-License-Identifier: MIT
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   8  * this software and associated documentation files (the "Software"), to deal in
   9  * the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11  * the Software, and to permit persons to whom the Software is furnished to do so,
  12  * subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in all
  15  * copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  *
  24  * https://www.FreeRTOS.org
  25  * https://github.com/FreeRTOS
  26  *
  27  */
  28
  29 #include "FreeRTOS.h"
  30 #include "task.h"
  31 #include "croutine.h"
  32
  33 /* Remove the whole file is co-routines are not being used. */
  34 #if ( configUSE_CO_ROUTINES != 0 )
  35
  36 /*
  37  * Some kernel aware debuggers require data to be viewed to be global, rather
  38  * than file scope.
  39  */
  40     #ifdef portREMOVE_STATIC_QUALIFIER
  41         #define static
  42     #endif
  43
  44
  45 /* Lists for ready and blocked co-routines. --------------------*/
  46     static List_t pxReadyCoRoutineLists[ configMAX_CO_ROUTINE_PRIORITIES ]; /*< Prioritised ready co-routines. */
  47     static List_t xDelayedCoRoutineList1;                                   /*< Delayed co-routines. */
  48     static List_t xDelayedCoRoutineList2;                                   /*< Delayed co-routines (two lists are used - one for delays that have overflowed the current tick count. */
  49     static List_t * pxDelayedCoRoutineList = NULL;                          /*< Points to the delayed co-routine list currently being used. */
  50     static List_t * pxOverflowDelayedCoRoutineList = NULL;                  /*< Points to the delayed co-routine list currently being used to hold co-routines that have overflowed the current tick count. */
  51     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. */
  52
  53 /* Other file private variables. --------------------------------*/
  54     CRCB_t * pxCurrentCoRoutine = NULL;
  55     static UBaseType_t uxTopCoRoutineReadyPriority = 0;
  56     static TickType_t xCoRoutineTickCount = 0, xLastTickCount = 0, xPassedTicks = 0;
  57
  58 /* The initial state of the co-routine when it is created. */
  59     #define corINITIAL_STATE    ( 0 )
  60
  61 /*
  62  * Place the co-routine represented by pxCRCB into the appropriate ready queue
  63  * for the priority.  It is inserted at the end of the list.
  64  *
  65  * This macro accesses the co-routine ready lists and therefore must not be
  66  * used from within an ISR.
  67  */
  68     #define prvAddCoRoutineToReadyQueue( pxCRCB )                                                                               \
  69     do {                                                                                                                        \
  70         if( ( pxCRCB )->uxPriority > uxTopCoRoutineReadyPriority )                                                              \
  71         {                                                                                                                       \
  72             uxTopCoRoutineReadyPriority = ( pxCRCB )->uxPriority;                                                               \
  73         }                                                                                                                       \
  74         vListInsertEnd( ( List_t * ) &( pxReadyCoRoutineLists[ ( pxCRCB )->uxPriority ] ), &( ( pxCRCB )->xGenericListItem ) ); \
  75     } while( 0 )
  76
  77 /*
  78  * Utility to ready all the lists used by the scheduler.  This is called
  79  * automatically upon the creation of the first co-routine.
  80  */
  81     static void prvInitialiseCoRoutineLists( void );
  82
  83 /*
  84  * Co-routines that are readied by an interrupt cannot be placed directly into
  85  * the ready lists (there is no mutual exclusion).  Instead they are placed in
  86  * in the pending ready list in order that they can later be moved to the ready
  87  * list by the co-routine scheduler.
  88  */
  89     static void prvCheckPendingReadyList( void );
  90
  91 /*
  92  * Macro that looks at the list of co-routines that are currently delayed to
  93  * see if any require waking.
  94  *
  95  * Co-routines are stored in the queue in the order of their wake time -
  96  * meaning once one co-routine has been found whose timer has not expired
  97  * we need not look any further down the list.
  98  */
  99     static void prvCheckDelayedList( void );
 100
 101 /*-----------------------------------------------------------*/
 102
 103     BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode,
 104                                  UBaseType_t uxPriority,
 105                                  UBaseType_t uxIndex )
 106     {
 107         BaseType_t xReturn;
 108         CRCB_t * pxCoRoutine;
 109
 110         /* Allocate the memory that will store the co-routine control block. */
 111         pxCoRoutine = ( CRCB_t * ) pvPortMalloc( sizeof( CRCB_t ) );
 112
 113         if( pxCoRoutine )
 114         {
 115             /* If pxCurrentCoRoutine is NULL then this is the first co-routine to
 116             * be created and the co-routine data structures need initialising. */
 117             if( pxCurrentCoRoutine == NULL )
 118             {
 119                 pxCurrentCoRoutine = pxCoRoutine;
 120                 prvInitialiseCoRoutineLists();
 121             }
 122
 123             /* Check the priority is within limits. */
 124             if( uxPriority >= configMAX_CO_ROUTINE_PRIORITIES )
 125             {
 126                 uxPriority = configMAX_CO_ROUTINE_PRIORITIES - 1;
 127             }
 128
 129             /* Fill out the co-routine control block from the function parameters. */
 130             pxCoRoutine->uxState = corINITIAL_STATE;
 131             pxCoRoutine->uxPriority = uxPriority;
 132             pxCoRoutine->uxIndex = uxIndex;
 133             pxCoRoutine->pxCoRoutineFunction = pxCoRoutineCode;
 134
 135             /* Initialise all the other co-routine control block parameters. */
 136             vListInitialiseItem( &( pxCoRoutine->xGenericListItem ) );
 137             vListInitialiseItem( &( pxCoRoutine->xEventListItem ) );
 138
 139             /* Set the co-routine control block as a link back from the ListItem_t.
 140              * This is so we can get back to the containing CRCB from a generic item
 141              * in a list. */
 142             listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xGenericListItem ), pxCoRoutine );
 143             listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xEventListItem ), pxCoRoutine );
 144
 145             /* Event lists are always in priority order. */
 146             listSET_LIST_ITEM_VALUE( &( pxCoRoutine->xEventListItem ), ( ( TickType_t ) configMAX_CO_ROUTINE_PRIORITIES - ( TickType_t ) uxPriority ) );
 147
 148             /* Now the co-routine has been initialised it can be added to the ready
 149              * list at the correct priority. */
 150             prvAddCoRoutineToReadyQueue( pxCoRoutine );
 151
 152             xReturn = pdPASS;
 153         }
 154         else
 155         {
 156             xReturn = errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY;
 157         }
 158
 159         return xReturn;
 160     }
 161 /*-----------------------------------------------------------*/
 162
 163     void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay,
 164                                      List_t * pxEventList )
 165     {
 166         TickType_t xTimeToWake;
 167
 168         /* Calculate the time to wake - this may overflow but this is
 169          * not a problem. */
 170         xTimeToWake = xCoRoutineTickCount + xTicksToDelay;
 171
 172         /* We must remove ourselves from the ready list before adding
 173          * ourselves to the blocked list as the same list item is used for
 174          * both lists. */
 175         ( void ) uxListRemove( ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 176
 177         /* The list item will be inserted in wake time order. */
 178         listSET_LIST_ITEM_VALUE( &( pxCurrentCoRoutine->xGenericListItem ), xTimeToWake );
 179
 180         if( xTimeToWake < xCoRoutineTickCount )
 181         {
 182             /* Wake time has overflowed.  Place this item in the
 183              * overflow list. */
 184             vListInsert( ( List_t * ) pxOverflowDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 185         }
 186         else
 187         {
 188             /* The wake time has not overflowed, so we can use the
 189              * current block list. */
 190             vListInsert( ( List_t * ) pxDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 191         }
 192
 193         if( pxEventList )
 194         {
 195             /* Also add the co-routine to an event list.  If this is done then the
 196              * function must be called with interrupts disabled. */
 197             vListInsert( pxEventList, &( pxCurrentCoRoutine->xEventListItem ) );
 198         }
 199     }
 200 /*-----------------------------------------------------------*/
 201
 202     static void prvCheckPendingReadyList( void )
 203     {
 204         /* Are there any co-routines waiting to get moved to the ready list?  These
 205          * are co-routines that have been readied by an ISR.  The ISR cannot access
 206          * the ready lists itself. */
 207         while( listLIST_IS_EMPTY( &xPendingReadyCoRoutineList ) == pdFALSE )
 208         {
 209             CRCB_t * pxUnblockedCRCB;
 210
 211             /* The pending ready list can be accessed by an ISR. */
 212             portDISABLE_INTERRUPTS();
 213             {
 214                 pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( ( &xPendingReadyCoRoutineList ) );
 215                 ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
 216             }
 217             portENABLE_INTERRUPTS();
 218
 219             ( void ) uxListRemove( &( pxUnblockedCRCB->xGenericListItem ) );
 220             prvAddCoRoutineToReadyQueue( pxUnblockedCRCB );
 221         }
 222     }
 223 /*-----------------------------------------------------------*/
 224
 225     static void prvCheckDelayedList( void )
 226     {
 227         CRCB_t * pxCRCB;
 228
 229         xPassedTicks = xTaskGetTickCount() - xLastTickCount;
 230
 231         while( xPassedTicks )
 232         {
 233             xCoRoutineTickCount++;
 234             xPassedTicks--;
 235
 236             /* If the tick count has overflowed we need to swap the ready lists. */
 237             if( xCoRoutineTickCount == 0 )
 238             {
 239                 List_t * pxTemp;
 240
 241                 /* Tick count has overflowed so we need to swap the delay lists.  If there are
 242                  * any items in pxDelayedCoRoutineList here then there is an error! */
 243                 pxTemp = pxDelayedCoRoutineList;
 244                 pxDelayedCoRoutineList = pxOverflowDelayedCoRoutineList;
 245                 pxOverflowDelayedCoRoutineList = pxTemp;
 246             }
 247
 248             /* See if this tick has made a timeout expire. */
 249             while( listLIST_IS_EMPTY( pxDelayedCoRoutineList ) == pdFALSE )
 250             {
 251                 pxCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxDelayedCoRoutineList );
 252
 253                 if( xCoRoutineTickCount < listGET_LIST_ITEM_VALUE( &( pxCRCB->xGenericListItem ) ) )
 254                 {
 255                     /* Timeout not yet expired. */
 256                     break;
 257                 }
 258
 259                 portDISABLE_INTERRUPTS();
 260                 {
 261                     /* The event could have occurred just before this critical
 262                      *  section.  If this is the case then the generic list item will
 263                      *  have been moved to the pending ready list and the following
 264                      *  line is still valid.  Also the pvContainer parameter will have
 265                      *  been set to NULL so the following lines are also valid. */
 266                     ( void ) uxListRemove( &( pxCRCB->xGenericListItem ) );
 267
 268                     /* Is the co-routine waiting on an event also? */
 269                     if( pxCRCB->xEventListItem.pxContainer )
 270                     {
 271                         ( void ) uxListRemove( &( pxCRCB->xEventListItem ) );
 272                     }
 273                 }
 274                 portENABLE_INTERRUPTS();
 275
 276                 prvAddCoRoutineToReadyQueue( pxCRCB );
 277             }
 278         }
 279
 280         xLastTickCount = xCoRoutineTickCount;
 281     }
 282 /*-----------------------------------------------------------*/
 283
 284     void vCoRoutineSchedule( void )
 285     {
 286         /* Only run a co-routine after prvInitialiseCoRoutineLists() has been
 287          * called.  prvInitialiseCoRoutineLists() is called automatically when a
 288          * co-routine is created. */
 289         if( pxDelayedCoRoutineList != NULL )
 290         {
 291             /* See if any co-routines readied by events need moving to the ready lists. */
 292             prvCheckPendingReadyList();
 293
 294             /* See if any delayed co-routines have timed out. */
 295             prvCheckDelayedList();
 296
 297             /* Find the highest priority queue that contains ready co-routines. */
 298             while( listLIST_IS_EMPTY( &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) ) )
 299             {
 300                 if( uxTopCoRoutineReadyPriority == 0 )
 301                 {
 302                     /* No more co-routines to check. */
 303                     return;
 304                 }
 305
 306                 --uxTopCoRoutineReadyPriority;
 307             }
 308
 309             /* listGET_OWNER_OF_NEXT_ENTRY walks through the list, so the co-routines
 310              * of the same priority get an equal share of the processor time. */
 311             listGET_OWNER_OF_NEXT_ENTRY( pxCurrentCoRoutine, &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) );
 312
 313             /* Call the co-routine. */
 314             ( pxCurrentCoRoutine->pxCoRoutineFunction )( pxCurrentCoRoutine, pxCurrentCoRoutine->uxIndex );
 315         }
 316     }
 317 /*-----------------------------------------------------------*/
 318
 319     static void prvInitialiseCoRoutineLists( void )
 320     {
 321         UBaseType_t uxPriority;
 322
 323         for( uxPriority = 0; uxPriority < configMAX_CO_ROUTINE_PRIORITIES; uxPriority++ )
 324         {
 325             vListInitialise( ( List_t * ) &( pxReadyCoRoutineLists[ uxPriority ] ) );
 326         }
 327
 328         vListInitialise( ( List_t * ) &xDelayedCoRoutineList1 );
 329         vListInitialise( ( List_t * ) &xDelayedCoRoutineList2 );
 330         vListInitialise( ( List_t * ) &xPendingReadyCoRoutineList );
 331
 332         /* Start with pxDelayedCoRoutineList using list1 and the
 333          * pxOverflowDelayedCoRoutineList using list2. */
 334         pxDelayedCoRoutineList = &xDelayedCoRoutineList1;
 335         pxOverflowDelayedCoRoutineList = &xDelayedCoRoutineList2;
 336     }
 337 /*-----------------------------------------------------------*/
 338
 339     BaseType_t xCoRoutineRemoveFromEventList( const List_t * pxEventList )
 340     {
 341         CRCB_t * pxUnblockedCRCB;
 342         BaseType_t xReturn;
 343
 344         /* This function is called from within an interrupt.  It can only access
 345          * event lists and the pending ready list.  This function assumes that a
 346          * check has already been made to ensure pxEventList is not empty. */
 347         pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxEventList );
 348         ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
 349         vListInsertEnd( ( List_t * ) &( xPendingReadyCoRoutineList ), &( pxUnblockedCRCB->xEventListItem ) );
 350
 351         if( pxUnblockedCRCB->uxPriority >= pxCurrentCoRoutine->uxPriority )
 352         {
 353             xReturn = pdTRUE;
 354         }
 355         else
 356         {
 357             xReturn = pdFALSE;
 358         }
 359
 360         return xReturn;
 361     }
 362
 363 #endif /* configUSE_CO_ROUTINES == 0 */