-.. 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
=======================
EAL Command-line Options
------------------------
-The following are the EAL command-line options that can be used in conjunction with the testpmd,
-or any other DPDK application.
-See the DPDK Getting Started Guide for more information on these options.
-
-* -c COREMASK
-
- Set the hexadecimal bitmask of the cores to run on.
-
-* -l CORELIST
-
- List of cores to run on
-
- The argument format is <c1>[-c2][,c3[-c4],...]
- where c1, c2, etc are core indexes between 0 and 128
-
-* --lcores COREMAP
-
- Map lcore set to physical cpu set
-
- The argument format is
- '<lcores[@cpus]>[<,lcores[@cpus]>...]'
-
- 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
-
-* --master-lcore ID
-
- Core ID that is used as master
-
-* -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 "<driver><id>[,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
-* -i, --interactive
+The command line options are:
+
+* ``-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 initialization.
+
+* ``--tx-first``
+
+ Start forwarding, after sending a burst of packets first.
+
+.. Note::
+
+ This flag should be only used in non-interactive mode.
- Start forwarding on init.
+* ``--stats-period PERIOD``
-* --nb-cores=N
+ 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``
Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048.
-* --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
+ ...
- XX:XX:XX:XX:XX:01
+* ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
- XX:XX:XX:XX:XX:02
+ 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.
- ...
+* ``--tx-ip=SRC,DST``
-* --eth-peer=N,XX:XX:XX:XX:XX:XX
+ 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).
- 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.
+* ``--tx-udp=SRC[,DST]``
-* --pkt-filter-mode=mode
+ 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).
- 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.
+* ``--pkt-filter-mode=mode``
-* --pkt-filter-report-hash=mode
+ Set Flow Director mode where mode is either ``none`` (the default), ``signature`` or ``perfect``.
+ See :ref:`testpmd_flow_director` for more details.
- Set Flow Director hash match reporting mode where mode is none, match (the default) or always.
+* ``--pkt-filter-report-hash=mode``
-* --pkt-filter-size=N
+ Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``.
+
+* ``--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``
+
+ Disable hardware CRC stripping.
+
+* ``--enable-lro``
- Enable hardware CRC stripping.
+ Enable large receive offload.
-* --enable-rx-cksum
+* ``--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.
-* --disable-hw-vlan-filter
+* ``--enable-hw-vlan-filter``
- Disable hardware VLAN filter.
+ Enable hardware VLAN filter.
-* --disable-hw-vlan-strip
+* ``--enable-hw-vlan-strip``
- Disable hardware VLAN strip.
+ Enable hardware VLAN strip.
-* --disable-hw-vlan-extend
+* ``--enable-hw-vlan-extend``
- Disable hardware VLAN extend.
+ Enable hardware VLAN extend.
-* --enable-drop-en
+* ``--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
+
+* ``--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
+* ``--txfreet=N``
- Set the transmit free 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.
-* --txrst=N
+* ``--txrst=N``
- Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of --txd.
+ Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
The default value is 0.
-* --txqflags=0xXXXXXXXX
+* ``--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)]``
+
+ Set the TX queues statistics counters mapping 0 <= mapping <= 15.
+
+* ``--no-flush-rx``
+
+ Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
+
+* ``--txpkts=X[,Y]``
+
+ Set TX segment sizes or total packet length. Valid for ``tx-only``
+ and ``flowgen`` forwarding modes.
+
+* ``--txonly-multi-flow``
+
+ Generate multiple flows in txonly mode.
+
+* ``--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``
- Set the hexadecimal bitmask of TX queue flags, where 0 <= N <= 0x7FFFFFFF.
+ Disable RMV interrupts for all ports, even those supporting it.
+
+* ``--bitrate-stats=N``
+
+ Set the logical core N to perform bitrate calculation.
+
+* ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
+
+ Enable printing the occurrence of the designated event. Using all will
+ enable all of them.
+
+* ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
+
+ 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.
- Note::
+* ``--rx-offloads=0xXXXXXXXX``
- When using hardware offload functions such as vlan, checksum...,
- add txqflags=0, since depending on the PMD,
- txqflags might be set to a non-zero value.
+ Set the hexadecimal bitmask of RX queue offloads.
+ The default value is 0.
-* --rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]
+* ``--hot-plug``
- Set the RX queues statistics counters mapping 0 <= mapping <= 15.
+ Enable device event monitor mechanism for hotplug.
-* --tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]
+* ``--vxlan-gpe-port=N``
- Set the TX queues statistics counters mapping 0 <= mapping <= 15.
+ Set the UDP port number of tunnel VXLAN-GPE to N.
+ The default value is 4790.
-* --no-flush-rx
+* ``--mlockall``
- Don't flush the RX streams before starting forwarding. Used mainly with PCAP drivers.
+ Enable locking all memory.
-* --txpkts=X[,Y]
+* ``--no-mlockall``
- Set TX segment sizes.
+ Disable locking all memory.
-* --disable-link-check
+* ``--mp-alloc <native|anon|xmem|xmemhuge>``
- Disable check on link status when starting/stopping ports.
+ 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.