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