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 automatically deleted from the table with no control plane intervention.
  22  */
  23
  24 #include <stdint.h>
  25 #include <sys/queue.h>
  26
  27 #include <rte_compat.h>
  28
  29 /** Learner table creation parameters. */
  30 struct rte_swx_table_learner_params {
  31         /** Key size in bytes. Must be non-zero. */
  32         uint32_t key_size;
  33
  34         /** Offset of the first byte of the key within the key buffer. */
  35         uint32_t key_offset;
  36
  37         /** Mask of *key_size* bytes logically laid over the bytes at positions
  38          * *key_offset* .. (*key_offset* + *key_size* - 1) of the key buffer in order to specify
  39          * which bits from the key buffer are part of the key and which ones are not. A bit value of
  40          * 1 in the *key_mask0* means the respective bit in the key buffer is part of the key, while
  41          * a bit value of 0 means the opposite. A NULL value means that all the bits are part of the
  42          * key, i.e. the *key_mask0* is an all-ones mask.
  43          */
  44         uint8_t *key_mask0;
  45
  46         /** Maximum size (in bytes) of the action data. The data stored in the table for each entry
  47          * is equal to *action_data_size* plus 8 bytes, which are used to store the action ID.
  48          */
  49         uint32_t action_data_size;
  50
  51         /** Maximum number of keys to be stored in the table together with their associated data. */
  52         uint32_t n_keys_max;
  53
  54         /** Key timeout in seconds. Must be non-zero. Each table key expires and is automatically
  55          * deleted from the table after this many seconds.
  56          */
  57         uint32_t key_timeout;
  58 };
  59
  60 /**
  61  * Learner table memory footprint get
  62  *
  63  * @param[in] params
  64  *   Table create parameters.
  65  * @return
  66  *   Table memory footprint in bytes.
  67  */
  68 __rte_experimental
  69 uint64_t
  70 rte_swx_table_learner_footprint_get(struct rte_swx_table_learner_params *params);
  71
  72 /**
  73  * Learner table mailbox size get
  74  *
  75  * The mailbox is used to store the context of a lookup operation that is in
  76  * progress and it is passed as a parameter to the lookup operation. This allows
  77  * for multiple concurrent lookup operations into the same table.
  78  *
  79  * @return
  80  *   Table mailbox footprint in bytes.
  81  */
  82 __rte_experimental
  83 uint64_t
  84 rte_swx_table_learner_mailbox_size_get(void);
  85
  86 /**
  87  * Learner table create
  88  *
  89  * @param[in] params
  90  *   Table creation parameters.
  91  * @param[in] numa_node
  92  *   Non-Uniform Memory Access (NUMA) node.
  93  * @return
  94  *   Table handle, on success, or NULL, on error.
  95  */
  96 __rte_experimental
  97 void *
  98 rte_swx_table_learner_create(struct rte_swx_table_learner_params *params, int numa_node);
  99
 100 /**
 101  * Learner table key lookup
 102  *
 103  * The table lookup operation searches a given key in the table and upon its completion it returns
 104  * an indication of whether the key is found in the table (lookup hit) or not (lookup miss). In case
 105  * of lookup hit, the action_id and the action_data associated with the key are also returned.
 106  *
 107  * Multiple invocations of this function may be required in order to complete a single table lookup
 108  * operation for a given table and a given lookup key. The completion of the table lookup operation
 109  * is flagged by a return value of 1; in case of a return value of 0, the function must be invoked
 110  * again with exactly the same arguments.
 111  *
 112  * The mailbox argument is used to store the context of an on-going table key lookup operation, and
 113  * possibly an associated key add operation. The mailbox mechanism allows for multiple concurrent
 114  * table key lookup and add operations into the same table.
 115  *
 116  * @param[in] table
 117  *   Table handle.
 118  * @param[in] mailbox
 119  *   Mailbox for the current table lookup operation.
 120  * @param[in] time
 121  *   Current time measured in CPU clock cycles.
 122  * @param[in] key
 123  *   Lookup key. Its size must be equal to the table *key_size*.
 124  * @param[out] action_id
 125  *   ID of the action associated with the *key*. Must point to a valid 64-bit variable. Only valid
 126  *   when the function returns 1 and *hit* is set to true.
 127  * @param[out] action_data
 128  *   Action data for the *action_id* action. Must point to a valid array of table *action_data_size*
 129  *   bytes. Only valid when the function returns 1 and *hit* is set to true.
 130  * @param[out] hit
 131  *   Only valid when the function returns 1. Set to non-zero (true) on table lookup hit and to zero
 132  *   (false) on table lookup miss.
 133  * @return
 134  *   0 when the table lookup operation is not yet completed, and 1 when the table lookup operation
 135  *   is completed. No other return values are allowed.
 136  */
 137 __rte_experimental
 138 int
 139 rte_swx_table_learner_lookup(void *table,
 140                              void *mailbox,
 141                              uint64_t time,
 142                              uint8_t **key,
 143                              uint64_t *action_id,
 144                              uint8_t **action_data,
 145                              int *hit);
 146
 147 /**
 148  * Learner table key add
 149  *
 150  * This operation takes the latest key that was looked up in the table and adds it to the table with
 151  * the given action ID and action data. Typically, this operation is only invoked when the latest
 152  * lookup operation in the current table resulted in lookup miss.
 153  *
 154  * @param[in] table
 155  *   Table handle.
 156  * @param[in] mailbox
 157  *   Mailbox for the current operation.
 158  * @param[in] time
 159  *   Current time measured in CPU clock cycles.
 160  * @param[out] action_id
 161  *   ID of the action associated with the key.
 162  * @param[out] action_data
 163  *   Action data for the *action_id* action.
 164  * @return
 165  *   0 on success, 1 or error (table full).
 166  */
 167 __rte_experimental
 168 uint32_t
 169 rte_swx_table_learner_add(void *table,
 170                           void *mailbox,
 171                           uint64_t time,
 172                           uint64_t action_id,
 173                           uint8_t *action_data);
 174
 175 /**
 176  * Learner table key delete
 177  *
 178  * This operation takes the latest key that was looked up in the table and deletes it from the
 179  * table. Typically, this operation is only invoked to force the deletion of the key before the key
 180  * expires on timeout due to inactivity.
 181  *
 182  * @param[in] table
 183  *   Table handle.
 184  * @param[in] mailbox
 185  *   Mailbox for the current operation.
 186  */
 187 __rte_experimental
 188 void
 189 rte_swx_table_learner_delete(void *table,
 190                              void *mailbox);
 191
 192 /**
 193  * Learner table free
 194  *
 195  * @param[in] table
 196  *   Table handle.
 197  */
 198 __rte_experimental
 199 void
 200 rte_swx_table_learner_free(void *table);
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif