[spp] [PATCH 07/11] docs: add SPP controller in design section

[ogawa.yasufumi at lab.ntt.co.jp]

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

Add descriptions for design of SPP controller, which consists of
spp-ctl and SPP CLI exactly.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi at lab.ntt.co.jp>
---
 docs/guides/overview/design.rst | 61 +++++++++++++++++++++++++++++++++++------
 docs/guides/setup/howto_use.rst |  4 +++
 2 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/docs/guides/overview/design.rst b/docs/guides/overview/design.rst
index 9663a09..8a7f6b7 100644
--- a/docs/guides/overview/design.rst
+++ b/docs/guides/overview/design.rst
@@ -7,14 +7,32 @@
 Design
 ======
 
-SPP is composed of several DPDK processes and controller processes [1].
+SPP is composed of several DPDK processes and controller processes for
+connecting each of client processes with high-throughput path of DPDK.
+:numref:`figure_spp_overview_design_all` shows SPP processes and client apps
+for describing overview of design of SPP. In this diagram, solid line arrows
+describe a data path for packet forwarding and it can be configured from
+controller via command messaging of blue dashed line arrows.
+
+.. _figure_spp_overview_design_all:
+
+.. figure:: ../images/overview/design/spp_overview_design_all.*
+   :width: 85%
+
+   Overview of design of SPP
 
 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 primary process is responsible for resource management, for example,
+initializing ports, mbufs or shared memory. On the other hand,
+secondary processes of ``spp_nfv`` are working for forwarding [1].
+
+
+.. _spp_overview_spp_controller:
+
+SPP Controller
+--------------
 
 SPP is controlled from python based management framework. It consists of
 front-end CLI and back-end server process.
@@ -29,10 +47,6 @@ 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].
 
-
-SPP Controller
---------------
-
 spp-ctl
 ~~~~~~~
 
@@ -46,6 +60,37 @@ using SPP from a framework, such as OpenStack.
 <https://github.com/openstack/networking-spp>`_
 is a Neutron ML2 plugin for SPP and `spp-agent` works as a SPP controller.
 
+As shown in :numref:`figure_spp_overview_design_spp_ctl`,
+``spp-ctl`` behaves as a TCP server for SPP primary and secondary processes,
+and REST API server for client applications.
+It should be launched in advance to setup connections with other processes.
+``spp-ctl``  uses three TCP ports for primary, secondaries and clients.
+The default port numbers are ``5555``, ``6666`` and ``7777``.
+
+.. _figure_spp_overview_design_spp_ctl:
+
+.. figure:: ../images/overview/design/spp_overview_design_spp-ctl.*
+   :width: 48%
+
+   Spp-ctl as a REST API server
+
+SPP CLI
+~~~~~~~
+
+SPP CLI is a user interface for managing SPP and implemented as a client of
+``spp-ctl``. It provides several kinds of command for inspecting SPP
+processes, changing path configuration or showing statistics of packets.
+However, you do not need to use SPP CLI if you use ``netowrking-spp`` or
+other client applications of ``spp-ctl``. SPP CLI is one of them.
+
+From SPP CLI, user is able to configure paths as similar as
+patch panel like manner by sending commands to each of SPP secondary processes.
+``patch phy:0 ring:0`` is to connect two ports, ``phy:0`` and ``ring:0``.
+
+As described in :ref:`Getting Started<spp_setup_howto_use_spp_cli>` guide,
+SPP CLI is able to communicate several ``spp-ctl`` to support multiple nodes
+configuration.
+
 
 Reference
 ---------
diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index a7fa97a..8b8fa0b 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -1,6 +1,8 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
     Copyright(c) 2010-2014 Intel Corporation
 
+.. _spp_setup_howto_use:
+
 How to Use
 ==========
 
@@ -75,6 +77,8 @@ All of options can be referred with help option ``-h``.
       -s SEC_PORT           secondary port, default=6666
       -a API_PORT           web api port, default=7777
 
+.. _spp_setup_howto_use_spp_cli:
+
 SPP CLI
 ~~~~~~~
 
-- 
2.7.4