* [spp] [PATCH 0/4] Revise help messages of commands and documentation
@ 2018-10-11 11:12 ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 1/4] controller: revise help messages ogawa.yasufumi
` (3 more replies)
0 siblings, 4 replies; 5+ messages in thread
From: ogawa.yasufumi @ 2018-10-11 11:12 UTC (permalink / raw)
To: spp, ferruh.yigit, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Revise help messages of SPP controller for updating old, adding new and
correcting wrong descriptions. Documents of commands are also revised
in this update.
Yasufumi Ogawa (4):
controller: revise help messages
docs: update primary command reference
docs: update secondary command reference
docs: update common command reference
docs/guides/commands/common.rst | 55 ++++++++++-----
docs/guides/commands/primary.rst | 29 ++++----
docs/guides/commands/secondary.rst | 84 ++++++++++++++---------
src/controller/shell.py | 134 ++++++++++++++++++++++++-------------
4 files changed, 199 insertions(+), 103 deletions(-)
--
2.7.4
^ permalink raw reply [flat|nested] 5+ messages in thread
* [spp] [PATCH 1/4] controller: revise help messages
2018-10-11 11:12 [spp] [PATCH 0/4] Revise help messages of commands and documentation ogawa.yasufumi
@ 2018-10-11 11:12 ` ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 2/4] docs: update primary command reference ogawa.yasufumi
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: ogawa.yasufumi @ 2018-10-11 11:12 UTC (permalink / raw)
To: spp, ferruh.yigit, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Revise help messages of SPP controller for updating old, adding new and
correcting wrong descriptions.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
src/controller/shell.py | 134 ++++++++++++++++++++++++++++++++----------------
1 file changed, 89 insertions(+), 45 deletions(-)
diff --git a/src/controller/shell.py b/src/controller/shell.py
index 8fb5a1a..3e0ca00 100644
--- a/src/controller/shell.py
+++ b/src/controller/shell.py
@@ -18,7 +18,7 @@ from . import topo
class Shell(cmd.Cmd, object):
- """SPP command prompt"""
+ """SPP command prompt."""
hist_file = '.spp_history'
@@ -51,7 +51,7 @@ class Shell(cmd.Cmd, object):
readline.write_history_file(hist_file)
def default(self, line):
- """Define defualt behaviour
+ """Define defualt behaviour.
If user input is commend styled, controller simply echo
as a comment.
@@ -64,7 +64,7 @@ class Shell(cmd.Cmd, object):
super(Shell, self).default(line)
def emptyline(self):
- """Do nothin for empty input
+ """Do nothin for empty input.
It override Cmd.emptyline() which runs previous input as default
to do nothing.
@@ -91,7 +91,7 @@ class Shell(cmd.Cmd, object):
self.hist_file)
def close_all_secondary(self):
- """Terminate all secondary processes"""
+ """Terminate all secondary processes."""
tmp_list = []
for i in spp_common.SECONDARY_LIST:
@@ -101,10 +101,14 @@ class Shell(cmd.Cmd, object):
spp_common.SECONDARY_COUNT = 0
def get_status(self):
- """Return status of primary and secondary processes
+ """Return the status of SPP processes.
- It is called from do_status() method and return primary status
- and a list of secondary processes as status.
+ Show the number of each of SPP processes running on.
+
+ spp > status
+ Soft Patch Panel Status :
+ primary: 1
+ secondary count: 2
"""
secondary = []
@@ -118,7 +122,7 @@ class Shell(cmd.Cmd, object):
return stat
def print_status(self):
- """Display information about connected clients"""
+ """Display information about connected clients."""
print("Soft Patch Panel Status :")
print("primary: %d" % spp_common.PRIMARY) # it is 1 if PRIMA == True
@@ -357,7 +361,7 @@ class Shell(cmd.Cmd, object):
self.response(self.CMD_OK, json.dumps(stat))
def do_pri(self, command):
- """Send command to primary process
+ """Send a command to primary process.
Spp primary takes sub commands.
@@ -392,14 +396,20 @@ class Shell(cmd.Cmd, object):
return completions
def do_sec(self, arg):
- """Send command to secondary process
+ """Send a command to secondary process specified with ID.
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
+ spp > sec 1; status
+ spp > sec 1; add ring:0
+ spp > sec 1; patch phy:0 ring:0
+
+ You can refer all of sub commands by pressing TAB after
+ 'sec 1;'.
+
+ spp > sec 1; # press TAB
+ add del exit forward patch status stop
"""
# remove unwanted spaces to avoid invalid command error
@@ -470,14 +480,13 @@ class Shell(cmd.Cmd, object):
print(e)
def do_record(self, fname):
- """Save commands to a log file
+ """Save commands as a recipe file.
- Save command history to a log file for loading from playback
- command later as a config file.
- Config is a series of SPP command and you can also create it
- from scratch without playback command.
+ Save all of commands to a specified file as a recipe. This file
+ is reloaded with 'playback' command later. You can also edit
+ the recipe by hand to customize.
- spp > record path/to/file
+ spp > record path/to/recipe_file
"""
if fname == '':
@@ -490,12 +499,12 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_playback(self, fname):
- """Load a config file to reproduce network configuration
+ """Setup a network configuration from recipe file.
- Config is a series of SPP command and you can also create it
- from scratch without playback command.
+ Recipe is a file describing a series of SPP command to setup
+ a network configuration.
- spp > playback path/to/config
+ spp > playback path/to/recipe_file
"""
if fname == '':
@@ -520,7 +529,7 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_pwd(self, args):
- """Show corrent directory
+ """Show corrent directory.
It behaves as UNIX's pwd command.
@@ -530,7 +539,7 @@ class Shell(cmd.Cmd, object):
print(os.getcwd())
def do_ls(self, args):
- """Show a list of specified directory
+ """Show a list of specified directory.
It behaves as UNIX's ls command.
@@ -547,7 +556,7 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_cd(self, args):
- """Change current directory
+ """Change current directory.
spp > cd path/to/dir
"""
@@ -562,9 +571,10 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line, 'directory')
def do_mkdir(self, args):
- """Create a new directory
+ """Create a new directory.
- It behaves as 'mkdir -p'.
+ It behaves as 'mkdir -p' which means that you can create sub
+ directories at once.
spp > mkdir path/to/dir
"""
@@ -576,9 +586,10 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_bye(self, arg):
- """Terminate SPP processes and controller
+ """Terminate SPP processes and controller.
- It also terminates logging if you activate recording.
+ There are three usages for terminating processes.
+ It terminates logging if you activated recording.
(1) Terminate secondary processes
spp > bye sec
@@ -627,7 +638,10 @@ class Shell(cmd.Cmd, object):
print("No such a directory.")
def do_redo(self, args):
- """Execute command of index of history."""
+ """Execute command of index of history.
+
+ spp > redo 5 # exec 5th command in the history
+ """
idx = int(args)
cmdline = None
@@ -651,12 +665,16 @@ class Shell(cmd.Cmd, object):
self.hist_file)
def do_history(self, arg):
- """Show history.
+ """Show command history.
spp > history
1 ls
2 cat file.txt
...
+
+ Command history is recorded in a file named '.spp_history'.
+ It does not add some command which are no meaning for history.
+ 'bye', 'exit', 'history', 'redo'
"""
# flush all of history to the hist_file.
@@ -688,7 +706,7 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_less(self, arg):
- """View contents of a file
+ """View contents of a file.
spp > less file
"""
@@ -702,11 +720,12 @@ class Shell(cmd.Cmd, object):
return common.compl_common(text, line)
def do_exit(self, args):
- """Terminate SPP controller
+ """Terminate SPP controller process.
- It is an alias for bye command and same as bye command.
+ It is an alias of bye command to terminate controller.
spp > exit
+ Thank you for using Soft Patch Panel
"""
self.close()
@@ -714,29 +733,45 @@ class Shell(cmd.Cmd, object):
return True
def do_inspect(self, args):
+ """Print attributes of Shell for debugging.
+
+ This command is intended to be used by developers to show the
+ inside of the object of Shell class.
+
+ spp > inspect
+ {'cmdqueue': [],
+ 'completekey': 'tab',
+ 'completion_matches': ['inspect'],
+ 'lastcmd': 'inspect',
+ 'old_completer': None,
+ 'stdin': <open file '<stdin>', mode 'r' at 0x7fe96bddf0c0>,
+ 'stdout': <open file '<stdout>', mode 'w' at 0x7fe96bddf150>}
+
+ """
+
from pprint import pprint
if args == '':
pprint(vars(self))
def terms_topo_subgraph(self):
- """Define terms of topo_subgraph command"""
+ """Define terms of topo_subgraph command."""
return ['add', 'del']
def do_topo_subgraph(self, args):
- """Subgarph manager for topo
+ """Edit subgarph for topo command.
- Subgraph is a group of object defined in dot language.
- For topo command, it is used for grouping resources of each
- of VM or container to topology be more understandable.
+ Subgraph is a group of object defined in dot language. For topo
+ command, it is used for grouping resources of each of VM or
+ container to topology be more understandable.
- Add subgraph labeled 'vm1'.
+ (1) Add subgraph labeled 'vm1'.
spp > topo_subgraph add vm1 vhost:1;vhost:2
- Delete subgraph 'vm1'.
+ (2) Delete subgraph 'vm1'.
spp > topo_subgraph del vm1
- To show subgraphs, run topo_subgraph without args.
+ (3) Show subgraphs by running topo_subgraph without args.
spp > topo_subgraph
label: vm1 subgraph: "vhost:1;vhost:2"
"""
@@ -801,6 +836,15 @@ class Shell(cmd.Cmd, object):
pass
def do_topo_resize(self, args):
+ """Change the size of the image of topo command.
+
+ You can specify the size by percentage or ratio.
+
+ spp > topo resize 60% # percentage
+ spp > topo resize 0.6 # ratio
+
+ """
+
if args == '':
print(self.topo_size)
else:
@@ -816,7 +860,7 @@ class Shell(cmd.Cmd, object):
print(self.topo_size)
def do_topo(self, args):
- """Output network topology
+ """Output network topology.
Support four types of output.
* terminal (but very few terminals supporting to display images)
@@ -900,7 +944,7 @@ class Shell(cmd.Cmd, object):
pass
def do_load_cmd(self, args):
- """Load command plugin
+ """Load command plugin.
Path of plugin file is 'spp/src/controller/command'.
--
2.7.4
^ permalink raw reply [flat|nested] 5+ messages in thread
* [spp] [PATCH 2/4] docs: update primary command reference
2018-10-11 11:12 [spp] [PATCH 0/4] Revise help messages of commands and documentation ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 1/4] controller: revise help messages ogawa.yasufumi
@ 2018-10-11 11:12 ` ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 3/4] docs: update secondary " ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 4/4] docs: update common " ogawa.yasufumi
3 siblings, 0 replies; 5+ messages in thread
From: ogawa.yasufumi @ 2018-10-11 11:12 UTC (permalink / raw)
To: spp, ferruh.yigit, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Update description of primary commands.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/commands/primary.rst | 29 +++++++++++++++++------------
1 file changed, 17 insertions(+), 12 deletions(-)
diff --git a/docs/guides/commands/primary.rst b/docs/guides/commands/primary.rst
index 0a338e9..85c1c68 100644
--- a/docs/guides/commands/primary.rst
+++ b/docs/guides/commands/primary.rst
@@ -38,29 +38,35 @@ Primary process is managed with ``pri`` command.
status
------
-Show status of primary.
+Show forwarding statistics of each of ports.
.. code-block:: console
- spp > pri status
- recv:('127.0.0.1', 50524):{Server Running}
-
+ spp > pri; status
+ Physical Ports:
+ ID rx tx tx_drop mac_addr
+ 0 78932932 78932931 1 56:48:4f:53:54:00
+ Ring Ports:
+ ID rx tx rx_drop tx_drop
+ 0 89283 89283 0 0
+ 1 9208 9203 0 5
+ ...
exit
----
-Terminate primary.
+Terminate primary process.
.. code-block:: console
- spp > pri exit
- closing:('127.0.0.1', 50524)
+ spp > pri; exit
.. note::
- You should not use this command because terminating primary before
- secondaries may cause an error.
- You shold use ``bye`` command instead of ``pri exit``.
+ You should not use this command if one or more secondary processes
+ are still running because terminating primary before secondaries may
+ cause an error. You shold use ``bye`` command instead of
+ ``pri; exit``.
clear
-----
@@ -69,5 +75,4 @@ Clear statistics.
.. code-block:: console
- spp > pri clear
- recv:('127.0.0.1', 50524):{clear stats}
+ spp > pri; clear
--
2.7.4
^ permalink raw reply [flat|nested] 5+ messages in thread
* [spp] [PATCH 3/4] docs: update secondary command reference
2018-10-11 11:12 [spp] [PATCH 0/4] Revise help messages of commands and documentation ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 1/4] controller: revise help messages ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 2/4] docs: update primary command reference ogawa.yasufumi
@ 2018-10-11 11:12 ` ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 4/4] docs: update common " ogawa.yasufumi
3 siblings, 0 replies; 5+ messages in thread
From: ogawa.yasufumi @ 2018-10-11 11:12 UTC (permalink / raw)
To: spp, ferruh.yigit, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Update description of secondary ommands.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/commands/secondary.rst | 84 ++++++++++++++++++++++++--------------
1 file changed, 53 insertions(+), 31 deletions(-)
diff --git a/docs/guides/commands/secondary.rst b/docs/guides/commands/secondary.rst
index d3566ad..0c4d417 100644
--- a/docs/guides/commands/secondary.rst
+++ b/docs/guides/commands/secondary.rst
@@ -29,7 +29,7 @@
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Secondary Commands
-======================
+==================
Each of secondary processes is managed with ``sec`` command.
It is for sending sub commands to secondary with specific ID called
@@ -44,48 +44,70 @@ owned by secondary process.
spp > sec [SEC_ID];[SUB_CMD]
+All of Sub commands are referred with ``help`` command.
+
+.. code-block:: console
+
+ spp > help sec
+
+ Send a command to secondary process specified with ID.
+
+ 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 phy:0 ring:0
+
+ You can refer all of sub commands by pressing TAB after
+ 'sec 1;'.
+
+ spp > sec 1; # press TAB
+ add del exit forward patch status stop
status
------
-Show running status and resources.
+Show running status and ports assigned to the process. If a port is
+patched to other port, source and destination ports are shown, or only
+source if it is not patched.
.. code-block:: console
- spp > sec 1;status
- status: idling
- ports:
- - 'phy:0'
- - 'phy:1'
+ spp > sec 1; status
+ - status: idling
+ - ports:
+ - phy:0 -> ring:0
+ - phy:1
add
---
-Add a PMD to the secondary with resource ID.
+Add a port to the secondary with resource ID.
-Adding ring 0 by
+For example, adding ``ring:0`` by
.. code-block:: console
- spp> sec 1;add ring 0
+ spp> sec 1; add ring:0
-Or adding vhost 0 by
+Or adding ``vhost:0`` by
.. code-block:: console
- spp> sec 1;add vhost 0
+ spp> sec 1; add vhost:0
patch
------
Create a path between two ports, source and destination ports.
-This command just creates path and does not start forwarding.
+This command just creates a path and does not start forwarding.
.. code-block:: console
- spp > sec 1;patch phy:0 ring:0
+ spp > sec 1; patch phy:0 ring:0
forward
@@ -95,18 +117,18 @@ Start forwarding.
.. code-block:: console
- spp > sec 1;forward
+ spp > sec 1; forward
Running status is changed from ``idling`` to ``running`` by
executing it.
.. code-block:: console
- spp > sec 1;status
- status: running
- ports:
- - 'phy:0'
- - 'phy:1'
+ spp > sec 1; status
+ - status: running
+ - ports:
+ - phy:0
+ - phy:1
stop
@@ -116,36 +138,36 @@ Stop forwarding.
.. code-block:: console
- spp > sec 1;stop
+ spp > sec 1; stop
Running status is changed from ``running`` to ``idling`` by
executing it.
.. code-block:: console
- spp > sec 1;status
- status: idling
- ports:
- - 'phy:0'
- - 'phy:1'
+ spp > sec 1; status
+ - status: idling
+ - ports:
+ - phy:0
+ - phy:1
del
---
-Delete PMD added by ``add`` subcommand from the secondary.
+Delete a port from the secondary.
.. code-block:: console
- spp> sec 1;del ring 0
+ spp> sec 1; del ring:0
exit
----
-Terminate the secondary. For terminating all secondaries, use ``bye sec``
-command instead of it.
+Terminate the secondary. For terminating all secondaries,
+use ``bye sec`` command instead of it.
.. code-block:: console
- spp> sec 1;exit
+ spp> sec 1; exit
--
2.7.4
^ permalink raw reply [flat|nested] 5+ messages in thread
* [spp] [PATCH 4/4] docs: update common command reference
2018-10-11 11:12 [spp] [PATCH 0/4] Revise help messages of commands and documentation ogawa.yasufumi
` (2 preceding siblings ...)
2018-10-11 11:12 ` [spp] [PATCH 3/4] docs: update secondary " ogawa.yasufumi
@ 2018-10-11 11:12 ` ogawa.yasufumi
3 siblings, 0 replies; 5+ messages in thread
From: ogawa.yasufumi @ 2018-10-11 11:12 UTC (permalink / raw)
To: spp, ferruh.yigit, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Update description of common commands.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/commands/common.rst | 55 ++++++++++++++++++++++++++++++-----------
1 file changed, 40 insertions(+), 15 deletions(-)
diff --git a/docs/guides/commands/common.rst b/docs/guides/commands/common.rst
index ebd1fa1..36573f5 100644
--- a/docs/guides/commands/common.rst
+++ b/docs/guides/commands/common.rst
@@ -30,7 +30,7 @@
Common Commands
-====================
+===============
status
------
@@ -48,16 +48,34 @@ It also show a list of secondary IDs
Connected secondary id: 2
+playback
+--------
+
+Restore network configuration from a recipe file which defines a set
+of SPP commands.
+You can prepare a recipe file by using ``record`` command or editing
+file by hand.
+
+It is recommended to use extension ``.rcp`` to be self-sxplanatory as
+a recipe, although you can use any of extensions such as ``.txt`` or
+``.log``.
+
+.. code-block:: console
+
+ spp > playback /path/to/my.rcp
+
+
record
------
-Start recording user's input and create a history file for ``playback``
-commnad.
-Recording is stopped by executing ``exit`` or ``playback`` command.
+Start recording user's input and create a recipe file for loading
+from ``playback`` commnad.
+Recording recipe is stopped by executing ``exit`` or ``playback``
+command.
.. code-block:: console
- spp > record 2nfv_uni.config
+ spp > record /path/to/my.rcp
.. note::
@@ -67,21 +85,28 @@ Recording is stopped by executing ``exit`` or ``playback`` command.
next relase.
-playback
---------
+history
+-------
-Restore configuration from a config file.
-Content of config file is just a series of SPP commnad.
-You prepare a config file by using ``record`` command or editing a text
-file by hand.
+Show command history. Command history is recorded in a file named
+``$HOME/.spp_history``. It does not add some command which are no
+meaning for history, ``bye``, ``exit``, ``history`` and ``redo``.
-It is recommended to use extension ``.config`` to be self-sxplanatory
-as a config, although you can use any of extensions such as ``.txt`` or
-``.log``.
+.. code-block:: console
+
+ spp > history
+ 1 ls
+ 2 cat file.txt
+
+
+redo
+----
+
+Execute command of index of history.
.. code-block:: console
- spp> playback 2nfv_uni.config
+ spp > redo 5 # exec 5th command in the history
pwd
--
2.7.4
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2018-10-11 11:12 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-10-11 11:12 [spp] [PATCH 0/4] Revise help messages of commands and documentation ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 1/4] controller: revise help messages ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 2/4] docs: update primary command reference ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 3/4] docs: update secondary " ogawa.yasufumi
2018-10-11 11:12 ` [spp] [PATCH 4/4] docs: update common " ogawa.yasufumi
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).