FIB table add/delete API
[vpp.git] / src / vnet / fib / fib_table.h
1 /*
2  * Copyright (c) 2016 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15
16 #ifndef __FIB_TABLE_H__
17 #define __FIB_TABLE_H__
18
19 #include <vnet/ip/ip.h>
20 #include <vnet/adj/adj.h>
21 #include <vnet/fib/fib_entry.h>
22 #include <vnet/mpls/mpls.h>
23 #include <vnet/mpls/packet.h>
24
25 /**
26  * Keep a lock per-source and a total
27  */
28 #define FIB_TABLE_N_LOCKS (FIB_SOURCE_MAX+1)
29 #define FIB_TABLE_TOTAL_LOCKS FIB_SOURCE_MAX
30
31 /**
32  * @brief 
33  *   A protocol Independent FIB table
34  */
35 typedef struct fib_table_t_
36 {
37     /**
38      * Which protocol this table serves. Used to switch on the union above.
39      */
40     fib_protocol_t ft_proto;
41
42     /**
43      * per-source number of locks on the table
44      */
45     u16 ft_locks[FIB_TABLE_N_LOCKS];
46
47     /**
48      * Table ID (hash key) for this FIB.
49      */
50     u32 ft_table_id;
51
52     /**
53      * Index into FIB vector.
54      */
55     fib_node_index_t ft_index;
56
57     /**
58      * flow hash configuration
59      */
60     u32 ft_flow_hash_config;
61
62     /**
63      * Per-source route counters
64      */
65     u32 ft_src_route_counts[FIB_SOURCE_MAX];
66
67     /**
68      * Total route counters
69      */
70     u32 ft_total_route_counts;
71
72     /**
73      * Table description
74      */
75     u8* ft_desc;
76 } fib_table_t;
77
78 /**
79  * @brief
80  *  Format the description/name of the table
81  */
82 extern u8* format_fib_table_name(u8* s, va_list ap);
83
84 /**
85  * @brief
86  *  Perfom a longest prefix match in the non-forwarding table
87  *
88  * @param fib_index
89  *  The index of the FIB
90  *
91  * @param prefix
92  *  The prefix to lookup
93  *
94  * @return
95  *  The index of the fib_entry_t for the best match, which may be the default route
96  */
97 extern fib_node_index_t fib_table_lookup(u32 fib_index,
98                                          const fib_prefix_t *prefix);
99
100 /**
101  * @brief
102  *  Perfom an exact match in the non-forwarding table
103  *
104  * @param fib_index
105  *  The index of the FIB
106  *
107  * @param prefix
108  *  The prefix to lookup
109  *
110  * @return
111  *  The index of the fib_entry_t for the exact match, or INVALID
112  *  is there is no match.
113  */
114 extern fib_node_index_t fib_table_lookup_exact_match(u32 fib_index,
115                                                      const fib_prefix_t *prefix);
116
117 /**
118  * @brief
119  *  Get the less specific (covering) prefix
120  *
121  * @param fib_index
122  *  The index of the FIB
123  *
124  * @param prefix
125  *  The prefix to lookup
126  *
127  * @return
128  *  The index of the less specific fib_entry_t.
129  */
130 extern fib_node_index_t fib_table_get_less_specific(u32 fib_index,
131                                                     const fib_prefix_t *prefix);
132
133 /**
134  * @brief
135  *  Add a 'special' entry to the FIB.
136  *  A special entry is an entry that the FIB is not expect to resolve
137  *  via the usual mechanisms (i.e. recurisve or neighbour adj DB lookup).
138  *  Instead the will link to a DPO valid for the source and/or the flags.
139  *  This add is reference counting per-source. So n 'removes' are required
140  *  for n 'adds', if the entry is no longer required.
141  *  If the source needs to provide non-default forwarding use:
142  *  fib_table_entry_special_dpo_add()
143  *
144  * @param fib_index
145  *  The index of the FIB
146  *
147  * @param prefix
148  *  The prefix to add
149  *
150  * @param source
151  *  The ID of the client/source adding the entry.
152  *
153  * @param flags
154  *  Flags for the entry.
155  *
156  * @return
157  *  the index of the fib_entry_t that is created (or exists already).
158  */
159 extern fib_node_index_t fib_table_entry_special_add(u32 fib_index,
160                                                     const fib_prefix_t *prefix,
161                                                     fib_source_t source,
162                                                     fib_entry_flag_t flags);
163
164 /**
165  * @brief
166  *  Add a 'special' entry to the FIB that links to the DPO passed
167  *  A special entry is an entry that the FIB is not expect to resolve
168  *  via the usual mechanisms (i.e. recurisve or neighbour adj DB lookup).
169  *  Instead the client/source provides the DPO to link to.
170  *  This add is reference counting per-source. So n 'removes' are required
171  *  for n 'adds', if the entry is no longer required.
172  *
173   * @param fib_index
174  *  The index of the FIB
175  *
176  * @param prefix
177  *  The prefix to add
178  *
179  * @param source
180  *  The ID of the client/source adding the entry.
181  *
182  * @param flags
183  *  Flags for the entry.
184  *
185  * @param dpo
186  *  The DPO to link to.
187  *
188  * @return
189  *  the index of the fib_entry_t that is created (or existed already).
190  */
191 extern fib_node_index_t fib_table_entry_special_dpo_add(u32 fib_index,
192                                                         const fib_prefix_t *prefix,
193                                                         fib_source_t source,
194                                                         fib_entry_flag_t stype,
195                                                         const dpo_id_t *dpo);
196
197 /**
198  * @brief
199  *  Update a 'special' entry to the FIB that links to the DPO passed
200  *  A special entry is an entry that the FIB is not expect to resolve
201  *  via the usual mechanisms (i.e. recurisve or neighbour adj DB lookup).
202  *  Instead the client/source provides the DPO to link to.
203  *  Special entries are add/remove reference counted per-source. So n
204  * 'removes' are required for n 'adds', if the entry is no longer required.
205  *  An 'update' is an 'add' if no 'add' has already been called, otherwise an 'add'
206  * is therefore assumed to act on the reference instance of that add.
207  *
208  * @param fib_entry_index
209  *  The index of the FIB entry to update
210  *
211  * @param source
212  *  The ID of the client/source adding the entry.
213  *
214  * @param flags
215  *  Flags for the entry.
216  *
217  * @param dpo
218  *  The DPO to link to.
219  *
220  * @return
221  *  the index of the fib_entry_t that is created (or existed already).
222  */
223 extern fib_node_index_t fib_table_entry_special_dpo_update (u32 fib_index,
224                                                             const fib_prefix_t *prefix,
225                                                             fib_source_t source,
226                                                             fib_entry_flag_t stype,
227                                                             const dpo_id_t *dpo);
228
229 /**
230  * @brief
231  *  Remove a 'special' entry from the FIB.
232  *  This add is reference counting per-source. So n 'removes' are required
233  *  for n 'adds', if the entry is no longer required.
234  *
235  * @param fib_index
236  *  The index of the FIB
237  *
238  * @param prefix
239  *  The prefix to remove
240  *
241  * @param source
242  *  The ID of the client/source adding the entry.
243  *
244  */
245 extern void fib_table_entry_special_remove(u32 fib_index,
246                                            const fib_prefix_t *prefix,
247                                            fib_source_t source);
248
249 /**
250  * @brief
251  *  Add one path to an entry (aka route) in the FIB. If the entry does not
252  *  exist, it will be created.
253  * See the documentation for fib_route_path_t for more descirptions of
254  * the path parameters.
255  *
256  * @param fib_index
257  *  The index of the FIB
258  *
259  * @param prefix
260  *  The prefix for the entry to add
261  *
262  * @param source
263  *  The ID of the client/source adding the entry.
264  *
265  * @param flags
266  *  Flags for the entry.
267  *
268  * @paran next_hop_proto
269  *  The protocol of the next hop. This cannot be derived in the event that
270  * the next hop is all zeros.
271  *
272  * @param next_hop
273  *  The address of the next-hop.
274  *
275  * @param sw_if_index
276  *  The index of the interface.
277  *
278  * @param next_hop_fib_index,
279  *  The fib index of the next-hop for recursive resolution
280  *
281  * @param next_hop_weight
282  *  [un]equal cost path weight
283  *
284  * @param  next_hop_label_stack
285  *  The path's out-going label stack. NULL is there is none.
286  *
287  * @param  pf
288  *  Flags for the path
289  *
290  * @return
291  *  the index of the fib_entry_t that is created (or existed already).
292  */
293 extern fib_node_index_t fib_table_entry_path_add(u32 fib_index,
294                                                  const fib_prefix_t *prefix,
295                                                  fib_source_t source,
296                                                  fib_entry_flag_t flags,
297                                                  dpo_proto_t next_hop_proto,
298                                                  const ip46_address_t *next_hop,
299                                                  u32 next_hop_sw_if_index,
300                                                  u32 next_hop_fib_index,
301                                                  u32 next_hop_weight,
302                                                  mpls_label_t *next_hop_label_stack,
303                                                  fib_route_path_flags_t pf);
304 /**
305  * @brief
306  *  Add n paths to an entry (aka route) in the FIB. If the entry does not
307  *  exist, it will be created.
308  * See the documentation for fib_route_path_t for more descirptions of
309  * the path parameters.
310  *
311  * @param fib_index
312  *  The index of the FIB
313  *
314  * @param prefix
315  *  The prefix for the entry to add
316  *
317  * @param source
318  *  The ID of the client/source adding the entry.
319  *
320  * @param flags
321  *  Flags for the entry.
322  *
323  * @param rpaths
324  *  A vector of paths. Not const since they may be modified.
325  *
326  * @return
327  *  the index of the fib_entry_t that is created (or existed already).
328  */
329 extern fib_node_index_t fib_table_entry_path_add2(u32 fib_index,
330                                                   const fib_prefix_t *prefix,
331                                                   fib_source_t source,
332                                                   fib_entry_flag_t flags,
333                                                   fib_route_path_t *rpath);
334
335 /**
336  * @brief
337  * remove one path to an entry (aka route) in the FIB. If this is the entry's
338  * last path, then the entry will be removed, unless it has other sources.
339  * See the documentation for fib_route_path_t for more descirptions of
340  * the path parameters.
341  *
342  * @param fib_index
343  *  The index of the FIB
344  *
345  * @param prefix
346  *  The prefix for the entry to add
347  *
348  * @param source
349  *  The ID of the client/source adding the entry.
350  *
351  * @paran next_hop_proto
352  *  The protocol of the next hop. This cannot be derived in the event that
353  * the next hop is all zeros.
354  *
355  * @param next_hop
356  *  The address of the next-hop.
357  *
358  * @param sw_if_index
359  *  The index of the interface.
360  *
361  * @param next_hop_fib_index,
362  *  The fib index of the next-hop for recursive resolution
363  *
364  * @param next_hop_weight
365  *  [un]equal cost path weight
366  *
367  * @param  pf
368  *  Flags for the path
369  */
370 extern void fib_table_entry_path_remove(u32 fib_index,
371                                         const fib_prefix_t *prefix,
372                                         fib_source_t source,
373                                         dpo_proto_t next_hop_proto,
374                                         const ip46_address_t *next_hop,
375                                         u32 next_hop_sw_if_index,
376                                         u32 next_hop_fib_index,
377                                         u32 next_hop_weight,
378                                         fib_route_path_flags_t pf);
379
380 /**
381  * @brief
382  * Remove n paths to an entry (aka route) in the FIB. If this is the entry's
383  * last path, then the entry will be removed, unless it has other sources.
384  * See the documentation for fib_route_path_t for more descirptions of
385  * the path parameters.
386  *
387  * @param fib_index
388  *  The index of the FIB
389  *
390  * @param prefix
391  *  The prefix for the entry to add
392  *
393  * @param source
394  *  The ID of the client/source adding the entry.
395  *
396  * @param rpaths
397  *  A vector of paths.
398  */
399 extern void fib_table_entry_path_remove2(u32 fib_index,
400                                          const fib_prefix_t *prefix,
401                                          fib_source_t source,
402                                          fib_route_path_t *paths);
403
404 /**
405  * @brief
406  *  Update an entry to have a new set of paths. If the entry does not
407  *  exist, it will be created.
408  * The difference between an 'path-add' and an update, is that path-add is
409  * an incremental addition of paths, whereas an update is a wholesale swap.
410  *
411  * @param fib_index
412  *  The index of the FIB
413  *
414  * @param prefix
415  *  The prefix for the entry to add
416  *
417  * @param source
418  *  The ID of the client/source adding the entry.
419  *
420  * @param rpaths
421  *  A vector of paths. Not const since they may be modified.
422  *
423  * @return
424  *  the index of the fib_entry_t that is created (or existed already).
425  */
426 extern fib_node_index_t fib_table_entry_update(u32 fib_index,
427                                                const fib_prefix_t *prefix,
428                                                fib_source_t source,
429                                                fib_entry_flag_t flags,
430                                                fib_route_path_t *paths);
431
432 /**
433  * @brief
434  *  Update the entry to have just one path. If the entry does not
435  *  exist, it will be created.
436  * See the documentation for fib_route_path_t for more descirptions of
437  * the path parameters.
438  *
439  * @param fib_index
440  *  The index of the FIB
441  *
442  * @param prefix
443  *  The prefix for the entry to add
444  *
445  * @param source
446  *  The ID of the client/source adding the entry.
447  *
448  * @param flags
449  *  Flags for the entry.
450  *
451  * @paran next_hop_proto
452  *  The protocol of the next hop. This cannot be derived in the event that
453  * the next hop is all zeros.
454  *
455  * @param next_hop
456  *  The address of the next-hop.
457  *
458  * @param sw_if_index
459  *  The index of the interface.
460  *
461  * @param next_hop_fib_index,
462  *  The fib index of the next-hop for recursive resolution
463  *
464  * @param next_hop_weight
465  *  [un]equal cost path weight
466  *
467  * @param  next_hop_label_stack
468  *  The path's out-going label stack. NULL is there is none.
469  *
470  * @param  pf
471  *  Flags for the path
472  *
473  * @return
474  *  the index of the fib_entry_t that is created (or existed already).
475  */
476 extern fib_node_index_t fib_table_entry_update_one_path(u32 fib_index,
477                                                         const fib_prefix_t *prefix,
478                                                         fib_source_t source,
479                                                         fib_entry_flag_t flags,
480                                                         dpo_proto_t next_hop_proto,
481                                                         const ip46_address_t *next_hop,
482                                                         u32 next_hop_sw_if_index,
483                                                         u32 next_hop_fib_index,
484                                                         u32 next_hop_weight,
485                                                         mpls_label_t *next_hop_label_stack,
486                                                         fib_route_path_flags_t pf);
487
488 /**
489  * @brief
490  *  Add a MPLS local label for the prefix/route. If the entry does not
491  *  exist, it will be created. In theory more than one local label can be
492  *  added, but this is not yet supported.
493  *
494  * @param fib_index
495  *  The index of the FIB
496  *
497  * @param prefix
498  *  The prefix for the entry to which to add the label
499  *
500  * @param label
501  *  The MPLS label to add
502  *
503  * @return
504  *  the index of the fib_entry_t that is created (or existed already).
505  */
506 extern fib_node_index_t fib_table_entry_local_label_add(u32 fib_index,
507                                                         const fib_prefix_t *prefix,
508                                                         mpls_label_t label);
509 /**
510  * @brief
511  *  remove a MPLS local label for the prefix/route.
512  *
513  * @param fib_index
514  *  The index of the FIB
515  *
516  * @param prefix
517  *  The prefix for the entry to which to add the label
518  *
519  * @param label
520  *  The MPLS label to add
521  */
522 extern void fib_table_entry_local_label_remove(u32 fib_index,
523                                                const fib_prefix_t *prefix,
524                                                mpls_label_t label);
525
526 /**
527  * @brief
528  *  Delete a FIB entry. If the entry has no more sources, then it is
529  * removed from the table.
530  *
531  * @param fib_index
532  *  The index of the FIB
533  *
534  * @param prefix
535  *  The prefix for the entry to remove
536  *
537  * @param source
538  *  The ID of the client/source adding the entry.
539  */
540 extern void fib_table_entry_delete(u32 fib_index,
541                                    const fib_prefix_t *prefix,
542                                    fib_source_t source);
543
544 /**
545  * @brief
546  *  Delete a FIB entry. If the entry has no more sources, then it is
547  * removed from the table.
548  *
549  * @param entry_index
550  *  The index of the FIB entry
551  *
552  * @param source
553  *  The ID of the client/source adding the entry.
554  */
555 extern void fib_table_entry_delete_index(fib_node_index_t entry_index,
556                                          fib_source_t source);
557
558 /**
559  * @brief
560  *  Flush all entries from a table for the source
561  *
562  * @param fib_index
563  *  The index of the FIB
564  *
565  * @paran proto
566  *  The protocol of the entries in the table
567  *
568  * @param source
569  *  the source to flush
570  */
571 extern void fib_table_flush(u32 fib_index,
572                             fib_protocol_t proto,
573                             fib_source_t source);
574
575 /**
576  * @brief
577  *  Get the index of the FIB bound to the interface
578  *
579  * @paran proto
580  *  The protocol of the FIB (and thus the entries therein)
581  *
582  * @param sw_if_index
583  *  The interface index
584  *
585  * @return fib_index
586  *  The index of the FIB
587  */
588 extern u32 fib_table_get_index_for_sw_if_index(fib_protocol_t proto,
589                                                u32 sw_if_index);
590
591 /**
592  * @brief
593  *  Get the Table-ID of the FIB bound to the interface
594  *
595  * @paran proto
596  *  The protocol of the FIB (and thus the entries therein)
597  *
598  * @param sw_if_index
599  *  The interface index
600  *
601  * @return fib_index
602  *  The tableID of the FIB
603  */
604 extern u32 fib_table_get_table_id_for_sw_if_index(fib_protocol_t proto,
605                                                   u32 sw_if_index);
606
607 /**
608  * @brief
609  *  Get the index of the FIB for a Table-ID. This DOES NOT create the
610  * FIB if it does not exist.
611  *
612  * @paran proto
613  *  The protocol of the FIB (and thus the entries therein)
614  *
615  * @param table-id
616  *  The Table-ID
617  *
618  * @return fib_index
619  *  The index of the FIB, which may be INVALID.
620  */
621 extern u32 fib_table_find(fib_protocol_t proto, u32 table_id);
622
623
624 /**
625  * @brief
626  *  Get the index of the FIB for a Table-ID. This DOES create the
627  * FIB if it does not exist.
628  *
629  * @paran proto
630  *  The protocol of the FIB (and thus the entries therein)
631  *
632  * @param table-id
633  *  The Table-ID
634  *
635  * @return fib_index
636  *  The index of the FIB
637  *
638  * @param source
639  *  The ID of the client/source.
640  */
641 extern u32 fib_table_find_or_create_and_lock(fib_protocol_t proto,
642                                              u32 table_id,
643                                              fib_source_t source);
644
645 /**
646  * @brief
647  *  Create a new table with no table ID. This means it does not get
648  * added to the hash-table and so can only be found by using the index returned.
649  *
650  * @paran proto
651  *  The protocol of the FIB (and thus the entries therein)
652  *
653  * @param fmt
654  *  A string to describe the table
655  *
656  * @param source
657  *  The ID of the client/source.
658  *
659  * @return fib_index
660  *  The index of the FIB
661  */
662 extern u32 fib_table_create_and_lock(fib_protocol_t proto,
663                                      fib_source_t source,
664                                      const char *const fmt,
665                                      ...);
666
667 /**
668  * @brief
669  *  Get the flow hash configured used by the table
670  *
671  * @param fib_index
672  *  The index of the FIB
673  *
674  * @paran proto
675  *  The protocol of the FIB (and thus the entries therein)
676  *
677  * @return The flow hash config
678  */
679 extern flow_hash_config_t fib_table_get_flow_hash_config(u32 fib_index,
680                                                          fib_protocol_t proto);
681
682 /**
683  * @brief
684  *  Get the flow hash configured used by the protocol
685  *
686  * @paran proto
687  *  The protocol of the FIB (and thus the entries therein)
688  *
689  * @return The flow hash config
690  */
691 extern flow_hash_config_t fib_table_get_default_flow_hash_config(fib_protocol_t proto);
692
693 /**
694  * @brief
695  *  Set the flow hash configured used by the table
696  *
697  * @param fib_index
698  *  The index of the FIB
699  *
700  * @paran proto
701  *  The protocol of the FIB (and thus the entries therein)
702  *
703  * @param hash_config
704  *  The flow-hash config to set
705  *
706  * @return none
707  */
708 extern void fib_table_set_flow_hash_config(u32 fib_index,
709                                            fib_protocol_t proto,
710                                            flow_hash_config_t hash_config);
711
712 /**
713  * @brief
714  * Take a reference counting lock on the table
715  *
716  * @param fib_index
717  *  The index of the FIB
718  *
719  * @paran proto
720  *  The protocol of the FIB (and thus the entries therein)
721  *
722  * @param source
723  *  The ID of the client/source.
724  */ 
725 extern void fib_table_unlock(u32 fib_index,
726                              fib_protocol_t proto,
727                              fib_source_t source);
728
729 /**
730  * @brief
731  * Release a reference counting lock on the table. When the last lock
732  * has gone. the FIB is deleted.
733  *
734  * @param fib_index
735  *  The index of the FIB
736  *
737  * @paran proto
738  *  The protocol of the FIB (and thus the entries therein)
739  *
740  * @param source
741  *  The ID of the client/source.
742  */ 
743 extern void fib_table_lock(u32 fib_index,
744                            fib_protocol_t proto,
745                            fib_source_t source);
746
747 /**
748  * @brief
749  * Return the number of entries in the FIB added by a given source.
750  *
751  * @param fib_index
752  *  The index of the FIB
753  *
754  * @paran proto
755  *  The protocol of the FIB (and thus the entries therein)
756  *
757  * @return number of sourced entries.
758  */ 
759 extern u32 fib_table_get_num_entries(u32 fib_index,
760                                      fib_protocol_t proto,
761                                      fib_source_t source);
762
763 /**
764  * @brief
765  * Get a pointer to a FIB table
766  */
767 extern fib_table_t *fib_table_get(fib_node_index_t index,
768                                   fib_protocol_t proto);
769
770 /**
771  * @brief Call back function when walking entries in a FIB table
772  */
773 typedef int (*fib_table_walk_fn_t)(fib_node_index_t fei,
774                                    void *ctx);
775
776 /**
777  * @brief Walk all entries in a FIB table
778  * N.B: This is NOT safe to deletes. If you need to delete walk the whole
779  * table and store elements in a vector, then delete the elements
780  */
781 extern void fib_table_walk(u32 fib_index,
782                            fib_protocol_t proto,
783                            fib_table_walk_fn_t fn,
784                            void *ctx);
785
786 #endif