lib/librte_rib/rte_rib.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_RIB_H_
   7 #define _RTE_RIB_H_
   8
   9 /**
  10  * @file
  11  *
  12  * RTE RIB library.
  13  *
  14  * @warning
  15  * @b EXPERIMENTAL:
  16  * All functions in this file may be changed or removed without prior notice.
  17  *
  18  * Level compressed tree implementation for IPv4 Longest Prefix Match
  19  */
  20
  21 #include <rte_compat.h>
  22
  23 /**
  24  * rte_rib_get_nxt() flags
  25  */
  26 enum {
  27         /** flag to get all subroutes in a RIB tree */
  28         RTE_RIB_GET_NXT_ALL,
  29         /** flag to get first matched subroutes in a RIB tree */
  30         RTE_RIB_GET_NXT_COVER
  31 };
  32
  33 struct rte_rib;
  34 struct rte_rib_node;
  35
  36 /** RIB configuration structure */
  37 struct rte_rib_conf {
  38         /**
  39          * Size of extension block inside rte_rib_node.
  40          * This space could be used to store additional user
  41          * defined data.
  42          */
  43         size_t  ext_sz;
  44         /* size of rte_rib_node's pool */
  45         int     max_nodes;
  46 };
  47
  48 /**
  49  * Get an IPv4 mask from prefix length
  50  * It is caller responsibility to make sure depth is not bigger than 32
  51  *
  52  * @param depth
  53  *   prefix length
  54  * @return
  55  *  IPv4 mask
  56  */
  57 static inline uint32_t
  58 rte_rib_depth_to_mask(uint8_t depth)
  59 {
  60         return (uint32_t)(UINT64_MAX << (32 - depth));
  61 }
  62
  63 /**
  64  * Lookup an IP into the RIB structure
  65  *
  66  * @param rib
  67  *  RIB object handle
  68  * @param ip
  69  *  IP to be looked up in the RIB
  70  * @return
  71  *  pointer to struct rte_rib_node on success
  72  *  NULL otherwise
  73  */
  74 __rte_experimental
  75 struct rte_rib_node *
  76 rte_rib_lookup(struct rte_rib *rib, uint32_t ip);
  77
  78 /**
  79  * Lookup less specific route into the RIB structure
  80  *
  81  * @param ent
  82  *  Pointer to struct rte_rib_node that represents target route
  83  * @return
  84  *  pointer to struct rte_rib_node that represents
  85  *   less specific route on success
  86  *  NULL otherwise
  87  */
  88 __rte_experimental
  89 struct rte_rib_node *
  90 rte_rib_lookup_parent(struct rte_rib_node *ent);
  91
  92 /**
  93  * Lookup prefix into the RIB structure
  94  *
  95  * @param rib
  96  *  RIB object handle
  97  * @param ip
  98  *  net to be looked up in the RIB
  99  * @param depth
 100  *  prefix length
 101  * @return
 102  *  pointer to struct rte_rib_node on success
 103  *  NULL otherwise
 104  */
 105 __rte_experimental
 106 struct rte_rib_node *
 107 rte_rib_lookup_exact(struct rte_rib *rib, uint32_t ip, uint8_t depth);
 108
 109 /**
 110  * Retrieve next more specific prefix from the RIB
 111  * that is covered by ip/depth supernet in an ascending order
 112  *
 113  * @param rib
 114  *  RIB object handle
 115  * @param ip
 116  *  net address of supernet prefix that covers returned more specific prefixes
 117  * @param depth
 118  *  supernet prefix length
 119  * @param last
 120  *   pointer to the last returned prefix to get next prefix
 121  *   or
 122  *   NULL to get first more specific prefix
 123  * @param flag
 124  *  -RTE_RIB_GET_NXT_ALL
 125  *   get all prefixes from subtrie
 126  *  -RTE_RIB_GET_NXT_COVER
 127  *   get only first more specific prefix even if it have more specifics
 128  * @return
 129  *  pointer to the next more specific prefix
 130  *  NULL if there is no prefixes left
 131  */
 132 __rte_experimental
 133 struct rte_rib_node *
 134 rte_rib_get_nxt(struct rte_rib *rib, uint32_t ip, uint8_t depth,
 135         struct rte_rib_node *last, int flag);
 136
 137 /**
 138  * Remove prefix from the RIB
 139  *
 140  * @param rib
 141  *  RIB object handle
 142  * @param ip
 143  *  net to be removed from the RIB
 144  * @param depth
 145  *  prefix length
 146  */
 147 __rte_experimental
 148 void
 149 rte_rib_remove(struct rte_rib *rib, uint32_t ip, uint8_t depth);
 150
 151 /**
 152  * Insert prefix into the RIB
 153  *
 154  * @param rib
 155  *  RIB object handle
 156  * @param ip
 157  *  net to be inserted to the RIB
 158  * @param depth
 159  *  prefix length
 160  * @return
 161  *  pointer to new rte_rib_node on success
 162  *  NULL otherwise
 163  */
 164 __rte_experimental
 165 struct rte_rib_node *
 166 rte_rib_insert(struct rte_rib *rib, uint32_t ip, uint8_t depth);
 167
 168 /**
 169  * Get an ip from rte_rib_node
 170  *
 171  * @param node
 172  *  pointer to the rib node
 173  * @param ip
 174  *  pointer to the ip to save
 175  * @return
 176  *  0 on success.
 177  *  -1 on failure with rte_errno indicating reason for failure.
 178  */
 179 __rte_experimental
 180 int
 181 rte_rib_get_ip(const struct rte_rib_node *node, uint32_t *ip);
 182
 183 /**
 184  * Get a depth from rte_rib_node
 185  *
 186  * @param node
 187  *  pointer to the rib node
 188  * @param depth
 189  *  pointer to the depth to save
 190  * @return
 191  *  0 on success.
 192  *  -1 on failure with rte_errno indicating reason for failure.
 193  */
 194 __rte_experimental
 195 int
 196 rte_rib_get_depth(const struct rte_rib_node *node, uint8_t *depth);
 197
 198 /**
 199  * Get ext field from the rib node
 200  * It is caller responsibility to make sure there are necessary space
 201  * for the ext field inside rib node.
 202  *
 203  * @param node
 204  *  pointer to the rib node
 205  * @return
 206  *  pointer to the ext
 207  */
 208 __rte_experimental
 209 void *
 210 rte_rib_get_ext(struct rte_rib_node *node);
 211
 212 /**
 213  * Get nexthop from the rib node
 214  *
 215  * @param node
 216  *  pointer to the rib node
 217  * @param nh
 218  *  pointer to the nexthop to save
 219  * @return
 220  *  0 on success.
 221  *  -1 on failure with rte_errno indicating reason for failure.
 222  */
 223 __rte_experimental
 224 int
 225 rte_rib_get_nh(const struct rte_rib_node *node, uint64_t *nh);
 226
 227 /**
 228  * Set nexthop into the rib node
 229  *
 230  * @param node
 231  *  pointer to the rib node
 232  * @param nh
 233  *  nexthop value to set to the rib node
 234  * @return
 235  *  0 on success.
 236  *  -1 on failure with rte_errno indicating reason for failure.
 237  */
 238 __rte_experimental
 239 int
 240 rte_rib_set_nh(struct rte_rib_node *node, uint64_t nh);
 241
 242 /**
 243  * Create RIB
 244  *
 245  * @param name
 246  *  RIB name
 247  * @param socket_id
 248  *  NUMA socket ID for RIB table memory allocation
 249  * @param conf
 250  *  Structure containing the configuration
 251  * @return
 252  *  Handle to RIB object on success
 253  *  NULL otherwise with rte_errno indicating reason for failure.
 254  */
 255 __rte_experimental
 256 struct rte_rib *
 257 rte_rib_create(const char *name, int socket_id,
 258                const struct rte_rib_conf *conf);
 259
 260 /**
 261  * Find an existing RIB object and return a pointer to it.
 262  *
 263  * @param name
 264  *  Name of the rib object as passed to rte_rib_create()
 265  * @return
 266  *  Pointer to RIB object on success
 267  *  NULL otherwise with rte_errno indicating reason for failure.
 268  */
 269 __rte_experimental
 270 struct rte_rib *
 271 rte_rib_find_existing(const char *name);
 272
 273 /**
 274  * Free an RIB object.
 275  *
 276  * @param rib
 277  *   RIB object handle
 278  * @return
 279  *   None
 280  */
 281 __rte_experimental
 282 void
 283 rte_rib_free(struct rte_rib *rib);
 284
 285 #endif /* _RTE_RIB_H_ */