docs: Incororate Scott's overall review
Change-Id: Ic70a62e17891fa9291a5274400ae89f1d6194b6e Signed-off-by: John DeNisco <jdenisco@cisco.com>
This commit is contained in:

committed by
Neale Ranns

parent
5c482a9de3
commit
c64ba6dc6a
Binary file not shown.
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 43 KiB |
@ -4,6 +4,14 @@
|
||||
Developers
|
||||
##########
|
||||
|
||||
The Developers section covers the following areas:
|
||||
|
||||
* Building VPP
|
||||
* Describes the components of the four VPP layers
|
||||
* How to Create, Add, Enable/Disable features
|
||||
* Discusses different aspects of Bounded-index Extensible Hashing (bihash)
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
@ -1,8 +1,31 @@
|
||||
.. _gettingstarted:
|
||||
|
||||
###############
|
||||
Getting Started
|
||||
###############
|
||||
######################
|
||||
Getting Started Guides
|
||||
######################
|
||||
|
||||
The Getting Started Guide is comprised of several different sections; a section for Users, another for Developers, and a section for Writing VPP documentation.
|
||||
|
||||
The Users section covers basic VPP installation and configuration operations. This section covers the following areas:
|
||||
|
||||
* Describes the different types of VPP packages
|
||||
* Describes how to install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE).
|
||||
* Explains how to configure, then use VPP.
|
||||
* Explains how to use the Configuration Utility.
|
||||
|
||||
The Developers section covers the following areas:
|
||||
|
||||
* Building VPP
|
||||
* Describes the components of the four VPP layers
|
||||
* How to Create, Add, Enable/Disable features
|
||||
* Discusses different aspects of Bounded-index Extensible Hashing (bihash)
|
||||
|
||||
The Writing VPP Documentation section covers the following topics:
|
||||
|
||||
* How to build VPP documents
|
||||
* How to push your changes to the VPP Docs Repository
|
||||
* Identifies the different styles associated to reStructuredText
|
||||
* Identifies the different styles associated to Markdown
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
@ -3,11 +3,12 @@
|
||||
Huge Pages
|
||||
----------
|
||||
|
||||
VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage
|
||||
settings when VPP is installed. By default, VPP sets the number of hugepages on
|
||||
a system to 1024 2M hugepages (1G hugepages are no longer supported). This is
|
||||
the number of hugepages on the system, not just used by VPP. When VPP is
|
||||
installed, the following file is copied to the system and used to apply the
|
||||
VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage settings
|
||||
when VPP is installed. By default, VPP sets the number of hugepages on a system
|
||||
to 1024 2M hugepages (1G hugepages are no longer supported). This is the number
|
||||
of hugepages on the system, not just used by VPP.
|
||||
|
||||
When VPP is installed, the following file is copied to the system and used to apply the
|
||||
hugepage settings on VPP installation and system reboot:
|
||||
|
||||
.. code-block:: console
|
||||
|
@ -1,10 +1,10 @@
|
||||
.. _configuring:
|
||||
|
||||
Configuring VPP
|
||||
===============
|
||||
==================
|
||||
|
||||
There is some basic configuration that is need to run FD.io VPP. This section
|
||||
will describe some basic configuration.
|
||||
There is some basic configuration that is needed to run FD.io VPP. This section
|
||||
describes the basic configuration:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
@ -10,9 +10,10 @@ VPP Configuration File - 'startup.conf'
|
||||
|
||||
|
||||
After a successful installation, VPP installs a startup config file named
|
||||
*'startup.conf'* in the *'/etc/vpp/'*' directory. This file can be tailored to
|
||||
*startup.conf* in the */etc/vpp/* directory. This file can be tailored to
|
||||
make VPP run as desired, but contains default values for typical installations.
|
||||
Below are more details about this file and parameter and values it contains.
|
||||
|
||||
Below are more details about this file and the parameters and values it contains.
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
@ -4,11 +4,11 @@
|
||||
List/Install/Uninstall VPP
|
||||
**************************
|
||||
|
||||
With option "4" the user can list, install or uninstall the FD.io VPP packages. If there
|
||||
are packages already installed, the packages will be listed and then the user will be asked
|
||||
if the packages should be uninstalled. If no packages are installed the user will be asked if
|
||||
the FD.io packages should be installed. The packages installed will be the latest released
|
||||
packages.
|
||||
With command option "4" the user can list, install, or uninstall the FD.io VPP
|
||||
packages. If there are packages already installed, then the packages will be listed
|
||||
and the user will be asked if the packages should be uninstalled. If no packages are
|
||||
installed, then the user will be asked if the FD.io packages should be installed. The
|
||||
packages installed will be the latest released packages.
|
||||
|
||||
Uninstalling the packages:
|
||||
|
||||
|
@ -4,9 +4,9 @@
|
||||
Show System Information
|
||||
***********************
|
||||
|
||||
With option "1" the user can inspect the system characteristics.
|
||||
With command option "1" the user can inspect the system characteristics.
|
||||
|
||||
This example shows a system that VPP has not yet been installed.
|
||||
This example shows a system that has not yet had VPP installed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -1,13 +1,14 @@
|
||||
.. _config-command-three:
|
||||
|
||||
***********************
|
||||
************************
|
||||
Apply the Configuration
|
||||
***********************
|
||||
************************
|
||||
|
||||
After the configuration files have been examined and are correct. The configuration
|
||||
can be applied. After the configuration is applied use option "1" to check the
|
||||
system configuration. Notice the default is NOT to change the grub file. If the option
|
||||
to change the grub command line is selected a reboot of the system will be required.
|
||||
After the configuration files have been examined and verified as correct, then the
|
||||
configuration can be applied by using command option '3'. After the configuration
|
||||
is applied, use option "1" to check the system configuration. Notice the default is
|
||||
NOT to change the grub file. If the option to change the grub command line is selected,
|
||||
then a reboot of the system will be required.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -4,10 +4,12 @@
|
||||
Dry Run
|
||||
*******
|
||||
|
||||
With the config utility dry run option the important configuration files are created
|
||||
so that the user can examine them and then if they look reasonable apply them with
|
||||
option 3. The files for **Ubuntu** can be found in the root directory /usr/local/vpp/vpp-config/dryrun
|
||||
and for **Centos** in /usr/vpp/vpp-config/dryrun.
|
||||
With command option '2' (the config utility *dry run* option) the important
|
||||
configuration files are created so that the user can examine them, and then
|
||||
if they look reasonable apply them with command option 3.
|
||||
|
||||
The files for **Ubuntu** can be found in the root directory */usr/local/vpp/vpp-config/dryrun*
|
||||
and for **Centos** in directory */usr/vpp/vpp-config/dryrun*.
|
||||
|
||||
The important configuration files are **/etc/vpp/startup.conf**, **/etc/sysctl.d/80-vpp.conf**,
|
||||
and **/etc/default/grub**
|
||||
@ -15,32 +17,32 @@ and **/etc/default/grub**
|
||||
Startup.conf
|
||||
============
|
||||
|
||||
FD.io VPP startup parameters are configured in the file **/etc/vpp/startup.conf**. The
|
||||
utility creates this file under the vpp-config root directory in vpp/startup.conf.
|
||||
the values in this file come from the questions asked about the devices, cores, rx queues,
|
||||
FD.io VPP startup parameters are configured in the file **/etc/vpp/startup.conf**.
|
||||
The utility creates this file under the *vpp-config* root directory in the file *vpp/startup.conf*.
|
||||
The values in this file come from the questions asked about the devices, cores, rx queues,
|
||||
and tcp parameters.
|
||||
|
||||
80-vpp.conf
|
||||
===========
|
||||
============
|
||||
|
||||
The huge page configuration comes by setting values in the file **/etc/sysctl.d/80-vpp.conf**.
|
||||
The utility creates the file under the root directory in sysctl.d/80-vpp.conf. When asked the
|
||||
question about huge pages the correct values are put in the dryrin file.
|
||||
The utility creates the file under the root directory in the file *sysctl.d/80-vpp.conf*. When asked the
|
||||
question about huge pages the correct values are put in the dryrun file.
|
||||
|
||||
grub
|
||||
====
|
||||
|
||||
CPUs can be isolated for use by VPP or other processes such as VMs using the grub configuration
|
||||
file. This file is **/etc/default/grub**. This file must be modified with care. It is possible to
|
||||
make your system unusable if this file is modified incorrectly. The dry run file is located under
|
||||
the vpp-config root directory and then default.
|
||||
CPUs can be isolated for use by VPP or other processes such as VMs using the grub
|
||||
configuration file. This file is **/etc/default/grub**. This file must be modified with
|
||||
care. It is possible to make your system unusable if this file is modified incorrectly.
|
||||
The dry run file is located under the *vpp-config* root directory and then default.
|
||||
|
||||
*********************
|
||||
***********************
|
||||
Executing the Dry Run
|
||||
*********************
|
||||
***********************
|
||||
|
||||
The following is an example of how to execute a dry run. Defaults should be picked first and then
|
||||
the values increased accordingly.
|
||||
The following is an example of how to execute a dry run. Defaults should be picked first,
|
||||
and then the values increased accordingly.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -8,14 +8,15 @@ The vpp-config utility provides the user with several different menus. This allo
|
||||
user to configure ports, some performance characteristics, the number of huge pages
|
||||
and install/uninstall the released FD.io packages.
|
||||
|
||||
It is recommended that the menu options are executed in this order.
|
||||
It is recommended that the menu command options, noted below as *"x)"*, are run in
|
||||
this order (command option 4 first, then options 1,2,3):
|
||||
|
||||
#. :ref:`4) List/Install/Uninstall VPP <config-command-four>`
|
||||
#. :ref:`1) Show basic system information <config-command-one>`
|
||||
#. :ref:`2) Dry Run <config-command-two>`
|
||||
#. :ref:`3) Full Configuration <config-command-three>`
|
||||
|
||||
Once vpp-config is installed as a root user execute the following
|
||||
Once vpp-config is installed as a root user, then run the following code:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -44,8 +45,8 @@ Once vpp-config is installed as a root user execute the following
|
||||
Default Values
|
||||
==============
|
||||
|
||||
If you do not choose to modify the default for any of the questions prompted by vpp-config,
|
||||
you may press the ENTER key to select the default options:
|
||||
If you do not choose to modify the default for any of the questions prompted by vpp-config, then
|
||||
you may press the **ENTER** key to select the default options:
|
||||
|
||||
* Questions that ask [Y/n], the capital letter Y is the default answer.
|
||||
* Numbers have their default within brackets, such as in [1024], the 1024 is the default.
|
||||
|
@ -1,8 +1,16 @@
|
||||
.. _users:
|
||||
|
||||
#####
|
||||
########
|
||||
Users
|
||||
#####
|
||||
########
|
||||
|
||||
The Users section covers basic VPP installation and configuration operations. This
|
||||
section covers the following areas:
|
||||
|
||||
* Describes the different types of VPP packages
|
||||
* Describes how to install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE)
|
||||
* Explains how to configure, then use VPP
|
||||
* Explains how to use the Configuration Utility
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
@ -8,7 +8,7 @@ Setup the fd.io Repository - Centos 7
|
||||
Update the OS
|
||||
-------------
|
||||
|
||||
It is probably a good idea to update and upgrade the OS before starting:
|
||||
Before starting the repository setup, it is a good idea to first update and upgrade the OS.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -3,11 +3,10 @@
|
||||
.. toctree::
|
||||
|
||||
Installing VPP from Packages
|
||||
============================
|
||||
==============================
|
||||
|
||||
If you are simply using vpp, it can be convenient to install the binaries from
|
||||
existing packages. This guide will describe how pull, install and run the VPP
|
||||
packages.
|
||||
If you want to use VPP it can be convenient to install the binaries from
|
||||
existing packages. This guide describes how to pull, install and run the VPP packages.
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -20,10 +19,13 @@ The following is a brief description of the packages to be installed with VPP.
|
||||
packages
|
||||
|
||||
Installing VPP Binaries
|
||||
-----------------------
|
||||
----------------------------------
|
||||
|
||||
This section provides directions on how to Install VPP binaries on Ubuntu, Centos,
|
||||
and openSUSE platforms.
|
||||
|
||||
Installing on Ubuntu
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
The following are instructions on how to install VPP on Ubuntu.
|
||||
|
||||
.. toctree::
|
||||
|
@ -4,17 +4,18 @@
|
||||
|
||||
Installing
|
||||
==========
|
||||
Top install VPP on openSUSE first pick the following release and execute the appropriate commands.
|
||||
To install VPP on openSUSE, first install the following release and then execute
|
||||
the appropriate commands.
|
||||
|
||||
openSUSE Tumbleweed (rolling release)
|
||||
-------------------------------------
|
||||
------------------------------------------------------------
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo zypper install vpp vpp-plugins
|
||||
|
||||
openSUSE Leap 42.3
|
||||
------------------
|
||||
--------------------------------
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -1,7 +1,9 @@
|
||||
.. _packages:
|
||||
|
||||
Packages
|
||||
========
|
||||
==========
|
||||
|
||||
This section identifies the different VPP packages and describes their contents.
|
||||
|
||||
.. toctree::
|
||||
|
||||
|
@ -3,13 +3,13 @@
|
||||
.. toctree::
|
||||
|
||||
Ubuntu 16.04 - Setup the fd.io Repository
|
||||
=========================================
|
||||
==========================================
|
||||
|
||||
From the following choose one of the releases to install.
|
||||
From the following, choose one of the releases to install.
|
||||
|
||||
|
||||
Update the OS
|
||||
-------------
|
||||
-----------------------
|
||||
|
||||
It is probably a good idea to update and upgrade the OS before starting
|
||||
|
||||
@ -19,7 +19,7 @@ It is probably a good idea to update and upgrade the OS before starting
|
||||
|
||||
|
||||
Point to the Repository
|
||||
-----------------------
|
||||
-----------------------------------
|
||||
|
||||
Create a file **"/etc/apt/sources.list.d/99fd.io.list"** with the contents that point to
|
||||
the version needed. The contents needed are shown below.
|
||||
@ -27,7 +27,7 @@ the version needed. The contents needed are shown below.
|
||||
.. _install_vpp:
|
||||
|
||||
VPP latest Release
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
@ -37,7 +37,7 @@ Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
|
||||
VPP stable/1804 Branch
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
@ -47,7 +47,7 @@ Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
|
||||
VPP master Branch
|
||||
^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
@ -57,7 +57,7 @@ Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
|
||||
|
||||
|
||||
Install the Mandatory Packages
|
||||
==============================
|
||||
===============================
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -66,7 +66,7 @@ Install the Mandatory Packages
|
||||
|
||||
|
||||
Install the Optional Packages
|
||||
=============================
|
||||
==============================
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
@ -4,6 +4,15 @@
|
||||
Writing VPP Documentation
|
||||
#########################
|
||||
|
||||
This section covers the following topics:
|
||||
|
||||
* Building VPP Documents
|
||||
* Merging FD.io VPP documents and performing a Git review
|
||||
* Using Read the Docs
|
||||
* reStructured Text Style Guide that describes different format styles
|
||||
* Markdown Style Guide that describes different format styles
|
||||
|
||||
|
||||
.. toctree::
|
||||
|
||||
buildingrst
|
||||
@ -13,6 +22,3 @@ Writing VPP Documentation
|
||||
styleguidemd/index.rst
|
||||
todo
|
||||
pushingapatch
|
||||
|
||||
|
||||
|
||||
|
@ -1,8 +1,14 @@
|
||||
.. _overview:
|
||||
|
||||
=========================================
|
||||
==========
|
||||
Overview
|
||||
=========================================
|
||||
==========
|
||||
|
||||
This section discusses the following information:
|
||||
|
||||
* What VPP is, what packet processing provides and the benefits VPP provides
|
||||
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
@ -1,8 +1,10 @@
|
||||
.. _packet-processing:
|
||||
|
||||
=================
|
||||
===================
|
||||
Packet Processing
|
||||
=================
|
||||
===================
|
||||
|
||||
This section identifies different components of packet processing and describes their benefits:
|
||||
|
||||
* Layer 2 - 4 Network Stack
|
||||
|
||||
|
@ -4,6 +4,8 @@
|
||||
Developer Friendly
|
||||
==================
|
||||
|
||||
This section describes the different ways VPP is friendly to developers:
|
||||
|
||||
* Extensive runtime counters; throughput, `intructions per cycle <https://en.wikipedia.org/wiki/Instructions_per_cycle>`_, errors, events etc.
|
||||
* Integrated pipeline tracing facilities
|
||||
* Multi-language API bindings
|
||||
|
@ -4,7 +4,9 @@
|
||||
Fast, Scalable and Deterministic
|
||||
================================
|
||||
|
||||
* `Continuous integration and system testing <https://wiki.fd.io/view/CSIT#Start_Here>`_
|
||||
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
|
||||
|
||||
|
Reference in New Issue
Block a user