[dts][PATCH V1 1/2] test_plans/vf_l2fwd: add vf_l2fwd test plan

[Yu Jiang <yux.jiang@intel.com>]

test_plans/vf_l2fwd: add vf_l2fwd test plan

Signed-off-by: Yu Jiang <yux.jiang@intel.com>
---
 test_plans/index.rst              |   1 +
 test_plans/vf_l2fwd_test_plan.rst | 133 ++++++++++++++++++++++++++++++
 2 files changed, 134 insertions(+)
 create mode 100644 test_plans/vf_l2fwd_test_plan.rst

diff --git a/test_plans/index.rst b/test_plans/index.rst
index 9ca954e2..8d54e8b6 100644
--- a/test_plans/index.rst
+++ b/test_plans/index.rst
@@ -203,6 +203,7 @@ The following are the test plans for the DPDK DTS automated test system.
     power_telemetry_test_plan
     power_throughput_test_plan
     vmdq_test_plan
+    vf_l2fwd_test_plan
     vf_l3fwd_test_plan
     softnic_test_plan
     vm_hotplug_test_plan
diff --git a/test_plans/vf_l2fwd_test_plan.rst b/test_plans/vf_l2fwd_test_plan.rst
new file mode 100644
index 00000000..95eb14ed
--- /dev/null
+++ b/test_plans/vf_l2fwd_test_plan.rst
@@ -0,0 +1,133 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2022 Intel Corporation
+
+======================
+VF L2 Forwarding Tests
+======================
+
+This test application is a basic packet processing application using Intel®
+DPDK. It is a layer-2 (L2) forwarding application which takes traffic from
+a single RX port and transmits it with few modification on a single TX port.
+
+For a packet received on a RX port (RX_PORT), it would be transmitted from a
+TX port (TX_PORT=RX_PORT+1) if RX_PORT is even; otherwise from a TX port
+(TX_PORT=RX_PORT-1) if RX_PORT is odd. Before being transmitted, the source
+mac address of the packet would be replaced by the mac address of the TX port,
+while the destination mac address would be replaced by 00:09:c0:00:00:TX_PORT_ID.
+
+The test application should be run with the wanted paired ports configured using
+the coremask parameter via the command line. i.e. port 0 and 1 is a valid pair,
+while port 1 and 2 isn't. The test is performed by running the test application
+and using a traffic generator. Tests are run with receiving a variety of size of
+packets generated by the traffic generator and forwarding back to the traffic
+generator. The packet loss and the throughput are the right ones need to be
+measured.
+These tests use l2fwd as a simple forwarder between NIC vfs.
+
+The ``l2fwd`` application is run with EAL parameters and parameters for
+the application itself. For details about the EAL parameters, see the relevant
+DPDK **Getting Started Guide**.
+http://doc.dpdk.org/guides/sample_app_ug/l2_forward_real_virtual.html?highlight=l2fwd
+
+The application requires a number of command line options:
+
+./<build_dir>/examples/dpdk-l2fwd [EAL options] -- -p PORTMASK
+                               [-P]
+                               [-q NQ]
+                               --[no-]mac-updating
+                               [--portmap="(port, port)[,(port, port)]"]
+
+``-p PORTMASK``: A hexadecimal bitmask of the ports to configure
+``-P``: Optional, set all ports to promiscuous mode so that packets are accepted regardless of the MAC destination address.
+Without this option, only packets with the MAC destination address set to the Ethernet address of the port are accepted.
+``-q NQ``: A number of queues (=ports) per lcore (default is 1)
+``--[no-]mac-updating``: Enable or disable MAC addresses updating (enabled by default)
+``--portmap=”(port,port)[,(port,port)]``: Determines forwarding ports mapping.
+
+Prerequisites
+=============
+
+If using vfio the kernel must be >= 3.6+ and VT-d must be enabled in bios.When
+using vfio, use the following commands to load the vfio driver and bind it
+to the device under test::
+
+   modprobe vfio
+   modprobe vfio-pci
+   usertools/dpdk-devbind.py --bind=vfio-pci device_bus_id
+
+Assume port 0 and 1 are connected to the traffic generator, to run the test
+application in linuxapp environment with 4 lcores, 2 ports and 8 RX queues
+per lcore::
+
+    $ ./x86_64-native-linuxapp-gcc/examples/dpdk-l2fwd -n 1-4 -c 0xf -- -q 8 -p 0x3
+
+Also, if the ports to be tested are different, the port mask should be changed.
+The lcore used to run the test application and the number of queue used for a
+lcore could be changed. For benchmarking, the EAL parameters and the parameters
+for the application itself for different test cases should be the same.
+This application may be used for basic VM to VM communication too.
+
+Topology
+--------
+DUT port 0 <----> Tester port A
+DUT port 1 <----> Tester port B
+
+Hardware
+--------
+Supported NICs
+
+Software
+--------
+
+dpdk: http://dpdk.org/git/dpdk
+scapy: http://www.secdev.org/projects/scapy/
+
+General set up
+--------------
+Compile DPDK and l2fwd app::
+
+    CC=gcc meson --werror -Denable_kmods=True -Dlibdir=lib --default-library=static x86_64-native-linuxapp-gcc
+    ninja -C x86_64-native-linuxapp-gcc -j 110
+    meson configure -Dexamples=l2fwd x86_64-native-linuxapp-gcc
+    ninja -C x86_64-native-linuxapp-gcc
+    ls x86_64-native-linuxapp-gcc/examples/dpdk-l2fwd
+
+Get the pci device id of DUT, for example::
+
+    ./usertools/dpdk-devbind.py -s
+
+    0000:18:00.0 'Device 159b' if=ens785f0 drv=ice unused=vfio-pci
+    0000:18:00.1 'Device 159b' if=ens785f1 drv=ice unused=vfio-pci
+
+Generate 1 VF on each PF::
+
+    echo 1 > /sys/bus/pci/devices/0000:18:00.0/sriov_numvfs
+    echo 1 > /sys/bus/pci/devices/0000:18:00.1/sriov_numvfs
+
+Set mac addr for VFs::
+
+    ip link set ens785f0 vf 0 mac 00:11:22:33:44:55
+    ip link set ens785f1 vf 0 mac 00:11:22:33:44:11
+
+Bind VFs to dpdk driver::
+
+    modprobe vfio-pci
+    ./usertools/dpdk-devbind.py -b vfio-pci 0000:18:01.0 0000:18:02.0
+
+
+Test Case: Port testing
+=======================
+
+Assume ``port A`` on packet generator connects to NIC ``port 0``, while ``port B``
+on packet generator connects to NIC ``port 1``. Set the destination mac address
+of the packet stream to be sent out from ``port A`` to the mac address of
+``port 0``, while the destination mac address of the packet stream to be sent out
+from ``port B`` to the mac address of ``port 1``. Other parameters of the packet
+stream could be anything valid. Then run the test application as below::
+
+    $ ./x86_64-native-linuxapp-gcc/examples/dpdk-l2fwd -n 4 -c 0xf -a <device_bus_id> -a <device_bus_id> -- -q [1|2|4|8] -p 0x3
+
+Trigger the packet generator of bursting packets from ``port A``, then check if
+``port 0`` could receive them and ``port 1`` could forward them back. Stop it
+and then trigger the packet generator of bursting packets from ``port B``, then
+check if ``port 1`` could receive them and ``port 0`` could forward them back.
-- 
2.25.1