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

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