ligang/vpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOCS: Moved multiarch and build system, Incorprated Scott's changes

Browse Source 
Change-Id: I5a57846db2d4faac1aa24db4629b612657f59afb
Signed-off-by: John DeNisco <jdenisco@cisco.com>
This commit is contained in:
John DeNisco
2018-08-14 16:04:09 -04:00
committed by Dave Barach
parent 9f0c02053f
commit ce96dda447
25 changed files with 130 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/conf.py
View File

@ -19,13 +19,13 @@
# -- Project information -----------------------------------------------------
project = u'Vector Packet Processor'
copyright = u'2018, John DeNisco'
copyright = u'2018, Linux Foundation'
author = u'John DeNisco'
# The short X.Y version
version = u''
# The full version, including alpha/beta/rc tags
release = u'0.1'
release = u'1.0'
# -- General configuration ---------------------------------------------------

25
docs/gettingstarted/developers/building.rst
View File

@ -6,6 +6,7 @@ Building VPP
============
To get started developing with VPP you need to get the sources and build the packages.
For more information on the build system please refer to :ref:`buildsystem`.
.. _setupproxies:
@ -24,7 +25,7 @@ You may run these commands:
Get the VPP Sources
-----------------------------------
To get the VPP sources and get ready to build execute the following:
To get the VPP sources that are used to create the build, run the following commands:
.. code-block:: console
@ -44,8 +45,9 @@ commands:
There should be no output, or packages showing after each of the above commands.
Run these commands to install the dependencies for FD.io VPP.
If it hangs during downloading at any point, you may need to set up :ref:`proxies for this to work <setupproxies>`.
Run the following **make** command to install the dependencies for FD.io VPP.
If it hangs at any point during the download, then you may need to set up
:ref:`proxies for this to work <setupproxies>`.
.. code-block:: console
@ -74,9 +76,9 @@ If it hangs during downloading at any point, you may need to set up :ref:`proxie
Build VPP (Debug)
----------------------------
This build version contains debug symbols which is useful to modify VPP. The command
below will build debug version of VPP. The binaries when building the debug images
can be found in /build-root/vpp_debug-native.
This build version contains debug symbols which are useful for modifying VPP. The
**make** command below builds a debug version of VPP. The binaries, when building the
debug images, can be found in /build-root/vpp_debug-native.
.. code-block:: console
@ -105,6 +107,10 @@ Build VPP (Release Version)
To build the release version of FD.io VPP. This build is optimized and will not create debug symbols.
The binaries when building the release images can be found in /build-root/vpp-native.
Use the following **make** command below to build the release version of FD.io VPP. This build is
optimized and will not create debug symbols. When building the release images, the binaries can
be found in /build-root/vpp-native.
.. code-block:: console
$ make build-release
@ -113,19 +119,20 @@ The binaries when building the release images can be found in /build-root/vpp-na
Building Necessary Packages
--------------------------------------------
To build the debian packages, one of the following commands below depending on the system:
Building Debian Packages
^^^^^^^^^^^^^^^^^^^^^^^^^
To build the debian packages, use one of the following commands below, depending on the system:
.. code-block:: console
$ make pkg-deb
Building RPM Packages
^^^^^^^^^^^^^^^^^^^^^^^
To build the rpm packages, use one of the following commands below, depending on the system:
.. code-block:: console
$ make pkg-rpm

0
docs/reference/buildsystem/buildrootmakefile.rst → docs/gettingstarted/developers/buildsystem/buildrootmakefile.rst
View File

2
docs/reference/buildsystem/index.rst → docs/gettingstarted/developers/buildsystem/index.rst
View File

@ -3,7 +3,7 @@
Build System
============
This reference guide describes the vpp build system in detail
This guide describes the vpp build system in detail.
.. toctree::

0
docs/reference/buildsystem/mainmakefile.md → docs/gettingstarted/developers/buildsystem/mainmakefile.md
View File

8
docs/gettingstarted/developers/gdb_examples.rst
View File

@ -10,7 +10,7 @@ In this section we have a few useful gdb commands.
Starting GDB
----------------------------
Once at the gdb prompt VPP can be started with the following:
Once at the gdb prompt, VPP can be started by isuuing the following commands:
.. code-block:: console
@ -25,7 +25,7 @@ Backtrace
----------------------------
If you encounter issues when running VPP, such as VPP terminating due to a segfault
or abort signal, you can run the VPP debug binary and then execute **backtrace** or **bt**.
or abort signal, then you can run the VPP debug binary and then execute **backtrace** or **bt**.
.. code-block:: console
@ -38,12 +38,12 @@ or abort signal, you can run the VPP debug binary and then execute **backtrace**
Get to the GDB prompt
---------------------------------------
When running VPP is running get to the command prompt with CTRL-c.
When VPP is running, you can get to the command prompt by entering CTRL-c.
Breakpoints
---------------------------------------
When at the GDB prompt set a breakpoint like so:
When at the GDB prompt, set a breakpoint by using the commands below:
.. code-block:: console

10
docs/gettingstarted/developers/gitreview.rst
View File

@ -57,20 +57,20 @@ Otherwise, clone with:
$ git clone ssh://YOUR_GERRIT_USERNAME@gerrit.fd.io:29418/vpp
$ cd vpp
When attempting to clone the repo it will ask if you want to add the Server Host Key to the list of known hosts. Type **yes** and hit enter.
When attempting to clone the repo Git will prompt you asking if you want to add the Server Host Key to the list of known hosts. Enter **yes** and press the **Enter** key.
Git Review
===========
The VPP documents use the gerrit server and git review for submitting and fetching patches.
The VPP documents use the gerrit server, and git review for submitting and fetching patches.
New patch
-----------------
When working with new patch use the following to get your patch reviewed.
When working with a new patch, use the following commands to get your patch reviewed.
Make sure you have modified the correct files with:
Make sure you have modified the correct files by issuing the following commands:
.. code-block:: console
@ -78,7 +78,7 @@ Make sure you have modified the correct files with:
$ git diff
Then add and commit the patch. You may want to add a tag to the commit comments.
For example for document only patches you should add the tag **DOCS:**.
For example for a document with only patches you should add the tag **DOCS:**.
.. code-block:: console

2
docs/gettingstarted/developers/index.rst
View File

@ -25,8 +25,10 @@ The Developers section covers the following areas:
plugins
vnet
featurearcs
multiarch/index.rst
bihash
vpp_api_module
binary_api_support
buildsystem/index.rst
sample_plugin

0
docs/reference/multiarch/index.rst → docs/gettingstarted/developers/multiarch/index.rst
View File

0
docs/reference/multiarch/nodefns.rst → docs/gettingstarted/developers/multiarch/nodefns.rst
View File

2
docs/gettingstarted/developers/plugins.md → docs/gettingstarted/developers/plugins.rst
View File

@ -1,3 +1,4 @@
.. _dplugins:
Plugins
=======
@ -9,3 +10,4 @@ filter to apply (if desired). VLIB needs to load plug-ins very early.
Once loaded, the plug-in DLL mechanism uses dlsym to find and verify a
vlib\_plugin\_registration data structure in the newly-loaded plug-in.
For more on plugins please refer to :ref:`sample_plugin`.

11
docs/gettingstarted/developers/running_vpp.rst
View File

@ -5,13 +5,14 @@
Running VPP
===========
After build the VPP binaries, there a several to run the images you've built. These is useful when
if you need to run VPP without installing the packages. For instance if you want to run VPP with GDB.
After building the VPP binaries, you now have several images that you have built.
These images are useful when you need to run VPP without installing the packages.
For instance if you want to run VPP with GDB.
Without GDB
Running Without GDB
_________________________
To run the VPP images, that you've build without GDB.
To run the VPP images that you've built without GDB, run the following commands:
Running the release image:
@ -27,7 +28,7 @@ Running the debug image:
# make run
#
With GDB
Running With GDB
_________________________
With the following commands you can run VPP and then be dropped into the GDB prompt.

6
docs/gettingstarted/developers/sample_plugin.rst
View File

@ -1,9 +1,9 @@
.. _sample_plugin:
.. toctree::
Integrating a plugin
=====================
Integrating a complete plugin with VPP
======================================
.. toctree::
Overview
________

17
docs/gettingstarted/index.rst
View File

@ -1,17 +1,20 @@
.. _gettingstarted:
######################
Getting Started Guides
Getting Started
######################
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 Getting Started Guide is comprised of several different sections; a User section
that describes a basic installation and configuration of VPP (either manually or using
a config utility), another install for Developers, which contains additional code that
provides tools that are used in a development environment.
The Users section covers basic VPP installation and configuration operations. This section covers the following areas:
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.
* Describes the different types of VPP packages, which are used in both basic and developer installs.
* Describes how to manually install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE) and then how to configure and use VPP.
* Explains how to use the Configuration Utility to install, and then configure VPP.
The Developers section covers the following areas:

27
docs/gettingstarted/users/configuring/hugepages.rst
View File

@ -3,13 +3,14 @@
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.
VPP requires *hugepages* to run during VPP operation, to manage large pages of memory.
During VPP installation, VPP will overwrite the existing hugepage settings. 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:
When VPP is installed, the following configuration file is copied to the system. The
hugepage settings are applied in the VPP installation and on system reboots. To set
the hugepage settings, perform the following commands:
.. code-block:: console
@ -30,10 +31,10 @@ hugepage settings on VPP installation and system reboot:
# to current shmmax value.
kernel.shmmax=2147483648
Depending on how the system is being used, this file can be updated to adjust
Depending on how the system is being used, this configuration file can be updated to adjust
the number of hugepages reserved on a system. Below are some examples of
possible values.
possible settings.
For a small VM with minimal workload:
.. code-block:: console
@ -54,9 +55,9 @@ For a large system running multiple VMs, each needing its own set of hugepages:
.. note::
If VPP is being run in a Virtual Machine (VM), the VM must have hugepage
backing. When VPP is installed, it will attempt to overwrite existing
hugepage setting. If the VM does not have hugepage backing, this will fail,
but this may go unnoticed. When the VM is rebooted, on system startup,
*'vm.nr_hugepages'* will be reapplied, will fail, and the VM will abort kernel
backing. When VPP is installed, it will attempt to overwrite existing the
hugepage setting. If the VM does not have hugepage backing, the install will fail,
but the failure may go unnoticed. When the VM is rebooted, on system startup,
*'vm.nr_hugepages'* will be reapplied, and will fail, and the VM will abort kernel
boot, locking up the VM. To avoid this scenario, ensure the VM has enough
hugepage backing.

4
docs/gettingstarted/users/configuring/index.rst
View File

@ -3,8 +3,8 @@
Configuring VPP
==================
There is some basic configuration that is needed to run FD.io VPP. This section
describes the basic configuration:
There is some basic configuration that needs to be performed before running
FD.io VPP. This section describes the configuration process:
.. toctree::
:maxdepth: 2

12
docs/gettingstarted/users/index.rst
View File

@ -4,13 +4,19 @@
Users
########
The Users section describe a basic VPP installation and configuration operation.
The installation and configuration of VPP can be done either manually, or by
using a configuration utility.
This section covers the following areas:
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
* Describes how to manually install VPP Binaries on different OS platforms (Ubuntu, Centos, openSUSE)
* Explains how to manually configure, then run VPP
* Explains how to install, then configure VPP using the Configuration Utility
.. toctree::
:maxdepth: 2

40
docs/gettingstarted/users/installing/centos.rst
View File

@ -8,7 +8,8 @@ Setup the fd.io Repository - Centos 7
Update the OS
-------------
Before starting the repository setup, it is a good idea to first update and upgrade the OS.
Before starting the repository setup, it is a good idea to first update and upgrade
the OS; run the following command to update the OS:
.. code-block:: console
@ -18,8 +19,7 @@ Before starting the repository setup, it is a good idea to first update and upgr
Point to the Repository
-----------------------
For CentOS based systems, there are two respositories to pull VPP binaries
from.
For CentOS based systems, there are two respositories to pull VPP binaries from:
* CentOS NFV SIG Repository
* Nexus Repository
@ -28,15 +28,14 @@ from.
CentOS NFV SIG Repository
^^^^^^^^^^^^^^^^^^^^^^^^^
VPP is not in the official CentOS 7 distro. However, CentOS has Special
VPP is not in the official CentOS 7 distro; however, CentOS has Special
Interest Groups (SIG), which are smaller groups within the CentOS community that
focus on a small set of issues. The CentOS NFV (Network Function Virtualization)
SIG was created to provide a CentOS-based stack that will serve as a platform
for the deployment and testing of virtual network functions (VNFs). VPP has been
included in this SIG.
To install released packages from the CentOS NFV SIG Repository on an updated
Centos 7 system, first, install the CentOS NFV SIG FIDO repo file:
Centos 7 system, first, install the CentOS NFV SIG FIDO repo file by running the
following command:
.. code-block:: console
@ -109,7 +108,7 @@ VPP Latest Release
""""""""""""""""""
To allow *'yum'* access to the official VPP releases, create the file
*'/etc/yum.repos.d/fdio-release.repo'* with the following content:
*'/etc/yum.repos.d/fdio-release.repo'* with the following content.
.. code-block:: console
@ -122,7 +121,7 @@ To allow *'yum'* access to the official VPP releases, create the file
The *'yum install vpp'* command will install the most recent release. To
install older releases, run the following command to get the list of releases
provided:
provided.
.. code-block:: console
@ -133,10 +132,10 @@ sample *'yum --showduplicates list'* output and an example of installing a
particular version of the RPMs.
VPP Stable Branch
"""""""""""""""""
"""""""""""""""""""
To allow *yum* access to the build artifacts for a VPP stable branch, create
the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content:
the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content.
.. code-block:: console
@ -164,10 +163,10 @@ particular version of the RPMs.
VPP Master Branch
"""""""""""""""""
"""""""""""""""""""
To allow *yum* access to the nightly builds from the VPP master branch, create
the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content:
the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content.
.. code-block:: console
@ -180,7 +179,7 @@ the file *'/etc/yum.repos.d/fdio-release.repo'* with the following content:
The *'yum install vpp'* command will install the most recent build on the
branch. Run the following command to get the list of images produce by the
branch:
branch.
.. code-block:: console
@ -194,18 +193,18 @@ particular version of the RPMs.
Install VPP RPMs
================
To install the VPP packet engine, run the following:
To install the VPP packet engine, run the following command:
.. code-block:: console
$ sudo yum install vpp
The **'vpp'** RPM depend on the **'vpp-lib'** and **'vpp-selinux-policy'**
The *vpp* RPM depends on the *vpp-lib* and *vpp-selinux-policy*
RPMs, so they will be installed as well.
.. note::
The **'vpp-selinux-policy'** will not enable SELinux on the system. It
The *vpp-selinux-policy* will not enable SELinux on the system. It
will install a Custom VPP SELinux policy that will be used if SELinux is
enabled at any time.
@ -221,19 +220,18 @@ Starting VPP
============
Once VPP is installed on the system, to run VPP as a systemd service on CentOS,
run:
run the following command:
.. code-block:: console
$ sudo systemctl start vpp
Then to enable VPP to start on system reboot:
Then to enable VPP to start on system reboot, run the following command:
.. code-block:: console
$ sudo systemctl enable vpp
Outside of running VPP as a systemd service, VPP can be started manually or
made to run within GDB for debugging. See :ref:`running` for more details and
ways to tailor VPP to a specific system.
@ -242,6 +240,8 @@ ways to tailor VPP to a specific system.
Uninstall the VPP RPMs
======================
To uninstall a VPP RPM, run the following command:
.. code-block:: console
$ sudo yum autoremove vpp*

20
docs/gettingstarted/users/installing/index.rst
View File

@ -12,16 +12,8 @@ existing packages. This guide describes how to pull, install and run the VPP pac
.. toctree::
Package Descriptions
--------------------
The following is a brief description of the packages to be installed with VPP.
.. toctree::
packages
Installing VPP Binaries
----------------------------------
Installing VPP
---------------
This section provides directions on how to Install VPP binaries on Ubuntu, Centos,
and openSUSE platforms.
@ -49,3 +41,11 @@ The following are instructions on how to install VPP on openSUSE.
.. toctree::
opensuse
Package Descriptions
--------------------
The following is a brief description of the packages to be installed with VPP.
.. toctree::
packages

9
docs/gettingstarted/users/installing/opensuse.rst
View File

@ -4,8 +4,9 @@
Installing
==========
To install VPP on openSUSE, first install the following release and then execute
the appropriate commands.
To install VPP on openSUSE, first install the following release, and then execute
the associated commands.
openSUSE Tumbleweed (rolling release)
------------------------------------------------------------
@ -25,6 +26,8 @@ openSUSE Leap 42.3
Uninstall
=========
To uninstall the vpp plugins, run the following command:
.. code-block:: console
sudo zypper remove -u vpp vpp-plugins
@ -32,6 +35,8 @@ Uninstall
openSUSE Tumbleweed (rolling release)
-------------------------------------
To uninstall the openSUSE Tumbleweed, run the following command:
.. code-block:: console
sudo zypper remove -u vpp vpp-plugins

18
docs/gettingstarted/users/installing/ubuntu.rst
View File

@ -5,13 +5,13 @@
Ubuntu 16.04 - Setup the fd.io Repository
==========================================
From the following, choose one of the releases to install.
Choose one of the following releases to install.
Update the OS
-----------------------
It is probably a good idea to update and upgrade the OS before starting
It is a good idea to first update and upgrade the OS before starting; run the following command to update the OS:
.. code-block:: console
@ -21,7 +21,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
Create a file **/etc/apt/sources.list.d/99fd.io.list** with contents that point to
the version needed. The contents needed are shown below.
.. _install_vpp:
@ -29,7 +29,7 @@ the version needed. The contents needed are shown below.
VPP latest Release
^^^^^^^^^^^^^^^^^^^
Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
Create the file **/etc/apt/sources.list.d/99fd.io.list** that contain the following contents:
.. code-block:: console
@ -39,7 +39,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:
Create the file **/etc/apt/sources.list.d/99fd.io.list** that contain the following contents:
.. code-block:: console
@ -49,7 +49,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:
Create the file **/etc/apt/sources.list.d/99fd.io.list** that contain the following contents:
.. code-block:: console
@ -59,6 +59,8 @@ Create the file **/etc/apt/sources.list.d/99fd.io.list** with contents:
Install the Mandatory Packages
===============================
Install the mandatory packages by running the following commands:
.. code-block:: console
sudo apt-get update
@ -68,6 +70,8 @@ Install the Mandatory Packages
Install the Optional Packages
==============================
Install the optional packages by running the following command:
.. code-block:: console
sudo apt-get install vpp-dbg vpp-dev vpp-api-java vpp-api-python vpp-api-lua
@ -76,6 +80,8 @@ Install the Optional Packages
Uninstall the Packages
======================
Uninstall the packages by running the following command:
.. code-block:: console
sudo apt-get remove --purge vpp*

2
docs/gettingstarted/writingdocs/index.rst
View File

@ -1,7 +1,7 @@
.. _writingdocs:
#########################
VPP Documents
Writing Documents
#########################
This section covers the following topics:

2
docs/index.rst
View File

@ -7,8 +7,6 @@
FD.io VPP
#########
This is beta VPP Documentation it is not meant to be complete or accurate yet!!!!
FD.io Vector Packet Processing (VPP) is a fast, scalable and multi-platform network stack.
FD.io VPP is, at it's core, a scalable layer 2-4 network stack.

6
docs/links/index.rst
View File

@ -1,8 +1,8 @@
.. _links:
#############
Other Links
#############
#############################
VPP Wiki and Other Links
#############################
There are several places to find helpful Information regarding FD.io VPP.

4
docs/reference/index.rst
View File

@ -7,9 +7,7 @@ Reference
.. toctree::
:maxdepth: 2
vppvagrant/index.rst
readthedocs/index.rst
github/index.rst
vppvagrant/index.rst
buildsystem/index.rst
multiarch/index.rst
cmdreference/index.rst