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 */ 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 */ 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 */ 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 * @size: size of the list 149 * Return: uint32_t 150 */ 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 */ 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