1 /* 2 * dspbridge/mpu_api/inc/list.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Copyright (C) 2007 Texas Instruments, Inc. 7 * 8 * This program is free software; you can redistribute it and/or modify it 9 * under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation version 2.1 of the License. 11 * 12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind, 13 * whether express or implied; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 */ 17 18 19 /* 20 * ======== list.h ======== 21 * Purpose: 22 * Declarations of list management control structures and definitions 23 * of inline list management functions. 24 * 25 * Public Functions: 26 * LST_Create 27 * LST_Delete 28 * LST_Exit 29 * LST_First 30 * LST_GetHead 31 * LST_InitElem 32 * LST_Init 33 * LST_InsertBefore 34 * LST_IsEmpty 35 * LST_Next 36 * LST_PutTail 37 * LST_RemoveElem 38 * 39 * Notes: 40 * 41 *! Revision History 42 *! ================ 43 *! 10-Aug-2000 ag: Added LST_InsertBefore(). 44 *! 29-Oct-1999 kc: Cleaned up for code review. 45 *! 16-Aug-1997 cr: added explicit identifiers. 46 *! 10-Aug-1996 gp: Acquired from SMM for WinSPOX v.1.1; renamed identifiers. 47 *! 21-Oct-1994 dh4: Cleaned / commented for code review. 48 *! 08-Jun-1994 dh4: Converted to SPM (added extern "C"). 49 */ 50 51 #ifndef LIST_ 52 #define LIST_ 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 #include <dspapi.h> 59 60 #define LST_IsEmpty(l) (((l)->head.next == &(l)->head)) 61 62 struct LST_ELEM { 63 struct LST_ELEM *next; 64 struct LST_ELEM *prev; 65 struct LST_ELEM *self; 66 } ; 67 68 /*typedef LST_ELEM *LST_PELEM;*/ 69 70 struct LST_LIST { 71 struct LST_ELEM head; 72 } ; 73 74 /*typedef LST_LIST *LST_PLIST;*/ 75 76 /* 77 * ======== LST_Create ======== 78 * Purpose: 79 * Allocates and initializes a circular list. 80 * Details: 81 * Uses portable MEM_Calloc() function to allocate a list containing 82 * a single element and initializes that element to indicate that it 83 * is the "end of the list" (i.e., the list is empty). 84 * An empty list is indicated by the "next" pointer in the element 85 * at the head of the list pointing to the head of the list, itself. 86 * Parameters: 87 * Returns: 88 * Pointer to beginning of created list (success) 89 * NULL --> Allocation failed 90 * Requires: 91 * LST initialized. 92 * Ensures: 93 * Notes: 94 * The created list contains a single element. This element is the 95 * "empty" element, because its "next" and "prev" pointers point at 96 * the same location (the element itself). 97 */ 98 extern struct LST_LIST* LST_Create(); 99 100 /* 101 * ======== LST_Delete ======== 102 * Purpose: 103 * Removes a list by freeing its control structure's memory space. 104 * Details: 105 * Uses portable MEM_Free() function to deallocate the memory 106 * block pointed at by the input parameter. 107 * Parameters: 108 * pList: Pointer to list control structure of list to be deleted 109 * Returns: 110 * Void 111 * Requires: 112 * - LST initialized. 113 * - pList != NULL. 114 * Ensures: 115 * Notes: 116 * Must ONLY be used for empty lists, because it does not walk the 117 * chain of list elements. Calling this function on a non-empty list 118 * will cause a memory leak. 119 */ 120 extern VOID LST_Delete(IN struct LST_LIST* pList); 121 122 /* 123 * ======== LST_Exit ======== 124 * Purpose: 125 * Discontinue usage of module; free resources when reference count 126 * reaches 0. 127 * Parameters: 128 * Returns: 129 * Requires: 130 * LST initialized. 131 * Ensures: 132 * Resources used by module are freed when cRef reaches zero. 133 */ 134 extern VOID LST_Exit(); 135 136 /* 137 * ======== LST_First ======== 138 * Purpose: 139 * Returns a pointer to the first element of the list, or NULL if the list 140 * is empty. 141 * Parameters: 142 * pList: Pointer to list control structure. 143 * Returns: 144 * Pointer to first list element, or NULL. 145 * Requires: 146 * - LST initialized. 147 * - pList != NULL. 148 * Ensures: 149 */ 150 extern struct LST_ELEM* LST_First(IN struct LST_LIST* pList); 151 152 /* 153 * ======== LST_GetHead ======== 154 * Purpose: 155 * Pops the head off the list and returns a pointer to it. 156 * Details: 157 * If the list is empty, returns NULL. 158 * Else, removes the element at the head of the list, making the next 159 * element the head of the list. 160 * The head is removed by making the tail element of the list point its 161 * "next" pointer at the next element after the head, and by making the 162 * "prev" pointer of the next element after the head point at the tail 163 * element. So the next element after the head becomes the new head of 164 * the list. 165 * Parameters: 166 * pList: Pointer to list control structure of list whose head 167 * element is to be removed 168 * Returns: 169 * Pointer to element that was at the head of the list (success) 170 * NULL No elements in list 171 * Requires: 172 * - head.self must be correctly set to &head. 173 * - LST initialized. 174 * - pList != NULL. 175 * Ensures: 176 * Notes: 177 * Because the tail of the list points forward (its "next" pointer) to 178 * the head of the list, and the head of the list points backward (its 179 * "prev" pointer) to the tail of the list, this list is circular. 180 */ 181 extern struct LST_ELEM* LST_GetHead(IN struct LST_LIST* pList); 182 183 /* 184 * ======== LST_Init ======== 185 * Purpose: 186 * Initializes private state of LST module. 187 * Parameters: 188 * Returns: 189 * TRUE if initialized; FALSE otherwise. 190 * Requires: 191 * Ensures: 192 * LST initialized. 193 */ 194 extern bool LST_Init(); 195 196 /* 197 * ======== LST_InitElem ======== 198 * Purpose: 199 * Initializes a list element to default (cleared) values 200 * Details: 201 * Parameters: 202 * pElem: Pointer to list element to be reset 203 * Returns: 204 * Requires: 205 * LST initialized. 206 * Ensures: 207 * Notes: 208 * This function must not be called to "reset" an element in the middle 209 * of a list chain -- that would break the chain. 210 * 211 */ 212 extern VOID LST_InitElem(IN struct LST_ELEM* pListElem); 213 214 /* 215 * ======== LST_InsertBefore ======== 216 * Purpose: 217 * Insert the element before the existing element. 218 * Parameters: 219 * pList: Pointer to list control structure. 220 * pElem: Pointer to element in list to insert. 221 * pElemExisting: Pointer to existing list element. 222 * Returns: 223 * Requires: 224 * - LST initialized. 225 * - pList != NULL. 226 * - pElem != NULL. 227 * - pElemExisting != NULL. 228 * Ensures: 229 */ 230 extern VOID LST_InsertBefore(IN struct LST_LIST* pList, 231 IN struct LST_ELEM* pElem, 232 IN struct LST_ELEM* pElemExisting); 233 234 /* 235 * ======== LST_Next ======== 236 * Purpose: 237 * Returns a pointer to the next element of the list, or NULL if the next 238 * element is the head of the list or the list is empty. 239 * Parameters: 240 * pList: Pointer to list control structure. 241 * pCurElem: Pointer to element in list to remove. 242 * Returns: 243 * Pointer to list element, or NULL. 244 * Requires: 245 * - LST initialized. 246 * - pList != NULL. 247 * - pCurElem != NULL. 248 * Ensures: 249 */ 250 extern struct LST_ELEM* LST_Next(IN struct LST_LIST* pList, 251 IN struct LST_ELEM* pCurElem); 252 253 /* 254 * ======== LST_PutTail ======== 255 * Purpose: 256 * Adds the specified element to the tail of the list 257 * Details: 258 * Sets new element's "prev" pointer to the address previously held by 259 * the head element's prev pointer. This is the previous tail member of 260 * the list. 261 * Sets the new head's prev pointer to the address of the element. 262 * Sets next pointer of the previous tail member of the list to point to 263 * the new element (rather than the head, which it had been pointing at). 264 * Sets new element's next pointer to the address of the head element. 265 * Sets head's prev pointer to the address of the new element. 266 * Parameters: 267 * pList: Pointer to list control structure to which *pElem will be 268 * added 269 * pElem: Pointer to list element to be added 270 * Returns: 271 * Void 272 * Requires: 273 * *pElem and *pList must both exist. 274 * pElem->self = pElem before pElem is passed to this function. 275 * LST initialized. 276 * Ensures: 277 * Notes: 278 * Because the tail is always "just before" the head of the list (the 279 * tail's "next" pointer points at the head of the list, and the head's 280 * "prev" pointer points at the tail of the list), the list is circular. 281 * Warning: if pElem->self is not set beforehand, LST_GetHead() will 282 * return an erroneous pointer when it is called for this element. 283 */ 284 extern VOID LST_PutTail(IN struct LST_LIST* pList, 285 IN struct LST_ELEM* pListElem); 286 287 /* 288 * ======== LST_RemoveElem ======== 289 * Purpose: 290 * Removes (unlinks) the given element from the list, if the list is not 291 * empty. Does not free the list element. 292 * Parameters: 293 * pList: Pointer to list control structure. 294 * pCurElem: Pointer to element in list to remove. 295 * Returns: 296 * Requires: 297 * - LST initialized. 298 * - pList != NULL. 299 * - pCurElem != NULL. 300 * Ensures: 301 */ 302 extern VOID LST_RemoveElem(IN struct LST_LIST* pList, 303 IN struct LST_ELEM* pCurElem); 304 305 #ifdef __cplusplus 306 } 307 #endif 308 #endif /* LIST_ */ 309