docs: better docs, mv doxygen to sphinx

This patch refactors the VPP sphinx docs
in order to make it easier to consume
for external readers as well as VPP developers.

It also makes sphinx the single source
of documentation, which simplifies maintenance
and operation.

Most important updates are:

- reformat the existing documentation as rst
- split RELEASE.md and move it into separate rst files
- remove section 'events'
- remove section 'archive'
- remove section 'related projects'
- remove section 'feature by release'
- remove section 'Various links'
- make (Configuration reference, CLI docs,
  developer docs) top level items in the list
- move 'Use Cases' as part of 'About VPP'
- move 'Troubleshooting' as part of 'Getting Started'
- move test framework docs into 'Developer Documentation'
- add a 'Contributing' section for gerrit,
  docs and other contributer related infos
- deprecate doxygen and test-docs targets
- redirect the "make doxygen" target to "make docs"

Type: refactor

Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>

1 files changed, 106 insertions, 0 deletions

diff --git a/docs/developer/corefeatures/fib/multicast.rst b/docs/developer/corefeatures/fib/multicast.rst
new file mode 100644
index 00000000000..37c5673dcde
--- /dev/null
+++ b/docs/developer/corefeatures/fib/multicast.rst
@@ -0,0 +1,106 @@
+.. _mfib:
+
+IP Multicast FIB
+----------------
+
+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/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.
+
+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:
+
+.. code-block:: console
+
+   $ ip mroute add 1.1.1.1 239.1.1.1 via GigEthernet0/0/0 Forward
+   $ ip mroute add 1.1.1.1 239.1.1.1 via GigEthernet0/0/1 Forward
+
+the flag 'Forward' passed with the path specifies this path to be part of the replication set.
+To add a path from GigEthernet0/0/2 to the accepting (RPF) set do:
+
+.. code-block:: console
+
+   $ ip mroute add 1.1.1.1 239.1.1.1 via GigEthernet0/0/2 Accept
+
+A (\*,G) entry is added by not specifying a source address:
+
+.. code-block:: console
+
+   $ ip mroute add 232.2.2.2 via GigEthernet0/0/2 Forward
+
+A (\*,G/m) entry is added by not specifying a source address and giving
+the group address a mask:
+
+.. code-block:: console
+
+   $ ip mroute add 232.2.2.0/24 via GigEthernet0/0/2 Forward
+
+Entries are deleted when all paths have been removed and all entry flags (see below) are also removed.
+
+Advanced
+^^^^^^^^
+
+There are a set of flags associated only with an entry, see:
+
+.. code-block:: console
+
+   $ show mfib route flags
+
+only some of these are relevant over the API/CLI:
+
+#. Signal - packets that match this entry will generate an event that
+   is sent to the control plane (which can be retrieved via the signal
+   dump API)
+#. Connected - indicates that the control plane should be informed of
+   connected sources (also retrieved via the signal dump API)
+#. Accept-all-itf - the entry shall accept packets from all
+   interfaces, thus eliminating the RPF check
+#. Drop - Drop all packet matching this entry.
+
+flags on an entry can be changed with:
+
+.. code-block:: console
+
+   $ ip mroute <PREFIX> <FLAG>
+
+An alternative approach to the RPF check, that does check the
+accepting path set, is to give the entry and RPF-ID:
+
+.. code-block:: console
+
+   $ ip mroute <PREFIX> rpf-id X
+
+the RPF-ID is an attribute of a received packet's meta-data and is
+added to the packet when it ingresses on a given entity such as an
+MPLS-tunnel or a BIER table disposition entry.