[spp] [PATCH 0/3] Update documentation for pri launch command

[spp] [PATCH 0/3] Update documentation for pri launch command

[ogawa.yasufumi]

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

This series of updates is to add descriptions for `pri; launch` commmand
and its usages.

* Add launch command in `SPP Commands` chapter.

* Update `How to Use` section for launch command.


Yasufumi Ogawa (3):
  docs: add config command
  docs: add usage of pri launch command
  docs: update how to use guide

 docs/guides/commands/common.rst |  73 ++++++++++++++++++++
 docs/guides/setup/howto_use.rst | 148 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 215 insertions(+), 6 deletions(-)

-- 
2.7.4

[spp] [PATCH 1/3] docs: add config command

[ogawa.yasufumi]

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

This patch is to add `config` command in "SPP Commands" chapter.

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

diff --git a/docs/guides/commands/common.rst b/docs/guides/commands/common.rst
index ef862c5..6c72878 100644
--- a/docs/guides/commands/common.rst
+++ b/docs/guides/commands/common.rst
@@ -23,6 +23,79 @@ Show the status of SPP processes.
         2: vf:3
 
 
+config
+------
+
+Show or update config params.
+
+Config params used for changing behaviour of SPP CLI. For instance, if you
+change command prompt, you can set any of prompt with ``config`` command
+other than default ``spp >``.
+
+.. code-block:: none
+
+    # set prompt to "$ spp"
+    spp > config prompt "$ spp"
+    Set prompt: "$ spp "
+    $ spp
+
+
+Show Config
+~~~~~~~~~~~
+
+To show the list of config all of params, simply run ``config``.
+
+.. code-block:: none
+
+    # show list of config
+    spp > config
+    - max_secondary: "16"       # The maximum number of secondary processes
+    - sec_nfv_nof_lcores: "1"   # Default num of lcores for workers of spp_nfv
+    - topo_size: "60%"  # Percentage or ratio of topo
+    - sec_base_lcore: "1"       # Shared lcore among secondaryes
+    ....
+
+Or show params only started from ``sec_``, add the keyword to the commnad.
+
+.. code-block:: none
+
+    # show config started from `sec_`
+    spp > config sec_
+    - sec_vhost_cli: "" # Vhost client mode, activated if set any of values
+    - sec_mem: "-m 512" # Mem size
+    - sec_nfv_nof_lcores: "1"   # Default num of lcores for workers of spp_nfv
+    - sec_base_lcore: "1"       # Shared lcore among secondaryes
+    ....
+
+Set Config
+~~~~~~~~~~
+
+One of typical uses of ``config`` command is to change the default params of
+other commands. ``pri; launch`` takes several options for launching secondary
+process and it is completed by using default params started from ``sec_``.
+
+.. code-block:: none
+
+    spp > pri; launch nfv 2  # press TAB for completion
+    spp > pri; launch nfv 2 -l 1,2 -m 512 -- -n 2 -s 192.168.11.59:6666
+
+The default number of memory size is ``-m 512`` and the definition
+``sec_mem`` can be changed with ``config`` command.
+Here is an example of changing ``-m 512`` to ``--socket-mem 512,0``.
+
+.. code-block:: none
+
+    spp > config sec_mem "--socket-mem 512,0"
+    Set sec_mem: "--socket-mem 512,0"
+
+After updating the param, expanded options is also updated.
+
+.. code-block:: none
+
+    spp > pri; launch nfv 2  # press TAB for completion
+    spp > pri; launch nfv 2 -l 1,2 --socket-mem 512,0 -- -n 2 -s ...
+
+
 playback
 --------
 
-- 
2.7.4

[spp] [PATCH 2/3] docs: add usage of pri launch command

[ogawa.yasufumi]

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

This update is to add how to launch secondary process with
`pri; launch` command and how to find log file to `How to Use` section.

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

diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index f8a33bc..4207abc 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -301,6 +301,58 @@ unique among all of secondaries.
 If you attempt to launch a secondary process with the same ID, it
 is failed.
 
+
+Launch from SPP CLI
+~~~~~~~~~~~~~~~~~~~
+
+You can launch SPP secondary processes from SPP CLI wihtout openning
+other terminals. ``pri; launch`` command is for any of secondary processes
+with specific options. It takes secondary type, ID and options of EAL
+and application itself as similar to launching from terminal.
+Here is an example of launching ``spp_nfv``. You notice that there is no
+``--proc-type secondary`` which should be required for secondary.
+It is added to the options by SPP CLI before launching the process.
+
+.. code-block:: none
+
+   # launch spp_nfv with sec ID 2
+   spp > pri; launch nfv 2 -l 1,2 -m 512 -- -n 2 -s 192.168.1.100:6666
+   Send request to launch nfv:2.
+
+After running this command, you can find ``nfv:2`` is launched
+successfully.
+
+.. code-block:: none
+
+   spp > status
+   - spp-ctl:
+     - address: 192.168.1.100:7777
+   - primary:
+     - status: running
+   - secondary:
+     - processes:
+       1: nfv:2
+
+Instead of displaying log messages in terminal, it outputs the messages
+in a log file. All of log files of secondary processes launched with
+``pri`` are located in ``log/`` directory under the project root.
+The name of log file is found ``log/spp_nfv-2.log``.
+
+.. code-block:: console
+
+    $ tail -f log/spp_nfv-2.log
+    SPP_NFV: Used lcores: 1 2
+    SPP_NFV: entering main loop on lcore 2
+    SPP_NFV: My ID 2 start handling message
+    SPP_NFV: [Press Ctrl-C to quit ...]
+    SPP_NFV: Creating socket...
+    SPP_NFV: Trying to connect ... socket 24
+    SPP_NFV: Connected
+    SPP_NFV: Received string: _get_client_id
+    SPP_NFV: token 0 = _get_client_id
+    SPP_NFV: To Server: {"results":[{"result":"success"}],"client_id":2, ...
+
+
 Launch SPP on VM
 ~~~~~~~~~~~~~~~~
 
@@ -313,7 +365,7 @@ Before launching VM, you need to prepare a socket file for creating
 ``vhost-user`` device.
 Run ``add`` command with resource UID ``vhost:0`` to create socket file.
 
-.. code-block:: console
+.. code-block:: none
 
     spp > nfv 1; add vhost:0
 
-- 
2.7.4

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

[ogawa.yasufumi]

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

* Add usage of launching secondary process from SPP CLI.

* Update how to manage SPP running on VM with `server` command.

* Revise descriptions of usage of QEMU to be more understandable.

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

diff --git a/docs/guides/setup/howto_use.rst b/docs/guides/setup/howto_use.rst
index 4207abc..225f096 100644
--- a/docs/guides/setup/howto_use.rst
+++ b/docs/guides/setup/howto_use.rst
@@ -112,7 +112,8 @@ option for ``spp.py``, or failed to connect and to launch.
 
 .. code-block:: console
 
-    # to send request to http://192.168.1.100:7777
+    # terminal 2
+    # bind to spp-ctl on 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.
 
@@ -207,8 +208,9 @@ 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``.
 
-You can use ``-m`` for memory reservation instead of ``--socket-mem`` if you
-use single NUMA node.
+You can use ``-m 1024`` for memory reservation instead of
+``--socket-mem 1024,0`` if you use single NUMA node. In this case, 512 MB is
+reserved on each of nodes.
 
 .. note::
 
@@ -232,6 +234,7 @@ secondary processes.
 
 .. code-block:: console
 
+    # terminal 3
     $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
         -l 1 -n 4 \
         --socket-mem 512,512 \
@@ -315,23 +318,25 @@ It is added to the options by SPP CLI before launching the process.
 
 .. code-block:: none
 
-   # launch spp_nfv with sec ID 2
-   spp > pri; launch nfv 2 -l 1,2 -m 512 -- -n 2 -s 192.168.1.100:6666
-   Send request to launch nfv:2.
+    # terminal 2
+    # launch spp_nfv with sec ID 2
+    spp > pri; launch nfv 2 -l 1,2 -m 512 -- -n 2 -s 192.168.1.100:6666
+    Send request to launch nfv:2.
 
 After running this command, you can find ``nfv:2`` is launched
 successfully.
 
 .. code-block:: none
 
-   spp > status
-   - spp-ctl:
-     - address: 192.168.1.100:7777
-   - primary:
-     - status: running
-   - secondary:
-     - processes:
-       1: nfv:2
+    # terminal 2
+    spp > status
+    - spp-ctl:
+      - address: 192.168.1.100:7777
+    - primary:
+      - status: running
+    - secondary:
+      - processes:
+        1: nfv:2
 
 Instead of displaying log messages in terminal, it outputs the messages
 in a log file. All of log files of secondary processes launched with
@@ -340,6 +345,7 @@ The name of log file is found ``log/spp_nfv-2.log``.
 
 .. code-block:: console
 
+    # terminal 5
     $ tail -f log/spp_nfv-2.log
     SPP_NFV: Used lcores: 1 2
     SPP_NFV: entering main loop on lcore 2
@@ -367,6 +373,7 @@ Run ``add`` command with resource UID ``vhost:0`` to create socket file.
 
 .. code-block:: none
 
+    # terminal 2
     spp > nfv 1; add vhost:0
 
 In this example, it creates socket file with index 0 from ``spp_nfv`` of ID 1.
@@ -375,10 +382,15 @@ It is used as a qemu option to add vhost interface.
 
 Launch VM with ``qemu-system-x86_64`` for x86 64bit architecture.
 Qemu takes many options for defining resources including virtual
-devices.
+devices. You cannot use this example as it is because some options are
+depend on your environment.
+You should specify disk image with ``-hda``, sixth option in this
+example, and ``qemu-ifup`` script for assigning an IP address for the VM
+to be able to access as 12th line.
 
 .. code-block:: console
 
+    # terminal 5
     $ sudo qemu-system-x86_64 \
         -cpu host \
         -enable-kvm \
@@ -421,4 +433,76 @@ For other options, please refer to
     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.
+After VM is booted, you install DPDK and SPP in the VM as in the host.
+IP address of the VM is assigned while it is created and you can find
+the address in a file generated from libvirt if you use Ubuntu.
+
+.. code-block:: console
+
+    # terminal 5
+    $ cat /var/lib/libvirt/dnsmasq/virbr0.status
+    [
+        {
+            "ip-address": "192.168.122.100",
+            ...
+
+    # Login VM, install DPDK and SPP
+    $ ssh user@192.168.122.100
+    ...
+
+It is recommended to configure ``/etc/default/grub`` for hugepages and
+reboot the VM after installation.
+
+Finally, login to the VM, bind ports to DPDK and launch ``spp-ctl``
+and ``spp_primamry``.
+You should add ``-b`` option to be accessed from SPP CLI on host.
+
+.. code-block:: console
+
+    # terminal 5
+    $ ssh user@192.168.122.100
+    $ cd /path/to/spp
+    $ python3 src/spp-ctl/spp-ctl -b 192.168.122.100
+    ...
+
+Confirm that virtio interfaces are under the management of DPDK before
+launching DPDK processes.
+
+.. code-block:: console
+
+    # terminal 6
+    $ ssh user@192.168.122.100
+    $ cd /path/to/spp
+    $ sudo ./src/primary/x86_64-native-linuxapp-gcc/spp_primary \
+        -l 1 -n 4 \
+        -m 1024 \
+        --huge-dir=/dev/hugepages \
+        --proc-type=primary \
+        -- \
+        -p 0x03 \
+        -n 6 \
+        -s 192.168.122.100:5555
+
+You can configure SPP running on the VM from SPP CLI.
+Use ``server`` command is to switch node under the management.
+
+.. code-block:: none
+
+    # terminal 2
+    # show list of spp-ctl nodes
+    spp > server
+    1: 192.168.1.100:7777 *
+    2: 192.168.122.100:7777
+
+    # change node under the management
+    spp > server 2
+    Switch spp-ctl to "2: 192.168.122.100:7777".
+
+    # confirm node is switched
+    spp > server
+    1: 192.168.1.100:7777
+    2: 192.168.122.100:7777 *
+
+    # configure SPP on VM
+    spp > status
+    ...
-- 
2.7.4