* [spp] [PATCH 1/3] docs: revise secondary commands section
2018-11-29 12:28 [spp] [PATCH 0/3] Update Secondary Commands section ogawa.yasufumi
@ 2018-11-29 12:28 ` ogawa.yasufumi
2018-11-29 12:28 ` [spp] [PATCH 2/3] docs: correct typos of spp_vf commands ogawa.yasufumi
2018-11-29 12:28 ` [spp] [PATCH 3/3] docs: add spp_mirror command reference ogawa.yasufumi
2 siblings, 0 replies; 4+ messages in thread
From: ogawa.yasufumi @ 2018-11-29 12:28 UTC (permalink / raw)
To: ferruh.yigit, spp, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Spp_vf command is moved to `spp.py` and used in the same way as spp_nfv.
This update is to revise `Secondary Commands` section and it is divided
into subsections `spp_nfv` and `spp_vf` by this update.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/commands/index.rst | 2 +-
docs/guides/commands/secondary.rst | 146 ------------
docs/guides/commands/secondary/index.rst | 12 +
docs/guides/commands/secondary/spp_nfv.rst | 146 ++++++++++++
docs/guides/commands/secondary/spp_vf.rst | 348 +++++++++++++++++++++++++++++
docs/guides/commands/spp_vf.rst | 348 -----------------------------
6 files changed, 507 insertions(+), 495 deletions(-)
delete mode 100644 docs/guides/commands/secondary.rst
create mode 100644 docs/guides/commands/secondary/index.rst
create mode 100644 docs/guides/commands/secondary/spp_nfv.rst
create mode 100644 docs/guides/commands/secondary/spp_vf.rst
delete mode 100644 docs/guides/commands/spp_vf.rst
diff --git a/docs/guides/commands/index.rst b/docs/guides/commands/index.rst
index 5a615c0..04442a3 100644
--- a/docs/guides/commands/index.rst
+++ b/docs/guides/commands/index.rst
@@ -12,7 +12,7 @@ controller.
:numbered:
primary
- secondary
+ secondary/index
spp_vf
common
experimental
diff --git a/docs/guides/commands/secondary.rst b/docs/guides/commands/secondary.rst
deleted file mode 100644
index bd4b964..0000000
--- a/docs/guides/commands/secondary.rst
+++ /dev/null
@@ -1,146 +0,0 @@
-.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2010-2014 Intel Corporation
-
-Secondary Commands
-==================
-
-Each of secondary processes is managed with ``sec`` command.
-It is for sending sub commands to secondary with specific ID called
-secondary ID.
-
-``sec`` command takes an secondary ID and a sub command. They must be
-separated with delimiter ``;``.
-Some of sub commands take additional arguments for speicfying resource
-owned by secondary process.
-
-.. code-block:: console
-
- 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 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 -> ring:0
- - phy:1
-
-
-add
----
-
-Add a port to the secondary with resource ID.
-
-For example, adding ``ring:0`` by
-
-.. code-block:: console
-
- spp> sec 1; add ring:0
-
-Or adding ``vhost:0`` by
-
-.. code-block:: console
-
- spp> sec 1; add vhost:0
-
-
-patch
-------
-
-Create a path between two ports, source and destination ports.
-This command just creates a path and does not start forwarding.
-
-.. code-block:: console
-
- spp > sec 1; patch phy:0 ring:0
-
-
-forward
--------
-
-Start forwarding.
-
-.. code-block:: console
-
- 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
-
-
-stop
-----
-
-Stop forwarding.
-
-.. code-block:: console
-
- 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
-
-
-del
----
-
-Delete a port from the secondary.
-
-.. code-block:: console
-
- spp> sec 1; del ring:0
-
-
-exit
-----
-
-Terminate the secondary. For terminating all secondaries,
-use ``bye sec`` command instead of it.
-
-.. code-block:: console
-
- spp> sec 1; exit
diff --git a/docs/guides/commands/secondary/index.rst b/docs/guides/commands/secondary/index.rst
new file mode 100644
index 0000000..81daf70
--- /dev/null
+++ b/docs/guides/commands/secondary/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2018 Nippon Telegraph and Telephone Corporation
+
+Secondary Commands
+==================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ spp_nfv
+ spp_vf
diff --git a/docs/guides/commands/secondary/spp_nfv.rst b/docs/guides/commands/secondary/spp_nfv.rst
new file mode 100644
index 0000000..794ead5
--- /dev/null
+++ b/docs/guides/commands/secondary/spp_nfv.rst
@@ -0,0 +1,146 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation
+
+spp_nfv
+=======
+
+Each of ``spp_nfv`` and ``spp_vm`` processes is managed with ``sec`` command.
+It is for sending sub commands to secondary with specific ID called
+secondary ID.
+
+``sec`` command takes an secondary ID and a sub command. They must be
+separated with delimiter ``;``.
+Some of sub commands take additional arguments for speicfying resource
+owned by secondary process.
+
+.. code-block:: console
+
+ 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 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 -> ring:0
+ - phy:1
+
+
+add
+---
+
+Add a port to the secondary with resource ID.
+
+For example, adding ``ring:0`` by
+
+.. code-block:: console
+
+ spp> sec 1; add ring:0
+
+Or adding ``vhost:0`` by
+
+.. code-block:: console
+
+ spp> sec 1; add vhost:0
+
+
+patch
+------
+
+Create a path between two ports, source and destination ports.
+This command just creates a path and does not start forwarding.
+
+.. code-block:: console
+
+ spp > sec 1; patch phy:0 ring:0
+
+
+forward
+-------
+
+Start forwarding.
+
+.. code-block:: console
+
+ 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
+
+
+stop
+----
+
+Stop forwarding.
+
+.. code-block:: console
+
+ 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
+
+
+del
+---
+
+Delete a port from the secondary.
+
+.. code-block:: console
+
+ spp> sec 1; del ring:0
+
+
+exit
+----
+
+Terminate the secondary. For terminating all secondaries,
+use ``bye sec`` command instead of it.
+
+.. code-block:: console
+
+ spp> sec 1; exit
diff --git a/docs/guides/commands/secondary/spp_vf.rst b/docs/guides/commands/secondary/spp_vf.rst
new file mode 100644
index 0000000..2ba2790
--- /dev/null
+++ b/docs/guides/commands/secondary/spp_vf.rst
@@ -0,0 +1,348 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation
+
+.. _commands_spp_vf:
+
+spp_vf
+======
+
+``spp_vf`` is a kind of SPP secondary process. It it introduced for
+providing SR-IOV like features.
+
+Each of ``spp_vf`` processes is managed with ``vf`` command. It is for
+sending sub commands with specific ID called secondary ID for changing
+configuration, assigning or releasing resources.
+
+Secondary ID is referred as ``--client-id`` which is given as an argument
+while launching ``spp_vf``. It should be unique among all of secondary
+processes including ``spp_nfv``, ``spp_vm`` and others.
+
+``vf`` command takes an secondary ID and one of sub commands. Secondary ID
+and sub command should be separated with delimiter ``;``, or failed to a
+command error. Some of sub commands take additional arguments for
+configuration of the process or its resource management.
+
+.. code-block:: console
+
+ spp > vf SEC_ID; SUB_CMD
+
+In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the
+following sub commands. Details of each of sub commands are described in the
+next sections.
+
+* status
+* component
+* port
+* classifier_table
+
+``spp_vf`` supports TAB completion. You can complete all of the name
+of commands and its arguments. For instance, you find all of sub commands
+by pressing TAB after ``vf SEC_ID;``.
+
+.. code-block:: console
+
+ spp > vf 1; # press TAB key
+ classifier_table component port status
+
+It tries to complete all of possible arguments. However, ``spp_vf`` takes
+also an arbitrary parameter which cannot be predicted, for example, name of
+component MAC address. In this cases, ``spp_vf`` shows capitalized keyword
+for indicating it is an arbitrary parameter. Here is an exmaple of
+``component`` command to initialize a worker thread. Keyword ``NAME`` should
+be replaced with your favorite name for the worker of the role.
+
+.. code-block:: console
+
+ spp > vf 1; component st # press TAB key to show args starting 'st'
+ start stop
+ spp > vf 1; component start NAME # 'NAME' is shown with TAB after start
+ spp > vf 1; component start fw1 # replace 'NAME' with your favorite name
+ spp > vf 1; component start fw1 # then, press TAB to show core IDs
+ 5 6 7 8
+
+It is another example of replacing keyword. ``port`` is a sub command for
+assigning a resource to a worker thread. ``RES_UID`` is replaced with
+resource UID which is a combination of port type and its ID such as
+``ring:0`` or ``vhost:1`` to assign it as RX port of forwarder ``fw1``.
+
+.. code-block:: console
+
+ spp > vf 1; port add RES_UID
+ spp > vf 1; port add ring:0 rx fw1
+
+If you are reached to the end of arguments, no candidate keyword is displayed.
+It is a completed statement of ``component`` command, and TAB
+completion does not work after ``forward`` because it is ready to run.
+
+.. code-block:: console
+
+ spp > vf 1; component start fw1 5 forward
+ Succeeded to start component 'fw1' on core:5
+
+It is also completed secondary IDs of ``spp_vf`` and it is helpful if you run
+several ``spp_vf`` processes.
+
+.. code-block:: console
+
+ spp > vf # press TAB after space following 'vf'
+ 1; 3; # you find two spp_vf processes of sec ID 1, 3
+
+By the way, it is also a case of no candidate keyword is displayed if your
+command statement is wrong. You might be encountered an error if you run the
+wrong command. Please take care.
+
+.. code-block:: console
+
+ spp > vf 1; compo # no candidate shown for wrong command
+ Invalid command "compo".
+
+
+.. _commands_spp_vf_status:
+
+status
+------
+
+Show the information of worker threads and its resources. Status information
+consists of three parts.
+
+.. code-block:: console
+
+ spp > vf 1; status
+ Basic Information:
+ - client-id: 3
+ - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4]
+ Classifier Table:
+ - C0:8E:CD:38:EA:A8, ring:4
+ - C0:8E:CD:38:BC:E6, ring:3
+ Components:
+ - core:5 'fw1' (type: forward)
+ - rx: ring:0
+ - tx: ring:1
+ - core:6 'mg' (type: merge)
+ - core:7 'cls' (type: classifier_mac)
+ - rx: ring:2
+ - tx: ring:3
+ - tx: ring:4
+ - core:8 '' (type: unuse)
+
+``Basic Information`` is for describing attributes of ``spp_vf`` itself.
+``client-id`` is a secondary ID of the process and ``ports`` is a list of
+all of ports owned the process.
+
+``Classifier Table`` is a list of entries of ``classifier_mac`` worker thread.
+Each of entry is a combination of MAC address and destination port which is
+assigned to this thread.
+
+``Components`` is a list of all of worker threads. Each of workers has a
+core ID running on, type of the worker and a list of resources.
+Entry of no name with ``unuse`` type means that no worker thread assigned to
+the core. In other words, it is ready to be assinged.
+
+
+.. _commands_spp_vf_component:
+
+component
+---------
+
+Assing or release a role of forwarding to worker threads running on each of
+cores which are reserved with ``-c`` or ``-l`` option while launching
+``spp_vf``. The role of the worker is chosen from ``forward``, ``merge`` or
+``classifier_mac``.
+
+``forward`` role is for simply forwarding from source port to destination port.
+On the other hands, ``merge`` role is for receiving packets from multiple ports
+as N:1 communication, or ``classifier_mac`` role is for sending packet to
+multiple ports by referring MAC address as 1:N communication.
+
+You are required to give an arbitrary name with as an ID for specifying the role.
+This name is also used while releasing the role.
+
+.. code-block:: console
+
+ # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME'
+ spp > vf SEC_ID; component start NAME CORE_ID ROLE
+
+ # release worker 'NAME' from the role
+ spp > vf SEC_ID; component stop NAME
+
+Here is some examples of assigning roles with ``component`` command.
+
+.. code-block:: console
+
+ # assign 'forward' role with name 'fw1' on core 2
+ spp > vf 2; component start fw1 2 forward
+
+ # assign 'merge' role with name 'mgr1' on core 3
+ spp > vf 2; component start mgr1 3 merge
+
+ # assign 'classifier_mac' role with name 'cls1' on core 4
+ spp > vf 2; component start cls1 4 classifier_mac
+
+Or examples of releasing roles.
+
+.. code-block:: console
+
+ # release roles
+ spp > vf 2; component stop fw1
+ spp > vf 2; component stop mgr1
+ spp > vf 2; component stop cls1
+
+
+.. _commands_spp_vf_port:
+
+port
+----
+
+Add or delete a port to a worker.
+
+Adding port
+~~~~~~~~~~~
+
+.. code-block:: console
+
+ spp > vf SEC_ID; port add RES_UID DIR NAME
+
+``RES_UID`` is with replaced with resource UID such as ``ring:0`` or
+``vhost:1``. ``spp_vf`` supports three types of port.
+
+ * ``phy`` : Physical NIC
+ * ``ring`` : Ring PMD
+ * ``vhost`` : Vhost PMD
+
+``DIR`` means the direction of forwarding and it should be ``rx`` or ``tx``.
+``NAME`` is the same as for ``component`` command.
+
+This is an example for adding ports to a classifer ``cls1``. In this case,
+it is configured to receive packets from ``phy:0`` and send it to ``ring:0``
+or ``ring:1``. The destination is decided with MAC address of the packets
+by referring the table. How to configure the table is described in
+:ref:`classifier_table<commands_spp_vf_classifier_table>` command.
+
+.. code-block:: console
+
+ # recieve from 'phy:0'
+ spp > vf 2; port add phy:0 rx cls1
+
+ # send to 'ring:0' and 'ring:1'
+ spp > vf 2; port add ring:0 tx cls1
+ spp > vf 2; port add ring:1 tx cls1
+
+``spp_vf`` also supports VLAN features, adding or deleting VLAN tag.
+It is used remove VLAN tags from incoming packets from outside of host
+machine, or add VLAN tag to outgoing packets.
+
+To configure VLAN features, use additional sub command ``add_vlantag``
+or ``del_vlantag`` followed by ``port`` sub command.
+
+To remove VLAN tag, simply add ``del_vlantag`` sub command without arguments.
+
+.. code-block:: console
+
+ spp > vf SEC_ID; port add RES_UID DIR NAME del_vlantag
+
+On the other hand, use ``add_vlantag`` which takes two arguments,
+``VID`` and ``PCP``, for adding VLAN tag to the packets.
+
+.. code-block:: console
+
+ spp > vf SEC_ID; port add RES_UID DIR NAME add_vlantag VID PCP
+
+``VID`` is a VLAN ID and ``PCP`` is a Priority Code Point defined in
+`IEEE 802.1p
+<https://1.ieee802.org/>`_.
+It is used for QoS by defining priority ranged from lowest prioroty
+``0`` to the highest ``7``.
+
+Here is an example of use of VLAN features considering a use case of
+a forwarder removes VLAN tag from incoming packets and another forwarder
+adds VLAN tag before sending packet outside.
+
+.. code-block:: console
+
+ # remove VLAN tag in forwarder 'fw1'
+ spp > vf 2; port add phy:0 rx fw1 del_vlantag
+
+ # add VLAN tag with VLAN ID and PCP in forwarder 'fw2'
+ spp > vf 2; port add phy:1 tx fw2 add_vlantag 101 3
+
+Deleting port
+~~~~~~~~~~~~~
+
+Delete a port which is not used anymore.
+
+.. code-block:: console
+
+ spp > sec SEC_ID; port del RES_UID DIR NAME
+
+It is same as the adding port, but no need to add additional sub command
+for VLAN features.
+
+Here is an example.
+
+.. code-block:: console
+
+ # delete rx port 'ring:0' from 'cls1'
+ spp > vf 2; port del rx cls1
+
+ # delete tx port 'vhost:1' from 'mgr1'
+ spp > vf 2; port del vhost:1 tx mgr1
+
+
+.. _commands_spp_vf_classifier_table:
+
+classifier_table
+----------------
+
+Register an entry of a combination of MAC address and port to
+a table of classifier.
+
+.. code-block:: console
+
+ # add entry
+ spp > vf SEC_ID; classifier_table add mac MAC_ADDR RES_UID
+
+ # delete entry
+ spp > vf SEC_ID; classifier_table del mac MAC_ADDRESS RES_ID
+
+This is an example to register MAC address ``52:54:00:01:00:01``
+with port ``ring:0``.
+
+.. code-block:: console
+
+ spp > vf 1; classifier_table add mac 52:54:00:01:00:01 ring:0
+
+Classifier supports the ``default`` entry for packets which does not
+match any of entries in the table. If you assign ``ring:1`` as default,
+simply specify ``default`` instead of MAC address.
+
+.. code-block:: console
+
+ spp > vf 1; classifier_table add mac default ring:1
+
+``classifier_table`` sub command also supports VLAN features as similar
+to ``port``.
+
+.. code-block:: console
+
+ # add entry with VLAN features
+ spp > vf SEC_ID; classifier_table add vlan VID MAC_ADDR RES_UID
+
+ # delete entry of VLAN
+ spp > vf SEC_ID; classifier_table del vlan VID MAC_ADDR RES_UID
+
+Here is an example for adding entries.
+
+.. code-block:: console
+
+ # add entry with VLAN tag
+ spp > vf 1; classifier_table add vlan 101 52:54:00:01:00:01 ring:0
+
+ # add entry of default with VLAN tag
+ spp > vf 1; classifier_table add vlan 101 default ring:1
+
+Delete an entryThis is an example to delete an entry for port ``ring:0``.
+
+.. code-block:: console
+
+ # delete entry with VLAN tag
+ spp > vf 1; classifier_table del vlan 101 52:54:00:01:00:01 ring:0
diff --git a/docs/guides/commands/spp_vf.rst b/docs/guides/commands/spp_vf.rst
deleted file mode 100644
index baa1e45..0000000
--- a/docs/guides/commands/spp_vf.rst
+++ /dev/null
@@ -1,348 +0,0 @@
-.. SPDX-License-Identifier: BSD-3-Clause
- Copyright(c) 2010-2014 Intel Corporation
-
-.. _commands_spp_vf:
-
-SPP VF
-======
-
-``spp_vf`` is a kind of SPP secondary process. It it introduced for
-providing SR-IOV like features.
-
-Each of ``spp_vf`` processes is managed with ``vf`` command. It is for
-sending sub commands with specific ID called secondary ID for changing
-configuration, assigning or releasing resources.
-
-Secondary ID is referred as ``--client-id`` which is given as an argument
-while launching ``spp_vf``. It should be unique among all of secondary
-processes including ``spp_nfv``, ``spp_vm`` and others.
-
-``vf`` command takes an secondary ID and one of sub commands. Secondary ID
-and sub command should be separated with delimiter ``;``, or failed to a
-command error. Some of sub commands take additional arguments for
-configuration of the process or its resource management.
-
-.. code-block:: console
-
- spp > vf SEC_ID; SUB_CMD
-
-In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the
-following sub commands. Details of each of sub commands are described in the
-next sections.
-
-* status
-* component
-* port
-* classifier_table
-
-``spp_vf`` supports TAB completion. You can complete all of the name
-of commands and its arguments. For instance, you find all of sub commands
-by pressing TAB after ``vf SEC_ID;``.
-
-.. code-block:: console
-
- spp > vf 1; # press TAB key
- classifier_table component port status
-
-It tries to complete all of possible arguments. However, ``spp_vf`` takes
-also an arbitrary parameter which cannot be predicted, for example, name of
-component MAC address. In this cases, ``spp_vf`` shows capitalized keyword
-for indicating it is an arbitrary parameter. Here is an exmaple of
-``component`` command to initialize a worker thread. Keyword ``NAME`` should
-be replaced with your favorite name for the worker of the role.
-
-.. code-block:: console
-
- spp > vf 1; component st # press TAB key to show args starting 'st'
- start stop
- spp > vf 1; component start NAME # 'NAME' is shown with TAB after start
- spp > vf 1; component start fw1 # replace 'NAME' with your favorite name
- spp > vf 1; component start fw1 # then, press TAB to show core IDs
- 5 6 7 8
-
-It is another example of replacing keyword. ``port`` is a sub command for
-assigning a resource to a worker thread. ``RES_UID`` is replaced with
-resource UID which is a combination of port type and its ID such as
-``ring:0`` or ``vhost:1`` to assign it as RX port of forwarder ``fw1``.
-
-.. code-block:: console
-
- spp > vf 1; port add RES_UID
- spp > vf 1; port add ring:0 rx fw1
-
-If you are reached to the end of arguments, no candidate keyword is displayed.
-It is a completed statement of ``component`` command, and TAB
-completion does not work after ``forward`` because it is ready to run.
-
-.. code-block:: console
-
- spp > vf 1; component start fw1 5 forward
- Succeeded to start component 'fw1' on core:5
-
-It is also completed secondary IDs of ``spp_vf`` and it is helpful if you run
-several ``spp_vf`` processes.
-
-.. code-block:: console
-
- spp > vf # press TAB after space following 'vf'
- 1; 3; # you find two spp_vf processes of sec ID 1, 3
-
-By the way, it is also a case of no candidate keyword is displayed if your
-command statement is wrong. You might be encountered an error if you run the
-wrong command. Please take care.
-
-.. code-block:: console
-
- spp > vf 1; compo # no candidate shown for wrong command
- Invalid command "compo".
-
-
-.. _commands_spp_vf_status:
-
-status
-------
-
-Show the information of worker threads and its resources. Status information
-consists of three parts.
-
-.. code-block:: console
-
- spp > vf 1; status
- Basic Information:
- - client-id: 3
- - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4]
- Classifier Table:
- - C0:8E:CD:38:EA:A8, ring:4
- - C0:8E:CD:38:BC:E6, ring:3
- Components:
- - core:5 'fw1' (type: forward)
- - rx: ring:0
- - tx: ring:1
- - core:6 'mg' (type: merge)
- - core:7 'cls' (type: classifier_mac)
- - rx: ring:2
- - tx: ring:3
- - tx: ring:4
- - core:8 '' (type: unuse)
-
-``Basic Information`` is for describing attributes of ``spp_vf`` itself.
-``client-id`` is a secondary ID of the process and ``ports`` is a list of
-all of ports owned the process.
-
-``Classifier Table`` is a list of entries of ``classifier_mac`` worker thread.
-Each of entry is a combination of MAC address and destination port which is
-assigned to this thread.
-
-``Components`` is a list of all of worker threads. Each of workers has a
-core ID running on, type of the worker and a list of resources.
-Entry of no name with ``unuse`` type means that no worker thread assigned to
-the core. In other words, it is ready to be assinged.
-
-
-.. _commands_spp_vf_component:
-
-component
----------
-
-Assing or release a role of forwarding to worker threads running on each of
-cores which are reserved with ``-c`` or ``-l`` option while launching
-``spp_vf``. The role of the worker is chosen from ``forward``, ``merge`` or
-``classifier_mac``.
-
-``forward`` role is for simply forwarding from source port to destination port.
-On the other hands, ``merge`` role is for receiving packets from multiple ports
-as N:1 communication, or ``classifier_mac`` role is for sending packet to
-multiple ports by referring MAC address as 1:N communication.
-
-You are required to give an arbitrary name with as an ID for specifying the role.
-This name is also used while releasing the role.
-
-.. code-block:: console
-
- # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME'
- spp > vf SEC_ID; component start NAME CORE_ID ROLE
-
- # release worker 'NAME' from the role
- spp > vf SEC_ID; component stop NAME
-
-Here is some examples of assigning roles with ``component`` command.
-
-.. code-block:: console
-
- # assign 'forward' role with name 'fw1' on core 2
- spp > vf 2; component start fw1 2 forward
-
- # assign 'merge' role with name 'mgr1' on core 3
- spp > vf 2; component start mgr1 3 merge
-
- # assign 'classifier_mac' role with name 'cls1' on core 4
- spp > vf 2; component start cls1 4 classifier_mac
-
-Or examples of releasing roles.
-
-.. code-block:: console
-
- # release roles
- spp > vf 2; component stop fw1
- spp > vf 2; component stop mgr1
- spp > vf 2; component stop cls1
-
-
-.. _commands_spp_vf_port:
-
-port
-----
-
-Add or delete a port to a worker.
-
-Adding port
-~~~~~~~~~~~
-
-.. code-block:: console
-
- spp > vf SEC_ID; port add RES_UID DIR NAME
-
-``RES_UID`` is with replaced with resource UID such as ``ring:0`` or
-``vhost:1``. ``spp_vf`` supports three types of port.
-
- * ``phy`` : Physical NIC
- * ``ring`` : Ring PMD
- * ``vhost`` : Vhost PMD
-
-``DIR`` means the direction of forwarding and it should be ``rx`` or ``tx``.
-``NAME`` is the same as for ``component`` command.
-
-This is an example for adding ports to a classifer ``cls1``. In this case,
-it is configured to receive packets from ``phy:0`` and send it to ``ring:0``
-or ``ring:1``. The destination is decided with MAC address of the packets
-by referring the table. How to configure the table is described in
-:ref:`classifier_table<commands_spp_vf_classifier_table>` command.
-
-.. code-block:: console
-
- # recieve from 'phy:0'
- spp > vf 2; port add phy:0 rx cls1
-
- # send to 'ring:0' and 'ring:1'
- spp > vf 2; port add ring:0 tx cls1
- spp > vf 2; port add ring:1 tx cls1
-
-``spp_vf`` also supports VLAN features, adding or deleting VLAN tag.
-It is used remove VLAN tags from incoming packets from outside of host
-machine, or add VLAN tag to outgoing packets.
-
-To configure VLAN features, use additional sub command ``add_vlantag``
-or ``del_vlantag`` followed by ``port`` sub command.
-
-To remove VLAN tag, simply add ``del_vlantag`` sub command without arguments.
-
-.. code-block:: console
-
- spp > vf SEC_ID; port add RES_UID DIR NAME del_vlantag
-
-On the other hand, use ``add_vlantag`` which takes two arguments,
-``VID`` and ``PCP``, for adding VLAN tag to the packets.
-
-.. code-block:: console
-
- spp > vf SEC_ID; port add RES_UID DIR NAME add_vlantag VID PCP
-
-``VID`` is a VLAN ID and ``PCP`` is a Priority Code Point defined in
-`IEEE 802.1p
-<https://1.ieee802.org/>`_.
-It is used for QoS by defining priority ranged from lowest prioroty
-``0`` to the highest ``7``.
-
-Here is an example of use of VLAN features considering a use case of
-a forwarder removes VLAN tag from incoming packets and another forwarder
-adds VLAN tag before sending packet outside.
-
-.. code-block:: console
-
- # remove VLAN tag in forwarder 'fw1'
- spp > vf 2; port add phy:0 rx fw1 del_vlantag
-
- # add VLAN tag with VLAN ID and PCP in forwarder 'fw2'
- spp > vf 2; port add phy:1 tx fw2 add_vlantag 101 3
-
-Deleting port
-~~~~~~~~~~~~~
-
-Delete a port which is not used anymore.
-
-.. code-block:: console
-
- spp > sec SEC_ID; port del RES_UID DIR NAME
-
-It is same as the adding port, but no need to add additional sub command
-for VLAN features.
-
-Here is an example.
-
-.. code-block:: console
-
- # delete rx port 'ring:0' from 'cls1'
- spp > vf 2; port del rx cls1
-
- # delete tx port 'vhost:1' from 'mgr1'
- spp > vf 2; port del vhost:1 tx mgr1
-
-
-.. _commands_spp_vf_classifier_table:
-
-classifier_table
-----------------
-
-Register an entry of a combination of MAC address and port to
-a table of classifier.
-
-.. code-block:: console
-
- # add entry
- spp > vf SEC_ID; classifier_table add mac MAC_ADDR RES_UID
-
- # delete entry
- spp > vf SEC_ID; classifier_table del mac MAC_ADDRESS RES_ID
-
-This is an example to register MAC address ``52:54:00:01:00:01``
-with port ``ring:0``.
-
-.. code-block:: console
-
- spp > vf 1; classifier_table add mac 52:54:00:01:00:01 ring:0
-
-Classifier supports the ``default`` entry for packets which does not
-match any of entries in the table. If you assign ``ring:1`` as default,
-simply specify ``default`` instead of MAC address.
-
-.. code-block:: console
-
- spp > vf 1; classifier_table add mac default ring:1
-
-``classifier_table`` sub command also supports VLAN features as similar
-to ``port``.
-
-.. code-block:: console
-
- # add entry with VLAN features
- spp > vf SEC_ID; classifier_table add vlan VID MAC_ADDR RES_UID
-
- # delete entry of VLAN
- spp > vf SEC_ID; classifier_table del vlan VID MAC_ADDR RES_UID
-
-Here is an example for adding entries.
-
-.. code-block:: console
-
- # add entry with VLAN tag
- spp > vf 1; classifier_table add vlan 101 52:54:00:01:00:01 ring:0
-
- # add entry of default with VLAN tag
- spp > vf 1; classifier_table add vlan 101 default ring:1
-
-Delete an entryThis is an example to delete an entry for port ``ring:0``.
-
-.. code-block:: console
-
- # delete entry with VLAN tag
- spp > vf 1; classifier_table del vlan 101 52:54:00:01:00:01 ring:0
--
2.7.4
^ permalink raw reply [flat|nested] 4+ messages in thread* [spp] [PATCH 3/3] docs: add spp_mirror command reference
2018-11-29 12:28 [spp] [PATCH 0/3] Update Secondary Commands section ogawa.yasufumi
2018-11-29 12:28 ` [spp] [PATCH 1/3] docs: revise secondary commands section ogawa.yasufumi
2018-11-29 12:28 ` [spp] [PATCH 2/3] docs: correct typos of spp_vf commands ogawa.yasufumi
@ 2018-11-29 12:28 ` ogawa.yasufumi
2 siblings, 0 replies; 4+ messages in thread
From: ogawa.yasufumi @ 2018-11-29 12:28 UTC (permalink / raw)
To: ferruh.yigit, spp, ogawa.yasufumi
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
This patch is to add spp_mirror commands to `Secondary Commands`
section.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/commands/secondary/index.rst | 1 +
docs/guides/commands/secondary/spp_mirror.rst | 220 ++++++++++++++++++++++++++
2 files changed, 221 insertions(+)
create mode 100644 docs/guides/commands/secondary/spp_mirror.rst
diff --git a/docs/guides/commands/secondary/index.rst b/docs/guides/commands/secondary/index.rst
index 81daf70..5c09d57 100644
--- a/docs/guides/commands/secondary/index.rst
+++ b/docs/guides/commands/secondary/index.rst
@@ -10,3 +10,4 @@ Secondary Commands
spp_nfv
spp_vf
+ spp_mirror
diff --git a/docs/guides/commands/secondary/spp_mirror.rst b/docs/guides/commands/secondary/spp_mirror.rst
new file mode 100644
index 0000000..7aab9d1
--- /dev/null
+++ b/docs/guides/commands/secondary/spp_mirror.rst
@@ -0,0 +1,220 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation
+
+.. _commands_spp_mirror:
+
+spp_mirror
+==========
+
+``spp_mirror`` is an implementation of TaaS feature as a SPP secondary process
+for port mirroring.
+
+Each of ``spp_mirror`` processes is managed with ``mirror`` command. Because
+basic design of ``spp_mirror`` is derived from ``spp_vf``, its commands are
+almost similar to ``spp_vf``.
+
+Secondary ID is referred as ``--client-id`` which is given as an argument
+while launching ``spp_mirror``. It should be unique among all of secondary
+processes including ``spp_nfv`` and others.
+
+``mirror`` command takes an secondary ID and one of sub commands. Secondary ID
+and sub command should be separated with delimiter ``;``, or failed to a
+command error. Some of sub commands take additional arguments for
+configuration of the process or its resource management.
+
+.. code-block:: console
+
+ spp > mirror SEC_ID; SUB_CMD
+
+In this example, ``SEC_ID`` is a secondary ID and ``SUB_CMD`` is one of the
+following sub commands. Details of each of sub commands are described in the
+next sections.
+
+* status
+* component
+* port
+
+``spp_mirror`` supports TAB completion. You can complete all of the name
+of commands and its arguments. For instance, you find all of sub commands
+by pressing TAB after ``mirror SEC_ID;``.
+
+.. code-block:: console
+
+ spp > mirror 1; # press TAB key
+ component port status
+
+It tries to complete all of possible arguments. However, ``spp_mirror`` takes
+also an arbitrary parameter which cannot be predicted, for example, name of
+component. In this cases, ``spp_mirror`` shows capitalized keyword for
+indicating it is an arbitrary parameter. Here is an exmaple of ``component``
+command to initialize a worker thread. Keyword ``NAME`` should be replaced with
+your favorite name for the worker of the role.
+
+.. code-block:: console
+
+ spp > mirror 1; component st # press TAB key to show args starting 'st'
+ start stop
+ spp > mirror 1; component start NAME # 'NAME' is shown with TAB after start
+ spp > mirror 1; component start mr1 # replace 'NAME' with favorite name
+ spp > mirror 1; component start mr1 # then, press TAB to show core IDs
+ 5 6 7
+
+It is another example of replacing keyword. ``port`` is a sub command for
+assigning a resource to a worker thread. ``RES_UID`` is replaced with
+resource UID which is a combination of port type and its ID such as
+``ring:0`` or ``vhost:1`` to assign it as RX port of forwarder ``mr1``.
+
+.. code-block:: console
+
+ spp > mirror 1; port add RES_UID
+ spp > mirror 1; port add ring:0 rx mr1
+
+If you are reached to the end of arguments, no candidate keyword is displayed.
+It is a completed statement of ``component`` command, and TAB
+completion does not work after ``mirror`` because it is ready to run.
+
+.. code-block:: console
+
+ spp > mirror 1; component start mr1 5 mirror
+ Succeeded to start component 'mr1' on core:5
+
+It is also completed secondary IDs of ``spp_mirror`` and it is helpful if you run
+several ``spp_mirror`` processes.
+
+.. code-block:: console
+
+ spp > mirror # press TAB after space following 'mirror'
+ 1; 3; # you find two spp_mirror processes of sec ID 1, 3
+
+By the way, it is also a case of no candidate keyword is displayed if your
+command statement is wrong. You might be encountered an error if you run the
+wrong command. Please take care.
+
+.. code-block:: console
+
+ spp > mirror 1; compa # no candidate shown for wrong command
+ Invalid command "compa".
+
+
+.. _commands_spp_mirror_status:
+
+status
+------
+
+Show the information of worker threads and its resources. Status information
+consists of three parts.
+
+.. code-block:: console
+
+ spp > vf 1; status
+ Basic Information:
+ - client-id: 3
+ - ports: [phy:0, phy:1, ring:0, ring:1, ring:2, ring:3, ring:4]
+ Components:
+ - core:5 'mr1' (type: mirror)
+ - rx: ring:0
+ - tx: [ring:1, ring:2]
+ - core:6 'mr2' (type: mirror)
+ - rx: ring:3
+ - tx: [ring:4, ring:5]
+ - core:7 '' (type: unuse)
+
+``Basic Information`` is for describing attributes of ``spp_mirror`` itself.
+``client-id`` is a secondary ID of the process and ``ports`` is a list of
+all of ports owned the process.
+
+``Components`` is a list of all of worker threads. Each of workers has a
+core ID running on, type of the worker and a list of resources.
+Entry of no name with ``unuse`` type means that no worker thread assigned to
+the core. In other words, it is ready to be assinged.
+
+
+.. _commands_spp_mirror_component:
+
+component
+---------
+
+Assing or release a role of forwarding to worker threads running on each of
+cores which are reserved with ``-c`` or ``-l`` option while launching
+``spp_mirror``. Unlike ``spp_vf``, ``spp_mirror`` only has one role, ``mirror``.
+
+.. code-block:: console
+
+ # assign 'ROLE' to worker on 'CORE_ID' with a 'NAME'
+ spp > mirror SEC_ID; component start NAME CORE_ID ROLE
+
+ # release worker 'NAME' from the role
+ spp > mirror SEC_ID; component stop NAME
+
+Here is some examples of assigning roles with ``component`` command.
+
+.. code-block:: console
+
+ # assign 'mirror' role with name 'mr1' on core 2
+ spp > mirror 2; component start mr1 2 mirror
+
+Or examples of releasing roles.
+
+.. code-block:: console
+
+ # release mirror role
+ spp > vf 2; component stop mr1
+
+
+.. _commands_spp_mirror_port:
+
+port
+----
+
+Add or delete a port to a worker.
+
+Adding port
+~~~~~~~~~~~
+
+.. code-block:: console
+
+ spp > vf SEC_ID; port add RES_UID DIR NAME
+
+``RES_UID`` is with replaced with resource UID such as ``ring:0`` or
+``vhost:1``. ``spp_mirror`` supports three types of port.
+
+ * ``phy`` : Physical NIC
+ * ``ring`` : Ring PMD
+ * ``vhost`` : Vhost PMD
+
+``DIR`` means the direction of forwarding and it should be ``rx`` or ``tx``.
+``NAME`` is the same as for ``component`` command.
+
+This is an example for adding ports to ``mr1``. In this case, it is configured
+to receive packets from ``ring:0`` and send it to ``vhost:0`` and ``vhost:1``
+by duplicating the packets.
+
+.. code-block:: console
+
+ # recieve from 'phy:0'
+ spp > mirror 2; port add ring:0 rx mr1
+
+ # send to 'ring:0' and 'ring:1'
+ spp > mirror 2; port add vhost:0 tx mr1
+ spp > mirror 2; port add vhost:1 tx mr1
+
+
+Deleting port
+~~~~~~~~~~~~~
+
+Delete a port which is not used anymore. It is almost same as adding port.
+
+.. code-block:: console
+
+ spp > mirror SEC_ID; port del RES_UID DIR NAME
+
+
+Here is an example.
+
+.. code-block:: console
+
+ # delete rx port 'ring:0' from 'mr1'
+ spp > mirror 2; port del ring:0 rx mr1
+
+ # delete tx port 'vhost:1' from 'mr1'
+ spp > mirror 2; port del vhost:1 tx mr1
--
2.7.4
^ permalink raw reply [flat|nested] 4+ messages in thread