docs: Incororate Scott's overall review

Change-Id: Ic70a62e17891fa9291a5274400ae89f1d6194b6e
Signed-off-by: John DeNisco <jdenisco@cisco.com>
This commit is contained in:
John DeNisco
2018-08-02 15:03:15 -04:00
committed by Neale Ranns
parent 5c482a9de3
commit c64ba6dc6a
22 changed files with 146 additions and 78 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 43 KiB

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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
------------

View File

@ -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:

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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::

View File

@ -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

View File

@ -1,7 +1,9 @@
.. _packages:
Packages
========
==========
This section identifies the different VPP packages and describes their contents.
.. toctree::

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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