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 /** Action ID for the current entry. */
95 /** Action data for the current entry. Its size is defined by the action
96 * specified by the *action_id*. It must be NULL when the action data
97 * size of the *action_id* action is NULL. It must never exceed the
98 * *action_data_size* of the table.
100 uint8_t *action_data;
103 /** List of table entries. */
104 TAILQ_HEAD(rte_swx_table_entry_list, rte_swx_table_entry);
107 * Table memory footprint get
110 * Table create parameters.
114 * Any additional table create arguments. It may be NULL.
116 * Table memory footprint in bytes, if successful, or zero, on error.
119 (*rte_swx_table_footprint_get_t)(struct rte_swx_table_params *params,
120 struct rte_swx_table_entry_list *entries,
124 * Table mailbox size get
126 * The mailbox is used to store the context of a lookup operation that is in
127 * progress and it is passed as a parameter to the lookup operation. This allows
128 * for multiple concurrent lookup operations into the same table.
131 * Table memory footprint in bytes, on success, or zero, on error.
134 (*rte_swx_table_mailbox_size_get_t)(void);
140 * Table creation parameters.
142 * Entries to be added to the table at creation time.
144 * Any additional table create arguments. It may be NULL.
145 * @param[in] numa_node
146 * Non-Uniform Memory Access (NUMA) node.
148 * Table handle, on success, or NULL, on error.
151 (*rte_swx_table_create_t)(struct rte_swx_table_params *params,
152 struct rte_swx_table_entry_list *entries,
162 * Entry to be added to the table.
164 * 0 on success or the following error codes otherwise:
165 * -EINVAL: Invalid table handle, entry or entry field;
166 * -ENOSPC: Table full.
169 (*rte_swx_table_add_t)(void *table,
170 struct rte_swx_table_entry *entry);
178 * Entry to be deleted from the table. The entry *action_id* and *action_data*
179 * fields are ignored.
181 * 0 on success or the following error codes otherwise:
182 * -EINVAL: Invalid table handle, entry or entry field;
183 * -ENOSPC: Table full.
186 (*rte_swx_table_delete_t)(void *table,
187 struct rte_swx_table_entry *entry);
192 * The table lookup operation searches a given key in the table and upon its
193 * completion it returns an indication of whether the key is found in the table
194 * (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and
195 * the action_data associated with the key are also returned.
197 * Multiple invocations of this function may be required in order to complete a
198 * single table lookup operation for a given table and a given lookup key. The
199 * completion of the table lookup operation is flagged by a return value of 1;
200 * in case of a return value of 0, the function must be invoked again with
201 * exactly the same arguments.
203 * The mailbox argument is used to store the context of an on-going table lookup
204 * operation. The mailbox mechanism allows for multiple concurrent table lookup
205 * operations into the same table.
207 * The typical reason an implementation may choose to split the table lookup
208 * operation into multiple steps is to hide the latency of the inherrent memory
209 * read operations: before a read operation with the source data likely not in
210 * the CPU cache, the source data prefetch is issued and the table lookup
211 * operation is postponed in favor of some other unrelated work, which the CPU
212 * executes in parallel with the source data being fetched into the CPU cache;
213 * later on, the table lookup operation is resumed, this time with the source
214 * data likely to be read from the CPU cache with no CPU pipeline stall, which
215 * significantly improves the table lookup performance.
220 * Mailbox for the current table lookup operation.
222 * Lookup key. Its size mult be equal to the table *key_size*. If the latter
223 * is zero, then the lookup key must be NULL.
224 * @param[out] action_id
225 * ID of the action associated with the *key*. Must point to a valid 64-bit
226 * variable. Only valid when the function returns 1 and *hit* is set to true.
227 * @param[out] action_data
228 * Action data for the *action_id* action. Must point to a valid array of
229 * table *action_data_size* bytes. Only valid when the function returns 1 and
230 * *hit* is set to true.
232 * Only valid when the function returns 1. Set to non-zero (true) on table
233 * lookup hit and to zero (false) on table lookup miss.
235 * 0 when the table lookup operation is not yet completed, and 1 when the
236 * table lookup operation is completed. No other return values are allowed.
239 (*rte_swx_table_lookup_t)(void *table,
243 uint8_t **action_data,
253 (*rte_swx_table_free_t)(void *table);
255 /** Table operations. */
256 struct rte_swx_table_ops {
257 /** Table memory footprint get. Set to NULL when not supported. */
258 rte_swx_table_footprint_get_t footprint_get;
260 /** Table mailbox size get. When NULL, the mailbox size is 0. */
261 rte_swx_table_mailbox_size_get_t mailbox_size_get;
263 /** Table create. Must be non-NULL. */
264 rte_swx_table_create_t create;
266 /** Incremental table entry add. Set to NULL when not supported, in
267 * which case the existing table has to be destroyed and a new table
268 * built from scratch with the new entry included.
270 rte_swx_table_add_t add;
272 /** Incremental table entry delete. Set to NULL when not supported, in
273 * which case the existing table has to be destroyed and a new table
274 * built from scratch with the entry excluded.
276 rte_swx_table_delete_t del;
278 /** Table lookup. Must be non-NULL. */
279 rte_swx_table_lookup_t lkp;
281 /** Table free. Must be non-NULL. */
282 rte_swx_table_free_t free;