[spp] [PATCH 1/2] docs: add explanation of port number check

[spp] [PATCH 1/2] docs: add explanation of port number check

[x-fn-spp]

From: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>

There is a conditions where components of spp_vf and spp_mirror
starts packet forwarding. This patch adds those descriptions
into design section and also add explanation of check when adding port
to components in command reference section.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/commands/secondary/spp_mirror.rst | 13 +++++++++++++
 docs/guides/commands/secondary/spp_vf.rst     | 18 ++++++++++++++++++
 docs/guides/spp_vf/design.rst                 | 10 ++++++++--
 3 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/docs/guides/commands/secondary/spp_mirror.rst b/docs/guides/commands/secondary/spp_mirror.rst
index f81d3a9..bb60f05 100644
--- a/docs/guides/commands/secondary/spp_mirror.rst
+++ b/docs/guides/commands/secondary/spp_mirror.rst
@@ -198,6 +198,13 @@ by duplicating the packets.
     spp > mirror 2; port add vhost:0 tx mr1
     spp > mirror 2; port add vhost:1 tx mr1
 
+Adding port may cause component to start packet forwarding. Please see
+detail in
+:ref:`design spp_mirror<spp_vf_design_spp_mirror>`.
+
+Until one rx and two tx ports are registered, ``spp_mirror`` does not start
+forwarding. If it is requested to add more than one rx and two tx ports, it
+replies an error message.
 
 Deleting port
 ~~~~~~~~~~~~~
@@ -219,6 +226,12 @@ Here is some examples.
     # delete tx port 'vhost:1' from 'mr1'
     spp > mirror 2; port del vhost:1 tx mr1
 
+
+.. note::
+
+  Deleting port may cause component to stop packet forwarding.
+  Please see detail in :ref:`design spp_mirror<spp_vf_design_spp_mirror>`.
+
 exit
 ----
 
diff --git a/docs/guides/commands/secondary/spp_vf.rst b/docs/guides/commands/secondary/spp_vf.rst
index 6f1824b..d31688e 100644
--- a/docs/guides/commands/secondary/spp_vf.rst
+++ b/docs/guides/commands/secondary/spp_vf.rst
@@ -276,6 +276,20 @@ adds VLAN tag before sending packet outside.
     # add VLAN tag with VLAN ID and PCP in forwarder 'fw2'
     spp > vf 2; port add phy:1 tx fw2 add_vlantag 101 3
 
+Adding port may cause component to start packet forwarding. Please see
+detail in
+:ref:`design spp_vf<spp_vf_design_spp_vf>`.
+
+Until one rx port and one tx port are added, forwarder does not start packet
+forwarding. If it is requested to add more than one rx and one tx port, it
+replies an error message.
+Until at least one rx port and two tx ports are added, classifier does not
+start packet forwarding. If it is requested to add more than two rx ports, it
+replies an error message.
+Until at least two rx ports and one tx port are added, merger does not start
+packet forwarding. If it is requested to add more than two tx ports, it replies
+an error message.
+
 Deleting port
 ~~~~~~~~~~~~~
 
@@ -298,6 +312,10 @@ Here is an example.
     # delete tx port 'vhost:1' from 'mgr1'
     spp > vf 2; port del vhost:1 tx mgr1
 
+.. note::
+
+   Deleting port may cause component to stop packet forwarding.
+   Please see detail in :ref:`design spp_vf<spp_vf_design_spp_vf>`.
 
 .. _commands_spp_vf_classifier_table:
 
diff --git a/docs/guides/spp_vf/design.rst b/docs/guides/spp_vf/design.rst
index 23246ba..4774ef7 100644
--- a/docs/guides/spp_vf/design.rst
+++ b/docs/guides/spp_vf/design.rst
@@ -1,5 +1,5 @@
 ..  SPDX-License-Identifier: BSD-3-Clause
-    Copyright(c) 2019 Nippon Telegraph and Telephone Corporation
+    Copyright(c) 2010-2014 Intel Corporation
 
 .. _spp_vf_design:
 
@@ -37,12 +37,16 @@ Forwarder
 ^^^^^^^^^
 
 Simply forwards packets from rx to tx port.
+Forwarder does not start forwarding until when at least one rx and one tx are
+added.
 
 Merger
 ^^^^^^
 
 Receives packets from multiple rx ports to aggregate
 packets and sends to a desctination port.
+Merger does not start forwarding until when at least two rx and one tx are
+added.
 
 Classifier
 ^^^^^^^^^^
@@ -56,6 +60,8 @@ Classifier prepares tables for each of VLAN ID and decides
 which of table is referred
 if TPID (Tag Protocol Indetifier) is included in a packet and
 equals to 0x8100 as defined in IEEE 802.1Q standard.
+Classifier does not start forwarding until when at least one rx and two tx are
+added.
 
 .. _spp_vf_design_spp_mirror:
 
@@ -107,7 +113,7 @@ spp_pcap
 the second smallest ID and ``wirter`` threads on the rest of cores. You should
 have enough cores if you need to capture large amount of packets.
 
-``spp_pcap`` has 4 types of command. ``start``,``stop``,``exit`` and ``status``
+``spp_pcap`` has 4 types of command. ``start``, ``stop``, ``exit`` and ``status``
 to control behavior of ``spp_pcap``.
 
 With ``start`` command, you can start capturing.
-- 
2.17.1

[spp] [PATCH 2/2] docs: add data management for command process

[x-fn-spp]

From: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>

spp_vf and spp_mirror takes 2 step approach when reflecting
data after reception of command input.
This patch add explanation about with the actual code.

Signed-off-by: Hideyuki Yamashita <yamashita.hideyuki@po.ntt-tx.co.jp>
Signed-off-by: Naoki Takada <takada.naoki@lab.ntt.co.jp>
---
 docs/guides/spp_vf/explain/functions_vf.rst | 42 +++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/guides/spp_vf/explain/functions_vf.rst b/docs/guides/spp_vf/explain/functions_vf.rst
index c915655..46499db 100644
--- a/docs/guides/spp_vf/explain/functions_vf.rst
+++ b/docs/guides/spp_vf/explain/functions_vf.rst
@@ -421,3 +421,45 @@ For distributing multicast packet, it is cloned with
                             (long)classifier_info->active_classifieds[i]);
             }
     }
+
+Data management for command processing
+--------------------------------------
+``spp_vf`` has two data areas for for port, component and core.
+One is called reference area and other is called updating area.
+The reason is for having two data areas is that updating
+reference area which is referred by packet transmitting process
+directly may lead inconsistency when transmitting packet.
+When ``spp_vf`` process command, it changes pointer of reference
+area and updating area so that data which is referred by transmitting
+process is changed.
+
+The following code shows how flush is called inside spp_vf.
+You can read that data is flushed in the order of port, core and component.
+
+Note that ``spp_vf`` and ``spp_mirror`` has code logic in common and
+the above rule applies to also on ``spp_mirror``.
+
+.. code-block:: c
+
+        spp_flush(void)
+        {
+                int ret = SPP_RET_NG;
+                struct cancel_backup_info *backup_info = NULL;
+
+                spp_get_mng_data_addr(NULL, NULL, NULL,
+                                        NULL, NULL, NULL, &backup_info);
+
+                /* Initial setting of each interface. */
+                ret = flush_port();
+                        if (ret < SPP_RET_OK)
+                        return ret;
+
+                /* Flush of core index. */
+                flush_core();
+
+                /* Flush of component */
+                ret = flush_component();
+
+                backup_mng_info(backup_info);
+                return ret;
+        }
-- 
2.17.1