lib/table/rte_swx_table_learner.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2021 Intel Corporation
   3  */
   4 #ifndef __INCLUDE_RTE_SWX_TABLE_LEARNER_H__
   5 #define __INCLUDE_RTE_SWX_TABLE_LEARNER_H__
   6
   7 #ifdef __cplusplus
   8 extern "C" {
   9 #endif
  10
  11 /**
  12  * @file
  13  * RTE SWX Learner Table
  14  *
  15  * The learner table API.
  16  *
  17  * This table type is typically used for learning or connection tracking, where it allows for the
  18  * implementation of the "add on miss" scenario: whenever the lookup key is not found in the table
  19  * (lookup miss), the data plane can decide to add this key to the table with a given action with no
  20  * control plane intervention. Likewise, the table keys expire based on a configurable timeout and
  21  * are thus automatically removed from the table with no control plane intervention.
  22  *
  23  * The keys are not automatically rearmed on lookup hit. To delay the key expiration, the key timer
  24  * has to be explicitly reinitialized on lookup hit. The key will be kept in the table as long as it
  25  * is frequently hit and explicitly rearmed on every hit.
  26  *
  27  * Operation overview:
  28  * 1) Lookup miss:
  29  *      a) add: Add the current input key (the key that missed the lookup) to the table with given
  30  *              action, action parameters and expiration timeout. This is the way to populate the
  31  *              table (which is empty initially). Data plane operation.
  32  *      b) Do nothing: Keep the current input key out of the table.
  33  * 2) Lookup hit:
  34  *      a) add: Update the action, action parameters and/or the expiration timeout for the current
  35  *              input key, which is already in the table. The expiration timer of the key is
  36  *              automatically rearmed. Data plane operation.
  37  *      b) rearm: Rearm the expiration timer for the current input key, which is already in the
  38  *              table. The timeout value used for the expiration timer is either the same as the one
  39  *              currently associated with the key or a new one can be provided as input. Data plane
  40  *              operation.
  41  *      c) delete: Delete the current input key from the table. The purpose of this operation is to
  42  *              force the deletion of the key from the table before the key expires on timeout due
  43  *              to inactivity. Data plane operation.
  44  *      d) Do nothing: Keep the expiration timer of the current input key running down. This key
  45  *              will thus expire naturally, unless it is hit again as part of a subsequent lookup
  46  *              operation, when the key timer can be rearmed or re-added to prolong its life.
  47  */
  48
  49 #include <stdint.h>
  50
  51 #include <rte_compat.h>
  52
  53 /** Maximum number of key timeout values per learner table. */
  54 #ifndef RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX
  55 #define RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX 16
  56 #endif
  57
  58 /** Learner table creation parameters. */
  59 struct rte_swx_table_learner_params {
  60         /** Key size in bytes. Must be non-zero. */
  61         uint32_t key_size;
  62
  63         /** Offset of the first byte of the key within the key buffer. */
  64         uint32_t key_offset;
  65
  66         /** Mask of *key_size* bytes logically laid over the bytes at positions
  67          * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in order to specify
  68          * which bits from the key buffer are part of the key and which ones are not. A bit value of
  69          * 1 in the *key_mask0* means the respective bit in the key buffer is part of the key, while
  70          * a bit value of 0 means the opposite. A NULL value means that all the bits are part of the
  71          * key, i.e. the *key_mask0* is an all-ones mask.
  72          */
  73         uint8_t *key_mask0;
  74
  75         /** Maximum size (in bytes) of the action data. The data stored in the table for each entry
  76          * is equal to *action_data_size* plus 8 bytes, which are used to store the action ID.
  77          */
  78         uint32_t action_data_size;
  79
  80         /** Maximum number of keys to be stored in the table together with their associated data. */
  81         uint32_t n_keys_max;
  82
  83         /** The set of all possible key timeout values measured in seconds. Each value must be
  84          * non-zero. Each table key expires and is automatically deleted from the table after
  85          * this many seconds.
  86          */
  87         uint32_t *key_timeout;
  88
  89         /** Number of possible key timeout values present in the *key_timeout* set. It must be less
  90          * than or equal to *RTE_SWX_TABLE_LEARNER_N_KEY_TIMEOUTS_MAX*.
  91          */
  92         uint32_t n_key_timeouts;
  93 };
  94
  95 /**
  96  * Learner table memory footprint get
  97  *
  98  * @param[in] params
  99  *   Table create parameters.
 100  * @return
 101  *   Table memory footprint in bytes.
 102  */
 103 __rte_experimental
 104 uint64_t
 105 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params);
 106
 107 /**
 108  * Learner table mailbox size get
 109  *
 110  * The mailbox is used to store the context of a lookup operation that is in
 111  * progress and it is passed as a parameter to the lookup operation. This allows
 112  * for multiple concurrent lookup operations into the same table.
 113  *
 114  * @return
 115  *   Table mailbox footprint in bytes.
 116  */
 117 __rte_experimental
 118 uint64_t
 119 rte_swx_table_learner_mailbox_size_get(void);
 120
 121 /**
 122  * Learner table create
 123  *
 124  * @param[in] params
 125  *   Table creation parameters.
 126  * @param[in] numa_node
 127  *   Non-Uniform Memory Access (NUMA) node.
 128  * @return
 129  *   Table handle, on success, or NULL, on error.
 130  */
 131 __rte_experimental
 132 void *
 133 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node);
 134
 135 /**
 136  * Learner table key timeout update
 137  *
 138  * @param[in] table
 139  *   Table handle.
 140  * @param[in] key_timeout_id
 141  *   Key timeout ID. Must be less than the configured *n_key_timeouts* value.
 142  * @param[in] key_timeout
 143  *   Key timeout value measured in seconds.
 144  * @return
 145  *   0 on success or the following error codes otherwise:
 146  *   -EINVAL: Invalid argument(s).
 147  */
 148 __rte_experimental
 149 int
 150 rte_swx_table_learner_timeout_update(void *table,
 151                                      uint32_t key_timeout_id,
 152                                      uint32_t key_timeout);
 153
 154 /**
 155  * Learner table key lookup
 156  *
 157  * The table lookup operation searches a given key in the table and upon its completion it returns
 158  * an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case
 159  * of lookup hit, the action_id and the action_data associated with the key are also returned.
 160  *
 161  * Multiple invocations of this function may be required in order to complete a single table lookup
 162  * operation for a given table and a given lookup key. The completion of the table lookup operation
 163  * is flagged by a return value of 1; in case of a return value of 0, the function must be invoked
 164  * again with exactly the same arguments.
 165  *
 166  * The mailbox argument is used to store the context of an on-going table key lookup operation, and
 167  * possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent
 168  * table key lookup and add operations into the same table.
 169  *
 170  * @param[in] table
 171  *   Table handle.
 172  * @param[in] mailbox
 173  *   Mailbox for the current table lookup operation.
 174  * @param[in] time
 175  *   Current time measured in CPU clock cycles.
 176  * @param[in] key
 177  *   Lookup key. Its size must be equal to the table *key_size*.
 178  * @param[out] action_id
 179  *   ID of the action associated with the *key*. Must point to a valid 64-bit variable. Only valid
 180  *   when the function returns 1 and *hit* is set to true.
 181  * @param[out] action_data
 182  *   Action data for the *action_id* action. Must point to a valid array of table *action_data_size*
 183  *   bytes. Only valid when the function returns 1 and *hit* is set to true.
 184  * @param[out] hit
 185  *   Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero
 186  *   (false) on table lookup miss.
 187  * @return
 188  *   0 when the table lookup operation is not yet completed, and 1 when the table lookup operation
 189  *   is completed. No other return values are allowed.
 190  */
 191 __rte_experimental
 192 int
 193 rte_swx_table_learner_lookup(void *table,
 194                              void *mailbox,
 195                              uint64_t time,
 196                              uint8_t **key,
 197                              uint64_t *action_id,
 198                              uint8_t **action_data,
 199                              int *hit);
 200
 201 /**
 202  * Learner table key add
 203  *
 204  * This operation takes the latest key that was looked up in the table and adds it to the table with
 205  * the given action ID and action data. Typically, this operation is only invoked when the latest
 206  * lookup operation in the current table resulted in lookup miss.
 207  *
 208  * @param[in] table
 209  *   Table handle.
 210  * @param[in] mailbox
 211  *   Mailbox for the current operation.
 212  * @param[in] time
 213  *   Current time measured in CPU clock cycles.
 214  * @param[out] action_id
 215  *   ID of the action associated with the key.
 216  * @param[out] action_data
 217  *   Action data for the *action_id* action.
 218  * @param[in] key_timeout_id
 219  *   Key timeout ID.
 220  * @return
 221  *   0 on success, 1 or error (table full).
 222  */
 223 __rte_experimental
 224 uint32_t
 225 rte_swx_table_learner_add(void *table,
 226                           void *mailbox,
 227                           uint64_t time,
 228                           uint64_t action_id,
 229                           uint8_t *action_data,
 230                           uint32_t key_timeout_id);
 231
 232 /**
 233  * Learner table key rearm with same timeout value
 234  *
 235  * This operation takes the latest key that was looked up in the table and, in case of lookup hit,
 236  * it rearms its expiration timer using the same timeout value currently associated with the key.
 237  *
 238  * @param[in] table
 239  *   Table handle.
 240  * @param[in] mailbox
 241  *   Mailbox for the current operation.
 242  * @param[in] time
 243  *   Current time measured in CPU clock cycles.
 244  */
 245 __rte_experimental
 246 void
 247 rte_swx_table_learner_rearm(void *table,
 248                             void *mailbox,
 249                             uint64_t time);
 250
 251 /**
 252  * Learner table key rearm with given timeout value
 253  *
 254  * This operation takes the latest key that was looked up in the table and, in case of lookup hit,
 255  * it rearms its expiration timer using the given timeout value.
 256  *
 257  * @param[in] table
 258  *   Table handle.
 259  * @param[in] mailbox
 260  *   Mailbox for the current operation.
 261  * @param[in] time
 262  *   Current time measured in CPU clock cycles.
 263  * @param[in] key_timeout_id
 264  *   Key timeout ID.
 265  */
 266 __rte_experimental
 267 void
 268 rte_swx_table_learner_rearm_new(void *table,
 269                                 void *mailbox,
 270                                 uint64_t time,
 271                                 uint32_t key_timeout_id);
 272
 273 /**
 274  * Learner table key delete
 275  *
 276  * This operation takes the latest key that was looked up in the table and deletes it from the
 277  * table. Typically, this operation is only invoked to force the deletion of the key before the key
 278  * expires on timeout due to inactivity.
 279  *
 280  * @param[in] table
 281  *   Table handle.
 282  * @param[in] mailbox
 283  *   Mailbox for the current operation.
 284  */
 285 __rte_experimental
 286 void
 287 rte_swx_table_learner_delete(void *table,
 288                              void *mailbox);
 289
 290 /**
 291  * Learner table free
 292  *
 293  * @param[in] table
 294  *   Table handle.
 295  */
 296 __rte_experimental
 297 void
 298 rte_swx_table_learner_free(void *table);
 299
 300 #ifdef __cplusplus
 301 }
 302 #endif
 303
 304 #endif