lib/librte_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 #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