begriffs open source - freertos/blob - include/list.h

   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 /*\r
  30  * This is the list implementation used by the scheduler.  While it is tailored\r
  31  * heavily for the schedulers needs, it is also available for use by\r
  32  * application code.\r
  33  *\r
  34  * list_ts can only store pointers to list_item_ts.  Each ListItem_t contains a\r
  35  * numeric value (xItemValue).  Most of the time the lists are sorted in\r
  36  * ascending item value order.\r
  37  *\r
  38  * Lists are created already containing one list item.  The value of this\r
  39  * item is the maximum possible that can be stored, it is therefore always at\r
  40  * the end of the list and acts as a marker.  The list member pxHead always\r
  41  * points to this marker - even though it is at the tail of the list.  This\r
  42  * is because the tail contains a wrap back pointer to the true head of\r
  43  * the list.\r
  44  *\r
  45  * In addition to it's value, each list item contains a pointer to the next\r
  46  * item in the list (pxNext), a pointer to the list it is in (pxContainer)\r
  47  * and a pointer to back to the object that contains it.  These later two\r
  48  * pointers are included for efficiency of list manipulation.  There is\r
  49  * effectively a two way link between the object containing the list item and\r
  50  * the list item itself.\r
  51  *\r
  52  *\r
  53  * \page ListIntroduction List Implementation\r
  54  * \ingroup FreeRTOSIntro\r
  55  */\r
  56 \r
  57 \r
  58 #ifndef LIST_H\r
  59 #define LIST_H\r
  60 \r
  61 #ifndef INC_FREERTOS_H\r
  62     #error "FreeRTOS.h must be included before list.h"\r
  63 #endif\r
  64 \r
  65 /*\r
  66  * The list structure members are modified from within interrupts, and therefore\r
  67  * by rights should be declared volatile.  However, they are only modified in a\r
  68  * functionally atomic way (within critical sections of with the scheduler\r
  69  * suspended) and are either passed by reference into a function or indexed via\r
  70  * a volatile variable.  Therefore, in all use cases tested so far, the volatile\r
  71  * qualifier can be omitted in order to provide a moderate performance\r
  72  * improvement without adversely affecting functional behaviour.  The assembly\r
  73  * instructions generated by the IAR, ARM and GCC compilers when the respective\r
  74  * compiler's options were set for maximum optimisation has been inspected and\r
  75  * deemed to be as intended.  That said, as compiler technology advances, and\r
  76  * especially if aggressive cross module optimisation is used (a use case that\r
  77  * has not been exercised to any great extend) then it is feasible that the\r
  78  * volatile qualifier will be needed for correct optimisation.  It is expected\r
  79  * that a compiler removing essential code because, without the volatile\r
  80  * qualifier on the list structure members and with aggressive cross module\r
  81  * optimisation, the compiler deemed the code unnecessary will result in\r
  82  * complete and obvious failure of the scheduler.  If this is ever experienced\r
  83  * then the volatile qualifier can be inserted in the relevant places within the\r
  84  * list structures by simply defining configLIST_VOLATILE to volatile in\r
  85  * FreeRTOSConfig.h (as per the example at the bottom of this comment block).\r
  86  * If configLIST_VOLATILE is not defined then the preprocessor directives below\r
  87  * will simply #define configLIST_VOLATILE away completely.\r
  88  *\r
  89  * To use volatile list structure members then add the following line to\r
  90  * FreeRTOSConfig.h (without the quotes):\r
  91  * "#define configLIST_VOLATILE volatile"\r
  92  */\r
  93 #ifndef configLIST_VOLATILE\r
  94     #define configLIST_VOLATILE\r
  95 #endif /* configSUPPORT_CROSS_MODULE_OPTIMISATION */\r
  96 \r
  97 /* *INDENT-OFF* */\r
  98 #ifdef __cplusplus\r
  99     extern "C" {\r
 100 #endif\r
 101 /* *INDENT-ON* */\r
 102 \r
 103 /* Macros that can be used to place known values within the list structures,\r
 104  * then check that the known values do not get corrupted during the execution of\r
 105  * the application.   These may catch the list data structures being overwritten in\r
 106  * memory.  They will not catch data errors caused by incorrect configuration or\r
 107  * use of FreeRTOS.*/\r
 108 #if ( configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES == 0 )\r
 109     /* Define the macros to do nothing. */\r
 110     #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE\r
 111     #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE\r
 112     #define listFIRST_LIST_INTEGRITY_CHECK_VALUE\r
 113     #define listSECOND_LIST_INTEGRITY_CHECK_VALUE\r
 114     #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem )\r
 115     #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem )\r
 116     #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList )\r
 117     #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList )\r
 118     #define listTEST_LIST_ITEM_INTEGRITY( pxItem )\r
 119     #define listTEST_LIST_INTEGRITY( pxList )\r
 120 #else /* if ( configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES == 0 ) */\r
 121     /* Define macros that add new members into the list structures. */\r
 122     #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE     TickType_t xListItemIntegrityValue1;\r
 123     #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE    TickType_t xListItemIntegrityValue2;\r
 124     #define listFIRST_LIST_INTEGRITY_CHECK_VALUE          TickType_t xListIntegrityValue1;\r
 125     #define listSECOND_LIST_INTEGRITY_CHECK_VALUE         TickType_t xListIntegrityValue2;\r
 126 \r
 127 /* Define macros that set the new structure members to known values. */\r
 128     #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem )     ( pxItem )->xListItemIntegrityValue1 = pdINTEGRITY_CHECK_VALUE\r
 129     #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem )    ( pxItem )->xListItemIntegrityValue2 = pdINTEGRITY_CHECK_VALUE\r
 130     #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList )              ( pxList )->xListIntegrityValue1 = pdINTEGRITY_CHECK_VALUE\r
 131     #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList )              ( pxList )->xListIntegrityValue2 = pdINTEGRITY_CHECK_VALUE\r
 132 \r
 133 /* Define macros that will assert if one of the structure members does not\r
 134  * contain its expected value. */\r
 135     #define listTEST_LIST_ITEM_INTEGRITY( pxItem )                      configASSERT( ( ( pxItem )->xListItemIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxItem )->xListItemIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) )\r
 136     #define listTEST_LIST_INTEGRITY( pxList )                           configASSERT( ( ( pxList )->xListIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxList )->xListIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) )\r
 137 #endif /* configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES */\r
 138 \r
 139 \r
 140 /*\r
 141  * Definition of the only type of object that a list can contain.\r
 142  */\r
 143 struct xLIST;\r
 144 struct xLIST_ITEM\r
 145 {\r
 146     listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE           /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */\r
 147     configLIST_VOLATILE TickType_t xItemValue;          /*< The value being listed.  In most cases this is used to sort the list in ascending order. */\r
 148     struct xLIST_ITEM * configLIST_VOLATILE pxNext;     /*< Pointer to the next ListItem_t in the list. */\r
 149     struct xLIST_ITEM * configLIST_VOLATILE pxPrevious; /*< Pointer to the previous ListItem_t in the list. */\r
 150     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. */\r
 151     struct xLIST * configLIST_VOLATILE pxContainer;     /*< Pointer to the list in which this list item is placed (if any). */\r
 152     listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE          /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */\r
 153 };\r
 154 typedef struct xLIST_ITEM ListItem_t;                   /* For some reason lint wants this as two separate definitions. */\r
 155 \r
 156 #if ( configUSE_MINI_LIST_ITEM == 1 )\r
 157     struct xMINI_LIST_ITEM\r
 158     {\r
 159         listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */\r
 160         configLIST_VOLATILE TickType_t xItemValue;\r
 161         struct xLIST_ITEM * configLIST_VOLATILE pxNext;\r
 162         struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;\r
 163     };\r
 164     typedef struct xMINI_LIST_ITEM MiniListItem_t;\r
 165 #else\r
 166     typedef struct xLIST_ITEM      MiniListItem_t;\r
 167 #endif\r
 168 \r
 169 /*\r
 170  * Definition of the type of queue used by the scheduler.\r
 171  */\r
 172 typedef struct xLIST\r
 173 {\r
 174     listFIRST_LIST_INTEGRITY_CHECK_VALUE      /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */\r
 175     volatile UBaseType_t uxNumberOfItems;\r
 176     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 (). */\r
 177     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. */\r
 178     listSECOND_LIST_INTEGRITY_CHECK_VALUE     /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */\r
 179 } List_t;\r
 180 \r
 181 /*\r
 182  * Access macro to set the owner of a list item.  The owner of a list item\r
 183  * is the object (usually a TCB) that contains the list item.\r
 184  *\r
 185  * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER\r
 186  * \ingroup LinkedList\r
 187  */\r
 188 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner )    ( ( pxListItem )->pvOwner = ( void * ) ( pxOwner ) )\r
 189 \r
 190 /*\r
 191  * Access macro to get the owner of a list item.  The owner of a list item\r
 192  * is the object (usually a TCB) that contains the list item.\r
 193  *\r
 194  * \page listGET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER\r
 195  * \ingroup LinkedList\r
 196  */\r
 197 #define listGET_LIST_ITEM_OWNER( pxListItem )             ( ( pxListItem )->pvOwner )\r
 198 \r
 199 /*\r
 200  * Access macro to set the value of the list item.  In most cases the value is\r
 201  * used to sort the list in ascending order.\r
 202  *\r
 203  * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE\r
 204  * \ingroup LinkedList\r
 205  */\r
 206 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue )     ( ( pxListItem )->xItemValue = ( xValue ) )\r
 207 \r
 208 /*\r
 209  * Access macro to retrieve the value of the list item.  The value can\r
 210  * represent anything - for example the priority of a task, or the time at\r
 211  * which a task should be unblocked.\r
 212  *\r
 213  * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE\r
 214  * \ingroup LinkedList\r
 215  */\r
 216 #define listGET_LIST_ITEM_VALUE( pxListItem )             ( ( pxListItem )->xItemValue )\r
 217 \r
 218 /*\r
 219  * Access macro to retrieve the value of the list item at the head of a given\r
 220  * list.\r
 221  *\r
 222  * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE\r
 223  * \ingroup LinkedList\r
 224  */\r
 225 #define listGET_ITEM_VALUE_OF_HEAD_ENTRY( pxList )        ( ( ( pxList )->xListEnd ).pxNext->xItemValue )\r
 226 \r
 227 /*\r
 228  * Return the list item at the head of the list.\r
 229  *\r
 230  * \page listGET_HEAD_ENTRY listGET_HEAD_ENTRY\r
 231  * \ingroup LinkedList\r
 232  */\r
 233 #define listGET_HEAD_ENTRY( pxList )                      ( ( ( pxList )->xListEnd ).pxNext )\r
 234 \r
 235 /*\r
 236  * Return the next list item.\r
 237  *\r
 238  * \page listGET_NEXT listGET_NEXT\r
 239  * \ingroup LinkedList\r
 240  */\r
 241 #define listGET_NEXT( pxListItem )                        ( ( pxListItem )->pxNext )\r
 242 \r
 243 /*\r
 244  * Return the list item that marks the end of the list\r
 245  *\r
 246  * \page listGET_END_MARKER listGET_END_MARKER\r
 247  * \ingroup LinkedList\r
 248  */\r
 249 #define listGET_END_MARKER( pxList )                      ( ( ListItem_t const * ) ( &( ( pxList )->xListEnd ) ) )\r
 250 \r
 251 /*\r
 252  * Access macro to determine if a list contains any items.  The macro will\r
 253  * only have the value true if the list is empty.\r
 254  *\r
 255  * \page listLIST_IS_EMPTY listLIST_IS_EMPTY\r
 256  * \ingroup LinkedList\r
 257  */\r
 258 #define listLIST_IS_EMPTY( pxList )                       ( ( ( pxList )->uxNumberOfItems == ( UBaseType_t ) 0 ) ? pdTRUE : pdFALSE )\r
 259 \r
 260 /*\r
 261  * Access macro to return the number of items in the list.\r
 262  */\r
 263 #define listCURRENT_LIST_LENGTH( pxList )                 ( ( pxList )->uxNumberOfItems )\r
 264 \r
 265 /*\r
 266  * Access function to obtain the owner of the next entry in a list.\r
 267  *\r
 268  * The list member pxIndex is used to walk through a list.  Calling\r
 269  * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list\r
 270  * and returns that entry's pxOwner parameter.  Using multiple calls to this\r
 271  * function it is therefore possible to move through every item contained in\r
 272  * a list.\r
 273  *\r
 274  * The pxOwner parameter of a list item is a pointer to the object that owns\r
 275  * the list item.  In the scheduler this is normally a task control block.\r
 276  * The pxOwner parameter effectively creates a two way link between the list\r
 277  * item and its owner.\r
 278  *\r
 279  * @param pxTCB pxTCB is set to the address of the owner of the next list item.\r
 280  * @param pxList The list from which the next item owner is to be returned.\r
 281  *\r
 282  * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY\r
 283  * \ingroup LinkedList\r
 284  */\r
 285 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList )                                           \\r
 286     {                                                                                          \\r
 287         List_t * const pxConstList = ( pxList );                                               \\r
 288         /* Increment the index to the next item and return the item, ensuring */               \\r
 289         /* we don't return the marker used at the end of the list.  */                         \\r
 290         ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                           \\r
 291         if( ( void * ) ( pxConstList )->pxIndex == ( void * ) &( ( pxConstList )->xListEnd ) ) \\r
 292         {                                                                                      \\r
 293             ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                       \\r
 294         }                                                                                      \\r
 295         ( pxTCB ) = ( pxConstList )->pxIndex->pvOwner;                                         \\r
 296     }\r
 297 \r
 298 /*\r
 299  * Version of uxListRemove() that does not return a value.  Provided as a slight\r
 300  * optimisation for xTaskIncrementTick() by being inline.\r
 301  *\r
 302  * Remove an item from a list.  The list item has a pointer to the list that\r
 303  * it is in, so only the list item need be passed into the function.\r
 304  *\r
 305  * @param uxListRemove The item to be removed.  The item will remove itself from\r
 306  * the list pointed to by it's pxContainer parameter.\r
 307  *\r
 308  * @return The number of items that remain in the list after the list item has\r
 309  * been removed.\r
 310  *\r
 311  * \page listREMOVE_ITEM listREMOVE_ITEM\r
 312  * \ingroup LinkedList\r
 313  */\r
 314 #define listREMOVE_ITEM( pxItemToRemove ) \\r
 315     {                                     \\r
 316         /* The list item knows which list it is in.  Obtain the list from the list \\r
 317          * item. */                                                              \\r
 318         List_t * const pxList = ( pxItemToRemove )->pxContainer;                 \\r
 319                                                                                  \\r
 320         ( pxItemToRemove )->pxNext->pxPrevious = ( pxItemToRemove )->pxPrevious; \\r
 321         ( pxItemToRemove )->pxPrevious->pxNext = ( pxItemToRemove )->pxNext;     \\r
 322         /* Make sure the index is left pointing to a valid item. */              \\r
 323         if( pxList->pxIndex == ( pxItemToRemove ) )                              \\r
 324         {                                                                        \\r
 325             pxList->pxIndex = ( pxItemToRemove )->pxPrevious;                    \\r
 326         }                                                                        \\r
 327                                                                                  \\r
 328         ( pxItemToRemove )->pxContainer = NULL;                                  \\r
 329         ( pxList->uxNumberOfItems )--;                                           \\r
 330     }\r
 331 \r
 332 /*\r
 333  * Inline version of vListInsertEnd() to provide slight optimisation for\r
 334  * xTaskIncrementTick().\r
 335  *\r
 336  * Insert a list item into a list.  The item will be inserted in a position\r
 337  * such that it will be the last item within the list returned by multiple\r
 338  * calls to listGET_OWNER_OF_NEXT_ENTRY.\r
 339  *\r
 340  * The list member pxIndex is used to walk through a list.  Calling\r
 341  * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list.\r
 342  * Placing an item in a list using vListInsertEnd effectively places the item\r
 343  * in the list position pointed to by pxIndex.  This means that every other\r
 344  * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before\r
 345  * the pxIndex parameter again points to the item being inserted.\r
 346  *\r
 347  * @param pxList The list into which the item is to be inserted.\r
 348  *\r
 349  * @param pxNewListItem The list item to be inserted into the list.\r
 350  *\r
 351  * \page listINSERT_END listINSERT_END\r
 352  * \ingroup LinkedList\r
 353  */\r
 354 #define listINSERT_END( pxList, pxNewListItem )           \\r
 355     {                                                     \\r
 356         ListItem_t * const pxIndex = ( pxList )->pxIndex; \\r
 357                                                           \\r
 358         /* Only effective when configASSERT() is also defined, these tests may catch \\r
 359          * the list data structures being overwritten in memory.  They will not catch \\r
 360          * data errors caused by incorrect configuration or use of FreeRTOS. */ \\r
 361         listTEST_LIST_INTEGRITY( ( pxList ) );                                  \\r
 362         listTEST_LIST_ITEM_INTEGRITY( ( pxNewListItem ) );                      \\r
 363                                                                                 \\r
 364         /* Insert a new list item into ( pxList ), but rather than sort the list, \\r
 365          * makes the new list item the last item to be removed by a call to \\r
 366          * listGET_OWNER_OF_NEXT_ENTRY(). */                 \\r
 367         ( pxNewListItem )->pxNext = pxIndex;                 \\r
 368         ( pxNewListItem )->pxPrevious = pxIndex->pxPrevious; \\r
 369                                                              \\r
 370         pxIndex->pxPrevious->pxNext = ( pxNewListItem );     \\r
 371         pxIndex->pxPrevious = ( pxNewListItem );             \\r
 372                                                              \\r
 373         /* Remember which list the item is in. */            \\r
 374         ( pxNewListItem )->pxContainer = ( pxList );         \\r
 375                                                              \\r
 376         ( ( pxList )->uxNumberOfItems )++;                   \\r
 377     }\r
 378 \r
 379 /*\r
 380  * Access function to obtain the owner of the first entry in a list.  Lists\r
 381  * are normally sorted in ascending item value order.\r
 382  *\r
 383  * This function returns the pxOwner member of the first item in the list.\r
 384  * The pxOwner parameter of a list item is a pointer to the object that owns\r
 385  * the list item.  In the scheduler this is normally a task control block.\r
 386  * The pxOwner parameter effectively creates a two way link between the list\r
 387  * item and its owner.\r
 388  *\r
 389  * @param pxList The list from which the owner of the head item is to be\r
 390  * returned.\r
 391  *\r
 392  * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY\r
 393  * \ingroup LinkedList\r
 394  */\r
 395 #define listGET_OWNER_OF_HEAD_ENTRY( pxList )            ( ( &( ( pxList )->xListEnd ) )->pxNext->pvOwner )\r
 396 \r
 397 /*\r
 398  * Check to see if a list item is within a list.  The list item maintains a\r
 399  * "container" pointer that points to the list it is in.  All this macro does\r
 400  * is check to see if the container and the list match.\r
 401  *\r
 402  * @param pxList The list we want to know if the list item is within.\r
 403  * @param pxListItem The list item we want to know if is in the list.\r
 404  * @return pdTRUE if the list item is in the list, otherwise pdFALSE.\r
 405  */\r
 406 #define listIS_CONTAINED_WITHIN( pxList, pxListItem )    ( ( ( pxListItem )->pxContainer == ( pxList ) ) ? ( pdTRUE ) : ( pdFALSE ) )\r
 407 \r
 408 /*\r
 409  * Return the list a list item is contained within (referenced from).\r
 410  *\r
 411  * @param pxListItem The list item being queried.\r
 412  * @return A pointer to the List_t object that references the pxListItem\r
 413  */\r
 414 #define listLIST_ITEM_CONTAINER( pxListItem )            ( ( pxListItem )->pxContainer )\r
 415 \r
 416 /*\r
 417  * This provides a crude means of knowing if a list has been initialised, as\r
 418  * pxList->xListEnd.xItemValue is set to portMAX_DELAY by the vListInitialise()\r
 419  * function.\r
 420  */\r
 421 #define listLIST_IS_INITIALISED( pxList )                ( ( pxList )->xListEnd.xItemValue == portMAX_DELAY )\r
 422 \r
 423 /*\r
 424  * Must be called before a list is used!  This initialises all the members\r
 425  * of the list structure and inserts the xListEnd item into the list as a\r
 426  * marker to the back of the list.\r
 427  *\r
 428  * @param pxList Pointer to the list being initialised.\r
 429  *\r
 430  * \page vListInitialise vListInitialise\r
 431  * \ingroup LinkedList\r
 432  */\r
 433 void vListInitialise( List_t * const pxList ) PRIVILEGED_FUNCTION;\r
 434 \r
 435 /*\r
 436  * Must be called before a list item is used.  This sets the list container to\r
 437  * null so the item does not think that it is already contained in a list.\r
 438  *\r
 439  * @param pxItem Pointer to the list item being initialised.\r
 440  *\r
 441  * \page vListInitialiseItem vListInitialiseItem\r
 442  * \ingroup LinkedList\r
 443  */\r
 444 void vListInitialiseItem( ListItem_t * const pxItem ) PRIVILEGED_FUNCTION;\r
 445 \r
 446 /*\r
 447  * Insert a list item into a list.  The item will be inserted into the list in\r
 448  * a position determined by its item value (ascending item value order).\r
 449  *\r
 450  * @param pxList The list into which the item is to be inserted.\r
 451  *\r
 452  * @param pxNewListItem The item that is to be placed in the list.\r
 453  *\r
 454  * \page vListInsert vListInsert\r
 455  * \ingroup LinkedList\r
 456  */\r
 457 void vListInsert( List_t * const pxList,\r
 458                   ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION;\r
 459 \r
 460 /*\r
 461  * Insert a list item into a list.  The item will be inserted in a position\r
 462  * such that it will be the last item within the list returned by multiple\r
 463  * calls to listGET_OWNER_OF_NEXT_ENTRY.\r
 464  *\r
 465  * The list member pxIndex is used to walk through a list.  Calling\r
 466  * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list.\r
 467  * Placing an item in a list using vListInsertEnd effectively places the item\r
 468  * in the list position pointed to by pxIndex.  This means that every other\r
 469  * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before\r
 470  * the pxIndex parameter again points to the item being inserted.\r
 471  *\r
 472  * @param pxList The list into which the item is to be inserted.\r
 473  *\r
 474  * @param pxNewListItem The list item to be inserted into the list.\r
 475  *\r
 476  * \page vListInsertEnd vListInsertEnd\r
 477  * \ingroup LinkedList\r
 478  */\r
 479 void vListInsertEnd( List_t * const pxList,\r
 480                      ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION;\r
 481 \r
 482 /*\r
 483  * Remove an item from a list.  The list item has a pointer to the list that\r
 484  * it is in, so only the list item need be passed into the function.\r
 485  *\r
 486  * @param uxListRemove The item to be removed.  The item will remove itself from\r
 487  * the list pointed to by it's pxContainer parameter.\r
 488  *\r
 489  * @return The number of items that remain in the list after the list item has\r
 490  * been removed.\r
 491  *\r
 492  * \page uxListRemove uxListRemove\r
 493  * \ingroup LinkedList\r
 494  */\r
 495 UBaseType_t uxListRemove( ListItem_t * const pxItemToRemove ) PRIVILEGED_FUNCTION;\r
 496 \r
 497 /* *INDENT-OFF* */\r
 498 #ifdef __cplusplus\r
 499     }\r
 500 #endif\r
 501 /* *INDENT-ON* */\r
 502 \r
 503 #endif /* ifndef LIST_H */\r