[spp] [PATCH 0/3] Update documents for SPP controller

[spp] [PATCH 0/3] Update documents for SPP controller

[ogawa.yasufumi]

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

Series of update for documents.

Yasufumi Ogawa (3):
  docs: add additional common commands
  docs: add experimental commands
  docs: fix typo of experimental command section

 docs/guides/commands/common.rst       |  90 ++++++++++++++++++++++++-
 docs/guides/commands/experimental.rst | 123 ++++++++++++++++++++++++++++++++++
 docs/guides/commands/index.rst        |   1 +
 3 files changed, 211 insertions(+), 3 deletions(-)
 create mode 100644 docs/guides/commands/experimental.rst

-- 
2.13.1

[spp] [PATCH 1/3] docs: add additional common commands

[ogawa.yasufumi]

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

SPP is updated to support for basic Linux commands, such as pwd, cd and
ls.

This update is for adding the new commands to common command section.

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

diff --git a/docs/guides/commands/common.rst b/docs/guides/commands/common.rst
index 719d663..ebd1fa1 100644
--- a/docs/guides/commands/common.rst
+++ b/docs/guides/commands/common.rst
@@ -43,7 +43,7 @@ It also show a list of secondary IDs
     spp > status
     Soft Patch Panel Status :
     primary: 1
-    secondary count: 4
+    secondary count: 2
     Connected secondary id: 1
     Connected secondary id: 2
 
@@ -84,6 +84,67 @@ as a config, although you can use any of extensions such as ``.txt`` or
     spp> playback 2nfv_uni.config
 
 
+pwd
+---
+
+Show current path.
+
+.. code-block:: console
+
+    spp> pwd
+    /path/to/curdir
+
+
+cd
+--
+
+Change current directory.
+
+.. code-block:: console
+
+    spp> cd /path/to/dir
+
+
+ls
+--
+
+Show a list of directory contents.
+
+.. code-block:: console
+
+    spp> ls /path/to/dir
+
+
+mkdir
+-----
+
+Make a directory.
+
+.. code-block:: console
+
+    spp> mkdir /path/to/dir
+
+
+cat
+---
+
+Show contents of a file.
+
+.. code-block:: console
+
+    spp> cat /path/to/file
+
+
+less
+----
+
+Show contents of a file.
+
+.. code-block:: console
+
+    spp> less /path/to/file
+
+
 bye
 ---
 
@@ -111,6 +172,18 @@ Second one is for all SPP processes other than controller.
     closing:('127.0.0.1', 53620)
 
 
+exit
+----
+
+Same as ``bye`` command but just for terminating SPP controller and
+not for other processes.
+
+.. code-block:: console
+
+    spp > exit
+    Thank you for using Soft Patch Panel
+
+
 help
 ----
 
@@ -122,9 +195,20 @@ Show help message for SPP commands.
 
     Documented commands (type help <topic>):
     ========================================
-    bye  help  playback  pri  record  sec  status
+    bye  cd    help  load_cmd  mkdir     pri  record  status  topo_subgraph
+    cat  exit  less  ls        playback  pwd  sec     topo
 
     spp > help status
-    Display Soft Patch Panel Status
+    Display status info of SPP processes
+
+        spp > status
+
     spp > help sec
     Send command to secondary process
+
+        SPP secondary process is specified with secondary ID and takes
+        sub commands.
+
+        spp > sec 1;status
+        spp > sec 1;add ring 0
+        spp > sec 1;patch 0 2
-- 
2.13.1

[spp] [PATCH 2/3] docs: add experimental commands

[ogawa.yasufumi]

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

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/experimental.rst | 122 ++++++++++++++++++++++++++++++++++
 docs/guides/commands/index.rst        |   1 +
 2 files changed, 123 insertions(+)
 create mode 100644 docs/guides/commands/experimental.rst

diff --git a/docs/guides/commands/experimental.rst b/docs/guides/commands/experimental.rst
new file mode 100644
index 0000000..e140263
--- /dev/null
+++ b/docs/guides/commands/experimental.rst
@@ -0,0 +1,122 @@
+..  BSD LICENSE
+    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Experimental Commands
+=====================
+
+There are experimental commands in SPP controller.
+It might not work for some cases properly because it is not well tested
+currently.
+
+topo
+----
+
+Output network topology in several formats.
+
+Support four types of output.
+* terminal (but very few terminals supporting to display images)
+* browser (websocket server is required)
+* image file (jpg, png, bmp)
+* text (dot, json, yaml)
+
+Most used format migth be ``term`` for output an image of network
+configuration in terminal.
+``topo`` command also show an image in a browser.
+
+This command uses `graphviz
+<https://www.graphviz.org/>`_
+for generating topology file and you can
+also generate a dot formatted file directory.
+
+There are some usecases.
+
+.. code-block:: console
+
+    spp > topo term  # terminal
+    spp > topo http  # browser
+    spp > topo network_conf.jpg  # image
+    spp > topo network_conf.dot  # text
+
+
+topo_subgraph
+-------------
+
+``topo_subgraph`` is a supplemental command for manageing subgraphs
+for ``topo``.
+
+Subgraph is a group of object defined in dot language. Grouping objects
+helps your understanding relationship or hierarchy of each of objects.
+For topo command, it is used for grouping resources of each
+of VM or container to topology be more understandable.
+
+For example, add subgraph labeled ``vm1`` for a VM which has two vhost
+interfaces ``VHOST1`` and ``VHOST2``.
+You do not need to use upper case for resource names because
+``topo_subgraph`` command capitalizes given names internally.
+
+.. code-block:: console
+
+    spp > topo_subgraph add vm1 VHOST1;VHOST2  # upper case
+    spp > topo_subgraph add vm1 vhost1;vhost2  # lower case
+
+If VM is shut down and subgraph is not needed anymore,
+delete subgraph 'vm1'.
+
+.. code-block:: console
+
+    spp > topo_subgraph del vm1
+
+To show all of subgraphs, run topo_subgraph without args.
+
+.. code-block:: console
+
+    spp > topo_subgraph
+    label: vm2    subgraph: "VHOST3;VHOST4"
+    label: vm1    subgraph: "VHOST1;VHOST2"
+
+
+load_cmd
+--------
+
+Load a command plugin dynamically while running SPP controller.
+
+
+Plugin file must be placed in ``spp/src/controller/command`` and
+command name must be the same as file name.
+For example, ``hello`` command is loaded from
+``spp/src/controller/command/hello.py``.
+
+.. code-block:: console
+
+    spp > load hello
+    Module 'command.hello' loaded.
+    spp > hello alice
+    Hello, alice!
diff --git a/docs/guides/commands/index.rst b/docs/guides/commands/index.rst
index 7526e68..a8574b6 100644
--- a/docs/guides/commands/index.rst
+++ b/docs/guides/commands/index.rst
@@ -41,3 +41,4 @@ controller.
    primary
    secondary
    common
+   experimental
-- 
2.13.1

[spp] [PATCH v2 2/3] docs: add experimental commands

[ogawa.yasufumi]

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

Correct license for previous version.

Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
 docs/guides/commands/experimental.rst | 123 ++++++++++++++++++++++++++++++++++
 docs/guides/commands/index.rst        |   1 +
 2 files changed, 124 insertions(+)
 create mode 100644 docs/guides/commands/experimental.rst

diff --git a/docs/guides/commands/experimental.rst b/docs/guides/commands/experimental.rst
new file mode 100644
index 0000000..651f896
--- /dev/null
+++ b/docs/guides/commands/experimental.rst
@@ -0,0 +1,123 @@
+..  BSD LICENSE
+    Copyright(c) 2017 Nippon Telegraph and Telephone Corporation
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Nippon Telegraph and Telephone Corporation
+    nor the names of its contributors may be used to endorse or
+    promote products derived from this software without specific
+    prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+Experimental Commands
+=====================
+
+There are experimental commands in SPP controller.
+It might not work for some cases properly because it is not well tested
+currently.
+
+topo
+----
+
+Output network topology in several formats.
+
+Support four types of output.
+* terminal (but very few terminals supporting to display images)
+* browser (websocket server is required)
+* image file (jpg, png, bmp)
+* text (dot, json, yaml)
+
+Most used format migth be ``term`` for output an image of network
+configuration in terminal.
+``topo`` command also show an image in a browser.
+
+This command uses `graphviz
+<https://www.graphviz.org/>`_
+for generating topology file and you can
+also generate a dot formatted file directory.
+
+There are some usecases.
+
+.. code-block:: console
+
+    spp > topo term  # terminal
+    spp > topo http  # browser
+    spp > topo network_conf.jpg  # image
+    spp > topo network_conf.dot  # text
+
+
+topo_subgraph
+-------------
+
+``topo_subgraph`` is a supplemental command for manageing subgraphs
+for ``topo``.
+
+Subgraph is a group of object defined in dot language. Grouping objects
+helps your understanding relationship or hierarchy of each of objects.
+For topo command, it is used for grouping resources of each
+of VM or container to topology be more understandable.
+
+For example, add subgraph labeled ``vm1`` for a VM which has two vhost
+interfaces ``VHOST1`` and ``VHOST2``.
+You do not need to use upper case for resource names because
+``topo_subgraph`` command capitalizes given names internally.
+
+.. code-block:: console
+
+    spp > topo_subgraph add vm1 VHOST1;VHOST2  # upper case
+    spp > topo_subgraph add vm1 vhost1;vhost2  # lower case
+
+If VM is shut down and subgraph is not needed anymore,
+delete subgraph 'vm1'.
+
+.. code-block:: console
+
+    spp > topo_subgraph del vm1
+
+To show all of subgraphs, run topo_subgraph without args.
+
+.. code-block:: console
+
+    spp > topo_subgraph
+    label: vm2    subgraph: "VHOST3;VHOST4"
+    label: vm1    subgraph: "VHOST1;VHOST2"
+
+
+load_cmd
+--------
+
+Load a command plugin dynamically while running SPP controller.
+
+
+Plugin file must be placed in ``spp/src/controller/command`` and
+command name must be the same as file name.
+For example, ``hello`` command is loaded from
+``spp/src/controller/command/hello.py``.
+
+.. code-block:: console
+
+    spp > load hello
+    Module 'command.hello' loaded.
+    spp > hello alice
+    Hello, alice!
diff --git a/docs/guides/commands/index.rst b/docs/guides/commands/index.rst
index 7526e68..a8574b6 100644
--- a/docs/guides/commands/index.rst
+++ b/docs/guides/commands/index.rst
@@ -41,3 +41,4 @@ controller.
    primary
    secondary
    common
+   experimental
-- 
2.13.1

[spp] [PATCH 3/3] docs: fix typo of experimental command section

[ogawa.yasufumi]

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

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

diff --git a/docs/guides/commands/experimental.rst b/docs/guides/commands/experimental.rst
index e140263..34c121d 100644
--- a/docs/guides/commands/experimental.rst
+++ b/docs/guides/commands/experimental.rst
@@ -42,6 +42,7 @@ topo
 Output network topology in several formats.
 
 Support four types of output.
+
 * terminal (but very few terminals supporting to display images)
 * browser (websocket server is required)
 * image file (jpg, png, bmp)
@@ -116,7 +117,7 @@ For example, ``hello`` command is loaded from
 
 .. code-block:: console
 
-    spp > load hello
+    spp > load_cmd hello
     Module 'command.hello' loaded.
     spp > hello alice
     Hello, alice!
-- 
2.13.1

Re: [spp] [PATCH 0/3] Update documents for SPP controller

[Ferruh Yigit]

On 3/6/2018 10:55 AM, ogawa.yasufumi@lab.ntt.co.jp wrote:
> From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
> 
> Series of update for documents.
> 
> Yasufumi Ogawa (3):
>   docs: add additional common commands
>   docs: add experimental commands
>   docs: fix typo of experimental command section

Series applied thanks.

(v2 of 2/3 merged)