Re: [dts] [PATCH V1] test_plans:add test plan about multicast

["Tu, Lijuan" <lijuan.tu@intel.com>]

Applied, thanks

> -----Original Message-----
> From: dts [mailto:dts-bounces@dpdk.org] On Behalf Of changqingxwu
> Sent: Friday, August 9, 2019 4:05 PM
> To: dts@dpdk.org
> Cc: Wu, ChangqingX <changqingx.wu@intel.com>
> Subject: [dts] [PATCH V1] test_plans:add test plan about multicast
> 
> Signed-off-by: changqingxwu <changqingx.wu@intel.com>
> ---
>  test_plans/multicast_test_plan.rst | 321 +++++++++++++++++++++++++++++
>  1 file changed, 321 insertions(+)
>  create mode 100644 test_plans/multicast_test_plan.rst
> 
> diff --git a/test_plans/multicast_test_plan.rst
> b/test_plans/multicast_test_plan.rst
> new file mode 100644
> index 0000000..f52dd9c
> --- /dev/null
> +++ b/test_plans/multicast_test_plan.rst
> @@ -0,0 +1,321 @@
> +.. Copyright (c) <2019>, Intel Corporation
> +   All rights reserved.
> +
> +   Redistribution and use in source and binary forms, with or without
> +   modification, are permitted provided that the following conditions
> +   are met:
> +
> +   - Redistributions of source code must retain the above copyright
> +     notice, this list of conditions and the following disclaimer.
> +
> +   - Redistributions in binary form must reproduce the above copyright
> +     notice, this list of conditions and the following disclaimer in
> +     the documentation and/or other materials provided with the
> +     distribution.
> +
> +   - Neither the name of Intel Corporation nor the names of its
> +     contributors may be used to endorse or promote products derived
> +     from this software without specific prior written permission.
> +
> +   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
> CONTRIBUTORS
> +   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
> +   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
> FITNESS
> +   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
> +   COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
> INDIRECT,
> +   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
> +   (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
> OR
> +   SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
> +   HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
> CONTRACT,
> +   STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
> +   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
> ADVISED
> +   OF THE POSSIBILITY OF SUCH DAMAGE.
> +
> +==============
> +IPv4 Multicast
> +==============
> +
> +This is the test plan for the Intel® DPDK IPv4 Multicast application.
> +The results are produced using the ``ipv4_fragmentation`` application.
> +
> +Description
> +-----------
> +
> +The test application (``ipv4_multicast``) implements a basic Layer-3
> +forwarding scheme on the traffic received from two network interfaces.
> +For each input packet, the output interface the packet should be sent
> +out on is determined based on a lookup operation into the routing table
> maintained by the application.
> +
> +This application disregards the rules for multicast groups assigned by
> +IANA (RFC 5771) and only sets a goal to demonstrate a sample multicast
> implementation.
> +
> +The ``ipv4_multicast`` application accepts the following command line
> options:
> +
> +- For the EAL:
> +
> +  - ``-c COREMASK``: Hexadecimal bitmask of cores we are running on
> +  - ``-m MB``: Memory to allocate (default 64MB)
> +  - ``-n NUM``: Number of memory channels (don't detect)
> +  - ``-r NUM``: Number of memory ranks (don't detect)
> +
> +- And for the application itself (seperated by ``--`` from above options):
> +
> +  - ``-p PORTMASK``: Hexadecimal bitmask of ports to use
> +  - ``-q NUM``: Number of queues per lcore
> +
> +
> +Prerequisites
> +=============
> +
> +1. Hardware requirements:
> +
> +- Board is populated with 2x 10GbE ports. Special PCIe restrictions may
> +  be required for performance. For example, the following requirements
> +should be
> +  met for Intel 82599 (Niantic) NICs:
> +
> +	- NICs are plugged into PCIe Gen2 or Gen3 slots
> +	- For PCIe Gen2 slots, the number of lanes should be 8x or higher
> +	- A single port from each NIC should be used, so for 4x ports, 4x NICs
> should
> +	  be used
> +
> +- NIC ports connected to traffic generator. It is assumed that the NIC
> +ports
> +  P0 and P2 (as identified by the DPDK application) are connected to
> +the
> +  traffic generator ports TG0 and TG2. The application-side port mask
> +of
> +  NIC ports is noted as PORTMASK in this section.
> +
> +2. BIOS requirements:
> +
> +- Intel® Hyper-Threading Technology is ENABLED
> +- Hardware Prefetcher is DISABLED
> +- Adjacent Cache Line Prefetch is DISABLED
> +- Direct Cache Access is DISABLED
> +
> +3. Linux kernel requirements:
> +
> +- Linux kernel has the following features enabled: huge page support,
> +UIO, HPET
> +- Appropriate number of huge pages are reserved at kernel boot time
> +- The IDs of the hardware threads (logical cores) per each CPU socket
> +can be
> +  determined by parsing the file /proc/cpuinfo. The naming convention
> +for the
> +  logical cores is: C{x.y.z} = hyper-thread z of physical core y of CPU
> +socket x,
> +  with typical values of x = 0 .. 3, y = 0 .. 7, z = 0 .. 1. Logical
> +cores
> +  C{0.0.0} and C{0.0.1} should be avoided while executing the test, as
> +they are
> +  used by the Linux kernel for running regular processes. NUMA mode is
> +not supported
> +  by the application, so both cores and NICs should be on one socket for
> best results.
> +
> +4. Software application requirements
> +
> +The routing table consists of 15 entries, each of them consisting of
> +two fields - multicast address (which corresponds to multicast group,
> +as per IPv4 Multicast
> +specification) and a portmask associated with that group. The routing
> +table is implemented as a hash table.
> +
> +The routing table looks like this:
> +
> +|
> +
> ++-------+-------------+----------+
> +| Entry | IPv4        | Output   |
> +| #     | destination | ports    |
> +|       | address     |          |
> ++-------+-------------+----------+
> +| 0     | 224.0.0.1   | P1       |
> ++-------+-------------+----------+
> +| 1     | 224.0.0.2   | P2       |
> ++-------+-------------+----------+
> +| 2     | 224.0.0.3   | P1 P2    |
> ++-------+-------------+----------+
> +| 3     | 224.0.0.4   | P3       |
> ++-------+-------------+----------+
> +| 4     | 224.0.0.5   | P1 P3    |
> ++-------+-------------+----------+
> +| 5     | 224.0.0.6   | P2 P3    |
> ++-------+-------------+----------+
> +| 6     | 224.0.0.7   | P1 P2 P3 |
> ++-------+-------------+----------+
> +| 7     | 224.0.0.8   | P4       |
> ++-------+-------------+----------+
> +| 8     | 224.0.0.9   | P1 P4    |
> ++-------+-------------+----------+
> +| 9     | 224.0.0.10  | P2 P4    |
> ++-------+-------------+----------+
> +| 10    | 224.0.0.11  | P1 P2 P4 |
> ++-------+-------------+----------+
> +| 11    | 224.0.0.12  | P3 P4    |
> ++-------+-------------+----------+
> +| 12    | 224.0.0.13  | P1 P3 P4 |
> ++-------+-------------+----------+
> +| 13    | 224.0.0.14  | P2 P3 P4 |
> ++-------+-------------+----------+
> +| 14    | 224.0.0.15  | P1-P4    |
> ++-------+-------------+----------+
> +
> +|
> +
> +The routing table is given for reference and information purposes.
> +
> +For convenience purposes, the portmask for every multicast group is
> +equal to number of group i.e. for multicast group 5 (IP address
> +224.0.0.5) the portmask is equal to 5. This allows for some flexibility
> +in testing environment like support for different numbers of ports and
> different port configurations (up to four ports are supported).
> +
> +The recommended setup is to set up three flows per input port. Each
> +input port should be located on a different NIC (such as P0 and P2).
> +Then, a multicast group should be set corresponding to the setup i.e.
> +if ports 0 and 2 are connected to the traffic generator, multicast group 5
> must be used.
> +
> +Each of the three flows should be set up to be returned through the
> +same port, through the opposite port, and through both ports.
> +Appropriate destination IP addresses should be set up to indicate from
> which port the packet must return.
> +
> +5. Traffic generator requirements
> +
> +The flows need to be configured and started by the traffic generator
> +(this table assumes that
> +P0 and P2 are used on testing machine):
> +
> +|
> +
> ++------+---------+------------+-----------+------+-------+--------+
> +| Flow | Traffic | IPv4       | IPv4      | Port | Port  | L4     |
> +|      | Gen.    | Src.       | Dst.      | Src. | Dest. | Proto. |
> +|      | Port    | Address    | Address   |      |       |        |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F1   | TG0     | 10.100.0.1 | 224.0.0.1 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F2   | TG0     | 10.100.0.2 | 224.0.0.4 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F3   | TG0     | 10.100.0.3 | 224.0.0.5 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F4   | TG1     | 11.100.0.1 | 224.0.0.4 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F5   | TG1     | 11.100.0.2 | 224.0.0.1 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +| F6   | TG1     | 11.100.0.3 | 224.0.0.5 | ANY  | ANY   | ANY    |
> ++------+---------+------------+-----------+------+-------+--------+
> +
> +|
> +
> +These flows do not change across the test cases.
> +
> +
> +Test Case: IP4 Multicast Forwarding
> +===================================
> +
> +In addition to performance testing, multicast packets produced by
> +application must be validated with the following criteria:
> +
> +  - Source and destination IPv4 addresses of the packets forwarded by the
> application
> +    must not be changed during forwarding
> +  - Ethernet address of forwarded packets must be set to IPv4 multicast
> Ethernet addresses, which
> +    are constructed from 01-00-5E-00-00-00 ORed with lower 23 bits of 28-bit
> multicast group.
> +  - Payload of the packets must not change in any way
> +  - Packets should arrive only from ports they are supposed to arrive.
> +
> +Here is a table which shows the requirements for which TG flows should
> arrive from which port:
> +
> +|
> +
> ++------+---------+-----------+------------+-----------+
> +| Flow | Traffic | RECV Port | IPv4       | IPv4      |
> +|      | Gen.    |           | Src.       | Dst.      |
> +|      | Port    |           | Address    | Address   |
> ++------+---------+-----------+------------+-----------+
> +| F1   | TG0     | TG0       | 10.100.0.1 | 224.0.0.1 |
> ++------+---------+-----------+------------+-----------+
> +| F2   | TG0     | TG1       | 10.100.0.2 | 224.0.0.4 |
> ++------+---------+-----------+------------+-----------+
> +| F3   | TG0     | TG0 TG1   | 10.100.0.3 | 224.0.0.5 |
> ++------+---------+-----------+------------+-----------+
> +| F4   | TG1     | TG1       | 11.100.0.1 | 224.0.0.4 |
> ++------+---------+-----------+------------+-----------+
> +| F5   | TG1     | TG0       | 11.100.0.2 | 224.0.0.1 |
> ++------+---------+-----------+------------+-----------+
> +| F6   | TG1     | TG0 TG1   | 11.100.0.3 | 224.0.0.5 |
> ++------+---------+-----------+------------+-----------+
> +
> +|
> +
> +Assuming that ports ``0`` and ``2`` are connected to a traffic
> +generator, launch the ``ipv4_multicast`` with the following arguments::
> +
> +  ./examples/ipv4_multicast/build/ipv4_multicast -c 0x2 -n 1 -- -p 0x5
> + -q 2
> +
> +If the app run successfully, it will be the same as the shown in the
> terminal. ::
> +
> +  ...
> +  Initializing port 0 on lcore 1...  Address:90:E2:BA:4A:53:28, rxq=0 txq=1,0
> done:
> +  Skipping disabled port 1
> +  Initializing port 2 on lcore 1...  Address:90:E2:BA:50:8D:68, rxq=0 txq=1,0
> done:
> +  Skipping disabled port 3
> +
> +  Checking link statusdone
> +  Port0 Link Up. Speed 10000 Mbps - full-duplex
> +  Port2 Link Up. Speed 10000 Mbps - full-duplex
> +
> +Test Case: IPv4 Multicast Performance
> +=====================================
> +
> +The following items are configured through the command line interface
> +of the
> +application:
> +
> +  - The maximum number of RX queues (ports) to be available for each
> + lcore
> +  - The set of ports to be enabled for forwarding
> +
> +The test report should provide the throughput rate measurements (in
> +mpps and % of the line rate for 2x NIC ports) as listed in the table below:
> +
> +|
> +
> ++----+---------+---------+------------------+
> +| #  |Number of|Flows    | Throughput Rate  |
> +|    |threads  |enabled  |                  |
> +|    |and cores|         +------------------+
> +|    |         |         |  mpps  |    %    |
> ++----+---------+---------+--------+---------+
> +| 1  | 1C/1T   |  F1 F4  |        |         |
> ++----+---------+---------+--------+---------+
> +| 2  | 1C/2T   |  F1 F4  |        |         |
> ++----+---------+---------+--------+---------+
> +| 3  | 2C/1C   |  F1 F4  |        |         |
> ++----+---------+---------+--------+---------+
> +| 1  | 1C/1T   |  F2 F5  |        |         |
> ++----+---------+---------+--------+---------+
> +| 2  | 1C/2T   |  F2 F5  |        |         |
> ++----+---------+---------+--------+---------+
> +| 3  | 2C/1C   |  F2 F5  |        |         |
> ++----+---------+---------+--------+---------+
> +| 1  | 1C/1T   |  F3 F6  |        |         |
> ++----+---------+---------+--------+---------+
> +| 2  | 1C/2T   |  F3 F6  |        |         |
> ++----+---------+---------+--------+---------+
> +| 3  | 2C/1C   |  F3 F6  |        |         |
> ++----+---------+---------+--------+---------+
> +
> +|
> +
> +The application command line associated with each of the above tests is
> +presented in the table below. The test report should present this table
> +with the actual command line used, replacing the PORTMASK  with its
> +actual value used during test execution.
> +
> +|
> +
> ++-----+-------------------------------------------------------+
> +| #   | Command Line                                          |
> ++-----+-------------------------------------------------------+
> +|1    |./ipv4_multicast -c 0x40 -n 3 -- -p PORTMASK -q 2      |
> ++-----+-------------------------------------------------------+
> +|2    |./ipv4_multicast -c 0x400040 -n 3 -- -p PORTMASK -q 1  |
> ++-----+-------------------------------------------------------+
> +|3    |./ipv4_multicast -c 0x30 -n 3 -- -p PORTMASK -q 1      |
> ++-----+-------------------------------------------------------+
> +|4    |./ipv4_multicast -c 0x40 -n 3 -- -p PORTMASK -q 2      |
> ++-----+-------------------------------------------------------+
> +|5    |./ipv4_multicast -c 0x400040 -n 3 -- -p PORTMASK -q 1  |
> ++-----+-------------------------------------------------------+
> +|6    |./ipv4_multicast -c 0x30 -n 3 -- -p PORTMASK -q 1      |
> ++-----+-------------------------------------------------------+
> +|7    |./ipv4_multicast -c 0x40 -n 3 -- -p PORTMASK -q 2      |
> ++-----+-------------------------------------------------------+
> +|8    |./ipv4_multicast -c 0x400040 -n 3 -- -p PORTMASK -q 1  |
> ++-----+-------------------------------------------------------+
> +|9    |./ipv4_multicast -c 0x30 -n 3 -- -p PORTMASK -q 1      |
> ++-----+-------------------------------------------------------+
> --
> 2.17.2