[spp] [PATCH 2/2] docs: update spp_vf command

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

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

Revise descriptions and examples of spp_vf command.

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

diff --git a/docs/guides/commands/spp_vf.rst b/docs/guides/commands/spp_vf.rst
index 8e4a72a..aa2b1f4 100644
--- a/docs/guides/commands/spp_vf.rst
+++ b/docs/guides/commands/spp_vf.rst
@@ -3,245 +3,346 @@
 
 .. _commands_spp_vf:
 
-SPP VF Commands
-===============
+SPP VF
+======
 
-Each of secondary processes is managed with ``sec`` command.
-It is for sending sub commands to secondary with specific ID called
-secondary ID.
+``spp_vf`` is a kind of SPP secondary process. It it introduced for
+providing SR-IOV like features.
 
-``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.
+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 > sec [SID];[SUB_CMD]
+    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
-------
+* status
+* component
+* port
+* classifier_table
 
-Show running status and resources.
+``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 > sec 1;status
-    recv:7:{Client ID 1 Idling
-    1
-    port id: 0,on,PHY,outport: none
-    port id: 1,on,PHY,outport: none
-    }
-
+    spp > vf 1;  # press TAB key
+    classifier_table  component      port        status
 
-component
----------
+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.
 
-.. note::
-    This command is only supported for spp_vf.
+.. code-block:: console
 
-Start or stop a component. SPP VF provides three types of components,
-``forwarder``, ``classifier`` and ``merger``.
+    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
 
-``component start`` command creates and starts a component with given
-options.
+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 > sec [SID];component start [NAME] [CORE_ID] [DIRECTIVE]
-
-* ``NAME`` is used as an identifier of the component.
-* ``DIRECTIVE`` is a role of the component and corresponds to three types
-  of components.
+    spp > vf 1; port add RES_UID
+    spp > vf 1; port add ring:0 rx fw1
 
-  * forward
-  * merge
-  * classifier_mac
-
-This is an example for starting three types of components.
+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 > sec 1;component start forwarder1 2 forward
-    spp > sec 1;component start merger1 3 merge
-    spp > sec 1;component start classifier1 4 classifier_mac
+    spp > vf 1; component start fw1 5 forward
+    Succeeded to start component 'fw1' on core:5
 
-``component stop`` command terminates a component with given options
-same as ``component start`` command..
+It is also completed secondary IDs of ``spp_vf`` and it is helpful if you run
+several ``spp_vf`` processes.
 
 .. code-block:: console
 
-    spp > sec [SID];component stop [NAME] [CORE_ID] [DIRECTIVE]
+    spp > vf  # press TAB after space following 'vf'
+    1;  3;    # you find two spp_vf processes of sec ID 1, 3
 
-This is an example for stopping three types of components.
+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 > sec 1;component stop forwarder1 2 forward
-    spp > sec 1;component stop merger1 3 merge
-    spp > sec 1;component stop classifier1 4 classifier_mac
+    spp > vf 1; compo  # no candidate shown for wrong command
+    Invalid command "compo".
 
 
-port
-----
+.. _commands_spp_vf_status:
 
-.. note::
-    This command is only supported for spp_vf.
-
-Add a port to a component or delete it from.
-SPP VF is able to treat VLAN tag by adding port with VLAN options.
+status
+------
 
-``port add`` command adds a port to a component with given options.
+Show the information of worker threads and its resources. Status information
+consists of three parts.
 
 .. code-block:: console
 
-    spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME]
+    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:
 
-* ``RES_ID`` is a resource ID and defined as a combination of resource
-  type and number separated with delimiter ``:``.
-  There are three types of resources.
+component
+---------
 
-  * ``phy`` for physical NIC
-  * ``vhost`` for vhost PMD
-  * ``ring`` for ring PMD
+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``.
 
-* ``PORT_TYPE`` is ``rx`` or ``tx``.
-* ``NAME`` is used as an identifier of the component.
+``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.
 
-This is an example for adding port ``phy:0`` to ``classifier1`` as
-``rx`` and to ``merger1`` as ``tx``.
+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
 
-    spp > sec 1;port add phy:0 rx classifier1
-    spp > sec 1;port add phy:0 tx merger1
+    # 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
 
-For VLAN support, you need to add options for ``port add`` command.
-To add VLAN tag, additional option ``add_vlantag`` with its options
-``VID`` and ``PCP`` are required.
+Here is some examples of assigning roles with ``component`` command.
 
 .. code-block:: console
 
-    spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME] add_vlantag [VID] [PCP]
+    # assign 'forward' role with name 'fw1' on core 2
+    spp > vf 2; component start fw1 2 forward
 
-* ``PCP`` (Priority Code Point) is an attribute for priority defined in
-  IEEE 802.1p standard. It is ranged from 0 to 7 and
-  7 is the highest priority.
+    # assign 'merge' role with name 'mgr1' on core 3
+    spp > vf 2; component start mgr1 3 merge
 
-Or to delete VLAN tag, ``del_vlantag`` option is required.
+    # 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
 
-    spp > sec [SID];port add [RES_ID] [PORT_TYPE] [NAME] del_vlantag
+    # release roles
+    spp > vf 2; component stop fw1
+    spp > vf 2; component stop mgr1
+    spp > vf 2; component stop cls1
 
-This is an example for adding a port with ``add_vlantag`` or
-``del_vlantag``.
-In this case, add rx port to append VLAN ID 101 with PCP 3 and
-tx port to append VLAN ID 102 with PCP3.
 
-(1) Add VLAN tag
+.. _commands_spp_vf_port:
 
-.. code-block:: console
+port
+----
 
-    spp > sec 1;port add phy:0 rx classifier1 add_vlantag 101 3
-    spp > sec 1;port add phy:0 tx merger1 add_vlantag 102 3
+Add or delete a port to a worker.
 
-(2) Delete VLAN tag
+Adding port
+~~~~~~~~~~~
 
 .. code-block:: console
 
-    spp > sec 1;port add phy:0 rx classifier1 del_vlantag
-    spp > sec 1;port add phy:0 tx merger1 del_vlantag
+    spp > vf SEC_ID; port add RES_UID DIR NAME
 
-``port del`` command deletes a port from a component with given options
-same as ``port add`` command..
+``RES_UID`` is with replaced with resource UID such as ``ring:0`` or
+``vhost:1``. ``spp_vf`` supports three types of port.
 
-.. code-block:: console
+  * ``phy`` : Physical NIC
+  * ``ring`` : Ring PMD
+  * ``vhost`` : Vhost PMD
 
-    spp > sec [SID];port del [RES_ID] [PORT_TYPE] [NAME]
+``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 deleting port added in previous example.
+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
 
-    spp > sec 1;port del phy:0 rx classifier1
-    spp > sec 1;port del phy:0 tx merger1
+    # 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
 
-classifier_table
-----------------
+``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.
 
-.. note::
-    This command is only supported for spp_vf.
+To configure VLAN features, use additional sub command ``add_vlantag``
+or ``del_vlantag`` followed by ``port`` sub command.
 
-Register an entry as a combination of MAC address and resource ID
-to classifier table.
+To remove VLAN tag, simply add ``del_vlantag`` sub command without arguments.
 
 .. code-block:: console
 
-    spp > sec [SID];classifier_table add mac [MAC_ADDRESS] [RES_ID]
+    spp > vf SEC_ID; port add RES_UID DIR NAME del_vlantag
 
-This is an example to register MAC address ``52:54:00:01:00:01``
-with resource ID ``ring:0``.
+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 > sec 1;classifier_table add mac 52:54:00:01:00:01 ring:0
+    spp > vf SEC_ID; port add RES_UID DIR NAME add_vlantag VID PCP
 
-Here is another example in which using keyword ``default`` instead of
-``52:54:00:01:00:01``.
-``default`` is applied for packets which are not matched any of registered
-MAC addresses.
-In this case, all of not matched packets are sent to ``ring:0``.
+``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
 
-    spp > sec 0;classifier_table add mac default ring:0
+    # 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
+~~~~~~~~~~~~~
 
-Register an entry with a VLAN ID to classifier table.
+Delete a port which is not used anymore.
 
 .. code-block:: console
 
-    spp > sec 1;classifier_table add vlan [VID] [MAC_ADDRESS] [RES_ID]
+    spp > sec SEC_ID; port del RES_UID DIR NAME
 
-This is an example to register MAC address ``52:54:00:01:00:01``
-with VLAN ID and resource ID ``ring:0``.
+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
 
-    spp > sec 0;classifier_table add vlan 101 52:54:00:01:00:01 ring:0
+    # 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]
 
-Here is another example in which using keyword ``default`` instead of
-``52:54:00:01:00:01``.
-``default`` is applied for packets which are not matched any of registered
-MAC addresses for specified VLAN ID.
-In this case, all of not matched packets are sent to ``ring:0``.
+This is an example to register MAC address ``52:54:00:01:00:01``
+with port ``ring:0``.
 
 .. code-block:: console
 
-    spp > sec 0;classifier_table add vlan 101 default ring:1
+    spp > vf 1; classifier_table add mac 52:54:00:01:00:01 ring:0
 
-Delete an entry.
+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 > sec 1;classifier_table add del [MAC_ADDRESS] [RES_ID]
+    spp > vf 1; classifier_table add mac default ring:1
 
-This is an example to delete an entry for port ``ring:0``.
+``classifier_table`` sub command also supports VLAN features as similar
+to ``port``.
 
 .. code-block:: console
 
-    spp > sec 1;classifier_table del mac 52:54:00:01:00:01 ring:0
+    # add entry with VLAN features
+    spp > vf SEC_ID; classifier_table add vlan VID MAC_ADDR RES_UID
 
-Delete an entry with a VLAN ID.
+    # 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
 
-    spp > sec 1;classifier_table del vlan [VID] [MAC_ADDRESS] [RES_ID]
+    # 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
 
-This is an example to delete an entry with VLAN ID 101.
+Delete an entryThis is an example to delete an entry for port ``ring:0``.
 
 .. code-block:: console
 
-    spp > sec 0;classifier_table del vlan 101 52:54:00:01:00:01 ring:0
+    # delete entry with VLAN tag
+    spp > vf 1; classifier_table del vlan 101 52:54:00:01:00:01 ring:0
-- 
2.13.1