Rohit Grover / FreeRTOS

www.freertos.org

Dependents:   Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more

Source/include/list.h@0:8e57f3e9cc89, 2014-01-24 (annotated)

Committer:
rgrover1
Date:
Fri Jan 24 14:56:04 2014 +0000
Revision:
0:8e57f3e9cc89
Making FreeRTOS available as a library

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 0:8e57f3e9cc89 1 /*
rgrover1 0:8e57f3e9cc89 2 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd.
rgrover1 0:8e57f3e9cc89 3 All rights reserved
rgrover1 0:8e57f3e9cc89 4
rgrover1 0:8e57f3e9cc89 5 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
rgrover1 0:8e57f3e9cc89 6
rgrover1 0:8e57f3e9cc89 7 ***************************************************************************
rgrover1 0:8e57f3e9cc89 8 * *
rgrover1 0:8e57f3e9cc89 9 * FreeRTOS provides completely free yet professionally developed, *
rgrover1 0:8e57f3e9cc89 10 * robust, strictly quality controlled, supported, and cross *
rgrover1 0:8e57f3e9cc89 11 * platform software that has become a de facto standard. *
rgrover1 0:8e57f3e9cc89 12 * *
rgrover1 0:8e57f3e9cc89 13 * Help yourself get started quickly and support the FreeRTOS *
rgrover1 0:8e57f3e9cc89 14 * project by purchasing a FreeRTOS tutorial book, reference *
rgrover1 0:8e57f3e9cc89 15 * manual, or both from: http://www.FreeRTOS.org/Documentation *
rgrover1 0:8e57f3e9cc89 16 * *
rgrover1 0:8e57f3e9cc89 17 * Thank you! *
rgrover1 0:8e57f3e9cc89 18 * *
rgrover1 0:8e57f3e9cc89 19 ***************************************************************************
rgrover1 0:8e57f3e9cc89 20
rgrover1 0:8e57f3e9cc89 21 This file is part of the FreeRTOS distribution.
rgrover1 0:8e57f3e9cc89 22
rgrover1 0:8e57f3e9cc89 23 FreeRTOS is free software; you can redistribute it and/or modify it under
rgrover1 0:8e57f3e9cc89 24 the terms of the GNU General Public License (version 2) as published by the
rgrover1 0:8e57f3e9cc89 25 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception.
rgrover1 0:8e57f3e9cc89 26
rgrover1 0:8e57f3e9cc89 27 >>! NOTE: The modification to the GPL is included to allow you to distribute
rgrover1 0:8e57f3e9cc89 28 >>! a combined work that includes FreeRTOS without being obliged to provide
rgrover1 0:8e57f3e9cc89 29 >>! the source code for proprietary components outside of the FreeRTOS
rgrover1 0:8e57f3e9cc89 30 >>! kernel.
rgrover1 0:8e57f3e9cc89 31
rgrover1 0:8e57f3e9cc89 32 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
rgrover1 0:8e57f3e9cc89 33 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
rgrover1 0:8e57f3e9cc89 34 FOR A PARTICULAR PURPOSE. Full license text is available from the following
rgrover1 0:8e57f3e9cc89 35 link: http://www.freertos.org/a00114.html
rgrover1 0:8e57f3e9cc89 36
rgrover1 0:8e57f3e9cc89 37 1 tab == 4 spaces!
rgrover1 0:8e57f3e9cc89 38
rgrover1 0:8e57f3e9cc89 39 ***************************************************************************
rgrover1 0:8e57f3e9cc89 40 * *
rgrover1 0:8e57f3e9cc89 41 * Having a problem? Start by reading the FAQ "My application does *
rgrover1 0:8e57f3e9cc89 42 * not run, what could be wrong?" *
rgrover1 0:8e57f3e9cc89 43 * *
rgrover1 0:8e57f3e9cc89 44 * http://www.FreeRTOS.org/FAQHelp.html *
rgrover1 0:8e57f3e9cc89 45 * *
rgrover1 0:8e57f3e9cc89 46 ***************************************************************************
rgrover1 0:8e57f3e9cc89 47
rgrover1 0:8e57f3e9cc89 48 http://www.FreeRTOS.org - Documentation, books, training, latest versions,
rgrover1 0:8e57f3e9cc89 49 license and Real Time Engineers Ltd. contact details.
rgrover1 0:8e57f3e9cc89 50
rgrover1 0:8e57f3e9cc89 51 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
rgrover1 0:8e57f3e9cc89 52 including FreeRTOS+Trace - an indispensable productivity tool, a DOS
rgrover1 0:8e57f3e9cc89 53 compatible FAT file system, and our tiny thread aware UDP/IP stack.
rgrover1 0:8e57f3e9cc89 54
rgrover1 0:8e57f3e9cc89 55 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High
rgrover1 0:8e57f3e9cc89 56 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS
rgrover1 0:8e57f3e9cc89 57 licenses offer ticketed support, indemnification and middleware.
rgrover1 0:8e57f3e9cc89 58
rgrover1 0:8e57f3e9cc89 59 http://www.SafeRTOS.com - High Integrity Systems also provide a safety
rgrover1 0:8e57f3e9cc89 60 engineered and independently SIL3 certified version for use in safety and
rgrover1 0:8e57f3e9cc89 61 mission critical applications that require provable dependability.
rgrover1 0:8e57f3e9cc89 62
rgrover1 0:8e57f3e9cc89 63 1 tab == 4 spaces!
rgrover1 0:8e57f3e9cc89 64 */
rgrover1 0:8e57f3e9cc89 65
rgrover1 0:8e57f3e9cc89 66 /*
rgrover1 0:8e57f3e9cc89 67 * This is the list implementation used by the scheduler. While it is tailored
rgrover1 0:8e57f3e9cc89 68 * heavily for the schedulers needs, it is also available for use by
rgrover1 0:8e57f3e9cc89 69 * application code.
rgrover1 0:8e57f3e9cc89 70 *
rgrover1 0:8e57f3e9cc89 71 * xLists can only store pointers to xListItems. Each xListItem contains a
rgrover1 0:8e57f3e9cc89 72 * numeric value (xItemValue). Most of the time the lists are sorted in
rgrover1 0:8e57f3e9cc89 73 * descending item value order.
rgrover1 0:8e57f3e9cc89 74 *
rgrover1 0:8e57f3e9cc89 75 * Lists are created already containing one list item. The value of this
rgrover1 0:8e57f3e9cc89 76 * item is the maximum possible that can be stored, it is therefore always at
rgrover1 0:8e57f3e9cc89 77 * the end of the list and acts as a marker. The list member pxHead always
rgrover1 0:8e57f3e9cc89 78 * points to this marker - even though it is at the tail of the list. This
rgrover1 0:8e57f3e9cc89 79 * is because the tail contains a wrap back pointer to the true head of
rgrover1 0:8e57f3e9cc89 80 * the list.
rgrover1 0:8e57f3e9cc89 81 *
rgrover1 0:8e57f3e9cc89 82 * In addition to it's value, each list item contains a pointer to the next
rgrover1 0:8e57f3e9cc89 83 * item in the list (pxNext), a pointer to the list it is in (pxContainer)
rgrover1 0:8e57f3e9cc89 84 * and a pointer to back to the object that contains it. These later two
rgrover1 0:8e57f3e9cc89 85 * pointers are included for efficiency of list manipulation. There is
rgrover1 0:8e57f3e9cc89 86 * effectively a two way link between the object containing the list item and
rgrover1 0:8e57f3e9cc89 87 * the list item itself.
rgrover1 0:8e57f3e9cc89 88 *
rgrover1 0:8e57f3e9cc89 89 *
rgrover1 0:8e57f3e9cc89 90 * \page ListIntroduction List Implementation
rgrover1 0:8e57f3e9cc89 91 * \ingroup FreeRTOSIntro
rgrover1 0:8e57f3e9cc89 92 */
rgrover1 0:8e57f3e9cc89 93
rgrover1 0:8e57f3e9cc89 94
rgrover1 0:8e57f3e9cc89 95 #ifndef LIST_H
rgrover1 0:8e57f3e9cc89 96 #define LIST_H
rgrover1 0:8e57f3e9cc89 97
rgrover1 0:8e57f3e9cc89 98 /*
rgrover1 0:8e57f3e9cc89 99 * The list structure members are modified from within interrupts, and therefore
rgrover1 0:8e57f3e9cc89 100 * by rights should be declared volatile. However, they are only modified in a
rgrover1 0:8e57f3e9cc89 101 * functionally atomic way (within critical sections of with the scheduler
rgrover1 0:8e57f3e9cc89 102 * suspended) and are either passed by reference into a function or indexed via
rgrover1 0:8e57f3e9cc89 103 * a volatile variable. Therefore, in all use cases tested so far, the volatile
rgrover1 0:8e57f3e9cc89 104 * qualifier can be omitted in order to provide a moderate performance
rgrover1 0:8e57f3e9cc89 105 * improvement without adversely affecting functional behaviour. The assembly
rgrover1 0:8e57f3e9cc89 106 * instructions generated by the IAR, ARM and GCC compilers when the respective
rgrover1 0:8e57f3e9cc89 107 * compiler's options were set for maximum optimisation has been inspected and
rgrover1 0:8e57f3e9cc89 108 * deemed to be as intended. That said, as compiler technology advances, and
rgrover1 0:8e57f3e9cc89 109 * especially if aggressive cross module optimisation is used (a use case that
rgrover1 0:8e57f3e9cc89 110 * has not been exercised to any great extend) then it is feasible that the
rgrover1 0:8e57f3e9cc89 111 * volatile qualifier will be needed for correct optimisation. It is expected
rgrover1 0:8e57f3e9cc89 112 * that a compiler removing essential code because, without the volatile
rgrover1 0:8e57f3e9cc89 113 * qualifier on the list structure members and with aggressive cross module
rgrover1 0:8e57f3e9cc89 114 * optimisation, the compiler deemed the code unnecessary will result in
rgrover1 0:8e57f3e9cc89 115 * complete and obvious failure of the scheduler. If this is ever experienced
rgrover1 0:8e57f3e9cc89 116 * then the volatile qualifier can be inserted in the relevant places within the
rgrover1 0:8e57f3e9cc89 117 * list structures by simply defining configLIST_VOLATILE to volatile in
rgrover1 0:8e57f3e9cc89 118 * FreeRTOSConfig.h (as per the example at the bottom of this comment block).
rgrover1 0:8e57f3e9cc89 119 * If configLIST_VOLATILE is not defined then the preprocessor directives below
rgrover1 0:8e57f3e9cc89 120 * will simply #define configLIST_VOLATILE away completely.
rgrover1 0:8e57f3e9cc89 121 *
rgrover1 0:8e57f3e9cc89 122 * To use volatile list structure members then add the following line to
rgrover1 0:8e57f3e9cc89 123 * FreeRTOSConfig.h (without the quotes):
rgrover1 0:8e57f3e9cc89 124 * "#define configLIST_VOLATILE volatile"
rgrover1 0:8e57f3e9cc89 125 */
rgrover1 0:8e57f3e9cc89 126 #ifndef configLIST_VOLATILE
rgrover1 0:8e57f3e9cc89 127 #define configLIST_VOLATILE
rgrover1 0:8e57f3e9cc89 128 #endif /* configSUPPORT_CROSS_MODULE_OPTIMISATION */
rgrover1 0:8e57f3e9cc89 129
rgrover1 0:8e57f3e9cc89 130 #ifdef __cplusplus
rgrover1 0:8e57f3e9cc89 131 extern "C" {
rgrover1 0:8e57f3e9cc89 132 #endif
rgrover1 0:8e57f3e9cc89 133 /*
rgrover1 0:8e57f3e9cc89 134 * Definition of the only type of object that a list can contain.
rgrover1 0:8e57f3e9cc89 135 */
rgrover1 0:8e57f3e9cc89 136 struct xLIST_ITEM
rgrover1 0:8e57f3e9cc89 137 {
rgrover1 0:8e57f3e9cc89 138 configLIST_VOLATILE portTickType xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */
rgrover1 0:8e57f3e9cc89 139 struct xLIST_ITEM * configLIST_VOLATILE pxNext; /*< Pointer to the next xListItem in the list. */
rgrover1 0:8e57f3e9cc89 140 struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;/*< Pointer to the previous xListItem in the list. */
rgrover1 0:8e57f3e9cc89 141 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. */
rgrover1 0:8e57f3e9cc89 142 void * configLIST_VOLATILE pvContainer; /*< Pointer to the list in which this list item is placed (if any). */
rgrover1 0:8e57f3e9cc89 143 };
rgrover1 0:8e57f3e9cc89 144 typedef struct xLIST_ITEM xListItem; /* For some reason lint wants this as two separate definitions. */
rgrover1 0:8e57f3e9cc89 145
rgrover1 0:8e57f3e9cc89 146 struct xMINI_LIST_ITEM
rgrover1 0:8e57f3e9cc89 147 {
rgrover1 0:8e57f3e9cc89 148 configLIST_VOLATILE portTickType xItemValue;
rgrover1 0:8e57f3e9cc89 149 struct xLIST_ITEM * configLIST_VOLATILE pxNext;
rgrover1 0:8e57f3e9cc89 150 struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;
rgrover1 0:8e57f3e9cc89 151 };
rgrover1 0:8e57f3e9cc89 152 typedef struct xMINI_LIST_ITEM xMiniListItem;
rgrover1 0:8e57f3e9cc89 153
rgrover1 0:8e57f3e9cc89 154 /*
rgrover1 0:8e57f3e9cc89 155 * Definition of the type of queue used by the scheduler.
rgrover1 0:8e57f3e9cc89 156 */
rgrover1 0:8e57f3e9cc89 157 typedef struct xLIST
rgrover1 0:8e57f3e9cc89 158 {
rgrover1 0:8e57f3e9cc89 159 configLIST_VOLATILE unsigned portBASE_TYPE uxNumberOfItems;
rgrover1 0:8e57f3e9cc89 160 xListItem * configLIST_VOLATILE pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */
rgrover1 0:8e57f3e9cc89 161 xMiniListItem 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. */
rgrover1 0:8e57f3e9cc89 162 } xList;
rgrover1 0:8e57f3e9cc89 163
rgrover1 0:8e57f3e9cc89 164 /*
rgrover1 0:8e57f3e9cc89 165 * Access macro to set the owner of a list item. The owner of a list item
rgrover1 0:8e57f3e9cc89 166 * is the object (usually a TCB) that contains the list item.
rgrover1 0:8e57f3e9cc89 167 *
rgrover1 0:8e57f3e9cc89 168 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
rgrover1 0:8e57f3e9cc89 169 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 170 */
rgrover1 0:8e57f3e9cc89 171 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( ( pxListItem )->pvOwner = ( void * ) ( pxOwner ) )
rgrover1 0:8e57f3e9cc89 172
rgrover1 0:8e57f3e9cc89 173 /*
rgrover1 0:8e57f3e9cc89 174 * Access macro to get the owner of a list item. The owner of a list item
rgrover1 0:8e57f3e9cc89 175 * is the object (usually a TCB) that contains the list item.
rgrover1 0:8e57f3e9cc89 176 *
rgrover1 0:8e57f3e9cc89 177 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
rgrover1 0:8e57f3e9cc89 178 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 179 */
rgrover1 0:8e57f3e9cc89 180 #define listGET_LIST_ITEM_OWNER( pxListItem ) ( pxListItem )->pvOwner
rgrover1 0:8e57f3e9cc89 181
rgrover1 0:8e57f3e9cc89 182 /*
rgrover1 0:8e57f3e9cc89 183 * Access macro to set the value of the list item. In most cases the value is
rgrover1 0:8e57f3e9cc89 184 * used to sort the list in descending order.
rgrover1 0:8e57f3e9cc89 185 *
rgrover1 0:8e57f3e9cc89 186 * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE
rgrover1 0:8e57f3e9cc89 187 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 188 */
rgrover1 0:8e57f3e9cc89 189 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( ( pxListItem )->xItemValue = ( xValue ) )
rgrover1 0:8e57f3e9cc89 190
rgrover1 0:8e57f3e9cc89 191 /*
rgrover1 0:8e57f3e9cc89 192 * Access macro to retrieve the value of the list item. The value can
rgrover1 0:8e57f3e9cc89 193 * represent anything - for example a the priority of a task, or the time at
rgrover1 0:8e57f3e9cc89 194 * which a task should be unblocked.
rgrover1 0:8e57f3e9cc89 195 *
rgrover1 0:8e57f3e9cc89 196 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
rgrover1 0:8e57f3e9cc89 197 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 198 */
rgrover1 0:8e57f3e9cc89 199 #define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue )
rgrover1 0:8e57f3e9cc89 200
rgrover1 0:8e57f3e9cc89 201 /*
rgrover1 0:8e57f3e9cc89 202 * Access macro the retrieve the value of the list item at the head of a given
rgrover1 0:8e57f3e9cc89 203 * list.
rgrover1 0:8e57f3e9cc89 204 *
rgrover1 0:8e57f3e9cc89 205 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
rgrover1 0:8e57f3e9cc89 206 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 207 */
rgrover1 0:8e57f3e9cc89 208 #define listGET_ITEM_VALUE_OF_HEAD_ENTRY( pxList ) ( (&( ( pxList )->xListEnd ))->pxNext->xItemValue )
rgrover1 0:8e57f3e9cc89 209
rgrover1 0:8e57f3e9cc89 210 /*
rgrover1 0:8e57f3e9cc89 211 * Access macro to determine if a list contains any items. The macro will
rgrover1 0:8e57f3e9cc89 212 * only have the value true if the list is empty.
rgrover1 0:8e57f3e9cc89 213 *
rgrover1 0:8e57f3e9cc89 214 * \page listLIST_IS_EMPTY listLIST_IS_EMPTY
rgrover1 0:8e57f3e9cc89 215 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 216 */
rgrover1 0:8e57f3e9cc89 217 #define listLIST_IS_EMPTY( pxList ) ( ( portBASE_TYPE ) ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 ) )
rgrover1 0:8e57f3e9cc89 218
rgrover1 0:8e57f3e9cc89 219 /*
rgrover1 0:8e57f3e9cc89 220 * Access macro to return the number of items in the list.
rgrover1 0:8e57f3e9cc89 221 */
rgrover1 0:8e57f3e9cc89 222 #define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems )
rgrover1 0:8e57f3e9cc89 223
rgrover1 0:8e57f3e9cc89 224 /*
rgrover1 0:8e57f3e9cc89 225 * Access function to obtain the owner of the next entry in a list.
rgrover1 0:8e57f3e9cc89 226 *
rgrover1 0:8e57f3e9cc89 227 * The list member pxIndex is used to walk through a list. Calling
rgrover1 0:8e57f3e9cc89 228 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
rgrover1 0:8e57f3e9cc89 229 * and returns that entries pxOwner parameter. Using multiple calls to this
rgrover1 0:8e57f3e9cc89 230 * function it is therefore possible to move through every item contained in
rgrover1 0:8e57f3e9cc89 231 * a list.
rgrover1 0:8e57f3e9cc89 232 *
rgrover1 0:8e57f3e9cc89 233 * The pxOwner parameter of a list item is a pointer to the object that owns
rgrover1 0:8e57f3e9cc89 234 * the list item. In the scheduler this is normally a task control block.
rgrover1 0:8e57f3e9cc89 235 * The pxOwner parameter effectively creates a two way link between the list
rgrover1 0:8e57f3e9cc89 236 * item and its owner.
rgrover1 0:8e57f3e9cc89 237 *
rgrover1 0:8e57f3e9cc89 238 * @param pxList The list from which the next item owner is to be returned.
rgrover1 0:8e57f3e9cc89 239 *
rgrover1 0:8e57f3e9cc89 240 * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY
rgrover1 0:8e57f3e9cc89 241 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 242 */
rgrover1 0:8e57f3e9cc89 243 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \
rgrover1 0:8e57f3e9cc89 244 { \
rgrover1 0:8e57f3e9cc89 245 xList * const pxConstList = ( pxList ); \
rgrover1 0:8e57f3e9cc89 246 /* Increment the index to the next item and return the item, ensuring */ \
rgrover1 0:8e57f3e9cc89 247 /* we don't return the marker used at the end of the list. */ \
rgrover1 0:8e57f3e9cc89 248 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \
rgrover1 0:8e57f3e9cc89 249 if( ( void * ) ( pxConstList )->pxIndex == ( void * ) &( ( pxConstList )->xListEnd ) ) \
rgrover1 0:8e57f3e9cc89 250 { \
rgrover1 0:8e57f3e9cc89 251 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \
rgrover1 0:8e57f3e9cc89 252 } \
rgrover1 0:8e57f3e9cc89 253 ( pxTCB ) = ( pxConstList )->pxIndex->pvOwner; \
rgrover1 0:8e57f3e9cc89 254 }
rgrover1 0:8e57f3e9cc89 255
rgrover1 0:8e57f3e9cc89 256
rgrover1 0:8e57f3e9cc89 257 /*
rgrover1 0:8e57f3e9cc89 258 * Access function to obtain the owner of the first entry in a list. Lists
rgrover1 0:8e57f3e9cc89 259 * are normally sorted in ascending item value order.
rgrover1 0:8e57f3e9cc89 260 *
rgrover1 0:8e57f3e9cc89 261 * This function returns the pxOwner member of the first item in the list.
rgrover1 0:8e57f3e9cc89 262 * The pxOwner parameter of a list item is a pointer to the object that owns
rgrover1 0:8e57f3e9cc89 263 * the list item. In the scheduler this is normally a task control block.
rgrover1 0:8e57f3e9cc89 264 * The pxOwner parameter effectively creates a two way link between the list
rgrover1 0:8e57f3e9cc89 265 * item and its owner.
rgrover1 0:8e57f3e9cc89 266 *
rgrover1 0:8e57f3e9cc89 267 * @param pxList The list from which the owner of the head item is to be
rgrover1 0:8e57f3e9cc89 268 * returned.
rgrover1 0:8e57f3e9cc89 269 *
rgrover1 0:8e57f3e9cc89 270 * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY
rgrover1 0:8e57f3e9cc89 271 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 272 */
rgrover1 0:8e57f3e9cc89 273 #define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( (&( ( pxList )->xListEnd ))->pxNext->pvOwner )
rgrover1 0:8e57f3e9cc89 274
rgrover1 0:8e57f3e9cc89 275 /*
rgrover1 0:8e57f3e9cc89 276 * Check to see if a list item is within a list. The list item maintains a
rgrover1 0:8e57f3e9cc89 277 * "container" pointer that points to the list it is in. All this macro does
rgrover1 0:8e57f3e9cc89 278 * is check to see if the container and the list match.
rgrover1 0:8e57f3e9cc89 279 *
rgrover1 0:8e57f3e9cc89 280 * @param pxList The list we want to know if the list item is within.
rgrover1 0:8e57f3e9cc89 281 * @param pxListItem The list item we want to know if is in the list.
rgrover1 0:8e57f3e9cc89 282 * @return pdTRUE is the list item is in the list, otherwise pdFALSE.
rgrover1 0:8e57f3e9cc89 283 * pointer against
rgrover1 0:8e57f3e9cc89 284 */
rgrover1 0:8e57f3e9cc89 285 #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( portBASE_TYPE ) ( ( pxListItem )->pvContainer == ( void * ) ( pxList ) ) )
rgrover1 0:8e57f3e9cc89 286
rgrover1 0:8e57f3e9cc89 287 /*
rgrover1 0:8e57f3e9cc89 288 * Return the list a list item is contained within (referenced from).
rgrover1 0:8e57f3e9cc89 289 *
rgrover1 0:8e57f3e9cc89 290 * @param pxListItem The list item being queried.
rgrover1 0:8e57f3e9cc89 291 * @return A pointer to the xList object that references the pxListItem
rgrover1 0:8e57f3e9cc89 292 */
rgrover1 0:8e57f3e9cc89 293 #define listLIST_ITEM_CONTAINER( pxListItem ) ( ( pxListItem )->pvContainer )
rgrover1 0:8e57f3e9cc89 294
rgrover1 0:8e57f3e9cc89 295 /*
rgrover1 0:8e57f3e9cc89 296 * This provides a crude means of knowing if a list has been initialised, as
rgrover1 0:8e57f3e9cc89 297 * pxList->xListEnd.xItemValue is set to portMAX_DELAY by the vListInitialise()
rgrover1 0:8e57f3e9cc89 298 * function.
rgrover1 0:8e57f3e9cc89 299 */
rgrover1 0:8e57f3e9cc89 300 #define listLIST_IS_INITIALISED( pxList ) ( ( pxList )->xListEnd.xItemValue == portMAX_DELAY )
rgrover1 0:8e57f3e9cc89 301
rgrover1 0:8e57f3e9cc89 302 /*
rgrover1 0:8e57f3e9cc89 303 * Must be called before a list is used! This initialises all the members
rgrover1 0:8e57f3e9cc89 304 * of the list structure and inserts the xListEnd item into the list as a
rgrover1 0:8e57f3e9cc89 305 * marker to the back of the list.
rgrover1 0:8e57f3e9cc89 306 *
rgrover1 0:8e57f3e9cc89 307 * @param pxList Pointer to the list being initialised.
rgrover1 0:8e57f3e9cc89 308 *
rgrover1 0:8e57f3e9cc89 309 * \page vListInitialise vListInitialise
rgrover1 0:8e57f3e9cc89 310 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 311 */
rgrover1 0:8e57f3e9cc89 312 void vListInitialise( xList * const pxList );
rgrover1 0:8e57f3e9cc89 313
rgrover1 0:8e57f3e9cc89 314 /*
rgrover1 0:8e57f3e9cc89 315 * Must be called before a list item is used. This sets the list container to
rgrover1 0:8e57f3e9cc89 316 * null so the item does not think that it is already contained in a list.
rgrover1 0:8e57f3e9cc89 317 *
rgrover1 0:8e57f3e9cc89 318 * @param pxItem Pointer to the list item being initialised.
rgrover1 0:8e57f3e9cc89 319 *
rgrover1 0:8e57f3e9cc89 320 * \page vListInitialiseItem vListInitialiseItem
rgrover1 0:8e57f3e9cc89 321 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 322 */
rgrover1 0:8e57f3e9cc89 323 void vListInitialiseItem( xListItem * const pxItem );
rgrover1 0:8e57f3e9cc89 324
rgrover1 0:8e57f3e9cc89 325 /*
rgrover1 0:8e57f3e9cc89 326 * Insert a list item into a list. The item will be inserted into the list in
rgrover1 0:8e57f3e9cc89 327 * a position determined by its item value (descending item value order).
rgrover1 0:8e57f3e9cc89 328 *
rgrover1 0:8e57f3e9cc89 329 * @param pxList The list into which the item is to be inserted.
rgrover1 0:8e57f3e9cc89 330 *
rgrover1 0:8e57f3e9cc89 331 * @param pxNewListItem The item to that is to be placed in the list.
rgrover1 0:8e57f3e9cc89 332 *
rgrover1 0:8e57f3e9cc89 333 * \page vListInsert vListInsert
rgrover1 0:8e57f3e9cc89 334 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 335 */
rgrover1 0:8e57f3e9cc89 336 void vListInsert( xList * const pxList, xListItem * const pxNewListItem );
rgrover1 0:8e57f3e9cc89 337
rgrover1 0:8e57f3e9cc89 338 /*
rgrover1 0:8e57f3e9cc89 339 * Insert a list item into a list. The item will be inserted in a position
rgrover1 0:8e57f3e9cc89 340 * such that it will be the last item within the list returned by multiple
rgrover1 0:8e57f3e9cc89 341 * calls to listGET_OWNER_OF_NEXT_ENTRY.
rgrover1 0:8e57f3e9cc89 342 *
rgrover1 0:8e57f3e9cc89 343 * The list member pvIndex is used to walk through a list. Calling
rgrover1 0:8e57f3e9cc89 344 * listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.
rgrover1 0:8e57f3e9cc89 345 * Placing an item in a list using vListInsertEnd effectively places the item
rgrover1 0:8e57f3e9cc89 346 * in the list position pointed to by pvIndex. This means that every other
rgrover1 0:8e57f3e9cc89 347 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
rgrover1 0:8e57f3e9cc89 348 * the pvIndex parameter again points to the item being inserted.
rgrover1 0:8e57f3e9cc89 349 *
rgrover1 0:8e57f3e9cc89 350 * @param pxList The list into which the item is to be inserted.
rgrover1 0:8e57f3e9cc89 351 *
rgrover1 0:8e57f3e9cc89 352 * @param pxNewListItem The list item to be inserted into the list.
rgrover1 0:8e57f3e9cc89 353 *
rgrover1 0:8e57f3e9cc89 354 * \page vListInsertEnd vListInsertEnd
rgrover1 0:8e57f3e9cc89 355 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 356 */
rgrover1 0:8e57f3e9cc89 357 void vListInsertEnd( xList * const pxList, xListItem * const pxNewListItem );
rgrover1 0:8e57f3e9cc89 358
rgrover1 0:8e57f3e9cc89 359 /*
rgrover1 0:8e57f3e9cc89 360 * Remove an item from a list. The list item has a pointer to the list that
rgrover1 0:8e57f3e9cc89 361 * it is in, so only the list item need be passed into the function.
rgrover1 0:8e57f3e9cc89 362 *
rgrover1 0:8e57f3e9cc89 363 * @param uxListRemove The item to be removed. The item will remove itself from
rgrover1 0:8e57f3e9cc89 364 * the list pointed to by it's pxContainer parameter.
rgrover1 0:8e57f3e9cc89 365 *
rgrover1 0:8e57f3e9cc89 366 * @return The number of items that remain in the list after the list item has
rgrover1 0:8e57f3e9cc89 367 * been removed.
rgrover1 0:8e57f3e9cc89 368 *
rgrover1 0:8e57f3e9cc89 369 * \page uxListRemove uxListRemove
rgrover1 0:8e57f3e9cc89 370 * \ingroup LinkedList
rgrover1 0:8e57f3e9cc89 371 */
rgrover1 0:8e57f3e9cc89 372 unsigned portBASE_TYPE uxListRemove( xListItem * const pxItemToRemove );
rgrover1 0:8e57f3e9cc89 373
rgrover1 0:8e57f3e9cc89 374 #ifdef __cplusplus
rgrover1 0:8e57f3e9cc89 375 }
rgrover1 0:8e57f3e9cc89 376 #endif
rgrover1 0:8e57f3e9cc89 377
rgrover1 0:8e57f3e9cc89 378 #endif
rgrover1 0:8e57f3e9cc89 379