2 FreeRTOS.org V5.1.2 - Copyright (C) 2003-2009 Richard Barry.
\r
4 This file is part of the FreeRTOS.org distribution.
\r
6 FreeRTOS.org is free software; you can redistribute it and/or modify
\r
7 it under the terms of the GNU General Public License as published by
\r
8 the Free Software Foundation; either version 2 of the License, or
\r
9 (at your option) any later version.
\r
11 FreeRTOS.org is distributed in the hope that it will be useful,
\r
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
\r
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
\r
14 GNU General Public License for more details.
\r
16 You should have received a copy of the GNU General Public License
\r
17 along with FreeRTOS.org; if not, write to the Free Software
\r
18 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
\r
20 A special exception to the GPL can be applied should you wish to distribute
\r
21 a combined work that includes FreeRTOS.org, without being obliged to provide
\r
22 the source code for any proprietary components. See the licensing section
\r
23 of http://www.FreeRTOS.org for full details of how and when the exception
\r
26 ***************************************************************************
\r
27 ***************************************************************************
\r
29 * Get the FreeRTOS eBook! See http://www.FreeRTOS.org/Documentation *
\r
31 * This is a concise, step by step, 'hands on' guide that describes both *
\r
32 * general multitasking concepts and FreeRTOS specifics. It presents and *
\r
33 * explains numerous examples that are written using the FreeRTOS API. *
\r
34 * Full source code for all the examples is provided in an accompanying *
\r
37 ***************************************************************************
\r
38 ***************************************************************************
\r
40 Please ensure to read the configuration and relevant port sections of the
\r
41 online documentation.
\r
43 http://www.FreeRTOS.org - Documentation, latest information, license and
\r
46 http://www.SafeRTOS.com - A version that is certified for use in safety
\r
49 http://www.OpenRTOS.com - Commercial support, development, porting,
\r
50 licensing and training services.
\r
54 * This is the list implementation used by the scheduler. While it is tailored
\r
55 * heavily for the schedulers needs, it is also available for use by
\r
58 * xLists can only store pointers to xListItems. Each xListItem contains a
\r
59 * numeric value (xItemValue). Most of the time the lists are sorted in
\r
60 * descending item value order.
\r
62 * Lists are created already containing one list item. The value of this
\r
63 * item is the maximum possible that can be stored, it is therefore always at
\r
64 * the end of the list and acts as a marker. The list member pxHead always
\r
65 * points to this marker - even though it is at the tail of the list. This
\r
66 * is because the tail contains a wrap back pointer to the true head of
\r
69 * In addition to it's value, each list item contains a pointer to the next
\r
70 * item in the list (pxNext), a pointer to the list it is in (pxContainer)
\r
71 * and a pointer to back to the object that contains it. These later two
\r
72 * pointers are included for efficiency of list manipulation. There is
\r
73 * effectively a two way link between the object containing the list item and
\r
74 * the list item itself.
\r
77 * \page ListIntroduction List Implementation
\r
78 * \ingroup FreeRTOSIntro
\r
84 + Included local const within listGET_OWNER_OF_NEXT_ENTRY() to assist
\r
85 compiler with optimisation. Thanks B.R.
\r
95 * Definition of the only type of object that a list can contain.
\r
99 portTickType xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */
\r
100 volatile struct xLIST_ITEM * pxNext; /*< Pointer to the next xListItem in the list. */
\r
101 volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */
\r
102 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
103 void * pvContainer; /*< Pointer to the list in which this list item is placed (if any). */
\r
105 typedef struct xLIST_ITEM xListItem; /* For some reason lint wants this as two separate definitions. */
\r
107 struct xMINI_LIST_ITEM
\r
109 portTickType xItemValue;
\r
110 volatile struct xLIST_ITEM *pxNext;
\r
111 volatile struct xLIST_ITEM *pxPrevious;
\r
113 typedef struct xMINI_LIST_ITEM xMiniListItem;
\r
116 * Definition of the type of queue used by the scheduler.
\r
118 typedef struct xLIST
\r
120 volatile unsigned portBASE_TYPE uxNumberOfItems;
\r
121 volatile xListItem * pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */
\r
122 volatile 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. */
\r
126 * Access macro to set the owner of a list item. The owner of a list item
\r
127 * is the object (usually a TCB) that contains the list item.
\r
129 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
\r
130 * \ingroup LinkedList
\r
132 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( pxListItem )->pvOwner = ( void * ) pxOwner
\r
135 * Access macro to set the value of the list item. In most cases the value is
\r
136 * used to sort the list in descending order.
\r
138 * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE
\r
139 * \ingroup LinkedList
\r
141 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( pxListItem )->xItemValue = xValue
\r
144 * Access macro the retrieve the value of the list item. The value can
\r
145 * represent anything - for example a the priority of a task, or the time at
\r
146 * which a task should be unblocked.
\r
148 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
\r
149 * \ingroup LinkedList
\r
151 #define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue )
\r
154 * Access macro to determine if a list contains any items. The macro will
\r
155 * only have the value true if the list is empty.
\r
157 * \page listLIST_IS_EMPTY listLIST_IS_EMPTY
\r
158 * \ingroup LinkedList
\r
160 #define listLIST_IS_EMPTY( pxList ) ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )
\r
163 * Access macro to return the number of items in the list.
\r
165 #define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems )
\r
168 * Access function to obtain the owner of the next entry in a list.
\r
170 * The list member pxIndex is used to walk through a list. Calling
\r
171 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
\r
172 * and returns that entries pxOwner parameter. Using multiple calls to this
\r
173 * function it is therefore possible to move through every item contained in
\r
176 * The pxOwner parameter of a list item is a pointer to the object that owns
\r
177 * the list item. In the scheduler this is normally a task control block.
\r
178 * The pxOwner parameter effectively creates a two way link between the list
\r
179 * item and its owner.
\r
181 * @param pxList The list from which the next item owner is to be returned.
\r
183 * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY
\r
184 * \ingroup LinkedList
\r
186 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \
\r
188 xList * const pxConstList = pxList; \
\r
189 /* Increment the index to the next item and return the item, ensuring */ \
\r
190 /* we don't return the marker used at the end of the list. */ \
\r
191 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \
\r
192 if( ( pxConstList )->pxIndex == ( xListItem * ) &( ( pxConstList )->xListEnd ) ) \
\r
194 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \
\r
196 pxTCB = ( pxConstList )->pxIndex->pvOwner; \
\r
201 * Access function to obtain the owner of the first entry in a list. Lists
\r
202 * are normally sorted in ascending item value order.
\r
204 * This function returns the pxOwner member of the first item in the list.
\r
205 * The pxOwner parameter of a list item is a pointer to the object that owns
\r
206 * the list item. In the scheduler this is normally a task control block.
\r
207 * The pxOwner parameter effectively creates a two way link between the list
\r
208 * item and its owner.
\r
210 * @param pxList The list from which the owner of the head item is to be
\r
213 * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY
\r
214 * \ingroup LinkedList
\r
216 #define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )
\r
219 * Check to see if a list item is within a list. The list item maintains a
\r
220 * "container" pointer that points to the list it is in. All this macro does
\r
221 * is check to see if the container and the list match.
\r
223 * @param pxList The list we want to know if the list item is within.
\r
224 * @param pxListItem The list item we want to know if is in the list.
\r
225 * @return pdTRUE is the list item is in the list, otherwise pdFALSE.
\r
228 #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList )
\r
231 * Must be called before a list is used! This initialises all the members
\r
232 * of the list structure and inserts the xListEnd item into the list as a
\r
233 * marker to the back of the list.
\r
235 * @param pxList Pointer to the list being initialised.
\r
237 * \page vListInitialise vListInitialise
\r
238 * \ingroup LinkedList
\r
240 void vListInitialise( xList *pxList );
\r
243 * Must be called before a list item is used. This sets the list container to
\r
244 * null so the item does not think that it is already contained in a list.
\r
246 * @param pxItem Pointer to the list item being initialised.
\r
248 * \page vListInitialiseItem vListInitialiseItem
\r
249 * \ingroup LinkedList
\r
251 void vListInitialiseItem( xListItem *pxItem );
\r
254 * Insert a list item into a list. The item will be inserted into the list in
\r
255 * a position determined by its item value (descending item value order).
\r
257 * @param pxList The list into which the item is to be inserted.
\r
259 * @param pxNewListItem The item to that is to be placed in the list.
\r
261 * \page vListInsert vListInsert
\r
262 * \ingroup LinkedList
\r
264 void vListInsert( xList *pxList, xListItem *pxNewListItem );
\r
267 * Insert a list item into a list. The item will be inserted in a position
\r
268 * such that it will be the last item within the list returned by multiple
\r
269 * calls to listGET_OWNER_OF_NEXT_ENTRY.
\r
271 * The list member pvIndex is used to walk through a list. Calling
\r
272 * listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.
\r
273 * Placing an item in a list using vListInsertEnd effectively places the item
\r
274 * in the list position pointed to by pvIndex. This means that every other
\r
275 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
\r
276 * the pvIndex parameter again points to the item being inserted.
\r
278 * @param pxList The list into which the item is to be inserted.
\r
280 * @param pxNewListItem The list item to be inserted into the list.
\r
282 * \page vListInsertEnd vListInsertEnd
\r
283 * \ingroup LinkedList
\r
285 void vListInsertEnd( xList *pxList, xListItem *pxNewListItem );
\r
288 * Remove an item from a list. The list item has a pointer to the list that
\r
289 * it is in, so only the list item need be passed into the function.
\r
291 * @param vListRemove The item to be removed. The item will remove itself from
\r
292 * the list pointed to by it's pxContainer parameter.
\r
294 * \page vListRemove vListRemove
\r
295 * \ingroup LinkedList
\r
297 void vListRemove( xListItem *pxItemToRemove );
\r