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