1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2020 Intel Corporation
4 #ifndef __INCLUDE_RTE_SWX_TABLE_H__
5 #define __INCLUDE_RTE_SWX_TABLE_H__
19 #include <sys/queue.h>
22 enum rte_swx_table_match_type {
23 /** Wildcard Match (WM). */
24 RTE_SWX_TABLE_MATCH_WILDCARD,
26 /** Longest Prefix Match (LPM). */
27 RTE_SWX_TABLE_MATCH_LPM,
29 /** Exact Match (EM). */
30 RTE_SWX_TABLE_MATCH_EXACT,
33 /** Table creation parameters. */
34 struct rte_swx_table_params {
35 /** Table match type. */
36 enum rte_swx_table_match_type match_type;
38 /** Key size in bytes. */
41 /** Offset of the first byte of the key within the key buffer. */
44 /** Mask of *key_size* bytes logically laid over the bytes at positions
45 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in
46 * order to specify which bits from the key buffer are part of the key
47 * and which ones are not. A bit value of 1 in the *key_mask0* means the
48 * respective bit in the key buffer is part of the key, while a bit
49 * value of 0 means the opposite. A NULL value means that all the bits
50 * are part of the key, i.e. the *key_mask0* is an all-ones mask.
54 /** Maximum size (in bytes) of the action data. The data stored in the
55 * table for each entry is equal to *action_data_size* plus 8 bytes,
56 * which are used to store the action ID.
58 uint32_t action_data_size;
60 /** Maximum number of keys to be stored in the table together with their
67 struct rte_swx_table_entry {
68 /** Used to facilitate the membership of this table entry to a
71 TAILQ_ENTRY(rte_swx_table_entry) node;
73 /** Key value for the current entry. Array of *key_size* bytes or NULL
74 * if the *key_size* for the current table is 0.
78 /** Key mask for the current entry. Array of *key_size* bytes that is
79 * logically and'ed with *key_mask0* of the current table. A NULL value
80 * means that all the key bits already enabled by *key_mask0* are part
81 * of the key of the current entry.
85 /** Placeholder for a possible compressed version of the *key* and
86 * *key_mask* of the current entry. Typically a hash signature, its main
87 * purpose is to the linked list search operation. Should be ignored by
88 * the API functions below.
90 uint64_t key_signature;
92 /** Key priority for the current entry. Useful for wildcard match (as
93 * match rules are commonly overlapping with other rules), ignored for
94 * exact match (as match rules never overlap, hence all rules have the
95 * same match priority) and for LPM (match priority is driven by the
96 * prefix length, with non-overlapping prefixes essentially having the
97 * same match priority). Value 0 indicates the highest match priority.
99 uint32_t key_priority;
101 /** Action ID for the current entry. */
104 /** Action data for the current entry. Its size is defined by the action
105 * specified by the *action_id*. It must be NULL when the action data
106 * size of the *action_id* action is NULL. It must never exceed the
107 * *action_data_size* of the table.
109 uint8_t *action_data;
112 /** List of table entries. */
113 TAILQ_HEAD(rte_swx_table_entry_list, rte_swx_table_entry);
116 * Table memory footprint get
119 * Table create parameters.
123 * Any additional table create arguments. It may be NULL.
125 * Table memory footprint in bytes, if successful, or zero, on error.
128 (*rte_swx_table_footprint_get_t)(struct rte_swx_table_params *params,
129 struct rte_swx_table_entry_list *entries,
133 * Table mailbox size get
135 * The mailbox is used to store the context of a lookup operation that is in
136 * progress and it is passed as a parameter to the lookup operation. This allows
137 * for multiple concurrent lookup operations into the same table.
140 * Table memory footprint in bytes, on success, or zero, on error.
143 (*rte_swx_table_mailbox_size_get_t)(void);
149 * Table creation parameters.
151 * Entries to be added to the table at creation time.
153 * Any additional table create arguments. It may be NULL.
154 * @param[in] numa_node
155 * Non-Uniform Memory Access (NUMA) node.
157 * Table handle, on success, or NULL, on error.
160 (*rte_swx_table_create_t)(struct rte_swx_table_params *params,
161 struct rte_swx_table_entry_list *entries,
171 * Entry to be added to the table.
173 * 0 on success or the following error codes otherwise:
174 * -EINVAL: Invalid table handle, entry or entry field;
175 * -ENOSPC: Table full.
178 (*rte_swx_table_add_t)(void *table,
179 struct rte_swx_table_entry *entry);
187 * Entry to be deleted from the table. The entry *action_id* and *action_data*
188 * fields are ignored.
190 * 0 on success or the following error codes otherwise:
191 * -EINVAL: Invalid table handle, entry or entry field;
192 * -ENOSPC: Table full.
195 (*rte_swx_table_delete_t)(void *table,
196 struct rte_swx_table_entry *entry);
201 * The table lookup operation searches a given key in the table and upon its
202 * completion it returns an indication of whether the key is found in the table
203 * (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and
204 * the action_data associated with the key are also returned.
206 * Multiple invocations of this function may be required in order to complete a
207 * single table lookup operation for a given table and a given lookup key. The
208 * completion of the table lookup operation is flagged by a return value of 1;
209 * in case of a return value of 0, the function must be invoked again with
210 * exactly the same arguments.
212 * The mailbox argument is used to store the context of an on-going table lookup
213 * operation. The mailbox mechanism allows for multiple concurrent table lookup
214 * operations into the same table.
216 * The typical reason an implementation may choose to split the table lookup
217 * operation into multiple steps is to hide the latency of the inherrent memory
218 * read operations: before a read operation with the source data likely not in
219 * the CPU cache, the source data prefetch is issued and the table lookup
220 * operation is postponed in favor of some other unrelated work, which the CPU
221 * executes in parallel with the source data being fetched into the CPU cache;
222 * later on, the table lookup operation is resumed, this time with the source
223 * data likely to be read from the CPU cache with no CPU pipeline stall, which
224 * significantly improves the table lookup performance.
229 * Mailbox for the current table lookup operation.
231 * Lookup key. Its size mult be equal to the table *key_size*. If the latter
232 * is zero, then the lookup key must be NULL.
233 * @param[out] action_id
234 * ID of the action associated with the *key*. Must point to a valid 64-bit
235 * variable. Only valid when the function returns 1 and *hit* is set to true.
236 * @param[out] action_data
237 * Action data for the *action_id* action. Must point to a valid array of
238 * table *action_data_size* bytes. Only valid when the function returns 1 and
239 * *hit* is set to true.
241 * Only valid when the function returns 1. Set to non-zero (true) on table
242 * lookup hit and to zero (false) on table lookup miss.
244 * 0 when the table lookup operation is not yet completed, and 1 when the
245 * table lookup operation is completed. No other return values are allowed.
248 (*rte_swx_table_lookup_t)(void *table,
252 uint8_t **action_data,
262 (*rte_swx_table_free_t)(void *table);
264 /** Table operations. */
265 struct rte_swx_table_ops {
266 /** Table memory footprint get. Set to NULL when not supported. */
267 rte_swx_table_footprint_get_t footprint_get;
269 /** Table mailbox size get. When NULL, the mailbox size is 0. */
270 rte_swx_table_mailbox_size_get_t mailbox_size_get;
272 /** Table create. Must be non-NULL. */
273 rte_swx_table_create_t create;
275 /** Incremental table entry add. Set to NULL when not supported, in
276 * which case the existing table has to be destroyed and a new table
277 * built from scratch with the new entry included.
279 rte_swx_table_add_t add;
281 /** Incremental table entry delete. Set to NULL when not supported, in
282 * which case the existing table has to be destroyed and a new table
283 * built from scratch with the entry excluded.
285 rte_swx_table_delete_t del;
287 /** Table lookup. Must be non-NULL. */
288 rte_swx_table_lookup_t lkp;
290 /** Table free. Must be non-NULL. */
291 rte_swx_table_free_t free;