[spp] [PATCH 0/5] Update docs to the latest desigin

[spp] [PATCH 0/5] Update docs to the latest desigin

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

This series patches is to update docs to the latest design and behavior
of SPP. Assigning resources and outputs of commands are also updated in
this patches.

Thanks,
Yasufumi

Yasufumi Ogawa (5):
  docs: update overview section
  docs: update getting started section
  docs: update how to use section
  docs: update usecases section
  docs: add how to compile for docs

 docs/guides/overview.rst              |  41 ++++--
 docs/guides/setup/getting_started.rst |  78 ++++++++++-
 docs/guides/setup/howto_use.rst       |   4 +-
 docs/guides/setup/use_cases.rst       | 245 ++++++++++++++++++++--------------
 4 files changed, 248 insertions(+), 120 deletions(-)

-- 
2.13.1

[spp] [PATCH 1/5] docs: update overview section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Some of contents of overview section is old and needd to be updated.
This patch is to update for the latest design of SPP controller which
is devided into front-end CLI and back-end server. It is also added
an explanation of OpenStack plugin `networking-spp`.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/overview.rst | 41 +++++++++++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 14 deletions(-)

diff --git a/docs/guides/overview.rst b/docs/guides/overview.rst
index 2529f77..386ac49 100644
--- a/docs/guides/overview.rst
+++ b/docs/guides/overview.rst
@@ -21,28 +21,41 @@ NFV (Network Function Virtualization).
 With SPP, user is able to configure network easily and dynamically
 via simple patch panel like interface.
 
-The goal of SPP is to easily interconnect DPDK applications together,
-and assign resources dynamically to these applications to build a
-pipeline.
+The goal of SPP is to easily interconnect NFV applications via high
+thoughput network interfaces provided by DPDK and change configurations
+of resources dynamically to applications to build pipelines.
+
 
 Design
 ------
 
-SPP is composed of a primary DPDK application that is
-responsible for resource management. This primary application doesn't
-interact with any traffic, and is used to manage creation and freeing of
-resources only.
+SPP is composed of several DPDK processes and controller processes [1].
+
+In terms of DPDK processes, SPP is derived from DPDK's multi-process sample
+application and it consists of a primary process and multiple secondary
+processes.
+SPP primary process is responsible for resource management, for example, ports,
+mbufs or shared memory. On the other hand, secondary processes are working for
+tasks.
+
+SPP is controlled from python based management framework. It consists of
+front-end CLI and back-end server process.
+SPP's front-end CLI provides a patch panel like interface for users.
+This CLI process parses user input and sends request to the back-end via REST
+APIs. It means that the back-end server process accepts requests from other
+than CLI. It enables developers to implement control interface such as GUI, or
+plugin for other framework.
+`networking-spp
+<https://github.com/openstack/networking-spp>`_
+is a Neutron ML2 plugin for using SPP with OpenStack.
+By using networking-spp and doing some of extra tunings for optimization, you
+can deploy high-performance NFV services on OpenStack [2].
 
-A Python based management interface, SPP controller, is provided to
-control the primary
-DPDK application to create resources, which are then to be used by
-secondary applications.
-This management application provides a socket
-based interface for the primary and secondary DPDK applications to
-interface to the manager.
 
 Reference
 ---------
 
 * [1] `Implementation and Testing of Soft Patch Panel
   <https://dpdksummit.com/Archive/pdf/2017USA/Implementation%20and%20Testing%20of%20Soft%20Patch%20Panel.pdf>`_
+* [2] `Integrating OpenStack with DPDK for High Performance Applications
+  <https://www.openstack.org/summit/vancouver-2018/summit-schedule/events/20826>`_
-- 
2.13.1

[spp] [PATCH 2/5] docs: update getting started section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

* Correct configuration of PCAP PMD.

* Add description for version of Python and Python2 is going to be
  deprecated.

* Revise confirmation of running l2fwd because the purpose is not clear.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/getting_started.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst
index 1d026bd..16ff5d6 100644
--- a/docs/guides/setup/getting_started.rst
+++ b/docs/guides/setup/getting_started.rst
@@ -152,13 +152,15 @@ is included in ``wireshark``.
     $ sudo apt install wireshark
 
 PCAP is disabled by default in DPDK configuration.
-``CONFIG_RTE_LIBRTE_PMD_PCAP`` defines the configuration and enabled
-it to ``y``.
+``CONFIG_RTE_LIBRTE_PMD_PCAP`` and ``CONFIG_RTE_PORT_PCAP`` define the
+configuration and enabled it to ``y``.
 
 .. code-block:: console
 
     # dpdk/config/common_base
     CONFIG_RTE_LIBRTE_PMD_PCAP=y
+    ...
+    CONFIG_RTE_PORT_PCAP=y
 
 Compile DPDK with target environment.
 
@@ -188,6 +190,8 @@ Python 2 or 3 ?
 
 You need to install Python for using usertools of DPDK or SPP controller.
 DPDK and SPP support both of Python2 and 3.
+Howevrer, Python2 will not be maintained after 2020 and SPP is going to update
+only supporting Python3.
 
 
 Binding Network Ports to DPDK
@@ -289,8 +293,9 @@ cannot find it by using ``ifconfig`` or ``ip``.
 Confirm DPDK is setup properly
 ------------------------------
 
-You should run DPDK sample application ``l2fwd`` before SPP
-to confirm that DPDK is setup properly.
+You can confirm if you are ready to use DPDK by running DPDK's sample
+application. ``l2fwd`` is good choice to confirm it before SPP because
+it is very similar to SPP's worker process for forwarding.
 
 .. code-block:: console
 
@@ -301,7 +306,8 @@ to confirm that DPDK is setup properly.
      INSTALL-APP l2fwd
      INSTALL-MAP l2fwd.map
 
-In this case, run this application with two options.
+In this case, run this application simply with just two options
+while DPDK has many kinds of options.
 
   - -l: core list
   - -p: port mask
-- 
2.13.1

[spp] [PATCH 3/5] docs: update how to use section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update the exmaple of adding vhost because it is changed from `vhost 0`
to specify resource UID as `vhost:0`.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/howto_use.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index d52a38a..9c7d81d 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -239,11 +239,11 @@ create ``vhost-user`` and ``virtio-net-pci`` devices on the VM.
 
 Before launching VM, you need to prepare a socket file for creating
 ``vhost-user`` device.
-Socket file is created from SPP secondary as following.
+Run ``add`` command with resource UID ``vhost:0`` to create socket file.
 
 .. code-block:: console
 
-    spp > sec 1;add vhost 0
+    spp > sec 1;add vhost:0
 
 In this example, create socket file with index 0 from secondary of ID 1.
 Socket file is created as ``/tmp/sock0``.
-- 
2.13.1

[spp] [PATCH 4/5] docs: update usecases section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update command examples of old version.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/use_cases.rst | 245 ++++++++++++++++++++++++----------------
 1 file changed, 146 insertions(+), 99 deletions(-)

diff --git a/docs/guides/setup/use_cases.rst b/docs/guides/setup/use_cases.rst
index c2d7270..b8ce7d2 100644
--- a/docs/guides/setup/use_cases.rst
+++ b/docs/guides/setup/use_cases.rst
@@ -23,13 +23,13 @@ First of all, Check the status of ``spp_nfv`` from SPP controller.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
 
-This message explains that ``sec 1`` has two physical ports.
+This status message explains that ``sec 1`` has two physical ports.
 
 
 Configure spp_nfv as L2fwd
@@ -42,19 +42,23 @@ which means it is bi-directional connection.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:1
-    spp > sec 1;patch phy:1 phy:0
-    spp > sec 1;forward
+    spp > sec 1; patch phy:0 phy:1
+    Patch ports (phy:0 -> phy:1).
+    spp > sec 1; patch phy:1 phy:0
+    Patch ports (phy:1 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
 
-Confirm that status of ``sec 1`` is updated.
+Confirm that status of ``sec 1`` is updated to ``running`` and ports are
+patches as you defined.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: running
-    ports:
-      - 'phy:0 -> phy:1'
-      - 'phy:1 -> phy:0'
+    spp > sec 1; status
+    - status: running
+    - ports:
+      - phy:0 -> phy:1
+      - phy:1 -> phy:0
 
 .. _figure_spp_nfv_as_l2fwd:
 
@@ -65,11 +69,14 @@ Confirm that status of ``sec 1`` is updated.
 
 
 Stop forwarding and reset patch to clear configuration.
+``patch reset`` is to clear all of patch configurations.
 
 .. code-block:: console
 
-    spp > sec 1;stop
-    spp > sec 1;patch reset
+    spp > sec 1; stop
+    Stop forwarding.
+    spp > sec 1; patch reset
+    Clear all of patches.
 
 
 Configure spp_nfv for Loopback
@@ -80,9 +87,12 @@ for loopback.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:0
-    spp > sec 1;patch phy:1 phy:1
-    spp > sec 1;forward
+    spp > sec 1; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 1; patch phy:1 phy:1
+    Patch ports (phy:1 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
 
 
 Dual spp_nfv
@@ -113,10 +123,14 @@ from ``phy:1`` to ``phy:0`` for ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:1
-    spp > sec 2;patch phy:1 phy:0
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 phy:1
+    Patch ports (phy:0 -> phy:1).
+    spp > sec 2; patch phy:1 phy:0
+    Patch ports (phy:1 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_two_nfv_as_l2fwd:
 
@@ -134,10 +148,14 @@ Patch ``phy:0`` to ``phy:0`` for ``sec 1`` and
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:0
-    spp > sec 2;patch phy:1 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 2; patch phy:1 phy:1
+    Patch ports (phy:1 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_two_nfv_loopback:
 
@@ -167,14 +185,14 @@ All of ring PMDs is showed with ``status`` subcommand.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    addring0
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
 
 Notice that ``ring:0`` is added to ``sec 1``.
 You can delete it with ``del`` command if you do not need to
@@ -182,30 +200,36 @@ use it anymore.
 
 .. code-block:: console
 
-    spp > sec 1;del ring 0
-    delring0
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; del ring:0
+    Delete ring:0.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
 
 
 Uni-Directional L2fwd
 ~~~~~~~~~~~~~~~~~~~~~
 
 Add a ring PMD and connect two ``spp_nvf`` processes.
-To configure network path, add ``ring 0`` to ``sec 1`` and ``sec 2``.
+To configure network path, add ``ring:0`` to ``sec 1`` and ``sec 2``.
 Then, connect it with ``patch`` subcommand.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    spp > sec 2;add ring 0
-    spp > sec 1;patch phy:0 ring:0
-    spp > sec 2;patch ring:0 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 2; add ring:0
+    Add ring:0.
+    spp > sec 1; patch phy:0 ring:0
+    Patch ports (phy:0 -> ring:0).
+    spp > sec 2; patch ring:0 phy:1
+    Patch ports (ring:0 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_uni_directional_l2fwd:
 
@@ -220,46 +244,55 @@ Bi-Directional L2fwd
 
 Add two ring PMDs to two ``spp_nvf`` processes.
 For bi-directional forwarding,
-patch ``ring 0`` for a path from ``sec 1`` to ``sec 2``
-and ``ring 1`` for another path from ``sec 2`` to ``sec 1``.
+patch ``ring:0`` for a path from ``sec 1`` to ``sec 2``
+and ``ring:1`` for another path from ``sec 2`` to ``sec 1``.
 
-First, add ``ring 0`` and ``ring 1`` to ``sec 1``.
+First, add ``ring:0`` and ``ring:1`` to ``sec 1``.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    spp > sec 1;add ring 1
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
-      - 'ring:1'
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 1; add ring:1
+    Add ring:1.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
+      - ring:1
 
-
-Then, add ``ring 0`` and ``ring 1`` to ``sec 2``.
+Then, add ``ring:0`` and ``ring:1`` to ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 2;add ring 0
-    spp > sec 2;add ring 1
-    spp > sec 2;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
-      - 'ring:1'
+    spp > sec 2; add ring:0
+    Add ring:0.
+    spp > sec 2; add ring:1
+    Add ring:1.
+    spp > sec 2; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
+      - ring:1
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 ring:0
-    spp > sec 1;patch ring:1 phy:0
-    spp > sec 2;patch phy:1 ring:1
-    spp > sec 2;patch ring:0 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 ring:0
+    Patch ports (phy:0 -> ring:0).
+    spp > sec 1; patch ring:1 phy:0
+    Patch ports (ring:1 -> phy:0).
+    spp > sec 2; patch phy:1 ring:1
+    Patch ports (phy:1 -> ring:0).
+    spp > sec 2; patch ring:0 phy:1
+    Patch ports (ring:0 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_bi_directional_l2fwd:
 
@@ -284,10 +317,10 @@ vhost must be created by ``add`` subcommand before the VM is launched.
 Setup Vhost PMD
 ~~~~~~~~~~~~~~~
 
-In this use case, add ``vhost 0`` to ``sec 1`` for communicating
+In this use case, add ``vhost:0`` to ``sec 1`` for communicating
 with the VM.
 First, check if ``/tmp/sock0`` is already exist.
-You have to remove it already exist to avoid failure of socket file
+You should remove it already exist to avoid a failure of socket file
 creation.
 
 .. code-block:: console
@@ -302,13 +335,15 @@ Create ``/tmp/sock0`` from ``sec 1``.
 
 .. code-block:: console
 
-    spp > sec 1;add vhost 0
+    spp > sec 1; add vhost:0
+    Add vhost:0.
 
 
 Uni-Directional L2fwd with Vhost PMD
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Start a VM with vhost interface as described in
+Launch a VM by using the vhost interface created as previous step.
+Lauunching VM is described in
 :doc:`How to Use<howto_use>`
 and launch ``spp_vm`` with secondary ID 2.
 You find ``sec 2`` from controller after launched.
@@ -320,11 +355,16 @@ with ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 vhost:0
-    spp > sec 1;patch vhost:0 phy:1
-    spp > sec 2;patch phy:0 phy:0
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 vhost:0
+    Patch ports (phy:0 -> vhost:0).
+    spp > sec 1; patch vhost:0 phy:1
+    Patch ports (vhost:0 -> phy:1).
+    spp > sec 2; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_uni_directional_l2fwd_vhost:
 
@@ -341,7 +381,7 @@ PCAP PMD
 
 Pcap PMD is an interface for capturing or restoring traffic.
 For usign pcap PMD, you should set ``CONFIG_RTE_LIBRTE_PMD_PCAP``
-to ``y`` and compile DPDK before SPP.
+and ``CONFIG_RTE_PORT_PCAP`` to ``y`` and compile DPDK before SPP.
 Refer to
 :ref:`Install DPDK and SPP<install_dpdk_spp>`
 for details of setting up.
@@ -352,11 +392,11 @@ packets.
 For rx device, you can use any of pcap files other than SPP's pcap PMD.
 
 To start using pcap pmd, just using ``add`` subcommand as ring.
-Here is an example for creating pcap PMD with index ``1``.
+Here is an example for creating pcap PMD ``pcap:1``.
 
 .. code-block:: console
 
-    spp > sec 1;add pcap 1
+    spp > sec 1; add pcap:1
 
 After running it, you can find two of pcap files in ``/tmp``.
 
@@ -379,9 +419,12 @@ As the first usecase, add a pcap PMD and capture incoming packets from
 
 .. code-block:: console
 
-    spp > sec 1;add pcap 1
-    spp > sec 1;patch phy:0 pcap:1
-    spp > sec 1;forward
+    spp > sec 1; add pcap 1
+    Add pcap:1.
+    spp > sec 1; patch phy:0 pcap:1
+    Patch ports (phy:0 -> pcap:1).
+    spp > sec 1; forward
+    Start forwarding.
 
 .. _figure_spp_pcap_incoming:
 
@@ -404,7 +447,8 @@ To stop capturing, simply stop forwarding of ``spp_nfv``.
 
 .. code-block:: console
 
-    spp > sec 1;stop
+    spp > sec 1; stop
+    Stop forwarding.
 
 You can analyze the dumped pcap file with other tools like as wireshark.
 
@@ -418,11 +462,12 @@ Copy ``spp-tx1.pcap`` to ``spp-rx2.pcap`` first.
 
     $ sudo cp /tmp/spp-tx1.pcap /tmp/spp-rx2.pcap
 
-Then, add pcap PMD to another ``spp_nfv`` with index ``2``.
+Then, add pcap PMD ``pcap:2`` to another ``spp_nfv``.
 
 .. code-block:: console
 
-    spp > sec 2;add pcap 2
+    spp > sec 2; add pcap:2
+    Add pcap:2.
 
 .. _figure_spp_pcap_restoring:
 
@@ -447,7 +492,9 @@ and watch received packets on pktgen.
 
 .. code-block:: console
 
-    spp > sec 2;patch pcap:2 phy:1
-    spp > sec 2;forward
+    spp > sec 2; patch pcap:2 phy:1
+    Patch ports (pcap:2 -> phy:1).
+    spp > sec 2; forward
+    Start forwarding.
 
 After started forwarding, you can see that packet count is increased.
-- 
2.13.1

[spp] [PATCH 5/5] docs: add how to compile for docs

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

* Add installation of pakages for compiling HTML and PDF files.

* Add descriptions for compiling docs.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/getting_started.rst | 62 +++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst
index 16ff5d6..ca639db 100644
--- a/docs/guides/setup/getting_started.rst
+++ b/docs/guides/setup/getting_started.rst
@@ -6,6 +6,8 @@
 Getting Started
 ===============
 
+This documentation is described for Ubuntu 16.04 and later.
+
 Setup
 -----
 
@@ -139,6 +141,21 @@ Clone repository and compile DPDK in any directory.
     $ cd /path/to/any
     $ git clone http://dpdk.org/git/dpdk
 
+To compile DPDK, required to install libnuma-devel library.
+
+.. code-block:: console
+
+    $ sudo apt install libnuma-dev
+
+Python and pip are also required if not installed.
+
+.. code-block:: console
+
+    # Python2
+    $ sudo apt install python python-pip
+
+    # Python3
+    $ sudo apt install python3 python3-pip
 
 SPP provides libpcap-based PMD for dumping packet to a file or retrieve
 it from the file.
@@ -323,3 +340,48 @@ for EAL or application.
 Refer to `L2 Forwarding Sample Application
 <https://dpdk.org/doc/guides/sample_app_ug/l2_forward_real_virtual.html>`_
 for more details.
+
+
+Build Documentation
+-------------------
+
+This documentation is able to be biult as HTML and PDF formats from make
+command. Before compiling the documentation, you need to install some of
+packages required to compile.
+
+For HTML documentation, install sphinx and additional theme.
+
+.. code-block:: console
+
+    $ pip install sphinx
+    $ pip install sphinx-rtd-theme
+
+For PDF, inkscape and latex packages are required.
+
+.. code-block:: console
+
+    $ sudo apt install inkscape
+    $ sudo apt install texlive-latex-extra
+    $ sudo apt install texlive-latex-recommended
+
+HTML documentation is compiled by running make with ``doc-html``. This
+command launch sphinx for compiling HTML documents.
+Compiled HTML files are created in ``docs/guides/_build/html/`` and
+You can find the top page ``index.html`` in the directory.
+
+.. code-block:: console
+
+    $ make doc-html
+
+PDF documentation is compiled with ``doc-pdf`` which runs latex for.
+Compiled PDF file is created as ``docs/guides/_build/html/SoftPatchPanel.pdf``.
+
+.. code-block:: console
+
+    $ make doc-pdf
+
+You can also compile both of HTML and PDF documentations with ``doc-all``.
+
+.. code-block:: console
+
+    $ make doc-all
-- 
2.13.1

[spp] [PATCH v2 0/5] Update docs to the latest desigin

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

This is v2 patches for updating docs. All of IP addresses of command
examples in `How to Use` section are changed to be the same,
`192.168.1.100` in this case, as required.

Thanks,
Yasufumi

Yasufumi Ogawa (5):
  docs: update overview section
  docs: update getting started section
  docs: update how to use section
  docs: update usecases section
  docs: add how to compile for docs

 docs/guides/overview.rst              |  41 ++++--
 docs/guides/setup/getting_started.rst |  78 ++++++++++-
 docs/guides/setup/howto_use.rst       |  12 +-
 docs/guides/setup/use_cases.rst       | 245 ++++++++++++++++++++--------------
 4 files changed, 252 insertions(+), 124 deletions(-)

-- 
2.13.1

[spp] [PATCH v2 1/5] docs: update overview section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Some of contents of overview section is old and needd to be updated.
This patch is to update for the latest design of SPP controller which
is devided into front-end CLI and back-end server. It is also added
an explanation of OpenStack plugin `networking-spp`.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/overview.rst | 41 +++++++++++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 14 deletions(-)

diff --git a/docs/guides/overview.rst b/docs/guides/overview.rst
index 2529f77..386ac49 100644
--- a/docs/guides/overview.rst
+++ b/docs/guides/overview.rst
@@ -21,28 +21,41 @@ NFV (Network Function Virtualization).
 With SPP, user is able to configure network easily and dynamically
 via simple patch panel like interface.
 
-The goal of SPP is to easily interconnect DPDK applications together,
-and assign resources dynamically to these applications to build a
-pipeline.
+The goal of SPP is to easily interconnect NFV applications via high
+thoughput network interfaces provided by DPDK and change configurations
+of resources dynamically to applications to build pipelines.
+
 
 Design
 ------
 
-SPP is composed of a primary DPDK application that is
-responsible for resource management. This primary application doesn't
-interact with any traffic, and is used to manage creation and freeing of
-resources only.
+SPP is composed of several DPDK processes and controller processes [1].
+
+In terms of DPDK processes, SPP is derived from DPDK's multi-process sample
+application and it consists of a primary process and multiple secondary
+processes.
+SPP primary process is responsible for resource management, for example, ports,
+mbufs or shared memory. On the other hand, secondary processes are working for
+tasks.
+
+SPP is controlled from python based management framework. It consists of
+front-end CLI and back-end server process.
+SPP's front-end CLI provides a patch panel like interface for users.
+This CLI process parses user input and sends request to the back-end via REST
+APIs. It means that the back-end server process accepts requests from other
+than CLI. It enables developers to implement control interface such as GUI, or
+plugin for other framework.
+`networking-spp
+<https://github.com/openstack/networking-spp>`_
+is a Neutron ML2 plugin for using SPP with OpenStack.
+By using networking-spp and doing some of extra tunings for optimization, you
+can deploy high-performance NFV services on OpenStack [2].
 
-A Python based management interface, SPP controller, is provided to
-control the primary
-DPDK application to create resources, which are then to be used by
-secondary applications.
-This management application provides a socket
-based interface for the primary and secondary DPDK applications to
-interface to the manager.
 
 Reference
 ---------
 
 * [1] `Implementation and Testing of Soft Patch Panel
   <https://dpdksummit.com/Archive/pdf/2017USA/Implementation%20and%20Testing%20of%20Soft%20Patch%20Panel.pdf>`_
+* [2] `Integrating OpenStack with DPDK for High Performance Applications
+  <https://www.openstack.org/summit/vancouver-2018/summit-schedule/events/20826>`_
-- 
2.13.1

[spp] [PATCH v2 2/5] docs: update getting started section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

* Correct configuration of PCAP PMD.

* Add description for version of Python and Python2 is going to be
  deprecated.

* Revise confirmation of running l2fwd because the purpose is not clear.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/getting_started.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst
index 1d026bd..16ff5d6 100644
--- a/docs/guides/setup/getting_started.rst
+++ b/docs/guides/setup/getting_started.rst
@@ -152,13 +152,15 @@ is included in ``wireshark``.
     $ sudo apt install wireshark
 
 PCAP is disabled by default in DPDK configuration.
-``CONFIG_RTE_LIBRTE_PMD_PCAP`` defines the configuration and enabled
-it to ``y``.
+``CONFIG_RTE_LIBRTE_PMD_PCAP`` and ``CONFIG_RTE_PORT_PCAP`` define the
+configuration and enabled it to ``y``.
 
 .. code-block:: console
 
     # dpdk/config/common_base
     CONFIG_RTE_LIBRTE_PMD_PCAP=y
+    ...
+    CONFIG_RTE_PORT_PCAP=y
 
 Compile DPDK with target environment.
 
@@ -188,6 +190,8 @@ Python 2 or 3 ?
 
 You need to install Python for using usertools of DPDK or SPP controller.
 DPDK and SPP support both of Python2 and 3.
+Howevrer, Python2 will not be maintained after 2020 and SPP is going to update
+only supporting Python3.
 
 
 Binding Network Ports to DPDK
@@ -289,8 +293,9 @@ cannot find it by using ``ifconfig`` or ``ip``.
 Confirm DPDK is setup properly
 ------------------------------
 
-You should run DPDK sample application ``l2fwd`` before SPP
-to confirm that DPDK is setup properly.
+You can confirm if you are ready to use DPDK by running DPDK's sample
+application. ``l2fwd`` is good choice to confirm it before SPP because
+it is very similar to SPP's worker process for forwarding.
 
 .. code-block:: console
 
@@ -301,7 +306,8 @@ to confirm that DPDK is setup properly.
      INSTALL-APP l2fwd
      INSTALL-MAP l2fwd.map
 
-In this case, run this application with two options.
+In this case, run this application simply with just two options
+while DPDK has many kinds of options.
 
   - -l: core list
   - -p: port mask
-- 
2.13.1

[spp] [PATCH v2 3/5] docs: update how to use section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update the exmaple of adding vhost because it is changed from `vhost 0`
to specify resource UID as `vhost:0`.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/howto_use.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index d52a38a..5e96919 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -134,7 +134,7 @@ To launch primary, run ``spp_primary`` with options.
         -- \
         -p 0x03 \
         -n 10 \
-        -s 192.168.122.1:5555
+        -s 192.168.1.100:5555
 
 SPP primary takes EAL options before other application specific options.
 
@@ -169,7 +169,7 @@ physical ports.
         -- \
         -p 0x03 \
         -n 10 \
-        -s 192.168.122.1:5555
+        -s 192.168.1.100:5555
 
 - EAL options:
 
@@ -211,7 +211,7 @@ Run ``spp_nfv`` with options.
         --proc-type=secondary \
         -- \
         -n 1 \
-        -s 192.168.122.1:6666
+        -s 192.168.1.100:6666
 
 - EAL options:
 
@@ -239,11 +239,11 @@ create ``vhost-user`` and ``virtio-net-pci`` devices on the VM.
 
 Before launching VM, you need to prepare a socket file for creating
 ``vhost-user`` device.
-Socket file is created from SPP secondary as following.
+Run ``add`` command with resource UID ``vhost:0`` to create socket file.
 
 .. code-block:: console
 
-    spp > sec 1;add vhost 0
+    spp > sec 1;add vhost:0
 
 In this example, create socket file with index 0 from secondary of ID 1.
 Socket file is created as ``/tmp/sock0``.
@@ -307,7 +307,7 @@ Run ``spp_vm`` with options.
         -- \
         -p 0x01 \
         -n 1 \
-        -s 192.168.122.1:6666
+        -s 192.168.1.100:6666
 
 - EAL options:
 
-- 
2.13.1

[spp] [PATCH v2 4/5] docs: update usecases section

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

Update command examples of old version.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/use_cases.rst | 245 ++++++++++++++++++++++++----------------
 1 file changed, 146 insertions(+), 99 deletions(-)

diff --git a/docs/guides/setup/use_cases.rst b/docs/guides/setup/use_cases.rst
index c2d7270..b8ce7d2 100644
--- a/docs/guides/setup/use_cases.rst
+++ b/docs/guides/setup/use_cases.rst
@@ -23,13 +23,13 @@ First of all, Check the status of ``spp_nfv`` from SPP controller.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
 
-This message explains that ``sec 1`` has two physical ports.
+This status message explains that ``sec 1`` has two physical ports.
 
 
 Configure spp_nfv as L2fwd
@@ -42,19 +42,23 @@ which means it is bi-directional connection.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:1
-    spp > sec 1;patch phy:1 phy:0
-    spp > sec 1;forward
+    spp > sec 1; patch phy:0 phy:1
+    Patch ports (phy:0 -> phy:1).
+    spp > sec 1; patch phy:1 phy:0
+    Patch ports (phy:1 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
 
-Confirm that status of ``sec 1`` is updated.
+Confirm that status of ``sec 1`` is updated to ``running`` and ports are
+patches as you defined.
 
 .. code-block:: console
 
-    spp > sec 1;status
-    status: running
-    ports:
-      - 'phy:0 -> phy:1'
-      - 'phy:1 -> phy:0'
+    spp > sec 1; status
+    - status: running
+    - ports:
+      - phy:0 -> phy:1
+      - phy:1 -> phy:0
 
 .. _figure_spp_nfv_as_l2fwd:
 
@@ -65,11 +69,14 @@ Confirm that status of ``sec 1`` is updated.
 
 
 Stop forwarding and reset patch to clear configuration.
+``patch reset`` is to clear all of patch configurations.
 
 .. code-block:: console
 
-    spp > sec 1;stop
-    spp > sec 1;patch reset
+    spp > sec 1; stop
+    Stop forwarding.
+    spp > sec 1; patch reset
+    Clear all of patches.
 
 
 Configure spp_nfv for Loopback
@@ -80,9 +87,12 @@ for loopback.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:0
-    spp > sec 1;patch phy:1 phy:1
-    spp > sec 1;forward
+    spp > sec 1; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 1; patch phy:1 phy:1
+    Patch ports (phy:1 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
 
 
 Dual spp_nfv
@@ -113,10 +123,14 @@ from ``phy:1`` to ``phy:0`` for ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:1
-    spp > sec 2;patch phy:1 phy:0
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 phy:1
+    Patch ports (phy:0 -> phy:1).
+    spp > sec 2; patch phy:1 phy:0
+    Patch ports (phy:1 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_two_nfv_as_l2fwd:
 
@@ -134,10 +148,14 @@ Patch ``phy:0`` to ``phy:0`` for ``sec 1`` and
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 phy:0
-    spp > sec 2;patch phy:1 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 2; patch phy:1 phy:1
+    Patch ports (phy:1 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_two_nfv_loopback:
 
@@ -167,14 +185,14 @@ All of ring PMDs is showed with ``status`` subcommand.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    addring0
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
 
 Notice that ``ring:0`` is added to ``sec 1``.
 You can delete it with ``del`` command if you do not need to
@@ -182,30 +200,36 @@ use it anymore.
 
 .. code-block:: console
 
-    spp > sec 1;del ring 0
-    delring0
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
+    spp > sec 1; del ring:0
+    Delete ring:0.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
 
 
 Uni-Directional L2fwd
 ~~~~~~~~~~~~~~~~~~~~~
 
 Add a ring PMD and connect two ``spp_nvf`` processes.
-To configure network path, add ``ring 0`` to ``sec 1`` and ``sec 2``.
+To configure network path, add ``ring:0`` to ``sec 1`` and ``sec 2``.
 Then, connect it with ``patch`` subcommand.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    spp > sec 2;add ring 0
-    spp > sec 1;patch phy:0 ring:0
-    spp > sec 2;patch ring:0 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 2; add ring:0
+    Add ring:0.
+    spp > sec 1; patch phy:0 ring:0
+    Patch ports (phy:0 -> ring:0).
+    spp > sec 2; patch ring:0 phy:1
+    Patch ports (ring:0 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_uni_directional_l2fwd:
 
@@ -220,46 +244,55 @@ Bi-Directional L2fwd
 
 Add two ring PMDs to two ``spp_nvf`` processes.
 For bi-directional forwarding,
-patch ``ring 0`` for a path from ``sec 1`` to ``sec 2``
-and ``ring 1`` for another path from ``sec 2`` to ``sec 1``.
+patch ``ring:0`` for a path from ``sec 1`` to ``sec 2``
+and ``ring:1`` for another path from ``sec 2`` to ``sec 1``.
 
-First, add ``ring 0`` and ``ring 1`` to ``sec 1``.
+First, add ``ring:0`` and ``ring:1`` to ``sec 1``.
 
 .. code-block:: console
 
-    spp > sec 1;add ring 0
-    spp > sec 1;add ring 1
-    spp > sec 1;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
-      - 'ring:1'
+    spp > sec 1; add ring:0
+    Add ring:0.
+    spp > sec 1; add ring:1
+    Add ring:1.
+    spp > sec 1; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
+      - ring:1
 
-
-Then, add ``ring 0`` and ``ring 1`` to ``sec 2``.
+Then, add ``ring:0`` and ``ring:1`` to ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 2;add ring 0
-    spp > sec 2;add ring 1
-    spp > sec 2;status
-    status: idling
-    ports:
-      - 'phy:0'
-      - 'phy:1'
-      - 'ring:0'
-      - 'ring:1'
+    spp > sec 2; add ring:0
+    Add ring:0.
+    spp > sec 2; add ring:1
+    Add ring:1.
+    spp > sec 2; status
+    - status: idling
+    - ports:
+      - phy:0
+      - phy:1
+      - ring:0
+      - ring:1
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 ring:0
-    spp > sec 1;patch ring:1 phy:0
-    spp > sec 2;patch phy:1 ring:1
-    spp > sec 2;patch ring:0 phy:1
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 ring:0
+    Patch ports (phy:0 -> ring:0).
+    spp > sec 1; patch ring:1 phy:0
+    Patch ports (ring:1 -> phy:0).
+    spp > sec 2; patch phy:1 ring:1
+    Patch ports (phy:1 -> ring:0).
+    spp > sec 2; patch ring:0 phy:1
+    Patch ports (ring:0 -> phy:1).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_bi_directional_l2fwd:
 
@@ -284,10 +317,10 @@ vhost must be created by ``add`` subcommand before the VM is launched.
 Setup Vhost PMD
 ~~~~~~~~~~~~~~~
 
-In this use case, add ``vhost 0`` to ``sec 1`` for communicating
+In this use case, add ``vhost:0`` to ``sec 1`` for communicating
 with the VM.
 First, check if ``/tmp/sock0`` is already exist.
-You have to remove it already exist to avoid failure of socket file
+You should remove it already exist to avoid a failure of socket file
 creation.
 
 .. code-block:: console
@@ -302,13 +335,15 @@ Create ``/tmp/sock0`` from ``sec 1``.
 
 .. code-block:: console
 
-    spp > sec 1;add vhost 0
+    spp > sec 1; add vhost:0
+    Add vhost:0.
 
 
 Uni-Directional L2fwd with Vhost PMD
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Start a VM with vhost interface as described in
+Launch a VM by using the vhost interface created as previous step.
+Lauunching VM is described in
 :doc:`How to Use<howto_use>`
 and launch ``spp_vm`` with secondary ID 2.
 You find ``sec 2`` from controller after launched.
@@ -320,11 +355,16 @@ with ``sec 2``.
 
 .. code-block:: console
 
-    spp > sec 1;patch phy:0 vhost:0
-    spp > sec 1;patch vhost:0 phy:1
-    spp > sec 2;patch phy:0 phy:0
-    spp > sec 1;forward
-    spp > sec 2;forward
+    spp > sec 1; patch phy:0 vhost:0
+    Patch ports (phy:0 -> vhost:0).
+    spp > sec 1; patch vhost:0 phy:1
+    Patch ports (vhost:0 -> phy:1).
+    spp > sec 2; patch phy:0 phy:0
+    Patch ports (phy:0 -> phy:0).
+    spp > sec 1; forward
+    Start forwarding.
+    spp > sec 2; forward
+    Start forwarding.
 
 .. _figure_spp_uni_directional_l2fwd_vhost:
 
@@ -341,7 +381,7 @@ PCAP PMD
 
 Pcap PMD is an interface for capturing or restoring traffic.
 For usign pcap PMD, you should set ``CONFIG_RTE_LIBRTE_PMD_PCAP``
-to ``y`` and compile DPDK before SPP.
+and ``CONFIG_RTE_PORT_PCAP`` to ``y`` and compile DPDK before SPP.
 Refer to
 :ref:`Install DPDK and SPP<install_dpdk_spp>`
 for details of setting up.
@@ -352,11 +392,11 @@ packets.
 For rx device, you can use any of pcap files other than SPP's pcap PMD.
 
 To start using pcap pmd, just using ``add`` subcommand as ring.
-Here is an example for creating pcap PMD with index ``1``.
+Here is an example for creating pcap PMD ``pcap:1``.
 
 .. code-block:: console
 
-    spp > sec 1;add pcap 1
+    spp > sec 1; add pcap:1
 
 After running it, you can find two of pcap files in ``/tmp``.
 
@@ -379,9 +419,12 @@ As the first usecase, add a pcap PMD and capture incoming packets from
 
 .. code-block:: console
 
-    spp > sec 1;add pcap 1
-    spp > sec 1;patch phy:0 pcap:1
-    spp > sec 1;forward
+    spp > sec 1; add pcap 1
+    Add pcap:1.
+    spp > sec 1; patch phy:0 pcap:1
+    Patch ports (phy:0 -> pcap:1).
+    spp > sec 1; forward
+    Start forwarding.
 
 .. _figure_spp_pcap_incoming:
 
@@ -404,7 +447,8 @@ To stop capturing, simply stop forwarding of ``spp_nfv``.
 
 .. code-block:: console
 
-    spp > sec 1;stop
+    spp > sec 1; stop
+    Stop forwarding.
 
 You can analyze the dumped pcap file with other tools like as wireshark.
 
@@ -418,11 +462,12 @@ Copy ``spp-tx1.pcap`` to ``spp-rx2.pcap`` first.
 
     $ sudo cp /tmp/spp-tx1.pcap /tmp/spp-rx2.pcap
 
-Then, add pcap PMD to another ``spp_nfv`` with index ``2``.
+Then, add pcap PMD ``pcap:2`` to another ``spp_nfv``.
 
 .. code-block:: console
 
-    spp > sec 2;add pcap 2
+    spp > sec 2; add pcap:2
+    Add pcap:2.
 
 .. _figure_spp_pcap_restoring:
 
@@ -447,7 +492,9 @@ and watch received packets on pktgen.
 
 .. code-block:: console
 
-    spp > sec 2;patch pcap:2 phy:1
-    spp > sec 2;forward
+    spp > sec 2; patch pcap:2 phy:1
+    Patch ports (pcap:2 -> phy:1).
+    spp > sec 2; forward
+    Start forwarding.
 
 After started forwarding, you can see that packet count is increased.
-- 
2.13.1

[spp] [PATCH v2 5/5] docs: add how to compile for docs

[ogawa.yasufumi]

From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>

* Add installation of pakages for compiling HTML and PDF files.

* Add descriptions for compiling docs.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/setup/getting_started.rst | 62 +++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst
index 16ff5d6..ca639db 100644
--- a/docs/guides/setup/getting_started.rst
+++ b/docs/guides/setup/getting_started.rst
@@ -6,6 +6,8 @@
 Getting Started
 ===============
 
+This documentation is described for Ubuntu 16.04 and later.
+
 Setup
 -----
 
@@ -139,6 +141,21 @@ Clone repository and compile DPDK in any directory.
     $ cd /path/to/any
     $ git clone http://dpdk.org/git/dpdk
 
+To compile DPDK, required to install libnuma-devel library.
+
+.. code-block:: console
+
+    $ sudo apt install libnuma-dev
+
+Python and pip are also required if not installed.
+
+.. code-block:: console
+
+    # Python2
+    $ sudo apt install python python-pip
+
+    # Python3
+    $ sudo apt install python3 python3-pip
 
 SPP provides libpcap-based PMD for dumping packet to a file or retrieve
 it from the file.
@@ -323,3 +340,48 @@ for EAL or application.
 Refer to `L2 Forwarding Sample Application
 <https://dpdk.org/doc/guides/sample_app_ug/l2_forward_real_virtual.html>`_
 for more details.
+
+
+Build Documentation
+-------------------
+
+This documentation is able to be biult as HTML and PDF formats from make
+command. Before compiling the documentation, you need to install some of
+packages required to compile.
+
+For HTML documentation, install sphinx and additional theme.
+
+.. code-block:: console
+
+    $ pip install sphinx
+    $ pip install sphinx-rtd-theme
+
+For PDF, inkscape and latex packages are required.
+
+.. code-block:: console
+
+    $ sudo apt install inkscape
+    $ sudo apt install texlive-latex-extra
+    $ sudo apt install texlive-latex-recommended
+
+HTML documentation is compiled by running make with ``doc-html``. This
+command launch sphinx for compiling HTML documents.
+Compiled HTML files are created in ``docs/guides/_build/html/`` and
+You can find the top page ``index.html`` in the directory.
+
+.. code-block:: console
+
+    $ make doc-html
+
+PDF documentation is compiled with ``doc-pdf`` which runs latex for.
+Compiled PDF file is created as ``docs/guides/_build/html/SoftPatchPanel.pdf``.
+
+.. code-block:: console
+
+    $ make doc-pdf
+
+You can also compile both of HTML and PDF documentations with ``doc-all``.
+
+.. code-block:: console
+
+    $ make doc-all
-- 
2.13.1