[spp] [PATCH 5/5] docs: add helper tools

[ogawa.yasufumi at lab.ntt.co.jp]

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

This update is to add description of helper tools in `Tools` chapter.
There are two helper tools currently.

* cpu_layout.py
* sec_launcher.py

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi at lab.ntt.co.jp>
---
 docs/guides/tools/helpers/index.rst |  15 +++++
 docs/guides/tools/helpers/tools.rst | 115 ++++++++++++++++++++++++++++++++++++
 docs/guides/tools/index.rst         |   1 +
 3 files changed, 131 insertions(+)
 create mode 100644 docs/guides/tools/helpers/index.rst
 create mode 100644 docs/guides/tools/helpers/tools.rst

diff --git a/docs/guides/tools/helpers/index.rst b/docs/guides/tools/helpers/index.rst
new file mode 100644
index 0000000..c03b552
--- /dev/null
+++ b/docs/guides/tools/helpers/index.rst
@@ -0,0 +1,15 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+
+.. _spp_tools_helpers_index:
+
+Helper tools
+============
+
+Helper tools are intended to be used from other programs, such as ``spp-ctl``
+or SPP CLI.
+
+.. toctree::
+    :maxdepth: 1
+
+    tools
diff --git a/docs/guides/tools/helpers/tools.rst b/docs/guides/tools/helpers/tools.rst
new file mode 100644
index 0000000..b435d5f
--- /dev/null
+++ b/docs/guides/tools/helpers/tools.rst
@@ -0,0 +1,115 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+
+.. _spp_tools_helpers_tools:
+
+CPU Layout
+==========
+
+This tool is a customized script of DPDK's user tool ``cpu_layout.py``. It is
+used from ``spp-ctl`` to get CPU layout. The behaviour of this script is same
+as original one if you just run on terminal.
+
+.. code-block:: console
+
+    $ python3 tools/helpers/cpu_layout.py
+    ======================================================================
+    Core and Socket Information (as reported by '/sys/devices/system/cpu')
+    ======================================================================
+
+    cores =  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+    sockets =  [0]
+
+            Socket 0
+            --------
+    Core 0  [0]
+    Core 1  [1]
+    ...
+
+Customized version of ``cpu_layout.py`` accepts an additional option
+``--json`` to output the result in JSON format.
+
+.. code-block:: console
+
+    # Output in JSON format
+    $ python3 tools/helpers/cpu_layout.py --json | jq
+    [
+      {
+        "socket_id": 0,
+        "cores": [
+          {
+            "core_id": 1,
+            "cpus": [
+              1
+            ]
+          },
+          {
+            "core_id": 0,
+            "cpus": [
+              0
+            ]
+          },
+          ...
+      }
+    ]
+
+You can almost the same result from ``spp-ctl``, but the order of params are
+just different.
+
+.. code-block:: console
+
+    # Retrieve CPU layout via REST API
+    $ curl -X GET http://192.168.1.100:7777/v1/cpus | jq
+      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                     Dload  Upload   Total   Spent    Left  Speed
+    100   505  100   505    0     0  18091      0 --:--:-- --:--:-- --:--:-- 18703
+    [
+      {
+        "cores": [
+          {
+            "cpus": [
+              1
+            ],
+            "core_id": 1
+          },
+          {
+            "cpus": [
+              0
+            ],
+            "core_id": 0
+          },
+          ...
+        ],
+        "socket_id": 0
+      }
+    ]
+
+
+Secondary Process Launcher
+==========================
+
+It is very simple python script used to lauch a secondary process from other
+program. It is intended to be used from spp_primary for launching. Here is
+whole lines of the script.
+
+.. code-block:: python
+
+    #!/usr/bin/env python
+    # coding: utf-8
+    """SPP secondary launcher."""
+
+    import sys
+    import subprocess
+
+    if len(sys.argv) > 1:
+        cmd = sys.argv[1:]
+        subprocess.call(cmd)
+
+As you may notice, it just runs given name or path of command with options,
+so you can any of command other than SPP secondary processes. However, it
+might be nouse for almost of users.
+
+The reason of why this script is required is to launch secondary process from
+``spp_primary`` indirectly to avoid launched secondaries to be zombies finally.
+In addtion, secondary processes other than ``spp_nfv`` do not work correctly
+after launched with execv() or other siblings directly from ``spp_primary``.
diff --git a/docs/guides/tools/index.rst b/docs/guides/tools/index.rst
index 445c486..c739d79 100644
--- a/docs/guides/tools/index.rst
+++ b/docs/guides/tools/index.rst
@@ -11,3 +11,4 @@ Tools
    :numbered:
 
    sppc/index
+   helpers/index
-- 
2.7.4