net/mlx5: use SPDX tags in 6WIND copyrighted files
[dpdk.git] / lib / librte_table / rte_table.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2010-2014 Intel Corporation
3  */
4
5 #ifndef __INCLUDE_RTE_TABLE_H__
6 #define __INCLUDE_RTE_TABLE_H__
7
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11
12 /**
13  * @file
14  * RTE Table
15  *
16  * This tool is part of the DPDK Packet Framework tool suite and provides
17  * a standard interface to implement different types of lookup tables for data
18  * plane processing.
19  *
20  * Virtually any search algorithm that can uniquely associate data to a lookup
21  * key can be fitted under this lookup table abstraction. For the flow table
22  * use-case, the lookup key is an n-tuple of packet fields that uniquely
23  * identifies a traffic flow, while data represents actions and action
24  * meta-data associated with the same traffic flow.
25  *
26  ***/
27
28 #include <stdint.h>
29 #include <rte_port.h>
30
31 struct rte_mbuf;
32
33 /** Lookup table statistics */
34 struct rte_table_stats {
35         uint64_t n_pkts_in;
36         uint64_t n_pkts_lookup_miss;
37 };
38
39 /**
40  * Lookup table create
41  *
42  * @param params
43  *   Parameters for lookup table creation. The underlying data structure is
44  *   different for each lookup table type.
45  * @param socket_id
46  *   CPU socket ID (e.g. for memory allocation purpose)
47  * @param entry_size
48  *   Data size of each lookup table entry (measured in bytes)
49  * @return
50  *   Handle to lookup table instance
51  */
52 typedef void* (*rte_table_op_create)(void *params, int socket_id,
53         uint32_t entry_size);
54
55 /**
56  * Lookup table free
57  *
58  * @param table
59  *   Handle to lookup table instance
60  * @return
61  *   0 on success, error code otherwise
62  */
63 typedef int (*rte_table_op_free)(void *table);
64
65 /**
66  * Lookup table entry add
67  *
68  * @param table
69  *   Handle to lookup table instance
70  * @param key
71  *   Lookup key
72  * @param entry
73  *   Data to be associated with the current key. This parameter has to point to
74  *   a valid memory buffer where the first entry_size bytes (table create
75  *   parameter) are populated with the data.
76  * @param key_found
77  *   After successful invocation, *key_found is set to a value different than 0
78  *   if the current key is already present in the table and to 0 if not. This
79  *   pointer has to be set to a valid memory location before the table entry add
80  *   function is called.
81  * @param entry_ptr
82  *   After successful invocation, *entry_ptr stores the handle to the table
83  *   entry containing the data associated with the current key. This handle can
84  *   be used to perform further read-write accesses to this entry. This handle
85  *   is valid until the key is deleted from the table or the same key is
86  *   re-added to the table, typically to associate it with different data. This
87  *   pointer has to be set to a valid memory location before the function is
88  *   called.
89  * @return
90  *   0 on success, error code otherwise
91  */
92 typedef int (*rte_table_op_entry_add)(
93         void *table,
94         void *key,
95         void *entry,
96         int *key_found,
97         void **entry_ptr);
98
99 /**
100  * Lookup table entry delete
101  *
102  * @param table
103  *   Handle to lookup table instance
104  * @param key
105  *   Lookup key
106  * @param key_found
107  *   After successful invocation, *key_found is set to a value different than 0
108  *   if the current key was present in the table before the delete operation
109  *   was performed and to 0 if not. This pointer has to be set to a valid
110  *   memory location before the table entry delete function is called.
111  * @param entry
112  *   After successful invocation, if the key is found in the table (*key found
113  *   is different than 0 after function call is completed) and entry points to
114  *   a valid buffer (entry is set to a value different than NULL before the
115  *   function is called), then the first entry_size bytes (table create
116  *   parameter) in *entry store a copy of table entry that contained the data
117  *   associated with the current key before the key was deleted.
118  * @return
119  *   0 on success, error code otherwise
120  */
121 typedef int (*rte_table_op_entry_delete)(
122         void *table,
123         void *key,
124         int *key_found,
125         void *entry);
126
127 /**
128  * Lookup table entry add bulk
129  *
130  * @param table
131  *   Handle to lookup table instance
132  * @param key
133  *   Array containing lookup keys
134  * @param entries
135  *   Array containing data to be associated with each key. Every item in the
136  *   array has to point to a valid memory buffer where the first entry_size
137  *   bytes (table create parameter) are populated with the data.
138  * @param n_keys
139  *   Number of keys to add
140  * @param key_found
141  *   After successful invocation, key_found for every item in the array is set
142  *   to a value different than 0 if the current key is already present in the
143  *   table and to 0 if not. This pointer has to be set to a valid memory
144  *   location before the table entry add function is called.
145  * @param entries_ptr
146  *   After successful invocation, array *entries_ptr stores the handle to the
147  *   table entry containing the data associated with every key. This handle can
148  *   be used to perform further read-write accesses to this entry. This handle
149  *   is valid until the key is deleted from the table or the same key is
150  *   re-added to the table, typically to associate it with different data. This
151  *   pointer has to be set to a valid memory location before the function is
152  *   called.
153  * @return
154  *   0 on success, error code otherwise
155  */
156 typedef int (*rte_table_op_entry_add_bulk)(
157         void *table,
158         void **keys,
159         void **entries,
160         uint32_t n_keys,
161         int *key_found,
162         void **entries_ptr);
163
164 /**
165  * Lookup table entry delete bulk
166  *
167  * @param table
168  *   Handle to lookup table instance
169  * @param key
170  *   Array containing lookup keys
171  * @param n_keys
172  *   Number of keys to delete
173  * @param key_found
174  *   After successful invocation, key_found for every item in the array is set
175  *   to a value different than 0if the current key was present in the table
176  *   before the delete operation was performed and to 0 if not. This pointer
177  *   has to be set to a valid memory location before the table entry delete
178  *   function is called.
179  * @param entries
180  *   If entries pointer is NULL, this pointer is ignored for every entry found.
181  *   Else, after successful invocation, if specific key is found in the table
182  *   (key_found is different than 0 for this item after function call is
183  *   completed) and item of entry array points to a valid buffer (entry is set
184  *   to a value different than NULL before the function is called), then the
185  *   first entry_size bytes (table create parameter) in *entry store a copy of
186  *   table entry that contained the data associated with the current key before
187  *   the key was deleted.
188  * @return
189  *   0 on success, error code otherwise
190  */
191 typedef int (*rte_table_op_entry_delete_bulk)(
192         void *table,
193         void **keys,
194         uint32_t n_keys,
195         int *key_found,
196         void **entries);
197
198 /**
199  * Lookup table lookup
200  *
201  * @param table
202  *   Handle to lookup table instance
203  * @param pkts
204  *   Burst of input packets specified as array of up to 64 pointers to struct
205  *   rte_mbuf
206  * @param pkts_mask
207  *   64-bit bitmask specifying which packets in the input burst are valid. When
208  *   pkts_mask bit n is set, then element n of pkts array is pointing to a
209  *   valid packet. Otherwise, element n of pkts array does not point to a valid
210  *   packet, therefore it will not be accessed.
211  * @param lookup_hit_mask
212  *   Once the table lookup operation is completed, this 64-bit bitmask
213  *   specifies which of the valid packets in the input burst resulted in lookup
214  *   hit. For each valid input packet (pkts_mask bit n is set), the following
215  *   are true on lookup hit: lookup_hit_mask bit n is set, element n of entries
216  *   array is valid and it points to the lookup table entry that was hit. For
217  *   each valid input packet (pkts_mask bit n is set), the following are true
218  *   on lookup miss: lookup_hit_mask bit n is not set and element n of entries
219  *   array is not valid.
220  * @param entries
221  *   Once the table lookup operation is completed, this array provides the
222  *   lookup table entries that were hit, as described above. It is required
223  *   that this array is always pre-allocated by the caller of this function
224  *   with exactly 64 elements. The implementation is allowed to speculatively
225  *   modify the elements of this array, so elements marked as invalid in
226  *   lookup_hit_mask once the table lookup operation is completed might have
227  *   been modified by this function.
228  * @return
229  *   0 on success, error code otherwise
230  */
231 typedef int (*rte_table_op_lookup)(
232         void *table,
233         struct rte_mbuf **pkts,
234         uint64_t pkts_mask,
235         uint64_t *lookup_hit_mask,
236         void **entries);
237
238 /**
239  * Lookup table stats read
240  *
241  * @param table
242  *   Handle to lookup table instance
243  * @param stats
244  *   Handle to table stats struct to copy data
245  * @param clear
246  *   Flag indicating that stats should be cleared after read
247  *
248  * @return
249  *   Error code or 0 on success.
250  */
251 typedef int (*rte_table_op_stats_read)(
252         void *table,
253         struct rte_table_stats *stats,
254         int clear);
255
256 /** Lookup table interface defining the lookup table operation */
257 struct rte_table_ops {
258         rte_table_op_create f_create;                 /**< Create */
259         rte_table_op_free f_free;                     /**< Free */
260         rte_table_op_entry_add f_add;                 /**< Entry add */
261         rte_table_op_entry_delete f_delete;           /**< Entry delete */
262         rte_table_op_entry_add_bulk f_add_bulk;       /**< Add entry bulk */
263         rte_table_op_entry_delete_bulk f_delete_bulk; /**< Delete entry bulk */
264         rte_table_op_lookup f_lookup;                 /**< Lookup */
265         rte_table_op_stats_read f_stats;              /**< Stats */
266 };
267
268 #ifdef __cplusplus
269 }
270 #endif
271
272 #endif