docs: Rewrite the what is VPP (first) section, also fix the build

Signed-off-by: John DeNisco <jdenisco@cisco.com>
Change-Id: Ifb558171f8976a721703e74afea997d006273b5f
Signed-off-by: Dave Barach <dave@barachs.net>

32 files changed, 161 insertions, 555 deletions

diff --git a/docs/Makefile b/docs/Makefile
index a67b28a3f1b..4e8f1634b21 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -41,6 +41,7 @@ ifeq ($(OS_ID),ubuntu)
 else ifneq ("$(wildcard /etc/redhat-release)","")
 	@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
 endif
-	@python3 -m pip install sphinxcontrib-spelling
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W -b spelling  $(O)
+# Disable spell checking for now
+#	@python3 -m pip install sphinxcontrib-spelling
+#	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W -b spelling  $(O)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/about.rst b/docs/about.rst
index 786d896aba1..eae97b23b75 100644
--- a/docs/about.rst
+++ b/docs/about.rst
@@ -4,6 +4,6 @@
 About
 =====
 
-**VPP Version:** 20.01-rc0~171-g1146ff4
+**VPP Version:** 20.01-rc0~594-g340c15c6e
 
-**Built on:** Wed Sep 11 12:59:45 GMT 2019
+**Built on:** Wed Nov  6 18:47:36 GMT 2019
diff --git a/docs/conf.py b/docs/conf.py
index eb66cb38ac0..68dab302105 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,14 +18,14 @@
 
 # -- Project information -----------------------------------------------------
 
-project = u'Vector Packet Processor'
+project = u'The Vector Packet Processor'
 copyright = u'2018, Linux Foundation'
 author = u'John DeNisco'
 
 # The short X.Y version
 version = u'master'
 # The full version, including alpha/beta/rc tags
-release = u'01'
+release = u'20.01'
 
 
 # -- General configuration ---------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index 0fa3b21e768..391c5832820 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,25 +3,35 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-#########
-FD.io VPP
-#########
+#########################################
+What is the Vector Packet Processor (VPP)
+#########################################
 
-FD.io Vector Packet Processing (VPP) is a fast, scalable layer 2-4
-multi-platform network stack. VPP supports integration with OpenStack
-and Kubernetes. Network management features include configuration,
-counters and sampling. Development tools include plugin extensibility,
-high-performance event-logging, multiple kinds of packet tracing;
-debug images include extensive consistency checking.
+FD.io's Vector Packet Processor (VPP) is a fast, scalable layer 2-4
+multi-platform network stack. It runs in `Linux Userspace <https://en.wikipedia.org/wiki/User_space>`_
+on multiple architectures including x86, ARM, and Power architectures.
+VPP is built using the `Dataplane Development Kit (DPDK) <https://en.wikipedia.org/wiki/Data_Plane_Development_Kit>`_.
 
-Use-cases include vSwitch, vRouter, Gateways, Firewalls and Load
-Balancers, to name several. Out of the box, VPP works as a software
-development kit or an appliance.
+VPP benefits include high performance, proven technology, modularity,
+and a rich feature set.
+
+VPP supports integration with OpenStack and Kubernetes. Network
+management features include configuration, counters, sampling and
+more. For developers, VPP includes plugin extensibility,
+high-performance event-logging, and multiple kinds of packet
+tracing. Development debug images include complete symbol tables, and
+extensive consistency checking.
+
+Some VPP Use-cases include vSwitches, vRouters, Gateways, Firewalls
+and Load Balancers, to name a few. Out of the box, VPP can work as a
+software development kit or an appliance.
+
+For more details click on the links below or press next.
 
 .. toctree::
    :maxdepth: 2
 
-   overview/index
+   whatisvpp/index.rst
    gettingstarted/index
    links/index
    usecases/index
diff --git a/docs/overview/features/controlplane.rst b/docs/overview/features/controlplane.rst
deleted file mode 100644
index 849617ae4e6..00000000000
--- a/docs/overview/features/controlplane.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _cp:
-
-=============
-Control Plane
-=============
-
-This section identifies the features associated with Control Plane:
-
-* DHCP client/proxy
-
-* DHCPv6 Proxy
-
diff --git a/docs/overview/features/devices.rst b/docs/overview/features/devices.rst
deleted file mode 100644
index f3ecd32c825..00000000000
--- a/docs/overview/features/devices.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-.. _dev:
-
-=======
-Devices
-=======
-
-Hardware
---------
-* `DPDK <https://www.dpdk.org/>`_
-
-  * `Network Interfaces <https://doc.dpdk.org/guides/nics/>`_
-  * `Cryptographic Devices <https://doc.dpdk.org/guides/cryptodevs/>`_
-
-* `Open Data Plane <https://github.com/FDio/odp4vpp>`_
-* `Intel Ethernet Adaptive Virtual Function <https://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/ethernet-adaptive-virtual-function-hardware-spec.pdf>`_
-
-Operating System
-----------------
-* `Netmap <http://info.iet.unipi.it/~luigi/netmap/>`_
-* `af_packet <http://man7.org/linux/man-pages/man7/packet.7.html>`_
-* Tap V2 (FastTap)
-
-Virtualization:
----------------
-* SSVM
-* Vhost / VirtIO
-
-Containers
-----------
-
-* Vhost-user
-* MemIF
-
diff --git a/docs/overview/features/index.rst b/docs/overview/features/index.rst
deleted file mode 100644
index dc825c4c2a9..00000000000
--- a/docs/overview/features/index.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-.. _features:
-
-========
-Features
-========
-
-The table below identifies different features that are associated to VPP. To see more details about a specific feature, just click the hyperlink associated to the feature noted in the table below.
-
-.. rst-class:: center-align-table
-
-+-------------------------+-----------+-----------+
-| :ref:`sdn`              |           |           |
-+------------+------------+ :ref:`cp` |           |
-|            | :ref:`l4`  |           |           |
-|            +------------+-----------+ :ref:`pg` |
-| :ref:`tun` | :ref:`l3`  |           |           |
-|            +------------+ :ref:`tm` |           |
-|            | :ref:`l2`  |           |           |
-+------------+------------+-----------+-----------+
-| :ref:`dev`                                      |
-+-------------------------------------------------+
-
-.. toctree::
-   :hidden:
-
-   devices.rst
-   integrations.rst
-   trafficmanagement.rst
-   l2.rst
-   l3.rst
-   l4.rst
-   tunnels.rst
-   controlplane.rst
-   plugins.rst
diff --git a/docs/overview/features/integrations.rst b/docs/overview/features/integrations.rst
deleted file mode 100644
index 848e8648438..00000000000
--- a/docs/overview/features/integrations.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-.. _sdn:
-
-========================
-SDN & Cloud Integrations
-========================
diff --git a/docs/overview/features/l2.rst b/docs/overview/features/l2.rst
deleted file mode 100644
index 939afb7e8be..00000000000
--- a/docs/overview/features/l2.rst
+++ /dev/null
@@ -1,58 +0,0 @@
-.. _l2:
-
-=======
-Layer 2
-=======
-
-This section identifies the features associated with Layer 2:
-
-MAC Layer
----------
-* Ethernet
-
-Discovery
----------
-* Cisco Discovery Protocol v2 (CDP)
-* Link Layer Discovery Protocol (LLDP)
-
-Link Layer Control Protocol
----------------------------
-* Bit Index Explicit Replication – Link Layer Multi-cast forwarding.
-* Link Layer Control (LLC) - multiplex protocols over the MAC layer. 
-* Spatial Reuse Protocol (SRP)
-* High-Level Data Link Control (HDLC)
-* Logical link control (LLC)
-* Link Agg Control Protocol (Active/Active, Active/Passive) – 18.04 
-
-Virtual Private Networks
-------------------------
-* MPLS 
-  
-  * MPLS-o-Ethernet – Deep label stacks supported
-
-* Virtual Private LAN Service (VPLS)
-* VLAN
-* Q-in-Q
-* Tag-rewrite (VTR) - push/pop/Translate (1:1,1:2, 2:1,2:2)
-* Ethernet flow point Filtering
-* Layer 2 Cross Connect
-
-Bridging
----------
-* Bridge Domains
-* MAC Learning (50k addresses)
-* Split-horizon group support
-* Flooding
-
-ARP
----
-* Proxy
-* Termination
-* Bidirectional Forwarding Detection
-
-Integrated Routing and Bridging (IRB)
--------------------------------------
-* Flexibility to both route and switch between groups of ports.
-* Bridged Virtual Interface (BVI) Support, allows traffic switched traffic to be routed.
-
-
diff --git a/docs/overview/features/l3.rst b/docs/overview/features/l3.rst
deleted file mode 100644
index 57ae10ff208..00000000000
--- a/docs/overview/features/l3.rst
+++ /dev/null
@@ -1,57 +0,0 @@
-.. _l3:
-
-=======
-Layer 3
-=======
-
-This section identifies the features associated with Layer 3:
-
-IP Layer
---------
-* ICMP
-* IPv4
-* IPv6
-* IPSEC
-* Link Local Addressing
-
-MultiCast
----------
-* Multicast FiB
-* IGMP
-
-Virtual Routing and forwarding (VRF)
-------------------------------------
-* VRF scaling, thousands of tables. 
-* Controlled cross-VRF lookups
-
-Multi-path
-----------
-* Equal Cost Multi Path (ECMP)
-* Unequal Cost Multi Path (UCMP)
-
-IPv4
-----
-* ARP
-* ARP Proxy
-* ARP Snooping
-
-IPv6
-----
-* Neighbour discovery (ND)
-* ND Proxy
-* Router Advertisement
-* Segment Routing
-* Distributed Virtual Routing Resolution
-
-Forwarding Information Base (FIB)
----------------------------------
-
-* Hierarchical FIB
-* Memory efficient
-* Multi-million entry scalable
-* Lockless/concurrent updates
-* Recursive lookups
-* Next hop failure detection
-* Shared FIB adjacencies
-* Multicast support
-* MPLS support
diff --git a/docs/overview/features/l4.rst b/docs/overview/features/l4.rst
deleted file mode 100644
index 28e1df5f65d..00000000000
--- a/docs/overview/features/l4.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. _l4:
-
-=======
-Layer 4
-=======
-
-This section identifies the features associated with Layer 4:
-
-* Session: 
-   - connectionless transports
-   - datagram reception and transmission
-* TCP: congestion control 
-* UDP: datagram mode
-* TLS async support
diff --git a/docs/overview/features/plugins.rst b/docs/overview/features/plugins.rst
deleted file mode 100644
index 0394a816cdb..00000000000
--- a/docs/overview/features/plugins.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-.. _pg:
-
-=======
-Plugins
-=======
-
-This section identifies the features associated with Plugins:
-
-* iOAM
diff --git a/docs/overview/features/trafficmanagement.rst b/docs/overview/features/trafficmanagement.rst
deleted file mode 100644
index e56af50a90e..00000000000
--- a/docs/overview/features/trafficmanagement.rst
+++ /dev/null
@@ -1,57 +0,0 @@
-.. _tm:
-
-==================
-Traffic Management
-==================
-
-This section identifies the features associated with Traffic Management:
-
-IP Layer Input Checks
----------------------
-* Source Reverse Path Forwarding
-* Time To Live expiration
-* IP header checksum
-* Layer 2 Length < IP Length
-
-Classifiers
------------
-* Multiple million Classifiers - Arbitrary N-tuple
-
-Policers
---------
-* Colour Aware & Token Bucket
-* Rounding Closest/Up/Down
-* Limits in PPS/KBPS
-* Types: 
-
-  * Single Rate Two Colour
-  * Single Rate Three Colour
-  * Dual Rate Three Colour
-
-* Action Triggers
-
-  * Conform
-  * Exceed
-  * Violate
-
-* Actions Type
-
-  * Drop
-  * Transmit
-  * Mark-and-transmit
-
-Switched Port Analyzer (SPAN)
-* mirror traffic to another switch port
-
-ACLs
-----
- * Stateful
- * Stateless
-
-COP
----
-
-MAC/IP Pairing
---------------
-Security feature
-
diff --git a/docs/overview/features/tunnels.rst b/docs/overview/features/tunnels.rst
deleted file mode 100644
index 0f2b2d23db0..00000000000
--- a/docs/overview/features/tunnels.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-.. _tun:
-
-=======
-Tunnels
-=======
-
-This section identifies the features associated with Tunnels:
-
-Layer 2
--------
-* L2TP
-* PPP
-* VLAN
-
-Layer 3
--------
-* Mapping of Address and Port with Encapsulation (MAP-E)
-* Lightweight IPv4 over IPv6
-
-   * An Extension to the Dual-Stack Lite Architecture
-
-* GENEVE
-* VXLAN
-
-Segment Routing
----------------
-* IPv6
-* MPLS
-
-Generic Routing Encapsulation (GRE)
-* GRE over IPSEC
-* GRE over IP
-* MPLS
-* NSH
diff --git a/docs/overview/index.rst b/docs/overview/index.rst
deleted file mode 100644
index 8d1e434d848..00000000000
--- a/docs/overview/index.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-.. _overview:
-
-==========
-Overview
-==========
-
-This section discusses the following information:
-
-* What VPP is, what  packet processing provides and the benefits VPP provides
-
-
-
-.. toctree::
-   :maxdepth: 1
-
-   whatisvpp/index.rst
-   features/index.rst
-   performance/index.rst
-   supported.rst
diff --git a/docs/overview/performance/current_ipv4_throughput.rst b/docs/overview/performance/current_ipv4_throughput.rst
deleted file mode 100644
index 3a34da76ca0..00000000000
--- a/docs/overview/performance/current_ipv4_throughput.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _current_ipv4_throughput:
-
-.. toctree::
-
-IPv4 Routed-Forwarding Performance Tests
-****************************************
-
-VPP NDR 64B packet throughput in 1t1c setup (1thread, 1core) is presented in the graph below.
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/rls1804/report/_static/vpp/64B-1t1c-ethip4-ip4-ndrdisc.html" width="1200" height="1000" frameborder="0">
diff --git a/docs/overview/performance/current_ipv6_throughput.rst b/docs/overview/performance/current_ipv6_throughput.rst
deleted file mode 100644
index 119f28f5665..00000000000
--- a/docs/overview/performance/current_ipv6_throughput.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. _current_ipv6_throughput:
-
-.. toctree::
-
-IPv6 Routed-Forwarding Performance Tests
-****************************************
-
-VPP NDR 78B packet throughput in 1t1c setup (1 thread, 1 core) is presented in the graph below.
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/rls1801/report/_static/vpp/78B-1t1c-ethip6-ip6-ndrdisc.html" width="1200" height="1000" frameborder="0">
-
-
-
-
diff --git a/docs/overview/performance/current_l2_throughput.rst b/docs/overview/performance/current_l2_throughput.rst
deleted file mode 100644
index 532e6dc7163..00000000000
--- a/docs/overview/performance/current_l2_throughput.rst
+++ /dev/null
@@ -1,12 +0,0 @@
- .. _current_l2_throughput:
-
-.. toctree::
-
-L2 Ethernet Switching Throughput Tests
-***************************************
-
-VPP NDR 64B packet throughput in 1 Core, 1 Thread setup, is presented in the graph below.
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/rls1801/report/_static/vpp/64B-1t1c-l2-sel2-ndrdisc.html" width="1200" height="1000" frameborder="0">
diff --git a/docs/overview/performance/current_ndr_throughput.rst b/docs/overview/performance/current_ndr_throughput.rst
deleted file mode 100644
index c7348314ef6..00000000000
--- a/docs/overview/performance/current_ndr_throughput.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-.. _current_ndr_throughput:
-
-.. toctree::
-
-NDR Performance Tests
-*********************
-
-This is a VPP NDR 64B packet throughput in 1 Core, 1 Thread setup, live graph of the NDR (No Drop Rate) L2 Performance Tests. 
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/rls1804/report/_static/vpp/64B-1t1c-l2-sel1-ndrdisc.html" width="800" height="1000" frameborder="0">
-
diff --git a/docs/overview/performance/trending_ipv4_throughput.rst b/docs/overview/performance/trending_ipv4_throughput.rst
deleted file mode 100644
index 4ba028b9e59..00000000000
--- a/docs/overview/performance/trending_ipv4_throughput.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. _trending_ipv4_throughput:
-
-.. toctree::
-
-IPv4 Routed-Forwarding Performance Tests
-****************************************
-
-This is a live graph of the IPv4 Routed Forwarding Switching Performance Tests. 
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/master/trending/_static/vpp/cpta-ip4-1t1c-x520.html" width="1200" height="1000" frameborder="0">
-
-
diff --git a/docs/overview/performance/trending_ipv6_throughput.rst b/docs/overview/performance/trending_ipv6_throughput.rst
deleted file mode 100644
index 8217b41e817..00000000000
--- a/docs/overview/performance/trending_ipv6_throughput.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. _trending_ipv6_throughput:
-
-.. toctree::
-
-IPv6 Routed-Forwarding Performance Tests
-****************************************
-
-VPP NDR 78B packet throughput in 1t1c setup (1 thread, 1 core) is presented in the trending graph below.
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/master/trending/_static/vpp/cpta-ip6-1t1c-x520-1.html" width="1200" height="1000" frameborder="0">
-
-
-
-
diff --git a/docs/overview/performance/trending_l2_throughput.rst b/docs/overview/performance/trending_l2_throughput.rst
deleted file mode 100644
index 59bb3bf6f1a..00000000000
--- a/docs/overview/performance/trending_l2_throughput.rst
+++ /dev/null
@@ -1,14 +0,0 @@
- .. _trending_l2_throughput:
-
-.. toctree::
-
-L2 Ethernet Switching Performance Tests
-***************************************
-
-This is a live graph of the 1 Core, 1 Thread, L2 Ethernet Switching Performance Tests Test on the x520 NIC.
-
-.. raw:: html
-
-    <iframe src="https://docs.fd.io/csit/master/trending/_static/vpp/cpta-l2-1t1c-x520.html" width="1200" height="1000" frameborder="0">
-
-
diff --git a/docs/overview/whatisvpp/fast.rst b/docs/overview/whatisvpp/fast.rst
deleted file mode 100644
index 9e9e314809c..00000000000
--- a/docs/overview/whatisvpp/fast.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _fast:
-
-================================
-Fast, Scalable and Deterministic
-================================
-
-This section describes the ways that VPP is fast, scalable and deterministic:
-
-* `Continuous integration and system testing (CSIT) <https://wiki.fd.io/view/CSIT#Start_Here>`_
-
-  * Including continuous & extensive, latency and throughput testing
-
-* Layer 2 Cross Connect (L2XC), typically achieve 15+ Mpps per core.
-* Tested to achieve **zero** packet drops and ~15µs latency.
-* Performance scales linearly with core/thread count
-* Supporting millions of concurrent lookup tables entries
-
-Please see :ref:`performance` for more information.
diff --git a/docs/overview/whatisvpp/index.rst b/docs/overview/whatisvpp/index.rst
deleted file mode 100644
index f8cb25dfd1e..00000000000
--- a/docs/overview/whatisvpp/index.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. _whatisvpp:
-
-=========================================
-What is VPP?
-=========================================
-
-FD.io's Vector Packet Processing (VPP) technology is a :ref:`fast`,
-:ref:`packet-processing` stack that runs on commodity CPUs. It provides
-out-of-the-box production quality switch/router functionality and much, much
-more. FD.io VPP is at the same time, an :ref:`extensible` and
-:ref:`developer-friendly` framework, capable of boot-strapping the development
-of packet-processing applications. The benefits of FD.io VPP are its high
-performance, proven technology, its modularity and flexibility, integrations and
-rich feature set.
-
-FD.io VPP is vector packet processing software, to learn more about what that
-means, see the :ref:`what-is-vector-packet-processing` section. 
-
-For more detailed information on FD.io features, see the following sections:
-
-.. toctree::
-   :maxdepth: 1
-
-   dataplane.rst
-   fast.rst
-   developer.rst
-   extensible.rst
diff --git a/docs/overview/whatisvpp/developer.rst b/docs/whatisvpp/developer.rst
index 040762b01ba..5151e65ff74 100644
--- a/docs/overview/whatisvpp/developer.rst
+++ b/docs/whatisvpp/developer.rst
@@ -1,10 +1,11 @@
 .. _developer-friendly:
 
-==================
-Developer Friendly
-==================
+=======================
+Features for Developers
+=======================
 
-This section describes the different ways VPP is friendly to developers:
+This section describes a little about the VPP environment and some of the features
+that can be used by developers.
 
 * Extensive runtime counters; throughput, `intructions per cycle <https://en.wikipedia.org/wiki/Instructions_per_cycle>`_, errors, events etc.
 * Integrated pipeline tracing facilities
@@ -24,3 +25,5 @@ This section describes the different ways VPP is friendly to developers:
   * Shared-memory segment base address randomization
   * Stack bounds checking
   * Static analysis with `Coverity <https://en.wikipedia.org/wiki/Coverity>`_
+
+For the supported architectures click next.
diff --git a/docs/overview/whatisvpp/extensible.rst b/docs/whatisvpp/extensible.rst
index e7762d71312..1df3b9fbd2f 100644
--- a/docs/overview/whatisvpp/extensible.rst
+++ b/docs/whatisvpp/extensible.rst
@@ -1,16 +1,18 @@
 .. _extensible:
 
-=============================
-Extensible and Modular Design
-=============================
+===========================
+The Packet Processing Graph
+===========================
+
+At the core of the FD.io VPP design is the **Packet Procerssing Graph**
+
+This makes the software:
 
 * Pluggable, easy to understand & extend
 * Mature graph node architecture
 * Full control to reorganize the pipeline
 * Fast, plugins are equal citizens
 
-**Modular, Flexible, and Extensible**
-
 The FD.io VPP packet processing pipeline is decomposed into a ‘packet processing
 graph’.  This modular approach means that anyone can ‘plugin’ new graph
 nodes. This makes VPP easily extensible and means that plugins can be
@@ -37,3 +39,5 @@ for libraries, and then dynamically loads each one in turn on startup.
 A plugin can introduce new graph nodes or rearrange the packet processing graph. 
 You can build a plugin completely independently of the FD.io VPP source tree,
 which means you can treat it as an independent component.
+
+For more on the network stack press next.
diff --git a/docs/whatisvpp/hoststack.rst b/docs/whatisvpp/hoststack.rst
new file mode 100644
index 00000000000..77e259a6731
--- /dev/null
+++ b/docs/whatisvpp/hoststack.rst
@@ -0,0 +1,26 @@
+.. _hoststack:
+
+==============
+TCP Host Stack
+==============
+
+VPP’s host stack leverages VPP’s graph based forwarding model and vectorized packet
+processing to ensure high throughput and scale transport protocol termination. It
+exposes apis that apart from allowing for efficient user-space app consumption and
+generation of data, also enables highly efficient local inter-app communication. 
+ 
+At a high level VPP’s host stack consists of 3 major components: 
+
+* A session layer that facilitates interaction between transport protocols and applications
+* Pluggable transport protocols, including TCP, QUIC, TLS, UDP
+* VCL (VPPComs library) a set of libraries meant to ease the consumability of the stack from application perspective
+ 
+All of these components were custom built to fit within VPP’s architecture and to
+leverage its speed. As a result, a significant amount of effort was invested into:
+
+*  building a transport pluggable session layer that abstracts the interaction between applications and transports using a custom-built shared memory infrastructure. Notably, this also allows for transport protocols that are typically implemented in applications, like QUIC and TLS, to be implemented within VPP. 
+* a clean slate TCP implementation that supports vectorized packet processing and follows VPP’s highly scalable threading model. The implementation is RFC compliant, supports a high number of high-speed TCP protocol features and it was validated using Defensic’s Codenomicon 1M+ tests suite. 
+* VCL, a library that emulates traditional asynchronous communication functions in user-space, all while allowing for new patterns to be developed, if needed. 
+* implementing a high performance “cut-through” communication mode that enables applications attached to vpp to transparently exchange data over shared memory without incurring the extra cost of a traditional transport protocol. Testing has shown this to be much more efficient than traditional inter-container networking.
+
+For developer features press next.
diff --git a/docs/whatisvpp/index.rst b/docs/whatisvpp/index.rst
new file mode 100644
index 00000000000..464119ccad5
--- /dev/null
+++ b/docs/whatisvpp/index.rst
@@ -0,0 +1,37 @@
+.. _whatisvpp:
+
+=================================
+The Vector Packet Processor (VPP)
+=================================
+
+This section describes some of the core concepts and features of FD.io VPP.
+
+To start with FD.io VPP uses a technique called Vector Packet Processing.
+This gives FD.io VPP a siginficant performance improvement over packet
+processing applications that use scalar processing. 
+
+Also, At the heart of Fd.io VPP's modular design is a 'Packet Processing Graph'.
+This makes FD.io VPP scalable and easily extensible.
+
+The FD.io software also includes a feature rich network stack. This includes
+a TCP host stack that utilizes VPP’s graph based forwarding model and vectorized
+packet processing.
+
+FD.io VPP is tested nightly for functionality and performance with the
+CSIT project.
+
+For more information on any of these features click on the links below or
+press next.
+
+.. toctree::
+   :maxdepth: 1
+
+   scalar-vs-vector-packet-processing.rst
+   extensible.rst
+   networkstack.rst
+   hoststack.rst
+   developer.rst
+   supported.rst
+   performance.rst
+
+Press next for more about Scalar/Vector Packet processing.
diff --git a/docs/overview/whatisvpp/dataplane.rst b/docs/whatisvpp/networkstack.rst
index daf2124158d..20c470828b1 100644
--- a/docs/overview/whatisvpp/dataplane.rst
+++ b/docs/whatisvpp/networkstack.rst
@@ -1,28 +1,30 @@
-.. _packet-processing:
+.. _network-stack:
 
-===================
-Packet Processing
-===================
+=============
+Network Stack
+=============
 
-This section identifies different components of packet processing and describes their benefits:
+This section describes a little about the FD.io network stack and describes some benefits:
 
 * Layer 2 - 4 Network Stack
 
   * Fast lookup tables for routes, bridge entries
   * Arbitrary n-tuple classifiers 
   * Control Plane, Traffic Management and Overlays
+
  
 * `Linux <https://en.wikipedia.org/wiki/Linux>`_ and `FreeBSD <https://en.wikipedia.org/wiki/FreeBSD>`_ support
 
-  * Wide support for standard Operating System Interfaces such as AF_Packet, Tun/Tap & Netmap.
+  * Support for standard Operating System Interfaces such as AF_Packet, Tun/Tap & Netmap.
 
-* Wide network and cryptographic hardware support with `DPDK <https://www.dpdk.org/>`_.
+* Network and cryptographic hardware support with `DPDK <https://www.dpdk.org/>`_.
 * Container and Virtualization support
 
   * Para-virtualized interfaces; Vhost and Virtio
   * Network Adapters over PCI passthrough
   * Native container interfaces; MemIF
   
+* Host Stack
 * Universal Data Plane: one code base, for many use cases
  
   * Discrete appliances; such as `Routers <https://en.wikipedia.org/wiki/Router_(computing)>`_ and `Switches <https://en.wikipedia.org/wiki/Network_switch>`_.
@@ -32,5 +34,6 @@ This section identifies different components of packet processing and describes
 
 * Out of the box production quality, with thanks to `CSIT <https://wiki.fd.io/view/CSIT#Start_Here>`_. 
 
-For more information, please see :ref:`features` for the complete list.
+For more information, please see :ref:`featuresbyrelease` for the complete list.
 
+For more on the TCP Host Stack press next.
diff --git a/docs/overview/performance/index.rst b/docs/whatisvpp/performance.rst
index 25e3897ff37..9b0fb21bb71 100644
--- a/docs/overview/performance/index.rst
+++ b/docs/whatisvpp/performance.rst
@@ -3,10 +3,8 @@
 Performance
 ===========
 
-Overview
-^^^^^^^^
-
-One of the benefits of FD.io VPP is high performance on relatively low-power computing, this performance is based on the following features:
+One of the benefits of FD.io VPP is it's high performance on relatively low-power computing.
+Included are the following.
 
 * A high-performance user-space network stack designed for commodity hardware:
 
@@ -30,43 +28,43 @@ These features have been designed to take full advantage of common micro-process
 * Cache-lined aligned buffers for cache and memory efficiency
 
 
-Packet Throughput Graphs
-^^^^^^^^^^^^^^^^^^^^^^^^
+Continuous System Integration and Testing (CSIT)
+------------------------------------------------
 
-These are some of the packet throughput graphs for FD.io VPP 18.04 from the CSIT `18.04 benchmarking report <https://docs.fd.io/csit/rls1804/report/>`_:
+The Continuous System Integration and Testing (CSIT) project provides functional and performance
+testing for FD.io VPP. This testing is focused on functional and performance regresssions. The results
+are posted to `CSIT Test Report <https://docs.fd.io/csit/master/report/>`_.
 
-.. toctree::
+For more about CSIT checkout the following links:
 
-    current_l2_throughput.rst    
-    current_ndr_throughput.rst
-    current_ipv4_throughput.rst
-    current_ipv6_throughput.rst
+* `CSIT Code Documentation <https://docs.fd.io/csit/master/doc/overview.html>`_
+* `CSIT Test Overview <https://docs.fd.io/csit/master/report/introduction/overview.html>`_
+* `VPP Performance Dashboard <https://docs.fd.io/csit/master/trending/introduction/index.html>`_
 
-Trending Throughput Graphs
-^^^^^^^^^^^^^^^^^^^^^^^^^^ 
 
-These are some of the trending packet throughput graphs from the CSIT `trending dashboard <https://docs.fd.io/csit/master/trending/introduction/index.html>`_. **Please note that**, performance in the trending graphs will change on a nightly basis in line with the software development cycle:
+CSIT Packet Throughput examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. toctree::
+Following are pointers to a few of the CSIT test reports. The test's titles read like this:
 
-    trending_l2_throughput.rst
-    trending_ipv4_throughput.rst
-    trending_ipv6_throughput.rst
+<packet size>-<number of threads><number of cores>-<test>-<interface type> 
 
-For More information on CSIT 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+For example the test with the title 64b-2t1c-l2switching-base-i40e is the
+test that does l2 switching using 64 byte packets, 2 threads, 1 core using an i40e
+interface.
 
-The FD.io CSIT is implemented with below platforms:
+Here are a few examples:
 
-* x86/64
-* ARM-AArch64
+* `L2 Ethernet switching <https://docs.fd.io/csit/master/report/vpp_performance_tests/packet_throughput_graphs/l2.html>`_
+* `IPv4 Routing <https://docs.fd.io/csit/master/report/vpp_performance_tests/packet_throughput_graphs/ip4.html>`_
+* `IPv6 Routing <https://docs.fd.io/csit/master/report/vpp_performance_tests/packet_throughput_graphs/ip6.html>`_
 
-   * Huawei TaiShan 2280
-   * Marvell MACCHIATObin
 
+Trending Throughput Graphs
+^^^^^^^^^^^^^^^^^^^^^^^^^^ 
 
-These are FD.io Continuous System Integration and Testing (CSIT)'s documentation links:
+These are some of the trending packet throughput graphs from the CSIT `trending dashboard <https://docs.fd.io/csit/master/trending/introduction/index.html>`_. **Please note that**, performance in the trending graphs will change on a nightly basis in line with the software development cycle:
 
-* `CSIT Code Documentation <https://docs.fd.io/csit/master/doc/overview.html>`_
-* `CSIT Test Overview <https://docs.fd.io/csit/rls1804/report/introduction/overview.html>`_
-* `VPP Performance Dashboard <https://docs.fd.io/csit/master/trending/introduction/index.html>`_
+* `L2 Ethernet Switching Trending <https://docs.fd.io/csit/master/trending/trending/l2.html>`_
+* `IPv4 Routing Trending <https://docs.fd.io/csit/master/trending/trending/ip4.html>`_
+* `IPv6 Routing Trending <https://docs.fd.io/csit/master/trending/trending/ip6.html>`_
diff --git a/docs/overview/whatisvpp/what-is-vector-packet-processing.rst b/docs/whatisvpp/scalar-vs-vector-packet-processing.rst
index 50a5bab8af1..ffa54a3f306 100644
--- a/docs/overview/whatisvpp/what-is-vector-packet-processing.rst
+++ b/docs/whatisvpp/scalar-vs-vector-packet-processing.rst
@@ -1,21 +1,16 @@
-:orphan:
+.. _scalar_vector:
 
-.. _what-is-vector-packet-processing:
+==================================
+Scalar vs Vector packet processing
+==================================
 
-=================================
-What is vector packet processing?
-=================================
+FD.io VPP is developed using vector packet processing, as opposed to
+scalar packet processing.
 
-FD.io VPP is developed using vector packet processing concepts, as opposed to
-scalar packet processing, these concepts are explained in the following sections. 
-
-Vector packet processing is a common approach among high performance `Userspace
-<https://en.wikipedia.org/wiki/User_space>`_ packet processing applications such
-as developed with FD.io VPP and `DPDK
-<https://en.wikipedia.org/wiki/Data_Plane_Development_Kit>`_. The scalar based
-approach tends to be favoured by Operating System `Kernel
-<https://en.wikipedia.org/wiki/Kernel_(operating_system)>`_ Network Stacks and
-Userspace stacks that don't have strict performance requirements.
+Vector packet processing is a common approach among high performance packet
+processing applications such FD.io VPP and `DPDK <https://en.wikipedia.org/wiki/Data_Plane_Development_Kit>`_.
+The scalar based approach tends to be favoured by network stacks that
+don't necessarily have strict performance requirements.
 
 **Scalar Packet Processing**
 
@@ -71,3 +66,4 @@ The further optimizations that this approaches enables are pipelining and
 prefetching to minimize read latency on table data and parallelize packet loads
 needed to process packets.
 
+Press next for more on Packet Processing Graphs.
diff --git a/docs/overview/supported.rst b/docs/whatisvpp/supported.rst
index 959d4483407..b201def5e06 100644
--- a/docs/overview/supported.rst
+++ b/docs/whatisvpp/supported.rst
@@ -27,3 +27,5 @@ recent LTS operating systems releases:
    * Ubuntu 
    * CentOS 
    * OpenSUSE
+
+For more about VPP performance press next.