1 /*
2  * Copyright (c) 2018-2019 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_hashtable.h - Public APIs for a hashtable data structure
22  */
23 
24 #ifndef __QDF_HASHTABLE_H
25 #define __QDF_HASHTABLE_H
26 
27 #include "i_qdf_hashtable.h"
28 
29 /*
30  * qdf_ht - opaque hashtable data type
31  */
32 #define qdf_ht __qdf_ht
33 
34 /*
35  * qdf_ht_entry - opaque hashtable entry for membership in a qdf_ht
36  */
37 #define qdf_ht_entry __qdf_ht_entry
38 
39 /**
40  * qdf_ht_declare() - declare a new qdf_ht
41  * @name: variable name of the hashtable to declare
42  * @bits: number of hash bits to use; buckets=2^bits; Needs to be a compile
43  *        time constant
44  *
45  */
46 #define qdf_ht_declare(name, bits) __qdf_ht_declare(name, bits)
47 
48 /**
49  * qdf_ht_init() - initialize a qdf_ht instance
50  * @table: a non-pointer qdf_ht instance to initialize
51  *
52  * Return: none
53  */
54 #define qdf_ht_init(table) __qdf_ht_init(table)
55 
56 /**
57  * qdf_ht_deinit() - de-initialize a qdf_ht instance
58  * @table: a non-pointer qdf_ht instance to de-initialize
59  *
60  * Return: none
61  */
62 #define qdf_ht_deinit(table) __qdf_ht_deinit(table)
63 
64 /**
65  * qdf_ht_empty() - check if a qdf_ht has any entries
66  * @table: a non-pointer qdf_ht instance to check
67  *
68  * Return: true if the hashtable is empty
69  */
70 #define qdf_ht_empty(table) __qdf_ht_empty(table)
71 
72 /**
73  * qdf_ht_add() - add an entry to a qdf_ht instance
74  * @table: a non-pointer qdf_ht instance to add an entry to
75  * @entry: pointer to a qdf_ht_entry instance to add to @table
76  * @key: the key to use for entry insertion and lookup
77  *
78  * Return: none
79  */
80 #define qdf_ht_add(table, entry, key) __qdf_ht_add(table, entry, key)
81 
82 /**
83  * qdf_ht_remove() - remove and entry from a qdf_ht instance
84  * @entry: pointer to a qdf_ht_entry instance to remove
85  *
86  * Return: none
87  */
88 #define qdf_ht_remove(entry) __qdf_ht_remove(entry)
89 
90 /**
91  * qdf_ht_for_each() - iterate all entries in @table
92  * @table: a non-pointer qdf_ht instance to iterate
93  * @i: int type cursor populated with the bucket index
94  * @cursor: container struct pointer populated with each iteration
95  * @entry_field: name of the entry field in the entry container struct
96  */
97 #define qdf_ht_for_each(table, i, cursor, entry_field) \
98 	__qdf_ht_for_each(table, i, cursor, entry_field)
99 
100 /**
101  * qdf_ht_for_each_safe() - iterate all entries in @table safe against removal
102  * of hash entry.
103  * @table: a non-pointer qdf_ht instance to iterate
104  * @i: int type cursor populated with the bucket index
105  * @tmp: a &struct used for temporary storage
106  * @cursor: container struct pointer populated with each iteration
107  * @entry_field: name of the entry field in the entry container struct
108  */
109 #define qdf_ht_for_each_safe(table, i, tmp, cursor, entry_field) \
110 	__qdf_ht_for_each_safe(table, i, tmp, cursor, entry_field)
111 
112 /**
113  * qdf_ht_for_each_in_bucket() - iterate entries in the bucket for @key
114  * @table: a non-pointer qdf_ht instance to iterate
115  * @cursor: container struct pointer populated with each iteration
116  * @entry_field: name of the entry field in the entry container struct
117  * @key: key used to lookup the hashtable bucket
118  */
119 #define qdf_ht_for_each_in_bucket(table, cursor, entry_field, key) \
120 	__qdf_ht_for_each_in_bucket(table, cursor, entry_field, key)
121 
122 /**
123  * qdf_ht_for_each_match() - iterates through each entry matching @key
124  * @table: a non-pointer qdf_ht instance to iterate
125  * @cursor: container struct pointer populated with each iteration
126  * @entry_field: name of the entry field in the entry container struct
127  * @key: key used to lookup the entries
128  * @key_field: name of the key field in the entry container struct
129  */
130 #define qdf_ht_for_each_match(table, cursor, entry_field, key, key_field) \
131 	__qdf_ht_for_each_match(table, cursor, entry_field, key, key_field)
132 
133 /**
134  * qdf_ht_get() - get the first entry with a key matching @key
135  * @table: a non-pointer qdf_ht instance to look in
136  * @cursor: container struct pointer populated with each iteration
137  * @entry_field: name of the entry field in the entry container struct
138  * @key: key used to lookup the entry
139  * @key_field: name of the key field in the entry container struct
140  */
141 #define qdf_ht_get(table, cursor, entry_field, key, key_field) \
142 	__qdf_ht_get(table, cursor, entry_field, key, key_field)
143 
144 #endif /* __QDF_HASHTABLE_H */
145