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