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