1 /* 2 * FreeRTOS Kernel V10.4.3 3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of 6 * this software and associated documentation files (the "Software"), to deal in 7 * the Software without restriction, including without limitation the rights to 8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 * the Software, and to permit persons to whom the Software is furnished to do so, 10 * subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in all 13 * copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 * 22 * https://www.FreeRTOS.org 23 * https://github.com/FreeRTOS 24 * 25 */ 26 27 /* 28 * This is the list implementation used by the scheduler. While it is tailored 29 * heavily for the schedulers needs, it is also available for use by 30 * application code. 31 * 32 * list_ts can only store pointers to list_item_ts. Each ListItem_t contains a 33 * numeric value (xItemValue). Most of the time the lists are sorted in 34 * descending item value order. 35 * 36 * Lists are created already containing one list item. The value of this 37 * item is the maximum possible that can be stored, it is therefore always at 38 * the end of the list and acts as a marker. The list member pxHead always 39 * points to this marker - even though it is at the tail of the list. This 40 * is because the tail contains a wrap back pointer to the true head of 41 * the list. 42 * 43 * In addition to it's value, each list item contains a pointer to the next 44 * item in the list (pxNext), a pointer to the list it is in (pxContainer) 45 * and a pointer to back to the object that contains it. These later two 46 * pointers are included for efficiency of list manipulation. There is 47 * effectively a two way link between the object containing the list item and 48 * the list item itself. 49 * 50 * 51 * \page ListIntroduction List Implementation 52 * \ingroup FreeRTOSIntro 53 */ 54 55 #ifndef INC_FREERTOS_H 56 #error "FreeRTOS.h must be included before list.h" 57 #endif 58 59 #ifndef LIST_H 60 #define LIST_H 61 62 /* 63 * The list structure members are modified from within interrupts, and therefore 64 * by rights should be declared volatile. However, they are only modified in a 65 * functionally atomic way (within critical sections of with the scheduler 66 * suspended) and are either passed by reference into a function or indexed via 67 * a volatile variable. Therefore, in all use cases tested so far, the volatile 68 * qualifier can be omitted in order to provide a moderate performance 69 * improvement without adversely affecting functional behaviour. The assembly 70 * instructions generated by the IAR, ARM and GCC compilers when the respective 71 * compiler's options were set for maximum optimisation has been inspected and 72 * deemed to be as intended. That said, as compiler technology advances, and 73 * especially if aggressive cross module optimisation is used (a use case that 74 * has not been exercised to any great extend) then it is feasible that the 75 * volatile qualifier will be needed for correct optimisation. It is expected 76 * that a compiler removing essential code because, without the volatile 77 * qualifier on the list structure members and with aggressive cross module 78 * optimisation, the compiler deemed the code unnecessary will result in 79 * complete and obvious failure of the scheduler. If this is ever experienced 80 * then the volatile qualifier can be inserted in the relevant places within the 81 * list structures by simply defining configLIST_VOLATILE to volatile in 82 * FreeRTOSConfig.h (as per the example at the bottom of this comment block). 83 * If configLIST_VOLATILE is not defined then the preprocessor directives below 84 * will simply #define configLIST_VOLATILE away completely. 85 * 86 * To use volatile list structure members then add the following line to 87 * FreeRTOSConfig.h (without the quotes): 88 * "#define configLIST_VOLATILE volatile" 89 */ 90 #ifndef configLIST_VOLATILE 91 #define configLIST_VOLATILE 92 #endif /* configSUPPORT_CROSS_MODULE_OPTIMISATION */ 93 94 /* *INDENT-OFF* */ 95 #ifdef __cplusplus 96 extern "C" { 97 #endif 98 /* *INDENT-ON* */ 99 100 /* Macros that can be used to place known values within the list structures, 101 * then check that the known values do not get corrupted during the execution of 102 * the application. These may catch the list data structures being overwritten in 103 * memory. They will not catch data errors caused by incorrect configuration or 104 * use of FreeRTOS.*/ 105 #if ( configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES == 0 ) 106 /* Define the macros to do nothing. */ 107 #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE 108 #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE 109 #define listFIRST_LIST_INTEGRITY_CHECK_VALUE 110 #define listSECOND_LIST_INTEGRITY_CHECK_VALUE 111 #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) 112 #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) 113 #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList ) 114 #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList ) 115 #define listTEST_LIST_ITEM_INTEGRITY( pxItem ) 116 #define listTEST_LIST_INTEGRITY( pxList ) 117 #else /* if ( configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES == 0 ) */ 118 /* Define macros that add new members into the list structures. */ 119 #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE TickType_t xListItemIntegrityValue1; 120 #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE TickType_t xListItemIntegrityValue2; 121 #define listFIRST_LIST_INTEGRITY_CHECK_VALUE TickType_t xListIntegrityValue1; 122 #define listSECOND_LIST_INTEGRITY_CHECK_VALUE TickType_t xListIntegrityValue2; 123 124 /* Define macros that set the new structure members to known values. */ 125 #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) ( pxItem )->xListItemIntegrityValue1 = pdINTEGRITY_CHECK_VALUE 126 #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) ( pxItem )->xListItemIntegrityValue2 = pdINTEGRITY_CHECK_VALUE 127 #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList ) ( pxList )->xListIntegrityValue1 = pdINTEGRITY_CHECK_VALUE 128 #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList ) ( pxList )->xListIntegrityValue2 = pdINTEGRITY_CHECK_VALUE 129 130 /* Define macros that will assert if one of the structure members does not 131 * contain its expected value. */ 132 #define listTEST_LIST_ITEM_INTEGRITY( pxItem ) configASSERT( ( ( pxItem )->xListItemIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxItem )->xListItemIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) ) 133 #define listTEST_LIST_INTEGRITY( pxList ) configASSERT( ( ( pxList )->xListIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxList )->xListIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) ) 134 #endif /* configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES */ 135 136 137 /* 138 * Definition of the only type of object that a list can contain. 139 */ 140 struct xLIST; 141 struct xLIST_ITEM 142 { 143 listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ 144 configLIST_VOLATILE TickType_t xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */ 145 struct xLIST_ITEM * configLIST_VOLATILE pxNext; /*< Pointer to the next ListItem_t in the list. */ 146 struct xLIST_ITEM * configLIST_VOLATILE pxPrevious; /*< Pointer to the previous ListItem_t in the list. */ 147 void * pvOwner; /*< Pointer to the object (normally a TCB) that contains the list item. There is therefore a two way link between the object containing the list item and the list item itself. */ 148 struct xLIST * configLIST_VOLATILE pxContainer; /*< Pointer to the list in which this list item is placed (if any). */ 149 listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ 150 }; 151 typedef struct xLIST_ITEM ListItem_t; /* For some reason lint wants this as two separate definitions. */ 152 153 struct xMINI_LIST_ITEM 154 { 155 listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ 156 configLIST_VOLATILE TickType_t xItemValue; 157 struct xLIST_ITEM * configLIST_VOLATILE pxNext; 158 struct xLIST_ITEM * configLIST_VOLATILE pxPrevious; 159 }; 160 typedef struct xMINI_LIST_ITEM MiniListItem_t; 161 162 /* 163 * Definition of the type of queue used by the scheduler. 164 */ 165 typedef struct xLIST 166 { 167 listFIRST_LIST_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ 168 volatile UBaseType_t uxNumberOfItems; 169 ListItem_t * configLIST_VOLATILE pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to listGET_OWNER_OF_NEXT_ENTRY (). */ 170 MiniListItem_t xListEnd; /*< List item that contains the maximum possible item value meaning it is always at the end of the list and is therefore used as a marker. */ 171 listSECOND_LIST_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ 172 } List_t; 173 174 /* 175 * Access macro to set the owner of a list item. The owner of a list item 176 * is the object (usually a TCB) that contains the list item. 177 * 178 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER 179 * \ingroup LinkedList 180 */ 181 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( ( pxListItem )->pvOwner = ( void * ) ( pxOwner ) ) 182 183 /* 184 * Access macro to get the owner of a list item. The owner of a list item 185 * is the object (usually a TCB) that contains the list item. 186 * 187 * \page listGET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER 188 * \ingroup LinkedList 189 */ 190 #define listGET_LIST_ITEM_OWNER( pxListItem ) ( ( pxListItem )->pvOwner ) 191 192 /* 193 * Access macro to set the value of the list item. In most cases the value is 194 * used to sort the list in descending order. 195 * 196 * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE 197 * \ingroup LinkedList 198 */ 199 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( ( pxListItem )->xItemValue = ( xValue ) ) 200 201 /* 202 * Access macro to retrieve the value of the list item. The value can 203 * represent anything - for example the priority of a task, or the time at 204 * which a task should be unblocked. 205 * 206 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE 207 * \ingroup LinkedList 208 */ 209 #define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue ) 210 211 /* 212 * Access macro to retrieve the value of the list item at the head of a given 213 * list. 214 * 215 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE 216 * \ingroup LinkedList 217 */ 218 #define listGET_ITEM_VALUE_OF_HEAD_ENTRY( pxList ) ( ( ( pxList )->xListEnd ).pxNext->xItemValue ) 219 220 /* 221 * Return the list item at the head of the list. 222 * 223 * \page listGET_HEAD_ENTRY listGET_HEAD_ENTRY 224 * \ingroup LinkedList 225 */ 226 #define listGET_HEAD_ENTRY( pxList ) ( ( ( pxList )->xListEnd ).pxNext ) 227 228 /* 229 * Return the next list item. 230 * 231 * \page listGET_NEXT listGET_NEXT 232 * \ingroup LinkedList 233 */ 234 #define listGET_NEXT( pxListItem ) ( ( pxListItem )->pxNext ) 235 236 /* 237 * Return the list item that marks the end of the list 238 * 239 * \page listGET_END_MARKER listGET_END_MARKER 240 * \ingroup LinkedList 241 */ 242 #define listGET_END_MARKER( pxList ) ( ( ListItem_t const * ) ( &( ( pxList )->xListEnd ) ) ) 243 244 /* 245 * Access macro to determine if a list contains any items. The macro will 246 * only have the value true if the list is empty. 247 * 248 * \page listLIST_IS_EMPTY listLIST_IS_EMPTY 249 * \ingroup LinkedList 250 */ 251 #define listLIST_IS_EMPTY( pxList ) ( ( ( pxList )->uxNumberOfItems == ( UBaseType_t ) 0 ) ? pdTRUE : pdFALSE ) 252 253 /* 254 * Access macro to return the number of items in the list. 255 */ 256 #define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems ) 257 258 /* 259 * Access function to obtain the owner of the next entry in a list. 260 * 261 * The list member pxIndex is used to walk through a list. Calling 262 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list 263 * and returns that entry's pxOwner parameter. Using multiple calls to this 264 * function it is therefore possible to move through every item contained in 265 * a list. 266 * 267 * The pxOwner parameter of a list item is a pointer to the object that owns 268 * the list item. In the scheduler this is normally a task control block. 269 * The pxOwner parameter effectively creates a two way link between the list 270 * item and its owner. 271 * 272 * @param pxTCB pxTCB is set to the address of the owner of the next list item. 273 * @param pxList The list from which the next item owner is to be returned. 274 * 275 * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY 276 * \ingroup LinkedList 277 */ 278 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \ 279 { \ 280 List_t * const pxConstList = ( pxList ); \ 281 /* Increment the index to the next item and return the item, ensuring */ \ 282 /* we don't return the marker used at the end of the list. */ \ 283 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ 284 if( ( void * ) ( pxConstList )->pxIndex == ( void * ) &( ( pxConstList )->xListEnd ) ) \ 285 { \ 286 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ 287 } \ 288 ( pxTCB ) = ( pxConstList )->pxIndex->pvOwner; \ 289 } 290 291 292 /* 293 * Access function to obtain the owner of the first entry in a list. Lists 294 * are normally sorted in ascending item value order. 295 * 296 * This function returns the pxOwner member of the first item in the list. 297 * The pxOwner parameter of a list item is a pointer to the object that owns 298 * the list item. In the scheduler this is normally a task control block. 299 * The pxOwner parameter effectively creates a two way link between the list 300 * item and its owner. 301 * 302 * @param pxList The list from which the owner of the head item is to be 303 * returned. 304 * 305 * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY 306 * \ingroup LinkedList 307 */ 308 #define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( ( &( ( pxList )->xListEnd ) )->pxNext->pvOwner ) 309 310 /* 311 * Check to see if a list item is within a list. The list item maintains a 312 * "container" pointer that points to the list it is in. All this macro does 313 * is check to see if the container and the list match. 314 * 315 * @param pxList The list we want to know if the list item is within. 316 * @param pxListItem The list item we want to know if is in the list. 317 * @return pdTRUE if the list item is in the list, otherwise pdFALSE. 318 */ 319 #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( ( pxListItem )->pxContainer == ( pxList ) ) ? ( pdTRUE ) : ( pdFALSE ) ) 320 321 /* 322 * Return the list a list item is contained within (referenced from). 323 * 324 * @param pxListItem The list item being queried. 325 * @return A pointer to the List_t object that references the pxListItem 326 */ 327 #define listLIST_ITEM_CONTAINER( pxListItem ) ( ( pxListItem )->pxContainer ) 328 329 /* 330 * This provides a crude means of knowing if a list has been initialised, as 331 * pxList->xListEnd.xItemValue is set to portMAX_DELAY by the vListInitialise() 332 * function. 333 */ 334 #define listLIST_IS_INITIALISED( pxList ) ( ( pxList )->xListEnd.xItemValue == portMAX_DELAY ) 335 336 /* 337 * Must be called before a list is used! This initialises all the members 338 * of the list structure and inserts the xListEnd item into the list as a 339 * marker to the back of the list. 340 * 341 * @param pxList Pointer to the list being initialised. 342 * 343 * \page vListInitialise vListInitialise 344 * \ingroup LinkedList 345 */ 346 void vListInitialise( List_t * const pxList ) PRIVILEGED_FUNCTION; 347 348 /* 349 * Must be called before a list item is used. This sets the list container to 350 * null so the item does not think that it is already contained in a list. 351 * 352 * @param pxItem Pointer to the list item being initialised. 353 * 354 * \page vListInitialiseItem vListInitialiseItem 355 * \ingroup LinkedList 356 */ 357 void vListInitialiseItem( ListItem_t * const pxItem ) PRIVILEGED_FUNCTION; 358 359 /* 360 * Insert a list item into a list. The item will be inserted into the list in 361 * a position determined by its item value (descending item value order). 362 * 363 * @param pxList The list into which the item is to be inserted. 364 * 365 * @param pxNewListItem The item that is to be placed in the list. 366 * 367 * \page vListInsert vListInsert 368 * \ingroup LinkedList 369 */ 370 void vListInsert( List_t * const pxList, 371 ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION; 372 373 /* 374 * Insert a list item into a list. The item will be inserted in a position 375 * such that it will be the last item within the list returned by multiple 376 * calls to listGET_OWNER_OF_NEXT_ENTRY. 377 * 378 * The list member pxIndex is used to walk through a list. Calling 379 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list. 380 * Placing an item in a list using vListInsertEnd effectively places the item 381 * in the list position pointed to by pxIndex. This means that every other 382 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before 383 * the pxIndex parameter again points to the item being inserted. 384 * 385 * @param pxList The list into which the item is to be inserted. 386 * 387 * @param pxNewListItem The list item to be inserted into the list. 388 * 389 * \page vListInsertEnd vListInsertEnd 390 * \ingroup LinkedList 391 */ 392 void vListInsertEnd( List_t * const pxList, 393 ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION; 394 395 /* 396 * Remove an item from a list. The list item has a pointer to the list that 397 * it is in, so only the list item need be passed into the function. 398 * 399 * @param uxListRemove The item to be removed. The item will remove itself from 400 * the list pointed to by it's pxContainer parameter. 401 * 402 * @return The number of items that remain in the list after the list item has 403 * been removed. 404 * 405 * \page uxListRemove uxListRemove 406 * \ingroup LinkedList 407 */ 408 UBaseType_t uxListRemove( ListItem_t * const pxItemToRemove ) PRIVILEGED_FUNCTION; 409 410 /* *INDENT-OFF* */ 411 #ifdef __cplusplus 412 } 413 #endif 414 /* *INDENT-ON* */ 415 416 #endif /* ifndef LIST_H */ 417
