begriffs open source - freertos/blob - croutine.c

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