docs: Update FIB documentation
Type: docs
Signed-off-by: Neale Ranns <nranns@cisco.com>
Change-Id: I3dfde4520a48c945ca9707accabbe1735c1a8799
diff --git a/docs/gettingstarted/developers/fib20/multicast.rst b/docs/gettingstarted/developers/fib20/multicast.rst
index 15bcddf..7cffba8 100644
--- a/docs/gettingstarted/developers/fib20/multicast.rst
+++ b/docs/gettingstarted/developers/fib20/multicast.rst
@@ -3,22 +3,40 @@
IP Multicast FIB
----------------
-Basics
-^^^^^^
+The two principal differences between multicast and unicast forwarding
+are:
+
+* there is no load-balancing among paths, there is only replication
+ across paths.
+* multicast forwarding has an explicit reverse path forwarding (RPF)
+ check. It will only forward a packet if it arrives from a peer for
+ which it has been explicitly configured to accept.
+
+The other factor that influences the design of the mFIB is that the
+match criteria (the prefix) is different. For multicast it is
+necessary to be able to match on source and destination/group
+addresses (termed an (S,G)) and only on a destination prefix (a (\*,
+G/m)). This prefix is much bigger than a unicast prefix, and since
+unicast scale is almost always greater than multicast scale, it is not
+a good idea to have a single definition of a prefix. Therefore,
+there is a fib_prefix_t (and hence a fib_entry_t) and an
+mfib_prefix_t (and hence a mfib_entry_t).
+
+The fib_path_t and fib_path_list_t are reused. A path can represent
+either a peer from which to accept packets or a peer to which to send
+packets. A path-extension is added to the fib_path_t/mfib_entry_t to
+describe the role the path plays. Logically the path-list is split
+into two sets; an accepting set and a forwarding set. The forwarding set
+contributes a replicate DPO for forwarding and the accepting set
+contributes a list of interfaces (an mfib_itf_t) for the RPF check.
An IP multicast FIB (mFIB) is a data-structure that holds entries that
-represent a (S,G) or a (\*,G) multicast group. There is one IPv4 and
+represent a (S,G) or a (\*,G/m) multicast group. There is one IPv4 and
one IPv6 mFIB per IP table, i.e. each time the user calls 'ip[6] table
add X' an mFIB is created.
-
-A path describes either where a packet is sent to or where a packet is
-received from. mFIB entries maintain two sets of 'paths'; the
-forwarding set and the accepting set. Each path in the forwarding set
-will output a replica of a received packet. A received packet is only
-accepted for forwarding if it ingresses on a path that matches in the
-accepting set - this is the RPF check.
-
+Usage
+^^^^^
To add an entry to the default mFIB for the group (1.1.1.1, 239.1.1.1)
that will replicate packets to GigEthernet0/0/0 and GigEthernet0/0/1, do: