diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/dts_gsg/Makefile | 156 | ||||
| -rw-r--r-- | doc/dts_gsg/conf.py | 40 | ||||
| -rw-r--r-- | doc/dts_gsg/config.rst | 254 | ||||
| -rw-r--r-- | doc/dts_gsg/image/dts_network_arch.png | bin | 0 -> 147605 bytes | |||
| -rw-r--r-- | doc/dts_gsg/image/dts_result.png | bin | 0 -> 7885 bytes | |||
| -rw-r--r-- | doc/dts_gsg/image/dts_soft_arch.png | bin | 0 -> 92092 bytes | |||
| -rw-r--r-- | doc/dts_gsg/index.rst | 42 | ||||
| -rw-r--r-- | doc/dts_gsg/intro.rst | 124 | ||||
| -rw-r--r-- | doc/dts_gsg/review.rst | 104 | ||||
| -rw-r--r-- | doc/dts_gsg/sys_reqs.rst | 186 |
10 files changed, 906 insertions, 0 deletions
diff --git a/doc/dts_gsg/Makefile b/doc/dts_gsg/Makefile new file mode 100644 index 0000000..e69cfc7 --- /dev/null +++ b/doc/dts_gsg/Makefile @@ -0,0 +1,156 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build +SOURCEDIR = ./ + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter + +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) + +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -E -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/DPDKDTFTestFramework.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/DPDKDTFTestFramework.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/DPDKDTFTestFramework" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/DPDKDTFTestFramework" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/dts_gsg/conf.py b/doc/dts_gsg/conf.py new file mode 100644 index 0000000..9213b01 --- /dev/null +++ b/doc/dts_gsg/conf.py @@ -0,0 +1,40 @@ +# BSD LICENSE +# Copyright(c) 2010-2014 Intel Corporation. All rights reserved. +# 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. + +import subprocess + +project = 'DPDK Test Suite' + +copyright = '2014, dpdk.org' + +#version = subprocess.check_output(["make","-sRrC","../../", "showversion"]) + +master_doc = 'index' + diff --git a/doc/dts_gsg/config.rst b/doc/dts_gsg/config.rst new file mode 100644 index 0000000..7276681 --- /dev/null +++ b/doc/dts_gsg/config.rst @@ -0,0 +1,254 @@ +Configuring DPDK Test Suite +=========================== + +DPDK Test Suite command line +---------------------------- + +DPDK Test Suite supports multiple parameters and these parameters, which will select different of working mode of test framework. In the meantime, DPDK Test Suite can work with none parameter, then every parameter will set to its default value. +For Example, please see specific usage, you can get these information via DPDK Test Suite help messages. + +.. code-block:: console + + usage: main.py [-h] [--config-file CONFIG_FILE] [--git GIT] [--patch PATCH] + [--snapshot SNAPSHOT] [--output OUTPUT] [-s] [-r] [-p PROJECT] + [--suite-dir SUITE_DIR] [-t TEST_CASES [TEST_CASES ...]] + [-d DIR] + +DPDK Test Suite supports the following parameters: + +.. table:: + + +---------------------------+---------------------------------------------------+------------------+ + | parameter | description | Default Value | + +---------------------------+---------------------------------------------------+------------------+ + | -h,--help | show this help message and exit | | + +---------------------------+---------------------------------------------------+------------------+ + | --config-file CONFIG_FILE | configuration file that describes the test cases, | ../execution.cfg | + | | DUTs and targets | | + +---------------------------+---------------------------------------------------+------------------+ + | --git GIT | Indicate git label to use as input | None | + +---------------------------+---------------------------------------------------+------------------+ + | --patch PATCH | apply a patch to the package under test | None | + +---------------------------+---------------------------------------------------+------------------+ + | --snapshot SNAPSHOT | snapshot .tgz file to use as input | ../dpdk.tar.gz | + +---------------------------+---------------------------------------------------+------------------+ + | --output OUTPUT | Output directory where DPDK Test Suite log and | ../output | + | | result saved | | + +---------------------------+---------------------------------------------------+------------------+ + | -s --skip-setup | Skips all possible setup steps done on both DUT | | + | | and tester boards. | | + +---------------------------+---------------------------------------------------+------------------+ + | -r | Reads the DUT configuration from a cache. If not | | + | | specified, the DUT configuration will be | | + | | calculated as usual and cached. | | + +---------------------------+---------------------------------------------------+------------------+ + | -p PROJECT | Specify that which project will be tested dpdk | | + | --project PROJECT | | | + +---------------------------+---------------------------------------------------+------------------+ + | -t TEST_CASES | Executes only the followings test cases | None | + | [TEST_CASES ...] | | | + | --test-cases | | | + | TEST_CASES | | | + | [TEST_CASES ...] | | | + +---------------------------+---------------------------------------------------+------------------+ + | -d DIR --dir DIR | Output directory where dpdk package is extracted | dpdk | + +---------------------------+---------------------------------------------------+------------------+ + | --suite-dir | Test suite directory where test suites will be | ../tests | + | | imported | | + +---------------------------+---------------------------------------------------+------------------+ + | -v, --verbose | Enable verbose output, all log shown on screen | | + +---------------------------+---------------------------------------------------+------------------+ + +Please see more information about some critical parameters as the following: + +**--config-file** + +DPDK Test Suite configure file defines some critical parameters. It must contain the DUT CRB IP address, wish list of test suites, DPDK target information and test mode parameter. + +**--git** + +When we use –-git parameter, DPDK Test Suite will clone the source code from dpdk.org git repository, then checkout branch specified by the parameter. + +**--patch** + +DPDK Test Suite also support apply specified patch list by --patch parameter before build DPDK packet. +**--skip-setup** + +If DPDK source code doesn’t changed, you can use --skip-setup to skip unzip and compilation of DPDK source code, just reuse original source code. + +**--project** + +Parameter –-project can load customized project model and do its own project initialization. + +**--output** + +If we perform multiple validation at the same time, result files in output folder maybe overwritten. Then we can use –-output parameter to specify the output folder and save execution log and result files. This option will make sure that all test result will be stored in the different excel files and rst files, doesn’t conflict each other. + +.. note:: + The current working folder of DPDK Test Suite is “framework” and default output folder is “../output” + +**--t** + +You can only run some specified cases in test suites. + +We can use parameter –-t to determine those cases. + +**--suite-dir** + +DPDK Test Suite support load suites from different folders, this will be helpful when there’s several projects existing in the same time. + +**--verbose** + +DPDK Test Suite support verbose mode. When enable this mode, all log messages will be output on screen and helpful for debug. + +DPDK Release Preparation +------------------------ + +Firstly, you need to download the latest code from dpdk.org, then archive and compress it in the source code folder. After that, please move this zipped file to DPDK Test Suite folder. Once launch test framework, DPDK Test Suite will copy this zipped file to root folder on DUT. Finally this source code zip file will be unzipped and built. + +.. code-block:: console + + [root@tester dcts]# ls + [root@tester dcts]# dts dpdk.tar.gz execution.cfg framework output test_plans tests + +If enables patch option, DPDK Test Suite will also make patch the unzipped folder and compile it. + +.. code-block:: console + + [root@tester dcts]# ./dts --patch 1.patch --patch 2.patch + +Create your own execution configuration +--------------------------------------- + +First of all, you must create a file named execution.cfg as below. + +.. code-block:: console + + [Execution1] + crbs=10.239.128.117 + test_suites= + hello_world, + l2fwd + targets= + x86_64-default-linuxapp-gcc, + parameters=nic_type=niantic:func=true + +* crbs: IP address of the DUT CRB. The detail information of this CRB is defined in file crbs.py. +* test_suites: defines list of test suites, which will plan to be executed. +* gets: list of DPDK targets to be tested. +* parameters: you can define multiple keywords + + – nic_type : is the type of the NIC to use. The types are defined in the file settings.py. + + – func=true run only functional test + + – perf=true run only performance test + +Then please add the detail information about your CRB in **crbs.py** as follows: + +.. code-block:: console + + crbs = [ + {'IP': '10.239.128.117', + 'name': 'CrownPassCRB1', + 'user': 'root', + 'pass': 'tester', + 'tester IP': '10.239.128.116', + IXIA: None, + 'memory channels': 4, + 'bypass core0': True}, + ] + +.. table:: + + +-----------------+----------------------------------------------------+ + | Item | description | + +-----------------+----------------------------------------------------+ + | IP | IP address of DUT | + +-----------------+----------------------------------------------------+ + | name | Name of DUT | + +-----------------+----------------------------------------------------+ + | user | UserName of DPDK Test Suite used to login into DUT | + +-----------------+----------------------------------------------------+ + | pass | Password of DPDK Test Suite used to login into DUT | + +-----------------+----------------------------------------------------+ + | Tester IP | IP address of tester | + +-----------------+----------------------------------------------------+ + | memory channels | number of memory channels for DPDK EAL | + +-----------------+----------------------------------------------------+ + | bypass core0 | skip the first core when initialize DPDK | + +-----------------+----------------------------------------------------+ + +Launch DPDK Test Suite +---------------------- + +After we have prepared the zipped dpdk file and configuration file, just type the followed command “./dts”, it will start the validation process. + +DPDK Test Suite will create communication sessions first. + +.. code-block:: console + + DUT 10.239.128.117 + DTS_DUT_CMD: ssh root@10.239.128.117 + DTS_DUT_CMD: ssh root@10.239.128.117 + DTS_TESTER_CMD: ssh root@10.239.128.116 + DCS_TESTER_CMD: ssh root@10.239.128.116 + + +Then copy snapshot zipped dpdk source code to DUT. +.. code-block:: console + + DTS_DUT_CMD: scp ../dpdk.tar.gz root@10.239.128.117: + +Collect CPU core and network device information of DUT and tester. + +Automatically detect the network topology of DUT and tester. + +.. code-block:: console + + DTS_TESTER_RESULT: DUT PORT MAP: [4, 5, 6, 7] + +Build dpdk source code and then setup the running environment. + +.. code-block:: console + + DTS_DUT_CMD: make -j install T=x86_64-native-linuxapp-gcc + DTS_DUT_CMD: awk '/Hugepagesize/ {print $2}' /proc/meminfo + DTS_DUT_CMD: awk '/HugePages_Total/ { print $2 }' /proc/meminfo + DTS_DUT_CMD: umount `awk '/hugetlbfs/ { print $2 }' /proc/mounts` + DTS_DUT_CMD: mkdir -p /mnt/huge + DTS_DUT_CMD: mount -t hugetlbfs nodev /mnt/huge + DTS_DUT_CMD: modprobe uio + DTS_DUT_CMD: rmmod -f igb_uio + DTS_DUT_CMD: insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko + DTS_DUT_CMD: lsmod | grep igb_uio + DTS_DUT_CMD: tools/dpdk_nic_bind.py --bind=igb_uio 08:00.0 08:00.1 0a:00.0 0a:00.1 + +Begin the validation process of test suite. + +.. code-block:: console + + TEST SUITE : TestCmdline + INFO: NIC : niantic + SUITE_DUT_CMD: make -j -C examples/cmdline + SUITE_DUT_CMD: ./examples/cmdline/build/app/cmdline -n 1 -c 0x2 + INFO: Test Case test_cmdline_sample_commands Begin + + +Clean-up DUT and tester after all validation finished. + +.. code-block:: console + + DTS_DUT_CMD: rmmod igb_uio + DTS_DUT_CMD: modprobe igb + DTS_DUT_CMD: modprobe ixgbe + DTS_DUT_CMD: modprobe e1000e + DTS_DUT_CMD: modprobe e1000 + DTS_DUT_CMD: modprobe virtio_net + DTS_TESTER_CMD: rmmod igb_uio + DTS_TESTER_CMD: modprobe igb + DTS_TESTER_CMD: modprobe ixgbe + DTS_TESTER_CMD: modprobe e1000e + DTS_TESTER_CMD: modprobe e1000 + DTS_TESTER_CMD: modprobe virtio_net + diff --git a/doc/dts_gsg/image/dts_network_arch.png b/doc/dts_gsg/image/dts_network_arch.png Binary files differnew file mode 100644 index 0000000..6861cea --- /dev/null +++ b/doc/dts_gsg/image/dts_network_arch.png diff --git a/doc/dts_gsg/image/dts_result.png b/doc/dts_gsg/image/dts_result.png Binary files differnew file mode 100644 index 0000000..f39f5f8 --- /dev/null +++ b/doc/dts_gsg/image/dts_result.png diff --git a/doc/dts_gsg/image/dts_soft_arch.png b/doc/dts_gsg/image/dts_soft_arch.png Binary files differnew file mode 100644 index 0000000..c489c5d --- /dev/null +++ b/doc/dts_gsg/image/dts_soft_arch.png diff --git a/doc/dts_gsg/index.rst b/doc/dts_gsg/index.rst new file mode 100644 index 0000000..e13cec3 --- /dev/null +++ b/doc/dts_gsg/index.rst @@ -0,0 +1,42 @@ +.. BSD LICENSE + Copyright(c) 2010-2014 Intel Corporation. All rights reserved. + 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. + +Getting Started Guide +===================== + +.. toctree:: + :maxdepth: 2 + :numbered: + + intro + sys_reqs + config + review + diff --git a/doc/dts_gsg/intro.rst b/doc/dts_gsg/intro.rst new file mode 100644 index 0000000..cacdd8b --- /dev/null +++ b/doc/dts_gsg/intro.rst @@ -0,0 +1,124 @@ +Introduction +============ + +This document describes how to install and configure the Data Plane Development Kit Test Suite (DPDK Test Suite) in a Linux environment. Users can refer this document to enable this test infrastructure in their environment and don’t need go deeply with too much details about this framework. +DPDK Test Suite is an automation test tool for DPDK software, a python-base library. It can run on remote tester machine, and communicate/manage DUT by SSH connection. DTF supports different kind of traffic generators, including DPDK-based PacketGen, third-party professional tester equipment (IXIA®). +Data Plane Development Kit Test Suite (DPDK Test Suite) includes one set of test cases and DPDK generic test framework . DPDK Test Suite provides test example, references and framework for open source community. Based on DPDK Test Suite, everyone can develop their test plan, automation script and configuration for own features and platform. In addition, DPDK Test Suite provides a solution to allow that DPDK developers contribute their function test to certify their patch integration. It only requires limitation effort to maintain test cases once merged into DPDK Test Suite. Everyone can utilize DPDK Test Suite to measure performance and functionality for features. + +Please see DPDK Test Suite architecture in the following figures: + +.. figure:: image/dts_soft_arch.png + +As generic test framework, DPDK Test Suite provides the following functions: + +* Able to work with DUT (Device Under Test), which installed Fedora, Ubuntu, WindRiver, FreeBSD, RedHat and SUSE +* Support both software and hardware traffic generators, including Scapy, DPDK-based PacketGen and IXIA traffic generator, even third party packet generator via TCL or Python library. +* Provide configure files to customize test suite and test cases to run under DUT. +* Support to output test result by excel, log text file, etc. +* In addition, Test Framework will manage communication with DUT by SSH, provides library to manage SSH connections. +* DPDK Test Suite provides one set of basic library to manage tester, DUT, test case, exception, generate report, and configure test plan by user configure files. It’s easy to develop user-defined test suite and test plan by self, and these test cases are able to integrate into DPDK Test Suite. +* With this test framework, user can automatically identify network topology, and easy to configure/deploy environment for DUT and tester, and provides flexibility to scale test capability by configuration. + +DPDK Test Suite environment includes DUT (Device under Test), Tester and packet generator. DPDK software will deployed and run on DUT. DPDK Test Suite test Framework and test code will be stored into tester. + +Please see architecture in the following figures: + + +.. figure:: image/dts_network_arch.png + +This architecture provides automatically mechanism to manage tester, DUT and packet generators, and remove dependency between test script and test environment/hardware. It defines one abstraction layer for DPDK Test Suite, and provides extensibility to add more test script. +In the DPDK Test Suite Test Framework, it provides the following modules to help to manage device, platform, configure and test results. + +.. table:: + + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | File Name | Description | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | dts.py | Main Application for DPDK Test Suite | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | main.py | Test script to parse input parameter | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | dut.py | Setup device under test including tool chain, IP address | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | tester.py | Provide API to setup tester environment including IP, port, etc. | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Exception.py | Manage User-defined exceptions used across the framework. | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Test_cases.py | Provides a base class for creating DPDK Test Suite test cases. | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | logger.py | Deal with different log files to record event or message | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | serializer.py | Provide wrapper class to manage temporary variables during execution | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | settings.py | Setting for default network card and its identifiers supported by the framework | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ssh_connection.py | Create session to host, implement send_expect and copy function | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ssh_pexpect.py | Handle ssh sessions between tester and DUT, Implement send_expect function to send command and get output data, Aslo support transfer files to tester or DUT | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | pmd_output.py | Module for get all statics value by port in testpmd | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | rst.py | Generate Rst Test Result Report | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | stats_reporter.py | Simple text file statistics generator | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | test_result.py | Generic result container. Useful to store/retrieve results during a DTF execution | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | excel_reporter.py | Excel spreadsheet generator | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | plotgraph.py | Generate graphs for each test suite | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | plotting.py | Generate Plots for performance test results | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | etgen.py | Software packet generator | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ixia_buffer_parser.py | Helper class that parses a list of files containing IXIA captured frames extracting a sequential number on them | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ixiacfg.py | IXIA Configuration file | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ixiaDCB.tcl | Third party Library which provided by IXIA, used to configure IXIA tester | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ixiaPing6.tcl | Third party Library which provided by IXIA, used to ping IXIA tester | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | IxiaWish.tcl | Third party Library which provided by IXIA, set up TCL environment to use correct multiversion-compatible applications | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | texttable.py | Third party Library , create simple ASCII tables | + +-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Beside Framework tool, DPDK Test Suite also defines one set of test cases. It includes basic test suite to verify basic functionality of DPDK library. These test script provides example and reference. Everyone can develop their test cases, verify their features functionality, and commit generic test report to maintainer. However, user-defined test cases, plan and script must follow DPDK Test Suite standard including code standard, naming conventions, configure format, rst test plan, API. + +Please see test cases, which included in the DPDK compliance test suites: + +.. table:: + + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Test Suite | Descriptions | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Command line | Define a demo example of command line interface in RTE | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | hello_world | Print a ``helloworld`` message on every enabled logic core. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Multi process | Demonstrates the basics of sharing information between DPDK processes. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Timer | Shows how timer can be used in a RTE application. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Blacklist/WhiteList | Tests Whitelist/Blacklist Features by Poll Mode Drivers. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | checksum_offload | Tests RX/TX L3/L4 Checksum offload features by Poll Mode Drivers | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | jumbo_frame | Tests jumbo frames features by Poll Mode Drivers | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | testpmd | Provides benchmark tests for the Intel Ethernet Controller (Niantic) Poll Mode Driver. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | l2fwd | Provides a basic packet processing application using 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. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | L3fwd | Verifies Layer-3 Forwarding results using ``l3fwd`` application. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | IP fragment | Verifies IPv4 fragmentation using ``ipv4_frag`` application. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | Flow direction | Verifies the Flow Director feature of the Intel 82599 10GbE Ethernet Controller | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | link_flowctrl | Verifies Ethernet Link Flow Control Features by Poll Mode Drivers | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | ieee1588 | Tests the IEEE1588 Precise Time Protocol offload supported in Poll Mode Drivers. | + +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/doc/dts_gsg/review.rst b/doc/dts_gsg/review.rst new file mode 100644 index 0000000..b808b30 --- /dev/null +++ b/doc/dts_gsg/review.rst @@ -0,0 +1,104 @@ +Review Test Result +================== + +Browse the result files +----------------------- +After DPDK Test Suite finished the validation, we can find the result files as below in output folder. The files in output folder maybe different when change the CRB or choose different suites. + +For Example, You can find the following in output folder after execution. + +.. code-block:: console + + [root@tester output]# ls + CrownPassCRB1 dts.log statistics.txt TestHelloWorld.log test_results.xls + +Please see details about these files: + +* CrownPassCRB1: contains the result RST file and graph of performance data +* dts.log: Full execution log of DPDK Test Suite framework +* statstics.txt: summary statistics of DPDK Test Suite executed suites +* TestHelloWorld.log: log message of TestHelloWorld case +* test_result.xls: excel format result file + +Check test result of DPDK Test Suite +------------------------------------ + +You can go through the summary of execution result via statistic.txt. This file includes the number of passed test cases, the number of failed case, the number of blocked and pass ratio. + +Please see example as the following. You can cat the sample file, then show this information of execution, totally executed two test cases, all cases passed the criterion and no failed or blocked cases. + +.. code-block:: console + + [root@tester output]# cat statistics.txt + Passed = 2 + Failed = 0 + Blocked = 0 + Pass rate = 100.0 + +If you need more detail information of test result, please open excel formatted file test_result.xls. This file contains of both detailed case information and case results. Also you can find description of the failure reason if DPDK Test Suite can track it. + +.. figure:: image/dts_result.png + +If you want to track more details about the process of each suite, please go to log file which named by this suite, all related information will stored in this file. + +DPDK Test Suite log module provides several levels to track event or output in log file. Every message level will have its own scopes. Separated log messages will help us get to known what happening in DPDK Test Suite and what happening in DUT and tester. + + +.. table:: + + +---------------------+---------------------------------------------------------------------------------------------+ + | Level | description | + +---------------------+---------------------------------------------------------------------------------------------+ + | INFO | DPDK Test Suite system level log, show start and stop process in this suite | + +---------------------+---------------------------------------------------------------------------------------------+ + | SUITE_DUT_CMD | Commands send to DUT CRB | + +---------------------+---------------------------------------------------------------------------------------------+ + | SUITE_DUT_OUTPUT | Output after the send the commands to DUT | + +---------------------+---------------------------------------------------------------------------------------------+ + | SUITE_TESTER_CMD | Commands send to tester, most of they are Scapy commands which will send packet to DUT port | + +---------------------+---------------------------------------------------------------------------------------------+ + | SUITE_TESTER_OUTPUT | Output after the send the commands to tester | + +---------------------+---------------------------------------------------------------------------------------------+ + + +Please see example for TestHelloWorld suite log as the following. This log file showed that application helloworld sent hello message from core1, and finally matched the pass criterion. + +.. code-block:: console + + 22/08/2014 11:04:45 INFO: + TEST SUITE : TestHelloWorld + 22/08/2014 11:04:45 INFO: NIC : niantic + 22/08/2014 11:04:45 SUITE_DUT_CMD: make -j -C examples/helloworld + 22/08/2014 11:04:45 SUITE_DUT_OUTPUT: make: Entering directory `/root/dpdk/examples/helloworld'^M + CC main.o^M + LD helloworld^M + INSTALL-MAP helloworld.map^M + INSTALL-APP helloworld^M + make: Leaving directory `/root/dpdk/examples/helloworld' + 22/08/2014 11:04:45 INFO: Test Case test_hello_world_single_core Begin + 22/08/2014 11:04:45 SUITE_DUT_CMD: ./examples/helloworld/build/app/helloworld -n 1 -c 0x1fffffffff + 22/08/2014 11:04:48 SUITE_DUT_OUTPUT: EAL: Detected lcore 0 as core 0 on socket 0^M + … + hello from core 1 + 22/08/2014 11:05:08 INFO: Test Case test_hello_world_single_core Result PASSED: + 22/08/2014 11:05:09 SUITE_DUT_CMD: uname + 22/08/2014 11:05:09 SUITE_DUT_OUTPUT: + 22/08/2014 11:05:09 SUITE_TESTER_CMD: killall scapy 2>/dev/null; echo tester + 22/08/2014 11:05:09 SUITE_TESTER_OUTPUT: tester + 22/08/2014 11:05:10 SUITE_TESTER_CMD: uname + 22/08/2014 11:05:10 SUITE_TESTER_OUTPUT: + 22/08/2014 11:05:10 INFO: + TEST SUITE ENDED: TestHelloWorld + +Generate PDF doc from RST +------------------------- + +Since DPDK Test Suite stores test result as RST by default, you may be want to transfer it to PDF formatted which make it more readable. Firstly, please enter the folder which contained the RST results, then use python tool ``rst2pdf`` to convert RST. If there’s no error return, you can find the pdf file generated with same name. + +.. code-block:: console + + [root@tester dcts]# cd output/CrownPassCRB1/x86_64-native-linuxapp-gcc/Niantic + [root@tester niantic]# rst2pdf TestResult_hello_world.rst + [root@tester niantic]# ls + TestResult_hello_world.pdf TestResult_hello_world.rst + diff --git a/doc/dts_gsg/sys_reqs.rst b/doc/dts_gsg/sys_reqs.rst new file mode 100644 index 0000000..fad5617 --- /dev/null +++ b/doc/dts_gsg/sys_reqs.rst @@ -0,0 +1,186 @@ +System Requirements +=================== + +The board assigned to be tester should be installed the latest Fedora distribution for easily installed DPDK Test Suite required python modules. Tester board needs plug at least 2 x Intel® 82599 (Niantic) NICs (2x 10GbE full duplex optical ports per NIC) in the PCI express slots, then connect these four Niantic ports to the DUT board and make sure the link has been started up and speed is 10000Mb/s. + +Beside the four Niantic ports, tester and DUT should also have one interface connected to the same intranet. So that they can be accessed by each other from local IP address. + +.. note:: + + Firewall should be disabled that all packets can be accepted by Niantic Interface. + +.. code-block:: console + + systemctl disable firewalld.service + +Setup Tester Environment +------------------------ + +.. note:: + + Please install the latest Fedora distribution on the tester before install DPDK Test Suite on tester. Currently we recommend Fedora 20 for tester. The setup instruction and required packages may be different on different operation systems. + +To enable tester environment, you need to install script language, tool chain and third party packet generator, etc. + +Please follow the guidance to finish install as the below section. + +SSH Service +~~~~~~~~~~~ +Since DPDK Test Suite Tester communicates with DUT via SSH, please install and start sshd service in your tester. + +.. code-block:: console + + yum install sshd # download / install ssh software + systemctl enable sshd.service # start ssh service + +For create authorized login session, user needs to generate RSA authentication keys to ssh connection. + +Please use the following commands: + +.. code-block:: console + + ssh-keygen -t rsa + +TCL Language Support modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Since some third party tools required TCL (Tool Command Language) supports, please install TCL package to control and connect third party package generator. (For example, third-party professional tester IXIA required TCL support) + +.. code-block:: console + + yum install tcl # download / install ssh software + +Install Third Party python modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With third party module, DPDK Test Suite is able to export test result as MS Excel file or graphs. To support this feature, please install the following modules in the tester. +Python Module “xlwt”: this module is used to generate spreadsheet files which compatible with MS Excel 97/2000/XP/2003 XLS files. +Python Module “numpy”: this module provides method to deal with array-processing test results. +Python Module “matplotlib”: this module is used to produce quality 2D test result summary as graphics +Python Module “pexpect”: this module provides API to automate interactive SSH sessions. +Python Module “docutils”: Docutils is a modular system for processing documentation into useful formats, such as HTML, XML, and LaTeX. +Python Module “pcapy”: Pcapy is a Python extension module that interfaces with the libpcap packet capture library. Pcapy enables python scripts to capture packets on the network. + +Please see installation instruction as the following: + + +.. code-block:: console + + yum install python-xlwt + yum install python-pexpect + yum install numpy + yum install python-matplotlib + yum install python-docutils + yum install pcapy + + +Setup and configure Scapy +~~~~~~~~~~~~~~~~~~~~~~~~~ +Scapy is a powerful interactive packet manipulation program. It is able to forge or decode packets of a wide number of protocols, send them on the wire, capture them, match requests and replies, and much more. It can easily handle most classical tasks like scanning, tracerouting, probing, unit tests, attacks or network discovery. + +DTCS uses python module scapy to forge or decode packets of a wide number of protocols, send them over the wire, capture them, and analyse the packets. + +.. code-block:: console + + yum install scapy + +Fedora20 default kernel will strip vlan header automatically and thus it will cause that scapy can’t detect vlan packet normally. To solve this issue, we need to configure scapy use libpcap which is a low-level network traffic monitoring tool. + +.. code-block:: console + + vim /usr/lib/python2.7/site-packages/scapy/config.py # open configure python files + use_pcap = True # find use_pcap and set it to True + +Install DPDK Test Suite on tester +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After configure environment, we need to install DPDK Test Suite into tester. First of all, download the latest DPDK Test Suite code from remote repo. + +.. code-block:: console + + [root@tester ~]# git clone http://dpdk.org/git/tools/dcts + [root@tester ~]# cd dcts + [root@tester dcts]# ls + [root@tester dcts]# dts execution.cfg framework output test_plans tests + +High Precision Timer (HPET) must be enabled in the platform BIOS if the HPET is to be used. Otherwise, the Time Stamp Counter (TSC) is used by default. The user can then navigate to the HPET option. On the Crystal Forest platform BIOS, the path is: +**Advanced -> PCH-IO Configuration -> High Precision Timer** + +The DPDK Test Suite is composed of several file and directories: + +* dts: Main module of DPDK Test Suite suite +* exectution.cfg: configuration file of DPDK Test Suite suite +* framework: folder with dts framework modules +* output: folder which contain running log files and result files +* test_plans: folder with rst files which contain the description of test case +* tests: folder with test case scripts + +Setup Target Environment +------------------------ + +This section describes how to deploy DPDK Test Suite packages into DUT target.So far, DPDK Test Suite supports the following OS on DUT: + +* Fedora18/19/20 +* Ubuntu12.04/14.04 +* WindRiver 6.0 +* FreeBSD 10 +* RedHat 6.5/7.0 +* SUSE 11 + +Before run DPDK Test Suite on target, we need to configure target environment, it includes BIOS setting, Network configure, compiler environment, etc. + +BIOS setting Prerequisite +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In general, enter BIOS Menu by pressing F2 while the platform is starting up. + +.. note:: + strongly recommend to install DPDK on Intel latest platform and processor. + +The High Precision Timer (HPET) must be enabled in the platform BIOS if the HPET is to be used. Otherwise, the Time Stamp Counter (TSC) is used by default. The user can then navigate to the HPET option. On the Crystal Forest platform BIOS, the path is: + +**Advanced -> PCH-IO Configuration -> High Precision Timer** + +Enhanced Intel SpeedStep® Technology must be disabled in the platform BIOS. Thus we will disable dynamically adjust processor voltage and core frequency which may cause unstable performance data. On the Crystal Forest platform BIOS, the path is: + +**Advanced -> Processor Configuration -> Enhanced Intel SpeedStep** + +Processor sate C3 and C6 must be disabled for performance measure too. On the Crystal Forest platform BIOS, the path is: + +**Advanced -> Processor Configuration -> Processor C3 +Advanced -> Processor Configuration -> Processor C6** + +Hyper-Threading Technology must be enabled. On the Crystal Forest platform BIOS, the path is: + +**Advanced -> Processor Configuration -> Intel® Hyper-Threading Tech** + +If the platform BIOS has any particular performance option, select the settings for best performance. + +DPDK running Prerequisite +~~~~~~~~~~~~~~~~~~~~~~~~~ +Compilation of DPDK need GNU maker, gcc, libc-header, kernel header installed. For 32-bit compilation on 64-bit systems, there’re some additional packages required. For Intel® C++ Compiler (icc) additional libraries may be required. For more detail information of required packets, please refer to Data Plane Development Kit Getting Started Guide. + +The DPDK igb_uio kernel module depends on traditional Linux kernel uio support to operate. Linux traditional uio support may be compiled as a module, so this module should be loaded using the modprobe program. +Kernel must support the allocation of hugepages. Hugepage support is required for the large memory pool allocation used for packet buffers. By using hugepage allocations, performance will be improved since only fewer pages are needed, and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches), which reduce the time it takes to translate a virtual page address to a physical page address. Without hugepages, high TLB miss rates would occur, slowing performance. + +The DPDK igb_uio kernel module depends on traditional Linux kernel ``uio`` support to operate. Linux traditional ``uio`` support may be compiled as a module, so this module should be loaded using the ``modprobe`` program. +Kernel must support the allocation of hugepages. Hugepage support is required for the large memory pool allocation used for packet buffers. By using hugepage allocations, performance will be improved since only fewer pages are needed, and therefore less Translation Lookaside Buffers (TLBs, high speed translation caches), which reduce the time it takes to translate a virtual page address to a physical page address. Without hugepages, high TLB miss rates would occur, slowing performance. + +For more detail information of system requirements, also refer to `Data Plane Development Kit Getting Started Guide <http://dpdk.org/doc/intel/dpdk-start-linux-1.7.0.pdf>`_. + +Authorized login session +------------------------ +In DPDK Test Suite, communication was established based on authorized ssh session. All ssh connection to each other will skip password interactive phase for remote server has been authorized. + +In tester, you can use tool ssh-copy-id to save local available keys on DUT, thus create authorise login session between tester and DUT. By the same way, you can create authorise login session between tester and itself. + +.. code-block:: console + + ssh-copy-id -i “IP of DUT” + ssh-copy-id -i “IP of tester” + +In DUT, You also can use tool ssh-copy-id to save local available keys in tester, thus create authorise login session between DUT and tester. + +.. code-block:: console + + ssh-copy-id –i “IP of Tester” + |
