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