From mboxrd@z Thu Jan 1 00:00:00 1970 From: John McNamara Subject: =?utf-8?q?=5BPATCH=5D_doc=3A_fix_rst_issues_in_testpmd?= =?utf-8?q?_user_guide?= Date: Mon, 28 Sep 2015 20:45:46 +0100 Message-ID: <1443469546-20901-1-git-send-email-john.mcnamara@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 4CCB72A5E for ; Mon, 28 Sep 2015 21:45:51 +0200 (CEST) List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Fix a number of RST issues in the testpmd user guide and refactored the structure to: * Remove redundant roadmap section. * Merge Overview section into Introduction. * Move "set fwd" to the start of its section. Signed-off-by: John McNamara --- doc/guides/testpmd_app_ug/build_app.rst | 4 +- doc/guides/testpmd_app_ug/index.rst | 1 - doc/guides/testpmd_app_ug/intro.rst | 39 +- doc/guides/testpmd_app_ug/overview.rst | 35 - doc/guides/testpmd_app_ug/run_app.rst | 262 ++--- doc/guides/testpmd_app_ug/testpmd_funcs.rst | 1440 ++++++++++++++-------= ------ 6 files changed, 878 insertions(+), 903 deletions(-) delete mode 100644 doc/guides/testpmd_app_ug/overview.rst diff --git a/doc/guides/testpmd_app_ug/build_app.rst b/doc/guides/testpmd= _app_ug/build_app.rst index 8b0a857..7f32a7c 100644 --- a/doc/guides/testpmd_app_ug/build_app.rst +++ b/doc/guides/testpmd_app_ug/build_app.rst @@ -31,8 +31,8 @@ Compiling the Application =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 -The testpmd application is compiled as part of the main compilation of t= he DPDK libraries and tools. -Refer to the DPDK Getting Started Guide for details. +The ``testpmd`` application is compiled as part of the main compilation = of the DPDK libraries and tools. +Refer to the DPDK Getting Started Guides for details. The basic compilation steps are: =20 #. Set the required environmental variables and go to the source direct= ory: diff --git a/doc/guides/testpmd_app_ug/index.rst b/doc/guides/testpmd_app= _ug/index.rst index 922535c..3b163c1 100644 --- a/doc/guides/testpmd_app_ug/index.rst +++ b/doc/guides/testpmd_app_ug/index.rst @@ -40,7 +40,6 @@ Testpmd Application User Guide :numbered: =20 intro - overview build_app run_app testpmd_funcs diff --git a/doc/guides/testpmd_app_ug/intro.rst b/doc/guides/testpmd_app= _ug/intro.rst index ccf57ed..8ef32e7 100644 --- a/doc/guides/testpmd_app_ug/intro.rst +++ b/doc/guides/testpmd_app_ug/intro.rst @@ -31,42 +31,11 @@ Introduction =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -This document is a user guide for the testpmd example application that i= s shipped as part of the Data Plane Development Kit. +This document is a user guide for the ``testpmd`` example application th= at is shipped as part of the Data Plane Development Kit. =20 -The testpmd application can be used to test the DPDK in a packet forward= ing mode +The ``testpmd`` application can be used to test the DPDK in a packet for= warding mode and also to access NIC hardware features such as Flow Director. It also serves as a example of how to build a more fully-featured applic= ation using the DPDK SDK. =20 -Documentation Roadmap ---------------------- - -The following is a list of DPDK documents in the suggested reading order= : - -* **Release Notes** : Provides release-specific information, including= supported features, - limitations, fixed issues, known issues and so on. - Also, provides the answers to frequently asked questions in FAQ form= at. - -* **Getting Started Guide** (this document): Describes how to install = and configure the DPDK; - designed to get users up and running quickly with the software. - -* **Programmer's Guide** : Describes: - - * The software architecture and how to use it (through examples), = specifically in a Linux* application (linuxapp) environment - - * The content of the DPDK, the build system - (including the commands that can be used in the root DPDK Makefi= le to build the development kit and an application) - and guidelines for porting an application - - * Optimizations used in the software and those that should be cons= idered for new development - - A glossary of terms is also provided. - -* **API Reference** : Provides detailed information about DPDK functio= ns, data structures and other programming constructs. - -* **Sample Applications User Guide** : Describes a set of sample appli= cations. - Each chapter describes a sample application that showcases specific = functionality and - provides instructions on how to compile, run and use the sample appl= ication. - -.. note:: - - These documents are available for download as a separate documentati= on package at the same location as the DPDK code package. +The guide shows how to build and run the testpmd application and +how to configure the application from the command line and the run-time = environment. diff --git a/doc/guides/testpmd_app_ug/overview.rst b/doc/guides/testpmd_= app_ug/overview.rst deleted file mode 100644 index 7937aca..0000000 --- a/doc/guides/testpmd_app_ug/overview.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. 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 FO= R - 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 AN= Y - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -Overview -=3D=3D=3D=3D=3D=3D=3D=3D - -The following sections show how to build and run the testpmd application= and -how to configure the application from the command line and the run-time = environment. diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_a= pp_ug/run_app.rst index 54ae2b2..f605564 100644 --- a/doc/guides/testpmd_app_ug/run_app.rst +++ b/doc/guides/testpmd_app_ug/run_app.rst @@ -36,117 +36,123 @@ EAL Command-line Options =20 The following are the EAL command-line options that can be used in conju= nction with the testpmd, or any other DPDK application. -See the DPDK Getting Started Guide for more information on these options= . +See the DPDK Getting Started Guides for more information on these option= s. =20 -* -c COREMASK +* ``-c COREMASK`` =20 Set the hexadecimal bitmask of the cores to run on. =20 -* -l CORELIST +* ``-l CORELIST`` =20 List of cores to run on =20 - The argument format is [-c2][,c3[-c4],...] - where c1, c2, etc are core indexes between 0 and 128 + The argument format is ``[-c2][,c3[-c4],...]`` + where ``c1``, ``c2``, etc are core indexes between 0 and 128. =20 -* --lcores COREMAP +* ``--lcores COREMAP`` =20 Map lcore set to physical cpu set =20 - The argument format is - '[<,lcores[@cpus]>...]' + The argument format is:: =20 - lcores and cpus list are grouped by '(' and ')' - Within the group, '-' is used for range separator, - ',' is used for single number separator. - '( )' can be omitted for single element group, - '@' can be omitted if cpus and lcores have the same value + [<,lcores[@cpus]>...] =20 -* --master-lcore ID + Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group. + The ``-`` character is used as a range separator and ``,`` is used a= s a single number separator. + The grouping ``()`` can be omitted for single element group. + The ``@`` can be omitted if cpus and lcores have the same value. =20 - Core ID that is used as master +* ``--master-lcore ID`` =20 -* -n NUM + Core ID that is used as master. + +* ``-n NUM`` =20 Set the number of memory channels to use. =20 -* -b, --pci-blacklist domain:bus:devid.func +* ``-b, --pci-blacklist domain:bus:devid.func`` =20 Blacklist a PCI devise to prevent EAL from using it. Multiple -b opt= ions are allowed. =20 -* -d LIB.so +* ``-d LIB.so`` =20 Load an external driver. Multiple -d options are allowed. =20 -* -w, --pci-whitelist domain:bus:devid:func +* ``-w, --pci-whitelist domain:bus:devid:func`` =20 Add a PCI device in white list. =20 -* -m MB +* ``-m MB`` =20 - Memory to allocate. See also --socket-mem. + Memory to allocate. See also ``--socket-mem``. =20 -* -r NUM +* ``-r NUM`` =20 Set the number of memory ranks (auto-detected by default). =20 -* -v +* ``-v`` =20 Display the version information on startup. =20 -* --xen-dom0 +* ``--xen-dom0`` =20 Support application running on Xen Domain0 without hugetlbfs. =20 -* --syslog +* ``--syslog`` =20 Set the syslog facility. =20 -* --socket-mem +* ``--socket-mem`` =20 Set the memory to allocate on specific sockets (use comma separated = values). =20 -* --huge-dir +* ``--huge-dir`` =20 Specify the directory where the hugetlbfs is mounted. =20 -* --proc-type +* ``--proc-type`` =20 Set the type of the current process. =20 -* --file-prefix +* ``--file-prefix`` =20 Prefix for hugepage filenames. =20 -* -vmware-tsc-map +* ``-vmware-tsc-map`` =20 Use VMware TSC map instead of native RDTSC. =20 -* --vdev +* ``--vdev`` + + Add a virtual device using the format:: + + [,key=3Dval, ...] =20 - Add a virtual device, with format "[,key=3Dval, ...]", e= .g. --vdev=3Deth_pcap0,iface=3Deth2. + For example:: =20 -* --base-virtaddr + --vdev 'eth_pcap0,rx_pcap=3Dinput.pcap,tx_pcap=3Doutput.pcap' + +* ``--base-virtaddr`` =20 Specify base virtual address. =20 -* --create-uio-dev +* ``--create-uio-dev`` =20 - Create /dev/uioX (usually done by hotplug). + Create ``/dev/uioX`` (usually done by hotplug). =20 -* --no-shconf +* ``--no-shconf`` =20 - No shared config (mmap'd files). + No shared config (mmap-ed files). =20 -* --no-pci +* ``--no-pci`` =20 Disable pci. =20 -* --no-hpet +* ``--no-hpet`` =20 Disable hpet. =20 -* --no-huge +* ``--no-huge`` =20 Use malloc instead of hugetlbfs. =20 @@ -155,278 +161,294 @@ Testpmd Command-line Options ---------------------------- =20 The following are the command-line options for the testpmd applications. -They must be separated from the EAL options, shown in the previous secti= on, with a -- separator: +They must be separated from the EAL options, shown in the previous secti= on, with a ``--`` separator: =20 .. code-block:: console =20 sudo ./testpmd -c 0xF -n 4 -- -i --portmask=3D0x1 --nb-cores=3D2 =20 -* -i, --interactive +The commandline options are: + +* ``-i, --interactive`` =20 Run testpmd in interactive mode. In this mode, the testpmd starts with a prompt that can be used to s= tart and stop forwarding, configure the application and display stats on the current packet pr= ocessing session. - See the Section 5.0, "Test Runtime Functions" section for more detai= ls. + See :ref:`testpmd_runtime` for more details. =20 In non-interactive mode, the application starts with the configuration specified on the comma= nd-line and immediately enters forwarding mode. =20 -* -h, --help +* ``-h, --help`` =20 Display a help message and quit. =20 -* -a, --auto-start +* ``-a, --auto-start`` =20 - Start forwarding on init. + Start forwarding on initialization. =20 -* --nb-cores=3DN +* ``--nb-cores=3DN`` =20 Set the number of forwarding cores, - where 1 <=3D N <=3D number of cores or RTE_MAX_LCORE from the config= uration file. + where 1 <=3D N <=3D "number of cores" or ``CONFIG_RTE_MAX_LCORE`` fr= om the configuration file. The default value is 1. =20 -* --nb-ports=3DN +* ``--nb-ports=3DN`` =20 Set the number of forwarding ports, - where 1 <=3D N <=3D number of ports on the board or RTE_MAX_ETHPORTS= from the configuration file. + where 1 <=3D N <=3D "number of ports" on the board or ``CONFIG_RTE_M= AX_ETHPORTS`` from the configuration file. The default value is the number of ports on the board. =20 -* --coremask=3D0xXX +* ``--coremask=3D0xXX`` =20 Set the hexadecimal bitmask of the cores running the packet forwardi= ng test. The master lcore is reserved for command line parsing only and canno= t be masked on for packet forwarding. =20 -* --portmask=3D0xXX +* ``--portmask=3D0xXX`` =20 Set the hexadecimal bitmask of the ports used by the packet forwardi= ng test. =20 -* --numa +* ``--numa`` =20 Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers= (mbufs). =20 -* --port-numa-config=3D(port,socket)[,(port,socket)] +* ``--port-numa-config=3D(port,socket)[,(port,socket)]`` =20 Specify the socket on which the memory pool to be used by the port w= ill be allocated. =20 -* --ring-numa-config=3D(port,flag,socket)[,(port,flag,socket)] +* ``--ring-numa-config=3D(port,flag,socket)[,(port,flag,socket)]`` =20 Specify the socket on which the TX/RX rings for the port will be all= ocated. Where flag is 1 for RX, 2 for TX, and 3 for RX and TX. =20 -* --socket-num=3DN +* ``--socket-num=3DN`` =20 Set the socket from which all memory is allocated in NUMA mode, where 0 <=3D N < number of sockets on the board. =20 -* --mbuf-size=3DN +* ``--mbuf-size=3DN`` =20 Set the data size of the mbufs used to N bytes, where N < 65536. The= default value is 2048. =20 -* --total-num-mbufs=3DN +* ``--total-num-mbufs=3DN`` =20 Set the number of mbufs to be allocated in the mbuf pools, where N >= 1024. =20 -* --max-pkt-len=3DN +* ``--max-pkt-len=3DN`` =20 Set the maximum packet size to N bytes, where N >=3D 64. The default= value is 1518. =20 -* --eth-peers-configfile=3Dname +* ``--eth-peers-configfile=3Dname`` =20 Use a configuration file containing the Ethernet addresses of the pe= er ports. - The configuration file should contain the Ethernet addresses on sepa= rate lines: - - XX:XX:XX:XX:XX:01 + The configuration file should contain the Ethernet addresses on sepa= rate lines:: =20 - XX:XX:XX:XX:XX:02 + XX:XX:XX:XX:XX:01 + XX:XX:XX:XX:XX:02 + ... =20 - ... =20 -* --eth-peer=3DN,XX:XX:XX:XX:XX:XX +* ``--eth-peer=3DN,XX:XX:XX:XX:XX:XX`` =20 - Set the MAC address XX:XX:XX:XX:XX:XX of the peer port N, - where 0 <=3D N < RTE_MAX_ETHPORTS from the configuration file. + Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N, + where 0 <=3D N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration = file. =20 -* --pkt-filter-mode=3Dmode +* ``--pkt-filter-mode=3Dmode`` =20 - Set Flow Director mode where mode is either none (the default), sign= ature or perfect. - See the Section 5.6, "Flow Director Functions" for more detail. + Set Flow Director mode where mode is either ``none`` (the default), = ``signature`` or ``perfect``. + See :ref:`testpmd_flow_director` for more details. =20 -* --pkt-filter-report-hash=3Dmode +* ``--pkt-filter-report-hash=3Dmode`` =20 - Set Flow Director hash match reporting mode where mode is none, matc= h (the default) or always. + Set Flow Director hash match reporting mode where mode is ``none``, = ``match`` (the default) or ``always``. =20 -* --pkt-filter-size=3DN +* ``--pkt-filter-size=3DN`` =20 Set Flow Director allocated memory size, where N is 64K, 128K or 256= K. Sizes are in kilobytes. The default is 64. =20 -* --pkt-filter-flexbytes-offset=3DN +* ``--pkt-filter-flexbytes-offset=3DN`` =20 Set the flexbytes offset. The offset is defined in words (not bytes) counted from the first by= te of the destination Ethernet MAC address, where N is 0 <=3D N <=3D 32. The default value is 0x6. =20 -* --pkt-filter-drop-queue=3DN +* ``--pkt-filter-drop-queue=3DN`` =20 Set the drop-queue. In perfect filter mode, when a rule is added with queue =3D -1, the = packet will be enqueued into the RX drop-queue. If the drop-queue does not exist, the packet is dropped. The default= value is N=3D127. =20 -* --crc-strip +* ``--crc-strip`` =20 Enable hardware CRC stripping. =20 -* --enable-rx-cksum +* ``--enable-rx-cksum`` =20 Enable hardware RX checksum offload. =20 -* --disable-hw-vlan +* ``--disable-hw-vlan`` =20 Disable hardware VLAN. =20 -* --disable-hw-vlan-filter +* ``--disable-hw-vlan-filter`` =20 Disable hardware VLAN filter. =20 -* --disable-hw-vlan-strip +* ``--disable-hw-vlan-strip`` =20 Disable hardware VLAN strip. =20 -* --disable-hw-vlan-extend +* ``--disable-hw-vlan-extend`` =20 Disable hardware VLAN extend. =20 -* --enable-drop-en +* ``--enable-drop-en`` =20 Enable per-queue packet drop for packets with no descriptors. =20 -* --disable-rss +* ``--disable-rss`` =20 Disable RSS (Receive Side Scaling). =20 -* --port-topology=3Dmode +* ``--port-topology=3Dmode`` + + Set port topology, where mode is ``paired`` (the default) or ``chain= ed``. + + In ``paired`` mode, the forwarding is between pairs of ports, for ex= ample: (0,1), (2,3), (4,5). + + In ``chained`` mode, the forwarding is to the next available port in= the port mask, for example: (0,1), (1,2), (2,0). =20 - Set port topology, where mode is paired(the default) or chained. - In paired mode, the forwarding is between pairs of ports, for exampl= e: (0,1), (2,3), (4,5). - In chained mode, the forwarding is to the next available port in the= port mask, for example: (0,1), (1,2), (2,0). The ordering of the ports can be changed using the portlist testpmd = runtime function. =20 -* --forward-mode=3DN +* ``--forward-mode=3Dmode`` =20 - Set forwarding mode. (N: io|mac|mac_retry|mac_swap|flowgen|rxonly|tx= only|csum|icmpecho|ieee1588) + Set the forwarding mode where ``mode`` is one of the following:: =20 -* --rss-ip + io (the default) + mac + mac_retry + mac_swap + flowgen + rxonly + txonly + csum + icmpecho + ieee1588 + +* ``--rss-ip`` =20 Set RSS functions for IPv4/IPv6 only. =20 -* --rss-udp +* ``--rss-udp`` =20 Set RSS functions for IPv4/IPv6 and UDP. =20 -* --rxq=3DN +* ``--rxq=3DN`` =20 Set the number of RX queues per port to N, where 1 <=3D N <=3D 65535= . The default value is 1. =20 -* --rxd=3DN +* ``--rxd=3DN`` =20 Set the number of descriptors in the RX rings to N, where N > 0. The default value is 128. =20 -* --txq=3DN +* ``--txq=3DN`` =20 Set the number of TX queues per port to N, where 1 <=3D N <=3D 65535= . The default value is 1. =20 -* --txd=3DN +* ``--txd=3DN`` =20 Set the number of descriptors in the TX rings to N, where N > 0. The default value is 512. =20 -* --burst=3DN +* ``--burst=3DN`` =20 Set the number of packets per burst to N, where 1 <=3D N <=3D 512. The default value is 16. =20 -* --mbcache=3DN +* ``--mbcache=3DN`` =20 Set the cache of mbuf memory pools to N, where 0 <=3D N <=3D 512. The default value is 16. =20 -* --rxpt=3DN +* ``--rxpt=3DN`` =20 Set the prefetch threshold register of RX rings to N, where N >=3D 0= . The default value is 8. =20 -* --rxht=3DN +* ``--rxht=3DN`` =20 Set the host threshold register of RX rings to N, where N >=3D 0. The default value is 8. =20 -* --rxfreet=3DN +* ``--rxfreet=3DN`` =20 Set the free threshold of RX descriptors to N, where 0 <=3D N < valu= e of --rxd. The default value is 0. =20 -* --rxwt=3DN +* ``--rxwt=3DN`` =20 Set the write-back threshold register of RX rings to N, where N >=3D= 0. The default value is 4. =20 -* --txpt=3DN +* ``--txpt=3DN`` =20 Set the prefetch threshold register of TX rings to N, where N >=3D 0= . The default value is 36. =20 -* --txht=3DN +* ``--txht=3DN`` =20 Set the host threshold register of TX rings to N, where N >=3D 0. The default value is 0. =20 -* --txwt=3DN +* ``--txwt=3DN`` =20 Set the write-back threshold register of TX rings to N, where N >=3D= 0. The default value is 0. =20 -* --txfreet=3DN +* ``--txfreet=3DN`` =20 - Set the transmit free threshold of TX rings to N, where 0 <=3D N <=3D= value of --txd. + Set the transmit free threshold of TX rings to N, where 0 <=3D N <=3D= value of ``--txd``. The default value is 0. =20 -* --txrst=3DN +* ``--txrst=3DN`` =20 - Set the transmit RS bit threshold of TX rings to N, where 0 <=3D N <= =3D value of --txd. + Set the transmit RS bit threshold of TX rings to N, where 0 <=3D N <= =3D value of ``--txd``. The default value is 0. =20 -* --txqflags=3D0xXXXXXXXX +* ``--txqflags=3D0xXXXXXXXX`` =20 Set the hexadecimal bitmask of TX queue flags, where 0 <=3D N <=3D 0= x7FFFFFFF. The default value is 0. =20 - Note:: + .. note:: + + When using hardware offload functions such as vlan or checksum + add ``txqflags=3D0`` to force the full-featured TX code path. + In some PMDs this may already be the default. =20 - When using hardware offload functions such as vlan, checksum..., - add txqflags=3D0, since depending on the PMD, - txqflags might be set to a non-zero value. =20 -* --rx-queue-stats-mapping=3D(port,queue,mapping)[,(port,queue,mapping= )] +* ``--rx-queue-stats-mapping=3D(port,queue,mapping)[,(port,queue,mappi= ng)]`` =20 Set the RX queues statistics counters mapping 0 <=3D mapping <=3D 15= . =20 -* --tx-queue-stats-mapping=3D(port,queue,mapping)[,(port,queue,mapping= )] +* ``--tx-queue-stats-mapping=3D(port,queue,mapping)[,(port,queue,mappi= ng)]`` =20 Set the TX queues statistics counters mapping 0 <=3D mapping <=3D 15= . =20 -* --no-flush-rx +* ``--no-flush-rx`` =20 - Don't flush the RX streams before starting forwarding. Used mainly w= ith PCAP drivers. + Don't flush the RX streams before starting forwarding. Used mainly w= ith the PCAP PMD. =20 -* --txpkts=3DX[,Y] +* ``--txpkts=3DX[,Y]`` =20 Set TX segment sizes. =20 -* --disable-link-check +* ``--disable-link-check`` =20 Disable check on link status when starting/stopping ports. diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/tes= tpmd_app_ug/testpmd_funcs.rst index aa77a91..71d831b 100644 --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst @@ -28,33 +28,43 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =20 +.. _testpmd_runtime: + Testpmd Runtime Functions =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 -Where the testpmd application is started in interactive mode, (-i|--inte= ractive), +Where the testpmd application is started in interactive mode, (``-i|--in= teractive``), it displays a prompt that can be used to start and stop forwarding, -configure the application, display statistics, set the Flow Director and= other tasks. - -.. code-block:: console +configure the application, display statistics, set the Flow Director and= other tasks:: =20 - testpmd> + testpmd> =20 The testpmd prompt has some, limited, readline support. -Common bash command- line functions such as Ctrl+a and Ctrl+e to go to t= he start and end of the prompt line are supported +Common bash command-line functions such as ``Ctrl+a`` and ``Ctrl+e`` to = go to the start and end of the prompt line are supported as well as access to the command history via the up-arrow. =20 There is also support for tab completion. -If you type a partial command and hit you get a list of the availa= ble completions: +If you type a partial command and hit ```` you get a list of the av= ailable completions: =20 .. code-block:: console =20 - testpmd> show port + testpmd> show port =20 - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_q= map X - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_q= map all - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_= qmap X - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_= qmap all - ... + info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qm= ap X + info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qm= ap all + stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_q= map X + stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_q= map all + ... + + +.. note:: + + Some examples in this document are too long to fit on one line are ar= e shown wrapped at `"\\"` for display purposes:: + + testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_w= ater) \ + (pause_time) (send_xon) (port_id) + +In the real ``testpmd>`` prompt these commands should be on a single lin= e. =20 Help Functions -------------- @@ -64,16 +74,16 @@ These are divided into sections and can be accessed u= sing help, help section or =20 .. code-block:: console =20 - testpmd> help + testpmd> help + + help control : Start and stop forwarding. + help display : Displaying port, stats and config information. + help config : Configuration information. + help ports : Configuring ports. + help registers : Reading and setting port registers. + help filters : Filters configuration help. + help all : All of the above sections. =20 - Help is available for the following sections: - help control : Start and stop forwarding. - help display : Displaying port, stats and config information. - help config : Configuration information. - help ports : Configuring ports. - help registers : Reading and setting port registers. - help filters : Filters configuration help. - help all : All of the above sections. =20 Control Functions ----------------- @@ -81,30 +91,31 @@ Control Functions start ~~~~~ =20 -Start packet forwarding with current configuration: +Start packet forwarding with current configuration:: =20 -start + testpmd> start =20 start tx_first ~~~~~~~~~~~~~~ =20 -Start packet forwarding with current configuration after sending one bur= st of packets: +Start packet forwarding with current configuration after sending one bur= st of packets:: =20 -start tx_first + testpmd> start tx_first =20 stop ~~~~ =20 -Stop packet forwarding, and display accumulated statistics: +Stop packet forwarding, and display accumulated statistics:: =20 -stop + testpmd> stop =20 quit ~~~~ =20 -Quit to prompt: +Quit to prompt:: + + testpmd> quit =20 -quit =20 Display Functions ----------------- @@ -115,143 +126,181 @@ testpmd configuration or the NIC status. show port ~~~~~~~~~ =20 -Display information for a given port or all ports: +Display information for a given port or all ports:: =20 -show port (info|stats|fdir|stat_qmap) (port_id|all) + testpmd> show port (info|stats|fdir|stat_qmap) (port_id|all) =20 The available information categories are: =20 -info : General port information such as MAC address. +* ``info``: General port information such as MAC address. =20 -stats : RX/TX statistics. +* ``stats``: RX/TX statistics. =20 -fdir : Flow Director information and statistics. +* ``fdir``: Flow Director information and statistics. =20 -stat_qmap : Queue statistics mapping. +* ``stat_qmap``: Queue statistics mapping. =20 For example: =20 .. code-block:: console =20 - testpmd> show port info 0 - - ********************* Infos for port 0 ********************* - - MAC address: XX:XX:XX:XX:XX:XX - Connect to socket: 0 - memory allocation on the socket: 0 - Link status: up - Link speed: 40000 Mbps - Link duplex: full-duplex - Promiscuous mode: enabled - Allmulticast mode: disabled - Maximum number of MAC addresses: 64 - Maximum number of MAC addresses of hash filtering: 0 - VLAN offload: - strip on - filter on - qinq(extend) off - Redirection table size: 512 - Supported flow types: - ipv4-frag - ipv4-tcp - ipv4-udp - ipv4-sctp - ipv4-other - ipv6-frag - ipv6-tcp - ipv6-udp - ipv6-sctp - ipv6-other - l2_payload + testpmd> show port info 0 + + ********************* Infos for port 0 ********************* + + MAC address: XX:XX:XX:XX:XX:XX + Connect to socket: 0 + memory allocation on the socket: 0 + Link status: up + Link speed: 40000 Mbps + Link duplex: full-duplex + Promiscuous mode: enabled + Allmulticast mode: disabled + Maximum number of MAC addresses: 64 + Maximum number of MAC addresses of hash filtering: 0 + VLAN offload: + strip on + filter on + qinq(extend) off + Redirection table size: 512 + Supported flow types: + ipv4-frag + ipv4-tcp + ipv4-udp + ipv4-sctp + ipv4-other + ipv6-frag + ipv6-tcp + ipv6-udp + ipv6-sctp + ipv6-other + l2_payload =20 show port rss reta ~~~~~~~~~~~~~~~~~~ =20 -Display the rss redirection table entry indicated by masks on port X: +Display the rss redirection table entry indicated by masks on port X:: =20 -show port (port_id) rss reta (size) (mask0, mask1...) + testpmd> show port (port_id) rss reta (size) (mask0, mask1...) =20 size is used to indicate the hardware supported reta size =20 show port rss-hash ~~~~~~~~~~~~~~~~~~ =20 -Display the RSS hash functions and RSS hash key of a port: +Display the RSS hash functions and RSS hash key of a port:: =20 -show port (port_id) rss-hash [key] + testpmd> show port (port_id) rss-hash [key] =20 clear port ~~~~~~~~~~ =20 -Clear the port statistics for a given port or for all ports: - -clear port (info|stats|fdir|stat_qmap) (port_id|all) +Clear the port statistics for a given port or for all ports:: =20 -For example: + testpmd> clear port (info|stats|fdir|stat_qmap) (port_id|all) =20 -.. code-block:: console +For example:: =20 - testpmd> clear port stats all + testpmd> clear port stats all =20 show config ~~~~~~~~~~~ =20 Displays the configuration of the application. -The configuration comes from the command-line, the runtime or the applic= ation defaults: +The configuration comes from the command-line, the runtime or the applic= ation defaults:: =20 -show config (rxtx|cores|fwd) + testpmd> show config (rxtx|cores|fwd) =20 The available information categories are: =20 -rxtx : RX/TX configuration items. +* ``rxtx``: RX/TX configuration items. =20 -cores : List of forwarding cores. +* ``cores``: List of forwarding cores. =20 -fwd : Packet forwarding configuration. +* ``fwd``: Packet forwarding configuration. =20 For example: =20 .. code-block:: console =20 - testpmd> show config rxtx + testpmd> show config rxtx + + io packet forwarding - CRC stripping disabled - packets/burst=3D16 + nb forwarding cores=3D2 - nb forwarding ports=3D1 + RX queues=3D1 - RX desc=3D128 - RX free threshold=3D0 + RX threshold registers: pthresh=3D8 hthresh=3D8 wthresh=3D4 + TX queues=3D1 - TX desc=3D512 - TX free threshold=3D0 + TX threshold registers: pthresh=3D36 hthresh=3D0 wthresh=3D0 + TX RS bit threshold=3D0 - TXQ flags=3D0x0 + +set fwd +~~~~~~~ + +Set the packet forwarding mode:: + + testpmd> set fwd (io|mac|mac_retry|macswap|flowgen| \ + rxonly|txonly|csum|icmpecho) + +The available information categories are: + +* ``io``: Forwards packets "as-is" in I/O mode. + This is the fastest possible forwarding operation as it does not acces= s packets data. + This is the default mode. + +* ``mac``: Changes the source and the destination Ethernet addresses of = packets before forwarding them. + +* ``mac_retry``: Same as "mac" forwarding mode, but includes retries if = the destination queue is full. + +* ``macswap``: MAC swap forwarding mode. + Swaps the source and the destination Ethernet addresses of packets bef= ore forwarding them. + +* ``flowgen``: Multi-flow generation mode. + Originates a number of flows (with varying destination IP addresses), = and terminate receive traffic. + +* ``rxonly``: Receives packets but doesn't transmit them. + +* ``txonly``: Generates and transmits packets without receiving any. + +* ``csum``: Changes the checksum field with hardware or software methods= depending on the offload flags on the packet. + +* ``icmpecho``: Receives a burst of packets, lookup for IMCP echo reques= ts and, if any, send back ICMP echo replies. + +* ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and T= X. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=3Dy``. + +Note: TX timestamping is only available in the "Full Featured" TX path. = To force ``testpmd`` into this mode set ``--txqflags=3D0``. + +Example:: + + testpmd> set fwd rxonly + + Set rxonly packet forwarding mode =20 - io packet forwarding - CRC stripping disabled - packets/burst=3D16 - nb forwarding cores=3D2 - nb forwarding ports=3D1 - RX queues=3D1 - RX desc=3D128 - RX free threshold=3D0 - RX threshold registers: pthresh=3D8 hthresh=3D8 wthresh=3D4 - TX queues=3D1 - TX desc=3D512 - TX free threshold=3D0 - TX threshold registers: pthresh=3D36 hthresh=3D0 wthresh=3D0 - TX RS bit threshold=3D0 - TXQ flags=3D0x0 =20 read rxd ~~~~~~~~ =20 -Display an RX descriptor for a port RX queue: - -read rxd (port_id) (queue_id) (rxd_id) +Display an RX descriptor for a port RX queue:: =20 -For example: + testpmd> read rxd (port_id) (queue_id) (rxd_id) =20 -.. code-block:: console +For example:: =20 - testpmd> read rxd 0 0 4 + testpmd> read rxd 0 0 4 0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180 =20 read txd ~~~~~~~~ =20 -Display a TX descriptor for a port TX queue: - -read txd (port_id) (queue_id) (txd_id) +Display a TX descriptor for a port TX queue:: =20 -For example: + testpmd> read txd (port_id) (queue_id) (txd_id) =20 -.. code-block:: console +For example:: =20 - testpmd> read txd 0 0 4 + testpmd> read txd 0 0 4 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C =20 + Configuration Functions ----------------------- =20 @@ -261,21 +310,21 @@ This section details the available configuration fu= nctions that are available. =20 .. note:: =20 - Configuration changes only become active when forwarding is started/= restarted. + Configuration changes only become active when forwarding is started/r= estarted. =20 set default ~~~~~~~~~~~ =20 -Reset forwarding to the default configuration: +Reset forwarding to the default configuration:: =20 -set default + testpmd> set default =20 set verbose ~~~~~~~~~~~ =20 -Set the debug verbosity level: +Set the debug verbosity level:: =20 -set verbose (level) + testpmd> set verbose (level) =20 Currently the only available levels are 0 (silent except for error) and = 1 (fully verbose). =20 @@ -286,276 +335,277 @@ Set the number of ports used by the application: =20 set nbport (num) =20 -This is equivalent to the --nb-ports command-line option. +This is equivalent to the ``--nb-ports`` command-line option. =20 set nbcore ~~~~~~~~~~ =20 -Set the number of cores used by the application: +Set the number of cores used by the application:: =20 -set nbcore (num) + testpmd> set nbcore (num) =20 -This is equivalent to the --nb-cores command-line option. +This is equivalent to the ``--nb-cores`` command-line option. =20 .. note:: =20 - The number of cores used must not be greater than number of ports us= ed multiplied by the number of queues per port. + The number of cores used must not be greater than number of ports use= d multiplied by the number of queues per port. =20 set coremask ~~~~~~~~~~~~ =20 -Set the forwarding cores hexadecimal mask: +Set the forwarding cores hexadecimal mask:: =20 -set coremask (mask) + testpmd> set coremask (mask) =20 -This is equivalent to the --coremask command-line option. +This is equivalent to the ``--coremask`` command-line option. =20 .. note:: =20 - The master lcore is reserved for command line parsing only and canno= t be masked on for packet forwarding. + The master lcore is reserved for command line parsing only and cannot= be masked on for packet forwarding. =20 set portmask ~~~~~~~~~~~~ =20 -Set the forwarding ports hexadecimal mask: +Set the forwarding ports hexadecimal mask:: =20 -set portmask (mask) + testpmd> set portmask (mask) =20 -This is equivalent to the --portmask command-line option. +This is equivalent to the ``--portmask`` command-line option. =20 set burst ~~~~~~~~~ =20 -Set number of packets per burst: +Set number of packets per burst:: =20 -set burst (num) + testpmd> set burst (num) =20 -This is equivalent to the --burst command-line option. +This is equivalent to the ``--burst command-line`` option. =20 -In mac_retry forwarding mode, the transmit delay time and number of retr= ies can also be set. +In ``mac_retry`` forwarding mode, the transmit delay time and number of = retries can also be set:: =20 -set burst tx delay (micrseconds) retry (num) + testpmd> set burst tx delay (micrseconds) retry (num) =20 set txpkts ~~~~~~~~~~ =20 -Set the length of each segment of the TX-ONLY packets: +Set the length of each segment of the TX-ONLY packets:: =20 -set txpkts (x[,y]*) + testpmd> set txpkts (x[,y]*) =20 Where x[,y]* represents a CSV list of values, without white space. =20 set corelist ~~~~~~~~~~~~ =20 -Set the list of forwarding cores: +Set the list of forwarding cores:: =20 -set corelist (x[,y]*) + testpmd> set corelist (x[,y]*) =20 For example, to change the forwarding cores: =20 .. code-block:: console =20 - testpmd> set corelist 3,1 - testpmd> show config fwd + testpmd> set corelist 3,1 + testpmd> show config fwd =20 - io packet forwarding - ports=3D2 - cores=3D2 - streams=3D2 - NUMA su= pport disabled - Logical Core 3 (socket 0) forwards packets on 1 streams: - RX P=3D0/Q=3D0 (socket 0) -> TX P=3D1/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:01 - Logical Core 1 (socket 0) forwards packets on 1 streams: - RX P=3D1/Q=3D0 (socket 0) -> TX P=3D0/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:00 + io packet forwarding - ports=3D2 - cores=3D2 - streams=3D2 - NUMA sup= port disabled + Logical Core 3 (socket 0) forwards packets on 1 streams: + RX P=3D0/Q=3D0 (socket 0) -> TX P=3D1/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:01 + Logical Core 1 (socket 0) forwards packets on 1 streams: + RX P=3D1/Q=3D0 (socket 0) -> TX P=3D0/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:00 =20 .. note:: =20 - The cores are used in the same order as specified on the command lin= e. + The cores are used in the same order as specified on the command line= . =20 set portlist ~~~~~~~~~~~~ =20 -Set the list of forwarding ports: +Set the list of forwarding ports:: =20 -set portlist (x[,y]*) + testpmd> set portlist (x[,y]*) =20 For example, to change the port forwarding: =20 .. code-block:: console =20 - testpmd> set portlist 0,2,1,3 - testpmd> show config fwd + testpmd> set portlist 0,2,1,3 + testpmd> show config fwd =20 - io packet forwarding - ports=3D4 - cores=3D1 - streams=3D4 - Logical Core 3 (socket 0) forwards packets on 4 streams: - RX P=3D0/Q=3D0 (socket 0) -> TX P=3D2/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:01 - RX P=3D2/Q=3D0 (socket 0) -> TX P=3D0/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:00 - RX P=3D1/Q=3D0 (socket 0) -> TX P=3D3/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:03 - RX P=3D3/Q=3D0 (socket 0) -> TX P=3D1/Q=3D0 (socket 0) peer=3D02:00:= 00:00:00:02 + io packet forwarding - ports=3D4 - cores=3D1 - streams=3D4 + Logical Core 3 (socket 0) forwards packets on 4 streams: + RX P=3D0/Q=3D0 (socket 0) -> TX P=3D2/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:01 + RX P=3D2/Q=3D0 (socket 0) -> TX P=3D0/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:00 + RX P=3D1/Q=3D0 (socket 0) -> TX P=3D3/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:03 + RX P=3D3/Q=3D0 (socket 0) -> TX P=3D1/Q=3D0 (socket 0) peer=3D02:00:0= 0:00:00:02 =20 vlan set strip ~~~~~~~~~~~~~~ =20 -Set the VLAN strip on a port: +Set the VLAN strip on a port:: =20 -vlan set strip (on|off) (port_id) + testpmd> vlan set strip (on|off) (port_id) =20 vlan set stripq ~~~~~~~~~~~~~~~ =20 -Set the VLAN strip for a queue on a port: +Set the VLAN strip for a queue on a port:: =20 -vlan set stripq (on|off) (port_id,queue_id) + testpmd> vlan set stripq (on|off) (port_id,queue_id) =20 vlan set filter ~~~~~~~~~~~~~~~ =20 -Set the VLAN filter on a port: +Set the VLAN filter on a port:: =20 -vlan set filter (on|off) (port_id) + testpmd> vlan set filter (on|off) (port_id) =20 vlan set qinq ~~~~~~~~~~~~~ =20 -Set the VLAN QinQ (extended queue in queue) on for a port: +Set the VLAN QinQ (extended queue in queue) on for a port:: =20 -vlan set qinq (on|off) (port_id) + testpmd> vlan set qinq (on|off) (port_id) =20 vlan set tpid ~~~~~~~~~~~~~ =20 -Set the outer VLAN TPID for packet filtering on a port: +Set the outer VLAN TPID for packet filtering on a port:: =20 -vlan set tpid (value) (port_id) + testpmd> vlan set tpid (value) (port_id) =20 .. note:: =20 - TPID value must be a 16-bit number (value <=3D 65536). + TPID value must be a 16-bit number (value <=3D 65536). =20 rx_vlan add ~~~~~~~~~~~ =20 -Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filter= ed by port ID: +Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filter= ed by port ID:: =20 -rx_vlan add (vlan_id|all) (port_id) + testpmd> rx_vlan add (vlan_id|all) (port_id) =20 .. note:: =20 - VLAN filter must be set on that port. VLAN ID < 4096. - Depending on the NIC used, number of vlan_ids may be limited to the = maximum entries - in VFTA table. This is important if enabling all vlan_ids. + VLAN filter must be set on that port. VLAN ID < 4096. + Depending on the NIC used, number of vlan_ids may be limited to the m= aximum entries + in VFTA table. This is important if enabling all vlan_ids. =20 rx_vlan rm ~~~~~~~~~~ =20 -Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers f= iltered by port ID: +Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers f= iltered by port ID:: =20 -rx_vlan rm (vlan_id|all) (port_id) + testpmd> rx_vlan rm (vlan_id|all) (port_id) =20 -rx_vlan add(for VF) -~~~~~~~~~~~~~~~~~~~ +rx_vlan add (for VF) +~~~~~~~~~~~~~~~~~~~~ =20 -Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for por= t ID: +Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for por= t ID:: =20 -rx_vlan add (vlan_id) port (port_id) vf (vf_mask) + testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask) =20 -rx_vlan rm(for VF) -~~~~~~~~~~~~~~~~~~ +rx_vlan rm (for VF) +~~~~~~~~~~~~~~~~~~~ =20 -Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) fo= r port ID: +Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) fo= r port ID:: =20 -rx_vlan rm (vlan_id) port (port_id) vf (vf_mask) + testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask) =20 rx_vlan set tpid ~~~~~~~~~~~~~~~~ =20 -Set the outer VLAN TPID for packet filtering on a port: +Set the outer VLAN TPID for packet filtering on a port:: =20 -rx_vlan set tpid (value) (port_id) + testpmd> rx_vlan set tpid (value) (port_id) =20 tunnel_filter add ~~~~~~~~~~~~~~~~~ =20 -Add a tunnel filter on a port: +Add a tunnel filter on a port:: =20 -tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) (inner_vla= n) - (tunnel_type) (filter_type) (tenant_id) (queue_id) + testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr= ) \ + (inner_vlan) (tunnel_type) (filter_type) (tenant_id) (queue_= id) =20 tunnel_filter remove ~~~~~~~~~~~~~~~~~~~~ =20 -Remove a tunnel filter on a port: +Remove a tunnel filter on a port:: =20 -tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) (inner_vlan= ) - (tunnel_type) (filter_type) (tenant_id) (queue_id) + testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr)= \ + (inner_vlan) (tunnel_type) (filter_type) (tenant_id) (queue_= id) =20 rx_vxlan_port add ~~~~~~~~~~~~~~~~~ =20 -Add an UDP port for VXLAN packet filter on a port: +Add an UDP port for VXLAN packet filter on a port:: =20 -rx_vxlan_port add (udp_port) (port_id) + testpmd> rx_vxlan_port add (udp_port) (port_id) =20 rx_vxlan_port remove ~~~~~~~~~~~~~~~~~~~~ =20 -Remove an UDP port for VXLAN packet filter on a port: +Remove an UDP port for VXLAN packet filter on a port:: =20 -rx_vxlan_port rm (udp_port) (port_id) + testpmd> rx_vxlan_port rm (udp_port) (port_id) =20 tx_vlan set ~~~~~~~~~~~ =20 -Set hardware insertion of VLAN IDs in packets sent on a port: +Set hardware insertion of VLAN IDs in packets sent on a port:: =20 -tx_vlan set (port_id) vlan_id[, vlan_id_outer] + testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer] =20 -.. code-block:: console +For example, set a single VLAN ID (5) insertion on port 0:: =20 - Set a single VLAN ID (5) insertion on port 0. + tx_vlan set 0 5 =20 - tx_vlan set 0 5 +Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1:: =20 - Set double VLAN ID (inner: 2, outer: 3) insertion on port 1. + tx_vlan set 1 2 3 =20 - tx_vlan set 1 2 3 =20 tx_vlan set pvid ~~~~~~~~~~~~~~~~ =20 -Set port based hardware insertion of VLAN ID in packets sent on a port: +Set port based hardware insertion of VLAN ID in packets sent on a port:: =20 -tx_vlan set pvid (port_id) (vlan_id) (on|off) + testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off) =20 tx_vlan reset ~~~~~~~~~~~~~ =20 -Disable hardware insertion of a VLAN header in packets sent on a port: +Disable hardware insertion of a VLAN header in packets sent on a port:: =20 -tx_vlan reset (port_id) + testpmd> tx_vlan reset (port_id) =20 csum set ~~~~~~~~ =20 Select hardware or software calculation of the checksum when -transmitting a packet using the csum forward engine: +transmitting a packet using the ``csum`` forwarding engine:: + + testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id) =20 -csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id) +Where: =20 -- ip|udp|tcp|sctp always concern the inner layer. +* ``ip|udp|tcp|sctp`` always relate to the inner layer. =20 -- outer-ip concerns the outer IP layer (only for IPv4) in case the packe= t is recognized - as a tunnel packet by the forward engine (vxlan, gre and ipip are - supported). See "csum parse-tunnel" command. +* ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case= where the packet is recognized + as a tunnel packet by the forwarding engine (vxlan, gre and ipip are + supported). See also the ``csum parse-tunnel`` command. =20 .. note:: =20 - Check the NIC Datasheet for hardware limits. + Check the NIC Datasheet for hardware limits. =20 csum parse-tunnel ~~~~~~~~~~~~~~~~~ =20 Define how tunneled packets should be handled by the csum forward -engine. +engine:: =20 -csum parse-tunnel (on|off) (tx_port_id) + testpmd> csum parse-tunnel (on|off) (tx_port_id) =20 If enabled, the csum forward engine will try to recognize supported tunnel headers (vxlan, gre, ipip). @@ -565,305 +615,280 @@ header is handled as a packet payload). =20 .. note:: =20 - The port argument is the TX port like in the "csum set" command. + The port argument is the TX port like in the ``csum set`` command. =20 Example: =20 -Consider a packet as following: -"eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in" +Consider a packet in packet like the following:: =20 -- If parse-tunnel is enabled, the ip|udp|tcp|sctp parameters of "csum - set" command are about inner headers (here ipv4_in and tcp_in), and th= e - outer-ip parameter is about outer headers (here ipv4_out). + eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in =20 -- If parse-tunnel is disabled, the ip|udp|tcp|sctp parameters of "csum - set" command are about outer headers, here ipv4_out and udp_out. +* If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``cs= um set`` + command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``),= and the + ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``= ). + +* If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``c= sum set`` + command relate to the outer headers, here ``ipv4_out`` and ``udp_out`= `. =20 csum show ~~~~~~~~~ =20 -Display tx checksum offload configuration: +Display tx checksum offload configuration:: =20 -csum show (port_id) + testpmd> csum show (port_id) =20 tso set ~~~~~~~ =20 -Enable TCP Segmentation Offload in csum forward engine: +Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine:= : =20 -tso set (segsize) (port_id) + testpmd> tso set (segsize) (port_id) =20 .. note:: =20 - Check the NIC datasheet for hardware limits + Check the NIC datasheet for hardware limits. =20 tso show ~~~~~~~~ =20 -Display the status of TCP Segmentation Offload: - -tso show (port_id) +Display the status of TCP Segmentation Offload:: =20 -set fwd -~~~~~~~ - -Set the packet forwarding mode: - -set fwd (io|mac|mac_retry|macswap|flowgen|rxonly|txonly|csum|icmpecho) - -The available information categories are: - -* io: forwards packets "as-is" in I/O mode. - This is the fastest possible forwarding operation as it does not acc= ess packets data. - This is the default mode. - -* mac: changes the source and the destination Ethernet addresses of pa= ckets before forwarding them. - -* mac_retry: same as "mac" forwarding mode, but includes retries if th= e destination queue is full. - -* macswap: MAC swap forwarding mode. - Swaps the source and the destination Ethernet addresses of packets b= efore forwarding them. - -* flowgen: multi-flow generation mode. - Originates a bunch of flows (varying destination IP addresses), and = terminate receive traffic. - -* rxonly: receives packets but doesn't transmit them. - -* txonly: generates and transmits packets without receiving any. - -* csum: changes the checksum field with HW or SW methods depending on = the offload flags on the packet. - -* icmpecho: receives a burst of packets, lookup for IMCP echo requests= and, if any, send back ICMP echo replies. - -* ieee1588: demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX.= Requires ``CONFIG_RTE_LIBRTE_IEEE1588=3Dy``. - Note: TX timestamping is only available in the "Full Featured" TX pa= th. To force ``testpmd`` into this mode set ``--txqflags=3D0``. - -Example: - -.. code-block:: console - - testpmd> set fwd rxonly - - Set rxonly packet forwarding mode + testpmd> tso show (port_id) =20 mac_addr add ~~~~~~~~~~~~ =20 -Add an alternative MAC address to a port: +Add an alternative MAC address to a port:: =20 -mac_addr add (port_id) (XX:XX:XX:XX:XX:XX) + testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX) =20 mac_addr remove ~~~~~~~~~~~~~~~ =20 -Remove a MAC address from a port: +Remove a MAC address from a port:: =20 -mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) + testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) =20 mac_addr add(for VF) ~~~~~~~~~~~~~~~~~~~~ =20 -Add an alternative MAC address for a VF to a port: +Add an alternative MAC address for a VF to a port:: =20 -mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) + testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) =20 set port-uta ~~~~~~~~~~~~ =20 -Set the unicast hash filter(s) on/off for a port X: +Set the unicast hash filter(s) on/off for a port:: =20 -set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off) + testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off) =20 set promisc ~~~~~~~~~~~ =20 Set the promiscuous mode on for a port or for all ports. -In promiscuous mode packets are not dropped if they aren't for the speci= fied MAC address: +In promiscuous mode packets are not dropped if they aren't for the speci= fied MAC address:: =20 -set promisc (port_id|all) (on|off) + testpmd> set promisc (port_id|all) (on|off) =20 set allmulti ~~~~~~~~~~~~ =20 -Set the allmulti mode for a port or for all ports: +Set the allmulti mode for a port or for all ports:: =20 -set allmulti (port_id|all) (on|off) + testpmd> set allmulti (port_id|all) (on|off) =20 Same as the ifconfig (8) option. Controls how multicast packets are hand= led. =20 set flow_ctrl rx ~~~~~~~~~~~~~~~~ =20 -Set the link flow control parameter on a port: +Set the link flow control parameter on a port:: =20 -set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ -(pause_time) (send_xon) (port_id) + testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_wate= r) \ + (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \ + autoneg (on|off) (port_id) =20 Where: =20 -high_water (integer): High threshold value to trigger XOFF. +* ``high_water`` (integer): High threshold value to trigger XOFF. + +* ``low_water`` (integer): Low threshold value to trigger XON. =20 -low_water (integer) : Low threshold value to trigger XON. +* ``pause_time`` (integer): Pause quota in the Pause frame. =20 -pause_time (integer): Pause quota in the Pause frame. +* ``send_xon`` (0/1): Send XON frame. =20 -send_xon (0/1) : Send XON frame. +* ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames. =20 -mac_ctrl_frame_fwd : Enable receiving MAC control frames +* ``autoneg``: Change the auto-negotiation para mete. =20 set pfc_ctrl rx ~~~~~~~~~~~~~~~ =20 -Set the priority flow control parameter on a port: +Set the priority flow control parameter on a port:: =20 -set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ (pause_t= ime) (priority) (port_id) + testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water= ) \ + (pause_time) (priority) (port_id) =20 Where: =20 -priority (0-7): VLAN User Priority. +* ``high_water`` (integer): High threshold value. + +* ``low_water`` (integer): Low threshold value. + +* ``pause_time`` (integer): Pause quota in the Pause frame. + +* ``priority`` (0-7): VLAN User Priority. =20 set stat_qmap ~~~~~~~~~~~~~ =20 -Set statistics mapping (qmapping 0..15) for RX/TX queue on port: - -set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping) +Set statistics mapping (qmapping 0..15) for RX/TX queue on port:: =20 -For example, to set rx queue 2 on port 0 to mapping 5: + testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping) =20 -.. code-block:: console +For example, to set rx queue 2 on port 0 to mapping 5:: =20 - testpmd>set stat_qmap rx 0 2 5 + testpmd>set stat_qmap rx 0 2 5 =20 -set port - rx/tx(for VF) -~~~~~~~~~~~~~~~~~~~~~~~~ +set port - rx/tx (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set VF receive/transmit from a port: +Set VF receive/transmit from a port:: =20 -set port (port_id) vf (vf_id) (rx|tx) (on|off) + testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off) =20 set port - mac address filter (for VF) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Add/Remove unicast or multicast MAC addr filter for a VF: +Add/Remove unicast or multicast MAC addr filter for a VF:: =20 -set port (port_id) vf (vf_id) (mac_addr) - (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off) + testpmd> set port (port_id) vf (vf_id) (mac_addr) \ + (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off) =20 set port - rx mode(for VF) ~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set the VF receive mode of a port: +Set the VF receive mode of a port:: =20 -set port (port_id) vf (vf_id) rxmode (AUPE|ROPE|BAM|MPE) (on|off) + testpmd> set port (port_id) vf (vf_id) \ + rxmode (AUPE|ROPE|BAM|MPE) (on|off) =20 The available receive modes are: =20 -* AUPE: accepts untagged VLAN. +* ``AUPE``: Accepts untagged VLAN. =20 -* ROPE: accepts unicast hash. +* ``ROPE``: Accepts unicast hash. =20 -* BAM: accepts broadcast packets +* ``BAM``: Accepts broadcast packets. =20 -* MPE: accepts all multicast packets +* ``MPE``: Accepts all multicast packets. =20 set port - tx_rate (for Queue) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set TX rate limitation for queue of a port ID: +Set TX rate limitation for a queue on a port:: =20 -set port (port_id) queue (queue_id) rate (rate_value) + testpmd> set port (port_id) queue (queue_id) rate (rate_value) =20 set port - tx_rate (for VF) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set TX rate limitation for queues in VF of a port ID: +Set TX rate limitation for queues in VF on a port:: =20 -set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask) + testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (= queue_mask) =20 set port - mirror rule ~~~~~~~~~~~~~~~~~~~~~~ =20 -Set pool or vlan type mirror rule for a port: +Set pool or vlan type mirror rule for a port:: =20 -set port (port_id) mirror-rule (rule_id) (pool-mirror-up|pool-mirror-dow= n|vlan-mirror) (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) + testpmd> set port (port_id) mirror-rule (rule_id) \ + (pool-mirror-up|pool-mirror-down|vlan-mirror) \ + (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) =20 -Set link mirror rule for a port: +Set link mirror rule for a port:: =20 -set port (port_id) mirror-rule (rule_id) (uplink-mirror|downlink-mirror)= dst-pool (pool_id) (on|off) + testpmd> set port (port_id) mirror-rule (rule_id) \ + (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off) =20 -For example to enable mirror traffic with vlan 0,1 to pool 0: +For example to enable mirror traffic with vlan 0,1 to pool 0:: =20 -.. code-block:: console - - set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on + set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on =20 reset port - mirror rule ~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Reset a mirror rule for a port. +Reset a mirror rule for a port:: =20 -reset port (port_id) mirror-rule (rule_id) + testpmd> reset port (port_id) mirror-rule (rule_id) =20 set flush_rx ~~~~~~~~~~~~ =20 -Flush (default) or don't flush RX streams before forwarding. -Mainly used with PCAP drivers to avoid the default behavior of flushing = the first 512 packets on RX streams. +Set the flush on RX streams before forwarding. +The default is flush ``on``. +Mainly used with PCAP drivers to turn off the default behavior of flushi= ng the first 512 packets on RX streams:: =20 -set flush_rx off + testpmd> set flush_rx off =20 set bypass mode ~~~~~~~~~~~~~~~ =20 -Set the bypass mode for the lowest port on bypass enabled NIC. +Set the bypass mode for the lowest port on bypass enabled NIC:: =20 -set bypass mode (normal|bypass|isolate) (port_id) + testpmd> set bypass mode (normal|bypass|isolate) (port_id) =20 set bypass event ~~~~~~~~~~~~~~~~ =20 -Set the event required to initiate specified bypass mode for the lowest = port on a bypass enabled NIC where: +Set the event required to initiate specified bypass mode for the lowest = port on a bypass enabled:: + + testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \ + mode (normal|bypass|isolate) (port_id) =20 -* timeout: enable bypass after watchdog timeout. +Where: =20 -* os_on: enable bypass when OS/board is powered on. +* ``timeout``: Enable bypass after watchdog timeout. =20 -* os_off: enable bypass when OS/board is powered off. +* ``os_on``: Enable bypass when OS/board is powered on. =20 -* power_on: enable bypass when power supply is turned on. +* ``os_off``: Enable bypass when OS/board is powered off. =20 -* power_off: enable bypass when power supply is turned off. +* ``power_on``: Enable bypass when power supply is turned on. + +* ``power_off``: Enable bypass when power supply is turned off. =20 -set bypass event (timeout|os_on|os_off|power_on|power_off) mode (normal|= bypass|isolate) (port_id) =20 set bypass timeout ~~~~~~~~~~~~~~~~~~ =20 -Set the bypass watchdog timeout to 'n' seconds where 0 =3D instant. +Set the bypass watchdog timeout to ``n`` seconds where 0 =3D instant:: =20 -set bypass timeout (0|1.5|2|3|4|8|16|32) + testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32) =20 show bypass config ~~~~~~~~~~~~~~~~~~ =20 -Show the bypass configuration for a bypass enabled NIC using the lowest = port on the NIC. +Show the bypass configuration for a bypass enabled NIC using the lowest = port on the NIC:: =20 -show bypass config (port_id) + testpmd> show bypass config (port_id) =20 set link up ~~~~~~~~~~~ =20 -Set link up for a port. +Set link up for a port:: =20 -set link-up port (port id) + testpmd> set link-up port (port id) =20 set link down ~~~~~~~~~~~~~ =20 -Set link down for a port. +Set link down for a port:: + + testpmd> set link-down port (port id) =20 -set link-down port (port id) =20 Port Functions -------------- @@ -872,7 +897,7 @@ The following sections show functions for configuring= ports. =20 .. note:: =20 - Port configuration changes only become active when forwarding is sta= rted/restarted. + Port configuration changes only become active when forwarding is star= ted/restarted. =20 port attach ~~~~~~~~~~~ @@ -887,22 +912,27 @@ For example, to move a pci device using ixgbe under= DPDK management: =20 .. code-block:: console =20 - ./tools/dpdk_nic_bind.py --status + # Check the status of the available devices. + ./tools/dpdk_nic_bind.py --status =20 - Network devices using DPDK-compatible driver - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - + Network devices using DPDK-compatible driver + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + =20 - Network devices using kernel driver - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - 0000:0a:00.0 '82599ES 10-Gigabit SFI/SFP+ Network Connection' if=3De= th2 drv=3Dixgbe unused=3D + Network devices using kernel driver + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 0000:0a:00.0 '82599ES 10-Gigabit' if=3Deth2 drv=3Dixgbe unused=3D =20 - ./tools/dpdk_nic_bind.py -b igb_uio 0000:0a:00.0 - ./tools/dpdk_nic_bind.py --status =20 - Network devices using DPDK-compatible driver - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - 0000:0a:00.0 '82599ES 10-Gigabit SFI/SFP+ Network Connection' drv=3D= igb_uio unused=3D + # Bind the device to igb_uio. + sudo ./tools/dpdk_nic_bind.py -b igb_uio 0000:0a:00.0 + + + # Recheck the status of the devices. + ./tools/dpdk_nic_bind.py --status + Network devices using DPDK-compatible driver + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 0000:0a:00.0 '82599ES 10-Gigabit' drv=3Digb_uio unused=3D =20 To attach a port created by virtual device, above steps are not needed. =20 @@ -912,44 +942,42 @@ For example, to attach a port whose pci address is = 0000:0a:00.0. =20 .. code-block:: console =20 - testpmd> port attach 0000:0a:00.0 - Attaching a new port... - EAL: PCI device 0000:0a:00.0 on NUMA socket -1 - EAL: probe driver: 8086:10fb rte_ixgbe_pmd - EAL: PCI memory mapped at 0x7f83bfa00000 - EAL: PCI memory mapped at 0x7f83bfa80000 - PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5 - PMD: eth_ixgbe_dev_init(): port 0 vendorID=3D0x8086 deviceID=3D0x10f= b - Port 0 is attached. Now total ports is 1 - Done - testpmd> + testpmd> port attach 0000:0a:00.0 + Attaching a new port... + EAL: PCI device 0000:0a:00.0 on NUMA socket -1 + EAL: probe driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory mapped at 0x7f83bfa00000 + EAL: PCI memory mapped at 0x7f83bfa80000 + PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5 + PMD: eth_ixgbe_dev_init(): port 0 vendorID=3D0x8086 deviceID=3D0x10fb + Port 0 is attached. Now total ports is 1 + Done =20 For example, to attach a port created by pcap PMD. =20 .. code-block:: console =20 - testpmd> port attach eth_pcap0 - Attaching a new port... - PMD: Initializing pmd_pcap for eth_pcap0 - PMD: Creating pcap-backed ethdev on numa socket 0 - Port 0 is attached. Now total ports is 1 - Done - testpmd> + testpmd> port attach eth_pcap0 + Attaching a new port... + PMD: Initializing pmd_pcap for eth_pcap0 + PMD: Creating pcap-backed ethdev on numa socket 0 + Port 0 is attached. Now total ports is 1 + Done =20 -In this case, identifier is "eth_pcap0". -This identifier format is the same as "--vdev" format of DPDK applicatio= ns. +In this case, identifier is ``eth_pcap0``. +This identifier format is the same as ``--vdev`` format of DPDK applicat= ions. =20 For example, to re-attach a bonded port which has been previously detach= ed, the mode and slave parameters must be given. =20 .. code-block:: console =20 - testpmd> port attach eth_bond_testpmd_0,mode=3D0,slave=3D1 - Attaching a new port... - EAL: Initializing pmd_bond for eth_bond_testpmd_0 - EAL: Create bonded device eth_bond_testpmd_0 on port 0 in mode 0 on = socket 0. - Port 0 is attached. Now total ports is 1 - Done + testpmd> port attach eth_bond_0,mode=3D0,slave=3D1 + Attaching a new port... + EAL: Initializing pmd_bond for eth_bond_0 + EAL: Create bonded device eth_bond_0 on port 0 in mode 0 on socket 0. + Port 0 is attached. Now total ports is 1 + Done =20 =20 port detach @@ -957,39 +985,40 @@ port detach =20 Detach a specific port. =20 -Before detaching a port, the port should be closed. +Before detaching a port, the port should be closed:: =20 -port detach (port_id) + testpmd> port detach (port_id) =20 For example, to detach a pci device port 0. =20 .. code-block:: console =20 - testpmd> port close 0 - Closing ports... - Done - testpmd> port detach 0 - Detaching a port... - EAL: PCI device 0000:0a:00.0 on NUMA socket -1 - EAL: remove driver: 8086:10fb rte_ixgbe_pmd - EAL: PCI memory unmapped at 0x7f83bfa00000 - EAL: PCI memory unmapped at 0x7f83bfa80000 - Done - testpmd> + testpmd> port close 0 + Closing ports... + Done + + testpmd> port detach 0 + Detaching a port... + EAL: PCI device 0000:0a:00.0 on NUMA socket -1 + EAL: remove driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory unmapped at 0x7f83bfa00000 + EAL: PCI memory unmapped at 0x7f83bfa80000 + Done + =20 For example, to detach a virtual device port 0. =20 .. code-block:: console =20 - testpmd> port close 0 - Closing ports... - Done - testpmd> port detach 0 - Detaching a port... - PMD: Closing pcap ethdev on numa socket 0 - Port 'eth_pcap0' is detached. Now total ports is 0 - Done - testpmd> + testpmd> port close 0 + Closing ports... + Done + + testpmd> port detach 0 + Detaching a port... + PMD: Closing pcap ethdev on numa socket 0 + Port 'eth_pcap0' is detached. Now total ports is 0 + Done =20 To remove a pci device completely from the system, first detach the port= from testpmd. Then the device should be moved under kernel management. @@ -999,214 +1028,218 @@ For example, to move a pci device under kernel m= anagement: =20 .. code-block:: console =20 - ./tools/dpdk_nic_bind.py -b ixgbe 0000:0a:00.0 - ./tools/dpdk_nic_bind.py --status + sudo ./tools/dpdk_nic_bind.py -b ixgbe 0000:0a:00.0 =20 - Network devices using DPDK-compatible driver - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - + ./tools/dpdk_nic_bind.py --status =20 - Network devices using kernel driver - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - 0000:0a:00.0 '82599ES 10-Gigabit SFI/SFP+ Network Connection' if=3De= th2 drv=3Dixgbe unused=3Digb_uio + Network devices using DPDK-compatible driver + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + + Network devices using kernel driver + =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 0000:0a:00.0 '82599ES 10-Gigabit' if=3Deth2 drv=3Dixgbe unused=3Digb_= uio =20 To remove a port created by a virtual device, above steps are not needed= . =20 port start ~~~~~~~~~~ =20 -Start all ports or a specific port: +Start all ports or a specific port:: =20 -port start (port_id|all) + testpmd> port start (port_id|all) =20 port stop ~~~~~~~~~ =20 -Stop all ports or a specific port: +Stop all ports or a specific port:: =20 -port stop (port_id|all) + testpmd> port stop (port_id|all) =20 port close ~~~~~~~~~~ =20 -Close all ports or a specific port: +Close all ports or a specific port:: =20 -port close (port_id|all) + testpmd> port close (port_id|all) =20 port start/stop queue ~~~~~~~~~~~~~~~~~~~~~ =20 -Start/stop a rx/tx queue on a specific port: +Start/stop a rx/tx queue on a specific port:: =20 -port (port_id) (rxq|txq) (queue_id) (start|stop) + testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop) =20 Only take effect when port is started. =20 port config - speed ~~~~~~~~~~~~~~~~~~~ =20 -Set the speed and duplex mode for all ports or a specific port: +Set the speed and duplex mode for all ports or a specific port:: =20 -port config (port_id|all) speed (10|100|1000|10000|auto) duplex (half|fu= ll|auto) + testpmd> port config (port_id|all) speed (10|100|1000|10000|auto) \ + duplex (half|full|auto) =20 port config - queues/descriptors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set number of queues/descriptors for rxq, txq, rxd and txd: +Set number of queues/descriptors for rxq, txq, rxd and txd:: =20 -port config all (rxq|txq|rxd|txd) (value) + testpmd> port config all (rxq|txq|rxd|txd) (value) =20 -This is equivalent to the --rxq, --txq, --rxd and --txd command-line opt= ions. +This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` = command-line options. =20 port config - max-pkt-len ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set the maximum packet length: +Set the maximum packet length:: =20 -port config all max-pkt-len (value) + testpmd> port config all max-pkt-len (value) =20 -This is equivalent to the --max-pkt-len command-line option. +This is equivalent to the ``--max-pkt-len`` command-line option. =20 port config - CRC Strip ~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set hardware CRC stripping on or off for all ports: +Set hardware CRC stripping on or off for all ports:: =20 -port config all crc-strip (on|off) + testpmd> port config all crc-strip (on|off) =20 CRC stripping is off by default. =20 -The on option is equivalent to the --crc-strip command-line option. +The ``on`` option is equivalent to the ``--crc-strip`` command-line opti= on. =20 port config - RX Checksum ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set hardware RX checksum offload to on or off for all ports: +Set hardware RX checksum offload to on or off for all ports:: =20 -port config all rx-cksum (on|off) + testpmd> port config all rx-cksum (on|off) =20 Checksum offload is off by default. =20 -The on option is equivalent to the --enable-rx-cksum command-line option= . +The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-lin= e option. =20 port config - VLAN ~~~~~~~~~~~~~~~~~~ =20 -Set hardware VLAN on or off for all ports: +Set hardware VLAN on or off for all ports:: =20 -port config all hw-vlan (on|off) + testpmd> port config all hw-vlan (on|off) =20 Hardware VLAN is on by default. =20 -The off option is equivalent to the --disable-hw-vlan command-line optio= n. +The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-li= ne option. =20 port config - VLAN filter ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set hardware VLAN filter on or off for all ports: +Set hardware VLAN filter on or off for all ports:: =20 -port config all hw-vlan-filter (on|off) + testpmd> port config all hw-vlan-filter (on|off) =20 Hardware VLAN filter is on by default. =20 -The off option is equivalent to the --disable-hw-vlan-filter command-lin= e option. +The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` com= mand-line option. =20 port config - VLAN strip ~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set hardware VLAN strip on or off for all ports: +Set hardware VLAN strip on or off for all ports:: =20 -port config all hw-vlan-strip (on|off) + testpmd> port config all hw-vlan-strip (on|off) =20 Hardware VLAN strip is on by default. =20 -The off option is equivalent to the --disable-hw-vlan-strip command-line= option. +The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` comm= and-line option. =20 port config - VLAN extend ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set hardware VLAN extend on or off for all ports: +Set hardware VLAN extend on or off for all ports:: =20 -port config all hw-vlan-extend (on|off) + testpmd> port config all hw-vlan-extend (on|off) =20 Hardware VLAN extend is off by default. =20 -The off option is equivalent to the --disable-hw-vlan-extend command-lin= e option. +The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` com= mand-line option. =20 port config - Drop Packets ~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set packet drop for packets with no descriptors on or off for all ports: +Set packet drop for packets with no descriptors on or off for all ports:= : =20 -port config all drop-en (on|off) + testpmd> port config all drop-en (on|off) =20 Packet dropping for packets with no descriptors is off by default. =20 -The on option is equivalent to the --enable-drop-en command-line option. +The ``on`` option is equivalent to the ``--enable-drop-en`` command-line= option. =20 port config - RSS ~~~~~~~~~~~~~~~~~ =20 -Set the RSS (Receive Side Scaling) mode on or off: +Set the RSS (Receive Side Scaling) mode on or off:: =20 -port config all rss (all|ip|tcp|udp|sctp|ether|none) + testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|none) =20 RSS is on by default. =20 -The off option is equivalent to the --disable-rss command-line option. +The ``none`` option is equivalent to the ``--disable-rss`` command-line = option. =20 port config - RSS Reta ~~~~~~~~~~~~~~~~~~~~~~ =20 -Set the RSS (Receive Side Scaling) redirection table: +Set the RSS (Receive Side Scaling) redirection table:: =20 -port config all rss reta (hash,queue)[,(hash,queue)] + testpmd> port config all rss reta (hash,queue)[,(hash,queue)] =20 port config - DCB ~~~~~~~~~~~~~~~~~ =20 -Set the DCB mode for an individual port: +Set the DCB mode for an individual port:: =20 -port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off) + testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (o= n|off) =20 The traffic class should be 4 or 8. =20 port config - Burst ~~~~~~~~~~~~~~~~~~~ =20 -Set the number of packets per burst: +Set the number of packets per burst:: =20 -port config all burst (value) + testpmd> port config all burst (value) =20 -This is equivalent to the --burst command-line option. +This is equivalent to the ``--burst`` command-line option. =20 port config - Threshold ~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set thresholds for TX/RX queues: +Set thresholds for TX/RX queues:: =20 -port config all (threshold) (value) + testpmd> port config all (threshold) (value) =20 Where the threshold type can be: =20 -* txpt: Set the prefetch threshold register of the TX rings, 0 <=3D va= lue <=3D 255. +* ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <=3D = value <=3D 255. + +* ``txht:`` Set the host threshold register of the TX rings, 0 <=3D valu= e <=3D 255. + +* ``txwt:`` Set the write-back threshold register of the TX rings, 0 <=3D= value <=3D 255. =20 -* txht: Set the host threshold register of the TX rings, 0 <=3D value = <=3D 255. +* ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <=3D = value <=3D 255. =20 -* txwt: Set the write-back threshold register of the TX rings, 0 <=3D = value <=3D 255. +* ``rxht:`` Set the host threshold register of the RX rings, 0 <=3D valu= e <=3D 255. =20 -* rxpt: Set the prefetch threshold register of the RX rings, 0 <=3D va= lue <=3D 255. +* ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <=3D= value <=3D 255. =20 -* rxht: Set the host threshold register of the RX rings, 0 <=3D value = <=3D 255. +* ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <=3D v= alue <=3D txd. =20 -* rxwt: Set the write-back threshold register of the RX rings, 0 <=3D = value <=3D 255. +* ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <=3D v= alue <=3D rxd. =20 -* txfreet: Set the transmit free threshold of the TX rings, 0 <=3D val= ue <=3D txd. +* ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <=3D value= <=3D txd. =20 -* rxfreet: Set the transmit free threshold of the RX rings, 0 <=3D val= ue <=3D rxd. +These threshold options are also available from the command-line. =20 -* txrst: Set the transmit RS bit threshold of TX rings, 0 <=3D value <= =3D txd. - These threshold options are also available from the command-line. =20 Link Bonding Functions ---------------------- @@ -1217,95 +1250,81 @@ manage link bonding devices from within testpmd i= nteractive prompt. create bonded device ~~~~~~~~~~~~~~~~~~~~ =20 -Create a new bonding device: +Create a new bonding device:: =20 -create bonded device (mode) (socket) + testpmd> create bonded device (mode) (socket) =20 -For example, to create a bonded device in mode 1 on socket 0. - -.. code-block:: console +For example, to create a bonded device in mode 1 on socket 0:: =20 - testpmd> create bonded 1 0 - created new bonded device (port X) + testpmd> create bonded 1 0 + created new bonded device (port X) =20 add bonding slave ~~~~~~~~~~~~~~~~~ =20 -Adds Ethernet device to a Link Bonding device: +Adds Ethernet device to a Link Bonding device:: =20 -add bonding slave (slave id) (port id) + testpmd> add bonding slave (slave id) (port id) =20 -For example, to add Ethernet device (port 6) to a Link Bonding device (p= ort 10). +For example, to add Ethernet device (port 6) to a Link Bonding device (p= ort 10):: =20 -.. code-block:: console - - testpmd> add bonding slave 6 10 + testpmd> add bonding slave 6 10 =20 =20 remove bonding slave ~~~~~~~~~~~~~~~~~~~~ =20 -Removes an Ethernet slave device from a Link Bonding device: +Removes an Ethernet slave device from a Link Bonding device:: =20 -remove bonding slave (slave id) (port id) + testpmd> remove bonding slave (slave id) (port id) =20 -For example, to remove Ethernet slave device (port 6) to a Link Bonding = device (port 10). +For example, to remove Ethernet slave device (port 6) to a Link Bonding = device (port 10):: =20 -.. code-block:: console - - testpmd> remove bonding slave 6 10 + testpmd> remove bonding slave 6 10 =20 set bonding mode ~~~~~~~~~~~~~~~~ =20 -Set the Link Bonding mode of a Link Bonding device: - -set bonding mode (value) (port id) +Set the Link Bonding mode of a Link Bonding device:: =20 -For example, to set the bonding mode of a Link Bonding device (port 10) = to broadcast (mode 3). + testpmd> set bonding mode (value) (port id) =20 -.. code-block:: console +For example, to set the bonding mode of a Link Bonding device (port 10) = to broadcast (mode 3):: =20 - testpmd> set bonding mode 3 10 + testpmd> set bonding mode 3 10 =20 set bonding primary ~~~~~~~~~~~~~~~~~~~ =20 -Set an Ethernet slave device as the primary device on a Link Bonding dev= ice: - -set bonding primary (slave id) (port id) +Set an Ethernet slave device as the primary device on a Link Bonding dev= ice:: =20 -For example, to set the Ethernet slave device (port 6) as the primary po= rt of a Link Bonding device (port 10). + testpmd> set bonding primary (slave id) (port id) =20 -.. code-block:: console +For example, to set the Ethernet slave device (port 6) as the primary po= rt of a Link Bonding device (port 10):: =20 - testpmd> set bonding primary 6 10 + testpmd> set bonding primary 6 10 =20 set bonding mac ~~~~~~~~~~~~~~~ =20 -Set the MAC address of a Link Bonding device: +Set the MAC address of a Link Bonding device:: =20 -set bonding mac (port id) (mac) + testpmd> set bonding mac (port id) (mac) =20 -For example, to set the MAC address of a Link Bonding device (port 10) t= o 00:00:00:00:00:01 - -.. code-block:: console +For example, to set the MAC address of a Link Bonding device (port 10) t= o 00:00:00:00:00:01:: =20 - testpmd> set bonding mac 10 00:00:00:00:00:01 + testpmd> set bonding mac 10 00:00:00:00:00:01 =20 set bonding xmit_balance_policy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set the transmission policy for a Link Bonding device when it is in Bala= nce XOR mode: +Set the transmission policy for a Link Bonding device when it is in Bala= nce XOR mode:: =20 -set bonding xmit_balance_policy (port_id) (l2|l23|l34) + testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34) =20 -For example, set a Link Bonding device (port 10) to use a balance policy= of layer 3+4 (IP addresses & UDP ports ) +For example, set a Link Bonding device (port 10) to use a balance policy= of layer 3+4 (IP addresses & UDP ports):: =20 -.. code-block:: console - - testpmd> set bonding xmit_balance_policy 10 l34 + testpmd> set bonding xmit_balance_policy 10 l34 =20 =20 set bonding mon_period @@ -1315,41 +1334,38 @@ Set the link status monitoring polling period in = milliseconds for a bonding devi =20 This adds support for PMD slave devices which do not support link status= interrupts. When the mon_period is set to a value greater than 0 then all PMD's whic= h do not support -link status ISR will be queried every polling interval to check if their= link status has changed. +link status ISR will be queried every polling interval to check if their= link status has changed:: =20 -set bonding mon_period (port_id) (value) + testpmd> set bonding mon_period (port_id) (value) =20 -For example, to set the link status monitoring polling period of bonded = device (port 5) to 150ms +For example, to set the link status monitoring polling period of bonded = device (port 5) to 150ms:: =20 -.. code-block:: console - - testpmd> set bonding mon_period 5 150 + testpmd> set bonding mon_period 5 150 =20 =20 show bonding config ~~~~~~~~~~~~~~~~~~~ =20 -Show the current configuration of a Link Bonding device: +Show the current configuration of a Link Bonding device:: =20 -show bonding config (port id) + testpmd> show bonding config (port id) =20 For example, to show the configuration a Link Bonding device (port 9) with 3 slave de= vices (1, 3, 4) -in balance mode with a transmission policy of layer 2+3. - -.. code-block:: console +in balance mode with a transmission policy of layer 2+3:: =20 - testpmd> show bonding config 9 + testpmd> show bonding config 9 Bonding mode: 2 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23 Slaves (3): [1 3 4] Active Slaves (3): [1 3 4] Primary: [3] =20 + Register Functions ------------------ =20 -The Register functions can be used to read from and write to registers o= n the network card referenced by a port number. +The Register Functions can be used to read from and write to registers o= n the network card referenced by a port number. This is mainly useful for debugging purposes. Reference should be made to the appropriate datasheet for the network ca= rd for details on the register addresses and fields that can be accessed. @@ -1357,86 +1373,75 @@ and fields that can be accessed. read reg ~~~~~~~~ =20 -Display the value of a port register: +Display the value of a port register:: =20 -read reg (port_id) (address) + testpmd> read reg (port_id) (address) =20 -For example, to examine the Flow Director control register (FDIRCTL, 0x0= 000EE000) on an Intel=C2=AE 82599 10 GbE Controller: +For example, to examine the Flow Director control register (FDIRCTL, 0x0= 000EE000) on an Intel 82599 10 GbE Controller:: =20 -.. code-block:: console - - testpmd> read reg 0 0xEE00 - port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) + testpmd> read reg 0 0xEE00 + port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) =20 read regfield ~~~~~~~~~~~~~ =20 -Display a port register bit field: - -read regfield (port_id) (address) (bit_x) (bit_y) +Display a port register bit field:: =20 -For example, reading the lowest two bits from the register in the exampl= e above: + testpmd> read regfield (port_id) (address) (bit_x) (bit_y) =20 -.. code-block:: console +For example, reading the lowest two bits from the register in the exampl= e above:: =20 - testpmd> read regfield 0 0xEE00 0 1 - port 0 PCI register at offset 0xEE00: bits[0, 1]=3D0x1 (1) + testpmd> read regfield 0 0xEE00 0 1 + port 0 PCI register at offset 0xEE00: bits[0, 1]=3D0x1 (1) =20 read regbit ~~~~~~~~~~~ =20 -Display a single port register bit: - -read regbit (port_id) (address) (bit_x) +Display a single port register bit:: =20 -For example, reading the lowest bit from the register in the example abo= ve: + testpmd> read regbit (port_id) (address) (bit_x) =20 -.. code-block:: console +For example, reading the lowest bit from the register in the example abo= ve:: =20 - testpmd> read regbit 0 0xEE00 0 - port 0 PCI register at offset 0xEE00: bit 0=3D1 + testpmd> read regbit 0 0xEE00 0 + port 0 PCI register at offset 0xEE00: bit 0=3D1 =20 write reg ~~~~~~~~~ =20 -Set the value of a port register: +Set the value of a port register:: =20 -write reg (port_id) (address) (value) + testpmd> write reg (port_id) (address) (value) =20 -For example, to clear a register: +For example, to clear a register:: =20 -.. code-block:: console - - testpmd> write reg 0 0xEE00 0x0 - port 0 PCI register at offset 0xEE00: 0x00000000 (0) + testpmd> write reg 0 0xEE00 0x0 + port 0 PCI register at offset 0xEE00: 0x00000000 (0) =20 write regfield ~~~~~~~~~~~~~~ =20 -Set bit field of a port register: +Set bit field of a port register:: =20 -write regfield (port_id) (address) (bit_x) (bit_y) (value) + testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value) =20 -For example, writing to the register cleared in the example above: +For example, writing to the register cleared in the example above:: =20 -.. code-block:: console - - testpmd> write regfield 0 0xEE00 0 1 2 - port 0 PCI register at offset 0xEE00: 0x00000002 (2) + testpmd> write regfield 0 0xEE00 0 1 2 + port 0 PCI register at offset 0xEE00: 0x00000002 (2) =20 write regbit ~~~~~~~~~~~~ =20 -Set single bit value of a port register: +Set single bit value of a port register:: =20 -write regbit (port_id) (address) (bit_x) (value) + testpmd> write regbit (port_id) (address) (bit_x) (value) =20 -For example, to set the high bit in the register from the example above: +For example, to set the high bit in the register from the example above:= : =20 -.. code-block:: console + testpmd> write regbit 0 0xEE00 31 1 + port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) =20 - testpmd> write regbit 0 0xEE00 31 1 - port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) =20 Filter Functions ---------------- @@ -1446,159 +1451,170 @@ This section details the available filter funct= ions that are available. ethertype_filter ~~~~~~~~~~~~~~~~~~~~ =20 -Add or delete a L2 Ethertype filter, which identify packets by their L2 = Ethertype mainly assign them to a receive queue. +Add or delete a L2 Ethertype filter, which identify packets by their L2 = Ethertype mainly assign them to a receive queue:: =20 -ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) e= thertype (ether_type) (drop|fwd) queue (queue_id) + ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address= ) \ + ethertype (ether_type) (drop|fwd) queue (queue_id) =20 The available information parameters are: =20 -* port_id: the port which the Ethertype filter assigned on. +* ``port_id``: The port which the Ethertype filter assigned on. =20 -* mac_addr: compare destination mac address. +* ``mac_addr``: Compare destination mac address. =20 -* mac_ignr: ignore destination mac address match. +* ``mac_ignr``: Ignore destination mac address match. =20 -* mac_address: destination mac address to match. +* ``mac_address``: Destination mac address to match. =20 -* ether_type: the EtherType value want to match, - for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) a= re invalid. +* ``ether_type``: The EtherType value want to match, + for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are= invalid. =20 -* queue_id : The receive queue associated with this EtherType filter. = It is meaningless when deleting or dropping. +* ``queue_id``: The receive queue associated with this EtherType filter. + It is meaningless when deleting or dropping. =20 -Example, to add/remove an ethertype filter rule: +Example, to add/remove an ethertype filter rule:: =20 -.. code-block:: console + testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \ + ethertype 0x0806 fwd queue 3 =20 - testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 ethertype= 0x0806 fwd queue 3 - testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 ethertype= 0x0806 fwd queue 3 + testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \ + ethertype 0x0806 fwd queue 3 =20 2tuple_filter ~~~~~~~~~~~~~~~~~ =20 Add or delete a 2-tuple filter, -which identify packets by specific protocol and destination TCP/UDP port -and forwards packets into one of the receive queues. +which identifies packets by specific protocol and destination TCP/UDP po= rt +and forwards packets into one of the receive queues:: =20 -2tuple_filter (port_id) (add|del) dst_port (dst_port_value) protocol (pr= otocol_value) -mask (mask_value) tcp_flags (tcp_flags_value) priority (prio_value) queu= e (queue_id) + 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \ + protocol (protocol_value) mask (mask_value) \ + tcp_flags (tcp_flags_value) priority (prio_value) \ + queue (queue_id) =20 The available information parameters are: =20 -* port_id: the port which the 2-tuple filter assigned on. +* ``port_id``: The port which the 2-tuple filter assigned on. =20 -* dst_port_value: destination port in L4. +* ``dst_port_value``: Destination port in L4. =20 -* protocol_value: IP L4 protocol. +* ``protocol_value``: IP L4 protocol. =20 -* mask_value: participates in the match or not by bit for field above,= 1b means participate. +* ``mask_value``: Participates in the match or not by bit for field abov= e, 1b means participate. =20 -* tcp_flags_value: TCP control bits. The non-zero value is invalid, wh= en the pro_value is not set to 0x06 (TCP). +* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, = when the pro_value is not set to 0x06 (TCP). =20 -* prio_value: priority of this filter. +* ``prio_value``: Priority of this filter. =20 -* queue_id: The receive queue associated with this 2-tuple filter. +* ``queue_id``: The receive queue associated with this 2-tuple filter. =20 -Example, to add/remove an 2tuple filter rule: +Example, to add/remove an 2tuple filter rule:: =20 -.. code-block:: console + testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \ + tcp_flags 0x02 priority 3 queue 3 =20 - testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 tcp= _flags 0x02 priority 3 queue 3 - testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 tcp= _flags 0x02 priority 3 queue 3 + testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \ + tcp_flags 0x02 priority 3 queue 3 =20 5tuple_filter ~~~~~~~~~~~~~~~~~ =20 Add or delete a 5-tuple filter, which consists of a 5-tuple (protocol, source and destination IP address= es, source and destination TCP/UDP/SCTP port) -and routes packets into one of the receive queues. +and routes packets into one of the receive queues:: =20 -5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip (src_addre= ss) dst_port (dst_port_value) src_port (src_port_value) -protocol (protocol_value) mask (mask_value) tcp_flags (tcp_flags_value) = priority (prio_value) queue (queue_id) + 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \ + (src_address) dst_port (dst_port_value) \ + src_port (src_port_value) protocol (protocol_value) \ + mask (mask_value) tcp_flags (tcp_flags_value) \ + priority (prio_value) queue (queue_id) =20 The available information parameters are: =20 -* port_id: the port which the 5-tuple filter assigned on. +* ``port_id``: The port which the 5-tuple filter assigned on. =20 -* dst_address: destination IP address. +* ``dst_address``: Destination IP address. =20 -* src_address: source IP address. +* ``src_address``: Source IP address. =20 -* dst_port_value: TCP/UDP destination port. +* ``dst_port_value``: TCP/UDP destination port. =20 -* src_port_value: TCP/UDP source port. +* ``src_port_value``: TCP/UDP source port. =20 -* protocol_value: L4 protocol. +* ``protocol_value``: L4 protocol. =20 -* mask_value: participates in the match or not by bit for field above,= 1b means participate +* ``mask_value``: Participates in the match or not by bit for field abov= e, 1b means participate =20 -* tcp_flags_value: TCP control bits. The non-zero value is invalid, wh= en the protocol_value is not set to 0x06 (TCP). +* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, = when the protocol_value is not set to 0x06 (TCP). =20 -* prio_value: the priority of this filter. +* ``prio_value``: The priority of this filter. =20 -* queue_id: The receive queue associated with this 5-tuple filter. +* ``queue_id``: The receive queue associated with this 5-tuple filter. =20 -Example, to add/remove an 5tuple filter rule: +Example, to add/remove an 5tuple filter rule:: =20 -.. code-block:: console + testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \ + dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ + flags 0x0 priority 3 queue 3 =20 - testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 dst_port = 64 src_port 32 protocol 0x06 mask 0x1F flags 0x0 priority 3 queue 3 - testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 dst_port = 64 src_port 32 protocol 0x06 mask 0x1F flags 0x0 priority 3 queue 3 + testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \ + dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ + flags 0x0 priority 3 queue 3 =20 syn_filter -~~~~~~~~~~~~~~ +~~~~~~~~~~ =20 -By SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a= separate queue. +Using the SYN filter, TCP packets whose *SYN* flag is set can be forwar= ded to a separate queue:: =20 -syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) + syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) =20 The available information parameters are: =20 -* port_id: the port which the SYN filter assigned on. +* ``port_id``: The port which the SYN filter assigned on. =20 -* high: this SYN filter has higher priority than other filters. +* ``high``: This SYN filter has higher priority than other filters. =20 -* low: this SYN filter has lower priority than other filters. +* ``low``: This SYN filter has lower priority than other filters. =20 -* queue_id: The receive queue associated with this SYN filter +* ``queue_id``: The receive queue associated with this SYN filter =20 -Example: - -.. code-block:: console +Example:: =20 - testpmd> syn_filter 0 add priority high queue 3 + testpmd> syn_filter 0 add priority high queue 3 =20 flex_filter ~~~~~~~~~~~ =20 With flex filter, packets can be recognized by any arbitrary pattern wit= hin the first 128 bytes of the packet -and routes packets into one of the receive queues. +and routed into one of the receive queues:: =20 -flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) -mask (mask_value) priority (prio_value) queue (queue_id) + flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \ + mask (mask_value) priority (prio_value) queue (queue_id) =20 The available information parameters are: =20 -* port_id: the port which the Flex filter is assigned on. +* ``port_id``: The port which the Flex filter is assigned on. =20 -* len_value: filter length in bytes, no greater than 128. +* ``len_value``: Filter length in bytes, no greater than 128. =20 -* bytes_value: a string in hexadecimal, means the value the flex filte= r needs to match. +* ``bytes_value``: A string in hexadecimal, means the value the flex fil= ter needs to match. =20 -* mask_value: a string in hexadecimal, bit 1 means corresponding byte = participates in the match. +* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byt= e participates in the match. =20 -* prio_value: the priority of this filter. +* ``prio_value``: The priority of this filter. =20 -* queue_id: the receive queue associated with this Flex filter. +* ``queue_id``: The receive queue associated with this Flex filter. =20 -Example: +Example:: =20 -.. code-block:: console + testpmd> flex_filter 0 add len 16 bytes 0x000000000000000000000000080= 60000 \ + mask 000C priority 3 queue 3 + + testpmd> flex_filter 0 del len 16 bytes 0x000000000000000000000000080= 60000 \ + mask 000C priority 3 queue 3 =20 - testpmd> flex_filter 0 add len 16 bytes 0x000000000000000000000000080= 60000 - mask 000C priority 3 queue 3 =20 - testpmd> flex_filter 0 del len 16 bytes 0x000000000000000000000000080= 60000 - mask 000C priority 3 queue 3 +.. _testpmd_flow_director: =20 flow_director_filter ~~~~~~~~~~~~~~~~~~~~ @@ -1606,154 +1622,158 @@ flow_director_filter The Flow Director works in receive mode to identify specific flows or se= ts of flows and route them to specific queues. =20 Two types of filtering are supported which are referred to as Perfect Ma= tch and Signature filters, the match mode -is set by the --pkt-filter-mode command-line parameter: +is set by the ``--pkt-filter-mode`` command-line parameter: =20 -* Perfect match filters. - The hardware checks a match between the masked fields of the receive= d packets and the programmed filters. +* Perfect match filters. + The hardware checks a match between the masked fields of the received = packets and the programmed filters. =20 -* Signature filters. - The hardware checks a match between a hash-based signature of the ma= sked fields of the received packet. +* Signature filters. + The hardware checks a match between a hash-based signature of the mask= ed fields of the received packet. =20 The Flow Director filters can match the different fields for different t= ype of packet: flow type, specific input set -per flow type and the flexible payload. The Flow Director can also mask = out parts of all of these fields so that filters +per flow type and the flexible payload. + +The Flow Director can also mask out parts of all of these fields so that= filters are only applied to certain fields or parts of the fields. =20 Different NICs may have different capabilities, command show port fdir (= port_id) can be used to acquire the information. =20 -# Commands to add flow director filters of different flow types. +# Commands to add flow director filters of different flow types:: =20 -flow_director_filter (port_id) (add|del|update) flow (ipv4-other|ipv4-fr= ag|ipv6-other|ipv6-frag) -src (src_ip_address) dst (dst_ip_address) vlan (vlan_value) flexbytes (f= lexbytes_value) -(drop|fwd) queue (queue_id) fd_id (fd_id_value) + flow_director_filter (port_id) (add|del|update) \ + flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) + src (src_ip_address) dst (dst_ip_address) \ + vlan (vlan_value) flexbytes (flexbytes_value) \ + (drop|fwd) queue (queue_id) fd_id (fd_id_value) =20 -flow_director_filter (port_id) (add|del|update) flow (ipv4-tcp|ipv4-udp|= ipv6-tcp|ipv6-udp) -src (src_ip_address) (src_port) dst (dst_ip_address) (dst_port) vlan (vl= an_value) -flexbytes (flexbytes_value) (drop|fwd) queue (queue_id) fd_id (fd_id_val= ue) + flow_director_filter (port_id) (add|del|update) \ + flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ + src (src_ip_address) (src_port) \ + dst (dst_ip_address) (dst_port) \ + vlan (vlan_value) flexbytes (flexbytes_value) \ + (drop|fwd) queue (queue_id) fd_id (fd_id_value) =20 -flow_director_filter (port_id) (add|del|update) flow (ipv4-sctp|ipv6-sct= p) -src (src_ip_address) (src_port) dst (dst_ip_address) (dst_port) tag (ver= ification_tag) -vlan (vlan_value) flexbytes (flexbytes_value) (drop|fwd) queue (queue_id= ) fd_id (fd_id_value) + flow_director_filter (port_id) (add|del|update) \ + flow (ipv4-sctp|ipv6-sctp) \ + src (src_ip_address) (src_port) \ + dst (dst_ip_address) (dst_port) + tag (verification_tag) vlan (vlan_value) \ + flexbytes (flexbytes_value) (drop|fwd) \ + queue (queue_id) fd_id (fd_id_value) =20 -flow_director_filter (port_id) (add|del|update) flow l2_payload -ether (ethertype) flexbytes (flexbytes_value) (drop|fwd) queue (queue_id= ) fd_id (fd_id_value) + flow_director_filter (port_id) (add|del|update) flow l2_payload \ + ether (ethertype) flexbytes (flexbytes_value) \ + (drop|fwd) queue (queue_id) fd_id (fd_id_value) =20 -For example, to add an ipv4-udp flow type filter: +For example, to add an ipv4-udp flow type filter:: =20 -.. code-block:: console + testpmd> flow_director_filter 0 add flow ipv4-udp src 2.2.2.3 32 \ + dst 2.2.2.5 33 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd= _id 1 =20 - testpmd> flow_director_filter 0 add flow ipv4-udp src 2.2.2.3 32 dst= 2.2.2.5 33 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd_id 1 +For example, add an ipv4-other flow type filter:: =20 -For example, add an ipv4-other flow type filter: - -.. code-block:: console - - testpmd> flow_director_filter 0 add flow ipv4-other src 2.2.2.3 dst = 2.2.2.5 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd_id 1 + testpmd> flow_director_filter 0 add flow ipv4-other src 2.2.2.3 \ + dst 2.2.2.5 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd_i= d 1 =20 flush_flow_director ~~~~~~~~~~~~~~~~~~~ =20 -flush all flow director filters on a device: +Flush all flow director filters on a device:: =20 -flush_flow_director (port_id) + testpmd> flush_flow_director (port_id) =20 -Example, to flush all flow director filter on port 0: - -.. code-block:: console +Example, to flush all flow director filter on port 0:: =20 testpmd> flush_flow_director 0 =20 flow_director_mask ~~~~~~~~~~~~~~~~~~ =20 -set flow director's masks on match input set +Set flow director's input masks:: =20 -flow_director_mask (port_id) vlan (vlan_value) src_mask (ipv4_src) (ipv6= _src) (src_port) dst_mask (ipv4_dst) (ipv6_dst) (dst_port) + flow_director_mask (port_id) vlan (vlan_value) \ + src_mask (ipv4_src) (ipv6_src) (src_port) \ + dst_mask (ipv4_dst) (ipv6_dst) (dst_port) =20 -Example, to set flow director mask on port 0: - -.. code-block:: console - - testpmd> flow_director_mask 0 vlan 0xefff src_mask 255.255.255.255 FF= FF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF dst_mask 255.255.255.255 FFF= F:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF +Example, to set flow director mask on port 0:: =20 + testpmd> flow_director_mask 0 vlan 0xefff \ + src_mask 255.255.255.255 \ + FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ + dst_mask 255.255.255.255 \ + FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF =20 flow_director_flex_mask ~~~~~~~~~~~~~~~~~~~~~~~ =20 -set masks of flow director's flexible payload based on certain flow type= : +set masks of flow director's flexible payload based on certain flow type= :: =20 -flow_director_flex_mask (port_id) flow (none|ipv4-other|ipv4-frag|ipv4-t= cp|ipv4-udp|ipv4-sctp| -ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|l2_payload|all) (mask) + testpmd> flow_director_flex_mask (port_id) \ + flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|= \ + ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ + l2_payload|all) (mask) =20 -Example, to set flow director's flex mask for all flow type on port 0: - -.. code-block:: console +Example, to set flow director's flex mask for all flow type on port 0:: =20 - testpmd> flow_director_flex_mask 0 flow all (0xff,0xff,0,0,0,0,0,0,0,= 0,0,0,0,0,0,0) + testpmd> flow_director_flex_mask 0 flow all \ + (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) =20 =20 flow_director_flex_payload ~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Configure flexible payload selection. +Configure flexible payload selection:: =20 -flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) + flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) =20 -For example, to select the first 16 bytes from the offset 4 (bytes) of p= acket's payload as flexible payload. +For example, to select the first 16 bytes from the offset 4 (bytes) of p= acket's payload as flexible payload:: =20 -.. code-block:: console - - testpmd> flow_director_flex_payload 0 l4 (4,5,6,7,8,9,10,11,12,13,14,= 15,16,17,18,19) + testpmd> flow_director_flex_payload 0 l4 \ + (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) =20 get_sym_hash_ena_per_port ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Get symmetric hash enable configuration per port. +Get symmetric hash enable configuration per port:: =20 -get_sym_hash_ena_per_port (port_id) + get_sym_hash_ena_per_port (port_id) =20 -For example, to get symmetric hash enable configuration of port 1. +For example, to get symmetric hash enable configuration of port 1:: =20 -.. code-block:: console - - testpmd> get_sym_hash_ena_per_port 1 + testpmd> get_sym_hash_ena_per_port 1 =20 set_sym_hash_ena_per_port ~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -Set symmetric hash enable configuration per port to enable or disable. - -set_sym_hash_ena_per_port (port_id) (enable|disable) +Set symmetric hash enable configuration per port to enable or disable:: =20 -For example, to set symmetric hash enable configuration of port 1 to ena= ble. + set_sym_hash_ena_per_port (port_id) (enable|disable) =20 -.. code-block:: console +For example, to set symmetric hash enable configuration of port 1 to ena= ble:: =20 - testpmd> set_sym_hash_ena_per_port 1 enable + testpmd> set_sym_hash_ena_per_port 1 enable =20 get_hash_global_config ~~~~~~~~~~~~~~~~~~~~~~ =20 -Get the global configurations of hash filters. - -get_hash_global_config (port_id) +Get the global configurations of hash filters:: =20 -For example, to get the global configurations of hash filters of port 1. + get_hash_global_config (port_id) =20 -.. code-block:: console +For example, to get the global configurations of hash filters of port 1:= : =20 - testpmd> get_hash_global_config 1 + testpmd> get_hash_global_config 1 =20 set_hash_global_config ~~~~~~~~~~~~~~~~~~~~~~ =20 -Set the global configurations of hash filters. +Set the global configurations of hash filters:: =20 -set_hash_global_config (port_id) (toeplitz|simple_xor|default) -(ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag|ip= v6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) -(enable|disable) + set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ + (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag= | \ + ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \ + (enable|disable) =20 -For example, to enable simple_xor for flow type of ipv6 on port 2. - -.. code-block:: console +For example, to enable simple_xor for flow type of ipv6 on port 2:: =20 - testpmd> set_hash_global_config 2 simple_xor ipv6 enable + testpmd> set_hash_global_config 2 simple_xor ipv6 enable --=20 1.8.1.4