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, 220 insertions, 0 deletions

diff --git a/docs/developer/corefeatures/fib/mplsfib.rst b/docs/developer/corefeatures/fib/mplsfib.rst
new file mode 100644
index 00000000000..50b17304850
--- /dev/null
+++ b/docs/developer/corefeatures/fib/mplsfib.rst
@@ -0,0 +1,220 @@
+.. _mplsfib:
+
+MPLS FIB
+--------
+
+Implementation
+^^^^^^^^^^^^^^^
+
+The MPLS FIB is implemented using exactly the same data structures as
+the IP FIB.  The only difference is the implementation of the
+table. Whereas for IPv4 this is an mtrie and for IPv6 a hash table,
+for MPLS it is a flat array indexed by a 21 bit key (label & EOS
+bit). This implementation is chosen to favour packet forwarding speed.
+
+It can be the case in MPLS forwarding that packets received with the
+EOS bit set in the MPLS label need to be forwarded differently from
+those without. The most common example of this is if the path set
+contains a path that does not have an output label. In this case the
+non-EOS packets cannot take this path, because to do so would expose
+the neighbouring router to a label that it did not allocate.
+
+The design choice to make with an MPLS FIB table is therefore:
+- 20 bit key: label only. When the EOS and non-EOS actions differ the result is a 'EOS-choice' object.
+- 21 bit key: label and EOS-bit. The result is then the specific action based on EOS-bit.
+
+20 bit key
+  - Advantages:lower memory overhead, since there are few DB entries.
+  - Disadvantages: slower DP performance in the case the path-lists
+    differ, as more objects are encountered in the switch path
+
+21 bit key
+  - Advantages: faster DP performance
+    Disadvantages: increased memory footprint.
+
+Switching between schemes based on observed/measured action similarity
+is not considered on the grounds of complexity and flip-flopping.
+
+VPP mantra - favour performance over memory. We choose a 21 bit key.
+
+Basics
+^^^^^^
+
+MPLS is not enabled by default. There are two steps to get
+started. First, create the default MPLS FIB:
+
+.. code-block:: console
+
+   $ mpls table add 0
+
+With '0' being the magic number for the 'default' table (just like it
+is for IPv[46]). One can create other MPLS tables, but, unlike IP
+tables, one cannot 'bind' non-default MPLS tables to interfaces, in
+other words all MPLS packets received on an interface will always
+result in a lookup in the default table. One has to be more inventive
+to use the non-default tables...
+
+Secondly, for *each* interface on which you wish to *receive* MPLS
+packets, that interface must be MPLS 'enabled'
+
+.. code-block:: console
+
+   $ set interface mpls GigEthernet0/0/0 enable
+
+there is no equivalent enable for transmit, all that is required is to
+use an interface as an egress path.
+
+Entries in the MPLS FIB can be displayed with:
+
+.. code-block:: console
+
+   $ sh mpls fib [table X] [label]
+
+There is a tight coupling between IP and MPLS forwarding. MPLS
+forwarding equivalence classes (FECs) are often an IP prefix – that is
+to say that traffic matching a given IP prefix is routed into a MPLS
+label switch path (LSP). It is thus necessary to be able to associate
+a given prefix/route with an [out-going] MPLS label that will be
+imposed when the packet is forwarded. This is configured as:
+
+.. code-block:: console
+
+   $ ip route add 1.1.1.1/32 via 10.10.10.10 GigEthernet0/0/0 out-labels 33
+
+packets matching 1.1.1.1/32 will be forwarded out GigEthernet0/0/0 and have
+MPLS label 33 imposed. More than one out-going label can be
+specified. Out-going MPLS labels can be applied to recursive and
+non-recursive routes, e.g;
+
+.. code-block:: console
+
+   $ ip route add 2.2.2.0/24 via 1.1.1.1 out-labels 34
+
+packets matching 2.2.2.0/24 will thus have two MPLS labels imposed; 34
+and 33. This is the realisation of, e,g, an MPLS BGP VPNv4.
+
+To associate/allocate a local-label for a prefix, and thus have
+packets to that local-label forwarded equivalently to the prefix do;
+
+.. code-block:: console
+
+   $ mpls local-label 99 2.2.2.0/24
+
+In the API this action is called a ‘bind’.
+The router receiving the MPLS encapsulated packets needs to be
+programmed with actions associated which each label value – this is
+the role of the MPLS FIB. The MPLS FIB is a table, whose key is the
+MPLS label value and end-of-stack (EOS) bit, which stores the action
+to perform on packets with matching encapsulation. Currently supported
+actions are:
+
+#. Pop the label and perform an IPv[46] lookup in a specified table
+#. Pop the label and forward via a specified next-hop (this is penultimate-hop-pop, PHP)
+#. Swap the label and forward via a specified next-hop.
+
+These can be programmed respectively by:	
+
+.. code-block:: console
+
+   $ mpls local-label 33 eos ip4-lookup-in-table X
+   $ mpls local-label 33 [eos] via 10.10.10.10 GigEthernet0/0/0
+   $ mpls local-label 33 [eos] via 10.10.10.10 GigEthernet0/0/0 out-labels 66
+
+the latter is an example of an MPLS cross connect. Any description of
+a next-hop, recursive, non-recursive, labelled, non-labelled, etc,
+that is valid for an IP prefix, is also valid for an MPLS
+local-label. Note the use of the 'eos' keyword which indicates the
+programming is for the case when the label is end-of-stack. The last
+two operations can apply to both eos and non-eos packets, but the pop
+and IP lookup only to an eos packet.
+
+
+MPLS VPN
+^^^^^^^^
+
+To configure an MPLS VPN for a PE the following example can be used.
+
+Step 1; Configure routes to the iBGP peers - note these route MUST
+have out-going labels;
+
+.. code-block:: console
+
+   $ ip route add 10.0.0.1/32 via 192.168.1.2 Eth0 out-labels 33
+   $ ip route add 10.0.0.2/32 via 192.168.2.2 Eth0 out-labels 34
+
+Step 2; Configure the customer 'VRF'
+
+.. code-block:: console
+
+   $ ip table add 2
+
+Step 3; add a route via the iBGP peer[s] with the MPLS label
+advertised by that peer
+
+.. code-block:: console
+
+   $ ip route add table 2 10.10.10.0/24 via 10.0.0.2 next-hop-table 0 out-label 122
+   $ ip route add table 2 10.10.10.0/24 via 10.0.0.1 next-hop-table 0 out-label 121
+
+Step 4; add a route via the eBGP peer
+
+.. code-block:: console
+
+   $ ip route add table 2 10.10.20.0/24 via 172.16.0.1 next-hop-table 2
+
+Step 5; depending on the label allocation scheme used, add routes to
+the MPLS FIB to accept incoming labelled packets:
+
+#. per-prefix label scheme - this command 'binds' the label to the same
+   forwarding as the IP route
+
+   .. code-block:: console
+
+      $ mpls local-label 99 10.10.20.0/24
+
+#. per-CE label scheme - this pops the incoming label and forwards via
+   the next-hop provided. Append config for 'out-labels' if so desired.
+
+   .. code-block:: console
+
+      $ mpls local-label 99 via 172.16.0.1 next-hop-table 2
+
+#. per-VRF label scheme
+
+   .. code-block:: console
+
+      $ mpls local-label 99 via ip4-lookup-in-table 2
+
+MPLS Tunnels
+^^^^^^^^^^^^
+
+MPLS tunnels are unidirectional and can impose a stack of labels. They
+are 'normal' interfaces and thus can be used, for example, as the
+target for IP routes and L2 cross-connects. To construct a tunnel:
+
+.. code-block:: console
+
+   $ mpls tunnel add via 10.10.10.10 GigEthernet0/0/0 out-labels 33 44 55
+
+and to then have that created tunnel to perform ECMP:
+
+.. code-block:: console
+
+   $ mpls tunnel add mpls-tunnel0 via 10.10.10.11 GigEthernet0/0/0 out-labels 66 77 88
+
+use
+
+.. code-block:: console
+
+   $ sh mpls tunnel [X]
+
+to see the monster you have created.
+
+An MPLS tunnel interface is an interface like any other and now ready
+for use with the usual set of interface commands, e.g.:
+
+.. code-block:: console
+
+   $ set interface state mpls-tunnel0 up
+   $ set interface ip address mpls-tunnel0 192.168.1.1/30
+   $ ip route 1.1.1.1/32 via mpls-tunnel0