xref: /wlan-driver/qca-wifi-host-cmn/qdf/inc/qdf_list.h (revision 5113495b16420b49004c444715d2daae2066e7dc)
1 /*
2  * Copyright (c) 2014-2018, 2021 The Linux Foundation. All rights reserved.
3  * Copyright (c) 2023 Qualcomm Innovation Center, Inc. All rights reserved.
4  *
5  * Permission to use, copy, modify, and/or distribute this software for
6  * any purpose with or without fee is hereby granted, provided that the
7  * above copyright notice and this permission notice appear in all
8  * copies.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12  * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13  * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15  * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17  * PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 /**
21  *  DOC: qdf_list.h
22  *  QCA driver framework (QDF) list APIs
23  *  Definitions for QDF Linked Lists API
24  *
25  *  Lists are implemented as a doubly linked list. An item in a list can
26  *  be of any type as long as the datatype contains a field of type
27  *  qdf_link_t.
28  *
29  *  In general, a list is a doubly linked list of items with a pointer
30  *  to the front of the list and a pointer to the end of the list.  The
31  *  list items contain a forward and back link.
32  *
33  *  QDF linked list APIs are NOT thread safe so make sure to use appropriate
34  *  locking mechanisms to assure operations on the list are thread safe.
35  */
36 
37 #if !defined(__QDF_LIST_H)
38 #define __QDF_LIST_H
39 
40 /* Include Files */
41 #include <qdf_types.h>
42 #include <qdf_status.h>
43 #include <i_qdf_list.h>
44 #include <qdf_trace.h>
45 
46 typedef __qdf_list_node_t qdf_list_node_t;
47 typedef __qdf_list_t qdf_list_t;
48 
49 /* Function declarations */
50 
51 /**
52  * qdf_list_insert_before() - insert new node before the node
53  * @list: Pointer to list
54  * @new_node: Pointer to input node
55  * @node: node before which new node should be added.
56  *
57  * Return: QDF status
58  */
59 QDF_STATUS qdf_list_insert_before(qdf_list_t *list,
60 	qdf_list_node_t *new_node, qdf_list_node_t *node);
61 /**
62  * qdf_list_insert_after() - insert new node after the node
63  * @list: Pointer to list
64  * @new_node: Pointer to input node
65  * @node: node after which new node should be added.
66  *
67  * Return: QDF status
68  */
69 QDF_STATUS qdf_list_insert_after(qdf_list_t *list,
70 	qdf_list_node_t *new_node, qdf_list_node_t *node);
71 QDF_STATUS qdf_list_insert_front(qdf_list_t *list, qdf_list_node_t *node);
72 
73 QDF_STATUS qdf_list_insert_back_size(qdf_list_t *list, qdf_list_node_t *node,
74 				     uint32_t *size);
75 
76 QDF_STATUS qdf_list_remove_front(qdf_list_t *list, qdf_list_node_t **node1);
77 
78 QDF_STATUS qdf_list_peek_next(qdf_list_t *list,	qdf_list_node_t *node,
79 			      qdf_list_node_t **node1);
80 
81 /**
82  * qdf_list_create() - Create qdf list and initialize list head
83  * @list: object of list
84  * @max_size: max size of the list
85  *
86  * Return: none
87  */
qdf_list_create(__qdf_list_t * list,uint32_t max_size)88 static inline void qdf_list_create(__qdf_list_t *list, uint32_t max_size)
89 {
90 	__qdf_list_create(list, max_size);
91 }
92 
93 #define QDF_LIST_ANCHOR(list) __QDF_LIST_ANCHOR(list)
94 
95 #define QDF_LIST_NODE_INIT(prev, next) __QDF_LIST_NODE_INIT(prev, next)
96 #define QDF_LIST_NODE_INIT_SINGLE(node) __QDF_LIST_NODE_INIT_SINGLE(node)
97 
98 #define QDF_LIST_INIT(tail, head) __QDF_LIST_INIT(tail, head)
99 #define QDF_LIST_INIT_SINGLE(node) __QDF_LIST_INIT_SINGLE(node)
100 #define QDF_LIST_INIT_EMPTY(list) __QDF_LIST_INIT_EMPTY(list)
101 
102 #define qdf_list_for_each(list_ptr, cursor, node_field) \
103 	__qdf_list_for_each(list_ptr, cursor, node_field)
104 
105 #define qdf_list_for_each_del(list_ptr, cursor, next, node_field) \
106 	__qdf_list_for_each_del(list_ptr, cursor, next, node_field)
107 
108 #define qdf_list_for_each_from(list_ptr, cursor, node_field) \
109 	__qdf_list_for_each_from(list_ptr, cursor, node_field)
110 
111 #define qdf_list_for_each_continue(list_ptr, cursor, node_field) \
112 	__qdf_list_for_each_continue(list_ptr, cursor, node_field)
113 
114 #define qdf_list_first_entry_or_null(list_ptr, type, node_field) \
115 	__qdf_list_first_entry_or_null(list_ptr, type, node_field)
116 
117 #define qdf_list_last_entry(list_ptr, type, node_field) \
118 	__qdf_list_last_entry(list_ptr, type, node_field)
119 
120 /**
121  * qdf_init_list_head() - initialize list head
122  * @list_head: pointer to list head
123  *
124  * Return: none
125  */
qdf_init_list_head(__qdf_list_node_t * list_head)126 static inline void qdf_init_list_head(__qdf_list_node_t *list_head)
127 {
128 	__qdf_init_list_head(list_head);
129 }
130 
131 /**
132  * qdf_list_destroy() - Destroy the list
133  * @list: object of list
134  * Return: none
135  */
qdf_list_destroy(qdf_list_t * list)136 static inline void qdf_list_destroy(qdf_list_t *list)
137 {
138 	if (list->count != 0) {
139 		QDF_TRACE(QDF_MODULE_ID_HDD, QDF_TRACE_LEVEL_ERROR,
140 			  "%s: list length not equal to zero", __func__);
141 		QDF_ASSERT(0);
142 	}
143 }
144 
145 /**
146  * qdf_list_size() - gives the size of the list
147  * @list: object of list
148  *
149  * Return: uint32_t size of the list
150  */
qdf_list_size(qdf_list_t * list)151 static inline uint32_t qdf_list_size(qdf_list_t *list)
152 {
153 	return __qdf_list_size(list);
154 }
155 
156 /**
157  * qdf_list_max_size() - gives the max size of the list
158  * @list: object of list
159  * Return: max size of the list
160  */
qdf_list_max_size(qdf_list_t * list)161 static inline uint32_t qdf_list_max_size(qdf_list_t *list)
162 {
163 	return __qdf_list_max_size(list);
164 }
165 
166 QDF_STATUS qdf_list_insert_back(qdf_list_t *list, qdf_list_node_t *node);
167 
168 QDF_STATUS qdf_list_remove_back(qdf_list_t *list, qdf_list_node_t **node1);
169 
170 QDF_STATUS qdf_list_peek_front(qdf_list_t *list, qdf_list_node_t **node1);
171 
172 QDF_STATUS qdf_list_remove_node(qdf_list_t *list,
173 				qdf_list_node_t *node_to_remove);
174 
175 bool qdf_list_empty(qdf_list_t *list);
176 
177 /**
178  * qdf_list_has_node() - check if a node is in a list
179  * @list: pointer to the list being searched
180  * @node: pointer to the node to search for
181  *
182  * This API has a time complexity of O(n).
183  *
184  * Return: true if the node is in the list
185  */
186 bool qdf_list_has_node(qdf_list_t *list, qdf_list_node_t *node);
187 
188 /**
189  * qdf_list_node_in_any_list() - ensure @node is a member of a list
190  * @node: list node to check
191  *
192  * This API has a time complexity of O(1). See also qdf_list_has_node().
193  *
194  * Return: true, if @node appears to be in a list
195  */
196 bool qdf_list_node_in_any_list(const qdf_list_node_t *node);
197 
198 /**
199  * qdf_list_join - Join two lists and reinitialize the emptied list
200  * @list1: Pointer to list 1
201  * @list2: Pointer to list 2
202  *
203  * This API joins list1 and list2 and writes the resultant list (list1 + list2)
204  * to list1. list2 is re initialized to an empty list.
205  *
206  * Return: QDF_STATUS of operation
207  */
208 QDF_STATUS qdf_list_join(qdf_list_t *list1, qdf_list_t *list2);
209 
210 /**
211  * qdf_list_split - Split a list into two chunks
212  * @new: Pointer to the list to store one of the chunks after splitting.
213  * This list will be overwritten by the API and hence it should be
214  * an empty list to avoid data loss.
215  * @list: Pointer to the list to be split
216  * @node: Pointer to a node within the @list. If @node is not present in
217  * the @list, behaviour is undefined.
218  *
219  * This API splits @list after @node. The initial portion of the @list
220  * up to and including @node will be moved to @new. The remaining portion will
221  * be assigned to @list.
222  */
223 QDF_STATUS qdf_list_split(qdf_list_t *new, qdf_list_t *list,
224 			  qdf_list_node_t *node);
225 #endif /* __QDF_LIST_H */
226