lib/librte_fib/rte_fib.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2018 Vladimir Medvedkin <medvedkinv@gmail.com>
   3  * Copyright(c) 2019 Intel Corporation
   4  */
   5
   6 #ifndef _RTE_FIB_H_
   7 #define _RTE_FIB_H_
   8
   9 /**
  10  * @file
  11  *
  12  * RTE FIB library.
  13  *
  14  * @warning
  15  * @b EXPERIMENTAL:
  16  * All functions in this file may be changed or removed without prior notice.
  17  *
  18  * FIB (Forwarding information base) implementation
  19  * for IPv4 Longest Prefix Match
  20  */
  21
  22 #include <rte_compat.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 struct rte_fib;
  29 struct rte_rib;
  30
  31 /** Maximum depth value possible for IPv4 FIB. */
  32 #define RTE_FIB_MAXDEPTH        32
  33
  34 /** Type of FIB struct */
  35 enum rte_fib_type {
  36         RTE_FIB_DUMMY,          /**< RIB tree based FIB */
  37         RTE_FIB_DIR24_8         /**< DIR24_8 based FIB */
  38 };
  39
  40 /** Modify FIB function */
  41 typedef int (*rte_fib_modify_fn_t)(struct rte_fib *fib, uint32_t ip,
  42         uint8_t depth, uint64_t next_hop, int op);
  43 /** FIB bulk lookup function */
  44 typedef void (*rte_fib_lookup_fn_t)(void *fib, const uint32_t *ips,
  45         uint64_t *next_hops, const unsigned int n);
  46
  47 enum rte_fib_op {
  48         RTE_FIB_ADD,
  49         RTE_FIB_DEL,
  50 };
  51
  52 /** Size of nexthop (1 << nh_sz) bits for DIR24_8 based FIB */
  53 enum rte_fib_dir24_8_nh_sz {
  54         RTE_FIB_DIR24_8_1B,
  55         RTE_FIB_DIR24_8_2B,
  56         RTE_FIB_DIR24_8_4B,
  57         RTE_FIB_DIR24_8_8B
  58 };
  59
  60 /** Type of lookup function implementation */
  61 enum rte_fib_lookup_type {
  62         RTE_FIB_LOOKUP_DEFAULT,
  63         /**< Selects the best implementation based on the max simd bitwidth */
  64         RTE_FIB_LOOKUP_DIR24_8_SCALAR_MACRO,
  65         /**< Macro based lookup function */
  66         RTE_FIB_LOOKUP_DIR24_8_SCALAR_INLINE,
  67         /**<
  68          * Lookup implementation using inlined functions
  69          * for different next hop sizes
  70          */
  71         RTE_FIB_LOOKUP_DIR24_8_SCALAR_UNI,
  72         /**<
  73          * Unified lookup function for all next hop sizes
  74          */
  75         RTE_FIB_LOOKUP_DIR24_8_VECTOR_AVX512
  76         /**< Vector implementation using AVX512 */
  77 };
  78
  79 /** FIB configuration structure */
  80 struct rte_fib_conf {
  81         enum rte_fib_type type; /**< Type of FIB struct */
  82         /** Default value returned on lookup if there is no route */
  83         uint64_t default_nh;
  84         int     max_routes;
  85         union {
  86                 struct {
  87                         enum rte_fib_dir24_8_nh_sz nh_sz;
  88                         uint32_t        num_tbl8;
  89                 } dir24_8;
  90         };
  91 };
  92
  93 /**
  94  * Create FIB
  95  *
  96  * @param name
  97  *  FIB name
  98  * @param socket_id
  99  *  NUMA socket ID for FIB table memory allocation
 100  * @param conf
 101  *  Structure containing the configuration
 102  * @return
 103  *  Handle to the FIB object on success
 104  *  NULL otherwise with rte_errno set to an appropriate values.
 105  */
 106 __rte_experimental
 107 struct rte_fib *
 108 rte_fib_create(const char *name, int socket_id, struct rte_fib_conf *conf);
 109
 110 /**
 111  * Find an existing FIB object and return a pointer to it.
 112  *
 113  * @param name
 114  *  Name of the fib object as passed to rte_fib_create()
 115  * @return
 116  *  Pointer to fib object or NULL if object not found with rte_errno
 117  *  set appropriately. Possible rte_errno values include:
 118  *   - ENOENT - required entry not available to return.
 119  */
 120 __rte_experimental
 121 struct rte_fib *
 122 rte_fib_find_existing(const char *name);
 123
 124 /**
 125  * Free an FIB object.
 126  *
 127  * @param fib
 128  *   FIB object handle
 129  * @return
 130  *   None
 131  */
 132 __rte_experimental
 133 void
 134 rte_fib_free(struct rte_fib *fib);
 135
 136 /**
 137  * Add a route to the FIB.
 138  *
 139  * @param fib
 140  *   FIB object handle
 141  * @param ip
 142  *   IPv4 prefix address to be added to the FIB
 143  * @param depth
 144  *   Prefix length
 145  * @param next_hop
 146  *   Next hop to be added to the FIB
 147  * @return
 148  *   0 on success, negative value otherwise
 149  */
 150 __rte_experimental
 151 int
 152 rte_fib_add(struct rte_fib *fib, uint32_t ip, uint8_t depth, uint64_t next_hop);
 153
 154 /**
 155  * Delete a rule from the FIB.
 156  *
 157  * @param fib
 158  *   FIB object handle
 159  * @param ip
 160  *   IPv4 prefix address to be deleted from the FIB
 161  * @param depth
 162  *   Prefix length
 163  * @return
 164  *   0 on success, negative value otherwise
 165  */
 166 __rte_experimental
 167 int
 168 rte_fib_delete(struct rte_fib *fib, uint32_t ip, uint8_t depth);
 169
 170 /**
 171  * Lookup multiple IP addresses in the FIB.
 172  *
 173  * @param fib
 174  *   FIB object handle
 175  * @param ips
 176  *   Array of IPs to be looked up in the FIB
 177  * @param next_hops
 178  *   Next hop of the most specific rule found for IP.
 179  *   This is an array of eight byte values.
 180  *   If the lookup for the given IP failed, then corresponding element would
 181  *   contain default nexthop value configured for a FIB.
 182  * @param n
 183  *   Number of elements in ips (and next_hops) array to lookup.
 184  *  @return
 185  *   -EINVAL for incorrect arguments, otherwise 0
 186  */
 187 __rte_experimental
 188 int
 189 rte_fib_lookup_bulk(struct rte_fib *fib, uint32_t *ips,
 190                 uint64_t *next_hops, int n);
 191 /**
 192  * Get pointer to the dataplane specific struct
 193  *
 194  * @param fib
 195  *   FIB object handle
 196  * @return
 197  *   Pointer on the dataplane struct on success
 198  *   NULL othervise
 199  */
 200 __rte_experimental
 201 void *
 202 rte_fib_get_dp(struct rte_fib *fib);
 203
 204 /**
 205  * Get pointer to the RIB
 206  *
 207  * @param fib
 208  *   FIB object handle
 209  * @return
 210  *   Pointer on the RIB on success
 211  *   NULL othervise
 212  */
 213 __rte_experimental
 214 struct rte_rib *
 215 rte_fib_get_rib(struct rte_fib *fib);
 216
 217 /**
 218  * Set lookup function based on type
 219  *
 220  * @param fib
 221  *   FIB object handle
 222  * @param type
 223  *   type of lookup function
 224  *
 225  * @return
 226  *   0 on success
 227  *   -EINVAL on failure
 228  */
 229 __rte_experimental
 230 int
 231 rte_fib_select_lookup(struct rte_fib *fib, enum rte_fib_lookup_type type);
 232
 233 #ifdef __cplusplus
 234 }
 235 #endif
 236
 237 #endif /* _RTE_FIB_H_ */