[spp] [PATCH 0/3] Update documentation for spp-ctl

[spp] [PATCH 0/3] Update documentation for spp-ctl

[ogawa.yasufumi]

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

Hi,

For spp-ctl is added as a new features of controller, documentation
should be updated. Explanations of spp-ctl itself and commands are
updated, but overview section and how to use section are still needed to
be updated.

This series of patches is for the purpose. It also includes a fix of
misc warning of duplicated labels in spp_vf command section.

Thanks,
Yasufumi

Yasufumi Ogawa (3):
  docs: update how to use section for using spp-ctl
  docs: correct duplicated labels in APIs reference
  docs: correct inappropriate labels in spp_vf

 docs/guides/commands/spp_vf.rst       |   2 +-
 docs/guides/setup/howto_use.rst       | 159 +++++++++++++++++++++++++---------
 docs/guides/spp-ctl/api-reference.rst |   2 +-
 3 files changed, 121 insertions(+), 42 deletions(-)

-- 
2.13.1

[spp] [PATCH 1/3] docs: update how to use section for using spp-ctl

[ogawa.yasufumi]

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

SPP controller is changed to request to SPP processes via spp-ctl. How
to use is also changed because spp-ctl should be launched before
`spp.py`. This patch is to update descriptions of SPP controller.

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

diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index 72f0f1b..d52a38a 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -4,57 +4,112 @@
 How to Use
 ==========
 
-SPP consists of primary process for managing resources,
-secondary processes for forwarding packet,
-and SPP controller to accept user commands and sent it to SPP processes.
+As described in :ref:`Overview<spp_overview>`, SPP consists of
+primary process for managing resources, secondary processes for
+forwarding packet, and SPP controller to accept user commands and
+send it to SPP processes.
 
-You must keep in mind the order of launching processes.
-Primary process must be launched before secondary.
-In addition, controller need to be launched before primary and secondary
-because it prepares TCP connections for communicating primary and secondary.
+You should keep in mind the order of launching processes.
+Primary process must be launched before secondary processes.
+``spp-ctl`` need to be launched before ``spp.py``, but no need to be launched
+before other processes. If ``spp-ctl`` is not running after primary and
+secondary processes are launched, they wait ``spp-ctl`` is launched.
 
-1. SPP Controller
-2. SPP Primary
-3. SPP Secondary
+In general, ``spp-ctl`` should be launched first, then ``spp.py`` and
+``spp_primary`` in each of terminals without running as background process.
+After ``spp_primary``, you launch secondary processes for your usage.
+If you just patch two DPDK applications on host, it is enough to use one
+``spp_nfv``, or use ``spp_vf`` if you need to classify packets.
+How to use of these secondary processes is described in next chapters.
 
 
 SPP Controller
-----------------
+--------------
 
-SPP controller is implemented as a python script ``spp.py``.
+spp-ctl
+~~~~~~~
+
+``spp-ctl`` is launched as a HTTP server for REST APIs for managing SPP
+processes. In default, it is accessed with URL ``http://127.0.0.1:7777``
+or ``http://localhost:7777``.
+``spp-ctl`` shows no messages after launched, but shows log messages for
+events such as receiving a request or terminating a process.
 
 .. code-block:: console
 
+    # terminal 1
+    $ cd /path/to/spp
+    $ python3 src/spp-ctl/spp-ctl
+
+Notice that It is implemented in ``python3`` and cannot launch
+with ``python`` or ``python2``.
+
+It has a option ``-b`` for binding address to be accessed from other than
+``127.0.0.1`` or ``localhost``.
+
+.. code-block:: console
+
+    # launch with URL http://192.168.1.100:7777
+    $ python3 src/spp-ctl/spp-ctl -b 192.168.1.100
+
+All of options can be referred with help option ``-h``.
+
+.. code-block:: console
+
+    python3 ./src/spp-ctl/spp-ctl -h
+    usage: spp-ctl [-h] [-b BIND_ADDR] [-p PRI_PORT] [-s SEC_PORT] [-a API_PORT]
+
+    SPP Controller
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -b BIND_ADDR, --bind-addr BIND_ADDR
+                            bind address, default=localhost
+      -p PRI_PORT           primary port, default=5555
+      -s SEC_PORT           secondary port, default=6666
+      -a API_PORT           web api port, default=7777
+
+spp.py
+~~~~~~
+
+If ``spp-ctl`` is launched, go to the next terminal and launch ``spp.py``.
+It supports both of Python 2 and 3, so use ``python`` in this case.
+
+.. code-block:: console
+
+    # terminal 2
     $ cd /path/to/spp
     $ python src/spp.py
-    primary port : 5555
-    secondary port : 6666
     Welcome to the spp.   Type help or ? to list commands.
 
     spp >
 
-Controller communicate with primary via TCP port 5555 and with secondary
-processes via 6666 in defalt.
-You can change port number by using options.
-Please refer help message for options.
+If you launched ``spp-ctl`` with ``-b`` option, you also need to use the same
+option for ``spp.py``, or failed to connect and to launch.
+
+.. code-block:: console
+
+    # to send request to http://192.168.1.100:7777
+    $ python src/spp.py -b 192.168.1.100
+    Welcome to the spp.   Type help or ? to list commands.
+
+    spp >
+
+All of options can be referred with help option ``-h``.
 
 .. code-block:: console
 
     $ python src/spp.py -h
-    usage: spp.py [-h] [-p PRI_PORT] [-s SEC_PORT] [-m MNG_PORT] [-ip IPADDR]
+    usage: spp.py [-h] [-b BIND_ADDR] [-a API_PORT]
 
     SPP Controller
 
     optional arguments:
       -h, --help            show this help message and exit
-      -p PRI_PORT, --pri-port PRI_PORT
-                            primary port number
-      -s SEC_PORT, --sec-port SEC_PORT
-                            secondary port number
-      -m MNG_PORT, --mng-port MNG_PORT
-                            management port number
-      -ip IPADDR, --ipaddr IPADDR
-                            IP address
+      -b BIND_ADDR, --bind-addr BIND_ADDR
+                            bind address, default=127.0.0.1
+      -a API_PORT, --api-port API_PORT
+                        bind address, default=777
 
 :doc:`../../commands/index` describes
 how to manage SPP processes from SPP controller.
@@ -70,6 +125,7 @@ To launch primary, run ``spp_primary`` with options.
 
 .. code-block:: console
 
+    # terminal 3
     $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
         -l 1 -n 4 \
         --socket-mem 512,512 \
@@ -80,15 +136,44 @@ To launch primary, run ``spp_primary`` with options.
         -n 10 \
         -s 192.168.122.1:5555
 
-SPP primary is a DPDK application and it takes EAL options before
-application specific options.
-Briefly describe about supported options.
-You can use ``-m`` instead of ``--socket-mem`` if you use single NUMA
-node.
+SPP primary takes EAL options before other application specific options.
+
+Core list option ``-l`` is for assigining cores and SPP primary requires just
+one core. You can use core mask option ``-c`` instead of ``-l``.
+
+You can use ``-m`` for memory reservation instead of ``--socket-mem`` if you
+use single NUMA node.
+
+.. note::
+
+    SPP primary show statistics within interval time periodically if you
+    assign two lcores. However, you can retrieve it with ``status`` command
+    of spp_primary. Second core of spp_primary is not used for counting
+    packets but used just for displaying the statistics.
+
+Primary process sets up physical ports of given port mask with ``-p`` option
+and ring ports of the number of ``-n`` option. Ports of  ``-p`` option is for
+accepting incomming packets and ``-n`` option is for inter-process packet
+forwarding. You can also add ports initialized with ``--vdev`` option to
+physical ports.
+
+.. code-block:: console
+
+    $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
+        -l 1 -n 4 \
+        --socket-mem 512,512 \
+        --huge-dir=/dev/hugepages \
+        --vdev eth_vhost1,iface=/tmp/sock1  # used as 1st phy port
+        --vdev eth_vhost2,iface=/tmp/sock2  # used as 2nd
+        --proc-type=primary \
+        -- \
+        -p 0x03 \
+        -n 10 \
+        -s 192.168.122.1:5555
 
 - EAL options:
 
-  - -l: core list (two cores required for displaying status)
+  - -l: core list
   - --socket-mem: memory size on each of NUMA nodes
   - --huge-dir: path of hugepage dir
   - --proc-type: process type
@@ -99,13 +184,6 @@ node.
   - -n: number of ring PMD
   - -s: IP address of controller and port prepared for primary
 
-.. note::
-
-    You do not need to give two cores if you are not interested in
-    statistics.
-    SPP primary is able to run with only one core and use second one
-    to show the statistics.
-
 
 SPP Secondary
 -------------
@@ -126,6 +204,7 @@ Run ``spp_nfv`` with options.
 
 .. code-block:: console
 
+    # terminal 4
     $ cd /path/to/spp
     $ sudo ./src/nfv/x86_64-native-linuxapp-gcc/spp_nfv \
         -l 2-3 -n 4 \
-- 
2.13.1

[spp] [PATCH 2/3] docs: correct duplicated labels in APIs reference

[ogawa.yasufumi]

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

There are duplicated labels in REST APIs warned while compiling
document. Fix this warning by correcting the labels.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/spp-ctl/api-reference.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/spp-ctl/api-reference.rst b/docs/guides/spp-ctl/api-reference.rst
index 3ae90fd..bb8409c 100644
--- a/docs/guides/spp-ctl/api-reference.rst
+++ b/docs/guides/spp-ctl/api-reference.rst
@@ -690,7 +690,7 @@ vlan object:
 
 classifier table:
 
-.. _table_spp_ctl_spp_vf_res_vlan:
+.. _table_spp_ctl_spp_vf_res_cls:
 
 .. table:: Vlan objects of getting spp_vf.
 
-- 
2.13.1

[spp] [PATCH 3/3] docs: correct inappropriate labels in spp_vf

[ogawa.yasufumi]

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

Fix inappropriate labels of command syntax in spp_vf.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/spp_vf.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/guides/commands/spp_vf.rst b/docs/guides/commands/spp_vf.rst
index aa2b1f4..baa1e45 100644
--- a/docs/guides/commands/spp_vf.rst
+++ b/docs/guides/commands/spp_vf.rst
@@ -302,7 +302,7 @@ a table of classifier.
     spp > vf SEC_ID; classifier_table add mac MAC_ADDR RES_UID
 
     # delete entry
-    spp > vf SEC_ID; classifier_table del mac [MAC_ADDRESS] [RES_ID]
+    spp > vf SEC_ID; classifier_table del mac MAC_ADDRESS RES_ID
 
 This is an example to register MAC address ``52:54:00:01:00:01``
 with port ``ring:0``.
-- 
2.13.1