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