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
 344 *   ``--rss-ip``
 345
 346     Set RSS functions for IPv4/IPv6 only.
 347
 348 *   ``--rss-udp``
 349
 350     Set RSS functions for IPv4/IPv6 and UDP.
 351
 352 *   ``--rxq=N``
 353
 354     Set the number of RX queues per port to N, where 1 <= N <= 65535.
 355     The default value is 1.
 356
 357 *   ``--rxd=N``
 358
 359     Set the number of descriptors in the RX rings to N, where N > 0.
 360     The default value is 128.
 361
 362 *   ``--txq=N``
 363
 364     Set the number of TX queues per port to N, where 1 <= N <= 65535.
 365     The default value is 1.
 366
 367 *   ``--txd=N``
 368
 369     Set the number of descriptors in the TX rings to N, where N > 0.
 370     The default value is 512.
 371
 372 *   ``--burst=N``
 373
 374     Set the number of packets per burst to N, where 1 <= N <= 512.
 375     The default value is 32.
 376     If set to 0, driver default is used if defined. Else, if driver
 377     default is not defined, default of 32 is used.
 378
 379 *   ``--mbcache=N``
 380
 381     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
 382     The default value is 16.
 383
 384 *   ``--rxpt=N``
 385
 386     Set the prefetch threshold register of RX rings to N, where N >= 0.
 387     The default value is 8.
 388
 389 *   ``--rxht=N``
 390
 391     Set the host threshold register of RX rings to N, where N >= 0.
 392     The default value is 8.
 393
 394 *   ``--rxfreet=N``
 395
 396     Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
 397     The default value is 0.
 398
 399 *   ``--rxwt=N``
 400
 401     Set the write-back threshold register of RX rings to N, where N >= 0.
 402     The default value is 4.
 403
 404 *   ``--txpt=N``
 405
 406     Set the prefetch threshold register of TX rings to N, where N >= 0.
 407     The default value is 36.
 408
 409 *   ``--txht=N``
 410
 411     Set the host threshold register of TX rings to N, where N >= 0.
 412     The default value is 0.
 413
 414 *   ``--txwt=N``
 415
 416     Set the write-back threshold register of TX rings to N, where N >= 0.
 417     The default value is 0.
 418
 419 *   ``--txfreet=N``
 420
 421     Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 422     The default value is 0.
 423
 424 *   ``--txrst=N``
 425
 426     Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 427     The default value is 0.
 428
 429 *   ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 430
 431     Set the RX queues statistics counters mapping 0 <= mapping <= 15.
 432
 433 *   ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 434
 435     Set the TX queues statistics counters mapping 0 <= mapping <= 15.
 436
 437 *   ``--no-flush-rx``
 438
 439     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
 440
 441 *   ``--txpkts=X[,Y]``
 442
 443     Set TX segment sizes or total packet length. Valid for ``tx-only``
 444     and ``flowgen`` forwarding modes.
 445
 446 *   ``--disable-link-check``
 447
 448     Disable check on link status when starting/stopping ports.
 449
 450 *   ``--no-lsc-interrupt``
 451
 452     Disable LSC interrupts for all ports, even those supporting it.
 453
 454 *   ``--no-rmv-interrupt``
 455
 456     Disable RMV interrupts for all ports, even those supporting it.
 457
 458 *   ``--bitrate-stats=N``
 459
 460     Set the logical core N to perform bitrate calculation.
 461
 462 *   ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 463
 464     Enable printing the occurrence of the designated event. Using all will
 465     enable all of them.
 466
 467 *   ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|dev_probed|dev_released|all>``
 468
 469     Disable printing the occurrence of the designated event. Using all will
 470     disable all of them.
 471
 472 *   ``--flow-isolate-all``
 473
 474     Providing this parameter requests flow API isolated mode on all ports at
 475     initialization time. It ensures all traffic is received through the
 476     configured flow rules only (see flow command).
 477
 478     Ports that do not support this mode are automatically discarded.
 479
 480 *   ``--tx-offloads=0xXXXXXXXX``
 481
 482     Set the hexadecimal bitmask of TX queue offloads.
 483     The default value is 0.
 484
 485 *   ``--hot-plug``
 486
 487     Enable device event monitor machenism for hotplug.
 488
 489 *   ``--vxlan-gpe-port=N``
 490
 491     Set the UDP port number of tunnel VXLAN-GPE to N.
 492     The default value is 4790.
 493
 494 *   ``--mlockall``
 495
 496     Enable locking all memory.
 497
 498 *   ``--no-mlockall``
 499
 500     Disable locking all memory.