1 /* Copyright (c) 2008-2012 Freescale Semiconductor, Inc
2 * All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
11 * * Neither the name of Freescale Semiconductor nor the
12 * names of its contributors may be used to endorse or promote products
13 * derived from this software without specific prior written permission.
14 *
15 *
16 * ALTERNATIVELY, this software may be distributed under the terms of the
17 * GNU General Public License ("GPL") as published by the Free Software
18 * Foundation, either version 2 of that License or (at your option) any
19 * later version.
20 *
21 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33
34 /**************************************************************************//**
35
36 @File list_ext.h
37
38 @Description External prototypes for list.c
39 *//***************************************************************************/
40
41 #ifndef __LIST_EXT_H
42 #define __LIST_EXT_H
43
44
45 #include "std_ext.h"
46
47
48 /**************************************************************************//**
49 @Group etc_id Utility Library Application Programming Interface
50
51 @Description External routines.
52
53 @{
54 *//***************************************************************************/
55
56 /**************************************************************************//**
57 @Group list_id List
58
59 @Description List module functions,definitions and enums.
60
61 @{
62 *//***************************************************************************/
63
64 /**************************************************************************//**
65 @Description List structure.
66 *//***************************************************************************/
67 typedef struct List
68 {
69 struct List *p_Next; /**< A pointer to the next list object */
70 struct List *p_Prev; /**< A pointer to the previous list object */
71 } t_List;
72
73
74 /**************************************************************************//**
75 @Function NCSW_LIST_FIRST/NCSW_LIST_LAST/NCSW_LIST_NEXT/NCSW_LIST_PREV
76
77 @Description Macro to get first/last/next/previous entry in a list.
78
79 @Param[in] p_List - A pointer to a list.
80 *//***************************************************************************/
81 #define NCSW_LIST_FIRST(p_List) (p_List)->p_Next
82 #define NCSW_LIST_LAST(p_List) (p_List)->p_Prev
83 #define NCSW_LIST_NEXT NCSW_LIST_FIRST
84 #define NCSW_LIST_PREV NCSW_LIST_LAST
85
86
87 /**************************************************************************//**
88 @Function NCSW_LIST_INIT
89
90 @Description Macro for initialization of a list struct.
91
92 @Param[in] lst - The t_List object to initialize.
93 *//***************************************************************************/
94 #define NCSW_LIST_INIT(lst) {&(lst), &(lst)}
95
96
97 /**************************************************************************//**
98 @Function NCSW_LIST
99
100 @Description Macro to declare of a list.
101
102 @Param[in] listName - The list object name.
103 *//***************************************************************************/
104 #define NCSW_LIST(listName) t_List listName = NCSW_LIST_INIT(listName)
105
106
107 /**************************************************************************//**
108 @Function INIT_LIST
109
110 @Description Macro to initialize a list pointer.
111
112 @Param[in] p_List - The list pointer.
113 *//***************************************************************************/
114 #define INIT_LIST(p_List) NCSW_LIST_FIRST(p_List) = NCSW_LIST_LAST(p_List) = (p_List)
115
116
117 /**************************************************************************//**
118 @Function NCSW_LIST_OBJECT
119
120 @Description Macro to get the struct (object) for this entry.
121
122 @Param[in] type - The type of the struct (object) this list is embedded in.
123 @Param[in] member - The name of the t_List object within the struct.
124
125 @Return The structure pointer for this entry.
126 *//***************************************************************************/
127 #define MEMBER_OFFSET(type, member) (PTR_TO_UINT(&((type *)0)->member))
128 #define NCSW_LIST_OBJECT(p_List, type, member) \
129 ((type *)((char *)(p_List)-MEMBER_OFFSET(type, member)))
130
131
132 /**************************************************************************//**
133 @Function NCSW_LIST_FOR_EACH
134
135 @Description Macro to iterate over a list.
136
137 @Param[in] p_Pos - A pointer to a list to use as a loop counter.
138 @Param[in] p_Head - A pointer to the head for your list pointer.
139
140 @Cautions You can't delete items with this routine.
141 For deletion use NCSW_LIST_FOR_EACH_SAFE().
142 *//***************************************************************************/
143 #define NCSW_LIST_FOR_EACH(p_Pos, p_Head) \
144 for (p_Pos = NCSW_LIST_FIRST(p_Head); p_Pos != (p_Head); p_Pos = NCSW_LIST_NEXT(p_Pos))
145
146
147 /**************************************************************************//**
148 @Function NCSW_LIST_FOR_EACH_SAFE
149
150 @Description Macro to iterate over a list safe against removal of list entry.
151
152 @Param[in] p_Pos - A pointer to a list to use as a loop counter.
153 @Param[in] p_Tmp - Another pointer to a list to use as temporary storage.
154 @Param[in] p_Head - A pointer to the head for your list pointer.
155 *//***************************************************************************/
156 #define NCSW_LIST_FOR_EACH_SAFE(p_Pos, p_Tmp, p_Head) \
157 for (p_Pos = NCSW_LIST_FIRST(p_Head), p_Tmp = NCSW_LIST_FIRST(p_Pos); \
158 p_Pos != (p_Head); \
159 p_Pos = p_Tmp, p_Tmp = NCSW_LIST_NEXT(p_Pos))
160
161
162 /**************************************************************************//**
163 @Function NCSW_LIST_FOR_EACH_OBJECT_SAFE
164
165 @Description Macro to iterate over list of given type safely.
166
167 @Param[in] p_Pos - A pointer to a list to use as a loop counter.
168 @Param[in] p_Tmp - Another pointer to a list to use as temporary storage.
169 @Param[in] type - The type of the struct this is embedded in.
170 @Param[in] p_Head - A pointer to the head for your list pointer.
171 @Param[in] member - The name of the list_struct within the struct.
172
173 @Cautions You can't delete items with this routine.
174 For deletion use NCSW_LIST_FOR_EACH_SAFE().
175 *//***************************************************************************/
176 #define NCSW_LIST_FOR_EACH_OBJECT_SAFE(p_Pos, p_Tmp, p_Head, type, member) \
177 for (p_Pos = NCSW_LIST_OBJECT(NCSW_LIST_FIRST(p_Head), type, member), \
178 p_Tmp = NCSW_LIST_OBJECT(NCSW_LIST_FIRST(&p_Pos->member), type, member); \
179 &p_Pos->member != (p_Head); \
180 p_Pos = p_Tmp, \
181 p_Tmp = NCSW_LIST_OBJECT(NCSW_LIST_FIRST(&p_Pos->member), type, member))
182
183 /**************************************************************************//**
184 @Function NCSW_LIST_FOR_EACH_OBJECT
185
186 @Description Macro to iterate over list of given type.
187
188 @Param[in] p_Pos - A pointer to a list to use as a loop counter.
189 @Param[in] type - The type of the struct this is embedded in.
190 @Param[in] p_Head - A pointer to the head for your list pointer.
191 @Param[in] member - The name of the list_struct within the struct.
192
193 @Cautions You can't delete items with this routine.
194 For deletion use NCSW_LIST_FOR_EACH_SAFE().
195 *//***************************************************************************/
196 #define NCSW_LIST_FOR_EACH_OBJECT(p_Pos, type, p_Head, member) \
197 for (p_Pos = NCSW_LIST_OBJECT(NCSW_LIST_FIRST(p_Head), type, member); \
198 &p_Pos->member != (p_Head); \
199 p_Pos = NCSW_LIST_OBJECT(NCSW_LIST_FIRST(&(p_Pos->member)), type, member))
200
201
202 /**************************************************************************//**
203 @Function NCSW_LIST_Add
204
205 @Description Add a new entry to a list.
206
207 Insert a new entry after the specified head.
208 This is good for implementing stacks.
209
210 @Param[in] p_New - A pointer to a new list entry to be added.
211 @Param[in] p_Head - A pointer to a list head to add it after.
212
213 @Return none.
214 *//***************************************************************************/
NCSW_LIST_Add(t_List * p_New,t_List * p_Head)215 static __inline__ void NCSW_LIST_Add(t_List *p_New, t_List *p_Head)
216 {
217 NCSW_LIST_PREV(NCSW_LIST_NEXT(p_Head)) = p_New;
218 NCSW_LIST_NEXT(p_New) = NCSW_LIST_NEXT(p_Head);
219 NCSW_LIST_PREV(p_New) = p_Head;
220 NCSW_LIST_NEXT(p_Head) = p_New;
221 }
222
223
224 /**************************************************************************//**
225 @Function NCSW_LIST_AddToTail
226
227 @Description Add a new entry to a list.
228
229 Insert a new entry before the specified head.
230 This is useful for implementing queues.
231
232 @Param[in] p_New - A pointer to a new list entry to be added.
233 @Param[in] p_Head - A pointer to a list head to add it before.
234
235 @Return none.
236 *//***************************************************************************/
NCSW_LIST_AddToTail(t_List * p_New,t_List * p_Head)237 static __inline__ void NCSW_LIST_AddToTail(t_List *p_New, t_List *p_Head)
238 {
239 NCSW_LIST_NEXT(NCSW_LIST_PREV(p_Head)) = p_New;
240 NCSW_LIST_PREV(p_New) = NCSW_LIST_PREV(p_Head);
241 NCSW_LIST_NEXT(p_New) = p_Head;
242 NCSW_LIST_PREV(p_Head) = p_New;
243 }
244
245
246 /**************************************************************************//**
247 @Function NCSW_LIST_Del
248
249 @Description Deletes entry from a list.
250
251 @Param[in] p_Entry - A pointer to the element to delete from the list.
252
253 @Return none.
254
255 @Cautions NCSW_LIST_IsEmpty() on entry does not return true after this,
256 the entry is in an undefined state.
257 *//***************************************************************************/
NCSW_LIST_Del(t_List * p_Entry)258 static __inline__ void NCSW_LIST_Del(t_List *p_Entry)
259 {
260 NCSW_LIST_PREV(NCSW_LIST_NEXT(p_Entry)) = NCSW_LIST_PREV(p_Entry);
261 NCSW_LIST_NEXT(NCSW_LIST_PREV(p_Entry)) = NCSW_LIST_NEXT(p_Entry);
262 }
263
264
265 /**************************************************************************//**
266 @Function NCSW_LIST_DelAndInit
267
268 @Description Deletes entry from list and reinitialize it.
269
270 @Param[in] p_Entry - A pointer to the element to delete from the list.
271
272 @Return none.
273 *//***************************************************************************/
NCSW_LIST_DelAndInit(t_List * p_Entry)274 static __inline__ void NCSW_LIST_DelAndInit(t_List *p_Entry)
275 {
276 NCSW_LIST_Del(p_Entry);
277 INIT_LIST(p_Entry);
278 }
279
280
281 /**************************************************************************//**
282 @Function NCSW_LIST_Move
283
284 @Description Delete from one list and add as another's head.
285
286 @Param[in] p_Entry - A pointer to the list entry to move.
287 @Param[in] p_Head - A pointer to the list head that will precede our entry.
288
289 @Return none.
290 *//***************************************************************************/
NCSW_LIST_Move(t_List * p_Entry,t_List * p_Head)291 static __inline__ void NCSW_LIST_Move(t_List *p_Entry, t_List *p_Head)
292 {
293 NCSW_LIST_Del(p_Entry);
294 NCSW_LIST_Add(p_Entry, p_Head);
295 }
296
297
298 /**************************************************************************//**
299 @Function NCSW_LIST_MoveToTail
300
301 @Description Delete from one list and add as another's tail.
302
303 @Param[in] p_Entry - A pointer to the entry to move.
304 @Param[in] p_Head - A pointer to the list head that will follow our entry.
305
306 @Return none.
307 *//***************************************************************************/
NCSW_LIST_MoveToTail(t_List * p_Entry,t_List * p_Head)308 static __inline__ void NCSW_LIST_MoveToTail(t_List *p_Entry, t_List *p_Head)
309 {
310 NCSW_LIST_Del(p_Entry);
311 NCSW_LIST_AddToTail(p_Entry, p_Head);
312 }
313
314
315 /**************************************************************************//**
316 @Function NCSW_LIST_IsEmpty
317
318 @Description Tests whether a list is empty.
319
320 @Param[in] p_List - A pointer to the list to test.
321
322 @Return 1 if the list is empty, 0 otherwise.
323 *//***************************************************************************/
NCSW_LIST_IsEmpty(t_List * p_List)324 static __inline__ int NCSW_LIST_IsEmpty(t_List *p_List)
325 {
326 return (NCSW_LIST_FIRST(p_List) == p_List);
327 }
328
329
330 /**************************************************************************//**
331 @Function NCSW_LIST_Append
332
333 @Description Join two lists.
334
335 @Param[in] p_NewList - A pointer to the new list to add.
336 @Param[in] p_Head - A pointer to the place to add it in the first list.
337
338 @Return none.
339 *//***************************************************************************/
340 void NCSW_LIST_Append(t_List *p_NewList, t_List *p_Head);
341
342
343 /**************************************************************************//**
344 @Function NCSW_LIST_NumOfObjs
345
346 @Description Counts number of objects in the list
347
348 @Param[in] p_List - A pointer to the list which objects are to be counted.
349
350 @Return Number of objects in the list.
351 *//***************************************************************************/
352 int NCSW_LIST_NumOfObjs(t_List *p_List);
353
354 /** @} */ /* end of list_id group */
355 /** @} */ /* end of etc_id group */
356
357
358 #endif /* __LIST_EXT_H */
359