diff options
22 files changed, 146 insertions, 78 deletions
diff --git a/docs/_images/vhost-topo.png b/docs/_images/vhost-topo.png Binary files differindex c2baf7edbed..6da458d2c7a 100644 --- a/docs/_images/vhost-topo.png +++ b/docs/_images/vhost-topo.png diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst index cccb18d731a..165488c7a31 100644 --- a/docs/gettingstarted/developers/index.rst +++ b/docs/gettingstarted/developers/index.rst @@ -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 diff --git a/docs/gettingstarted/index.rst b/docs/gettingstarted/index.rst index 754796b670b..acee1963af5 100644 --- a/docs/gettingstarted/index.rst +++ b/docs/gettingstarted/index.rst @@ -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 diff --git a/docs/gettingstarted/users/configuring/hugepages.rst b/docs/gettingstarted/users/configuring/hugepages.rst index 42f6aa30282..76ac7d0807d 100644 --- a/docs/gettingstarted/users/configuring/hugepages.rst +++ b/docs/gettingstarted/users/configuring/hugepages.rst @@ -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 diff --git a/docs/gettingstarted/users/configuring/index.rst b/docs/gettingstarted/users/configuring/index.rst index 75c5276d8a5..f1244c61a4f 100644 --- a/docs/gettingstarted/users/configuring/index.rst +++ b/docs/gettingstarted/users/configuring/index.rst @@ -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 diff --git a/docs/gettingstarted/users/configuring/startup.rst b/docs/gettingstarted/users/configuring/startup.rst index 7dd2c996a80..8ce27eb676d 100644 --- a/docs/gettingstarted/users/configuring/startup.rst +++ b/docs/gettingstarted/users/configuring/startup.rst @@ -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 ------------ diff --git a/docs/gettingstarted/users/configutil/commandfour.rst b/docs/gettingstarted/users/configutil/commandfour.rst index 27cac824e4a..6a1b82e1da5 100644 --- a/docs/gettingstarted/users/configutil/commandfour.rst +++ b/docs/gettingstarted/users/configutil/commandfour.rst @@ -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: diff --git a/docs/gettingstarted/users/configutil/commandone.rst b/docs/gettingstarted/users/configutil/commandone.rst index 9d63809b96b..33b6dbb04ce 100644 --- a/docs/gettingstarted/users/configutil/commandone.rst +++ b/docs/gettingstarted/users/configutil/commandone.rst @@ -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 diff --git a/docs/gettingstarted/users/configutil/commandthree.rst b/docs/gettingstarted/users/configutil/commandthree.rst index c4c44292fd0..589a3671acf 100644 --- a/docs/gettingstarted/users/configutil/commandthree.rst +++ b/docs/gettingstarted/users/configutil/commandthree.rst @@ -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 diff --git a/docs/gettingstarted/users/configutil/commandtwo.rst b/docs/gettingstarted/users/configutil/commandtwo.rst index 0d06c1410e5..c30663f5df9 100644 --- a/docs/gettingstarted/users/configutil/commandtwo.rst +++ b/docs/gettingstarted/users/configutil/commandtwo.rst @@ -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 diff --git a/docs/gettingstarted/users/configutil/usingvppconfig.rst b/docs/gettingstarted/users/configutil/usingvppconfig.rst index 4f1ce6c3c30..8694a83341f 100644 --- a/docs/gettingstarted/users/configutil/usingvppconfig.rst +++ b/docs/gettingstarted/users/configutil/usingvppconfig.rst @@ -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. diff --git a/docs/gettingstarted/users/index.rst b/docs/gettingstarted/users/index.rst index 6fd7260650a..36640a8b454 100644 --- a/docs/gettingstarted/users/index.rst +++ b/docs/gettingstarted/users/index.rst @@ -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 diff --git a/docs/gettingstarted/users/installing/centos.rst b/docs/gettingstarted/users/installing/centos.rst index bb69eb9e797..470ca87be1f 100644 --- a/docs/gettingstarted/users/installing/centos.rst +++ b/docs/gettingstarted/users/installing/centos.rst @@ -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 diff --git a/docs/gettingstarted/users/installing/index.rst b/docs/gettingstarted/users/installing/index.rst index 7636ec875fd..6cadae0a314 100644 --- a/docs/gettingstarted/users/installing/index.rst +++ b/docs/gettingstarted/users/installing/index.rst @@ -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:: diff --git a/docs/gettingstarted/users/installing/opensuse.rst b/docs/gettingstarted/users/installing/opensuse.rst index 8e91ebd2f45..b5dcbc35820 100644 --- a/docs/gettingstarted/users/installing/opensuse.rst +++ b/docs/gettingstarted/users/installing/opensuse.rst @@ -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 diff --git a/docs/gettingstarted/users/installing/packages.rst b/docs/gettingstarted/users/installing/packages.rst index d67ff605d99..55ddf05fdad 100644 --- a/docs/gettingstarted/users/installing/packages.rst +++ b/docs/gettingstarted/users/installing/packages.rst @@ -1,7 +1,9 @@ .. _packages: Packages -======== +========== + +This section identifies the different VPP packages and describes their contents. .. toctree:: diff --git a/docs/gettingstarted/users/installing/ubuntu.rst b/docs/gettingstarted/users/installing/ubuntu.rst index 9c082e667b0..5b4a1d86fee 100644 --- a/docs/gettingstarted/users/installing/ubuntu.rst +++ b/docs/gettingstarted/users/installing/ubuntu.rst @@ -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 diff --git a/docs/gettingstarted/writingdocs/index.rst b/docs/gettingstarted/writingdocs/index.rst index e1ce767e40e..1361c422af7 100644 --- a/docs/gettingstarted/writingdocs/index.rst +++ b/docs/gettingstarted/writingdocs/index.rst @@ -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 - - - diff --git a/docs/overview/index.rst b/docs/overview/index.rst index d3da0e211fa..8d1e434d848 100644 --- a/docs/overview/index.rst +++ b/docs/overview/index.rst @@ -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 diff --git a/docs/overview/whatisvpp/dataplane.rst b/docs/overview/whatisvpp/dataplane.rst index 9113038fc57..256165f4f8c 100644 --- a/docs/overview/whatisvpp/dataplane.rst +++ b/docs/overview/whatisvpp/dataplane.rst @@ -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 diff --git a/docs/overview/whatisvpp/developer.rst b/docs/overview/whatisvpp/developer.rst index a0bb2d451c0..57000d45880 100644 --- a/docs/overview/whatisvpp/developer.rst +++ b/docs/overview/whatisvpp/developer.rst @@ -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 diff --git a/docs/overview/whatisvpp/fast.rst b/docs/overview/whatisvpp/fast.rst index b04c12fbe7b..9e9e314809c 100644 --- a/docs/overview/whatisvpp/fast.rst +++ b/docs/overview/whatisvpp/fast.rst @@ -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 |
