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