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 26 #include <rte_compat.h> 27 28 /** Learner table creation parameters. */ 29 struct rte_swx_table_learner_params { 30 /** Key size in bytes. Must be non-zero. */ 31 uint32_t key_size; 32 33 /** Offset of the first byte of the key within the key buffer. */ 34 uint32_t key_offset; 35 36 /** Mask of *key_size* bytes logically laid over the bytes at positions 37 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in order to specify 38 * which bits from the key buffer are part of the key and which ones are not. A bit value of 39 * 1 in the *key_mask0* means the respective bit in the key buffer is part of the key, while 40 * a bit value of 0 means the opposite. A NULL value means that all the bits are part of the 41 * key, i.e. the *key_mask0* is an all-ones mask. 42 */ 43 uint8_t *key_mask0; 44 45 /** Maximum size (in bytes) of the action data. The data stored in the table for each entry 46 * is equal to *action_data_size* plus 8 bytes, which are used to store the action ID. 47 */ 48 uint32_t action_data_size; 49 50 /** Maximum number of keys to be stored in the table together with their associated data. */ 51 uint32_t n_keys_max; 52 53 /** Key timeout in seconds. Must be non-zero. Each table key expires and is automatically 54 * deleted from the table after this many seconds. 55 */ 56 uint32_t key_timeout; 57 }; 58 59 /** 60 * Learner table memory footprint get 61 * 62 * @param[in] params 63 * Table create parameters. 64 * @return 65 * Table memory footprint in bytes. 66 */ 67 __rte_experimental 68 uint64_t 69 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params); 70 71 /** 72 * Learner table mailbox size get 73 * 74 * The mailbox is used to store the context of a lookup operation that is in 75 * progress and it is passed as a parameter to the lookup operation. This allows 76 * for multiple concurrent lookup operations into the same table. 77 * 78 * @return 79 * Table mailbox footprint in bytes. 80 */ 81 __rte_experimental 82 uint64_t 83 rte_swx_table_learner_mailbox_size_get(void); 84 85 /** 86 * Learner table create 87 * 88 * @param[in] params 89 * Table creation parameters. 90 * @param[in] numa_node 91 * Non-Uniform Memory Access (NUMA) node. 92 * @return 93 * Table handle, on success, or NULL, on error. 94 */ 95 __rte_experimental 96 void * 97 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node); 98 99 /** 100 * Learner table key lookup 101 * 102 * The table lookup operation searches a given key in the table and upon its completion it returns 103 * an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case 104 * of lookup hit, the action_id and the action_data associated with the key are also returned. 105 * 106 * Multiple invocations of this function may be required in order to complete a single table lookup 107 * operation for a given table and a given lookup key. The completion of the table lookup operation 108 * is flagged by a return value of 1; in case of a return value of 0, the function must be invoked 109 * again with exactly the same arguments. 110 * 111 * The mailbox argument is used to store the context of an on-going table key lookup operation, and 112 * possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent 113 * table key lookup and add operations into the same table. 114 * 115 * @param[in] table 116 * Table handle. 117 * @param[in] mailbox 118 * Mailbox for the current table lookup operation. 119 * @param[in] time 120 * Current time measured in CPU clock cycles. 121 * @param[in] key 122 * Lookup key. Its size must be equal to the table *key_size*. 123 * @param[out] action_id 124 * ID of the action associated with the *key*. Must point to a valid 64-bit variable. Only valid 125 * when the function returns 1 and *hit* is set to true. 126 * @param[out] action_data 127 * Action data for the *action_id* action. Must point to a valid array of table *action_data_size* 128 * bytes. Only valid when the function returns 1 and *hit* is set to true. 129 * @param[out] hit 130 * Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero 131 * (false) on table lookup miss. 132 * @return 133 * 0 when the table lookup operation is not yet completed, and 1 when the table lookup operation 134 * is completed. No other return values are allowed. 135 */ 136 __rte_experimental 137 int 138 rte_swx_table_learner_lookup(void *table, 139 void *mailbox, 140 uint64_t time, 141 uint8_t **key, 142 uint64_t *action_id, 143 uint8_t **action_data, 144 int *hit); 145 146 /** 147 * Learner table key add 148 * 149 * This operation takes the latest key that was looked up in the table and adds it to the table with 150 * the given action ID and action data. Typically, this operation is only invoked when the latest 151 * lookup operation in the current table resulted in lookup miss. 152 * 153 * @param[in] table 154 * Table handle. 155 * @param[in] mailbox 156 * Mailbox for the current operation. 157 * @param[in] time 158 * Current time measured in CPU clock cycles. 159 * @param[out] action_id 160 * ID of the action associated with the key. 161 * @param[out] action_data 162 * Action data for the *action_id* action. 163 * @return 164 * 0 on success, 1 or error (table full). 165 */ 166 __rte_experimental 167 uint32_t 168 rte_swx_table_learner_add(void *table, 169 void *mailbox, 170 uint64_t time, 171 uint64_t action_id, 172 uint8_t *action_data); 173 174 /** 175 * Learner table key delete 176 * 177 * This operation takes the latest key that was looked up in the table and deletes it from the 178 * table. Typically, this operation is only invoked to force the deletion of the key before the key 179 * expires on timeout due to inactivity. 180 * 181 * @param[in] table 182 * Table handle. 183 * @param[in] mailbox 184 * Mailbox for the current operation. 185 */ 186 __rte_experimental 187 void 188 rte_swx_table_learner_delete(void *table, 189 void *mailbox); 190 191 /** 192 * Learner table free 193 * 194 * @param[in] table 195 * Table handle. 196 */ 197 __rte_experimental 198 void 199 rte_swx_table_learner_free(void *table); 200 201 #ifdef __cplusplus 202 } 203 #endif 204 205 #endif 206