1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2020 Intel Corporation 3 */ 4 #ifndef __INCLUDE_RTE_SWX_TABLE_H__ 5 #define __INCLUDE_RTE_SWX_TABLE_H__ 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 /** 12 * @file 13 * RTE SWX Table 14 * 15 * Table interface. 16 */ 17 18 #include <stdint.h> 19 20 #include <rte_os.h> 21 22 /** Match type. */ 23 enum rte_swx_table_match_type { 24 /** Wildcard Match (WM). */ 25 RTE_SWX_TABLE_MATCH_WILDCARD, 26 27 /** Longest Prefix Match (LPM). */ 28 RTE_SWX_TABLE_MATCH_LPM, 29 30 /** Exact Match (EM). */ 31 RTE_SWX_TABLE_MATCH_EXACT, 32 }; 33 34 /** Table creation parameters. */ 35 struct rte_swx_table_params { 36 /** Table match type. */ 37 enum rte_swx_table_match_type match_type; 38 39 /** Key size in bytes. */ 40 uint32_t key_size; 41 42 /** Offset of the first byte of the key within the key buffer. */ 43 uint32_t key_offset; 44 45 /** Mask of *key_size* bytes logically laid over the bytes at positions 46 * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in 47 * order to specify which bits from the key buffer are part of the key 48 * and which ones are not. A bit value of 1 in the *key_mask0* means the 49 * respective bit in the key buffer is part of the key, while a bit 50 * value of 0 means the opposite. A NULL value means that all the bits 51 * are part of the key, i.e. the *key_mask0* is an all-ones mask. 52 */ 53 uint8_t *key_mask0; 54 55 /** Maximum size (in bytes) of the action data. The data stored in the 56 * table for each entry is equal to *action_data_size* plus 8 bytes, 57 * which are used to store the action ID. 58 */ 59 uint32_t action_data_size; 60 61 /** Maximum number of keys to be stored in the table together with their 62 * associated data. 63 */ 64 uint32_t n_keys_max; 65 }; 66 67 /** Table entry. */ 68 struct rte_swx_table_entry { 69 /** Used to facilitate the membership of this table entry to a 70 * linked list. 71 */ 72 RTE_TAILQ_ENTRY(rte_swx_table_entry) node; 73 74 /** Key value for the current entry. Array of *key_size* bytes or NULL 75 * if the *key_size* for the current table is 0. 76 */ 77 uint8_t *key; 78 79 /** Key mask for the current entry. Array of *key_size* bytes that is 80 * logically and'ed with *key_mask0* of the current table. A NULL value 81 * means that all the key bits already enabled by *key_mask0* are part 82 * of the key of the current entry. 83 */ 84 uint8_t *key_mask; 85 86 /** Placeholder for a possible compressed version of the *key* and 87 * *key_mask* of the current entry. Typically a hash signature, its main 88 * purpose is to the linked list search operation. Should be ignored by 89 * the API functions below. 90 */ 91 uint64_t key_signature; 92 93 /** Key priority for the current entry. Useful for wildcard match (as 94 * match rules are commonly overlapping with other rules), ignored for 95 * exact match (as match rules never overlap, hence all rules have the 96 * same match priority) and for LPM (match priority is driven by the 97 * prefix length, with non-overlapping prefixes essentially having the 98 * same match priority). Value 0 indicates the highest match priority. 99 */ 100 uint32_t key_priority; 101 102 /** Action ID for the current entry. */ 103 uint64_t action_id; 104 105 /** Action data for the current entry. Considering S as the action data 106 * size of the *action_id* action, which must be less than or equal to 107 * the table *action_data_size*, the *action_data* field must point to 108 * an array of S bytes when S is non-zero. The *action_data* field is 109 * ignored when S is zero. 110 */ 111 uint8_t *action_data; 112 }; 113 114 /** List of table entries. */ 115 RTE_TAILQ_HEAD(rte_swx_table_entry_list, rte_swx_table_entry); 116 117 /** 118 * Table memory footprint get 119 * 120 * @param[in] params 121 * Table create parameters. 122 * @param[in] entries 123 * Table entries. 124 * @param[in] args 125 * Any additional table create arguments. It may be NULL. 126 * @return 127 * Table memory footprint in bytes, if successful, or zero, on error. 128 */ 129 typedef uint64_t 130 (*rte_swx_table_footprint_get_t)(struct rte_swx_table_params *params, 131 struct rte_swx_table_entry_list *entries, 132 const char *args); 133 134 /** 135 * Table mailbox size get 136 * 137 * The mailbox is used to store the context of a lookup operation that is in 138 * progress and it is passed as a parameter to the lookup operation. This allows 139 * for multiple concurrent lookup operations into the same table. 140 * 141 * @return 142 * Table memory footprint in bytes, on success, or zero, on error. 143 */ 144 typedef uint64_t 145 (*rte_swx_table_mailbox_size_get_t)(void); 146 147 /** 148 * Table create 149 * 150 * @param[in] params 151 * Table creation parameters. 152 * @param[in] entries 153 * Entries to be added to the table at creation time. 154 * @param[in] args 155 * Any additional table create arguments. It may be NULL. 156 * @param[in] numa_node 157 * Non-Uniform Memory Access (NUMA) node. 158 * @return 159 * Table handle, on success, or NULL, on error. 160 */ 161 typedef void * 162 (*rte_swx_table_create_t)(struct rte_swx_table_params *params, 163 struct rte_swx_table_entry_list *entries, 164 const char *args, 165 int numa_node); 166 167 /** 168 * Table entry add 169 * 170 * @param[in] table 171 * Table handle. 172 * @param[in] entry 173 * Entry to be added to the table. 174 * @return 175 * 0 on success or the following error codes otherwise: 176 * -EINVAL: Invalid table handle, entry or entry field; 177 * -ENOSPC: Table full. 178 */ 179 typedef int 180 (*rte_swx_table_add_t)(void *table, 181 struct rte_swx_table_entry *entry); 182 183 /** 184 * Table entry delete 185 * 186 * @param[in] table 187 * Table handle. 188 * @param[in] entry 189 * Entry to be deleted from the table. The entry *action_id* and *action_data* 190 * fields are ignored. 191 * @return 192 * 0 on success or the following error codes otherwise: 193 * -EINVAL: Invalid table handle, entry or entry field; 194 * -ENOSPC: Table full. 195 */ 196 typedef int 197 (*rte_swx_table_delete_t)(void *table, 198 struct rte_swx_table_entry *entry); 199 200 /** 201 * Table lookup 202 * 203 * The table lookup operation searches a given key in the table and upon its 204 * completion it returns an indication of whether the key is found in the table 205 * (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and 206 * the action_data associated with the key are also returned. 207 * 208 * Multiple invocations of this function may be required in order to complete a 209 * single table lookup operation for a given table and a given lookup key. The 210 * completion of the table lookup operation is flagged by a return value of 1; 211 * in case of a return value of 0, the function must be invoked again with 212 * exactly the same arguments. 213 * 214 * The mailbox argument is used to store the context of an on-going table lookup 215 * operation. The mailbox mechanism allows for multiple concurrent table lookup 216 * operations into the same table. 217 * 218 * The typical reason an implementation may choose to split the table lookup 219 * operation into multiple steps is to hide the latency of the inherrent memory 220 * read operations: before a read operation with the source data likely not in 221 * the CPU cache, the source data prefetch is issued and the table lookup 222 * operation is postponed in favor of some other unrelated work, which the CPU 223 * executes in parallel with the source data being fetched into the CPU cache; 224 * later on, the table lookup operation is resumed, this time with the source 225 * data likely to be read from the CPU cache with no CPU pipeline stall, which 226 * significantly improves the table lookup performance. 227 * 228 * @param[in] table 229 * Table handle. 230 * @param[in] mailbox 231 * Mailbox for the current table lookup operation. 232 * @param[in] key 233 * Lookup key. Its size mult be equal to the table *key_size*. If the latter 234 * is zero, then the lookup key must be NULL. 235 * @param[out] action_id 236 * ID of the action associated with the *key*. Must point to a valid 64-bit 237 * variable. Only valid when the function returns 1 and *hit* is set to true. 238 * @param[out] action_data 239 * Action data for the *action_id* action. Must point to a valid array of 240 * table *action_data_size* bytes. Only valid when the function returns 1 and 241 * *hit* is set to true. 242 * @param[out] hit 243 * Only valid when the function returns 1. Set to non-zero (true) on table 244 * lookup hit and to zero (false) on table lookup miss. 245 * @return 246 * 0 when the table lookup operation is not yet completed, and 1 when the 247 * table lookup operation is completed. No other return values are allowed. 248 */ 249 typedef int 250 (*rte_swx_table_lookup_t)(void *table, 251 void *mailbox, 252 uint8_t **key, 253 uint64_t *action_id, 254 uint8_t **action_data, 255 int *hit); 256 257 /** 258 * Table free 259 * 260 * @param[in] table 261 * Table handle. 262 */ 263 typedef void 264 (*rte_swx_table_free_t)(void *table); 265 266 /** Table operations. */ 267 struct rte_swx_table_ops { 268 /** Table memory footprint get. Set to NULL when not supported. */ 269 rte_swx_table_footprint_get_t footprint_get; 270 271 /** Table mailbox size get. When NULL, the mailbox size is 0. */ 272 rte_swx_table_mailbox_size_get_t mailbox_size_get; 273 274 /** Table create. Must be non-NULL. */ 275 rte_swx_table_create_t create; 276 277 /** Incremental table entry add. Set to NULL when not supported, in 278 * which case the existing table has to be destroyed and a new table 279 * built from scratch with the new entry included. 280 */ 281 rte_swx_table_add_t add; 282 283 /** Incremental table entry delete. Set to NULL when not supported, in 284 * which case the existing table has to be destroyed and a new table 285 * built from scratch with the entry excluded. 286 */ 287 rte_swx_table_delete_t del; 288 289 /** Table lookup. Must be non-NULL. */ 290 rte_swx_table_lookup_t lkp; 291 292 /** Table free. Must be non-NULL. */ 293 rte_swx_table_free_t free; 294 }; 295 296 #ifdef __cplusplus 297 } 298 #endif 299 300 #endif 301