X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftestpmd_app_ug%2Frun_app.rst;h=7994ddd95c39955a7cc146387f37cf822c5f8a95;hb=26cbb4191e91c07e8f498949b15ad33659797996;hp=ac2d07e1ba1d3203ad0d8647bfb570a892305871;hpb=ac718398f477cea795e6e6f8695b3e110a158b92;p=dpdk.git diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst old mode 100755 new mode 100644 index ac2d07e1ba..7994ddd95c --- a/doc/guides/testpmd_app_ug/run_app.rst +++ b/doc/guides/testpmd_app_ug/run_app.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2014 Intel Corporation. Running the Application ======================= @@ -34,357 +7,510 @@ Running the Application EAL Command-line Options ------------------------ -The following are the EAL command-line options that can be used in conjunction with the testpmd, -or any other Intel® DPDK application. -See the Intel® DPDK Getting Started Guide for more information on these options. - -* -c COREMASK - - Set the hexadecimal bitmask of the cores to run on. - -* -n NUM - - Set the number of memory channels to use. - -* -b, --pci-blacklist domain:bus:devid.func - - Blacklist a PCI devise to prevent EAL from using it. Multiple -b options are allowed. - -* -d LIB.so - - Load an external driver. Multiple -d options are allowed. - -* -w, --pci-whitelist domain:bus:devid:func - - Add a PCI device in white list. - -* -m MB - - Memory to allocate. See also --socket-mem. - -* -r NUM - - Set the number of memory ranks (auto-detected by default). - -* -v - - Display the version information on startup. - -* --xen-dom0 - - Support application running on Xen Domain0 without hugetlbfs. - -* --syslog - - Set the syslog facility. - -* --socket-mem - - Set the memory to allocate on specific sockets (use comma separated values). - -* --huge-dir - - Specify the directory where the hugetlbfs is mounted. - -* --proc-type - - Set the type of the current process. - -* --file-prefix - - Prefix for hugepage filenames. - -* -vmware-tsc-map - - Use VMware TSC map instead of native RDTSC. - -* --vdev - - Add a virtual device, with format "[,key=val, ...]", e.g. --vdev=eth_pcap0,iface=eth2. - -* --base-virtaddr - - Specify base virtual address. - -* --create-uio-dev - - Create /dev/uioX (usually done by hotplug). - -* --no-shconf - - No shared config (mmap'd files). - -* --no-pci - - Disable pci. - -* --no-hpet - - Disable hpet. - -* --no-huge - - Use malloc instead of hugetlbfs. +Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>` +or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for +a list of available EAL command-line options. Testpmd Command-line Options ---------------------------- The following are the command-line options for the testpmd applications. -They must be separated from the EAL options, shown in the previous section, with a -- separator: +They must be separated from the EAL options, shown in the previous section, with a ``--`` separator: .. code-block:: console - sudo ./testpmd -c 0xF -n 4 -- -i --portmask=0x1 --nb-cores=2 + sudo ./testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2 + +The command line options are: -* -i, --interactive +* ``-i, --interactive`` Run testpmd in interactive mode. In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding, configure the application and display stats on the current packet processing session. - See the Section 5.0, "Test Runtime Functions" section for more details. + See :ref:`testpmd_runtime` for more details. In non-interactive mode, the application starts with the configuration specified on the command-line and immediately enters forwarding mode. -* -h, --help +* ``-h, --help`` Display a help message and quit. -* -a, --auto-start +* ``-a, --auto-start`` - Start forwarding on init. + Start forwarding on initialization. -* --nb-cores=N +* ``--tx-first`` + + Start forwarding, after sending a burst of packets first. + +.. Note:: + + This flag should be only used in non-interactive mode. + +* ``--stats-period PERIOD`` + + Display statistics every PERIOD seconds, if interactive mode is disabled. + The default value is 0, which means that the statistics will not be displayed. + +* ``--nb-cores=N`` Set the number of forwarding cores, - where 1 <= N <= number of cores or RTE_MAX_LCORE from the configuration file. + where 1 <= N <= "number of cores" or ``CONFIG_RTE_MAX_LCORE`` from the configuration file. The default value is 1. -* --nb-ports=N +* ``--nb-ports=N`` Set the number of forwarding ports, - where 1 <= N <= number of ports on the board or RTE_MAX_ETHPORTS from the configuration file. + where 1 <= N <= "number of ports" on the board or ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file. The default value is the number of ports on the board. -* --coremask=0xXX +* ``--coremask=0xXX`` Set the hexadecimal bitmask of the cores running the packet forwarding test. The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding. -* --portmask=0xXX +* ``--portmask=0xXX`` Set the hexadecimal bitmask of the ports used by the packet forwarding test. -* --numa +* ``--portlist=X`` + + Set the forwarding ports based on the user input used by the packet forwarding test. + '-' denotes a range of ports to set including the two specified port IDs + ',' separates multiple port values. + Possible examples like --portlist=0,1 or --portlist=0-2 or --portlist=0,1-2 etc + +* ``--numa`` + + Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers + (mbufs). [Default setting] - Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs). +* ``--no-numa`` -* --port-numa-config=(port,socket)[,(port,socket)] + Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs). + +* ``--port-numa-config=(port,socket)[,(port,socket)]`` Specify the socket on which the memory pool to be used by the port will be allocated. -* --ring-numa-config=(port,flag,socket)[,(port,flag,socket)] +* ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]`` Specify the socket on which the TX/RX rings for the port will be allocated. Where flag is 1 for RX, 2 for TX, and 3 for RX and TX. -* --socket-num=N +* ``--socket-num=N`` Set the socket from which all memory is allocated in NUMA mode, where 0 <= N < number of sockets on the board. -* --mbuf-size=N +* ``--mbuf-size=N[,N1[,...Nn]`` - Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048. + Set the data size of the mbufs used to N bytes, where N < 65536. + The default value is 2048. If multiple mbuf-size values are specified the + extra memory pools will be created for allocating mbufs to receive packets + with buffer splittling features. -* --total-num-mbufs=N +* ``--total-num-mbufs=N`` Set the number of mbufs to be allocated in the mbuf pools, where N > 1024. -* --max-pkt-len=N +* ``--max-pkt-len=N`` Set the maximum packet size to N bytes, where N >= 64. The default value is 1518. -* --eth-peers-configfile=name +* ``--max-lro-pkt-size=N`` + + Set the maximum LRO aggregated packet size to N bytes, where N >= 64. + +* ``--eth-peers-configfile=name`` Use a configuration file containing the Ethernet addresses of the peer ports. - The configuration file should contain the Ethernet addresses on separate lines: + The configuration file should contain the Ethernet addresses on separate lines:: + + XX:XX:XX:XX:XX:01 + XX:XX:XX:XX:XX:02 + ... + +* ``--eth-peer=N,XX:XX:XX:XX:XX:XX`` - XX:XX:XX:XX:XX:01 + Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N, + where 0 <= N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file. - XX:XX:XX:XX:XX:02 +* ``--tx-ip=SRC,DST`` - ... + Set the source and destination IP address used when doing transmit only test. + The defaults address values are source 198.18.0.1 and + destination 198.18.0.2. These are special purpose addresses + reserved for benchmarking (RFC 5735). -* --eth-peer=N,XX:XX:XX:XX:XX:XX +* ``--tx-udp=SRC[,DST]`` - Set the MAC address XX:XX:XX:XX:XX:XX of the peer port N, - where 0 <= N < RTE_MAX_ETHPORTS from the configuration file. + Set the source and destination UDP port number for transmit test only test. + The default port is the port 9 which is defined for the discard protocol + (RFC 863). -* --pkt-filter-mode=mode +* ``--pkt-filter-mode=mode`` - Set Flow Director mode where mode is either none (the default), signature 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. -* --pkt-filter-report-hash=mode +* ``--pkt-filter-report-hash=mode`` - Set Flow Director hash match reporting mode where mode is none, match (the default) or always. + Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``. -* --pkt-filter-size=N +* ``--pkt-filter-size=N`` Set Flow Director allocated memory size, where N is 64K, 128K or 256K. Sizes are in kilobytes. The default is 64. -* --pkt-filter-flexbytes-offset=N +* ``--pkt-filter-flexbytes-offset=N`` Set the flexbytes offset. The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address, where N is 0 <= N <= 32. The default value is 0x6. -* --pkt-filter-drop-queue=N +* ``--pkt-filter-drop-queue=N`` Set the drop-queue. In perfect filter mode, when a rule is added with queue = -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=127. -* --crc-strip +* ``--disable-crc-strip`` - Enable hardware CRC stripping. + Disable hardware CRC stripping. -* --enable-rx-cksum +* ``--enable-lro`` + + Enable large receive offload. + +* ``--enable-rx-cksum`` Enable hardware RX checksum offload. -* --disable-hw-vlan +* ``--enable-scatter`` + + Enable scatter (multi-segment) RX. + +* ``--enable-hw-vlan`` - Disable hardware VLAN. + Enable hardware VLAN. -* --enable-drop-en +* ``--enable-hw-vlan-filter`` + + Enable hardware VLAN filter. + +* ``--enable-hw-vlan-strip`` + + Enable hardware VLAN strip. + +* ``--enable-hw-vlan-extend`` + + Enable hardware VLAN extend. + +* ``--enable-hw-qinq-strip`` + + Enable hardware QINQ strip. + +* ``--enable-drop-en`` Enable per-queue packet drop for packets with no descriptors. -* --disable-rss +* ``--disable-rss`` Disable RSS (Receive Side Scaling). -* --port-topology=mode +* ``--port-topology=mode`` + + Set port topology, where mode is ``paired`` (the default), ``chained`` or ``loop``. + + In ``paired`` mode, the forwarding is between pairs of ports, for example: (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). - Set port topology, where mode is paired(the default) or chained. - In paired mode, the forwarding is between pairs of ports, for example: (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. -* --forward-mode=N + In ``loop`` mode, ingress traffic is simply transmitted back on the same interface. + +* ``--forward-mode=mode`` - Set forwarding mode. (N: io|mac|mac_retry|mac_swap|flowgen|rxonly|txonly|csum|icmpecho) + Set the forwarding mode where ``mode`` is one of the following:: -* --rss-ip + io (the default) + mac + macswap + flowgen + rxonly + txonly + csum + icmpecho + ieee1588 + tm + noisy + 5tswap + +* ``--rss-ip`` Set RSS functions for IPv4/IPv6 only. -* --rss-udp +* ``--rss-udp`` Set RSS functions for IPv4/IPv6 and UDP. -* --rxq=N +* ``--rxq=N`` Set the number of RX queues per port to N, where 1 <= N <= 65535. The default value is 1. -* --rxd=N +* ``--rxd=N`` Set the number of descriptors in the RX rings to N, where N > 0. The default value is 128. -* --txq=N +* ``--txq=N`` Set the number of TX queues per port to N, where 1 <= N <= 65535. The default value is 1. -* --txd=N +* ``--txd=N`` Set the number of descriptors in the TX rings to N, where N > 0. The default value is 512. -* --burst=N +* ``--hairpinq=N`` + + Set the number of hairpin queues per port to N, where 1 <= N <= 65535. + The default value is 0. The number of hairpin queues are added to the + number of TX queues and to the number of RX queues. then the first + RX hairpin is binded to the first TX hairpin, the second RX hairpin is + binded to the second TX hairpin and so on. The index of the first + RX hairpin queue is the number of RX queues as configured using --rxq. + The index of the first TX hairpin queue is the number of TX queues + as configured using --txq. + +* ``--burst=N`` Set the number of packets per burst to N, where 1 <= N <= 512. - The default value is 16. + The default value is 32. + If set to 0, driver default is used if defined. Else, if driver + default is not defined, default of 32 is used. -* --mbcache=N +* ``--mbcache=N`` Set the cache of mbuf memory pools to N, where 0 <= N <= 512. The default value is 16. -* --rxpt=N +* ``--rxpt=N`` Set the prefetch threshold register of RX rings to N, where N >= 0. The default value is 8. -* --rxht=N +* ``--rxht=N`` Set the host threshold register of RX rings to N, where N >= 0. The default value is 8. -* --rxfreet=N +* ``--rxfreet=N`` Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd. The default value is 0. -* --rxwt=N +* ``--rxwt=N`` Set the write-back threshold register of RX rings to N, where N >= 0. The default value is 4. -* --txpt=N +* ``--txpt=N`` Set the prefetch threshold register of TX rings to N, where N >= 0. The default value is 36. -* --txht=N +* ``--txht=N`` Set the host threshold register of TX rings to N, where N >= 0. The default value is 0. -* --txwt=N +* ``--txwt=N`` Set the write-back threshold register of TX rings to N, where N >= 0. The default value is 0. -* --txfreet=N - - Set the transmit free threshold of TX rings to N, where 0 <= N <= value of --txd. - The default value is 0. - -* --txrst=N +* ``--txfreet=N`` - Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of --txd. + Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``. The default value is 0. -* --txqflags=0xXXXXXXXX +* ``--txrst=N`` - Set the hexadecimal bitmask of TX queue flags, where 0 <= N <= 0x7FFFFFFF. + Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``. The default value is 0. -* --rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)] +* ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]`` Set the RX queues statistics counters mapping 0 <= mapping <= 15. -* --tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)] +* ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]`` Set the TX queues statistics counters mapping 0 <= mapping <= 15. -* --no-flush-rx +* ``--no-flush-rx`` + + Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD. + +* ``--txpkts=X[,Y]`` - Don't flush the RX streams before starting forwarding. Used mainly with PCAP drivers. + Set TX segment sizes or total packet length. Valid for ``tx-only`` + and ``flowgen`` forwarding modes. -* --txpkts=X[,Y] +* ``--txonly-multi-flow`` - Set TX segment sizes. + Generate multiple flows in txonly mode. -* --disable-link-check +* ``--disable-link-check`` Disable check on link status when starting/stopping ports. + +* ``--disable-device-start`` + + Do not automatically start all ports. This allows testing + configuration of rx and tx queues before device is started + for the first time. + +* ``--no-lsc-interrupt`` + + Disable LSC interrupts for all ports, even those supporting it. + +* ``--no-rmv-interrupt`` + + Disable RMV interrupts for all ports, even those supporting it. + +* ``--bitrate-stats=N`` + + Set the logical core N to perform bitrate calculation. + +* ``--print-event `` + + Enable printing the occurrence of the designated event. Using all will + enable all of them. + +* ``--mask-event `` + + Disable printing the occurrence of the designated event. Using all will + disable all of them. + +* ``--flow-isolate-all`` + + Providing this parameter requests flow API isolated mode on all ports at + initialization time. It ensures all traffic is received through the + configured flow rules only (see flow command). + + Ports that do not support this mode are automatically discarded. + +* ``--tx-offloads=0xXXXXXXXX`` + + Set the hexadecimal bitmask of TX queue offloads. + The default value is 0. + +* ``--rx-offloads=0xXXXXXXXX`` + + Set the hexadecimal bitmask of RX queue offloads. + The default value is 0. + +* ``--hot-plug`` + + Enable device event monitor mechanism for hotplug. + +* ``--vxlan-gpe-port=N`` + + Set the UDP port number of tunnel VXLAN-GPE to N. + The default value is 4790. + +* ``--geneve-parsed-port=N`` + + Set the UDP port number that is used for parsing the GENEVE protocol to N. + HW may be configured with another tunnel Geneve port. + The default value is 6081. + +* ``--mlockall`` + + Enable locking all memory. + +* ``--no-mlockall`` + + Disable locking all memory. + +* ``--mp-alloc `` + + Select mempool allocation mode: + + * native: create and populate mempool using native DPDK memory + * anon: create mempool using native DPDK memory, but populate using + anonymous memory + * xmem: create and populate mempool using externally and anonymously + allocated area + * xmemhuge: create and populate mempool using externally and anonymously + allocated hugepage area + +* ``--noisy-tx-sw-buffer-size`` + + Set the number of maximum elements of the FIFO queue to be created + for buffering packets. Only available with the noisy forwarding mode. + The default value is 0. + +* ``--noisy-tx-sw-buffer-flushtime=N`` + + Set the time before packets in the FIFO queue is flushed. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-memory=N`` + + Set the size of the noisy neighbor simulation memory buffer in MB to N. + Only available with the noisy forwarding mode. The default value is 0. + + +* ``--noisy-lkup-num-reads=N`` + + Set the number of reads to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-num-writes=N`` + + Set the number of writes to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--noisy-lkup-num-reads-writes=N`` + + Set the number of r/w accesses to be done in noisy neighbor simulation memory buffer to N. + Only available with the noisy forwarding mode. The default value is 0. + +* ``--no-iova-contig`` + + Enable to create mempool which is not IOVA contiguous. Valid only with --mp-alloc=anon. + The default value is 0. + +* ``--rx-mq-mode`` + + Set the hexadecimal bitmask of RX multi queue mode which can be enabled. + The default value is 0x7:: + + ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_DCB_FLAG | ETH_MQ_RX_VMDQ_FLAG + +* ``--record-core-cycles`` + + Enable measurement of CPU cycles per packet. + +* ``--record-burst-stats`` + + Enable display of RX and TX burst stats. + +* ``--hairpin-mode=0xXX`` + + Set the hairpin port mode with bitmask, only valid when hairpin queues number is set. + bit 4 - explicit Tx flow rule + bit 1 - two hairpin ports paired + bit 0 - two hairpin ports loop + The default value is 0. Hairpin will use single port mode and implicit Tx flow mode.