docs: Update FIB documentation
Type: docs
Signed-off-by: Neale Ranns <nranns@cisco.com>
Change-Id: I3dfde4520a48c945ca9707accabbe1735c1a8799
diff --git a/docs/gettingstarted/developers/fib20/neighbors.rst b/docs/gettingstarted/developers/fib20/neighbors.rst
new file mode 100644
index 0000000..f460955
--- /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.