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 /** Action ID for the current entry. */ 93 uint64_t action_id; 94 95 /** Action data for the current entry. Its size is defined by the action 96 * specified by the *action_id*. It must be NULL when the action data 97 * size of the *action_id* action is NULL. It must never exceed the 98 * *action_data_size* of the table. 99 */ 100 uint8_t *action_data; 101 }; 102 103 /** List of table entries. */ 104 TAILQ_HEAD(rte_swx_table_entry_list, rte_swx_table_entry); 105 106 /** 107 * Table memory footprint get 108 * 109 * @param[in] params 110 * Table create parameters. 111 * @param[in] entries 112 * Table entries. 113 * @param[in] args 114 * Any additional table create arguments. It may be NULL. 115 * @return 116 * Table memory footprint in bytes, if successful, or zero, on error. 117 */ 118 typedef uint64_t 119 (*rte_swx_table_footprint_get_t)(struct rte_swx_table_params *params, 120 struct rte_swx_table_entry_list *entries, 121 const char *args); 122 123 /** 124 * Table mailbox size get 125 * 126 * The mailbox is used to store the context of a lookup operation that is in 127 * progress and it is passed as a parameter to the lookup operation. This allows 128 * for multiple concurrent lookup operations into the same table. 129 * 130 * @param[in] params 131 * Table creation parameters. 132 * @param[in] entries 133 * Entries to be added to the table at creation time. 134 * @param[in] args 135 * Any additional table create arguments. It may be NULL. 136 * @return 137 * Table memory footprint in bytes, on success, or zero, on error. 138 */ 139 typedef uint64_t 140 (*rte_swx_table_mailbox_size_get_t)(void); 141 142 /** 143 * Table create 144 * 145 * @param[in] params 146 * Table creation parameters. 147 * @param[in] entries 148 * Entries to be added to the table at creation time. 149 * @param[in] args 150 * Any additional table create arguments. It may be NULL. 151 * @param[in] numa_node 152 * Non-Uniform Memory Access (NUMA) node. 153 * @return 154 * Table handle, on success, or NULL, on error. 155 */ 156 typedef void * 157 (*rte_swx_table_create_t)(struct rte_swx_table_params *params, 158 struct rte_swx_table_entry_list *entries, 159 const char *args, 160 int numa_node); 161 162 /** 163 * Table entry add 164 * 165 * @param[in] table 166 * Table handle. 167 * @param[in] entry 168 * Entry to be added to the table. 169 * @return 170 * 0 on success or the following error codes otherwise: 171 * -EINVAL: Invalid table handle, entry or entry field; 172 * -ENOSPC: Table full. 173 */ 174 typedef int 175 (*rte_swx_table_add_t)(void *table, 176 struct rte_swx_table_entry *entry); 177 178 /** 179 * Table entry delete 180 * 181 * @param[in] table 182 * Table handle. 183 * @param[in] entry 184 * Entry to be deleted from the table. The entry *action_id* and *action_data* 185 * fields are ignored. 186 * @return 187 * 0 on success or the following error codes otherwise: 188 * -EINVAL: Invalid table handle, entry or entry field; 189 * -ENOSPC: Table full. 190 */ 191 typedef int 192 (*rte_swx_table_delete_t)(void *table, 193 struct rte_swx_table_entry *entry); 194 195 /** 196 * Table lookup 197 * 198 * The table lookup operation searches a given key in the table and upon its 199 * completion it returns an indication of whether the key is found in the table 200 * (lookup hit) or not (lookup miss). In case of lookup hit, the action_id and 201 * the action_data associated with the key are also returned. 202 * 203 * Multiple invocations of this function may be required in order to complete a 204 * single table lookup operation for a given table and a given lookup key. The 205 * completion of the table lookup operation is flagged by a return value of 1; 206 * in case of a return value of 0, the function must be invoked again with 207 * exactly the same arguments. 208 * 209 * The mailbox argument is used to store the context of an on-going table lookup 210 * operation. The mailbox mechanism allows for multiple concurrent table lookup 211 * operations into the same table. 212 * 213 * The typical reason an implementation may choose to split the table lookup 214 * operation into multiple steps is to hide the latency of the inherrent memory 215 * read operations: before a read operation with the source data likely not in 216 * the CPU cache, the source data prefetch is issued and the table lookup 217 * operation is postponed in favor of some other unrelated work, which the CPU 218 * executes in parallel with the source data being fetched into the CPU cache; 219 * later on, the table lookup operation is resumed, this time with the source 220 * data likely to be read from the CPU cache with no CPU pipeline stall, which 221 * significantly improves the table lookup performance. 222 * 223 * @param[in] table 224 * Table handle. 225 * @param[in] mailbox 226 * Mailbox for the current table lookup operation. 227 * @param[in] key 228 * Lookup key. Its size mult be equal to the table *key_size*. If the latter 229 * is zero, then the lookup key must be NULL. 230 * @param[out] action_id 231 * ID of the action associated with the *key*. Must point to a valid 64-bit 232 * variable. Only valid when the function returns 1 and *hit* is set to true. 233 * @param[out] action_data 234 * Action data for the *action_id* action. Must point to a valid array of 235 * table *action_data_size* bytes. Only valid when the function returns 1 and 236 * *hit* is set to true. 237 * @param[out] hit 238 * Only valid when the function returns 1. Set to non-zero (true) on table 239 * lookup hit and to zero (false) on table lookup miss. 240 * @return 241 * 0 when the table lookup operation is not yet completed, and 1 when the 242 * table lookup operation is completed. No other return values are allowed. 243 */ 244 typedef int 245 (*rte_swx_table_lookup_t)(void *table, 246 void *mailbox, 247 uint8_t **key, 248 uint64_t *action_id, 249 uint8_t **action_data, 250 int *hit); 251 252 /** 253 * Table free 254 * 255 * @param[in] table 256 * Table handle. 257 */ 258 typedef void 259 (*rte_swx_table_free_t)(void *table); 260 261 /** Table operations. */ 262 struct rte_swx_table_ops { 263 /** Table memory footprint get. Set to NULL when not supported. */ 264 rte_swx_table_footprint_get_t footprint_get; 265 266 /** Table mailbox size get. When NULL, the mailbox size is 0. */ 267 rte_swx_table_mailbox_size_get_t mailbox_size_get; 268 269 /** Table create. Must be non-NULL. */ 270 rte_swx_table_create_t create; 271 272 /** Incremental table entry add. Set to NULL when not supported, in 273 * which case the existing table has to be destroyed and a new table 274 * built from scratch with the new entry included. 275 */ 276 rte_swx_table_add_t add; 277 278 /** Incremental table entry delete. Set to NULL when not supported, in 279 * which case the existing table has to be destroyed and a new table 280 * built from scratch with the entry excluded. 281 */ 282 rte_swx_table_delete_t del; 283 284 /** Table lookup. Must be non-NULL. */ 285 rte_swx_table_lookup_t lkp; 286 287 /** Table free. Must be non-NULL. */ 288 rte_swx_table_free_t free; 289 }; 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif 296