begriffs open source - freertos/blob - croutine.c

   1 /*
   2  * FreeRTOS Kernel <DEVELOPMENT BRANCH>
   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         traceENTER_xCoRoutineCreate( pxCoRoutineCode, uxPriority, uxIndex );
 111
 112         /* Allocate the memory that will store the co-routine control block. */
 113         pxCoRoutine = ( CRCB_t * ) pvPortMalloc( sizeof( CRCB_t ) );
 114
 115         if( pxCoRoutine )
 116         {
 117             /* If pxCurrentCoRoutine is NULL then this is the first co-routine to
 118             * be created and the co-routine data structures need initialising. */
 119             if( pxCurrentCoRoutine == NULL )
 120             {
 121                 pxCurrentCoRoutine = pxCoRoutine;
 122                 prvInitialiseCoRoutineLists();
 123             }
 124
 125             /* Check the priority is within limits. */
 126             if( uxPriority >= configMAX_CO_ROUTINE_PRIORITIES )
 127             {
 128                 uxPriority = configMAX_CO_ROUTINE_PRIORITIES - 1;
 129             }
 130
 131             /* Fill out the co-routine control block from the function parameters. */
 132             pxCoRoutine->uxState = corINITIAL_STATE;
 133             pxCoRoutine->uxPriority = uxPriority;
 134             pxCoRoutine->uxIndex = uxIndex;
 135             pxCoRoutine->pxCoRoutineFunction = pxCoRoutineCode;
 136
 137             /* Initialise all the other co-routine control block parameters. */
 138             vListInitialiseItem( &( pxCoRoutine->xGenericListItem ) );
 139             vListInitialiseItem( &( pxCoRoutine->xEventListItem ) );
 140
 141             /* Set the co-routine control block as a link back from the ListItem_t.
 142              * This is so we can get back to the containing CRCB from a generic item
 143              * in a list. */
 144             listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xGenericListItem ), pxCoRoutine );
 145             listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xEventListItem ), pxCoRoutine );
 146
 147             /* Event lists are always in priority order. */
 148             listSET_LIST_ITEM_VALUE( &( pxCoRoutine->xEventListItem ), ( ( TickType_t ) configMAX_CO_ROUTINE_PRIORITIES - ( TickType_t ) uxPriority ) );
 149
 150             /* Now the co-routine has been initialised it can be added to the ready
 151              * list at the correct priority. */
 152             prvAddCoRoutineToReadyQueue( pxCoRoutine );
 153
 154             xReturn = pdPASS;
 155         }
 156         else
 157         {
 158             xReturn = errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY;
 159         }
 160
 161         traceRETURN_xCoRoutineCreate( xReturn );
 162
 163         return xReturn;
 164     }
 165 /*-----------------------------------------------------------*/
 166
 167     void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay,
 168                                      List_t * pxEventList )
 169     {
 170         TickType_t xTimeToWake;
 171
 172         traceENTER_vCoRoutineAddToDelayedList( xTicksToDelay, pxEventList );
 173
 174         /* Calculate the time to wake - this may overflow but this is
 175          * not a problem. */
 176         xTimeToWake = xCoRoutineTickCount + xTicksToDelay;
 177
 178         /* We must remove ourselves from the ready list before adding
 179          * ourselves to the blocked list as the same list item is used for
 180          * both lists. */
 181         ( void ) uxListRemove( ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 182
 183         /* The list item will be inserted in wake time order. */
 184         listSET_LIST_ITEM_VALUE( &( pxCurrentCoRoutine->xGenericListItem ), xTimeToWake );
 185
 186         if( xTimeToWake < xCoRoutineTickCount )
 187         {
 188             /* Wake time has overflowed.  Place this item in the
 189              * overflow list. */
 190             vListInsert( ( List_t * ) pxOverflowDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 191         }
 192         else
 193         {
 194             /* The wake time has not overflowed, so we can use the
 195              * current block list. */
 196             vListInsert( ( List_t * ) pxDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
 197         }
 198
 199         if( pxEventList )
 200         {
 201             /* Also add the co-routine to an event list.  If this is done then the
 202              * function must be called with interrupts disabled. */
 203             vListInsert( pxEventList, &( pxCurrentCoRoutine->xEventListItem ) );
 204         }
 205
 206         traceRETURN_vCoRoutineAddToDelayedList();
 207     }
 208 /*-----------------------------------------------------------*/
 209
 210     static void prvCheckPendingReadyList( void )
 211     {
 212         /* Are there any co-routines waiting to get moved to the ready list?  These
 213          * are co-routines that have been readied by an ISR.  The ISR cannot access
 214          * the ready lists itself. */
 215         while( listLIST_IS_EMPTY( &xPendingReadyCoRoutineList ) == pdFALSE )
 216         {
 217             CRCB_t * pxUnblockedCRCB;
 218
 219             /* The pending ready list can be accessed by an ISR. */
 220             portDISABLE_INTERRUPTS();
 221             {
 222                 pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( ( &xPendingReadyCoRoutineList ) );
 223                 ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
 224             }
 225             portENABLE_INTERRUPTS();
 226
 227             ( void ) uxListRemove( &( pxUnblockedCRCB->xGenericListItem ) );
 228             prvAddCoRoutineToReadyQueue( pxUnblockedCRCB );
 229         }
 230     }
 231 /*-----------------------------------------------------------*/
 232
 233     static void prvCheckDelayedList( void )
 234     {
 235         CRCB_t * pxCRCB;
 236
 237         xPassedTicks = xTaskGetTickCount() - xLastTickCount;
 238
 239         while( xPassedTicks )
 240         {
 241             xCoRoutineTickCount++;
 242             xPassedTicks--;
 243
 244             /* If the tick count has overflowed we need to swap the ready lists. */
 245             if( xCoRoutineTickCount == 0 )
 246             {
 247                 List_t * pxTemp;
 248
 249                 /* Tick count has overflowed so we need to swap the delay lists.  If there are
 250                  * any items in pxDelayedCoRoutineList here then there is an error! */
 251                 pxTemp = pxDelayedCoRoutineList;
 252                 pxDelayedCoRoutineList = pxOverflowDelayedCoRoutineList;
 253                 pxOverflowDelayedCoRoutineList = pxTemp;
 254             }
 255
 256             /* See if this tick has made a timeout expire. */
 257             while( listLIST_IS_EMPTY( pxDelayedCoRoutineList ) == pdFALSE )
 258             {
 259                 pxCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxDelayedCoRoutineList );
 260
 261                 if( xCoRoutineTickCount < listGET_LIST_ITEM_VALUE( &( pxCRCB->xGenericListItem ) ) )
 262                 {
 263                     /* Timeout not yet expired. */
 264                     break;
 265                 }
 266
 267                 portDISABLE_INTERRUPTS();
 268                 {
 269                     /* The event could have occurred just before this critical
 270                      *  section.  If this is the case then the generic list item will
 271                      *  have been moved to the pending ready list and the following
 272                      *  line is still valid.  Also the pvContainer parameter will have
 273                      *  been set to NULL so the following lines are also valid. */
 274                     ( void ) uxListRemove( &( pxCRCB->xGenericListItem ) );
 275
 276                     /* Is the co-routine waiting on an event also? */
 277                     if( pxCRCB->xEventListItem.pxContainer )
 278                     {
 279                         ( void ) uxListRemove( &( pxCRCB->xEventListItem ) );
 280                     }
 281                 }
 282                 portENABLE_INTERRUPTS();
 283
 284                 prvAddCoRoutineToReadyQueue( pxCRCB );
 285             }
 286         }
 287
 288         xLastTickCount = xCoRoutineTickCount;
 289     }
 290 /*-----------------------------------------------------------*/
 291
 292     void vCoRoutineSchedule( void )
 293     {
 294         traceENTER_vCoRoutineSchedule();
 295
 296         /* Only run a co-routine after prvInitialiseCoRoutineLists() has been
 297          * called.  prvInitialiseCoRoutineLists() is called automatically when a
 298          * co-routine is created. */
 299         if( pxDelayedCoRoutineList != NULL )
 300         {
 301             /* See if any co-routines readied by events need moving to the ready lists. */
 302             prvCheckPendingReadyList();
 303
 304             /* See if any delayed co-routines have timed out. */
 305             prvCheckDelayedList();
 306
 307             /* Find the highest priority queue that contains ready co-routines. */
 308             while( listLIST_IS_EMPTY( &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) ) )
 309             {
 310                 if( uxTopCoRoutineReadyPriority == 0 )
 311                 {
 312                     /* No more co-routines to check. */
 313                     return;
 314                 }
 315
 316                 --uxTopCoRoutineReadyPriority;
 317             }
 318
 319             /* listGET_OWNER_OF_NEXT_ENTRY walks through the list, so the co-routines
 320              * of the same priority get an equal share of the processor time. */
 321             listGET_OWNER_OF_NEXT_ENTRY( pxCurrentCoRoutine, &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) );
 322
 323             /* Call the co-routine. */
 324             ( pxCurrentCoRoutine->pxCoRoutineFunction )( pxCurrentCoRoutine, pxCurrentCoRoutine->uxIndex );
 325         }
 326
 327         traceRETURN_vCoRoutineSchedule();
 328     }
 329 /*-----------------------------------------------------------*/
 330
 331     static void prvInitialiseCoRoutineLists( void )
 332     {
 333         UBaseType_t uxPriority;
 334
 335         for( uxPriority = 0; uxPriority < configMAX_CO_ROUTINE_PRIORITIES; uxPriority++ )
 336         {
 337             vListInitialise( ( List_t * ) &( pxReadyCoRoutineLists[ uxPriority ] ) );
 338         }
 339
 340         vListInitialise( ( List_t * ) &xDelayedCoRoutineList1 );
 341         vListInitialise( ( List_t * ) &xDelayedCoRoutineList2 );
 342         vListInitialise( ( List_t * ) &xPendingReadyCoRoutineList );
 343
 344         /* Start with pxDelayedCoRoutineList using list1 and the
 345          * pxOverflowDelayedCoRoutineList using list2. */
 346         pxDelayedCoRoutineList = &xDelayedCoRoutineList1;
 347         pxOverflowDelayedCoRoutineList = &xDelayedCoRoutineList2;
 348     }
 349 /*-----------------------------------------------------------*/
 350
 351     BaseType_t xCoRoutineRemoveFromEventList( const List_t * pxEventList )
 352     {
 353         CRCB_t * pxUnblockedCRCB;
 354         BaseType_t xReturn;
 355
 356         traceENTER_xCoRoutineRemoveFromEventList( pxEventList );
 357
 358         /* This function is called from within an interrupt.  It can only access
 359          * event lists and the pending ready list.  This function assumes that a
 360          * check has already been made to ensure pxEventList is not empty. */
 361         pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxEventList );
 362         ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
 363         vListInsertEnd( ( List_t * ) &( xPendingReadyCoRoutineList ), &( pxUnblockedCRCB->xEventListItem ) );
 364
 365         if( pxUnblockedCRCB->uxPriority >= pxCurrentCoRoutine->uxPriority )
 366         {
 367             xReturn = pdTRUE;
 368         }
 369         else
 370         {
 371             xReturn = pdFALSE;
 372         }
 373
 374         traceRETURN_xCoRoutineRemoveFromEventList( xReturn );
 375
 376         return xReturn;
 377     }
 378
 379 #endif /* configUSE_CO_ROUTINES == 0 */