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 *   ``--iova-mode <pa|va>``
 137
 138     Force IOVA mode to a specific value.
 139
 140
 141 Testpmd Command-line Options
 142 ----------------------------
 143
 144 The following are the command-line options for the testpmd applications.
 145 They must be separated from the EAL options, shown in the previous section, with a ``--`` separator:
 146
 147 .. code-block:: console
 148
 149     sudo ./testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2
 150
 151 The commandline options are:
 152
 153 *   ``-i, --interactive``
 154
 155     Run testpmd in interactive mode.
 156     In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding,
 157     configure the application and display stats on the current packet processing session.
 158     See :ref:`testpmd_runtime` for more details.
 159
 160     In non-interactive mode,
 161     the application starts with the configuration specified on the command-line and
 162     immediately enters forwarding mode.
 163
 164 *   ``-h, --help``
 165
 166     Display a help message and quit.
 167
 168 *   ``-a, --auto-start``
 169
 170     Start forwarding on initialization.
 171
 172 *   ``--tx-first``
 173
 174     Start forwarding, after sending a burst of packets first.
 175
 176 .. Note::
 177
 178    This flag should be only used in non-interactive mode.
 179
 180 *   ``--stats-period PERIOD``
 181
 182     Display statistics every PERIOD seconds, if interactive mode is disabled.
 183     The default value is 0, which means that the statistics will not be displayed.
 184
 185 *   ``--nb-cores=N``
 186
 187     Set the number of forwarding cores,
 188     where 1 <= N <= "number of cores" or ``CONFIG_RTE_MAX_LCORE`` from the configuration file.
 189     The default value is 1.
 190
 191 *   ``--nb-ports=N``
 192
 193     Set the number of forwarding ports,
 194     where 1 <= N <= "number of ports" on the board or ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 195     The default value is the number of ports on the board.
 196
 197 *   ``--coremask=0xXX``
 198
 199     Set the hexadecimal bitmask of the cores running the packet forwarding test.
 200     The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
 201
 202 *   ``--portmask=0xXX``
 203
 204     Set the hexadecimal bitmask of the ports used by the packet forwarding test.
 205
 206 *   ``--numa``
 207
 208     Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers
 209     (mbufs). [Default setting]
 210
 211 *   ``--no-numa``
 212
 213     Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).
 214
 215 *   ``--port-numa-config=(port,socket)[,(port,socket)]``
 216
 217     Specify the socket on which the memory pool to be used by the port will be allocated.
 218
 219 *   ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]``
 220
 221     Specify the socket on which the TX/RX rings for the port will be allocated.
 222     Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.
 223
 224 *   ``--socket-num=N``
 225
 226     Set the socket from which all memory is allocated in NUMA mode,
 227     where 0 <= N < number of sockets on the board.
 228
 229 *   ``--mbuf-size=N``
 230
 231     Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048.
 232
 233 *   ``--total-num-mbufs=N``
 234
 235     Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.
 236
 237 *   ``--max-pkt-len=N``
 238
 239     Set the maximum packet size to N bytes, where N >= 64. The default value is 1518.
 240
 241 *   ``--eth-peers-configfile=name``
 242
 243     Use a configuration file containing the Ethernet addresses of the peer ports.
 244     The configuration file should contain the Ethernet addresses on separate lines::
 245
 246        XX:XX:XX:XX:XX:01
 247        XX:XX:XX:XX:XX:02
 248        ...
 249
 250
 251 *   ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
 252
 253     Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N,
 254     where 0 <= N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 255
 256 *   ``--pkt-filter-mode=mode``
 257
 258     Set Flow Director mode where mode is either ``none`` (the default), ``signature`` or ``perfect``.
 259     See :ref:`testpmd_flow_director` for more details.
 260
 261 *   ``--pkt-filter-report-hash=mode``
 262
 263     Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``.
 264
 265 *   ``--pkt-filter-size=N``
 266
 267     Set Flow Director allocated memory size, where N is 64K, 128K or 256K.
 268     Sizes are in kilobytes. The default is 64.
 269
 270 *   ``--pkt-filter-flexbytes-offset=N``
 271
 272     Set the flexbytes offset.
 273     The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address,
 274     where N is 0 <= N <= 32.
 275     The default value is 0x6.
 276
 277 *   ``--pkt-filter-drop-queue=N``
 278
 279     Set the drop-queue.
 280     In perfect filter mode, when a rule is added with queue = -1, the packet will be enqueued into the RX drop-queue.
 281     If the drop-queue does not exist, the packet is dropped. The default value is N=127.
 282
 283 *   ``--disable-crc-strip``
 284
 285     Disable hardware CRC stripping.
 286
 287 *   ``--enable-lro``
 288
 289     Enable large receive offload.
 290
 291 *   ``--enable-rx-cksum``
 292
 293     Enable hardware RX checksum offload.
 294
 295 *   ``--enable-scatter``
 296
 297     Enable scatter (multi-segment) RX.
 298
 299 *   ``--enable-hw-vlan``
 300
 301     Enable hardware VLAN.
 302
 303 *   ``--enable-hw-vlan-filter``
 304
 305     Enable hardware VLAN filter.
 306
 307 *   ``--enable-hw-vlan-strip``
 308
 309     Enable hardware VLAN strip.
 310
 311 *   ``--enable-hw-vlan-extend``
 312
 313     Enable hardware VLAN extend.
 314
 315 *   ``--enable-drop-en``
 316
 317     Enable per-queue packet drop for packets with no descriptors.
 318
 319 *   ``--disable-rss``
 320
 321     Disable RSS (Receive Side Scaling).
 322
 323 *   ``--port-topology=mode``
 324
 325     Set port topology, where mode is ``paired`` (the default) or ``chained``.
 326
 327     In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5).
 328
 329     In ``chained`` mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0).
 330
 331     The ordering of the ports can be changed using the portlist testpmd runtime function.
 332
 333 *   ``--forward-mode=mode``
 334
 335     Set the forwarding mode where ``mode`` is one of the following::
 336
 337        io (the default)
 338        mac
 339        macswap
 340        flowgen
 341        rxonly
 342        txonly
 343        csum
 344        icmpecho
 345        ieee1588
 346        tm
 347        noisy
 348
 349 *   ``--rss-ip``
 350
 351     Set RSS functions for IPv4/IPv6 only.
 352
 353 *   ``--rss-udp``
 354
 355     Set RSS functions for IPv4/IPv6 and UDP.
 356
 357 *   ``--rxq=N``
 358
 359     Set the number of RX queues per port to N, where 1 <= N <= 65535.
 360     The default value is 1.
 361
 362 *   ``--rxd=N``
 363
 364     Set the number of descriptors in the RX rings to N, where N > 0.
 365     The default value is 128.
 366
 367 *   ``--txq=N``
 368
 369     Set the number of TX queues per port to N, where 1 <= N <= 65535.
 370     The default value is 1.
 371
 372 *   ``--txd=N``
 373
 374     Set the number of descriptors in the TX rings to N, where N > 0.
 375     The default value is 512.
 376
 377 *   ``--burst=N``
 378
 379     Set the number of packets per burst to N, where 1 <= N <= 512.
 380     The default value is 32.
 381     If set to 0, driver default is used if defined. Else, if driver
 382     default is not defined, default of 32 is used.
 383
 384 *   ``--mbcache=N``
 385
 386     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
 387     The default value is 16.
 388
 389 *   ``--rxpt=N``
 390
 391     Set the prefetch threshold register of RX rings to N, where N >= 0.
 392     The default value is 8.
 393
 394 *   ``--rxht=N``
 395
 396     Set the host threshold register of RX rings to N, where N >= 0.
 397     The default value is 8.
 398
 399 *   ``--rxfreet=N``
 400
 401     Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
 402     The default value is 0.
 403
 404 *   ``--rxwt=N``
 405
 406     Set the write-back threshold register of RX rings to N, where N >= 0.
 407     The default value is 4.
 408
 409 *   ``--txpt=N``
 410
 411     Set the prefetch threshold register of TX rings to N, where N >= 0.
 412     The default value is 36.
 413
 414 *   ``--txht=N``
 415
 416     Set the host threshold register of TX rings to N, where N >= 0.
 417     The default value is 0.
 418
 419 *   ``--txwt=N``
 420
 421     Set the write-back threshold register of TX rings to N, where N >= 0.
 422     The default value is 0.
 423
 424 *   ``--txfreet=N``
 425
 426     Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 427     The default value is 0.
 428
 429 *   ``--txrst=N``
 430
 431     Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 432     The default value is 0.
 433
 434 *   ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 435
 436     Set the RX queues statistics counters mapping 0 <= mapping <= 15.
 437
 438 *   ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 439
 440     Set the TX queues statistics counters mapping 0 <= mapping <= 15.
 441
 442 *   ``--no-flush-rx``
 443
 444     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
 445
 446 *   ``--txpkts=X[,Y]``
 447
 448     Set TX segment sizes or total packet length. Valid for ``tx-only``
 449     and ``flowgen`` forwarding modes.
 450
 451 *   ``--disable-link-check``
 452
 453     Disable check on link status when starting/stopping ports.
 454
 455 *   ``--no-lsc-interrupt``
 456
 457     Disable LSC interrupts for all ports, even those supporting it.
 458
 459 *   ``--no-rmv-interrupt``
 460
 461     Disable RMV interrupts for all ports, even those supporting it.
 462
 463 *   ``--bitrate-stats=N``
 464
 465     Set the logical core N to perform bitrate calculation.
 466
 467 *   ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 468
 469     Enable printing the occurrence of the designated event. Using all will
 470     enable all of them.
 471
 472 *   ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 473
 474     Disable printing the occurrence of the designated event. Using all will
 475     disable all of them.
 476
 477 *   ``--flow-isolate-all``
 478
 479     Providing this parameter requests flow API isolated mode on all ports at
 480     initialization time. It ensures all traffic is received through the
 481     configured flow rules only (see flow command).
 482
 483     Ports that do not support this mode are automatically discarded.
 484
 485 *   ``--tx-offloads=0xXXXXXXXX``
 486
 487     Set the hexadecimal bitmask of TX queue offloads.
 488     The default value is 0.
 489
 490 *   ``--hot-plug``
 491
 492     Enable device event monitor machenism for hotplug.
 493
 494 *   ``--vxlan-gpe-port=N``
 495
 496     Set the UDP port number of tunnel VXLAN-GPE to N.
 497     The default value is 4790.
 498
 499 *   ``--mlockall``
 500
 501     Enable locking all memory.
 502
 503 *   ``--no-mlockall``
 504
 505     Disable locking all memory.
 506
 507 *   ``--mp-alloc <native|anon|xmem|xmemhuge>``
 508
 509     Select mempool allocation mode:
 510
 511     * native: create and populate mempool using native DPDK memory
 512     * anon: create mempool using native DPDK memory, but populate using
 513       anonymous memory
 514     * xmem: create and populate mempool using externally and anonymously
 515       allocated area
 516     * xmemhuge: create and populate mempool using externally and anonymously
 517       allocated hugepage area
 518
 519 *   ``--noisy-tx-sw-buffer-size``
 520
 521     Set the number of maximum elements  of the FIFO queue to be created
 522     for buffering packets. Only available with the noisy forwarding mode.
 523     The default value is 0.
 524
 525 *   ``--noisy-tx-sw-buffer-flushtime=N``
 526
 527     Set the time before packets in the FIFO queue is flushed.
 528     Only available with the noisy forwarding mode. The default value is 0.
 529
 530 *   ``--noisy-lkup-memory=N``
 531
 532     Set the size of the noisy neighbour simulation memory buffer in MB to N.
 533     Only available with the noisy forwarding mode. The default value is 0.
 534
 535
 536 *   ``--noisy-lkup-num-reads=N``
 537
 538     Set the number of reads to be done in noisy neighbour simulation memory buffer to N.
 539     Only available with the noisy forwarding mode. The default value is 0.
 540
 541 *   ``--noisy-lkup-num-writes=N``
 542
 543     Set the number of writes to be done in noisy neighbour simulation memory buffer to N.
 544     Only available with the noisy forwarding mode. The default value is 0.
 545
 546 *   ``--noisy-lkup-num-reads-writes=N``
 547
 548     Set the number of r/w accesses to be done in noisy neighbour simulation memory buffer to N.
 549     Only available with the noisy forwarding mode. The default value is 0.