doc/guides/testpmd_app_ug/run_app.rst

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