doc/guides/testpmd_app_ug/run_app.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 Running the Application
   5 =======================
   6
   7 EAL Command-line Options
   8 ------------------------
   9
  10 The following are the EAL command-line options that can be used in conjunction with the testpmd,
  11 or any other DPDK application.
  12 See the DPDK Getting Started Guides for more information on these options.
  13
  14 *   ``-c COREMASK``
  15
  16     Set the hexadecimal bitmask of the cores to run on.
  17
  18 *   ``-l CORELIST``
  19
  20     List of cores to run on
  21
  22     The argument format is ``<c1>[-c2][,c3[-c4],...]``
  23     where ``c1``, ``c2``, etc are core indexes between 0 and 128.
  24
  25 *   ``--lcores COREMAP``
  26
  27     Map lcore set to physical cpu set
  28
  29     The argument format is::
  30
  31        <lcores[@cpus]>[<,lcores[@cpus]>...]
  32
  33     Lcore and CPU lists are grouped by ``(`` and ``)`` Within the group.
  34     The ``-`` character is used as a range separator and ``,`` is used as a single number separator.
  35     The grouping ``()`` can be omitted for single element group.
  36     The ``@`` can be omitted if cpus and lcores have the same value.
  37
  38 .. Note::
  39     At a given instance only one core option ``--lcores``, ``-l`` or ``-c`` can be used.
  40
  41
  42 *   ``--master-lcore ID``
  43
  44     Core ID that is used as master.
  45
  46 *   ``-n NUM``
  47
  48     Set the number of memory channels to use.
  49
  50 *   ``-b, --pci-blacklist domain:bus:devid.func``
  51
  52     Blacklist a PCI device to prevent EAL from using it. Multiple -b options are allowed.
  53
  54 *   ``-d LIB.so``
  55
  56     Load an external driver. Multiple -d options are allowed.
  57
  58 *   ``-w, --pci-whitelist domain:bus:devid:func``
  59
  60     Add a PCI device in white list.
  61
  62 *   ``-m MB``
  63
  64     Memory to allocate. See also ``--socket-mem``.
  65
  66 *   ``-r NUM``
  67
  68     Set the number of memory ranks (auto-detected by default).
  69
  70 *   ``-v``
  71
  72     Display the version information on startup.
  73
  74 *   ``--syslog``
  75
  76     Set the syslog facility.
  77
  78 *   ``--socket-mem``
  79
  80     Set the memory to allocate on specific sockets (use comma separated values).
  81
  82 *   ``--huge-dir``
  83
  84     Specify the directory where the hugetlbfs is mounted.
  85
  86 *   ``mbuf-pool-ops-name``:
  87
  88     Pool ops name for mbuf to use.
  89
  90 *   ``--proc-type``
  91
  92     Set the type of the current process.
  93
  94 *   ``--file-prefix``
  95
  96     Prefix for hugepage filenames.
  97
  98 *   ``-vmware-tsc-map``
  99
 100     Use VMware TSC map instead of native RDTSC.
 101
 102 *   ``--vdev``
 103
 104     Add a virtual device using the format::
 105
 106        <driver><id>[,key=val, ...]
 107
 108     For example::
 109
 110        --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
 111
 112 *   ``--base-virtaddr``
 113
 114     Specify base virtual address.
 115
 116 *   ``--create-uio-dev``
 117
 118     Create ``/dev/uioX`` (usually done by hotplug).
 119
 120 *   ``--no-shconf``
 121
 122     No shared config (mmap-ed files).
 123
 124 *   ``--no-pci``
 125
 126     Disable pci.
 127
 128 *   ``--no-hpet``
 129
 130     Disable hpet.
 131
 132 *   ``--no-huge``
 133
 134     Use malloc instead of hugetlbfs.
 135
 136
 137 Testpmd Command-line Options
 138 ----------------------------
 139
 140 The following are the command-line options for the testpmd applications.
 141 They must be separated from the EAL options, shown in the previous section, with a ``--`` separator:
 142
 143 .. code-block:: console
 144
 145     sudo ./testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2
 146
 147 The commandline options are:
 148
 149 *   ``-i, --interactive``
 150
 151     Run testpmd in interactive mode.
 152     In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding,
 153     configure the application and display stats on the current packet processing session.
 154     See :ref:`testpmd_runtime` for more details.
 155
 156     In non-interactive mode,
 157     the application starts with the configuration specified on the command-line and
 158     immediately enters forwarding mode.
 159
 160 *   ``-h, --help``
 161
 162     Display a help message and quit.
 163
 164 *   ``-a, --auto-start``
 165
 166     Start forwarding on initialization.
 167
 168 *   ``--tx-first``
 169
 170     Start forwarding, after sending a burst of packets first.
 171
 172 .. Note::
 173
 174    This flag should be only used in non-interactive mode.
 175
 176 *   ``--stats-period PERIOD``
 177
 178     Display statistics every PERIOD seconds, if interactive mode is disabled.
 179     The default value is 0, which means that the statistics will not be displayed.
 180
 181 *   ``--nb-cores=N``
 182
 183     Set the number of forwarding cores,
 184     where 1 <= N <= "number of cores" or ``CONFIG_RTE_MAX_LCORE`` from the configuration file.
 185     The default value is 1.
 186
 187 *   ``--nb-ports=N``
 188
 189     Set the number of forwarding ports,
 190     where 1 <= N <= "number of ports" on the board or ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 191     The default value is the number of ports on the board.
 192
 193 *   ``--coremask=0xXX``
 194
 195     Set the hexadecimal bitmask of the cores running the packet forwarding test.
 196     The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
 197
 198 *   ``--portmask=0xXX``
 199
 200     Set the hexadecimal bitmask of the ports used by the packet forwarding test.
 201
 202 *   ``--numa``
 203
 204     Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers
 205     (mbufs). [Default setting]
 206
 207 *   ``--no-numa``
 208
 209     Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).
 210
 211 *   ``--port-numa-config=(port,socket)[,(port,socket)]``
 212
 213     Specify the socket on which the memory pool to be used by the port will be allocated.
 214
 215 *   ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]``
 216
 217     Specify the socket on which the TX/RX rings for the port will be allocated.
 218     Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.
 219
 220 *   ``--socket-num=N``
 221
 222     Set the socket from which all memory is allocated in NUMA mode,
 223     where 0 <= N < number of sockets on the board.
 224
 225 *   ``--mbuf-size=N``
 226
 227     Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048.
 228
 229 *   ``--total-num-mbufs=N``
 230
 231     Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.
 232
 233 *   ``--max-pkt-len=N``
 234
 235     Set the maximum packet size to N bytes, where N >= 64. The default value is 1518.
 236
 237 *   ``--eth-peers-configfile=name``
 238
 239     Use a configuration file containing the Ethernet addresses of the peer ports.
 240     The configuration file should contain the Ethernet addresses on separate lines::
 241
 242        XX:XX:XX:XX:XX:01
 243        XX:XX:XX:XX:XX:02
 244        ...
 245
 246
 247 *   ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
 248
 249     Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N,
 250     where 0 <= N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 251
 252 *   ``--pkt-filter-mode=mode``
 253
 254     Set Flow Director mode where mode is either ``none`` (the default), ``signature`` or ``perfect``.
 255     See :ref:`testpmd_flow_director` for more details.
 256
 257 *   ``--pkt-filter-report-hash=mode``
 258
 259     Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``.
 260
 261 *   ``--pkt-filter-size=N``
 262
 263     Set Flow Director allocated memory size, where N is 64K, 128K or 256K.
 264     Sizes are in kilobytes. The default is 64.
 265
 266 *   ``--pkt-filter-flexbytes-offset=N``
 267
 268     Set the flexbytes offset.
 269     The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address,
 270     where N is 0 <= N <= 32.
 271     The default value is 0x6.
 272
 273 *   ``--pkt-filter-drop-queue=N``
 274
 275     Set the drop-queue.
 276     In perfect filter mode, when a rule is added with queue = -1, the packet will be enqueued into the RX drop-queue.
 277     If the drop-queue does not exist, the packet is dropped. The default value is N=127.
 278
 279 *   ``--disable-crc-strip``
 280
 281     Disable hardware CRC stripping.
 282
 283 *   ``--enable-lro``
 284
 285     Enable large receive offload.
 286
 287 *   ``--enable-rx-cksum``
 288
 289     Enable hardware RX checksum offload.
 290
 291 *   ``--enable-scatter``
 292
 293     Enable scatter (multi-segment) RX.
 294
 295 *   ``--enable-hw-vlan``
 296
 297     Enable hardware VLAN.
 298
 299 *   ``--enable-hw-vlan-filter``
 300
 301     Enable hardware VLAN filter.
 302
 303 *   ``--enable-hw-vlan-strip``
 304
 305     Enable hardware VLAN strip.
 306
 307 *   ``--enable-hw-vlan-extend``
 308
 309     Enable hardware VLAN extend.
 310
 311 *   ``--enable-drop-en``
 312
 313     Enable per-queue packet drop for packets with no descriptors.
 314
 315 *   ``--disable-rss``
 316
 317     Disable RSS (Receive Side Scaling).
 318
 319 *   ``--port-topology=mode``
 320
 321     Set port topology, where mode is ``paired`` (the default) or ``chained``.
 322
 323     In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5).
 324
 325     In ``chained`` mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0).
 326
 327     The ordering of the ports can be changed using the portlist testpmd runtime function.
 328
 329 *   ``--forward-mode=mode``
 330
 331     Set the forwarding mode where ``mode`` is one of the following::
 332
 333        io (the default)
 334        mac
 335        mac_swap
 336        flowgen
 337        rxonly
 338        txonly
 339        csum
 340        icmpecho
 341        ieee1588
 342        tm
 343        noisy
 344
 345 *   ``--rss-ip``
 346
 347     Set RSS functions for IPv4/IPv6 only.
 348
 349 *   ``--rss-udp``
 350
 351     Set RSS functions for IPv4/IPv6 and UDP.
 352
 353 *   ``--rxq=N``
 354
 355     Set the number of RX queues per port to N, where 1 <= N <= 65535.
 356     The default value is 1.
 357
 358 *   ``--rxd=N``
 359
 360     Set the number of descriptors in the RX rings to N, where N > 0.
 361     The default value is 128.
 362
 363 *   ``--txq=N``
 364
 365     Set the number of TX queues per port to N, where 1 <= N <= 65535.
 366     The default value is 1.
 367
 368 *   ``--txd=N``
 369
 370     Set the number of descriptors in the TX rings to N, where N > 0.
 371     The default value is 512.
 372
 373 *   ``--burst=N``
 374
 375     Set the number of packets per burst to N, where 1 <= N <= 512.
 376     The default value is 32.
 377     If set to 0, driver default is used if defined. Else, if driver
 378     default is not defined, default of 32 is used.
 379
 380 *   ``--mbcache=N``
 381
 382     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
 383     The default value is 16.
 384
 385 *   ``--rxpt=N``
 386
 387     Set the prefetch threshold register of RX rings to N, where N >= 0.
 388     The default value is 8.
 389
 390 *   ``--rxht=N``
 391
 392     Set the host threshold register of RX rings to N, where N >= 0.
 393     The default value is 8.
 394
 395 *   ``--rxfreet=N``
 396
 397     Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
 398     The default value is 0.
 399
 400 *   ``--rxwt=N``
 401
 402     Set the write-back threshold register of RX rings to N, where N >= 0.
 403     The default value is 4.
 404
 405 *   ``--txpt=N``
 406
 407     Set the prefetch threshold register of TX rings to N, where N >= 0.
 408     The default value is 36.
 409
 410 *   ``--txht=N``
 411
 412     Set the host threshold register of TX rings to N, where N >= 0.
 413     The default value is 0.
 414
 415 *   ``--txwt=N``
 416
 417     Set the write-back threshold register of TX rings to N, where N >= 0.
 418     The default value is 0.
 419
 420 *   ``--txfreet=N``
 421
 422     Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 423     The default value is 0.
 424
 425 *   ``--txrst=N``
 426
 427     Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 428     The default value is 0.
 429
 430 *   ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 431
 432     Set the RX queues statistics counters mapping 0 <= mapping <= 15.
 433
 434 *   ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 435
 436     Set the TX queues statistics counters mapping 0 <= mapping <= 15.
 437
 438 *   ``--no-flush-rx``
 439
 440     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
 441
 442 *   ``--txpkts=X[,Y]``
 443
 444     Set TX segment sizes or total packet length. Valid for ``tx-only``
 445     and ``flowgen`` forwarding modes.
 446
 447 *   ``--disable-link-check``
 448
 449     Disable check on link status when starting/stopping ports.
 450
 451 *   ``--no-lsc-interrupt``
 452
 453     Disable LSC interrupts for all ports, even those supporting it.
 454
 455 *   ``--no-rmv-interrupt``
 456
 457     Disable RMV interrupts for all ports, even those supporting it.
 458
 459 *   ``--bitrate-stats=N``
 460
 461     Set the logical core N to perform bitrate calculation.
 462
 463 *   ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 464
 465     Enable printing the occurrence of the designated event. Using all will
 466     enable all of them.
 467
 468 *   ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 469
 470     Disable printing the occurrence of the designated event. Using all will
 471     disable all of them.
 472
 473 *   ``--flow-isolate-all``
 474
 475     Providing this parameter requests flow API isolated mode on all ports at
 476     initialization time. It ensures all traffic is received through the
 477     configured flow rules only (see flow command).
 478
 479     Ports that do not support this mode are automatically discarded.
 480
 481 *   ``--tx-offloads=0xXXXXXXXX``
 482
 483     Set the hexadecimal bitmask of TX queue offloads.
 484     The default value is 0.
 485
 486 *   ``--hot-plug``
 487
 488     Enable device event monitor machenism for hotplug.
 489
 490 *   ``--vxlan-gpe-port=N``
 491
 492     Set the UDP port number of tunnel VXLAN-GPE to N.
 493     The default value is 4790.
 494
 495 *   ``--mlockall``
 496
 497     Enable locking all memory.
 498
 499 *   ``--no-mlockall``
 500
 501     Disable locking all memory.
 502
 503 *   ``--mp-alloc <native|anon|xmem|xmemhuge>``
 504
 505     Select mempool allocation mode:
 506
 507     * native: create and populate mempool using native DPDK memory
 508     * anon: create mempool using native DPDK memory, but populate using
 509       anonymous memory
 510     * xmem: create and populate mempool using externally and anonymously
 511       allocated area
 512     * xmemhuge: create and populate mempool using externally and anonymously
 513       allocated hugepage area
 514
 515 *   ``--noisy-tx-sw-buffer-size``
 516
 517     Set the number of maximum elements  of the FIFO queue to be created
 518     for buffering packets. Only available with the noisy forwarding mode.
 519     The default value is 0.
 520
 521 *   ``--noisy-tx-sw-buffer-flushtime=N``
 522
 523     Set the time before packets in the FIFO queue is flushed.
 524     Only available with the noisy forwarding mode. The default value is 0.
 525
 526 *   ``--noisy-lkup-memory=N``
 527
 528     Set the size of the noisy neighbour simulation memory buffer in MB to N.
 529     Only available with the noisy forwarding mode. The default value is 0.
 530
 531
 532 *   ``--noisy-lkup-num-reads=N``
 533
 534     Set the number of reads to be done in noisy neighbour simulation memory buffer to N.
 535     Only available with the noisy forwarding mode. The default value is 0.
 536
 537 *   ``--noisy-lkup-num-writes=N``
 538
 539     Set the number of writes to be done in noisy neighbour simulation memory buffer to N.
 540     Only available with the noisy forwarding mode. The default value is 0.
 541
 542 *   ``--noisy-lkup-num-reads-writes=N``
 543
 544     Set the number of r/w accesses to be done in noisy neighbour simulation memory buffer to N.
 545     Only available with the noisy forwarding mode. The default value is 0.