1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2021 Intel Corporation 3 */ 4 #ifndef __INCLUDE_RTE_SWX_TABLE_LEARNER_H__ 5 #define __INCLUDE_RTE_SWX_TABLE_LEARNER_H__ 6 7 /** 8 * @file 9 * RTE SWX Learner Table 10 * 11 * The learner table API. 12 * 13 * This table type is typically used for learning or connection tracking, where it allows for the 14 * implementation of the "add on miss" scenario: whenever the lookup key is not found in the table 15 * (lookup miss), the data plane can decide to add this key to the table with a given action with no 16 * control plane intervention. Likewise, the table keys expire based on a configurable timeout and 17 * are thus automatically removed from the table with no control plane intervention. 18 * 19 * The keys are not automatically rearmed on lookup hit. To delay the key expiration, the key timer 20 * has to be explicitly reinitialized on lookup hit. The key will be kept in the table as long as it 21 * is frequently hit and explicitly rearmed on every hit. 22 * 23 * Operation overview: 24 * 1) Lookup miss: 25 * a) add: Add the current input key (the key that missed the lookup) to the table with given 26 * action, action parameters and expiration timeout. This is the way to populate the 27 * table (which is empty initially). Data plane operation. 28 * b) Do nothing: Keep the current input key out of the table. 29 * 2) Lookup hit: 30 * a) add: Update the action, action parameters and/or the expiration timeout for the current 31 * input key, which is already in the table. The expiration timer of the key is 32 * automatically rearmed. Data plane operation. 33 * b) rearm: Rearm the expiration timer for the current input key, which is already in the 34 * table. The timeout value used for the expiration timer is either the same as the one 35 * currently associated with the key or a new one can be provided as input. Data plane 36 * operation. 37 * c) delete: Delete the current input key from the table. The purpose of this operation is to 38 * force the deletion of the key from the table before the key expires on timeout due 39 * to inactivity. Data plane operation. 40 * d) Do nothing: Keep the expiration timer of the current input key running down. This key 41 * will thus expire naturally, unless it is hit again as part of a subsequent lookup 42 * operation, when the key timer can be rearmed or re-added to prolong its life. 43 */ 44 45 #include <stdint.h> 46 #include <sys/types.h> 47 48 #include <rte_compat.h> 49 50 #include "rte_swx_hash_func.h" 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /** Maximum number of key timeout values per learner table. */ 57 #ifndef RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX 58 #define RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX 16 59 #endif 60 61 /** Learner table creation parameters. */ 62 struct rte_swx_table_learner_params { 63 /** Key size in bytes. Must be non-zero. */ 64 uint32_t key_size; 65 66 /** Offset of the first byte of the key within the key buffer. */ 67 uint32_t key_offset; 68 69 /** Mask of *key_size* bytes logically laid over the bytes at positions 70 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in order to specify 71 * which bits from the key buffer are part of the key and which ones are not. A bit value of 72 * 1 in the *key_mask0* means the respective bit in the key buffer is part of the key, while 73 * a bit value of 0 means the opposite. A NULL value means that all the bits are part of the 74 * key, i.e. the *key_mask0* is an all-ones mask. 75 */ 76 uint8_t *key_mask0; 77 78 /** Maximum size (in bytes) of the action data. The data stored in the table for each entry 79 * is equal to *action_data_size* plus 8 bytes, which are used to store the action ID. 80 */ 81 uint32_t action_data_size; 82 83 /** Hash function. When NULL, the default hash function will be used. 84 */ 85 rte_swx_hash_func_t hash_func; 86 87 /** Maximum number of keys to be stored in the table together with their associated data. */ 88 uint32_t n_keys_max; 89 90 /** The set of all possible key timeout values measured in seconds. Each value must be 91 * non-zero. Each table key expires and is automatically deleted from the table after 92 * this many seconds. 93 */ 94 uint32_t *key_timeout; 95 96 /** Number of possible key timeout values present in the *key_timeout* set. It must be less 97 * than or equal to *RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX*. 98 */ 99 uint32_t n_key_timeouts; 100 }; 101 102 /** 103 * Learner table memory footprint get 104 * 105 * @param[in] params 106 * Table create parameters. 107 * @return 108 * Table memory footprint in bytes. 109 */ 110 __rte_experimental 111 uint64_t 112 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params); 113 114 /** 115 * Learner table mailbox size get 116 * 117 * The mailbox is used to store the context of a lookup operation that is in 118 * progress and it is passed as a parameter to the lookup operation. This allows 119 * for multiple concurrent lookup operations into the same table. 120 * 121 * @return 122 * Table mailbox footprint in bytes. 123 */ 124 __rte_experimental 125 uint64_t 126 rte_swx_table_learner_mailbox_size_get(void); 127 128 /** 129 * Learner table create 130 * 131 * @param[in] params 132 * Table creation parameters. 133 * @param[in] numa_node 134 * Non-Uniform Memory Access (NUMA) node. 135 * @return 136 * Table handle, on success, or NULL, on error. 137 */ 138 __rte_experimental 139 void * 140 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node); 141 142 /** 143 * Learner table key timeout update 144 * 145 * @param[in] table 146 * Table handle. 147 * @param[in] key_timeout_id 148 * Key timeout ID. Must be less than the configured *n_key_timeouts* value. 149 * @param[in] key_timeout 150 * Key timeout value measured in seconds. 151 * @return 152 * 0 on success or the following error codes otherwise: 153 * -EINVAL: Invalid argument(s). 154 */ 155 __rte_experimental 156 int 157 rte_swx_table_learner_timeout_update(void *table, 158 uint32_t key_timeout_id, 159 uint32_t key_timeout); 160 161 /** 162 * Learner table key lookup 163 * 164 * The table lookup operation searches a given key in the table and upon its completion it returns 165 * an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case 166 * of lookup hit, the action_id and the action_data associated with the key are also returned. 167 * 168 * Multiple invocations of this function may be required in order to complete a single table lookup 169 * operation for a given table and a given lookup key. The completion of the table lookup operation 170 * is flagged by a return value of 1; in case of a return value of 0, the function must be invoked 171 * again with exactly the same arguments. 172 * 173 * The mailbox argument is used to store the context of an on-going table key lookup operation, and 174 * possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent 175 * table key lookup and add operations into the same table. 176 * 177 * The table entry consists of the action ID and the action data. Each table entry is unique, even 178 * though different table entries can have identical content, i.e. same values for the action ID and 179 * the action data. The table entry ID is also returned by the table lookup operation. It can be 180 * used to index into an external array of resources such as counters, registers or meters to 181 * identify the resource directly associated with the current table entry with no need to store the 182 * corresponding index into the table entry. The index of the external resource is thus 183 * auto-generated instead of being stored in the table entry. 184 * 185 * @param[in] table 186 * Table handle. 187 * @param[in] mailbox 188 * Mailbox for the current table lookup operation. 189 * @param[in] time 190 * Current time measured in CPU clock cycles. 191 * @param[in] key 192 * Lookup key. Its size must be equal to the table *key_size*. 193 * @param[out] action_id 194 * ID of the action associated with the *key*. Must point to a valid 64-bit variable. Only valid 195 * when the function returns 1 and *hit* is set to true. 196 * @param[out] action_data 197 * Action data for the *action_id* action. Must point to a valid array of table *action_data_size* 198 * bytes. Only valid when the function returns 1 and *hit* is set to true. 199 * @param[out] entry_id 200 * Table entry unique ID. Must point to a valid 32-bit variable. Only valid when the function 201 * returns 1 and *hit* is set to true. 202 * @param[out] hit 203 * Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero 204 * (false) on table lookup miss. 205 * @return 206 * 0 when the table lookup operation is not yet completed, and 1 when the table lookup operation 207 * is completed. No other return values are allowed. 208 */ 209 __rte_experimental 210 int 211 rte_swx_table_learner_lookup(void *table, 212 void *mailbox, 213 uint64_t time, 214 uint8_t **key, 215 uint64_t *action_id, 216 uint8_t **action_data, 217 size_t *entry_id, 218 int *hit); 219 220 /** 221 * Learner table key add 222 * 223 * This operation takes the latest key that was looked up in the table and adds it to the table with 224 * the given action ID and action data. Typically, this operation is only invoked when the latest 225 * lookup operation in the current table resulted in lookup miss. 226 * 227 * @param[in] table 228 * Table handle. 229 * @param[in] mailbox 230 * Mailbox for the current operation. 231 * @param[in] time 232 * Current time measured in CPU clock cycles. 233 * @param[out] action_id 234 * ID of the action associated with the key. 235 * @param[out] action_data 236 * Action data for the *action_id* action. 237 * @param[in] key_timeout_id 238 * Key timeout ID. 239 * @return 240 * 0 on success, 1 or error (table full). 241 */ 242 __rte_experimental 243 uint32_t 244 rte_swx_table_learner_add(void *table, 245 void *mailbox, 246 uint64_t time, 247 uint64_t action_id, 248 uint8_t *action_data, 249 uint32_t key_timeout_id); 250 251 /** 252 * Learner table key rearm with same timeout value 253 * 254 * This operation takes the latest key that was looked up in the table and, in case of lookup hit, 255 * it rearms its expiration timer using the same timeout value currently associated with the key. 256 * 257 * @param[in] table 258 * Table handle. 259 * @param[in] mailbox 260 * Mailbox for the current operation. 261 * @param[in] time 262 * Current time measured in CPU clock cycles. 263 */ 264 __rte_experimental 265 void 266 rte_swx_table_learner_rearm(void *table, 267 void *mailbox, 268 uint64_t time); 269 270 /** 271 * Learner table key rearm with given timeout value 272 * 273 * This operation takes the latest key that was looked up in the table and, in case of lookup hit, 274 * it rearms its expiration timer using the given timeout value. 275 * 276 * @param[in] table 277 * Table handle. 278 * @param[in] mailbox 279 * Mailbox for the current operation. 280 * @param[in] time 281 * Current time measured in CPU clock cycles. 282 * @param[in] key_timeout_id 283 * Key timeout ID. 284 */ 285 __rte_experimental 286 void 287 rte_swx_table_learner_rearm_new(void *table, 288 void *mailbox, 289 uint64_t time, 290 uint32_t key_timeout_id); 291 292 /** 293 * Learner table key delete 294 * 295 * This operation takes the latest key that was looked up in the table and deletes it from the 296 * table. Typically, this operation is only invoked to force the deletion of the key before the key 297 * expires on timeout due to inactivity. 298 * 299 * @param[in] table 300 * Table handle. 301 * @param[in] mailbox 302 * Mailbox for the current operation. 303 */ 304 __rte_experimental 305 void 306 rte_swx_table_learner_delete(void *table, 307 void *mailbox); 308 309 /** 310 * Learner table free 311 * 312 * @param[in] table 313 * Table handle. 314 */ 315 __rte_experimental 316 void 317 rte_swx_table_learner_free(void *table); 318 319 #ifdef __cplusplus 320 } 321 #endif 322 323 #endif 324