From: ogawa.yasufumi@lab.ntt.co.jp
To: ferruh.yigit@intel.com, spp@dpdk.org, ogawa.yasufumi@lab.ntt.co.jp
Subject: [spp] [PATCH 2/2] docs: revise howto use section
Date: Tue, 18 Dec 2018 21:32:10 +0900 [thread overview]
Message-ID: <1545136330-12746-3-git-send-email-ogawa.yasufumi@lab.ntt.co.jp> (raw)
In-Reply-To: <1545136330-12746-1-git-send-email-ogawa.yasufumi@lab.ntt.co.jp>
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Revise descriptions for listed topics and correct typo.
* Add a usecase of multi-node for SPP CLI.
* Replace keyword `spp.py` with `SPP CLI` because it is changed to
be just a CLI.
* Update notes for revising the statements.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/setup/howto_use.rst | 128 +++++++++++++++++++++++++++++-----------
1 file changed, 93 insertions(+), 35 deletions(-)
diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index 1f511dd..78700e3 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -11,11 +11,12 @@ send it to SPP processes.
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.
+``spp-ctl`` need to be launched before SPP CLI, but no need to be launched
+before other processes. SPP CLI is launched from ``spp.py``.
+If ``spp-ctl`` is not running after primary and
+secondary processes are launched, processes wait ``spp-ctl`` is launched.
-In general, ``spp-ctl`` should be launched first, then ``spp.py`` and
+In general, ``spp-ctl`` should be launched first, then SPP CLI 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
@@ -26,14 +27,17 @@ How to use of these secondary processes is described in next chapters.
SPP Controller
--------------
+SPP Controller consists of ``spp-ctl`` and SPP CLI.
+
spp-ctl
~~~~~~~
-``spp-ctl`` is launched as a HTTP server for REST APIs for managing SPP
+``spp-ctl`` is 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.
+``spp-ctl`` shows no messages at first after launched, but shows
+log messages for events such as receiving a request or terminating
+a process.
.. code-block:: console
@@ -41,11 +45,13 @@ events such as receiving a request or terminating a process.
$ cd /path/to/spp
$ python3 src/spp-ctl/spp-ctl
-Notice that ``spp-ctl`` is implemented in ``python3`` and cannot launch
-with ``python`` or ``python2``.
+Notice that ``spp-ctl`` is implemented in ``python3`` and cannot be
+launched with ``python`` or ``python2``.
It has a option ``-b`` for binding address explicitly to be accessed
from other than default, ``127.0.0.1`` or ``localhost``.
+If you deploy SPP on multiple nodes, you might need to use ``-b`` option
+to be accessed from other processes running on other than local node.
.. code-block:: console
@@ -69,10 +75,10 @@ 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.py
-~~~~~~
+SPP CLI
+~~~~~~~
-If ``spp-ctl`` is launched, go to the next terminal and launch ``spp.py``.
+If ``spp-ctl`` is launched, go to the next terminal and launch SPP CLI.
It supports both of Python 2 and 3, so use ``python`` in this case.
.. code-block:: console
@@ -95,6 +101,49 @@ option for ``spp.py``, or failed to connect and to launch.
spp >
+One of the typical usecase of this option is to deploy multiple SPP nodes.
+:numref:`figure_spp_howto_multi_spp` is an exmaple of multiple nodes case.
+There are three nodes on each of which ``spp-ctl`` is running for accepting
+requests for SPP. These ``spp-ctl`` processes are controlled from
+``spp.py`` on host1 and all of paths are configured across the nodes.
+It is also able to be configured between hosts by changing
+soure or destination of phy ports.
+
+.. _figure_spp_howto_multi_spp:
+
+.. figure:: ../images/setup/howto_use/spp_howto_multi_spp.*
+ :width: 70%
+
+ Multiple SPP nodes
+
+Launch SPP CLI with three entries of binding addresses with ``-b`` option
+for specifying ``spp-ctl``. Here is an example.
+
+.. code-block:: console
+
+ # Launch SPP CLI
+ $ python src/spp.py -b 192.168.11.101 \
+ -b 192.168.11.102 \
+ -b 192.168.11.103 \
+
+You can find the host under the management of SPP CLI and switch with
+``server`` command.
+
+.. code-block:: console
+
+ spp > server list
+ 1: 192.168.1.101:7777 *
+ 2: 192.168.1.102:7777
+ 3: 192.168.1.103:7777
+
+To change the server, add an index number after ``server``.
+
+.. code-block:: console
+
+ # Launch SPP CLI
+ spp > server 3
+ Switch spp-ctl to "3: 192.168.1.103:7777".
+
All of options can be referred with help option ``-h``.
.. code-block:: console
@@ -111,17 +160,17 @@ All of options can be referred with help option ``-h``.
-a API_PORT, --api-port API_PORT
bind address, default=777
-:doc:`../../commands/index` describes
-how to manage SPP processes from SPP controller.
+All of SPP CLI commands are described in :doc:`../../commands/index`.
SPP Primary
-----------
-SPP primary is a resource manager and initializing EAL
-for secondary processes.
+SPP primary is a resource manager and has a responsibility for
+initializing EAL for secondary processes. It should be launched before
+secondary.
-To launch primary, run ``spp_primary`` with options.
+To launch SPP primary, run ``spp_primary`` with specific options.
.. code-block:: console
@@ -136,7 +185,7 @@ To launch primary, run ``spp_primary`` with options.
-n 10 \
-s 192.168.1.100:5555
-SPP primary takes EAL options before other application specific options.
+SPP primary takes EAL options and 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``.
@@ -146,16 +195,23 @@ 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.
+ Spp primary shows messages in the terminal after launched. However, the
+ contents of the message is different for the number of lcores assigned.
+
+ If you assign two lcores, SPP primary show statistics within
+ interval time periodically. On the other hand, just one lcore, it shows
+ log messages.
+
+ Anyway, you can retrieve it with ``status`` command of spp_primary.
+ The second core of spp_primary is not used for counting
+ packets actually, 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.
+physical ports. However, ports added with ``--vdev`` cannot referred from
+secondary processes.
.. code-block:: console
@@ -189,7 +245,7 @@ SPP Secondary
-------------
Secondary process behaves as a client of primary process and a worker
-for doing tasks.
+for doing tasks for packet processing.
This section describes about ``spp_nfv`` and ``spp_vm``,
which just simply forward packets similar to ``l2fwd``.
@@ -197,8 +253,8 @@ The difference between them is running on host or VM.
``spp_vm`` runs inside a VM as described in name.
-Launch on Host
-~~~~~~~~~~~~~~
+Launch spp_nfv on Host
+~~~~~~~~~~~~~~~~~~~~~~
Run ``spp_nfv`` with options.
@@ -225,12 +281,11 @@ Run ``spp_nfv`` with options.
Secondary ID is used to identify for sending messages and must be
unique among all of secondaries.
-If you attempt to launch a secondary process with the same ID,
-SPP controller does not accept it and assign unused number.
+If you attempt to launch a secondary process with the same ID, it
+is failed.
-
-Launch on VM
-~~~~~~~~~~~~
+Launch spp_vf on VM
+~~~~~~~~~~~~~~~~~~~
To communicate DPDK application running on a VM,
it is required to create a virtual device for the VM.
@@ -290,9 +345,12 @@ For other options, please refer to
.. note::
- To launch several VMs, you have to prepare qemu images for the VMs.
- You shortcut installing and setting up DPDK and SPP for each of
- VMs by creating a tmeplate image and copy it to the VMs.
+ In general, you need to prepare several qemu images for launcing
+ several VMs, but installing DPDK and SPP for several images is bother
+ and time consuming.
+
+ You can shortcut this tasks by creating a template image and copy it
+ to the VMs. It is just one time for installing for template.
After booted, you install DPDK and SPP in the VM as in the host.
@@ -324,7 +382,7 @@ Run ``spp_vm`` with options.
Secondary ID is used to identify for sending messages and must be
unique among all of secondaries.
If you attempt to launch a secondary process with the same ID,
-SPP controller does not accept it and assign unused number.
+it is failed.
In this case, port mask option is ``-p 0x01`` (using one port) because
the VM is launched with just one vhost interface.
--
2.7.4
prev parent reply other threads:[~2018-12-18 12:34 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-12-18 12:32 [spp] [PATCH 0/2] Update How to Use section ogawa.yasufumi
2018-12-18 12:32 ` [spp] [PATCH 1/2] docs: add image of muiti-node in howto section ogawa.yasufumi
2018-12-18 12:32 ` ogawa.yasufumi [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1545136330-12746-3-git-send-email-ogawa.yasufumi@lab.ntt.co.jp \
--to=ogawa.yasufumi@lab.ntt.co.jp \
--cc=ferruh.yigit@intel.com \
--cc=spp@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).