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