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