Home | History | Annotate | Download | only in inc
      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