00001 /* 00002 FreeRTOS V6.0.0 - Copyright (C) 2009 Real Time Engineers Ltd. 00003 00004 *************************************************************************** 00005 * * 00006 * If you are: * 00007 * * 00008 * + New to FreeRTOS, * 00009 * + Wanting to learn FreeRTOS or multitasking in general quickly * 00010 * + Looking for basic training, * 00011 * + Wanting to improve your FreeRTOS skills and productivity * 00012 * * 00013 * then take a look at the FreeRTOS eBook * 00014 * * 00015 * "Using the FreeRTOS Real Time Kernel - a Practical Guide" * 00016 * http://www.FreeRTOS.org/Documentation * 00017 * * 00018 * A pdf reference manual is also available. Both are usually delivered * 00019 * to your inbox within 20 minutes to two hours when purchased between 8am * 00020 * and 8pm GMT (although please allow up to 24 hours in case of * 00021 * exceptional circumstances). Thank you for your support! * 00022 * * 00023 *************************************************************************** 00024 00025 This file is part of the FreeRTOS distribution. 00026 00027 FreeRTOS is free software; you can redistribute it and/or modify it under 00028 the terms of the GNU General Public License (version 2) as published by the 00029 Free Software Foundation AND MODIFIED BY the FreeRTOS exception. 00030 ***NOTE*** The exception to the GPL is included to allow you to distribute 00031 a combined work that includes FreeRTOS without being obliged to provide the 00032 source code for proprietary components outside of the FreeRTOS kernel. 00033 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT 00034 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00035 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 00036 more details. You should have received a copy of the GNU General Public 00037 License and the FreeRTOS license exception along with FreeRTOS; if not it 00038 can be viewed here: http://www.freertos.org/a00114.html and also obtained 00039 by writing to Richard Barry, contact details for whom are available on the 00040 FreeRTOS WEB site. 00041 00042 1 tab == 4 spaces! 00043 00044 http://www.FreeRTOS.org - Documentation, latest information, license and 00045 contact details. 00046 00047 http://www.SafeRTOS.com - A version that is certified for use in safety 00048 critical systems. 00049 00050 http://www.OpenRTOS.com - Commercial support, development, porting, 00051 licensing and training services. 00052 */ 00053 00054 /* 00055 * This is the list implementation used by the scheduler. While it is tailored 00056 * heavily for the schedulers needs, it is also available for use by 00057 * application code. 00058 * 00059 * xLists can only store pointers to xListItems. Each xListItem contains a 00060 * numeric value (xItemValue). Most of the time the lists are sorted in 00061 * descending item value order. 00062 * 00063 * Lists are created already containing one list item. The value of this 00064 * item is the maximum possible that can be stored, it is therefore always at 00065 * the end of the list and acts as a marker. The list member pxHead always 00066 * points to this marker - even though it is at the tail of the list. This 00067 * is because the tail contains a wrap back pointer to the true head of 00068 * the list. 00069 * 00070 * In addition to it's value, each list item contains a pointer to the next 00071 * item in the list (pxNext), a pointer to the list it is in (pxContainer) 00072 * and a pointer to back to the object that contains it. These later two 00073 * pointers are included for efficiency of list manipulation. There is 00074 * effectively a two way link between the object containing the list item and 00075 * the list item itself. 00076 * 00077 * 00078 * \page ListIntroduction List Implementation 00079 * \ingroup FreeRTOSIntro 00080 */ 00081 00082 /* 00083 Changes from V4.3.1 00084 00085 + Included local const within listGET_OWNER_OF_NEXT_ENTRY() to assist 00086 compiler with optimisation. Thanks B.R. 00087 */ 00088 00089 #ifndef LIST_H 00090 #define LIST_H 00091 00092 #ifdef __cplusplus 00093 extern "C" { 00094 #endif 00095 /* 00096 * Definition of the only type of object that a list can contain. 00097 */ 00098 struct xLIST_ITEM 00099 { 00100 portTickType xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */ 00101 volatile struct xLIST_ITEM * pxNext; /*< Pointer to the next xListItem in the list. */ 00102 volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */ 00103 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. */ 00104 void * pvContainer; /*< Pointer to the list in which this list item is placed (if any). */ 00105 }; 00106 typedef struct xLIST_ITEM xListItem; /* For some reason lint wants this as two separate definitions. */ 00107 00108 struct xMINI_LIST_ITEM 00109 { 00110 portTickType xItemValue; 00111 volatile struct xLIST_ITEM *pxNext; 00112 volatile struct xLIST_ITEM *pxPrevious; 00113 }; 00114 typedef struct xMINI_LIST_ITEM xMiniListItem; 00115 00116 /* 00117 * Definition of the type of queue used by the scheduler. 00118 */ 00119 typedef struct xLIST 00120 { 00121 volatile unsigned portBASE_TYPE uxNumberOfItems; 00122 volatile xListItem * pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */ 00123 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. */ 00124 } xList; 00125 00126 /* 00127 * Access macro to set the owner of a list item. The owner of a list item 00128 * is the object (usually a TCB) that contains the list item. 00129 * 00130 * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER 00131 * \ingroup LinkedList 00132 */ 00133 #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( pxListItem )->pvOwner = ( void * ) pxOwner 00134 00135 /* 00136 * Access macro to set the value of the list item. In most cases the value is 00137 * used to sort the list in descending order. 00138 * 00139 * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE 00140 * \ingroup LinkedList 00141 */ 00142 #define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( pxListItem )->xItemValue = xValue 00143 00144 /* 00145 * Access macro the retrieve the value of the list item. The value can 00146 * represent anything - for example a the priority of a task, or the time at 00147 * which a task should be unblocked. 00148 * 00149 * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE 00150 * \ingroup LinkedList 00151 */ 00152 #define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue ) 00153 00154 /* 00155 * Access macro to determine if a list contains any items. The macro will 00156 * only have the value true if the list is empty. 00157 * 00158 * \page listLIST_IS_EMPTY listLIST_IS_EMPTY 00159 * \ingroup LinkedList 00160 */ 00161 #define listLIST_IS_EMPTY( pxList ) ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 ) 00162 00163 /* 00164 * Access macro to return the number of items in the list. 00165 */ 00166 #define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems ) 00167 00168 /* 00169 * Access function to obtain the owner of the next entry in a list. 00170 * 00171 * The list member pxIndex is used to walk through a list. Calling 00172 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list 00173 * and returns that entries pxOwner parameter. Using multiple calls to this 00174 * function it is therefore possible to move through every item contained in 00175 * a list. 00176 * 00177 * The pxOwner parameter of a list item is a pointer to the object that owns 00178 * the list item. In the scheduler this is normally a task control block. 00179 * The pxOwner parameter effectively creates a two way link between the list 00180 * item and its owner. 00181 * 00182 * @param pxList The list from which the next item owner is to be returned. 00183 * 00184 * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY 00185 * \ingroup LinkedList 00186 */ 00187 #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \ 00188 { \ 00189 xList * const pxConstList = pxList; \ 00190 /* Increment the index to the next item and return the item, ensuring */ \ 00191 /* we don't return the marker used at the end of the list. */ \ 00192 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ 00193 if( ( pxConstList )->pxIndex == ( xListItem * ) &( ( pxConstList )->xListEnd ) ) \ 00194 { \ 00195 ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ 00196 } \ 00197 pxTCB = ( pxConstList )->pxIndex->pvOwner; \ 00198 } 00199 00200 00201 /* 00202 * Access function to obtain the owner of the first entry in a list. Lists 00203 * are normally sorted in ascending item value order. 00204 * 00205 * This function returns the pxOwner member of the first item in the list. 00206 * The pxOwner parameter of a list item is a pointer to the object that owns 00207 * the list item. In the scheduler this is normally a task control block. 00208 * The pxOwner parameter effectively creates a two way link between the list 00209 * item and its owner. 00210 * 00211 * @param pxList The list from which the owner of the head item is to be 00212 * returned. 00213 * 00214 * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY 00215 * \ingroup LinkedList 00216 */ 00217 #define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) ) 00218 00219 /* 00220 * Check to see if a list item is within a list. The list item maintains a 00221 * "container" pointer that points to the list it is in. All this macro does 00222 * is check to see if the container and the list match. 00223 * 00224 * @param pxList The list we want to know if the list item is within. 00225 * @param pxListItem The list item we want to know if is in the list. 00226 * @return pdTRUE is the list item is in the list, otherwise pdFALSE. 00227 * pointer against 00228 */ 00229 #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList ) 00230 00231 /* 00232 * Must be called before a list is used! This initialises all the members 00233 * of the list structure and inserts the xListEnd item into the list as a 00234 * marker to the back of the list. 00235 * 00236 * @param pxList Pointer to the list being initialised. 00237 * 00238 * \page vListInitialise vListInitialise 00239 * \ingroup LinkedList 00240 */ 00241 void vListInitialise( xList *pxList ); 00242 00243 /* 00244 * Must be called before a list item is used. This sets the list container to 00245 * null so the item does not think that it is already contained in a list. 00246 * 00247 * @param pxItem Pointer to the list item being initialised. 00248 * 00249 * \page vListInitialiseItem vListInitialiseItem 00250 * \ingroup LinkedList 00251 */ 00252 void vListInitialiseItem( xListItem *pxItem ); 00253 00254 /* 00255 * Insert a list item into a list. The item will be inserted into the list in 00256 * a position determined by its item value (descending item value order). 00257 * 00258 * @param pxList The list into which the item is to be inserted. 00259 * 00260 * @param pxNewListItem The item to that is to be placed in the list. 00261 * 00262 * \page vListInsert vListInsert 00263 * \ingroup LinkedList 00264 */ 00265 void vListInsert( xList *pxList, xListItem *pxNewListItem ); 00266 00267 /* 00268 * Insert a list item into a list. The item will be inserted in a position 00269 * such that it will be the last item within the list returned by multiple 00270 * calls to listGET_OWNER_OF_NEXT_ENTRY. 00271 * 00272 * The list member pvIndex is used to walk through a list. Calling 00273 * listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list. 00274 * Placing an item in a list using vListInsertEnd effectively places the item 00275 * in the list position pointed to by pvIndex. This means that every other 00276 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before 00277 * the pvIndex parameter again points to the item being inserted. 00278 * 00279 * @param pxList The list into which the item is to be inserted. 00280 * 00281 * @param pxNewListItem The list item to be inserted into the list. 00282 * 00283 * \page vListInsertEnd vListInsertEnd 00284 * \ingroup LinkedList 00285 */ 00286 void vListInsertEnd( xList *pxList, xListItem *pxNewListItem ); 00287 00288 /* 00289 * Remove an item from a list. The list item has a pointer to the list that 00290 * it is in, so only the list item need be passed into the function. 00291 * 00292 * @param vListRemove The item to be removed. The item will remove itself from 00293 * the list pointed to by it's pxContainer parameter. 00294 * 00295 * \page vListRemove vListRemove 00296 * \ingroup LinkedList 00297 */ 00298 void vListRemove( xListItem *pxItemToRemove ); 00299 00300 #ifdef __cplusplus 00301 } 00302 #endif 00303 00304 #endif 00305