[spp] [PATCH 0/4] Update REST API reference and usecases

[spp] [PATCH 0/4] Update REST API reference and usecases

[ogawa.yasufumi]

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

This series of patches is to update REST API reference and usecases.

* For features added to primary, add descriptions in the section of
  REST API reference. It is also updates descriptions in spp_nfv
  remained old.

* Add usage of `server add` command in usecase.

Yasufumi Ogawa (4):
  docs: add lcores in pri status in REST API
  docs: add launch of primary to REST API reference
  docs: refactor spp_nfv REST API reference
  docs: add usage of server add command in usecase

 docs/guides/api_ref/spp_primary.rst   | 130 +++++++++++++++++++----
 docs/guides/api_ref/spp_vf.rst        | 187 +++++++++++++++++-----------------
 docs/guides/use_cases/multi_nodes.rst |  20 +++-
 3 files changed, 222 insertions(+), 115 deletions(-)

-- 
2.7.4

[spp] [PATCH 1/4] docs: add lcores in pri status in REST API

[ogawa.yasufumi]

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

This update is to add `lcores` attribute in `status` of spp_primary.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/api_ref/spp_primary.rst | 36 ++++++++++++++----------------------
 1 file changed, 14 insertions(+), 22 deletions(-)

diff --git a/docs/guides/api_ref/spp_primary.rst b/docs/guides/api_ref/spp_primary.rst
index fb89766..e46de21 100644
--- a/docs/guides/api_ref/spp_primary.rst
+++ b/docs/guides/api_ref/spp_primary.rst
@@ -31,14 +31,16 @@ Response
 
 .. table:: Response params of primary status.
 
-    +------------+-------+-------------------------------------------+
-    | Name       | Type  | Description                               |
-    |            |       |                                           |
-    +============+=======+===========================================+
-    | phy_ports  | array | An array of statistics of physical ports. |
-    +------------+-------+-------------------------------------------+
-    | ring_ports | array | An array of statistics of ring ports.     |
-    +------------+-------+-------------------------------------------+
+    +------------+-------+----------------------------------------+
+    | Name       | Type  | Description                            |
+    |            |       |                                        |
+    +============+=======+========================================+
+    | lcores     | array | Array of lcores spp_primary is using.  |
+    +------------+-------+----------------------------------------+
+    | phy_ports  | array | Array of statistics of physical ports. |
+    +------------+-------+----------------------------------------+
+    | ring_ports | array | Array of statistics of ring ports.     |
+    +------------+-------+----------------------------------------+
 
 Physical port object.
 
@@ -89,6 +91,9 @@ Response example
 .. code-block:: json
 
     {
+      "lcores": [
+        0
+      ],
       "phy_ports": [
         {
           "id": 0,
@@ -120,20 +125,7 @@ Response example
           "tx": 0,
           "tx_drop": 0
         },
-        {
-          "id": 2,
-          "rx": 0,
-          "rx_drop": 0,
-          "tx": 0,
-          "tx_drop": 0
-        },
-        {
-          "id": 3,
-          "rx": 0,
-          "rx_drop": 0,
-          "tx": 0,
-          "tx_drop": 0
-        }
+        ...
       ]
     }
 
-- 
2.7.4

[spp] [PATCH 2/4] docs: add launch of primary to REST API reference

[ogawa.yasufumi]

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

This patch is to add `launch` API for spp_primary which is for launching
a secondary process via REST API.

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

diff --git a/docs/guides/api_ref/spp_primary.rst b/docs/guides/api_ref/spp_primary.rst
index e46de21..3cbad10 100644
--- a/docs/guides/api_ref/spp_primary.rst
+++ b/docs/guides/api_ref/spp_primary.rst
@@ -174,3 +174,97 @@ Response
 ~~~~~~~~
 
 There is no body content for the response of a successful ``DELETE`` request.
+
+
+PUT /v1/primary/launch
+----------------------
+
+Launch a secondary process.
+
+* Normal response codes: 204
+* Error response codes: 400, 404
+
+
+Request (path)
+~~~~~~~~~~~~~~
+
+There is no params in this API.
+
+
+Request (body)
+~~~~~~~~~~~~~~
+
+There are four params for launching secondary process. ``eal`` object
+contains a set of EAL options, and ``app`` contains options of teh process.
+
+.. _table_spp_ctl_spp_primary_launch_body:
+
+.. table:: Request body params for launch secondary for spp_primary.
+
+    +-----------+---------+-------------------------------------------------+
+    | Name      | Type    | Description                                     |
+    |           |         |                                                 |
+    +===========+=========+=================================================+
+    | proc_name | string  | Process name such as ``spp_nfv`` or ``spp_vf``. |
+    +-----------+---------+-------------------------------------------------+
+    | client_id | integer | Secondary ID for the process.                   |
+    +-----------+---------+-------------------------------------------------+
+    | eal       | object  | Hash obj of DPDK's EAL options.                 |
+    +-----------+---------+-------------------------------------------------+
+    | app       | object  | Hash obj of options of secondary process.       |
+    +-----------+---------+-------------------------------------------------+
+
+``eal`` object is a hash of EAL options and its values. All of EAL options
+are referred in
+`EAL parameters
+<https://doc.dpdk.org/guides/linux_gsg/linux_eal_parameters.html>`_
+in DPDK's
+`Getting Started Guide for Linux
+<https://doc.dpdk.org/guides/linux_gsg/index.html>`_.
+
+``app`` object is a hash of options of secondary process, and you can refer
+options of each of processes in
+`How to Use
+<https://spp-tmp.readthedocs.io/en/latest/setup/howto_use.html>`_
+section.
+
+
+Request example
+~~~~~~~~~~~~~~~
+
+Launch ``spp_nfv`` with secondary ID 1 and lcores ``1,2``.
+
+.. code-block:: console
+
+    $ curl -X PUT -H 'application/json' \
+      -d "{'proc_name': 'spp_nfv', 'client_id': '1', \
+        'eal': {'-m': '512', '-l': '1,2', '--proc-type': 'secondary'}, \
+        'app': {'-s': '192.168.11.59:6666', '-n': '1'}}"
+      http://127.0.0.1:7777/v1/primary/launch
+
+Launch ``spp_vf`` with secondary ID 2 and lcores ``1,4-7``.
+
+.. code-block:: console
+
+    $ curl -X PUT -H 'application/json' \
+      -d "{'proc_name': 'spp_vf', 'client_id': '2', \
+        'eal': {'-m': '512', '-l': '1,4-7', '--proc-type': 'secondary'}, \
+        'app': {'-s': '192.168.11.59:6666', '--client-id': '2'}}"
+      http://127.0.0.1:7777/v1/primary/launch
+
+
+Response
+~~~~~~~~
+
+There is no body content for the response of a successful ``PUT`` request.
+
+
+Equivalent CLI command
+~~~~~~~~~~~~~~~~~~~~~~
+
+``proc_type`` is ``nfv``, ``vf`` or ``mirror`` or so.
+``eal_opts`` and ``app_opts`` are the same as launching from command line.
+
+.. code-block:: none
+
+    pri; launch {proc_type} {sec_id} {eal_opts} -- {app_opts}
-- 
2.7.4

[spp] [PATCH 3/4] docs: refactor spp_nfv REST API reference

[ogawa.yasufumi]

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

There are several invalid lines over the maximum 80 chars. This update
is to reduce the length of lines.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/api_ref/spp_vf.rst | 187 +++++++++++++++++++++--------------------
 1 file changed, 96 insertions(+), 91 deletions(-)

diff --git a/docs/guides/api_ref/spp_vf.rst b/docs/guides/api_ref/spp_vf.rst
index a600773..c406938 100644
--- a/docs/guides/api_ref/spp_vf.rst
+++ b/docs/guides/api_ref/spp_vf.rst
@@ -47,18 +47,18 @@ Response
 
 .. table:: Response params of getting spp_vf.
 
-    +------------------+---------+-----------------------------------------------+
-    | Name             | Type    | Description                                   |
-    |                  |         |                                               |
-    +==================+=========+===============================================+
-    | client-id        | integer | client id.                                    |
-    +------------------+---------+-----------------------------------------------+
-    | ports            | array   | an array of port ids used by the process.     |
-    +------------------+---------+-----------------------------------------------+
-    | components       | array   | an array of component objects in the process. |
-    +------------------+---------+-----------------------------------------------+
-    | classifier_table | array   | an array of classifier tables in the process. |
-    +------------------+---------+-----------------------------------------------+
+    +------------------+---------+--------------------------------------------+
+    | Name             | Type    | Description                                |
+    |                  |         |                                            |
+    +==================+=========+============================================+
+    | client-id        | integer | Client id.                                 |
+    +------------------+---------+--------------------------------------------+
+    | ports            | array   | Array of port ids used by the process.     |
+    +------------------+---------+--------------------------------------------+
+    | components       | array   | Array of component objects in the process. |
+    +------------------+---------+--------------------------------------------+
+    | classifier_table | array   | Array of classifier tables in the process. |
+    +------------------+---------+--------------------------------------------+
 
 Component objects:
 
@@ -66,20 +66,20 @@ Component objects:
 
 .. table:: Component objects of getting spp_vf.
 
-    +---------+---------+---------------------------------------------------------------------+
-    | Name    | Type    | Description                                                         |
-    |         |         |                                                                     |
-    +=========+=========+=====================================================================+
-    | core    | integer | core id running on the component                                    |
-    +---------+---------+---------------------------------------------------------------------+
-    | name    | string  | an array of port ids used by the process.                           |
-    +---------+---------+---------------------------------------------------------------------+
-    | type    | string  | an array of component objects in the process.                       |
-    +---------+---------+---------------------------------------------------------------------+
-    | rx_port | array   | an array of port objects connected to the rx side of the component. |
-    +---------+---------+---------------------------------------------------------------------+
-    | tx_port | array   | an array of port objects connected to the tx side of the component. |
-    +---------+---------+---------------------------------------------------------------------+
+    +---------+---------+--------------------------------------------------+
+    | Name    | Type    | Description                                      |
+    |         |         |                                                  |
+    +=========+=========+==================================================+
+    | core    | integer | Core id running on the component                 |
+    +---------+---------+--------------------------------------------------+
+    | name    | string  | Array of port ids used by the process.           |
+    +---------+---------+--------------------------------------------------+
+    | type    | string  | Array of component objects in the process.       |
+    +---------+---------+--------------------------------------------------+
+    | rx_port | array   | Array of port objs connected to rx of component. |
+    +---------+---------+--------------------------------------------------+
+    | tx_port | array   | Array of port objs connected to tx of component. |
+    +---------+---------+--------------------------------------------------+
 
 Port objects:
 
@@ -87,14 +87,14 @@ Port objects:
 
 .. table:: Port objects of getting spp_vf.
 
-    +---------+---------+---------------------------------------------------------------+
-    | Name    | Type    | Description                                                   |
-    |         |         |                                                               |
-    +=========+=========+===============================================================+
-    | port    | string  | port id. port id is the form {interface_type}:{interface_id}. |
-    +---------+---------+---------------------------------------------------------------+
-    | vlan    | object  | vlan operation which is applied to the port.                  |
-    +---------+---------+---------------------------------------------------------------+
+    +---------+---------+----------------------------------------------+
+    | Name    | Type    | Description                                  |
+    |         |         |                                              |
+    +=========+=========+==============================================+
+    | port    | string  | port id of {interface_type}:{interface_id}.  |
+    +---------+---------+----------------------------------------------+
+    | vlan    | object  | vlan operation which is applied to the port. |
+    +---------+---------+----------------------------------------------+
 
 Vlan objects:
 
@@ -119,16 +119,16 @@ Classifier table:
 
 .. table:: Vlan objects of getting spp_vf.
 
-    +-----------+--------+------------------------------------------------------------+
-    | Name      | Type   | Description                                                |
-    |           |        |                                                            |
-    +===========+========+============================================================+
-    | type      | string | ``mac`` or ``vlan``.                                       |
-    +-----------+--------+------------------------------------------------------------+
-    | value     | string | mac_address for ``mac``, vlan_id/mac_address for ``vlan``. |
-    +-----------+--------+------------------------------------------------------------+
-    | port      | string | port id applied to classify.                               |
-    +-----------+--------+------------------------------------------------------------+
+    +-----------+--------+-------------------------------------+
+    | Name      | Type   | Description                         |
+    |           |        |                                     |
+    +===========+========+=====================================+
+    | type      | string | ``mac`` or ``vlan``.                |
+    +-----------+--------+-------------------------------------+
+    | value     | string | mac_address or vlan_id/mac_address. |
+    +-----------+--------+-------------------------------------+
+    | port      | string | port id applied to classify.        |
+    +-----------+--------+-------------------------------------+
 
 
 Response example
@@ -273,20 +273,22 @@ Request (path)
 Request (body)
 ~~~~~~~~~~~~~~
 
+``type`` param is oen of ``forward``, ``merge`` or ``classifier_mac``.
+
 .. _table_spp_ctl_spp_vf_components_res:
 
 .. table:: Response params of components of spp_vf.
 
-    +-----------+---------+----------------------------------------------------------------------+
-    | Name      | Type    | Description                                                          |
-    |           |         |                                                                      |
-    +===========+=========+======================================================================+
-    | name      | string  | component name. must be unique in the process.                       |
-    +-----------+---------+----------------------------------------------------------------------+
-    | core      | integer | core id.                                                             |
-    +-----------+---------+----------------------------------------------------------------------+
-    | type      | string  | component type. one of ``forward``, ``merge`` or ``classifier_mac``. |
-    +-----------+---------+----------------------------------------------------------------------+
+    +-----------+---------+--------------------------------------------------+
+    | Name      | Type    | Description                                      |
+    |           |         |                                                  |
+    +===========+=========+==================================================+
+    | name      | string  | component name should be unique among processes. |
+    +-----------+---------+--------------------------------------------------+
+    | core      | integer | core id.                                         |
+    +-----------+---------+--------------------------------------------------+
+    | type      | string  | component type.                                  |
+    +-----------+---------+--------------------------------------------------+
 
 Request example
 ~~~~~~~~~~~~~~~
@@ -394,18 +396,18 @@ Request (body)
 
 .. table:: Request body params for ports of component of spp_vf.
 
-    +---------+---------+-----------------------------------------------------------------+
-    | Name    | Type    | Description                                                     |
-    |         |         |                                                                 |
-    +=========+=========+=================================================================+
-    | action  | string  | ``attach`` or ``detach``.                                       |
-    +---------+---------+-----------------------------------------------------------------+
-    | port    | string  | port id. port id is the form {interface_type}:{interface_id}.   |
-    +---------+---------+-----------------------------------------------------------------+
-    | dir     | string  | ``rx`` or ``tx``.                                               |
-    +---------+---------+-----------------------------------------------------------------+
-    | vlan    | object  | vlan operation which is applied to the port. it can be omitted. |
-    +---------+---------+-----------------------------------------------------------------+
+    +---------+---------+----------------------------------------------------+
+    | Name    | Type    | Description                                        |
+    |         |         |                                                    |
+    +=========+=========+====================================================+
+    | action  | string  | ``attach`` or ``detach``.                          |
+    +---------+---------+----------------------------------------------------+
+    | port    | string  | port id of {interface_type}:{interface_id}.        |
+    +---------+---------+----------------------------------------------------+
+    | dir     | string  | ``rx`` or ``tx``.                                  |
+    +---------+---------+----------------------------------------------------+
+    | vlan    | object  | vlan operation applied to port. it can be omitted. |
+    +---------+---------+----------------------------------------------------+
 
 Vlan object:
 
@@ -413,16 +415,16 @@ Vlan object:
 
 .. table:: Request body params for vlan ports of component of spp_vf.
 
-    +-----------+---------+----------------------------------------------------------+
-    | Name      | Type    | Description                                              |
-    |           |         |                                                          |
-    +===========+=========+==========================================================+
-    | operation | string  | ``add``, ``del`` or ``none``.                            |
-    +-----------+---------+----------------------------------------------------------+
-    | id        | integer | vlan id. ignored when operation is ``del`` or ``none``.  |
-    +-----------+---------+----------------------------------------------------------+
-    | pcp       | integer | vlan pcp. ignored when operation is ``del`` or ``none``. |
-    +-----------+---------+----------------------------------------------------------+
+    +-----------+---------+---------------------------------------------------+
+    | Name      | Type    | Description                                       |
+    |           |         |                                                   |
+    +===========+=========+===================================================+
+    | operation | string  | ``add``, ``del`` or ``none``.                     |
+    +-----------+---------+---------------------------------------------------+
+    | id        | integer | vid. ignored if operation is ``del`` or ``none``. |
+    +-----------+---------+---------------------------------------------------+
+    | pcp       | integer | pcp. ignored if operation is ``del`` or ``none``. |
+    +-----------+---------+---------------------------------------------------+
 
 
 Request example
@@ -500,24 +502,26 @@ Request (path)
 Request (body)
 ~~~~~~~~~~~~~~
 
+For ``vlan`` param, it can be omitted if it is for ``mac``.
+
 .. _table_spp_ctl_spp_vf_cls_table_body:
 
 .. table:: Request body params for classifier_table of spp_vf.
 
-    +-------------+-----------------+----------------------------------------------------+
-    | Name        | Type            | Description                                        |
-    |             |                 |                                                    |
-    +=============+=================+====================================================+
-    | action      | string          | ``add`` or ``del``.                                |
-    +-------------+-----------------+----------------------------------------------------+
-    | type        | string          | ``mac`` or ``vlan``.                               |
-    +-------------+-----------------+----------------------------------------------------+
-    | vlan        | integer or null | vlan id for ``vlan``. null or omitted for ``mac``. |
-    +-------------+-----------------+----------------------------------------------------+
-    | mac_address | string          | mac address.                                       |
-    +-------------+-----------------+----------------------------------------------------+
-    | port        | string          | port id.                                           |
-    +-------------+-----------------+----------------------------------------------------+
+    +-------------+-----------------+-----------------------------------------+
+    | Name        | Type            | Description                             |
+    |             |                 |                                         |
+    +=============+=================+=========================================+
+    | action      | string          | ``add`` or ``del``.                     |
+    +-------------+-----------------+-----------------------------------------+
+    | type        | string          | ``mac`` or ``vlan``.                    |
+    +-------------+-----------------+-----------------------------------------+
+    | vlan        | integer or null | vlan id for ``vlan``. null for ``mac``. |
+    +-------------+-----------------+-----------------------------------------+
+    | mac_address | string          | mac address.                            |
+    +-------------+-----------------+-----------------------------------------+
+    | port        | string          | port id.                                |
+    +-------------+-----------------+-----------------------------------------+
 
 
 Request example
@@ -529,7 +533,8 @@ the table.
 .. code-block:: console
 
     $ curl -X PUT -H 'application/json' \
-      -d '{"action": "add", "type": "mac", "mac_address": "FA:16:3E:7D:CC:35", \
+      -d '{"action": "add", "type": "mac", \
+         "mac_address": "FA:16:3E:7D:CC:35", \
          "port": "ring:0"}' \
       http://127.0.0.1:7777/v1/vfs/1/classifier_table
 
-- 
2.7.4

[spp] [PATCH 4/4] docs: add usage of server add command in usecase

[ogawa.yasufumi]

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

In `Multiple Nodes` section in usecase, add an example of adding nodes
by using `server add` command as usage.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/use_cases/multi_nodes.rst | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/guides/use_cases/multi_nodes.rst b/docs/guides/use_cases/multi_nodes.rst
index 6be567e..b44d0bd 100644
--- a/docs/guides/use_cases/multi_nodes.rst
+++ b/docs/guides/use_cases/multi_nodes.rst
@@ -49,8 +49,24 @@ for each of hosts. SPP CLI is able to be launched on any of nodes.
         -b 192.168.11.103 \
         -b 192.168.11.104 \
 
-If you succeeded to launch all of processes before, you can find them
-by running ``sever list`` command.
+Or you can add nodes after launching SPP CLI. Here is an example of
+launching it with first node, and adding the rest of nodes after.
+
+.. code-block:: console
+
+    # Launch SPP CLI
+    $ python src/spp.py -b 192.168.11.101
+    Welcome to the spp.  Type help or ? to list commands.
+
+    spp > server add 192.168.11.102
+    Registered spp-ctl "192.168.11.102:7777".
+    spp > server add 192.168.11.103
+    Registered spp-ctl "192.168.11.103:7777".
+    spp > server add 192.168.11.104
+    Registered spp-ctl "192.168.11.104:7777".
+
+If you have succeeded to launch all of ``spp-ctl`` processes before,
+you can find them by running ``sever list`` command.
 
 .. code-block:: console
 
-- 
2.7.4