[spp] [PATCH 0/3] Update Secondary Commands section

[spp] [PATCH 0/3] Update Secondary Commands section

[ogawa.yasufumi]

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

Hi,

This series of patches is to update `Secondary Commands` section in the
command reference. It is because SPP has several types of secondary
process and it can be managed from spp-ctl and spp.py, so I think now it
the time to update this section.

By this update, spp_vf commands are moved to `Secondary Commands`.
Spp_mirror introduced recently is also added to this section. It also
includes to correct typos in examples of spp_vf commands.

Thanks,
Yasufumi

Yasufumi Ogawa (3):
  docs: revise secondary commands section
  docs: correct typos of spp_vf commands
  docs: add spp_mirror command reference

 docs/guides/commands/index.rst                |   2 +-
 docs/guides/commands/secondary.rst            | 146 -----------
 docs/guides/commands/secondary/index.rst      |  13 +
 docs/guides/commands/secondary/spp_mirror.rst | 220 ++++++++++++++++
 docs/guides/commands/secondary/spp_nfv.rst    | 146 +++++++++++
 docs/guides/commands/secondary/spp_vf.rst     | 348 ++++++++++++++++++++++++++
 docs/guides/commands/spp_vf.rst               | 348 --------------------------
 7 files changed, 728 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_mirror.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

-- 
2.7.4

[spp] [PATCH 1/3] docs: revise secondary commands section

[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

[spp] [PATCH 2/3] docs: correct typos of spp_vf commands

[ogawa.yasufumi]

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

Modify two typos in command examples in `Deleting port` subsection.

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

diff --git a/docs/guides/commands/secondary/spp_vf.rst b/docs/guides/commands/secondary/spp_vf.rst
index 2ba2790..2ffe237 100644
--- a/docs/guides/commands/secondary/spp_vf.rst
+++ b/docs/guides/commands/secondary/spp_vf.rst
@@ -272,7 +272,7 @@ Delete a port which is not used anymore.
 
 .. code-block:: console
 
-    spp > sec SEC_ID; port del RES_UID DIR NAME
+    spp > vf 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.
@@ -282,7 +282,7 @@ Here is an example.
 .. code-block:: console
 
     # delete rx port 'ring:0' from 'cls1'
-    spp > vf 2; port del rx cls1
+    spp > vf 2; port del ring:0 rx cls1
 
     # delete tx port 'vhost:1' from 'mgr1'
     spp > vf 2; port del vhost:1 tx mgr1
-- 
2.7.4

[spp] [PATCH 3/3] docs: add spp_mirror command reference

[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