From dfd3954c0427422e2739b858d1e18503a5c59970 Mon Sep 17 00:00:00 2001 From: Neale Ranns Date: Mon, 9 Nov 2020 10:09:42 +0000 Subject: docs: Update FIB documentation Type: docs Signed-off-by: Neale Ranns Change-Id: I3dfde4520a48c945ca9707accabbe1735c1a8799 --- docs/gettingstarted/developers/fib20/neighbors.rst | 88 ++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/gettingstarted/developers/fib20/neighbors.rst (limited to 'docs/gettingstarted/developers/fib20/neighbors.rst') diff --git a/docs/gettingstarted/developers/fib20/neighbors.rst b/docs/gettingstarted/developers/fib20/neighbors.rst new file mode 100644 index 00000000000..f460955239c --- /dev/null +++ b/docs/gettingstarted/developers/fib20/neighbors.rst @@ -0,0 +1,88 @@ +.. _neighbors: + +Neighbours +^^^^^^^^^^^ + +.. figure:: /_images/ip-neighbor.png + +Figure 1: Neighbour data model + +Figure 1 shows the data model for IP neighbours. An IP neighbour contains the mapping +between a peer, identified by an IPv4 or IPv6 address, and its MAC address on a given +interface. An IP-table (VRF) is not part of the neighbour's +data/identity. This is because the virtualisation of a router into +different tables (VRFs) is performed at the interface level, i.e. an +IP-table is bound to a particular interface. A neighbour, which is +attached to an interface, is thus implicitly in that table, and +only in that table. It is also worth noting that IP neighbours +contribute forwarding for the egress direction, whereas an IP-table +is an ingress only function. + +The *ip_neighbor_t* represents the control-plane addition of the +neighbour. The *ip_adjacency_t* contains the data derived from the *ip_neighbor_t* that is needed to +forward packets to the peer. The additional data in the adjacency are the *rewrite* +and the *link_type*. The *link_type* is a description of the protocol of the packets +that will be forwarded with this adjacency; e.g. IPv4, IPv6 or MPLS. The *link_type* +maps directly to the ether-type in an Ethernet header, or the protocol filed in a +GRE header. The rewrite is a byte string representation of the header that will be +prepended to the packet when it is sent to that peer. For Ethernet interfaces this +is be the src,dst MAC and the ether-type. For LISP tunnels, the IP src,dst pair +and the LISP header. + +The *ip_neighbor_t* for an IPv4 peer (learned e.g. over ARP) will +install a *link_type=IPv4* when the entry is created and a +link_type=MPLS on demand (i.e. when a route with output labels resolves via the peer). + +Adjacency +--------- + +There are three sub-types of adjacencies. Purists would argue that some +of these sub-types are not really adjacencies but are instead other +forms of DPOs, and it would be hard to argue against that, but +historically (not just in VPP, but in the FIB implementations from +which VPP draws on for some of its concepts), these have been modelled +as adjacency types, the one thing they have in common is that they +have an associated interface and are terminal. The [sub] sub-types are: + +* A Neighbour Adjacency (key={interface, next-hop, link-type}). A + representation of a peer on a link (as described above). A neighbour adjacency itself has + two sub-types; terminal and mid-chain. When one speak of 'an + adjacency' one is usually referring to a terminal neighbour + sub-type. A mid-chain adjacency represents a neighbor on a virtual + interface which relies on the FIB to perform further forwarding. This + adjacency is thus not terminal for the FIB object graph but instead + appears in the 'middle' (the term chain is a synonym for graph in + some contexts). + A neighbour adjacency can be in one of two states; complete and + incomplete. A complete adjacency knows the rewrite string that + should be used to reach the peer, an incomplete adjacency does + not. If the adjacency was added as a result of the addition of an + *ip_neighbor_t* then the adjacency will be complete (because the + *ip_neighbor_t* knows the peer's MAC address). An incomplete + adjacency is created on demand by the FIB when a route's path + requires to resolve through such an adjacency. It is thus created in + order to resolve the missing dependency, it will become complete + once the *ip_neighbor_t* is discovered. + In the forwarding path a complete adjacency will prepend the rewrite + string and transmit on the egress interface, an incomplete adjacency + will construct a ARP/ND request to resolve the peer's IP address. + +* A Glean Adjacency (key={interface}). This is a representation of the need to discover + a peer on the given interface. It is used when it is known that the + packet is destined to an undiscoverd peer on that interface. The + difference between the glean adjacency and an + incomplete neighbour adjacency is that in the forwarding path the + glean adjacency will construct an ARP/ND request for the peer as + determined from the packet's destination address. The glean + adjacency is used to resolve connected prefixes on multi-access + interfaces. + +* A Multicast Adjacency (key={interface}). This represents the need to send an IP + multicast packet out of the adjacency's associated interface. Since + IP multicast constructs the destination MAC address from the IP + packet's destination/group address, the rewrite is always known and + hence the adjacency is always complete. + + +All adjacency types can be shared between routes, hence each type is +stored in a DB whose key is appropriate for the type. -- cgit 1.2.3-korg