drivers/staging/csr/oska/list.h

   1 /*
   2  * Operating system kernel abstraction -- linked lists.
   3  *
   4  * Copyright (C) 2009-2010 Cambridge Silicon Radio Ltd.
   5  *
   6  * Refer to LICENSE.txt included with this source code for details on
   7  * the license terms.
   8  */
   9 #ifndef __OSKA_LIST_H
  10 #define __OSKA_LIST_H
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 /**
  17  * @defgroup list Linked Lists
  18  *
  19  * Generic linked list implementations suitable for all platforms.
  20  *
  21  *   - Circular, doubly-linked list (struct os_list).
  22  */
  23
  24 /**
  25  * A list node.
  26  *
  27  * This list node structure should be the first field within any
  28  * structure that is to be stored in a list.
  29  *
  30  * @see struct os_list
  31  * @ingroup list
  32  */
  33 struct os_list_node {
  34     /**
  35      * The pointer to the previous node in the list, or os_list_end()
  36      * if the end of the list has been reached.
  37      */
  38     struct os_list_node *prev;
  39     /**
  40      * The pointer to the next node in the list, or os_list_end() if
  41      * the end of the list has been reached.
  42      */
  43     struct os_list_node *next;
  44 };
  45
  46 /**
  47  * A circular, doubly-linked list of nodes.
  48  *
  49  * Structures to be stored in a list should contains a struct
  50  * os_list_node as the \e first field.
  51  * \code
  52  *   struct foo {
  53  *      struct os_list_node node;
  54  *      int bar;
  55  *      ...
  56  *   };
  57  * \endcode
  58  * Going to/from a struct foo to a list node is then simple.
  59  * \code
  60  *   struct os_list_node *node;
  61  *   struct foo *foo;
  62  *   [...]
  63  *   node = &foo->node;
  64  *   foo = (struct foo *)node
  65  * \endcode
  66  * Lists must be initialized with os_list_init() before adding nodes
  67  * with os_list_add_tail().  The node at the head of the list is
  68  * obtained with os_list_head().  Nodes are removed from the list with
  69  * os_list_del().
  70  *
  71  * A list can be interated from the head to the tail using:
  72  * \code
  73  *   struct os_list_node *node;
  74  *   for (node = os_list_head(list); node != os_list_end(list); node = node->next) {
  75  *      struct foo *foo = (struct foo *)node;
  76  *      ...
  77  *   }
  78  * \endcode
  79  *
  80  * In the above loop, the current list node cannot be removed (with
  81  * os_list_del()).  If this is required use this form of loop:
  82  * \code
  83  *   struct os_list_node *node, *next;
  84  *   for (node = os_list_head(list), next = node->next;
  85  *        node != os_list_end(list);
  86  *        node = next, next = node->next) {
  87  *      struct foo *foo = (struct foo *)node;
  88  *      ...
  89  *      os_list_del(node);
  90  *      ...
  91  *   }
  92  * \endcode
  93  *
  94  * @ingroup list
  95  */
  96 struct os_list {
  97     /**
  98      * @internal
  99      * The dummy node marking the end of the list.
 100      */
 101     struct os_list_node head;
 102 };
 103
 104 void os_list_init(struct os_list *list);
 105 int os_list_empty(struct os_list *list);
 106 void os_list_add_tail(struct os_list *list, struct os_list_node *node);
 107 void os_list_del(struct os_list_node *node);
 108 struct os_list_node *os_list_head(struct os_list *list);
 109 struct os_list_node *os_list_end(struct os_list *list);
 110
 111 #ifdef __cplusplus
 112 } /* extern "C" */
 113 #endif
 114
 115 #endif /* #ifndef __OSKA_LIST_H */