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