lib/table/rte_swx_table.h

   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