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 automatically deleted from the table with no control plane intervention. 22 */ 23 24 #include <stdint.h> 25 #include <sys/queue.h> 26 27 #include <rte_compat.h> 28 29 /** Learner table creation parameters. */ 30 struct rte_swx_table_learner_params { 31 /** Key size in bytes. Must be non-zero. */ 32 uint32_t key_size; 33 34 /** Offset of the first byte of the key within the key buffer. */ 35 uint32_t key_offset; 36 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. 43 */ 44 uint8_t *key_mask0; 45 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. 48 */ 49 uint32_t action_data_size; 50 51 /** Maximum number of keys to be stored in the table together with their associated data. */ 52 uint32_t n_keys_max; 53 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. 56 */ 57 uint32_t key_timeout; 58 }; 59 60 /** 61 * Learner table memory footprint get 62 * 63 * @param[in] params 64 * Table create parameters. 65 * @return 66 * Table memory footprint in bytes. 67 */ 68 __rte_experimental 69 uint64_t 70 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params); 71 72 /** 73 * Learner table mailbox size get 74 * 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. 78 * 79 * @return 80 * Table mailbox footprint in bytes. 81 */ 82 __rte_experimental 83 uint64_t 84 rte_swx_table_learner_mailbox_size_get(void); 85 86 /** 87 * Learner table create 88 * 89 * @param[in] params 90 * Table creation parameters. 91 * @param[in] numa_node 92 * Non-Uniform Memory Access (NUMA) node. 93 * @return 94 * Table handle, on success, or NULL, on error. 95 */ 96 __rte_experimental 97 void * 98 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node); 99 100 /** 101 * Learner table key lookup 102 * 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. 106 * 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. 111 * 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. 115 * 116 * @param[in] table 117 * Table handle. 118 * @param[in] mailbox 119 * Mailbox for the current table lookup operation. 120 * @param[in] time 121 * Current time measured in CPU clock cycles. 122 * @param[in] key 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. 130 * @param[out] hit 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. 133 * @return 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. 136 */ 137 __rte_experimental 138 int 139 rte_swx_table_learner_lookup(void *table, 140 void *mailbox, 141 uint64_t time, 142 uint8_t **key, 143 uint64_t *action_id, 144 uint8_t **action_data, 145 int *hit); 146 147 /** 148 * Learner table key add 149 * 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. 153 * 154 * @param[in] table 155 * Table handle. 156 * @param[in] mailbox 157 * Mailbox for the current operation. 158 * @param[in] time 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. 164 * @return 165 * 0 on success, 1 or error (table full). 166 */ 167 __rte_experimental 168 uint32_t 169 rte_swx_table_learner_add(void *table, 170 void *mailbox, 171 uint64_t time, 172 uint64_t action_id, 173 uint8_t *action_data); 174 175 /** 176 * Learner table key delete 177 * 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. 181 * 182 * @param[in] table 183 * Table handle. 184 * @param[in] mailbox 185 * Mailbox for the current operation. 186 */ 187 __rte_experimental 188 void 189 rte_swx_table_learner_delete(void *table, 190 void *mailbox); 191 192 /** 193 * Learner table free 194 * 195 * @param[in] table 196 * Table handle. 197 */ 198 __rte_experimental 199 void 200 rte_swx_table_learner_free(void *table); 201 202 #ifdef __cplusplus 203 } 204 #endif 205 206 #endif 207