1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Running the Application 5======================= 6 7EAL Command-line Options 8------------------------ 9 10Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>` 11or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for 12a list of available EAL command-line options. 13 14 15Testpmd Command-line Options 16---------------------------- 17 18The following are the command-line options for the testpmd applications. 19They must be separated from the EAL options, shown in the previous section, with a ``--`` separator: 20 21.. code-block:: console 22 23 sudo ./dpdk-testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2 24 25The command line options are: 26 27* ``-i, --interactive`` 28 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. 33 34 In non-interactive mode, 35 the application starts with the configuration specified on the command-line and 36 immediately enters forwarding mode. 37 38* ``-h, --help`` 39 40 Display a help message and quit. 41 42* ``-a, --auto-start`` 43 44 Start forwarding on initialization. 45 46* ``--tx-first`` 47 48 Start forwarding, after sending a burst of packets first. 49 50.. Note:: 51 52 This flag should be only used in non-interactive mode. 53 54* ``--stats-period PERIOD`` 55 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. 58 59* ``--display-xstats xstat_name1[,...]`` 60 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'). 64 65* ``--nb-cores=N`` 66 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. 70 71* ``--nb-ports=N`` 72 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. 76 77* ``--coremask=0xXX`` 78 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. 81 82* ``--portmask=0xXX`` 83 84 Set the hexadecimal bitmask of the ports used by the packet forwarding test. 85 86* ``--portlist=X`` 87 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 92 93* ``--numa`` 94 95 Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers 96 (mbufs). [Default setting] 97 98* ``--no-numa`` 99 100 Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs). 101 102* ``--port-numa-config=(port,socket)[,(port,socket)]`` 103 104 Specify the socket on which the memory pool to be used by the port will be allocated. 105 106* ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]`` 107 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. 110 111* ``--socket-num=N`` 112 113 Set the socket from which all memory is allocated in NUMA mode, 114 where 0 <= N < number of sockets on the board. 115 116* ``--mbuf-size=N[,N1[,...Nn]`` 117 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. 122 123* ``--total-num-mbufs=N`` 124 125 Set the number of mbufs to be allocated in the mbuf pools, where N > 1024. 126 127* ``--max-pkt-len=N`` 128 129 Set the maximum packet size to N bytes, where N >= 64. The default value is 1518. 130 131* ``--max-lro-pkt-size=N`` 132 133 Set the maximum LRO aggregated packet size to N bytes, where N >= 64. 134 135* ``--eth-peers-configfile=name`` 136 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:: 139 140 XX:XX:XX:XX:XX:01 141 XX:XX:XX:XX:XX:02 142 ... 143 144* ``--eth-peer=N,XX:XX:XX:XX:XX:XX`` 145 146 Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N, 147 where 0 <= N < ``RTE_MAX_ETHPORTS``. 148 149* ``--tx-ip=SRC,DST`` 150 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). 155 156* ``--tx-udp=SRC[,DST]`` 157 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 160 (RFC 863). 161 162* ``--disable-crc-strip`` 163 164 Disable hardware CRC stripping. 165 166* ``--enable-lro`` 167 168 Enable large receive offload. 169 170* ``--enable-rx-cksum`` 171 172 Enable hardware RX checksum offload. 173 174* ``--enable-scatter`` 175 176 Enable scatter (multi-segment) RX. 177 178* ``--enable-hw-vlan`` 179 180 Enable hardware VLAN. 181 182* ``--enable-hw-vlan-filter`` 183 184 Enable hardware VLAN filter. 185 186* ``--enable-hw-vlan-strip`` 187 188 Enable hardware VLAN strip. 189 190* ``--enable-hw-vlan-extend`` 191 192 Enable hardware VLAN extend. 193 194* ``--enable-hw-qinq-strip`` 195 196 Enable hardware QINQ strip. 197 198* ``--enable-drop-en`` 199 200 Enable per-queue packet drop for packets with no descriptors. 201 202* ``--disable-rss`` 203 204 Disable RSS (Receive Side Scaling). 205 206* ``--port-topology=mode`` 207 208 Set port topology, where mode is ``paired`` (the default), ``chained`` or ``loop``. 209 210 In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5). 211 212 In ``chained`` mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0). 213 214 The ordering of the ports can be changed using the portlist testpmd runtime function. 215 216 In ``loop`` mode, ingress traffic is simply transmitted back on the same interface. 217 218* ``--forward-mode=mode`` 219 220 Set the forwarding mode where ``mode`` is one of the following:: 221 222 io (the default) 223 mac 224 macswap 225 flowgen 226 rxonly 227 txonly 228 csum 229 icmpecho 230 ieee1588 231 tm 232 noisy 233 5tswap 234 shared-rxq 235 recycle_mbufs 236 237* ``--rss-ip`` 238 239 Set RSS functions for IPv4/IPv6 only. 240 241* ``--rss-udp`` 242 243 Set RSS functions for IPv4/IPv6 and UDP. 244 245* ``--rxq=N`` 246 247 Set the number of RX queues per port to N, where 1 <= N <= 65535. 248 The default value is 1. 249 250* ``--rxd=N`` 251 252 Set the number of descriptors in the RX rings to N, where N > 0. 253 The default value is 128. 254 255* ``--txq=N`` 256 257 Set the number of TX queues per port to N, where 1 <= N <= 65535. 258 The default value is 1. 259 260* ``--txd=N`` 261 262 Set the number of descriptors in the TX rings to N, where N > 0. 263 The default value is 512. 264 265* ``--hairpinq=N`` 266 267 Set the number of hairpin queues per port to N, where 1 <= N <= 65535. 268 The default value is 0. The number of hairpin queues are added to the 269 number of TX queues and to the number of RX queues. then the first 270 RX hairpin is binded to the first TX hairpin, the second RX hairpin is 271 binded to the second TX hairpin and so on. The index of the first 272 RX hairpin queue is the number of RX queues as configured using --rxq. 273 The index of the first TX hairpin queue is the number of TX queues 274 as configured using --txq. 275 276* ``--burst=N`` 277 278 Set the number of packets per burst to N, where 1 <= N <= 512. 279 The default value is 32. 280 If set to 0, driver default is used if defined. Else, if driver 281 default is not defined, default of 32 is used. 282 283* ``--flowgen-clones=N`` 284 285 Set the number of each packet clones to be sent in `flowgen` mode. 286 Sending clones reduces host CPU load on creating packets and may help 287 in testing extreme speeds or maxing out Tx packet performance. 288 N should be not zero, but less than 'burst' parameter. 289 290* ``--flowgen-flows=N`` 291 292 Set the number of flows to be generated in `flowgen` mode, where 293 1 <= N <= INT32_MAX. 294 295* ``--mbcache=N`` 296 297 Set the cache of mbuf memory pools to N, where 0 <= N <= 512. 298 The default value is 16. 299 300* ``--rxpt=N`` 301 302 Set the prefetch threshold register of RX rings to N, where N >= 0. 303 The default value is 8. 304 305* ``--rxht=N`` 306 307 Set the host threshold register of RX rings to N, where N >= 0. 308 The default value is 8. 309 310* ``--rxfreet=N`` 311 312 Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd. 313 The default value is 0. 314 315* ``--rxwt=N`` 316 317 Set the write-back threshold register of RX rings to N, where N >= 0. 318 The default value is 4. 319 320* ``--txpt=N`` 321 322 Set the prefetch threshold register of TX rings to N, where N >= 0. 323 The default value is 36. 324 325* ``--txht=N`` 326 327 Set the host threshold register of TX rings to N, where N >= 0. 328 The default value is 0. 329 330* ``--txwt=N`` 331 332 Set the write-back threshold register of TX rings to N, where N >= 0. 333 The default value is 0. 334 335* ``--txfreet=N`` 336 337 Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``. 338 The default value is 0. 339 340* ``--txrst=N`` 341 342 Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``. 343 The default value is 0. 344 345* ``--no-flush-rx`` 346 347 Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD. 348 349* ``--rxoffs=X[,Y]`` 350 351 Set the offsets of packet segments on receiving if split 352 feature is engaged. Affects only the queues configured 353 with split offloads (currently BUFFER_SPLIT is supported only). 354 355* ``--rxpkts=X[,Y]`` 356 357 Set the length of segments to scatter packets on receiving if split 358 feature is engaged. Affects only the queues configured 359 with split offloads (currently BUFFER_SPLIT is supported only). 360 Optionally the multiple memory pools can be specified with --mbuf-size 361 command line parameter and the mbufs to receive will be allocated 362 sequentially from these extra memory pools. 363 364* ``--txpkts=X[,Y]`` 365 366 Set TX segment sizes or total packet length. Valid for ``tx-only`` 367 and ``flowgen`` forwarding modes. 368 369* ``--multi-rx-mempool`` 370 371 Enable multiple mbuf pools per Rx queue. 372 373* ``--txonly-multi-flow`` 374 375 Generate multiple flows in txonly mode. 376 377* ``--rxq-share=[X]`` 378 379 Create queues in shared Rx queue mode if device supports. 380 Shared Rx queues are grouped per X ports. X defaults to UINT32_MAX, 381 implies all ports join share group 1. Forwarding engine "shared-rxq" 382 should be used for shared Rx queues. This engine does Rx only and 383 update stream statistics accordingly. 384 385* ``--eth-link-speed`` 386 387 Set a forced link speed to the ethernet port:: 388 389 10 - 10Mbps (not supported) 390 100 - 100Mbps (not supported) 391 1000 - 1Gbps 392 2500 - 2.5Gbps 393 5000 - 5Gbps 394 10000 - 10Gbps 395 25000 - 25Gbps 396 40000 - 40Gbps 397 50000 - 50Gbps 398 100000 - 100Gbps 399 200000 - 200Gbps 400 400000 - 400Gbps 401 ... 402 403* ``--disable-link-check`` 404 405 Disable check on link status when starting/stopping ports. 406 407* ``--disable-device-start`` 408 409 Do not automatically start all ports. This allows testing 410 configuration of rx and tx queues before device is started 411 for the first time. 412 413* ``--no-lsc-interrupt`` 414 415 Disable LSC interrupts for all ports, even those supporting it. 416 417* ``--no-rmv-interrupt`` 418 419 Disable RMV interrupts for all ports, even those supporting it. 420 421* ``--bitrate-stats=N`` 422 423 Set the logical core N to perform bitrate calculation. 424 425* ``--latencystats=N`` 426 427 Set the logical core N to perform latency and jitter calculations. 428 429* ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|flow_aged|err_recovering|recovery_success|recovery_failed|all>`` 430 431 Enable printing the occurrence of the designated event. Using all will 432 enable all of them. 433 434* ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|flow_aged|err_recovering|recovery_success|recovery_failed|all>`` 435 436 Disable printing the occurrence of the designated event. Using all will 437 disable all of them. 438 439* ``--flow-isolate-all`` 440 441 Providing this parameter requests flow API isolated mode on all ports at 442 initialization time. It ensures all traffic is received through the 443 configured flow rules only (see flow command). 444 445 Ports that do not support this mode are automatically discarded. 446 447* ``--disable-flow-flush`` 448 449 Disable port flow flush when stopping port. 450 This allows testing keep flow rules or shared flow objects across restart. 451 452* ``--tx-offloads=0xXXXXXXXX`` 453 454 Set the hexadecimal bitmask of TX queue offloads. 455 The default value is 0. 456 457* ``--rx-offloads=0xXXXXXXXX`` 458 459 Set the hexadecimal bitmask of RX queue offloads. 460 The default value is 0. 461 462* ``--hot-plug`` 463 464 Enable device event monitor mechanism for hotplug. 465 466* ``--vxlan-gpe-port=N`` 467 468 Set the UDP port number of tunnel VXLAN-GPE to N. 469 The default value is 4790. 470 471* ``--geneve-parsed-port=N`` 472 473 Set the UDP port number that is used for parsing the GENEVE protocol to N. 474 HW may be configured with another tunnel Geneve port. 475 The default value is 6081. 476 477* ``--mlockall`` 478 479 Enable locking all memory. 480 481* ``--no-mlockall`` 482 483 Disable locking all memory. 484 485* ``--mp-alloc <native|anon|xmem|xmemhuge>`` 486 487 Select mempool allocation mode: 488 489 * native: create and populate mempool using native DPDK memory 490 * anon: create mempool using native DPDK memory, but populate using 491 anonymous memory 492 * xmem: create and populate mempool using externally and anonymously 493 allocated area 494 * xmemhuge: create and populate mempool using externally and anonymously 495 allocated hugepage area 496 497* ``--noisy-forward-mode=mode`` 498 499 Set the noisy vnf forwarding mode where ``mode`` is one of the following:: 500 501 io (the default) 502 mac 503 macswap 504 5tswap 505 506* ``--noisy-tx-sw-buffer-size`` 507 508 Set the number of maximum elements of the FIFO queue to be created 509 for buffering packets. Only available with the noisy forwarding mode. 510 The default value is 0. 511 512* ``--noisy-tx-sw-buffer-flushtime=N`` 513 514 Set the time before packets in the FIFO queue is flushed. 515 Only available with the noisy forwarding mode. The default value is 0. 516 517* ``--noisy-lkup-memory=N`` 518 519 Set the size of the noisy neighbor simulation memory buffer in MB to N. 520 Only available with the noisy forwarding mode. The default value is 0. 521 522 523* ``--noisy-lkup-num-reads=N`` 524 525 Set the number of reads to be done in noisy neighbor simulation memory buffer to N. 526 Only available with the noisy forwarding mode. The default value is 0. 527 528* ``--noisy-lkup-num-writes=N`` 529 530 Set the number of writes to be done in noisy neighbor simulation memory buffer to N. 531 Only available with the noisy forwarding mode. The default value is 0. 532 533* ``--noisy-lkup-num-reads-writes=N`` 534 535 Set the number of r/w accesses to be done in noisy neighbor simulation memory buffer to N. 536 Only available with the noisy forwarding mode. The default value is 0. 537 538* ``--no-iova-contig`` 539 540 Enable to create mempool which is not IOVA contiguous. Valid only with --mp-alloc=anon. 541 The default value is 0. 542 543* ``--rx-mq-mode`` 544 545 Set the hexadecimal bitmask of RX multi queue mode which can be enabled. 546 The default value is 0x7:: 547 548 RTE_ETH_MQ_RX_RSS_FLAG | RTE_ETH_MQ_RX_DCB_FLAG | RTE_ETH_MQ_RX_VMDQ_FLAG 549 550* ``--record-core-cycles`` 551 552 Enable measurement of CPU cycles per packet. 553 554* ``--record-burst-stats`` 555 556 Enable display of RX and TX burst stats. 557 558* ``--hairpin-mode=0xXXXX`` 559 560 Set the hairpin port configuration with bitmask, only valid when hairpin queues number is set:: 561 562 bit 18 - hairpin TX queues will use RTE memory 563 bit 16 - hairpin TX queues will use locked device memory 564 bit 13 - hairpin RX queues will use RTE memory 565 bit 12 - hairpin RX queues will use locked device memory 566 bit 9 - force memory settings of hairpin TX queue 567 bit 8 - force memory settings of hairpin RX queue 568 bit 4 - explicit Tx flow rule 569 bit 1 - two hairpin ports paired 570 bit 0 - two hairpin ports loop 571 572 The default value is 0. Hairpin will use single port mode and implicit Tx flow mode. 573 574* ``--hairpin-map=Rx port id:Rx queue:Tx port id:Tx queue:queues number`` 575 576 Set explicit hairpin configuration. 577 578Testpmd Multi-Process Command-line Options 579~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 580 581The following are the command-line options for testpmd multi-process support: 582 583* primary process: 584 585.. code-block:: console 586 587 sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 0-1 -- -i --rxq=4 --txq=4 \ 588 --num-procs=2 --proc-id=0 589 590* secondary process: 591 592.. code-block:: console 593 594 sudo ./dpdk-testpmd -a xxx --proc-type=auto -l 2-3 -- -i --rxq=4 --txq=4 \ 595 --num-procs=2 --proc-id=1 596 597The command line options are: 598 599* ``--num-procs=N`` 600 601 The number of processes which will be used. 602 603* ``--proc-id=ID`` 604 605 The ID of the current process (ID < num-procs). ID should be different in 606 primary process and secondary process, which starts from '0'. 607 608Calculation rule for queue: 609All queues are allocated to different processes based on ``proc_num`` and 610``proc_id``. 611Calculation rule for the testpmd to allocate queues to each process: 612* start(queue start id) = proc_id * nb_q / num_procs； 613 614* end(queue end id) = start + nb_q / num_procs； 615 616For example, if testpmd is configured to have 4 Tx and Rx queues, 617queues 0 and 1 will be used by the primary process and 618queues 2 and 3 will be used by the secondary process. 619 620The number of queues should be a multiple of the number of processes. If not, 621redundant queues will exist after queues are allocated to processes. If RSS 622is enabled, packet loss occurs when traffic is sent to all processes at the same 623time. Some traffic goes to redundant queues and cannot be forwarded. 624 625All the dev ops is supported in primary process. While secondary process is 626not permitted to allocate or release shared memory, so some ops are not supported 627as follows: 628 629- ``dev_configure`` 630- ``dev_start`` 631- ``dev_stop`` 632- ``dev_reset`` 633- ``rx_queue_setup`` 634- ``tx_queue_setup`` 635- ``rx_queue_release`` 636- ``tx_queue_release`` 637 638So, any command from testpmd which calls those APIs will not be supported in 639secondary process, like: 640 641.. code-block:: console 642 643 port config all rxq|txq|rxd|txd <value> 644 port config <port_id> rx_offload xxx on/off 645 port config <port_id> tx_offload xxx on/off 646 647etc. 648 649When secondary is running, port in primary is not permitted to be stopped. 650Reconfigure operation is only valid in primary. 651 652Stats is supported, stats will not change when one quits and starts, as they 653share the same buffer to store the stats. Flow rules are maintained in process 654level: primary and secondary has its own flow list (but one flow list in HW). 655The two can see all the queues, so setting the flow rules for the other is OK. 656But in the testpmd primary process receiving or transmitting packets from the 657queue allocated for secondary process is not permitted, and same for secondary 658process. 659 660Flow API and RSS are supported. 661