new file mode 100644
@@ -0,0 +1,372 @@
+.. Copyright (c) <2022>, 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 NOgit T 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.
+
+================================================
+vhost/virtio-user loopback server mode test plan
+================================================
+
+Description
+===========
+
+1. Virtio-user server mode is a feature to enable virtio-user as the server, vhost as the client,
+thus after vhost-user is killed then relaunched,
+virtio-user can reconnect back to vhost-user again; at another hand,
+virtio-user also can reconnect back to vhost-user after virtio-user is killed.
+2. This feature test need cover different rx/tx paths with virtio 1.0 and virtio 1.1,
+includes split ring mergeable, non-mergeable, inorder mergeable,inorder non-mergeable, vector_rx path
+and packed ring mergeable, non-mergeable, inorder non-mergeable, inorder mergeable, vectorized path.
+3. Split ring and packed ring test when vhost enqueue operation with multi-CBDMA channels.
+When DMA devices are bound to vfio driver,VA mode is the default and recommended. For PA mode,
+page by page mapping may exceed IOMMU's max capability, better to use 1G guest hugepage.
+
+For more about dpdk-testpmd sample, please refer to the DPDK docments:
+https://doc.dpdk.org/guides/testpmd_app_ug/run_app.html
+
+For virtio-user vdev parameter, you can refer to the DPDK docments:
+https://doc.dpdk.org/guides/nics/virtio.html#virtio-paths-selection-and-usage.
+
+Prerequisites
+=============
+
+Topology
+--------
+Test flow: Virtio-user-->Vhost-user-->Testpmd-->Vhost-user-->Virtio-user
+
+Hardware
+--------
+Supportted NICs: ALL
+
+Software
+--------
+Trex:http://trex-tgn.cisco.com/trex/release/v2.26.tar.gz
+
+General set up
+--------------
+1. Compile DPDK::
+
+ # CC=gcc meson --werror -Denable_kmods=True -Dlibdir=lib -Dexamples=all --default-library=<dpdk build dir>
+ # ninja -C <dpdk build dir> -j 110
+
+2. Get the PCI device ID and DMA device ID of DUT, for example, 0000:18:00.0 is PCI device ID, 0000:00:04.0, 0000:00:04.1 is DMA device ID::
+
+ <dpdk dir># ./usertools/dpdk-devbind.py -s
+
+ Network devices using kernel driver
+ ===================================
+ 0000:18:00.0 'Device 159b' if=ens785f0 drv=ice unused=vfio-pci
+
+ DMA devices using kernel driver
+ ===============================
+ 0000:00:04.0 'Sky Lake-E CBDMA Registers 2021' drv=ioatdma unused=vfio-pci
+ 0000:00:04.1 'Sky Lake-E CBDMA Registers 2021' drv=ioatdma unused=vfio-pci
+
+Test case
+=========
+
+Common steps
+------------
+1. Bind 1 NIC port and CBDMA channels to vfio-pci::
+
+ <dpdk dir># ./usertools/dpdk-devbind.py -b vfio-pci <DUT port pci device id>
+ <dpdk dir># ./usertools/dpdk-devbind.py -b vfio-pci <DUT port DMA device id>
+
+ For example, bind 2 CBDMA channels::
+ <dpdk dir># ./usertools/dpdk-devbind.py -b vfio-pci 0000:00:04.0,0000:00:04.1
+
+2. Attach pdump secondary process to primary process by same file-prefix::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-pdump -v --file-prefix=virtio1 -- \
+ --pdump 'device_id=net_virtio_user1,queue=0,rx-dev=./pdump-virtio-rx-q0.pcap,mbuf-size=8000' \
+ --pdump 'device_id=net_virtio_user1,queue=0,rx-dev=./pdump-virtio-rx-q0.pcap,mbuf-size=8000'
+
+
+Test Case 1: loopback packed ring all path cbdma test payload check with server mode and multi-queues
+-----------------------------------------------------------------------------------------------------
+This case uses testpmd to test packed ring all path with multi-queues to test payload check with server mode and relaunch vhost.
+
+1. Bind 8 CBDMA channel to vfio-pci, as common step 1.
+
+2. Launch vhost by below command::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 10-18 -n 4 \
+ -a 0000:00:04.0 -a 0000:00:04.1 -a 0000:00:04.2 -a 0000:00:04.3 -a 0000:00:04.4 -a 0000:00:04.5 -a 0000:00:04.6 -a 0000:00:04.7 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=8,client=1,dmas=[txq0;txq1;txq2;txq3;txq4;txq6;txq7]' \
+ --iova=va -- -i --nb-cores=5 --rxq=8 --txq=8 --txd=1024 --rxd=1024 \
+ --lcore-dma=[lcore11@0000:00:04.0,lcore11@0000:00:04.7,lcore12@0000:00:04.1,lcore12@0000:00:04.2,lcore12@0000:00:04.3,lcore13@0000:00:04.2,lcore13@0000:00:04.3,lcore13@0000:00:04.4,lcore14@0000:00:04.2,lcore14@0000:00:04.3,lcore14@0000:00:04.4,lcore14@0000:00:04.5,lcore15@0000:00:04.0,lcore15@0000:00:04.1,lcore15@0000:00:04.2,lcore15@0000:00:04.3,lcore15@0000:00:04.4,lcore15@0000:00:04.5,lcore15@0000:00:04.6,lcore15@0000:00:04.7]
+
+3. Launch virtio-user with packed ring mergeable inorder path::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=1,in_order=1,packed_vq=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+4. Start pdump to capture virtio-user packets, as common step 2.
+
+5. Send large pkts from vhost, check loopback performance can get expected and each queue can receive packets::
+
+ testpmd> set fwd csum
+ testpmd> set txpkts 64,64,64,2000,2000,2000
+ testpmd> set burst 1
+ testpmd> start tx_first 1
+ testpmd> stop
+
+6. Quit pdump, check all the packets length are 6192 Byte in the pcap file and the payload in receive packets are same.
+
+7. Quit and relaunch vhost and rerun step 4-6.
+
+8. Quit and relaunch virtio with packed ring mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=1,in_order=0,packed_vq=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+9. Rerun steps 4-7.
+
+10. Quit and relaunch virtio with packed ring non-mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=0,packed_vq=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+11. Send pkts from vhost, check loopback performance can get expected and each queue can receive packets::
+
+ testpmd> set fwd csum
+ testpmd> set txpkts 64,128,256,512
+ testpmd> set burst 1
+ testpmd> start tx_first 1
+ testpmd> stop
+
+12. Quit pdump, check all the packets length are 960 Byte in the pcap file and the payload in receive packets are same.
+
+13. Quit and relaunch vhost and rerun step 11-12.
+
+14. Quit and relaunch virtio with packed ring inorder non-mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=1,packed_vq=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+15. Rerun step 11-13.
+
+16. Quit and relaunch virtio with packed ring vectorized path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci --force-max-simd-bitwidth=512 \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=1,packed_vq=1,vectorized=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+17. Rerun step 11-13.
+
+18. Quit and relaunch virtio with packed ring vectorized path and ring size is not power of 2 as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci --force-max-simd-bitwidth=512 \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=1,packed_vq=1,vectorized=1,queue_size=1025,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1025 --rxd=1025
+ testpmd>set fwd csum
+ testpmd>start
+
+19. Rerun step 11-13.
+
+20. Quit and relaunch vhost w/ iova=pa::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 10-18 -n 4 \
+ -a 0000:00:04.0 -a 0000:00:04.1 -a 0000:00:04.2 -a 0000:00:04.3 -a 0000:00:04.4 -a 0000:00:04.5 -a 0000:00:04.6 -a 0000:00:04.7 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=8,client=1,dmas=[txq0;txq1;txq2;txq3;txq4;txq6;txq7]' \
+ --iova=pa -- -i --nb-cores=5 --rxq=8 --txq=8 --txd=1024 --rxd=1024 \
+ --lcore-dma=[lcore11@0000:00:04.0,lcore11@0000:00:04.7,lcore12@0000:00:04.1,lcore12@0000:00:04.2,lcore12@0000:00:04.3,lcore13@0000:00:04.2,lcore13@0000:00:04.3,lcore13@0000:00:04.4,lcore14@0000:00:04.2,lcore14@0000:00:04.3,lcore14@0000:00:04.4,lcore14@0000:00:04.5,lcore15@0000:00:04.0,lcore15@0000:00:04.1,lcore15@0000:00:04.2,lcore15@0000:00:04.3,lcore14@0000:00:04.4,lcore14@0000:00:04.5,lcore15@0000:00:04.6,lcore15@0000:00:04.7]
+
+21. Rerun steps 2-19.
+
+Test Case 2: loopback split ring all path cbdma test payload check with server mode and multi-queues
+----------------------------------------------------------------------------------------------------
+This case uses testpmd to test split ring all path with multi-queues to test payload check with server mode and relaunch vhost.
+
+1. Bind 3 CBDMA channel to vfio-pci, as common step 1.
+
+2. Launch vhost by below command::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 10-18 -n 4 -a 0000:00:04.0 -a 0000:00:04.1 -a 0000:00:04.2 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=8,client=1,dmas=[txq0;txq1;txq2;txq3;txq4;txq5;txq6]' \
+ --iova=va -- -i --nb-cores=5 --rxq=8 --txq=8 --txd=1024 --rxd=1024 \
+ --lcore-dma=[lcore11@0000:00:04.0,lcore12@0000:00:04.0,lcore13@0000:00:04.1,lcore13@0000:00:04.2,lcore14@0000:00:04.1,lcore14@0000:00:04.2,lcore15@0000:00:04.1,lcore15@0000:00:04.2]
+
+3. Launch virtio-user with split ring mergeable inorder path::
+
+ dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ -vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=1,in_order=1,server=1 \
+ - -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+4. Start pdump to capture virtio-user packets, as common step 2.
+
+5. Send large pkts from vhost, check loopback performance can get expected and each queue can receive packets::
+
+ testpmd> set fwd csum
+ testpmd> set txpkts 64,64,64,2000,2000,2000
+ testpmd> set burst 1
+ testpmd> start tx_first 1
+ testpmd> stop
+
+6. Quit pdump, check all the packets length are 6192 Byte in the pcap file and the payload in receive packets are same.
+
+7. Quit and relaunch vhost and rerun step 4-6.
+
+8. Quit and relaunch virtio with split ring mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=1,in_order=0,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+9. Rerun steps 4-7.
+
+10. Quit and relaunch virtio with split ring non-mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=0,server=1 \
+ -- -i --enable-hw-vlan-strip --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+11. Send pkts from vhost, check loopback performance can get expected and each queue can receive packets::
+
+ testpmd> set fwd csum
+ testpmd> set txpkts 64,128,256,512
+ testpmd> set burst 1
+ testpmd> start tx_first 1
+ testpmd> stop
+
+12. Quit pdump, check all the packets length are 960 Byte in the pcap file and the payload in receive packets are same.
+
+13. Quit and relaunch vhost and rerun step 11-12.
+
+14. Quit and relaunch virtio with split ring inorder non-mergeable path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+15. Rerun step 11-13.
+
+16. Quit and relaunch virtio with split ring vectorized path as below::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=virtio-user0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=8,mrg_rxbuf=0,in_order=0,vectorized=1,server=1 \
+ -- -i --nb-cores=1 --rxq=8 --txq=8 --txd=1024 --rxd=1024
+ testpmd>set fwd csum
+ testpmd>start
+
+17. Rerun step 11-13.
+
+18. Quit and relaunch vhost w/ iova=pa::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 10-18 -n 4 -a 0000:00:04.0 -a 0000:00:04.1 -a 0000:00:04.2 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=8,client=1,dmas=[txq0;txq1;txq2;txq3;txq4;txq5;txq6]' \
+ --iova=pa -- -i --nb-cores=5 --rxq=8 --txq=8 --txd=1024 --rxd=1024 \
+ --lcore-dma=[lcore11@0000:00:04.0,lcore12@0000:00:04.0,lcore13@0000:00:04.1,lcore13@0000:00:04.2,lcore14@0000:00:04.1,lcore14@0000:00:04.2,lcore15@0000:00:04.1,lcore15@0000:00:04.2]
+
+19. Rerun steps 2-18.
+
+Test Case 3: loopback split ring large chain packets stress test with server mode and cbdma enqueue
+---------------------------------------------------------------------------------------------------
+This case uses testpmd to test split ring large chain packets stress test with server mode.
+
+1. Bind 1 CBDMA channel to vfio-pci, as common step 1.
+
+2. Launch vhost by below command::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 2-3 -n 4 -a 0000:00:04.0 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=1,client=1,dmas=[txq0]' --iova=va -- -i --nb-cores=1 --mbuf-size=65535 --lcore-dma=[lcore3@0000:00:04.0]
+
+3. Launch virtio and start testpmd::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=testpmd0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=1,server=1,mrg_rxbuf=1,in_order=0,vectorized=1,queue_size=2048 \
+ -- -i --rxq=1 --txq=1 --txd=2048 --rxd=2048 --nb-cores=1
+ testpmd>start
+
+4. Send large packets from vhost, check virtio can receive packets::
+
+ testpmd> set txpkts 65535,65535,65535,65535,65535
+ testpmd> start tx_first 32
+ testpmd> show port stats all
+
+5. Stop and quit vhost testpmd and relaunch vhost with iova=pa::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 2-3 -n 4 -a 0000:00:04.0 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=1,client=1,dmas=[txq0]' --iova=pa -- -i --nb-cores=1 --mbuf-size=65535 --lcore-dma=[lcore3@0000:00:04.0]
+
+6. Rerun steps 4.
+
+Test Case 4: loopback packed ring large chain packets stress test with server mode and cbdma enqueue
+----------------------------------------------------------------------------------------------------
+This case uses testpmd to test packed ring large chain packets stress test with server mode.
+
+1. Bind 1 CBDMA channel to vfio-pci, as common step 1.
+
+2. Launch vhost by below command::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 2-3 -n 4 -a 0000:00:04.0 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=1,dmas=[txq0],client=1' --iova=va -- -i --nb-cores=1 --mbuf-size=65535 --lcore-dma=[lcore3@0000:00:04.0]
+
+3. Launch virtio and start testpmd::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 30,31 -n 4 --file-prefix=testpmd0 --no-pci \
+ --vdev=net_virtio_user0,mac=00:11:22:33:44:10,path=./vhost-net0,queues=1,mrg_rxbuf=1,in_order=0,vectorized=1,packed_vq=1,queue_size=2048,server=1 \
+ -- -i --rxq=1 --txq=1 --txd=2048 --rxd=2048 --nb-cores=1
+ testpmd>start
+
+4. Send large packets from vhost, check virtio can receive packets::
+
+ testpmd> set txpkts 65535,65535,65535,65535,65535
+ testpmd> start tx_first 32
+ testpmd> show port stats all
+
+5. Stop and quit vhost testpmd and relaunch vhost with iova=pa::
+
+ <dpdk dir># ./x86_64-native-linuxapp-gcc/app/dpdk-testpmd -l 2-3 -n 4 -a 0000:00:04.0 \
+ --vdev 'eth_vhost0,iface=vhost-net0,queues=1,dmas=[txq0],client=1' --iova=pa -- -i --nb-cores=1 --mbuf-size=65535 --lcore-dma=[lcore3@0000:00:04.0]
+
+6. Rerun steps 4.
\ No newline at end of file