1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
4 Running the Application
5 =======================
7 EAL Command-line Options
8 ------------------------
10 Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
11 or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
12 a list of available EAL command-line options.
15 Testpmd Command-line Options
16 ----------------------------
18 The following are the command-line options for the testpmd applications.
19 They must be separated from the EAL options, shown in the previous section, with a ``--`` separator:
21 .. code-block:: console
23 sudo ./dpdk-testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2
25 The command line options are:
27 * ``-i, --interactive``
29 Run testpmd in interactive mode.
30 In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding,
31 configure the application and display stats on the current packet processing session.
32 See :ref:`testpmd_runtime` for more details.
34 In non-interactive mode,
35 the application starts with the configuration specified on the command-line and
36 immediately enters forwarding mode.
40 Display a help message and quit.
42 * ``-a, --auto-start``
44 Start forwarding on initialization.
48 Start forwarding, after sending a burst of packets first.
52 This flag should be only used in non-interactive mode.
54 * ``--stats-period PERIOD``
56 Display statistics every PERIOD seconds, if interactive mode is disabled.
57 The default value is 0, which means that the statistics will not be displayed.
59 * ``--display-xstats xstat_name1[,...]``
61 Display comma-separated list of extended statistics every PERIOD seconds
62 as specified in ``--stats-period`` or when used with interactive commands
63 that show Rx/Tx statistics (i.e. 'show port stats').
67 Set the number of forwarding cores,
68 where 1 <= N <= "number of cores" or ``RTE_MAX_LCORE`` from the configuration file.
69 The default value is 1.
73 Set the number of forwarding ports,
74 where 1 <= N <= "number of ports" on the board or ``RTE_MAX_ETHPORTS`` from the configuration file.
75 The default value is the number of ports on the board.
79 Set the hexadecimal bitmask of the cores running the packet forwarding test.
80 The main lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
84 Set the hexadecimal bitmask of the ports used by the packet forwarding test.
88 Set the forwarding ports based on the user input used by the packet forwarding test.
89 '-' denotes a range of ports to set including the two specified port IDs
90 ',' separates multiple port values.
91 Possible examples like --portlist=0,1 or --portlist=0-2 or --portlist=0,1-2 etc
95 Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers
96 (mbufs). [Default setting]
100 Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).
102 * ``--port-numa-config=(port,socket)[,(port,socket)]``
104 Specify the socket on which the memory pool to be used by the port will be allocated.
106 * ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]``
108 Specify the socket on which the TX/RX rings for the port will be allocated.
109 Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.
113 Set the socket from which all memory is allocated in NUMA mode,
114 where 0 <= N < number of sockets on the board.
116 * ``--mbuf-size=N[,N1[,...Nn]``
118 Set the data size of the mbufs used to N bytes, where N < 65536.
119 The default value is 2048. If multiple mbuf-size values are specified the
120 extra memory pools will be created for allocating mbufs to receive packets
121 with buffer splitting features.
123 * ``--total-num-mbufs=N``
125 Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.
127 * ``--max-pkt-len=N``
129 Set the maximum packet size to N bytes, where N >= 64. The default value is 1518.
131 * ``--max-lro-pkt-size=N``
133 Set the maximum LRO aggregated packet size to N bytes, where N >= 64.
135 * ``--eth-peers-configfile=name``
137 Use a configuration file containing the Ethernet addresses of the peer ports.
138 The configuration file should contain the Ethernet addresses on separate lines::
144 * ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
146 Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N,
147 where 0 <= N < ``RTE_MAX_ETHPORTS``.
149 * ``--tx-ip=SRC,DST``
151 Set the source and destination IP address used when doing transmit only test.
152 The defaults address values are source 198.18.0.1 and
153 destination 198.18.0.2. These are special purpose addresses
154 reserved for benchmarking (RFC 5735).
156 * ``--tx-udp=SRC[,DST]``
158 Set the source and destination UDP port number for transmit test only test.
159 The default port is the port 9 which is defined for the discard protocol
162 * ``--pkt-filter-mode=mode``
164 Set Flow Director mode where mode is either ``none`` (the default), ``signature`` or ``perfect``.
165 See :ref:`testpmd_flow_director` for more details.
167 * ``--pkt-filter-report-hash=mode``
169 Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``.
171 * ``--pkt-filter-size=N``
173 Set Flow Director allocated memory size, where N is 64K, 128K or 256K.
174 Sizes are in kilobytes. The default is 64.
176 * ``--pkt-filter-flexbytes-offset=N``
178 Set the flexbytes offset.
179 The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address,
180 where N is 0 <= N <= 32.
181 The default value is 0x6.
183 * ``--pkt-filter-drop-queue=N``
186 In perfect filter mode, when a rule is added with queue = -1, the packet will be enqueued into the RX drop-queue.
187 If the drop-queue does not exist, the packet is dropped. The default value is N=127.
189 * ``--disable-crc-strip``
191 Disable hardware CRC stripping.
195 Enable large receive offload.
197 * ``--enable-rx-cksum``
199 Enable hardware RX checksum offload.
201 * ``--enable-scatter``
203 Enable scatter (multi-segment) RX.
205 * ``--enable-hw-vlan``
207 Enable hardware VLAN.
209 * ``--enable-hw-vlan-filter``
211 Enable hardware VLAN filter.
213 * ``--enable-hw-vlan-strip``
215 Enable hardware VLAN strip.
217 * ``--enable-hw-vlan-extend``
219 Enable hardware VLAN extend.
221 * ``--enable-hw-qinq-strip``
223 Enable hardware QINQ strip.
225 * ``--enable-drop-en``
227 Enable per-queue packet drop for packets with no descriptors.
231 Disable RSS (Receive Side Scaling).
233 * ``--port-topology=mode``
235 Set port topology, where mode is ``paired`` (the default), ``chained`` or ``loop``.
237 In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5).
239 In ``chained`` mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0).
241 The ordering of the ports can be changed using the portlist testpmd runtime function.
243 In ``loop`` mode, ingress traffic is simply transmitted back on the same interface.
245 * ``--forward-mode=mode``
247 Set the forwarding mode where ``mode`` is one of the following::
264 Set RSS functions for IPv4/IPv6 only.
268 Set RSS functions for IPv4/IPv6 and UDP.
272 Set the number of RX queues per port to N, where 1 <= N <= 65535.
273 The default value is 1.
277 Set the number of descriptors in the RX rings to N, where N > 0.
278 The default value is 128.
282 Set the number of TX queues per port to N, where 1 <= N <= 65535.
283 The default value is 1.
287 Set the number of descriptors in the TX rings to N, where N > 0.
288 The default value is 512.
292 Set the number of hairpin queues per port to N, where 1 <= N <= 65535.
293 The default value is 0. The number of hairpin queues are added to the
294 number of TX queues and to the number of RX queues. then the first
295 RX hairpin is binded to the first TX hairpin, the second RX hairpin is
296 binded to the second TX hairpin and so on. The index of the first
297 RX hairpin queue is the number of RX queues as configured using --rxq.
298 The index of the first TX hairpin queue is the number of TX queues
299 as configured using --txq.
303 Set the number of packets per burst to N, where 1 <= N <= 512.
304 The default value is 32.
305 If set to 0, driver default is used if defined. Else, if driver
306 default is not defined, default of 32 is used.
308 * ``--flowgen-clones=N``
310 Set the number of each packet clones to be sent in `flowgen` mode.
311 Sending clones reduces host CPU load on creating packets and may help
312 in testing extreme speeds or maxing out Tx packet performance.
313 N should be not zero, but less than 'burst' parameter.
315 * ``--flowgen-flows=N``
317 Set the number of flows to be generated in `flowgen` mode, where
322 Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
323 The default value is 16.
327 Set the prefetch threshold register of RX rings to N, where N >= 0.
328 The default value is 8.
332 Set the host threshold register of RX rings to N, where N >= 0.
333 The default value is 8.
337 Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
338 The default value is 0.
342 Set the write-back threshold register of RX rings to N, where N >= 0.
343 The default value is 4.
347 Set the prefetch threshold register of TX rings to N, where N >= 0.
348 The default value is 36.
352 Set the host threshold register of TX rings to N, where N >= 0.
353 The default value is 0.
357 Set the write-back threshold register of TX rings to N, where N >= 0.
358 The default value is 0.
362 Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
363 The default value is 0.
367 Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
368 The default value is 0.
372 Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
376 Set the offsets of packet segments on receiving if split
377 feature is engaged. Affects only the queues configured
378 with split offloads (currently BUFFER_SPLIT is supported only).
382 Set the length of segments to scatter packets on receiving if split
383 feature is engaged. Affects only the queues configured
384 with split offloads (currently BUFFER_SPLIT is supported only).
385 Optionally the multiple memory pools can be specified with --mbuf-size
386 command line parameter and the mbufs to receive will be allocated
387 sequentially from these extra memory pools.
391 Set TX segment sizes or total packet length. Valid for ``tx-only``
392 and ``flowgen`` forwarding modes.
394 * ``--txonly-multi-flow``
396 Generate multiple flows in txonly mode.
398 * ``--eth-link-speed``
400 Set a forced link speed to the ethernet port::
402 10 - 10Mbps (not supported)
403 100 - 100Mbps (not supported)
413 * ``--disable-link-check``
415 Disable check on link status when starting/stopping ports.
417 * ``--disable-device-start``
419 Do not automatically start all ports. This allows testing
420 configuration of rx and tx queues before device is started
423 * ``--no-lsc-interrupt``
425 Disable LSC interrupts for all ports, even those supporting it.
427 * ``--no-rmv-interrupt``
429 Disable RMV interrupts for all ports, even those supporting it.
431 * ``--bitrate-stats=N``
433 Set the logical core N to perform bitrate calculation.
435 * ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|flow_aged|all>``
437 Enable printing the occurrence of the designated event. Using all will
440 * ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|flow_aged|all>``
442 Disable printing the occurrence of the designated event. Using all will
445 * ``--flow-isolate-all``
447 Providing this parameter requests flow API isolated mode on all ports at
448 initialization time. It ensures all traffic is received through the
449 configured flow rules only (see flow command).
451 Ports that do not support this mode are automatically discarded.
453 * ``--tx-offloads=0xXXXXXXXX``
455 Set the hexadecimal bitmask of TX queue offloads.
456 The default value is 0.
458 * ``--rx-offloads=0xXXXXXXXX``
460 Set the hexadecimal bitmask of RX queue offloads.
461 The default value is 0.
465 Enable device event monitor mechanism for hotplug.
467 * ``--vxlan-gpe-port=N``
469 Set the UDP port number of tunnel VXLAN-GPE to N.
470 The default value is 4790.
472 * ``--geneve-parsed-port=N``
474 Set the UDP port number that is used for parsing the GENEVE protocol to N.
475 HW may be configured with another tunnel Geneve port.
476 The default value is 6081.
480 Enable locking all memory.
484 Disable locking all memory.
486 * ``--mp-alloc <native|anon|xmem|xmemhuge>``
488 Select mempool allocation mode:
490 * native: create and populate mempool using native DPDK memory
491 * anon: create mempool using native DPDK memory, but populate using
493 * xmem: create and populate mempool using externally and anonymously
495 * xmemhuge: create and populate mempool using externally and anonymously
496 allocated hugepage area
498 * ``--noisy-tx-sw-buffer-size``
500 Set the number of maximum elements of the FIFO queue to be created
501 for buffering packets. Only available with the noisy forwarding mode.
502 The default value is 0.
504 * ``--noisy-tx-sw-buffer-flushtime=N``
506 Set the time before packets in the FIFO queue is flushed.
507 Only available with the noisy forwarding mode. The default value is 0.
509 * ``--noisy-lkup-memory=N``
511 Set the size of the noisy neighbor simulation memory buffer in MB to N.
512 Only available with the noisy forwarding mode. The default value is 0.
515 * ``--noisy-lkup-num-reads=N``
517 Set the number of reads to be done in noisy neighbor simulation memory buffer to N.
518 Only available with the noisy forwarding mode. The default value is 0.
520 * ``--noisy-lkup-num-writes=N``
522 Set the number of writes to be done in noisy neighbor simulation memory buffer to N.
523 Only available with the noisy forwarding mode. The default value is 0.
525 * ``--noisy-lkup-num-reads-writes=N``
527 Set the number of r/w accesses to be done in noisy neighbor simulation memory buffer to N.
528 Only available with the noisy forwarding mode. The default value is 0.
530 * ``--no-iova-contig``
532 Enable to create mempool which is not IOVA contiguous. Valid only with --mp-alloc=anon.
533 The default value is 0.
537 Set the hexadecimal bitmask of RX multi queue mode which can be enabled.
538 The default value is 0x7::
540 ETH_MQ_RX_RSS_FLAG | ETH_MQ_RX_DCB_FLAG | ETH_MQ_RX_VMDQ_FLAG
542 * ``--record-core-cycles``
544 Enable measurement of CPU cycles per packet.
546 * ``--record-burst-stats``
548 Enable display of RX and TX burst stats.
550 * ``--hairpin-mode=0xXX``
552 Set the hairpin port mode with bitmask, only valid when hairpin queues number is set::
554 bit 4 - explicit Tx flow rule
555 bit 1 - two hairpin ports paired
556 bit 0 - two hairpin ports loop
558 The default value is 0. Hairpin will use single port mode and implicit Tx flow mode.
561 Testpmd Multi-Process Command-line Options
562 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
564 The following are the command-line options for testpmd multi-process support:
568 .. code-block:: console
570 sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 0-1 -- -i --rxq=4 --txq=4 \
571 --num-procs=2 --proc-id=0
575 .. code-block:: console
577 sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 2-3 -- -i --rxq=4 --txq=4 \
578 --num-procs=2 --proc-id=1
580 The command line options are:
584 The number of processes which will be used.
588 The ID of the current process (ID < num-procs). ID should be different in
589 primary process and secondary process, which starts from '0'.
591 Calculation rule for queue:
592 All queues are allocated to different processes based on ``proc_num`` and
594 Calculation rule for the testpmd to allocate queues to each process:
595 * start(queue start id) = proc_id * nb_q / num_procs;
597 * end(queue end id) = start + nb_q / num_procs;
599 For example, if testpmd is configured to have 4 Tx and Rx queues,
600 queues 0 and 1 will be used by the primary process and
601 queues 2 and 3 will be used by the secondary process.
603 The number of queues should be a multiple of the number of processes. If not,
604 redundant queues will exist after queues are allocated to processes. If RSS
605 is enabled, packet loss occurs when traffic is sent to all processes at the same
606 time. Some traffic goes to redundant queues and cannot be forwarded.
608 All the dev ops is supported in primary process. While secondary process is
609 not permitted to allocate or release shared memory, so some ops are not supported
617 - ``rx_queue_release``
618 - ``tx_queue_release``
620 So, any command from testpmd which calls those APIs will not be supported in
621 secondary process, like:
623 .. code-block:: console
625 port config all rxq|txq|rxd|txd <value>
626 port config <port_id> rx_offload xxx on/off
627 port config <port_id> tx_offload xxx on/off
631 When secondary is running, port in primary is not permitted to be stopped.
632 Reconfigure operation is only valid in primary.
634 Stats is supported, stats will not change when one quits and starts, as they
635 share the same buffer to store the stats. Flow rules are maintained in process
636 level: primary and secondary has its own flow list (but one flow list in HW).
637 The two can see all the queues, so setting the flow rules for the other is OK.
638 But in the testpmd primary process receiving or transmitting packets from the
639 queue allocated for secondary process is not permitted, and same for secondary
642 Flow API and RSS are supported.