Gitiles
Code Review Sign In
192.168.1.100 / T800_MD / 04730939d77d4b1fce91df3083777d88f0b04c4a / . / mcu / interface / service / stacklib / dlist.h
blob: 05b9abd97839aa2684474d63edc0f443f6aff20c [file] [log] [blame]
rjw6c1fd8f2022-11-30 14:33:01 +0800[diff] [blame]1/*****************************************************************************
2* Copyright Statement:
3* --------------------
4* This software is protected by Copyright and the information contained
5* herein is confidential. The software may not be copied and the information
6* contained herein may not be used or disclosed except with the written
7* permission of MediaTek Inc. (C) 2005
8*
9* BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
10* THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE")
11* RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON
12* AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES,
13* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
14* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
15* NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
16* SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
17* SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH
18* THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO
19* NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S
20* SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM.
21*
22* BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE
23* LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
24* AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE,
25* OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO
26* MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
27*
28* THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
29* WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
30* LAWS PRINCIPLES. ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
31* RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
32* THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
33*
34*****************************************************************************/
35
36/*****************************************************************************
37 *
38 * Filename:
39 * ---------
40 * dlist.h
41 *
42 * Project:
43 * --------
44 * Maui
45 *
46 * Description:
47 * ------------
48 * Header file for double linked list facility
49 *
50 * Author:
51 * -------
52 * -------
53 *
54 *============================================================================
55 * HISTORY
56 * Below this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
57 *------------------------------------------------------------------------------
58 * removed!
59 * removed!
60 * removed!
61 *
62 * removed!
63 * removed!
64 * removed!
65 * removed!
66 *
67 * removed!
68 * removed!
69 * removed!
70 *
71 * removed!
72 * removed!
73 * removed!
74 *
75 * removed!
76 * removed!
77 * removed!
78 *
79 * removed!
80 * removed!
81 * removed!
82 *
83 * removed!
84 * removed!
85 * removed!
86 *
87 * removed!
88 * removed!
89 * removed!
90 *
91 * removed!
92 * removed!
93 * removed!
94 *
95 * removed!
96 * removed!
97 * removed!
98 *
99 * removed!
100 * removed!
101 * removed!
102 *
103 * removed!
104 * removed!
105 * removed!
106 *
107 * removed!
108 * removed!
109 * removed!
110 *
111 * removed!
112 * removed!
113 * removed!
114 *
115 * removed!
116 * removed!
117 * removed!
118 *
119 * removed!
120 * removed!
121 * removed!
122 *
123 * removed!
124 * removed!
125 * removed!
126 *
127 * removed!
128 * removed!
129 * removed!
130 *
131 * removed!
132 * removed!
133 * removed!
134 *------------------------------------------------------------------------------
135 * Upper this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
136 *============================================================================
137 ****************************************************************************/
138#ifndef __DLIST_H__
139#define __DLIST_H__
140
141//#include "kal_release.h"
142/*RHR*/
143#include "kal_general_types.h"
144/*RHR*/
145/* TYPES DEFINITIONS ********************************************************/
146/*
147 * DLIST_LINK: The structure used for a link in a doubly linked list.
148 * The pThis field is a generic pointer that points to the item being listed.
149 * The pNext field is a pointer to the next link in the list, and is NULL for
150 * the last link in the list.
151 */
152typedef struct DLIST_LINK_TAG
153{
154 void *pThis; /*
155 * Pointer to the item in the list
156 */
157 struct DLIST_LINK_TAG *pPrev; /*
158 * Pointer to the previous link in the list
159 */
160 struct DLIST_LINK_TAG *pNext; /*
161 * Pointer to the next link in the list
162 */
163} DLIST_LINK;
164
165/*
166 * DLIST_HEAD: The structure used for the head of a doubly linked list.
167 * The ulCount field contains the number of links in the doubly linked list,
168 * and will be zero when the doubly linked list is empty.
169 * The pFirst field is a pointer to the first link in the doubly linked list,
170 * and will be NULL for an empty list.
171 */
172typedef struct DLIST_HEAD_TAG
173{
174 kal_uint32 ulCount; /*
175 * A count of the number of links in
176 * the list
177 */
178 struct DLIST_LINK_TAG *pFirst; /*
179 * A pointer to the first link in the
180 * list
181 */
182 struct DLIST_LINK_TAG *pLast; /*
183 * A pointer to the last link in the
184 * list
185 */
186} DLIST_HEAD;
187
188/*
189 * DLIST_HANDLE: Pointer to DLIST_HEAD structure to be used as a handle for the
190 * doubly linked list.
191 */
192typedef DLIST_HEAD *DLIST_HANDLE;
193
194/*
195 * DLIST_LINK_HANDLE: Pointer to DLIST_LINK structure to be used as a handle for
196 * a link in a doubly linked list.
197 */
198typedef DLIST_LINK *DLIST_LINK_HANDLE;
199
200
201/* GLOBAL VARIABLE DECLARATIONS *********************************************/
202/* The Omitted Storage Class Model is assumed. The storage class
203 * "extern" must be explicitly included on all referencing
204 * declarations, and the storage class must omitted from the single
205 * defining declaration for each external variable. The defining
206 * declaration can include an initializer, but it is not required to
207 * do so. It is invalid to have both an initiliazer and the storage
208 * class extern in a declaration (ref:[4.8.2; A Reference Manual]).
209 *
210 * Use global variables for performance improvement and always provide
211 * MACROS to manipulate them. E.g. SET(v) and GET. */
212
213/* PUBLIC FUNCTION PROTOTYPES ***********************************************/
214
215
216
217/**
218 * Description: Intialises a DLIST_HEAD
219 * structure before first use
220 *
221 * Notes: Sets ulCount to zero and pFirst to
222 * NULL.
223 */
224extern void DlistInit(DLIST_HANDLE hList);
225
226/**
227 * Description: Destroy the link list.
228 *
229 * Notes: Frees all links in the list, but not
230 * their items.
231 *
232 * @param hList
233 * @return kal_bool: TRUE if successful, FALSE is not
234 */
235extern kal_bool DlistDeleteAll_Dbg(DLIST_HANDLE hList,
236 kal_char *filename, kal_uint32 line);
237
238#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
239#define DlistDeleteAll(hList) \
240 DlistDeleteAll_Dbg(hList, __FILE__, __LINE__)
241#else
242#define DlistDeleteAll(hList) \
243 DlistDeleteAll_Dbg(hList, NULL, 0)
244#endif
245
246/****************************************************************************
247 * Function: DlistInsertAtStart
248 * Description: Adds a new link to the start of the doubly linked list
249 * Parameters: hList: Pointer to a DLIST_HEAD structure
250 * pThis: The item to be added to the doubly linked list
251 * Returns: kal_bool: TRUE if successful, FALSE is not
252 * Notes: Allocates memory for a new DLIST_LINK.
253 * Returns TRUE if the memory was allocated, else FALSE.
254 ****************************************************************************/
255
256extern kal_bool DlistInsertAtStart_Dbg(DLIST_HANDLE hList, void *pThis,
257 kal_char *filename, kal_uint32 line);
258extern kal_bool DlistInsertAtFront(DLIST_HANDLE hList, void *pThis, DLIST_LINK_HANDLE hLink);
259
260#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
261#define DlistInsertAtStart(hList, pThis) \
262 DlistInsertAtStart_Dbg(hList, pThis, __FILE__, __LINE__)
263#else
264#define DlistInsertAtStart(hList, pThis) \
265 DlistInsertAtStart_Dbg(hList, pThis, NULL, 0)
266#endif
267
268/****************************************************************************
269 * Function: DlistInsertAtEnd
270 * Description: Adds a new link to the end of the doubly linked list
271 * Parameters: hList: Pointer to a DLIST_HEAD structure
272 * pThis: The item to be added to the doubly linked list
273 * Returns: kal_bool: TRUE if successful, FALSE is not
274 * Notes: Allocates memory for a new DLIST_LINK.
275 * Returns TRUE if the memory was allocated, else FALSE.
276 ****************************************************************************/
277
278extern kal_bool DlistInsertAtEnd_Dbg(DLIST_HANDLE hList, void *pThis,
279 kal_char *filename, kal_uint32 line);
280#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
281#define DlistInsertAtEnd(hList, pThis) \
282 DlistInsertAtEnd_Dbg(hList, pThis, __FILE__, __LINE__)
283#else
284#define DlistInsertAtEnd(hList, pThis) \
285 DlistInsertAtEnd_Dbg(hList, pThis, NULL, 0)
286#endif
287
288/****************************************************************************
289 * Function: DlistInsertAfter
290 * Description: Adds a new link after the given link of the doubly linked list
291 * Parameters: hList: Pointer to a DLIST_HEAD structure
292 * phLink: Pointer to a pointer to the link to insert after
293 * pThis: The item to be added to the doubly linked list
294 * Returns: kal_bool: TRUE if successful, FALSE is not
295 * Notes: Need to use DlistFirst, DlistNext or DlistFind to set phLink
296 * before calling this function.
297 * Allocates memory for a new DLIST_LINK.
298 * Returns TRUE if the memory was allocated, else FALSE.
299 ****************************************************************************/
300
301extern kal_bool DlistInsertAfter_Dbg(DLIST_HANDLE hList,
302 DLIST_LINK_HANDLE *phLink, void *pThis,
303 kal_char *filename, kal_uint32 line);
304
305#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
306#define DlistInsertAfter(hList, phLink, pThis) \
307 DlistInsertAfter_Dbg(hList, phLink, pThis, __FILE__, __LINE__)
308#else
309#define DlistInsertAfter(hList, phLink, pThis) \
310 DlistInsertAfter_Dbg(hList, phLink, pThis, NULL, 0)
311#endif
312
313/****************************************************************************
314 * Function: DlistInsertBefore
315 * Description: Adds a new link before the given link of the doubly linked list
316 * Parameters: hList: Pointer to a DLIST_HEAD structure
317 * phLink: Pointer to a pointer to the link to insert before
318 * pThis: The item to be added to the doubly linked list
319 * Returns: kal_bool: TRUE if successful, FALSE is not
320 * Notes: Need to use DlistFirst, DlistNext or DlistFind to set phLink
321 * before calling this function.
322 * Allocates memory for a new DLIST_LINK.
323 * Returns TRUE if the memory was allocated, else FALSE.
324 ****************************************************************************/
325
326extern kal_bool DlistInsertBefore_Dbg(DLIST_HANDLE hList,
327 DLIST_LINK_HANDLE *phLink, void *pThis,
328 kal_char *filename, kal_uint32 line);
329
330#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
331#define DlistInsertBefore(hList, phLink, pThis) \
332 DlistInsertBefore_Dbg(hList, phLink, pThis, __FILE__, __LINE__)
333#else
334#define DlistInsertBefore(hList, phLink, pThis) \
335 DlistInsertBefore_Dbg(hList, phLink, pThis, NULL, 0)
336#endif
337
338/****************************************************************************
339 * Function: DlistSort
340 * Description: Sorts a doubly linked list into item order
341 * Parameters: hList: Pointer to a DLIST_HEAD structure
342 * Compare: Pointer to a function that compares two items,
343 * pThis and pNext, returning an int which is:
344 * zero if pThis == pNext
345 * negative if pThis < pNext
346 * positive if pThis > pNext
347 * Returns: kal_bool: TRUE if successful, FALSE is not
348 * Notes: DlistSort swaps items on Compare returning a positive result.
349 * To sort into the reverse order, use a different Compare
350 * function that inverts the positive and negative results.
351 ****************************************************************************/
352
353extern void DlistSort(DLIST_HANDLE hList, int (*Compare)(void *pThis, void *pNext));
354
355/****************************************************************************
356 * Function: DlistFirst
357 * Description: Gets the first item in the doubly linked list and sets the
358 * pointer at phLink for use by DlistNext, DlistInsertAfter or
359 * DlistDelete.
360 * Parameters: hList: Pointer to a DLIST_HEAD structure
361 * phLink: Pointer to a pointer to be set to the first link
362 * Returns: void *: Pointer to pThis of first link, or NULL if empty list.
363 * Notes: Might return NULL if pThis of first link is NULL pointer, or
364 * if the doubly linked list is empty. The pointer at phLink
365 * will be set to NULL if the doubly linked list is empty.
366 ****************************************************************************/
367
368extern void *DlistFirst(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink);
369
370/****************************************************************************
371 * Function: DlistLast
372 * Description: Gets the last item in the doubly linked list and sets the
373 * pointer at phLink for use by DlistPrev, DlistInsertAfter or
374 * DlistDelete.
375 * Parameters: hList: Pointer to a DLIST_HEAD structure
376 * phLink: Pointer to a pointer to be set to the last link
377 * Returns: void *: Pointer to pThis of last link, or NULL if empty list.
378 * Notes: Might return NULL if pThis of last link is NULL pointer, or
379 * if the doubly linked list is empty. The pointer at phLink
380 * will be set to NULL if the doubly linked list is empty.
381 ****************************************************************************/
382
383extern void *DlistLast(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink);
384
385/****************************************************************************
386 * Function: DlistNext
387 * Description: Gets the next item in the doubly linked list and sets the
388 * pointer at phLink for use by DlistInsertAfter or DlistDelete.
389 * Parameters: hList: Pointer to a DLIST_HEAD structure
390 * phLink: Pointer to a pointer to be set to the next link
391 * Returns: void *: Pointer to pThis of next link, or NULL if end of list.
392 * Notes: Might return NULL if pThis of first link is NULL pointer, or
393 * if the end of the doubly linked list has been reached. The
394 * pointer at phLink will be set to NULL if the end of the doubly
395 * linked list has been reached.
396 ****************************************************************************/
397
398extern void *DlistNext(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink);
399
400/****************************************************************************
401 * Function: DlistThis
402 * Description: Gets the current item in the doubly linked. Useful after a call
403 * to DlistDelete, where DlistNext will skip an item
404 * Parameters: hList: Pointer to a DLIST_HEAD structure
405 * phLink: Pointer to a pointer to be set to the next link
406 * Returns: void *: Pointer to pThis of this link.
407 * Notes: Might return NULL if pThis of this link is NULL pointer.
408 ****************************************************************************/
409
410extern void *DlistThis(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink);
411
412/****************************************************************************
413 * Function: DlistPrev
414 * Description: Gets the previous item in the doubly linked list and sets the
415 * pointer at phLink for use by DlistInsertAfter or DlistDelete.
416 * Parameters: hList: Pointer to a DLIST_HEAD structure
417 * phLink: Pointer to a pointer to be set to the previous link
418 * Returns: void *: Pointer to pThis of previous link, or NULL if end of
419 * list.
420 * Notes: Might return NULL if pThis of first link is NULL pointer, or
421 * if the end of the doubly linked list has been reached. The
422 * pointer at phLink will be set to NULL if the end of the doubly
423 * linked list has been reached.
424 ****************************************************************************/
425
426extern void *DlistPrev(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink);
427
428/****************************************************************************
429 * Function: DlistFind
430 * Description: Finds a particular item in a doubly linked list
431 * Parameters: hList: Pointer to a DLIST_HEAD structure
432 * phLink: Pointer to a pointer to be set to the found link
433 * pTarget: Pointer to the "value" being sought
434 * Compare: Pointer to a function that compares an item, pThis,
435 * with the "value" being sought, pTarget, returning an int which
436 * is zero if pThis == pTarget, else non-zero.
437 * Returns: void *: Pointer to pThis of link found, or NULL if not found.
438 * Notes: Sets the pointer at phLink to the link found, for use in
439 * subsequent DlistInsertAfter, DlistDelete or DlistNext calls.
440 ****************************************************************************/
441
442extern void *DlistFind(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink, void *pTarget,
443 int (*Compare)(void *pThis, void *pTarget));
444
445/****************************************************************************
446 * Function: DlistDelete
447 * Description: Deletes a particular item in a doubly linked list
448 * Parameters: hList: Pointer to a DLIST_HEAD structure
449 * phLink: Pointer to a pointer the link to be deleted
450 * Returns: kal_bool: TRUE if the pointer at phLink was not NULL, else FALSE
451 * Notes: Sets the pointer at phLink to the next link, for use in
452 * subsequent DlistInsertAfter, DlistDelete or DlistNext calls.
453 ****************************************************************************/
454
455extern kal_bool DlistDelete_Dbg(DLIST_HANDLE hList, DLIST_LINK_HANDLE *phLink,
456 kal_char *filename, kal_uint32 line);
457
458#if defined(DEBUG_KAL) && defined(DEBUG_BUF2)
459#define DlistDelete(hList, phLink) \
460 DlistDelete_Dbg(hList, phLink, __FILE__, __LINE__)
461#else
462#define DlistDelete(hList, phLink) \
463 DlistDelete_Dbg(hList, phLink, NULL, 0)
464#endif
465
466/****************************************************************************
467 * Function: DlistCount
468 * Description: Obtains the number of links in the doubly linked list
469 * Parameters: hList: Pointer to a DLIST_HEAD structure
470 * Returns: kal_uint32: the value of the DLIST_HEAD structure's ulCount field
471 * Notes: Enables functions using Dlist to treat DLIST_HEAD as a handle
472 ****************************************************************************/
473
474extern kal_uint32 DlistCount(DLIST_HANDLE hList);
475
476//#define KAREN_TRACE
477
478#ifndef GEN_FOR_PC
479//#include <stdio.h>
480#endif
481
482#endif /* __DLIST_H__ */