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*//***************************************************************************/
67typedef 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*//***************************************************************************/
215static __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*//***************************************************************************/
237static __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*//***************************************************************************/
258static __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*//***************************************************************************/
274static __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*//***************************************************************************/
291static __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*//***************************************************************************/
308static __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*//***************************************************************************/
324static __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*//***************************************************************************/
340void 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*//***************************************************************************/
352int 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