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