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 *   ``--syslog``
  98
  99     Set the syslog facility.
 100
 101 *   ``--socket-mem``
 102
 103     Set the memory to allocate on specific sockets (use comma separated values).
 104
 105 *   ``--huge-dir``
 106
 107     Specify the directory where the hugetlbfs is mounted.
 108
 109 *   ``mbuf-pool-ops-name``:
 110
 111     Pool ops name for mbuf to use.
 112
 113 *   ``--proc-type``
 114
 115     Set the type of the current process.
 116
 117 *   ``--file-prefix``
 118
 119     Prefix for hugepage filenames.
 120
 121 *   ``-vmware-tsc-map``
 122
 123     Use VMware TSC map instead of native RDTSC.
 124
 125 *   ``--vdev``
 126
 127     Add a virtual device using the format::
 128
 129        <driver><id>[,key=val, ...]
 130
 131     For example::
 132
 133        --vdev 'net_pcap0,rx_pcap=input.pcap,tx_pcap=output.pcap'
 134
 135 *   ``--base-virtaddr``
 136
 137     Specify base virtual address.
 138
 139 *   ``--create-uio-dev``
 140
 141     Create ``/dev/uioX`` (usually done by hotplug).
 142
 143 *   ``--no-shconf``
 144
 145     No shared config (mmap-ed files).
 146
 147 *   ``--no-pci``
 148
 149     Disable pci.
 150
 151 *   ``--no-hpet``
 152
 153     Disable hpet.
 154
 155 *   ``--no-huge``
 156
 157     Use malloc instead of hugetlbfs.
 158
 159
 160 Testpmd Command-line Options
 161 ----------------------------
 162
 163 The following are the command-line options for the testpmd applications.
 164 They must be separated from the EAL options, shown in the previous section, with a ``--`` separator:
 165
 166 .. code-block:: console
 167
 168     sudo ./testpmd -l 0-3 -n 4 -- -i --portmask=0x1 --nb-cores=2
 169
 170 The commandline options are:
 171
 172 *   ``-i, --interactive``
 173
 174     Run testpmd in interactive mode.
 175     In this mode, the testpmd starts with a prompt that can be used to start and stop forwarding,
 176     configure the application and display stats on the current packet processing session.
 177     See :ref:`testpmd_runtime` for more details.
 178
 179     In non-interactive mode,
 180     the application starts with the configuration specified on the command-line and
 181     immediately enters forwarding mode.
 182
 183 *   ``-h, --help``
 184
 185     Display a help message and quit.
 186
 187 *   ``-a, --auto-start``
 188
 189     Start forwarding on initialization.
 190
 191 *   ``--tx-first``
 192
 193     Start forwarding, after sending a burst of packets first.
 194
 195 .. Note::
 196
 197    This flag should be only used in non-interactive mode.
 198
 199 *   ``--stats-period PERIOD``
 200
 201     Display statistics every PERIOD seconds, if interactive mode is disabled.
 202     The default value is 0, which means that the statistics will not be displayed.
 203
 204 *   ``--nb-cores=N``
 205
 206     Set the number of forwarding cores,
 207     where 1 <= N <= "number of cores" or ``CONFIG_RTE_MAX_LCORE`` from the configuration file.
 208     The default value is 1.
 209
 210 *   ``--nb-ports=N``
 211
 212     Set the number of forwarding ports,
 213     where 1 <= N <= "number of ports" on the board or ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 214     The default value is the number of ports on the board.
 215
 216 *   ``--coremask=0xXX``
 217
 218     Set the hexadecimal bitmask of the cores running the packet forwarding test.
 219     The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
 220
 221 *   ``--portmask=0xXX``
 222
 223     Set the hexadecimal bitmask of the ports used by the packet forwarding test.
 224
 225 *   ``--numa``
 226
 227     Enable NUMA-aware allocation of RX/TX rings and of RX memory buffers
 228     (mbufs). [Default setting]
 229
 230 *   ``--no-numa``
 231
 232     Disable NUMA-aware allocation of RX/TX rings and of RX memory buffers (mbufs).
 233
 234 *   ``--port-numa-config=(port,socket)[,(port,socket)]``
 235
 236     Specify the socket on which the memory pool to be used by the port will be allocated.
 237
 238 *   ``--ring-numa-config=(port,flag,socket)[,(port,flag,socket)]``
 239
 240     Specify the socket on which the TX/RX rings for the port will be allocated.
 241     Where flag is 1 for RX, 2 for TX, and 3 for RX and TX.
 242
 243 *   ``--socket-num=N``
 244
 245     Set the socket from which all memory is allocated in NUMA mode,
 246     where 0 <= N < number of sockets on the board.
 247
 248 *   ``--mbuf-size=N``
 249
 250     Set the data size of the mbufs used to N bytes, where N < 65536. The default value is 2048.
 251
 252 *   ``--total-num-mbufs=N``
 253
 254     Set the number of mbufs to be allocated in the mbuf pools, where N > 1024.
 255
 256 *   ``--max-pkt-len=N``
 257
 258     Set the maximum packet size to N bytes, where N >= 64. The default value is 1518.
 259
 260 *   ``--eth-peers-configfile=name``
 261
 262     Use a configuration file containing the Ethernet addresses of the peer ports.
 263     The configuration file should contain the Ethernet addresses on separate lines::
 264
 265        XX:XX:XX:XX:XX:01
 266        XX:XX:XX:XX:XX:02
 267        ...
 268
 269
 270 *   ``--eth-peer=N,XX:XX:XX:XX:XX:XX``
 271
 272     Set the MAC address ``XX:XX:XX:XX:XX:XX`` of the peer port N,
 273     where 0 <= N < ``CONFIG_RTE_MAX_ETHPORTS`` from the configuration file.
 274
 275 *   ``--pkt-filter-mode=mode``
 276
 277     Set Flow Director mode where mode is either ``none`` (the default), ``signature`` or ``perfect``.
 278     See :ref:`testpmd_flow_director` for more details.
 279
 280 *   ``--pkt-filter-report-hash=mode``
 281
 282     Set Flow Director hash match reporting mode where mode is ``none``, ``match`` (the default) or ``always``.
 283
 284 *   ``--pkt-filter-size=N``
 285
 286     Set Flow Director allocated memory size, where N is 64K, 128K or 256K.
 287     Sizes are in kilobytes. The default is 64.
 288
 289 *   ``--pkt-filter-flexbytes-offset=N``
 290
 291     Set the flexbytes offset.
 292     The offset is defined in words (not bytes) counted from the first byte of the destination Ethernet MAC address,
 293     where N is 0 <= N <= 32.
 294     The default value is 0x6.
 295
 296 *   ``--pkt-filter-drop-queue=N``
 297
 298     Set the drop-queue.
 299     In perfect filter mode, when a rule is added with queue = -1, the packet will be enqueued into the RX drop-queue.
 300     If the drop-queue does not exist, the packet is dropped. The default value is N=127.
 301
 302 *   ``--disable-crc-strip``
 303
 304     Disable hardware CRC stripping.
 305
 306 *   ``--enable-lro``
 307
 308     Enable large receive offload.
 309
 310 *   ``--enable-rx-cksum``
 311
 312     Enable hardware RX checksum offload.
 313
 314 *   ``--enable-scatter``
 315
 316     Enable scatter (multi-segment) RX.
 317
 318 *   ``--disable-hw-vlan``
 319
 320     Disable hardware VLAN.
 321
 322 *   ``--disable-hw-vlan-filter``
 323
 324     Disable hardware VLAN filter.
 325
 326 *   ``--disable-hw-vlan-strip``
 327
 328     Disable hardware VLAN strip.
 329
 330 *   ``--disable-hw-vlan-extend``
 331
 332     Disable hardware VLAN extend.
 333
 334 *   ``--enable-drop-en``
 335
 336     Enable per-queue packet drop for packets with no descriptors.
 337
 338 *   ``--disable-rss``
 339
 340     Disable RSS (Receive Side Scaling).
 341
 342 *   ``--port-topology=mode``
 343
 344     Set port topology, where mode is ``paired`` (the default) or ``chained``.
 345
 346     In ``paired`` mode, the forwarding is between pairs of ports, for example: (0,1), (2,3), (4,5).
 347
 348     In ``chained`` mode, the forwarding is to the next available port in the port mask, for example: (0,1), (1,2), (2,0).
 349
 350     The ordering of the ports can be changed using the portlist testpmd runtime function.
 351
 352 *   ``--forward-mode=mode``
 353
 354     Set the forwarding mode where ``mode`` is one of the following::
 355
 356        io (the default)
 357        mac
 358        mac_swap
 359        flowgen
 360        rxonly
 361        txonly
 362        csum
 363        icmpecho
 364        ieee1588
 365        tm
 366
 367 *   ``--rss-ip``
 368
 369     Set RSS functions for IPv4/IPv6 only.
 370
 371 *   ``--rss-udp``
 372
 373     Set RSS functions for IPv4/IPv6 and UDP.
 374
 375 *   ``--rxq=N``
 376
 377     Set the number of RX queues per port to N, where 1 <= N <= 65535.
 378     The default value is 1.
 379
 380 *   ``--rxd=N``
 381
 382     Set the number of descriptors in the RX rings to N, where N > 0.
 383     The default value is 128.
 384
 385 *   ``--txq=N``
 386
 387     Set the number of TX queues per port to N, where 1 <= N <= 65535.
 388     The default value is 1.
 389
 390 *   ``--txd=N``
 391
 392     Set the number of descriptors in the TX rings to N, where N > 0.
 393     The default value is 512.
 394
 395 *   ``--burst=N``
 396
 397     Set the number of packets per burst to N, where 1 <= N <= 512.
 398     The default value is 16.
 399
 400 *   ``--mbcache=N``
 401
 402     Set the cache of mbuf memory pools to N, where 0 <= N <= 512.
 403     The default value is 16.
 404
 405 *   ``--rxpt=N``
 406
 407     Set the prefetch threshold register of RX rings to N, where N >= 0.
 408     The default value is 8.
 409
 410 *   ``--rxht=N``
 411
 412     Set the host threshold register of RX rings to N, where N >= 0.
 413     The default value is 8.
 414
 415 *   ``--rxfreet=N``
 416
 417     Set the free threshold of RX descriptors to N, where 0 <= N < value of --rxd.
 418     The default value is 0.
 419
 420 *   ``--rxwt=N``
 421
 422     Set the write-back threshold register of RX rings to N, where N >= 0.
 423     The default value is 4.
 424
 425 *   ``--txpt=N``
 426
 427     Set the prefetch threshold register of TX rings to N, where N >= 0.
 428     The default value is 36.
 429
 430 *   ``--txht=N``
 431
 432     Set the host threshold register of TX rings to N, where N >= 0.
 433     The default value is 0.
 434
 435 *   ``--txwt=N``
 436
 437     Set the write-back threshold register of TX rings to N, where N >= 0.
 438     The default value is 0.
 439
 440 *   ``--txfreet=N``
 441
 442     Set the transmit free threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 443     The default value is 0.
 444
 445 *   ``--txrst=N``
 446
 447     Set the transmit RS bit threshold of TX rings to N, where 0 <= N <= value of ``--txd``.
 448     The default value is 0.
 449
 450 *   ``--txqflags=0xXXXXXXXX``
 451
 452     Set the hexadecimal bitmask of TX queue flags, where 0 <= N <= 0x7FFFFFFF.
 453     The default value is 0.
 454
 455     .. note::
 456
 457        When using hardware offload functions such as vlan or checksum
 458        add ``txqflags=0`` to force the full-featured TX code path.
 459        In some PMDs this may already be the default.
 460
 461
 462 *   ``--rx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 463
 464     Set the RX queues statistics counters mapping 0 <= mapping <= 15.
 465
 466 *   ``--tx-queue-stats-mapping=(port,queue,mapping)[,(port,queue,mapping)]``
 467
 468     Set the TX queues statistics counters mapping 0 <= mapping <= 15.
 469
 470 *   ``--no-flush-rx``
 471
 472     Don't flush the RX streams before starting forwarding. Used mainly with the PCAP PMD.
 473
 474 *   ``--txpkts=X[,Y]``
 475
 476     Set TX segment sizes or total packet length. Valid for ``tx-only``
 477     and ``flowgen`` forwarding modes.
 478
 479 *   ``--disable-link-check``
 480
 481     Disable check on link status when starting/stopping ports.
 482
 483 *   ``--no-lsc-interrupt``
 484
 485     Disable LSC interrupts for all ports, even those supporting it.
 486
 487 *   ``--no-rmv-interrupt``
 488
 489     Disable RMV interrupts for all ports, even those supporting it.
 490
 491 *   ``--bitrate-stats=N``
 492
 493     Set the logical core N to perform bitrate calculation.
 494
 495 *   ``--print-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|all>``
 496
 497     Enable printing the occurrence of the designated event. Using all will
 498     enable all of them.
 499
 500 *   ``--mask-event <unknown|intr_lsc|queue_state|intr_reset|vf_mbox|macsec|intr_rmv|all>``
 501
 502     Disable printing the occurrence of the designated event. Using all will
 503     disable all of them.
 504
 505 *   ``--flow-isolate-all``
 506
 507     Providing this parameter requests flow API isolated mode on all ports at
 508     initialization time. It ensures all traffic is received through the
 509     configured flow rules only (see flow command).
 510
 511     Ports that do not support this mode are automatically discarded.