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__
23 enum rte_swx_table_match_type {
24 /** Wildcard Match (WM). */
25 RTE_SWX_TABLE_MATCH_WILDCARD,
27 /** Longest Prefix Match (LPM). */
28 RTE_SWX_TABLE_MATCH_LPM,
30 /** Exact Match (EM). */
31 RTE_SWX_TABLE_MATCH_EXACT,
34 /** Table creation parameters. */
35 struct rte_swx_table_params {
36 /** Table match type. */
37 enum rte_swx_table_match_type match_type;
39 /** Key size in bytes. */
42 /** Offset of the first byte of the key within the key buffer. */
45 /** Mask of *key_size* bytes logically laid over the bytes at positions
46 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in
47 * order to specify which bits from the key buffer are part of the key
48 * and which ones are not. A bit value of 1 in the *key_mask0* means the
49 * respective bit in the key buffer is part of the key, while a bit
50 * value of 0 means the opposite. A NULL value means that all the bits
51 * are part of the key, i.e. the *key_mask0* is an all-ones mask.
55 /** Maximum size (in bytes) of the action data. The data stored in the
56 * table for each entry is equal to *action_data_size* plus 8 bytes,
57 * which are used to store the action ID.
59 uint32_t action_data_size;
61 /** Maximum number of keys to be stored in the table together with their
68 struct rte_swx_table_entry {
69 /** Used to facilitate the membership of this table entry to a
72 RTE_TAILQ_ENTRY(rte_swx_table_entry) node;
74 /** Key value for the current entry. Array of *key_size* bytes or NULL
75 * if the *key_size* for the current table is 0.
79 /** Key mask for the current entry. Array of *key_size* bytes that is
80 * logically and'ed with *key_mask0* of the current table. A NULL value
81 * means that all the key bits already enabled by *key_mask0* are part
82 * of the key of the current entry.
86 /** Placeholder for a possible compressed version of the *key* and
87 * *key_mask* of the current entry. Typically a hash signature, its main
88 * purpose is to the linked list search operation. Should be ignored by
89 * the API functions below.
91 uint64_t key_signature;
93 /** Key priority for the current entry. Useful for wildcard match (as
94 * match rules are commonly overlapping with other rules), ignored for
95 * exact match (as match rules never overlap, hence all rules have the
96 * same match priority) and for LPM (match priority is driven by the
97 * prefix length, with non-overlapping prefixes essentially having the
98 * same match priority). Value 0 indicates the highest match priority.
100 uint32_t key_priority;
102 /** Action ID for the current entry. */
105 /** Action data for the current entry. Considering S as the action data
106 * size of the *action_id* action, which must be less than or equal to
107 * the table *action_data_size*, the *action_data* field must point to
108 * an array of S bytes when S is non-zero. The *action_data* field is
109 * ignored when S is zero.
111 uint8_t *action_data;
114 /** List of table entries. */
115 RTE_TAILQ_HEAD(rte_swx_table_entry_list, rte_swx_table_entry);
118 * Table memory footprint get
121 * Table create parameters.
125 * Any additional table create arguments. It may be NULL.
127 * Table memory footprint in bytes, if successful, or zero, on error.
130 (*rte_swx_table_footprint_get_t)(struct rte_swx_table_params *params,
131 struct rte_swx_table_entry_list *entries,
135 * Table mailbox size get
137 * The mailbox is used to store the context of a lookup operation that is in
138 * progress and it is passed as a parameter to the lookup operation. This allows
139 * for multiple concurrent lookup operations into the same table.
142 * Table memory footprint in bytes, on success, or zero, on error.
145 (*rte_swx_table_mailbox_size_get_t)(void);
151 * Table creation parameters.
153 * Entries to be added to the table at creation time.
155 * Any additional table create arguments. It may be NULL.
156 * @param[in] numa_node
157 * Non-Uniform Memory Access (NUMA) node.
159 * Table handle, on success, or NULL, on error.
162 (*rte_swx_table_create_t)(struct rte_swx_table_params *params,
163 struct rte_swx_table_entry_list *entries,
173 * Entry to be added to the table.
175 * 0 on success or the following error codes otherwise:
176 * -EINVAL: Invalid table handle, entry or entry field;
177 * -ENOSPC: Table full.
180 (*rte_swx_table_add_t)(void *table,
181 struct rte_swx_table_entry *entry);
189 * Entry to be deleted from the table. The entry *action_id* and *action_data*
190 * fields are ignored.
192 * 0 on success or the following error codes otherwise:
193 * -EINVAL: Invalid table handle, entry or entry field;
194 * -ENOSPC: Table full.
197 (*rte_swx_table_delete_t)(void *table,
198 struct rte_swx_table_entry *entry);
203 * The table lookup operation searches a given key in the table and upon its
204 * completion it returns an indication of whether the key is found in the table
205 * (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and
206 * the action_data associated with the key are also returned.
208 * Multiple invocations of this function may be required in order to complete a
209 * single table lookup operation for a given table and a given lookup key. The
210 * completion of the table lookup operation is flagged by a return value of 1;
211 * in case of a return value of 0, the function must be invoked again with
212 * exactly the same arguments.
214 * The mailbox argument is used to store the context of an on-going table lookup
215 * operation. The mailbox mechanism allows for multiple concurrent table lookup
216 * operations into the same table.
218 * The typical reason an implementation may choose to split the table lookup
219 * operation into multiple steps is to hide the latency of the inherrent memory
220 * read operations: before a read operation with the source data likely not in
221 * the CPU cache, the source data prefetch is issued and the table lookup
222 * operation is postponed in favor of some other unrelated work, which the CPU
223 * executes in parallel with the source data being fetched into the CPU cache;
224 * later on, the table lookup operation is resumed, this time with the source
225 * data likely to be read from the CPU cache with no CPU pipeline stall, which
226 * significantly improves the table lookup performance.
231 * Mailbox for the current table lookup operation.
233 * Lookup key. Its size mult be equal to the table *key_size*. If the latter
234 * is zero, then the lookup key must be NULL.
235 * @param[out] action_id
236 * ID of the action associated with the *key*. Must point to a valid 64-bit
237 * variable. Only valid when the function returns 1 and *hit* is set to true.
238 * @param[out] action_data
239 * Action data for the *action_id* action. Must point to a valid array of
240 * table *action_data_size* bytes. Only valid when the function returns 1 and
241 * *hit* is set to true.
243 * Only valid when the function returns 1. Set to non-zero (true) on table
244 * lookup hit and to zero (false) on table lookup miss.
246 * 0 when the table lookup operation is not yet completed, and 1 when the
247 * table lookup operation is completed. No other return values are allowed.
250 (*rte_swx_table_lookup_t)(void *table,
254 uint8_t **action_data,
264 (*rte_swx_table_free_t)(void *table);
266 /** Table operations. */
267 struct rte_swx_table_ops {
268 /** Table memory footprint get. Set to NULL when not supported. */
269 rte_swx_table_footprint_get_t footprint_get;
271 /** Table mailbox size get. When NULL, the mailbox size is 0. */
272 rte_swx_table_mailbox_size_get_t mailbox_size_get;
274 /** Table create. Must be non-NULL. */
275 rte_swx_table_create_t create;
277 /** Incremental table entry add. Set to NULL when not supported, in
278 * which case the existing table has to be destroyed and a new table
279 * built from scratch with the new entry included.
281 rte_swx_table_add_t add;
283 /** Incremental table entry delete. Set to NULL when not supported, in
284 * which case the existing table has to be destroyed and a new table
285 * built from scratch with the entry excluded.
287 rte_swx_table_delete_t del;
289 /** Table lookup. Must be non-NULL. */
290 rte_swx_table_lookup_t lkp;
292 /** Table free. Must be non-NULL. */
293 rte_swx_table_free_t free;