xref: /dpdk/lib/fib/rte_fib.h (revision 02d36ef6a9528e0f4a3403956e66bcea5fadbf8c)
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 created by rte_fib_create().
126  *   If fib is NULL, no operation is performed.
127  */
128 void
129 rte_fib_free(struct rte_fib *fib);
130 
131 /**
132  * Add a route to the FIB.
133  *
134  * @param fib
135  *   FIB object handle
136  * @param ip
137  *   IPv4 prefix address to be added to the FIB
138  * @param depth
139  *   Prefix length
140  * @param next_hop
141  *   Next hop to be added to the FIB
142  * @return
143  *   0 on success, negative value otherwise
144  */
145 int
146 rte_fib_add(struct rte_fib *fib, uint32_t ip, uint8_t depth, uint64_t next_hop);
147 
148 /**
149  * Delete a rule from the FIB.
150  *
151  * @param fib
152  *   FIB object handle
153  * @param ip
154  *   IPv4 prefix address to be deleted from the FIB
155  * @param depth
156  *   Prefix length
157  * @return
158  *   0 on success, negative value otherwise
159  */
160 int
161 rte_fib_delete(struct rte_fib *fib, uint32_t ip, uint8_t depth);
162 
163 /**
164  * Lookup multiple IP addresses in the FIB.
165  *
166  * @param fib
167  *   FIB object handle
168  * @param ips
169  *   Array of IPs to be looked up in the FIB
170  * @param next_hops
171  *   Next hop of the most specific rule found for IP.
172  *   This is an array of eight byte values.
173  *   If the lookup for the given IP failed, then corresponding element would
174  *   contain default nexthop value configured for a FIB.
175  * @param n
176  *   Number of elements in ips (and next_hops) array to lookup.
177  *  @return
178  *   -EINVAL for incorrect arguments, otherwise 0
179  */
180 int
181 rte_fib_lookup_bulk(struct rte_fib *fib, uint32_t *ips,
182 		uint64_t *next_hops, int n);
183 /**
184  * Get pointer to the dataplane specific struct
185  *
186  * @param fib
187  *   FIB object handle
188  * @return
189  *   Pointer on the dataplane struct on success
190  *   NULL otherwise
191  */
192 void *
193 rte_fib_get_dp(struct rte_fib *fib);
194 
195 /**
196  * Get pointer to the RIB
197  *
198  * @param fib
199  *   FIB object handle
200  * @return
201  *   Pointer on the RIB on success
202  *   NULL otherwise
203  */
204 struct rte_rib *
205 rte_fib_get_rib(struct rte_fib *fib);
206 
207 /**
208  * Set lookup function based on type
209  *
210  * @param fib
211  *   FIB object handle
212  * @param type
213  *   type of lookup function
214  *
215  * @return
216  *   0 on success
217  *   -EINVAL on failure
218  */
219 int
220 rte_fib_select_lookup(struct rte_fib *fib, enum rte_fib_lookup_type type);
221 
222 #ifdef __cplusplus
223 }
224 #endif
225 
226 #endif /* _RTE_FIB_H_ */
227