1/* Copyright (c) 2008-2011 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 @File          list_ext.h
36
37 @Description   External prototypes for list.c
38*//***************************************************************************/
39
40#ifndef __LIST_EXT_H
41#define __LIST_EXT_H
42
43
44#include "std_ext.h"
45
46
47/**************************************************************************//**
48 @Group         etc_id   Utility Library Application Programming Interface
49
50 @Description   External routines.
51
52 @{
53*//***************************************************************************/
54
55/**************************************************************************//**
56 @Group         list_id List
57
58 @Description   List module functions,definitions and enums.
59
60 @{
61*//***************************************************************************/
62
63/**************************************************************************//**
64 @Description   List structure.
65*//***************************************************************************/
66typedef struct List
67{
68    struct List *p_Next;  /**< A pointer to the next list object     */
69    struct List *p_Prev;  /**< A pointer to the previous list object */
70} t_List;
71
72
73/**************************************************************************//**
74 @Function      NCSW_LIST_FIRST/LIST_LAST/NCSW_LIST_NEXT/NCSW_LIST_PREV
75
76 @Description   Macro to get first/last/next/previous entry in a list.
77
78 @Param[in]     p_List - A pointer to a list.
79*//***************************************************************************/
80#define NCSW_LIST_FIRST(p_List) (p_List)->p_Next
81#define LIST_LAST(p_List)  (p_List)->p_Prev
82#define NCSW_LIST_NEXT          NCSW_LIST_FIRST
83#define NCSW_LIST_PREV          LIST_LAST
84
85
86/**************************************************************************//**
87 @Function      NCSW_LIST_INIT
88
89 @Description   Macro for initialization of a list struct.
90
91 @Param[in]     lst - The t_List object to initialize.
92*//***************************************************************************/
93#define NCSW_LIST_INIT(lst) {&(lst), &(lst)}
94
95
96/**************************************************************************//**
97 @Function      LIST
98
99 @Description   Macro to declare of a list.
100
101 @Param[in]     listName - The list object name.
102*//***************************************************************************/
103#define LIST(listName) t_List listName = NCSW_LIST_INIT(listName)
104
105
106/**************************************************************************//**
107 @Function      INIT_LIST
108
109 @Description   Macro to initialize a list pointer.
110
111 @Param[in]     p_List - The list pointer.
112*//***************************************************************************/
113#define INIT_LIST(p_List)   NCSW_LIST_FIRST(p_List) = LIST_LAST(p_List) = (p_List)
114
115
116/**************************************************************************//**
117 @Function      LIST_OBJECT
118
119 @Description   Macro to get the struct (object) for this entry.
120
121 @Param[in]     type   - The type of the struct (object) this list is embedded in.
122 @Param[in]     member - The name of the t_List object within the struct.
123
124 @Return        The structure pointer for this entry.
125*//***************************************************************************/
126#define MEMBER_OFFSET(type, member) (PTR_TO_UINT(&((type *)0)->member))
127#define LIST_OBJECT(p_List, type, member) \
128    ((type *)((char *)(p_List)-MEMBER_OFFSET(type, member)))
129
130
131/**************************************************************************//**
132 @Function      LIST_FOR_EACH
133
134 @Description   Macro to iterate over a list.
135
136 @Param[in]     p_Pos  - A pointer to a list to use as a loop counter.
137 @Param[in]     p_Head - A pointer to the head for your list pointer.
138
139 @Cautions      You can't delete items with this routine.
140                For deletion use LIST_FOR_EACH_SAFE().
141*//***************************************************************************/
142#define LIST_FOR_EACH(p_Pos, p_Head) \
143    for (p_Pos = NCSW_LIST_FIRST(p_Head); p_Pos != (p_Head); p_Pos = NCSW_LIST_NEXT(p_Pos))
144
145
146/**************************************************************************//**
147 @Function      LIST_FOR_EACH_SAFE
148
149 @Description   Macro to iterate over a list safe against removal of list entry.
150
151 @Param[in]     p_Pos  - A pointer to a list to use as a loop counter.
152 @Param[in]     p_Tmp  - Another pointer to a list to use as temporary storage.
153 @Param[in]     p_Head - A pointer to the head for your list pointer.
154*//***************************************************************************/
155#define LIST_FOR_EACH_SAFE(p_Pos, p_Tmp, p_Head)                \
156    for (p_Pos = NCSW_LIST_FIRST(p_Head), p_Tmp = NCSW_LIST_FIRST(p_Pos); \
157         p_Pos != (p_Head);                                     \
158         p_Pos = p_Tmp, p_Tmp = NCSW_LIST_NEXT(p_Pos))
159
160
161/**************************************************************************//**
162 @Function      LIST_FOR_EACH_OBJECT_SAFE
163
164 @Description   Macro to iterate over list of given type safely.
165
166 @Param[in]     p_Pos  - A pointer to a list to use as a loop counter.
167 @Param[in]     p_Tmp  - Another pointer to a list to use as temporary storage.
168 @Param[in]     type   - The type of the struct this is embedded in.
169 @Param[in]     p_Head - A pointer to the head for your list pointer.
170 @Param[in]     member - The name of the list_struct within the struct.
171
172 @Cautions      You can't delete items with this routine.
173                For deletion use LIST_FOR_EACH_SAFE().
174*//***************************************************************************/
175#define LIST_FOR_EACH_OBJECT_SAFE(p_Pos, p_Tmp, p_Head, type, member)      \
176    for (p_Pos = LIST_OBJECT(NCSW_LIST_FIRST(p_Head), type, member),            \
177         p_Tmp = LIST_OBJECT(NCSW_LIST_FIRST(&p_Pos->member), type, member);    \
178         &p_Pos->member != (p_Head);                                       \
179         p_Pos = p_Tmp,                                                    \
180         p_Tmp = LIST_OBJECT(NCSW_LIST_FIRST(&p_Pos->member), type, member))
181
182/**************************************************************************//**
183 @Function      LIST_FOR_EACH_OBJECT
184
185 @Description   Macro to iterate over list of given type.
186
187 @Param[in]     p_Pos  - A pointer to a list to use as a loop counter.
188 @Param[in]     type   - The type of the struct this is embedded in.
189 @Param[in]     p_Head - A pointer to the head for your list pointer.
190 @Param[in]     member - The name of the list_struct within the struct.
191
192 @Cautions      You can't delete items with this routine.
193                For deletion use LIST_FOR_EACH_SAFE().
194*//***************************************************************************/
195#define LIST_FOR_EACH_OBJECT(p_Pos, type, p_Head, member)                  \
196    for (p_Pos = LIST_OBJECT(NCSW_LIST_FIRST(p_Head), type, member);            \
197         &p_Pos->member != (p_Head);                                       \
198         p_Pos = LIST_OBJECT(NCSW_LIST_FIRST(&(p_Pos->member)), type, member))
199
200
201/**************************************************************************//**
202 @Function      LIST_Add
203
204 @Description   Add a new entry to a list.
205
206                Insert a new entry after the specified head.
207                This is good for implementing stacks.
208
209 @Param[in]     p_New  - A pointer to a new list entry to be added.
210 @Param[in]     p_Head - A pointer to a list head to add it after.
211
212 @Return        none.
213*//***************************************************************************/
214static __inline__ void LIST_Add(t_List *p_New, t_List *p_Head)
215{
216    NCSW_LIST_PREV(NCSW_LIST_NEXT(p_Head)) = p_New;
217    NCSW_LIST_NEXT(p_New)             = NCSW_LIST_NEXT(p_Head);
218    NCSW_LIST_PREV(p_New)             = p_Head;
219    NCSW_LIST_NEXT(p_Head)            = p_New;
220}
221
222
223/**************************************************************************//**
224 @Function      LIST_AddToTail
225
226 @Description   Add a new entry to a list.
227
228                Insert a new entry before the specified head.
229                This is useful for implementing queues.
230
231 @Param[in]     p_New  - A pointer to a new list entry to be added.
232 @Param[in]     p_Head - A pointer to a list head to add it after.
233
234 @Return        none.
235*//***************************************************************************/
236static __inline__ void LIST_AddToTail(t_List *p_New, t_List *p_Head)
237{
238    NCSW_LIST_NEXT(NCSW_LIST_PREV(p_Head)) = p_New;
239    NCSW_LIST_PREV(p_New)             = NCSW_LIST_PREV(p_Head);
240    NCSW_LIST_NEXT(p_New)             = p_Head;
241    NCSW_LIST_PREV(p_Head)            = p_New;
242}
243
244
245/**************************************************************************//**
246 @Function      LIST_Del
247
248 @Description   Deletes entry from a list.
249
250 @Param[in]     p_Entry - A pointer to the element to delete from the list.
251
252 @Return        none.
253
254 @Cautions      LIST_IsEmpty() on entry does not return true after this,
255                the entry is in an undefined state.
256*//***************************************************************************/
257static __inline__ void LIST_Del(t_List *p_Entry)
258{
259    NCSW_LIST_PREV(NCSW_LIST_NEXT(p_Entry)) = NCSW_LIST_PREV(p_Entry);
260    NCSW_LIST_NEXT(NCSW_LIST_PREV(p_Entry)) = NCSW_LIST_NEXT(p_Entry);
261}
262
263
264/**************************************************************************//**
265 @Function      LIST_DelAndInit
266
267 @Description   Deletes entry from list and reinitialize it.
268
269 @Param[in]     p_Entry - A pointer to the element to delete from the list.
270
271 @Return        none.
272*//***************************************************************************/
273static __inline__ void LIST_DelAndInit(t_List *p_Entry)
274{
275    LIST_Del(p_Entry);
276    INIT_LIST(p_Entry);
277}
278
279
280/**************************************************************************//**
281 @Function      LIST_Move
282
283 @Description   Delete from one list and add as another's head.
284
285 @Param[in]     p_Entry - A pointer to the list entry to move.
286 @Param[in]     p_Head  - A pointer to the list head that will precede our entry.
287
288 @Return        none.
289*//***************************************************************************/
290static __inline__ void LIST_Move(t_List *p_Entry, t_List *p_Head)
291{
292    LIST_Del(p_Entry);
293    LIST_Add(p_Entry, p_Head);
294}
295
296
297/**************************************************************************//**
298 @Function      LIST_MoveToTail
299
300 @Description   Delete from one list and add as another's tail.
301
302 @Param[in]     p_Entry - A pointer to the entry to move.
303 @Param[in]     p_Head  - A pointer to the list head that will follow our entry.
304
305 @Return        none.
306*//***************************************************************************/
307static __inline__ void LIST_MoveToTail(t_List *p_Entry, t_List *p_Head)
308{
309    LIST_Del(p_Entry);
310    LIST_AddToTail(p_Entry, p_Head);
311}
312
313
314/**************************************************************************//**
315 @Function      LIST_IsEmpty
316
317 @Description   Tests whether a list is empty.
318
319 @Param[in]     p_List - A pointer to the list to test.
320
321 @Return        1 if the list is empty, 0 otherwise.
322*//***************************************************************************/
323static __inline__ int LIST_IsEmpty(t_List *p_List)
324{
325    return (NCSW_LIST_FIRST(p_List) == p_List);
326}
327
328
329/**************************************************************************//**
330 @Function      LIST_Append
331
332 @Description   Join two lists.
333
334 @Param[in]     p_NewList - A pointer to the new list to add.
335 @Param[in]     p_Head    - A pointer to the place to add it in the first list.
336
337 @Return        none.
338*//***************************************************************************/
339void LIST_Append(t_List *p_NewList, t_List *p_Head);
340
341
342/**************************************************************************//**
343 @Function      LIST_NumOfObjs
344
345 @Description   Counts number of objects in the list
346
347 @Param[in]     p_List - A pointer to the list which objects are to be counted.
348
349 @Return        Number of objects in the list.
350*//***************************************************************************/
351int LIST_NumOfObjs(t_List *p_List);
352
353/** @} */ /* end of list_id group */
354/** @} */ /* end of etc_id group */
355
356
357#endif /* __LIST_EXT_H */
358