1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2021 Intel Corporation
4 #ifndef __INCLUDE_RTE_SWX_TABLE_LEARNER_H__
5 #define __INCLUDE_RTE_SWX_TABLE_LEARNER_H__
13 * RTE SWX Learner Table
15 * The learner table API.
17 * This table type is typically used for learning or connection tracking, where it allows for the
18 * implementation of the "add on miss" scenario: whenever the lookup key is not found in the table
19 * (lookup miss), the data plane can decide to add this key to the table with a given action with no
20 * control plane intervention. Likewise, the table keys expire based on a configurable timeout and
21 * are automatically deleted from the table with no control plane intervention.
25 #include <sys/queue.h>
27 #include <rte_compat.h>
29 /** Learner table creation parameters. */
30 struct rte_swx_table_learner_params {
31 /** Key size in bytes. Must be non-zero. */
34 /** Offset of the first byte of the key within the key buffer. */
37 /** Mask of *key_size* bytes logically laid over the bytes at positions
38 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in order to specify
39 * which bits from the key buffer are part of the key and which ones are not. A bit value of
40 * 1 in the *key_mask0* means the respective bit in the key buffer is part of the key, while
41 * a bit value of 0 means the opposite. A NULL value means that all the bits are part of the
42 * key, i.e. the *key_mask0* is an all-ones mask.
46 /** Maximum size (in bytes) of the action data. The data stored in the table for each entry
47 * is equal to *action_data_size* plus 8 bytes, which are used to store the action ID.
49 uint32_t action_data_size;
51 /** Maximum number of keys to be stored in the table together with their associated data. */
54 /** Key timeout in seconds. Must be non-zero. Each table key expires and is automatically
55 * deleted from the table after this many seconds.
61 * Learner table memory footprint get
64 * Table create parameters.
66 * Table memory footprint in bytes.
70 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params);
73 * Learner table mailbox size get
75 * The mailbox is used to store the context of a lookup operation that is in
76 * progress and it is passed as a parameter to the lookup operation. This allows
77 * for multiple concurrent lookup operations into the same table.
80 * Table mailbox footprint in bytes.
84 rte_swx_table_learner_mailbox_size_get(void);
87 * Learner table create
90 * Table creation parameters.
91 * @param[in] numa_node
92 * Non-Uniform Memory Access (NUMA) node.
94 * Table handle, on success, or NULL, on error.
98 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node);
101 * Learner table key lookup
103 * The table lookup operation searches a given key in the table and upon its completion it returns
104 * an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case
105 * of lookup hit, the action_id and the action_data associated with the key are also returned.
107 * Multiple invocations of this function may be required in order to complete a single table lookup
108 * operation for a given table and a given lookup key. The completion of the table lookup operation
109 * is flagged by a return value of 1; in case of a return value of 0, the function must be invoked
110 * again with exactly the same arguments.
112 * The mailbox argument is used to store the context of an on-going table key lookup operation, and
113 * possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent
114 * table key lookup and add operations into the same table.
119 * Mailbox for the current table lookup operation.
121 * Current time measured in CPU clock cycles.
123 * Lookup key. Its size must be equal to the table *key_size*.
124 * @param[out] action_id
125 * ID of the action associated with the *key*. Must point to a valid 64-bit variable. Only valid
126 * when the function returns 1 and *hit* is set to true.
127 * @param[out] action_data
128 * Action data for the *action_id* action. Must point to a valid array of table *action_data_size*
129 * bytes. Only valid when the function returns 1 and *hit* is set to true.
131 * Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero
132 * (false) on table lookup miss.
134 * 0 when the table lookup operation is not yet completed, and 1 when the table lookup operation
135 * is completed. No other return values are allowed.
139 rte_swx_table_learner_lookup(void *table,
144 uint8_t **action_data,
148 * Learner table key add
150 * This operation takes the latest key that was looked up in the table and adds it to the table with
151 * the given action ID and action data. Typically, this operation is only invoked when the latest
152 * lookup operation in the current table resulted in lookup miss.
157 * Mailbox for the current operation.
159 * Current time measured in CPU clock cycles.
160 * @param[out] action_id
161 * ID of the action associated with the key.
162 * @param[out] action_data
163 * Action data for the *action_id* action.
165 * 0 on success, 1 or error (table full).
169 rte_swx_table_learner_add(void *table,
173 uint8_t *action_data);
176 * Learner table key delete
178 * This operation takes the latest key that was looked up in the table and deletes it from the
179 * table. Typically, this operation is only invoked to force the deletion of the key before the key
180 * expires on timeout due to inactivity.
185 * Mailbox for the current operation.
189 rte_swx_table_learner_delete(void *table,
200 rte_swx_table_learner_free(void *table);