croutine.c 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363
  1. /*
  2. * FreeRTOS Kernel V10.4.4
  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. #include "FreeRTOS.h"
  29. #include "task.h"
  30. #include "croutine.h"
  31. /* Remove the whole file is co-routines are not being used. */
  32. #if ( configUSE_CO_ROUTINES != 0 )
  33. /*
  34. * Some kernel aware debuggers require data to be viewed to be global, rather
  35. * than file scope.
  36. */
  37. #ifdef portREMOVE_STATIC_QUALIFIER
  38. #define static
  39. #endif
  40. /* Lists for ready and blocked co-routines. --------------------*/
  41. static List_t pxReadyCoRoutineLists[ configMAX_CO_ROUTINE_PRIORITIES ]; /*< Prioritised ready co-routines. */
  42. static List_t xDelayedCoRoutineList1; /*< Delayed co-routines. */
  43. static List_t xDelayedCoRoutineList2; /*< Delayed co-routines (two lists are used - one for delays that have overflowed the current tick count. */
  44. static List_t * pxDelayedCoRoutineList = NULL; /*< Points to the delayed co-routine list currently being used. */
  45. 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. */
  46. 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. */
  47. /* Other file private variables. --------------------------------*/
  48. CRCB_t * pxCurrentCoRoutine = NULL;
  49. static UBaseType_t uxTopCoRoutineReadyPriority = 0;
  50. static TickType_t xCoRoutineTickCount = 0, xLastTickCount = 0, xPassedTicks = 0;
  51. /* The initial state of the co-routine when it is created. */
  52. #define corINITIAL_STATE ( 0 )
  53. /*
  54. * Place the co-routine represented by pxCRCB into the appropriate ready queue
  55. * for the priority. It is inserted at the end of the list.
  56. *
  57. * This macro accesses the co-routine ready lists and therefore must not be
  58. * used from within an ISR.
  59. */
  60. #define prvAddCoRoutineToReadyQueue( pxCRCB ) \
  61. { \
  62. if( pxCRCB->uxPriority > uxTopCoRoutineReadyPriority ) \
  63. { \
  64. uxTopCoRoutineReadyPriority = pxCRCB->uxPriority; \
  65. } \
  66. vListInsertEnd( ( List_t * ) &( pxReadyCoRoutineLists[ pxCRCB->uxPriority ] ), &( pxCRCB->xGenericListItem ) ); \
  67. }
  68. /*
  69. * Utility to ready all the lists used by the scheduler. This is called
  70. * automatically upon the creation of the first co-routine.
  71. */
  72. static void prvInitialiseCoRoutineLists( void );
  73. /*
  74. * Co-routines that are readied by an interrupt cannot be placed directly into
  75. * the ready lists (there is no mutual exclusion). Instead they are placed in
  76. * in the pending ready list in order that they can later be moved to the ready
  77. * list by the co-routine scheduler.
  78. */
  79. static void prvCheckPendingReadyList( void );
  80. /*
  81. * Macro that looks at the list of co-routines that are currently delayed to
  82. * see if any require waking.
  83. *
  84. * Co-routines are stored in the queue in the order of their wake time -
  85. * meaning once one co-routine has been found whose timer has not expired
  86. * we need not look any further down the list.
  87. */
  88. static void prvCheckDelayedList( void );
  89. /*-----------------------------------------------------------*/
  90. BaseType_t xCoRoutineCreate( crCOROUTINE_CODE pxCoRoutineCode,
  91. UBaseType_t uxPriority,
  92. UBaseType_t uxIndex )
  93. {
  94. BaseType_t xReturn;
  95. CRCB_t * pxCoRoutine;
  96. /* Allocate the memory that will store the co-routine control block. */
  97. pxCoRoutine = ( CRCB_t * ) pvPortMalloc( sizeof( CRCB_t ) );
  98. if( pxCoRoutine )
  99. {
  100. /* If pxCurrentCoRoutine is NULL then this is the first co-routine to
  101. * be created and the co-routine data structures need initialising. */
  102. if( pxCurrentCoRoutine == NULL )
  103. {
  104. pxCurrentCoRoutine = pxCoRoutine;
  105. prvInitialiseCoRoutineLists();
  106. }
  107. /* Check the priority is within limits. */
  108. if( uxPriority >= configMAX_CO_ROUTINE_PRIORITIES )
  109. {
  110. uxPriority = configMAX_CO_ROUTINE_PRIORITIES - 1;
  111. }
  112. /* Fill out the co-routine control block from the function parameters. */
  113. pxCoRoutine->uxState = corINITIAL_STATE;
  114. pxCoRoutine->uxPriority = uxPriority;
  115. pxCoRoutine->uxIndex = uxIndex;
  116. pxCoRoutine->pxCoRoutineFunction = pxCoRoutineCode;
  117. /* Initialise all the other co-routine control block parameters. */
  118. vListInitialiseItem( &( pxCoRoutine->xGenericListItem ) );
  119. vListInitialiseItem( &( pxCoRoutine->xEventListItem ) );
  120. /* Set the co-routine control block as a link back from the ListItem_t.
  121. * This is so we can get back to the containing CRCB from a generic item
  122. * in a list. */
  123. listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xGenericListItem ), pxCoRoutine );
  124. listSET_LIST_ITEM_OWNER( &( pxCoRoutine->xEventListItem ), pxCoRoutine );
  125. /* Event lists are always in priority order. */
  126. listSET_LIST_ITEM_VALUE( &( pxCoRoutine->xEventListItem ), ( ( TickType_t ) configMAX_CO_ROUTINE_PRIORITIES - ( TickType_t ) uxPriority ) );
  127. /* Now the co-routine has been initialised it can be added to the ready
  128. * list at the correct priority. */
  129. prvAddCoRoutineToReadyQueue( pxCoRoutine );
  130. xReturn = pdPASS;
  131. }
  132. else
  133. {
  134. xReturn = errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY;
  135. }
  136. return xReturn;
  137. }
  138. /*-----------------------------------------------------------*/
  139. void vCoRoutineAddToDelayedList( TickType_t xTicksToDelay,
  140. List_t * pxEventList )
  141. {
  142. TickType_t xTimeToWake;
  143. /* Calculate the time to wake - this may overflow but this is
  144. * not a problem. */
  145. xTimeToWake = xCoRoutineTickCount + xTicksToDelay;
  146. /* We must remove ourselves from the ready list before adding
  147. * ourselves to the blocked list as the same list item is used for
  148. * both lists. */
  149. ( void ) uxListRemove( ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
  150. /* The list item will be inserted in wake time order. */
  151. listSET_LIST_ITEM_VALUE( &( pxCurrentCoRoutine->xGenericListItem ), xTimeToWake );
  152. if( xTimeToWake < xCoRoutineTickCount )
  153. {
  154. /* Wake time has overflowed. Place this item in the
  155. * overflow list. */
  156. vListInsert( ( List_t * ) pxOverflowDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
  157. }
  158. else
  159. {
  160. /* The wake time has not overflowed, so we can use the
  161. * current block list. */
  162. vListInsert( ( List_t * ) pxDelayedCoRoutineList, ( ListItem_t * ) &( pxCurrentCoRoutine->xGenericListItem ) );
  163. }
  164. if( pxEventList )
  165. {
  166. /* Also add the co-routine to an event list. If this is done then the
  167. * function must be called with interrupts disabled. */
  168. vListInsert( pxEventList, &( pxCurrentCoRoutine->xEventListItem ) );
  169. }
  170. }
  171. /*-----------------------------------------------------------*/
  172. static void prvCheckPendingReadyList( void )
  173. {
  174. /* Are there any co-routines waiting to get moved to the ready list? These
  175. * are co-routines that have been readied by an ISR. The ISR cannot access
  176. * the ready lists itself. */
  177. while( listLIST_IS_EMPTY( &xPendingReadyCoRoutineList ) == pdFALSE )
  178. {
  179. CRCB_t * pxUnblockedCRCB;
  180. /* The pending ready list can be accessed by an ISR. */
  181. portDISABLE_INTERRUPTS();
  182. {
  183. pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( ( &xPendingReadyCoRoutineList ) );
  184. ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
  185. }
  186. portENABLE_INTERRUPTS();
  187. ( void ) uxListRemove( &( pxUnblockedCRCB->xGenericListItem ) );
  188. prvAddCoRoutineToReadyQueue( pxUnblockedCRCB );
  189. }
  190. }
  191. /*-----------------------------------------------------------*/
  192. static void prvCheckDelayedList( void )
  193. {
  194. CRCB_t * pxCRCB;
  195. xPassedTicks = xTaskGetTickCount() - xLastTickCount;
  196. while( xPassedTicks )
  197. {
  198. xCoRoutineTickCount++;
  199. xPassedTicks--;
  200. /* If the tick count has overflowed we need to swap the ready lists. */
  201. if( xCoRoutineTickCount == 0 )
  202. {
  203. List_t * pxTemp;
  204. /* Tick count has overflowed so we need to swap the delay lists. If there are
  205. * any items in pxDelayedCoRoutineList here then there is an error! */
  206. pxTemp = pxDelayedCoRoutineList;
  207. pxDelayedCoRoutineList = pxOverflowDelayedCoRoutineList;
  208. pxOverflowDelayedCoRoutineList = pxTemp;
  209. }
  210. /* See if this tick has made a timeout expire. */
  211. while( listLIST_IS_EMPTY( pxDelayedCoRoutineList ) == pdFALSE )
  212. {
  213. pxCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxDelayedCoRoutineList );
  214. if( xCoRoutineTickCount < listGET_LIST_ITEM_VALUE( &( pxCRCB->xGenericListItem ) ) )
  215. {
  216. /* Timeout not yet expired. */
  217. break;
  218. }
  219. portDISABLE_INTERRUPTS();
  220. {
  221. /* The event could have occurred just before this critical
  222. * section. If this is the case then the generic list item will
  223. * have been moved to the pending ready list and the following
  224. * line is still valid. Also the pvContainer parameter will have
  225. * been set to NULL so the following lines are also valid. */
  226. ( void ) uxListRemove( &( pxCRCB->xGenericListItem ) );
  227. /* Is the co-routine waiting on an event also? */
  228. if( pxCRCB->xEventListItem.pxContainer )
  229. {
  230. ( void ) uxListRemove( &( pxCRCB->xEventListItem ) );
  231. }
  232. }
  233. portENABLE_INTERRUPTS();
  234. prvAddCoRoutineToReadyQueue( pxCRCB );
  235. }
  236. }
  237. xLastTickCount = xCoRoutineTickCount;
  238. }
  239. /*-----------------------------------------------------------*/
  240. void vCoRoutineSchedule( void )
  241. {
  242. /* Only run a co-routine after prvInitialiseCoRoutineLists() has been
  243. * called. prvInitialiseCoRoutineLists() is called automatically when a
  244. * co-routine is created. */
  245. if( pxDelayedCoRoutineList != NULL )
  246. {
  247. /* See if any co-routines readied by events need moving to the ready lists. */
  248. prvCheckPendingReadyList();
  249. /* See if any delayed co-routines have timed out. */
  250. prvCheckDelayedList();
  251. /* Find the highest priority queue that contains ready co-routines. */
  252. while( listLIST_IS_EMPTY( &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) ) )
  253. {
  254. if( uxTopCoRoutineReadyPriority == 0 )
  255. {
  256. /* No more co-routines to check. */
  257. return;
  258. }
  259. --uxTopCoRoutineReadyPriority;
  260. }
  261. /* listGET_OWNER_OF_NEXT_ENTRY walks through the list, so the co-routines
  262. * of the same priority get an equal share of the processor time. */
  263. listGET_OWNER_OF_NEXT_ENTRY( pxCurrentCoRoutine, &( pxReadyCoRoutineLists[ uxTopCoRoutineReadyPriority ] ) );
  264. /* Call the co-routine. */
  265. ( pxCurrentCoRoutine->pxCoRoutineFunction )( pxCurrentCoRoutine, pxCurrentCoRoutine->uxIndex );
  266. }
  267. }
  268. /*-----------------------------------------------------------*/
  269. static void prvInitialiseCoRoutineLists( void )
  270. {
  271. UBaseType_t uxPriority;
  272. for( uxPriority = 0; uxPriority < configMAX_CO_ROUTINE_PRIORITIES; uxPriority++ )
  273. {
  274. vListInitialise( ( List_t * ) &( pxReadyCoRoutineLists[ uxPriority ] ) );
  275. }
  276. vListInitialise( ( List_t * ) &xDelayedCoRoutineList1 );
  277. vListInitialise( ( List_t * ) &xDelayedCoRoutineList2 );
  278. vListInitialise( ( List_t * ) &xPendingReadyCoRoutineList );
  279. /* Start with pxDelayedCoRoutineList using list1 and the
  280. * pxOverflowDelayedCoRoutineList using list2. */
  281. pxDelayedCoRoutineList = &xDelayedCoRoutineList1;
  282. pxOverflowDelayedCoRoutineList = &xDelayedCoRoutineList2;
  283. }
  284. /*-----------------------------------------------------------*/
  285. BaseType_t xCoRoutineRemoveFromEventList( const List_t * pxEventList )
  286. {
  287. CRCB_t * pxUnblockedCRCB;
  288. BaseType_t xReturn;
  289. /* This function is called from within an interrupt. It can only access
  290. * event lists and the pending ready list. This function assumes that a
  291. * check has already been made to ensure pxEventList is not empty. */
  292. pxUnblockedCRCB = ( CRCB_t * ) listGET_OWNER_OF_HEAD_ENTRY( pxEventList );
  293. ( void ) uxListRemove( &( pxUnblockedCRCB->xEventListItem ) );
  294. vListInsertEnd( ( List_t * ) &( xPendingReadyCoRoutineList ), &( pxUnblockedCRCB->xEventListItem ) );
  295. if( pxUnblockedCRCB->uxPriority >= pxCurrentCoRoutine->uxPriority )
  296. {
  297. xReturn = pdTRUE;
  298. }
  299. else
  300. {
  301. xReturn = pdFALSE;
  302. }
  303. return xReturn;
  304. }
  305. #endif /* configUSE_CO_ROUTINES == 0 */