* [spp] [PATCH 1/3] docs: update how to use section for using spp-ctl
2018-10-25 6:52 [spp] [PATCH 0/3] Update documentation for spp-ctl ogawa.yasufumi
@ 2018-10-25 6:52 ` ogawa.yasufumi
2018-10-25 6:52 ` [spp] [PATCH 2/3] docs: correct duplicated labels in APIs reference ogawa.yasufumi
2018-10-25 6:52 ` [spp] [PATCH 3/3] docs: correct inappropriate labels in spp_vf ogawa.yasufumi
2 siblings, 0 replies; 4+ messages in thread
From: ogawa.yasufumi @ 2018-10-25 6:52 UTC (permalink / raw)
To: spp, ferruh.yigit, 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
^ permalink raw reply [flat|nested] 4+ messages in thread