doc/guides/testpmd_app_ug/testpmd_funcs.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2016 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 .. _testpmd_runtime:
  32
  33 Testpmd Runtime Functions
  34 =========================
  35
  36 Where the testpmd application is started in interactive mode, (``-i|--interactive``),
  37 it displays a prompt that can be used to start and stop forwarding,
  38 configure the application, display statistics (including the extended NIC
  39 statistics aka xstats) , set the Flow Director and other tasks::
  40
  41    testpmd>
  42
  43 The testpmd prompt has some, limited, readline support.
  44 Common bash command-line functions such as ``Ctrl+a`` and ``Ctrl+e`` to go to the start and end of the prompt line are supported
  45 as well as access to the command history via the up-arrow.
  46
  47 There is also support for tab completion.
  48 If you type a partial command and hit ``<TAB>`` you get a list of the available completions:
  49
  50 .. code-block:: console
  51
  52    testpmd> show port <TAB>
  53
  54        info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X
  55        info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all
  56        stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X
  57        stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all
  58        ...
  59
  60
  61 .. note::
  62
  63    Some examples in this document are too long to fit on one line are are shown wrapped at `"\\"` for display purposes::
  64
  65       testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
  66                (pause_time) (send_xon) (port_id)
  67
  68 In the real ``testpmd>`` prompt these commands should be on a single line.
  69
  70 Help Functions
  71 --------------
  72
  73 The testpmd has on-line help for the functions that are available at runtime.
  74 These are divided into sections and can be accessed using help, help section or help all:
  75
  76 .. code-block:: console
  77
  78    testpmd> help
  79
  80        help control    : Start and stop forwarding.
  81        help display    : Displaying port, stats and config information.
  82        help config     : Configuration information.
  83        help ports      : Configuring ports.
  84        help registers  : Reading and setting port registers.
  85        help filters    : Filters configuration help.
  86        help all        : All of the above sections.
  87
  88
  89 Command File Functions
  90 ----------------------
  91
  92 To facilitate loading large number of commands or to avoid cutting and pasting where not
  93 practical or possible testpmd supports alternative methods for executing commands.
  94
  95 * If started with the ``--cmdline-file=FILENAME`` command line argument testpmd
  96   will execute all CLI commands contained within the file immediately before
  97   starting packet forwarding or entering interactive mode.
  98
  99 .. code-block:: console
 100
 101    ./testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt
 102    Interactive-mode selected
 103    CLI commands to be read from /home/ubuntu/flow-create-commands.txt
 104    Configuring Port 0 (socket 0)
 105    Port 0: 7C:FE:90:CB:74:CE
 106    Configuring Port 1 (socket 0)
 107    Port 1: 7C:FE:90:CB:74:CA
 108    Checking link statuses...
 109    Port 0 Link Up - speed 10000 Mbps - full-duplex
 110    Port 1 Link Up - speed 10000 Mbps - full-duplex
 111    Done
 112    Flow rule #0 created
 113    Flow rule #1 created
 114    ...
 115    ...
 116    Flow rule #498 created
 117    Flow rule #499 created
 118    Read all CLI commands from /home/ubuntu/flow-create-commands.txt
 119    testpmd>
 120
 121
 122 In all cases output from any included command will be displayed as standard output.
 123 Execution will continue until the end of the file is reached regardless of
 124 whether any errors occur.  The end user must examine the output to determine if
 125 any failures occurred.
 126
 127
 128 Control Functions
 129 -----------------
 130
 131 start
 132 ~~~~~
 133
 134 Start packet forwarding with current configuration::
 135
 136    testpmd> start
 137
 138 start tx_first
 139 ~~~~~~~~~~~~~~
 140
 141 Start packet forwarding with current configuration after sending specified number of bursts of packets::
 142
 143    testpmd> start tx_first (""|burst_num)
 144
 145 The default burst number is 1 when ``burst_num`` not presented.
 146
 147 stop
 148 ~~~~
 149
 150 Stop packet forwarding, and display accumulated statistics::
 151
 152    testpmd> stop
 153
 154 quit
 155 ~~~~
 156
 157 Quit to prompt::
 158
 159    testpmd> quit
 160
 161
 162 Display Functions
 163 -----------------
 164
 165 The functions in the following sections are used to display information about the
 166 testpmd configuration or the NIC status.
 167
 168 show port
 169 ~~~~~~~~~
 170
 171 Display information for a given port or all ports::
 172
 173    testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc|cap) (port_id|all)
 174
 175 The available information categories are:
 176
 177 * ``info``: General port information such as MAC address.
 178
 179 * ``stats``: RX/TX statistics.
 180
 181 * ``xstats``: RX/TX extended NIC statistics.
 182
 183 * ``fdir``: Flow Director information and statistics.
 184
 185 * ``stat_qmap``: Queue statistics mapping.
 186
 187 * ``dcb_tc``: DCB information such as TC mapping.
 188
 189 * ``cap``: Supported offload capabilities.
 190
 191 For example:
 192
 193 .. code-block:: console
 194
 195    testpmd> show port info 0
 196
 197    ********************* Infos for port 0 *********************
 198
 199    MAC address: XX:XX:XX:XX:XX:XX
 200    Connect to socket: 0
 201    memory allocation on the socket: 0
 202    Link status: up
 203    Link speed: 40000 Mbps
 204    Link duplex: full-duplex
 205    Promiscuous mode: enabled
 206    Allmulticast mode: disabled
 207    Maximum number of MAC addresses: 64
 208    Maximum number of MAC addresses of hash filtering: 0
 209    VLAN offload:
 210        strip on
 211        filter on
 212        qinq(extend) off
 213    Redirection table size: 512
 214    Supported flow types:
 215      ipv4-frag
 216      ipv4-tcp
 217      ipv4-udp
 218      ipv4-sctp
 219      ipv4-other
 220      ipv6-frag
 221      ipv6-tcp
 222      ipv6-udp
 223      ipv6-sctp
 224      ipv6-other
 225      l2_payload
 226      port
 227      vxlan
 228      geneve
 229      nvgre
 230
 231 show port rss reta
 232 ~~~~~~~~~~~~~~~~~~
 233
 234 Display the rss redirection table entry indicated by masks on port X::
 235
 236    testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
 237
 238 size is used to indicate the hardware supported reta size
 239
 240 show port rss-hash
 241 ~~~~~~~~~~~~~~~~~~
 242
 243 Display the RSS hash functions and RSS hash key of a port::
 244
 245    testpmd> show port (port_id) rss-hash ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2-payload|ipv6-ex|ipv6-tcp-ex|ipv6-udp-ex [key]
 246
 247 clear port
 248 ~~~~~~~~~~
 249
 250 Clear the port statistics for a given port or for all ports::
 251
 252    testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all)
 253
 254 For example::
 255
 256    testpmd> clear port stats all
 257
 258 show (rxq|txq)
 259 ~~~~~~~~~~~~~~
 260
 261 Display information for a given port's RX/TX queue::
 262
 263    testpmd> show (rxq|txq) info (port_id) (queue_id)
 264
 265 show config
 266 ~~~~~~~~~~~
 267
 268 Displays the configuration of the application.
 269 The configuration comes from the command-line, the runtime or the application defaults::
 270
 271    testpmd> show config (rxtx|cores|fwd|txpkts)
 272
 273 The available information categories are:
 274
 275 * ``rxtx``: RX/TX configuration items.
 276
 277 * ``cores``: List of forwarding cores.
 278
 279 * ``fwd``: Packet forwarding configuration.
 280
 281 * ``txpkts``: Packets to TX configuration.
 282
 283 For example:
 284
 285 .. code-block:: console
 286
 287    testpmd> show config rxtx
 288
 289    io packet forwarding - CRC stripping disabled - packets/burst=16
 290    nb forwarding cores=2 - nb forwarding ports=1
 291    RX queues=1 - RX desc=128 - RX free threshold=0
 292    RX threshold registers: pthresh=8 hthresh=8 wthresh=4
 293    TX queues=1 - TX desc=512 - TX free threshold=0
 294    TX threshold registers: pthresh=36 hthresh=0 wthresh=0
 295    TX RS bit threshold=0 - TXQ flags=0x0
 296
 297 set fwd
 298 ~~~~~~~
 299
 300 Set the packet forwarding mode::
 301
 302    testpmd> set fwd (io|mac|macswap|flowgen| \
 303                      rxonly|txonly|csum|icmpecho) (""|retry)
 304
 305 ``retry`` can be specified for forwarding engines except ``rx_only``.
 306
 307 The available information categories are:
 308
 309 * ``io``: Forwards packets "as-is" in I/O mode.
 310   This is the fastest possible forwarding operation as it does not access packets data.
 311   This is the default mode.
 312
 313 * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
 314   Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination
 315   address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
 316   'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
 317
 318 * ``macswap``: MAC swap forwarding mode.
 319   Swaps the source and the destination Ethernet addresses of packets before forwarding them.
 320
 321 * ``flowgen``: Multi-flow generation mode.
 322   Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
 323
 324 * ``rxonly``: Receives packets but doesn't transmit them.
 325
 326 * ``txonly``: Generates and transmits packets without receiving any.
 327
 328 * ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
 329
 330 * ``icmpecho``: Receives a burst of packets, lookup for IMCP echo requests and, if any, send back ICMP echo replies.
 331
 332 * ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=y``.
 333
 334 Note: TX timestamping is only available in the "Full Featured" TX path. To force ``testpmd`` into this mode set ``--txqflags=0``.
 335
 336 Example::
 337
 338    testpmd> set fwd rxonly
 339
 340    Set rxonly packet forwarding mode
 341
 342
 343 read rxd
 344 ~~~~~~~~
 345
 346 Display an RX descriptor for a port RX queue::
 347
 348    testpmd> read rxd (port_id) (queue_id) (rxd_id)
 349
 350 For example::
 351
 352    testpmd> read rxd 0 0 4
 353         0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
 354
 355 read txd
 356 ~~~~~~~~
 357
 358 Display a TX descriptor for a port TX queue::
 359
 360    testpmd> read txd (port_id) (queue_id) (txd_id)
 361
 362 For example::
 363
 364    testpmd> read txd 0 0 4
 365         0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
 366
 367 show vf stats
 368 ~~~~~~~~~~~~~
 369
 370 Display VF statistics::
 371
 372    testpmd> show vf stats (port_id) (vf_id)
 373
 374 clear vf stats
 375 ~~~~~~~~~~~~~~
 376
 377 Reset VF statistics::
 378
 379    testpmd> clear vf stats (port_id) (vf_id)
 380
 381 Configuration Functions
 382 -----------------------
 383
 384 The testpmd application can be configured from the runtime as well as from the command-line.
 385
 386 This section details the available configuration functions that are available.
 387
 388 .. note::
 389
 390    Configuration changes only become active when forwarding is started/restarted.
 391
 392 set default
 393 ~~~~~~~~~~~
 394
 395 Reset forwarding to the default configuration::
 396
 397    testpmd> set default
 398
 399 set verbose
 400 ~~~~~~~~~~~
 401
 402 Set the debug verbosity level::
 403
 404    testpmd> set verbose (level)
 405
 406 Currently the only available levels are 0 (silent except for error) and 1 (fully verbose).
 407
 408 set nbport
 409 ~~~~~~~~~~
 410
 411 Set the number of ports used by the application:
 412
 413 set nbport (num)
 414
 415 This is equivalent to the ``--nb-ports`` command-line option.
 416
 417 set nbcore
 418 ~~~~~~~~~~
 419
 420 Set the number of cores used by the application::
 421
 422    testpmd> set nbcore (num)
 423
 424 This is equivalent to the ``--nb-cores`` command-line option.
 425
 426 .. note::
 427
 428    The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
 429
 430 set coremask
 431 ~~~~~~~~~~~~
 432
 433 Set the forwarding cores hexadecimal mask::
 434
 435    testpmd> set coremask (mask)
 436
 437 This is equivalent to the ``--coremask`` command-line option.
 438
 439 .. note::
 440
 441    The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
 442
 443 set portmask
 444 ~~~~~~~~~~~~
 445
 446 Set the forwarding ports hexadecimal mask::
 447
 448    testpmd> set portmask (mask)
 449
 450 This is equivalent to the ``--portmask`` command-line option.
 451
 452 set burst
 453 ~~~~~~~~~
 454
 455 Set number of packets per burst::
 456
 457    testpmd> set burst (num)
 458
 459 This is equivalent to the ``--burst command-line`` option.
 460
 461 When retry is enabled, the transmit delay time and number of retries can also be set::
 462
 463    testpmd> set burst tx delay (microseconds) retry (num)
 464
 465 set txpkts
 466 ~~~~~~~~~~
 467
 468 Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
 469
 470    testpmd> set txpkts (x[,y]*)
 471
 472 Where x[,y]* represents a CSV list of values, without white space.
 473
 474 set txsplit
 475 ~~~~~~~~~~~
 476
 477 Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
 478
 479    testpmd> set txsplit (off|on|rand)
 480
 481 Where:
 482
 483 * ``off`` disable packet copy & split for CSUM mode.
 484
 485 * ``on`` split outgoing packet into multiple segments. Size of each segment
 486   and number of segments per packet is determined by ``set txpkts`` command
 487   (see above).
 488
 489 * ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
 490
 491 set corelist
 492 ~~~~~~~~~~~~
 493
 494 Set the list of forwarding cores::
 495
 496    testpmd> set corelist (x[,y]*)
 497
 498 For example, to change the forwarding cores:
 499
 500 .. code-block:: console
 501
 502    testpmd> set corelist 3,1
 503    testpmd> show config fwd
 504
 505    io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
 506    Logical Core 3 (socket 0) forwards packets on 1 streams:
 507    RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
 508    Logical Core 1 (socket 0) forwards packets on 1 streams:
 509    RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
 510
 511 .. note::
 512
 513    The cores are used in the same order as specified on the command line.
 514
 515 set portlist
 516 ~~~~~~~~~~~~
 517
 518 Set the list of forwarding ports::
 519
 520    testpmd> set portlist (x[,y]*)
 521
 522 For example, to change the port forwarding:
 523
 524 .. code-block:: console
 525
 526    testpmd> set portlist 0,2,1,3
 527    testpmd> show config fwd
 528
 529    io packet forwarding - ports=4 - cores=1 - streams=4
 530    Logical Core 3 (socket 0) forwards packets on 4 streams:
 531    RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
 532    RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
 533    RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
 534    RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
 535
 536 set tx loopback
 537 ~~~~~~~~~~~~~~~
 538
 539 Enable/disable tx loopback::
 540
 541    testpmd> set tx loopback (port_id) (on|off)
 542
 543 set drop enable
 544 ~~~~~~~~~~~~~~~
 545
 546 set drop enable bit for all queues::
 547
 548    testpmd> set all queues drop (port_id) (on|off)
 549
 550 set split drop enable (for VF)
 551 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 552
 553 set split drop enable bit for VF from PF::
 554
 555    testpmd> set vf split drop (port_id) (vf_id) (on|off)
 556
 557 set mac antispoof (for VF)
 558 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 559
 560 Set mac antispoof for a VF from the PF::
 561
 562    testpmd> set vf mac antispoof  (port_id) (vf_id) (on|off)
 563
 564 set macsec offload
 565 ~~~~~~~~~~~~~~~~~~
 566
 567 Enable/disable MACsec offload::
 568
 569    testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
 570    testpmd> set macsec offload (port_id) off
 571
 572 set macsec sc
 573 ~~~~~~~~~~~~~
 574
 575 Configure MACsec secure connection (SC)::
 576
 577    testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi)
 578
 579 .. note::
 580
 581    The pi argument is ignored for tx.
 582    Check the NIC Datasheet for hardware limits.
 583
 584 set macsec sa
 585 ~~~~~~~~~~~~~
 586
 587 Configure MACsec secure association (SA)::
 588
 589    testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
 590
 591 .. note::
 592
 593    The IDX value must be 0 or 1.
 594    Check the NIC Datasheet for hardware limits.
 595
 596 set broadcast mode (for VF)
 597 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 598
 599 Set broadcast mode for a VF from the PF::
 600
 601    testpmd> set vf broadcast (port_id) (vf_id) (on|off)
 602
 603 vlan set strip
 604 ~~~~~~~~~~~~~~
 605
 606 Set the VLAN strip on a port::
 607
 608    testpmd> vlan set strip (on|off) (port_id)
 609
 610 vlan set stripq
 611 ~~~~~~~~~~~~~~~
 612
 613 Set the VLAN strip for a queue on a port::
 614
 615    testpmd> vlan set stripq (on|off) (port_id,queue_id)
 616
 617 vlan set stripq (for VF)
 618 ~~~~~~~~~~~~~~~~~~~~~~~~
 619
 620 Set VLAN strip for all queues in a pool for a VF from the PF::
 621
 622    testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
 623
 624 vlan set insert (for VF)
 625 ~~~~~~~~~~~~~~~~~~~~~~~~
 626
 627 Set VLAN insert for a VF from the PF::
 628
 629    testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
 630
 631 vlan set tag (for VF)
 632 ~~~~~~~~~~~~~~~~~~~~~
 633
 634 Set VLAN tag for a VF from the PF::
 635
 636    testpmd> set vf vlan tag (port_id) (vf_id) (on|off)
 637
 638 vlan set antispoof (for VF)
 639 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 640
 641 Set VLAN antispoof for a VF from the PF::
 642
 643    testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
 644
 645 vlan set filter
 646 ~~~~~~~~~~~~~~~
 647
 648 Set the VLAN filter on a port::
 649
 650    testpmd> vlan set filter (on|off) (port_id)
 651
 652 vlan set qinq
 653 ~~~~~~~~~~~~~
 654
 655 Set the VLAN QinQ (extended queue in queue) on for a port::
 656
 657    testpmd> vlan set qinq (on|off) (port_id)
 658
 659 vlan set tpid
 660 ~~~~~~~~~~~~~
 661
 662 Set the inner or outer VLAN TPID for packet filtering on a port::
 663
 664    testpmd> vlan set (inner|outer) tpid (value) (port_id)
 665
 666 .. note::
 667
 668    TPID value must be a 16-bit number (value <= 65536).
 669
 670 rx_vlan add
 671 ~~~~~~~~~~~
 672
 673 Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
 674
 675    testpmd> rx_vlan add (vlan_id|all) (port_id)
 676
 677 .. note::
 678
 679    VLAN filter must be set on that port. VLAN ID < 4096.
 680    Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
 681    in VFTA table. This is important if enabling all vlan_ids.
 682
 683 rx_vlan rm
 684 ~~~~~~~~~~
 685
 686 Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
 687
 688    testpmd> rx_vlan rm (vlan_id|all) (port_id)
 689
 690 rx_vlan add (for VF)
 691 ~~~~~~~~~~~~~~~~~~~~
 692
 693 Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
 694
 695    testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
 696
 697 rx_vlan rm (for VF)
 698 ~~~~~~~~~~~~~~~~~~~
 699
 700 Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
 701
 702    testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
 703
 704 tunnel_filter add
 705 ~~~~~~~~~~~~~~~~~
 706
 707 Add a tunnel filter on a port::
 708
 709    testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \
 710             (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
 711             imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
 712
 713 The available information categories are:
 714
 715 * ``vxlan``: Set tunnel type as VXLAN.
 716
 717 * ``nvgre``: Set tunnel type as NVGRE.
 718
 719 * ``ipingre``: Set tunnel type as IP-in-GRE.
 720
 721 * ``imac-ivlan``: Set filter type as Inner MAC and VLAN.
 722
 723 * ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID.
 724
 725 * ``imac-tenid``: Set filter type as Inner MAC and tenant ID.
 726
 727 * ``imac``: Set filter type as Inner MAC.
 728
 729 * ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID.
 730
 731 * ``oip``: Set filter type as Outer IP.
 732
 733 * ``iip``: Set filter type as Inner IP.
 734
 735 Example::
 736
 737    testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \
 738             192.168.2.2 0 ipingre oip 1 1
 739
 740    Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP.
 741
 742 tunnel_filter remove
 743 ~~~~~~~~~~~~~~~~~~~~
 744
 745 Remove a tunnel filter on a port::
 746
 747    testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \
 748             (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
 749             imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
 750
 751 rx_vxlan_port add
 752 ~~~~~~~~~~~~~~~~~
 753
 754 Add an UDP port for VXLAN packet filter on a port::
 755
 756    testpmd> rx_vxlan_port add (udp_port) (port_id)
 757
 758 rx_vxlan_port remove
 759 ~~~~~~~~~~~~~~~~~~~~
 760
 761 Remove an UDP port for VXLAN packet filter on a port::
 762
 763    testpmd> rx_vxlan_port rm (udp_port) (port_id)
 764
 765 tx_vlan set
 766 ~~~~~~~~~~~
 767
 768 Set hardware insertion of VLAN IDs in packets sent on a port::
 769
 770    testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
 771
 772 For example, set a single VLAN ID (5) insertion on port 0::
 773
 774    tx_vlan set 0 5
 775
 776 Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
 777
 778    tx_vlan set 1 2 3
 779
 780
 781 tx_vlan set pvid
 782 ~~~~~~~~~~~~~~~~
 783
 784 Set port based hardware insertion of VLAN ID in packets sent on a port::
 785
 786    testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
 787
 788 tx_vlan reset
 789 ~~~~~~~~~~~~~
 790
 791 Disable hardware insertion of a VLAN header in packets sent on a port::
 792
 793    testpmd> tx_vlan reset (port_id)
 794
 795 csum set
 796 ~~~~~~~~
 797
 798 Select hardware or software calculation of the checksum when
 799 transmitting a packet using the ``csum`` forwarding engine::
 800
 801    testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)
 802
 803 Where:
 804
 805 * ``ip|udp|tcp|sctp`` always relate to  the inner layer.
 806
 807 * ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
 808   as a tunnel packet by the forwarding engine (vxlan, gre and ipip are
 809   supported). See also the ``csum parse-tunnel`` command.
 810
 811 .. note::
 812
 813    Check the NIC Datasheet for hardware limits.
 814
 815 csum parse-tunnel
 816 ~~~~~~~~~~~~~~~~~
 817
 818 Define how tunneled packets should be handled by the csum forward
 819 engine::
 820
 821    testpmd> csum parse-tunnel (on|off) (tx_port_id)
 822
 823 If enabled, the csum forward engine will try to recognize supported
 824 tunnel headers (vxlan, gre, ipip).
 825
 826 If disabled, treat tunnel packets as non-tunneled packets (a inner
 827 header is handled as a packet payload).
 828
 829 .. note::
 830
 831    The port argument is the TX port like in the ``csum set`` command.
 832
 833 Example:
 834
 835 Consider a packet in packet like the following::
 836
 837    eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
 838
 839 * If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
 840   command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
 841   ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``).
 842
 843 * If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum  set``
 844    command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
 845
 846 csum show
 847 ~~~~~~~~~
 848
 849 Display tx checksum offload configuration::
 850
 851    testpmd> csum show (port_id)
 852
 853 tso set
 854 ~~~~~~~
 855
 856 Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
 857
 858    testpmd> tso set (segsize) (port_id)
 859
 860 .. note::
 861
 862    Check the NIC datasheet for hardware limits.
 863
 864 tso show
 865 ~~~~~~~~
 866
 867 Display the status of TCP Segmentation Offload::
 868
 869    testpmd> tso show (port_id)
 870
 871 mac_addr add
 872 ~~~~~~~~~~~~
 873
 874 Add an alternative MAC address to a port::
 875
 876    testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
 877
 878 mac_addr remove
 879 ~~~~~~~~~~~~~~~
 880
 881 Remove a MAC address from a port::
 882
 883    testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
 884
 885 mac_addr add (for VF)
 886 ~~~~~~~~~~~~~~~~~~~~~
 887
 888 Add an alternative MAC address for a VF to a port::
 889
 890    testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
 891
 892 mac_addr set
 893 ~~~~~~~~~~~~
 894
 895 Set the default MAC address for a port::
 896
 897    testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX)
 898
 899 mac_addr set (for VF)
 900 ~~~~~~~~~~~~~~~~~~~~~
 901
 902 Set the MAC address for a VF from the PF::
 903
 904    testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
 905
 906 set port-uta
 907 ~~~~~~~~~~~~
 908
 909 Set the unicast hash filter(s) on/off for a port::
 910
 911    testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
 912
 913 set promisc
 914 ~~~~~~~~~~~
 915
 916 Set the promiscuous mode on for a port or for all ports.
 917 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
 918
 919    testpmd> set promisc (port_id|all) (on|off)
 920
 921 set allmulti
 922 ~~~~~~~~~~~~
 923
 924 Set the allmulti mode for a port or for all ports::
 925
 926    testpmd> set allmulti (port_id|all) (on|off)
 927
 928 Same as the ifconfig (8) option. Controls how multicast packets are handled.
 929
 930 set promisc (for VF)
 931 ~~~~~~~~~~~~~~~~~~~~
 932
 933 Set the unicast promiscuous mode for a VF from PF.
 934 It's supported by Intel i40e NICs now.
 935 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
 936
 937    testpmd> set vf promisc (port_id) (vf_id) (on|off)
 938
 939 set allmulticast (for VF)
 940 ~~~~~~~~~~~~~~~~~~~~~~~~~
 941
 942 Set the multicast promiscuous mode for a VF from PF.
 943 It's supported by Intel i40e NICs now.
 944 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
 945
 946    testpmd> set vf allmulti (port_id) (vf_id) (on|off)
 947
 948 set tx max bandwidth (for VF)
 949 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 950
 951 Set TX max absolute bandwidth (Mbps) for a VF from PF::
 952
 953    testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth)
 954
 955 set tc tx min bandwidth (for VF)
 956 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 957
 958 Set all TCs' TX min relative bandwidth (%) for a VF from PF::
 959
 960    testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...)
 961
 962 set tc tx max bandwidth (for VF)
 963 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 964
 965 Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF::
 966
 967    testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth)
 968
 969 set tc strict link priority mode
 970 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 971
 972 Set some TCs' strict link priority mode on a physical port::
 973
 974    testpmd> set tx strict-link-priority (port_id) (tc_bitmap)
 975
 976 set tc tx min bandwidth
 977 ~~~~~~~~~~~~~~~~~~~~~~~
 978
 979 Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs::
 980
 981    testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...)
 982
 983 set flow_ctrl rx
 984 ~~~~~~~~~~~~~~~~
 985
 986 Set the link flow control parameter on a port::
 987
 988    testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
 989             (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
 990             autoneg (on|off) (port_id)
 991
 992 Where:
 993
 994 * ``high_water`` (integer): High threshold value to trigger XOFF.
 995
 996 * ``low_water`` (integer): Low threshold value to trigger XON.
 997
 998 * ``pause_time`` (integer): Pause quota in the Pause frame.
 999
1000 * ``send_xon`` (0/1): Send XON frame.
1001
1002 * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
1003
1004 * ``autoneg``: Change the auto-negotiation parameter.
1005
1006 set pfc_ctrl rx
1007 ~~~~~~~~~~~~~~~
1008
1009 Set the priority flow control parameter on a port::
1010
1011    testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1012             (pause_time) (priority) (port_id)
1013
1014 Where:
1015
1016 * ``high_water`` (integer): High threshold value.
1017
1018 * ``low_water`` (integer): Low threshold value.
1019
1020 * ``pause_time`` (integer): Pause quota in the Pause frame.
1021
1022 * ``priority`` (0-7): VLAN User Priority.
1023
1024 set stat_qmap
1025 ~~~~~~~~~~~~~
1026
1027 Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
1028
1029    testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
1030
1031 For example, to set rx queue 2 on port 0 to mapping 5::
1032
1033    testpmd>set stat_qmap rx 0 2 5
1034
1035 set port - rx/tx (for VF)
1036 ~~~~~~~~~~~~~~~~~~~~~~~~~
1037
1038 Set VF receive/transmit from a port::
1039
1040    testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
1041
1042 set port - mac address filter (for VF)
1043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1044
1045 Add/Remove unicast or multicast MAC addr filter for a VF::
1046
1047    testpmd> set port (port_id) vf (vf_id) (mac_addr) \
1048             (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off)
1049
1050 set port - rx mode(for VF)
1051 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1052
1053 Set the VF receive mode of a port::
1054
1055    testpmd> set port (port_id) vf (vf_id) \
1056             rxmode (AUPE|ROPE|BAM|MPE) (on|off)
1057
1058 The available receive modes are:
1059
1060 * ``AUPE``: Accepts untagged VLAN.
1061
1062 * ``ROPE``: Accepts unicast hash.
1063
1064 * ``BAM``: Accepts broadcast packets.
1065
1066 * ``MPE``: Accepts all multicast packets.
1067
1068 set port - tx_rate (for Queue)
1069 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1070
1071 Set TX rate limitation for a queue on a port::
1072
1073    testpmd> set port (port_id) queue (queue_id) rate (rate_value)
1074
1075 set port - tx_rate (for VF)
1076 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1077
1078 Set TX rate limitation for queues in VF on a port::
1079
1080    testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
1081
1082 set port - mirror rule
1083 ~~~~~~~~~~~~~~~~~~~~~~
1084
1085 Set pool or vlan type mirror rule for a port::
1086
1087    testpmd> set port (port_id) mirror-rule (rule_id) \
1088             (pool-mirror-up|pool-mirror-down|vlan-mirror) \
1089             (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off)
1090
1091 Set link mirror rule for a port::
1092
1093    testpmd> set port (port_id) mirror-rule (rule_id) \
1094            (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off)
1095
1096 For example to enable mirror traffic with vlan 0,1 to pool 0::
1097
1098    set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on
1099
1100 reset port - mirror rule
1101 ~~~~~~~~~~~~~~~~~~~~~~~~
1102
1103 Reset a mirror rule for a port::
1104
1105    testpmd> reset port (port_id) mirror-rule (rule_id)
1106
1107 set flush_rx
1108 ~~~~~~~~~~~~
1109
1110 Set the flush on RX streams before forwarding.
1111 The default is flush ``on``.
1112 Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
1113
1114    testpmd> set flush_rx off
1115
1116 set bypass mode
1117 ~~~~~~~~~~~~~~~
1118
1119 Set the bypass mode for the lowest port on bypass enabled NIC::
1120
1121    testpmd> set bypass mode (normal|bypass|isolate) (port_id)
1122
1123 set bypass event
1124 ~~~~~~~~~~~~~~~~
1125
1126 Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
1127
1128    testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
1129             mode (normal|bypass|isolate) (port_id)
1130
1131 Where:
1132
1133 * ``timeout``: Enable bypass after watchdog timeout.
1134
1135 * ``os_on``: Enable bypass when OS/board is powered on.
1136
1137 * ``os_off``: Enable bypass when OS/board is powered off.
1138
1139 * ``power_on``: Enable bypass when power supply is turned on.
1140
1141 * ``power_off``: Enable bypass when power supply is turned off.
1142
1143
1144 set bypass timeout
1145 ~~~~~~~~~~~~~~~~~~
1146
1147 Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
1148
1149    testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
1150
1151 show bypass config
1152 ~~~~~~~~~~~~~~~~~~
1153
1154 Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
1155
1156    testpmd> show bypass config (port_id)
1157
1158 set link up
1159 ~~~~~~~~~~~
1160
1161 Set link up for a port::
1162
1163    testpmd> set link-up port (port id)
1164
1165 set link down
1166 ~~~~~~~~~~~~~
1167
1168 Set link down for a port::
1169
1170    testpmd> set link-down port (port id)
1171
1172 E-tag set
1173 ~~~~~~~~~
1174
1175 Enable E-tag insertion for a VF on a port::
1176
1177    testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1178
1179 Disable E-tag insertion for a VF on a port::
1180
1181    testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1182
1183 Enable/disable E-tag stripping on a port::
1184
1185    testpmd> E-tag set stripping (on|off) port (port_id)
1186
1187 Enable/disable E-tag based forwarding on a port::
1188
1189    testpmd> E-tag set forwarding (on|off) port (port_id)
1190
1191 Add an E-tag forwarding filter on a port::
1192
1193    testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id)
1194
1195 Delete an E-tag forwarding filter on a port::
1196    testpmd> E-tag set filter del e-tag-id (value) port (port_id)
1197
1198 ptype mapping
1199 ~~~~~~~~~~~~~
1200
1201 List all items from the ptype mapping table::
1202
1203    testpmd> ptype mapping get (port_id) (valid_only)
1204
1205 Where:
1206
1207 * ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0).
1208
1209 Replace a specific or a group of software defined ptype with a new one::
1210
1211    testpmd> ptype mapping replace  (port_id) (target) (mask) (pkt_type)
1212
1213 where:
1214
1215 * ``target``: A specific software ptype or a mask to represent a group of software ptypes.
1216
1217 * ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1).
1218
1219 * ``pkt_type``: The new software ptype to replace the old ones.
1220
1221 Update hardware defined ptype to software defined packet type mapping table::
1222
1223    testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype)
1224
1225 where:
1226
1227 * ``hw_ptype``: hardware ptype as the index of the ptype mapping table.
1228
1229 * ``sw_ptype``: software ptype as the value of the ptype mapping table.
1230
1231 Reset ptype mapping table::
1232
1233    testpmd> ptype mapping reset (port_id)
1234
1235 Port Functions
1236 --------------
1237
1238 The following sections show functions for configuring ports.
1239
1240 .. note::
1241
1242    Port configuration changes only become active when forwarding is started/restarted.
1243
1244 port attach
1245 ~~~~~~~~~~~
1246
1247 Attach a port specified by pci address or virtual device args::
1248
1249    testpmd> port attach (identifier)
1250
1251 To attach a new pci device, the device should be recognized by kernel first.
1252 Then it should be moved under DPDK management.
1253 Finally the port can be attached to testpmd.
1254
1255 For example, to move a pci device using ixgbe under DPDK management:
1256
1257 .. code-block:: console
1258
1259    # Check the status of the available devices.
1260    ./usertools/dpdk-devbind.py --status
1261
1262    Network devices using DPDK-compatible driver
1263    ============================================
1264    <none>
1265
1266    Network devices using kernel driver
1267    ===================================
1268    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
1269
1270
1271    # Bind the device to igb_uio.
1272    sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
1273
1274
1275    # Recheck the status of the devices.
1276    ./usertools/dpdk-devbind.py --status
1277    Network devices using DPDK-compatible driver
1278    ============================================
1279    0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
1280
1281 To attach a port created by virtual device, above steps are not needed.
1282
1283 For example, to attach a port whose pci address is 0000:0a:00.0.
1284
1285 .. code-block:: console
1286
1287    testpmd> port attach 0000:0a:00.0
1288    Attaching a new port...
1289    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1290    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
1291    EAL:   PCI memory mapped at 0x7f83bfa00000
1292    EAL:   PCI memory mapped at 0x7f83bfa80000
1293    PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
1294    PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
1295    Port 0 is attached. Now total ports is 1
1296    Done
1297
1298 For example, to attach a port created by pcap PMD.
1299
1300 .. code-block:: console
1301
1302    testpmd> port attach net_pcap0
1303    Attaching a new port...
1304    PMD: Initializing pmd_pcap for net_pcap0
1305    PMD: Creating pcap-backed ethdev on numa socket 0
1306    Port 0 is attached. Now total ports is 1
1307    Done
1308
1309 In this case, identifier is ``net_pcap0``.
1310 This identifier format is the same as ``--vdev`` format of DPDK applications.
1311
1312 For example, to re-attach a bonded port which has been previously detached,
1313 the mode and slave parameters must be given.
1314
1315 .. code-block:: console
1316
1317    testpmd> port attach net_bond_0,mode=0,slave=1
1318    Attaching a new port...
1319    EAL: Initializing pmd_bond for net_bond_0
1320    EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
1321    Port 0 is attached. Now total ports is 1
1322    Done
1323
1324
1325 port detach
1326 ~~~~~~~~~~~
1327
1328 Detach a specific port::
1329
1330    testpmd> port detach (port_id)
1331
1332 Before detaching a port, the port should be stopped and closed.
1333
1334 For example, to detach a pci device port 0.
1335
1336 .. code-block:: console
1337
1338    testpmd> port stop 0
1339    Stopping ports...
1340    Done
1341    testpmd> port close 0
1342    Closing ports...
1343    Done
1344
1345    testpmd> port detach 0
1346    Detaching a port...
1347    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1348    EAL:   remove driver: 8086:10fb rte_ixgbe_pmd
1349    EAL:   PCI memory unmapped at 0x7f83bfa00000
1350    EAL:   PCI memory unmapped at 0x7f83bfa80000
1351    Done
1352
1353
1354 For example, to detach a virtual device port 0.
1355
1356 .. code-block:: console
1357
1358    testpmd> port stop 0
1359    Stopping ports...
1360    Done
1361    testpmd> port close 0
1362    Closing ports...
1363    Done
1364
1365    testpmd> port detach 0
1366    Detaching a port...
1367    PMD: Closing pcap ethdev on numa socket 0
1368    Port 'net_pcap0' is detached. Now total ports is 0
1369    Done
1370
1371 To remove a pci device completely from the system, first detach the port from testpmd.
1372 Then the device should be moved under kernel management.
1373 Finally the device can be removed using kernel pci hotplug functionality.
1374
1375 For example, to move a pci device under kernel management:
1376
1377 .. code-block:: console
1378
1379    sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
1380
1381    ./usertools/dpdk-devbind.py --status
1382
1383    Network devices using DPDK-compatible driver
1384    ============================================
1385    <none>
1386
1387    Network devices using kernel driver
1388    ===================================
1389    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
1390
1391 To remove a port created by a virtual device, above steps are not needed.
1392
1393 port start
1394 ~~~~~~~~~~
1395
1396 Start all ports or a specific port::
1397
1398    testpmd> port start (port_id|all)
1399
1400 port stop
1401 ~~~~~~~~~
1402
1403 Stop all ports or a specific port::
1404
1405    testpmd> port stop (port_id|all)
1406
1407 port close
1408 ~~~~~~~~~~
1409
1410 Close all ports or a specific port::
1411
1412    testpmd> port close (port_id|all)
1413
1414 port start/stop queue
1415 ~~~~~~~~~~~~~~~~~~~~~
1416
1417 Start/stop a rx/tx queue on a specific port::
1418
1419    testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
1420
1421 Only take effect when port is started.
1422
1423 port config - speed
1424 ~~~~~~~~~~~~~~~~~~~
1425
1426 Set the speed and duplex mode for all ports or a specific port::
1427
1428    testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \
1429             duplex (half|full|auto)
1430
1431 port config - queues/descriptors
1432 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1433
1434 Set number of queues/descriptors for rxq, txq, rxd and txd::
1435
1436    testpmd> port config all (rxq|txq|rxd|txd) (value)
1437
1438 This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
1439
1440 port config - max-pkt-len
1441 ~~~~~~~~~~~~~~~~~~~~~~~~~
1442
1443 Set the maximum packet length::
1444
1445    testpmd> port config all max-pkt-len (value)
1446
1447 This is equivalent to the ``--max-pkt-len`` command-line option.
1448
1449 port config - CRC Strip
1450 ~~~~~~~~~~~~~~~~~~~~~~~
1451
1452 Set hardware CRC stripping on or off for all ports::
1453
1454    testpmd> port config all crc-strip (on|off)
1455
1456 CRC stripping is on by default.
1457
1458 The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option.
1459
1460 port config - scatter
1461 ~~~~~~~~~~~~~~~~~~~~~~~
1462
1463 Set RX scatter mode on or off for all ports::
1464
1465    testpmd> port config all scatter (on|off)
1466
1467 RX scatter mode is off by default.
1468
1469 The ``on`` option is equivalent to the ``--enable-scatter`` command-line option.
1470
1471 port config - TX queue flags
1472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1473
1474 Set a hexadecimal bitmap of TX queue flags for all ports::
1475
1476    testpmd> port config all txqflags value
1477
1478 This command is equivalent to the ``--txqflags`` command-line option.
1479
1480 port config - RX Checksum
1481 ~~~~~~~~~~~~~~~~~~~~~~~~~
1482
1483 Set hardware RX checksum offload to on or off for all ports::
1484
1485    testpmd> port config all rx-cksum (on|off)
1486
1487 Checksum offload is off by default.
1488
1489 The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option.
1490
1491 port config - VLAN
1492 ~~~~~~~~~~~~~~~~~~
1493
1494 Set hardware VLAN on or off for all ports::
1495
1496    testpmd> port config all hw-vlan (on|off)
1497
1498 Hardware VLAN is on by default.
1499
1500 The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option.
1501
1502 port config - VLAN filter
1503 ~~~~~~~~~~~~~~~~~~~~~~~~~
1504
1505 Set hardware VLAN filter on or off for all ports::
1506
1507    testpmd> port config all hw-vlan-filter (on|off)
1508
1509 Hardware VLAN filter is on by default.
1510
1511 The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option.
1512
1513 port config - VLAN strip
1514 ~~~~~~~~~~~~~~~~~~~~~~~~
1515
1516 Set hardware VLAN strip on or off for all ports::
1517
1518    testpmd> port config all hw-vlan-strip (on|off)
1519
1520 Hardware VLAN strip is on by default.
1521
1522 The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option.
1523
1524 port config - VLAN extend
1525 ~~~~~~~~~~~~~~~~~~~~~~~~~
1526
1527 Set hardware VLAN extend on or off for all ports::
1528
1529    testpmd> port config all hw-vlan-extend (on|off)
1530
1531 Hardware VLAN extend is off by default.
1532
1533 The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option.
1534
1535 port config - Drop Packets
1536 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1537
1538 Set packet drop for packets with no descriptors on or off for all ports::
1539
1540    testpmd> port config all drop-en (on|off)
1541
1542 Packet dropping for packets with no descriptors is off by default.
1543
1544 The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
1545
1546 port config - RSS
1547 ~~~~~~~~~~~~~~~~~
1548
1549 Set the RSS (Receive Side Scaling) mode on or off::
1550
1551    testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none)
1552
1553 RSS is on by default.
1554
1555 The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
1556
1557 port config - RSS Reta
1558 ~~~~~~~~~~~~~~~~~~~~~~
1559
1560 Set the RSS (Receive Side Scaling) redirection table::
1561
1562    testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
1563
1564 port config - DCB
1565 ~~~~~~~~~~~~~~~~~
1566
1567 Set the DCB mode for an individual port::
1568
1569    testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
1570
1571 The traffic class should be 4 or 8.
1572
1573 port config - Burst
1574 ~~~~~~~~~~~~~~~~~~~
1575
1576 Set the number of packets per burst::
1577
1578    testpmd> port config all burst (value)
1579
1580 This is equivalent to the ``--burst`` command-line option.
1581
1582 port config - Threshold
1583 ~~~~~~~~~~~~~~~~~~~~~~~
1584
1585 Set thresholds for TX/RX queues::
1586
1587    testpmd> port config all (threshold) (value)
1588
1589 Where the threshold type can be:
1590
1591 * ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
1592
1593 * ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
1594
1595 * ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
1596
1597 * ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
1598
1599 * ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
1600
1601 * ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
1602
1603 * ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
1604
1605 * ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
1606
1607 * ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
1608
1609 These threshold options are also available from the command-line.
1610
1611 port config - E-tag
1612 ~~~~~~~~~~~~~~~~~~~
1613
1614 Set the value of ether-type for E-tag::
1615
1616    testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value)
1617
1618 Enable/disable the E-tag support::
1619
1620    testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable)
1621
1622
1623 Link Bonding Functions
1624 ----------------------
1625
1626 The Link Bonding functions make it possible to dynamically create and
1627 manage link bonding devices from within testpmd interactive prompt.
1628
1629 create bonded device
1630 ~~~~~~~~~~~~~~~~~~~~
1631
1632 Create a new bonding device::
1633
1634    testpmd> create bonded device (mode) (socket)
1635
1636 For example, to create a bonded device in mode 1 on socket 0::
1637
1638    testpmd> create bonded 1 0
1639    created new bonded device (port X)
1640
1641 add bonding slave
1642 ~~~~~~~~~~~~~~~~~
1643
1644 Adds Ethernet device to a Link Bonding device::
1645
1646    testpmd> add bonding slave (slave id) (port id)
1647
1648 For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
1649
1650    testpmd> add bonding slave 6 10
1651
1652
1653 remove bonding slave
1654 ~~~~~~~~~~~~~~~~~~~~
1655
1656 Removes an Ethernet slave device from a Link Bonding device::
1657
1658    testpmd> remove bonding slave (slave id) (port id)
1659
1660 For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
1661
1662    testpmd> remove bonding slave 6 10
1663
1664 set bonding mode
1665 ~~~~~~~~~~~~~~~~
1666
1667 Set the Link Bonding mode of a Link Bonding device::
1668
1669    testpmd> set bonding mode (value) (port id)
1670
1671 For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
1672
1673    testpmd> set bonding mode 3 10
1674
1675 set bonding primary
1676 ~~~~~~~~~~~~~~~~~~~
1677
1678 Set an Ethernet slave device as the primary device on a Link Bonding device::
1679
1680    testpmd> set bonding primary (slave id) (port id)
1681
1682 For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
1683
1684    testpmd> set bonding primary 6 10
1685
1686 set bonding mac
1687 ~~~~~~~~~~~~~~~
1688
1689 Set the MAC address of a Link Bonding device::
1690
1691    testpmd> set bonding mac (port id) (mac)
1692
1693 For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
1694
1695    testpmd> set bonding mac 10 00:00:00:00:00:01
1696
1697 set bonding xmit_balance_policy
1698 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1699
1700 Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
1701
1702    testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34)
1703
1704 For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
1705
1706    testpmd> set bonding xmit_balance_policy 10 l34
1707
1708
1709 set bonding mon_period
1710 ~~~~~~~~~~~~~~~~~~~~~~
1711
1712 Set the link status monitoring polling period in milliseconds for a bonding device.
1713
1714 This adds support for PMD slave devices which do not support link status interrupts.
1715 When the mon_period is set to a value greater than 0 then all PMD's which do not support
1716 link status ISR will be queried every polling interval to check if their link status has changed::
1717
1718    testpmd> set bonding mon_period (port_id) (value)
1719
1720 For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
1721
1722    testpmd> set bonding mon_period 5 150
1723
1724
1725 show bonding config
1726 ~~~~~~~~~~~~~~~~~~~
1727
1728 Show the current configuration of a Link Bonding device::
1729
1730    testpmd> show bonding config (port id)
1731
1732 For example,
1733 to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
1734 in balance mode with a transmission policy of layer 2+3::
1735
1736    testpmd> show bonding config 9
1737         Bonding mode: 2
1738         Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
1739         Slaves (3): [1 3 4]
1740         Active Slaves (3): [1 3 4]
1741         Primary: [3]
1742
1743
1744 Register Functions
1745 ------------------
1746
1747 The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
1748 This is mainly useful for debugging purposes.
1749 Reference should be made to the appropriate datasheet for the network card for details on the register addresses
1750 and fields that can be accessed.
1751
1752 read reg
1753 ~~~~~~~~
1754
1755 Display the value of a port register::
1756
1757    testpmd> read reg (port_id) (address)
1758
1759 For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
1760
1761    testpmd> read reg 0 0xEE00
1762    port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
1763
1764 read regfield
1765 ~~~~~~~~~~~~~
1766
1767 Display a port register bit field::
1768
1769    testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
1770
1771 For example, reading the lowest two bits from the register in the example above::
1772
1773    testpmd> read regfield 0 0xEE00 0 1
1774    port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
1775
1776 read regbit
1777 ~~~~~~~~~~~
1778
1779 Display a single port register bit::
1780
1781    testpmd> read regbit (port_id) (address) (bit_x)
1782
1783 For example, reading the lowest bit from the register in the example above::
1784
1785    testpmd> read regbit 0 0xEE00 0
1786    port 0 PCI register at offset 0xEE00: bit 0=1
1787
1788 write reg
1789 ~~~~~~~~~
1790
1791 Set the value of a port register::
1792
1793    testpmd> write reg (port_id) (address) (value)
1794
1795 For example, to clear a register::
1796
1797    testpmd> write reg 0 0xEE00 0x0
1798    port 0 PCI register at offset 0xEE00: 0x00000000 (0)
1799
1800 write regfield
1801 ~~~~~~~~~~~~~~
1802
1803 Set bit field of a port register::
1804
1805    testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
1806
1807 For example, writing to the register cleared in the example above::
1808
1809    testpmd> write regfield 0 0xEE00 0 1 2
1810    port 0 PCI register at offset 0xEE00: 0x00000002 (2)
1811
1812 write regbit
1813 ~~~~~~~~~~~~
1814
1815 Set single bit value of a port register::
1816
1817    testpmd> write regbit (port_id) (address) (bit_x) (value)
1818
1819 For example, to set the high bit in the register from the example above::
1820
1821    testpmd> write regbit 0 0xEE00 31 1
1822    port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
1823
1824
1825 Filter Functions
1826 ----------------
1827
1828 This section details the available filter functions that are available.
1829
1830 Note these functions interface the deprecated legacy filtering framework,
1831 superseded by *rte_flow*. See `Flow rules management`_.
1832
1833 ethertype_filter
1834 ~~~~~~~~~~~~~~~~~~~~
1835
1836 Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue::
1837
1838    ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \
1839                     ethertype (ether_type) (drop|fwd) queue (queue_id)
1840
1841 The available information parameters are:
1842
1843 * ``port_id``: The port which the Ethertype filter assigned on.
1844
1845 * ``mac_addr``: Compare destination mac address.
1846
1847 * ``mac_ignr``: Ignore destination mac address match.
1848
1849 * ``mac_address``: Destination mac address to match.
1850
1851 * ``ether_type``: The EtherType value want to match,
1852   for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid.
1853
1854 * ``queue_id``: The receive queue associated with this EtherType filter.
1855   It is meaningless when deleting or dropping.
1856
1857 Example, to add/remove an ethertype filter rule::
1858
1859    testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \
1860                              ethertype 0x0806 fwd queue 3
1861
1862    testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \
1863                              ethertype 0x0806 fwd queue 3
1864
1865 2tuple_filter
1866 ~~~~~~~~~~~~~~~~~
1867
1868 Add or delete a 2-tuple filter,
1869 which identifies packets by specific protocol and destination TCP/UDP port
1870 and forwards packets into one of the receive queues::
1871
1872    2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \
1873                  protocol (protocol_value) mask (mask_value) \
1874                  tcp_flags (tcp_flags_value) priority (prio_value) \
1875                  queue (queue_id)
1876
1877 The available information parameters are:
1878
1879 * ``port_id``: The port which the 2-tuple filter assigned on.
1880
1881 * ``dst_port_value``: Destination port in L4.
1882
1883 * ``protocol_value``: IP L4 protocol.
1884
1885 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate.
1886
1887 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP).
1888
1889 * ``prio_value``: Priority of this filter.
1890
1891 * ``queue_id``: The receive queue associated with this 2-tuple filter.
1892
1893 Example, to add/remove an 2tuple filter rule::
1894
1895    testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \
1896                           tcp_flags 0x02 priority 3 queue 3
1897
1898    testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \
1899                           tcp_flags 0x02 priority 3 queue 3
1900
1901 5tuple_filter
1902 ~~~~~~~~~~~~~~~~~
1903
1904 Add or delete a 5-tuple filter,
1905 which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port)
1906 and routes packets into one of the receive queues::
1907
1908    5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \
1909                  (src_address) dst_port (dst_port_value) \
1910                  src_port (src_port_value) protocol (protocol_value) \
1911                  mask (mask_value) tcp_flags (tcp_flags_value) \
1912                  priority (prio_value) queue (queue_id)
1913
1914 The available information parameters are:
1915
1916 * ``port_id``: The port which the 5-tuple filter assigned on.
1917
1918 * ``dst_address``: Destination IP address.
1919
1920 * ``src_address``: Source IP address.
1921
1922 * ``dst_port_value``: TCP/UDP destination port.
1923
1924 * ``src_port_value``: TCP/UDP source port.
1925
1926 * ``protocol_value``: L4 protocol.
1927
1928 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate
1929
1930 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP).
1931
1932 * ``prio_value``: The priority of this filter.
1933
1934 * ``queue_id``: The receive queue associated with this 5-tuple filter.
1935
1936 Example, to add/remove an 5tuple filter rule::
1937
1938    testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1939             dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1940             flags 0x0 priority 3 queue 3
1941
1942    testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1943             dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1944             flags 0x0 priority 3 queue 3
1945
1946 syn_filter
1947 ~~~~~~~~~~
1948
1949 Using the  SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue::
1950
1951    syn_filter (port_id) (add|del) priority (high|low) queue (queue_id)
1952
1953 The available information parameters are:
1954
1955 * ``port_id``: The port which the SYN filter assigned on.
1956
1957 * ``high``: This SYN filter has higher priority than other filters.
1958
1959 * ``low``: This SYN filter has lower priority than other filters.
1960
1961 * ``queue_id``: The receive queue associated with this SYN filter
1962
1963 Example::
1964
1965    testpmd> syn_filter 0 add priority high queue 3
1966
1967 flex_filter
1968 ~~~~~~~~~~~
1969
1970 With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet
1971 and routed into one of the receive queues::
1972
1973    flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \
1974                mask (mask_value) priority (prio_value) queue (queue_id)
1975
1976 The available information parameters are:
1977
1978 * ``port_id``: The port which the Flex filter is assigned on.
1979
1980 * ``len_value``: Filter length in bytes, no greater than 128.
1981
1982 * ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match.
1983
1984 * ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match.
1985
1986 * ``prio_value``: The priority of this filter.
1987
1988 * ``queue_id``: The receive queue associated with this Flex filter.
1989
1990 Example::
1991
1992    testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \
1993                           mask 000C priority 3 queue 3
1994
1995    testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \
1996                           mask 000C priority 3 queue 3
1997
1998
1999 .. _testpmd_flow_director:
2000
2001 flow_director_filter
2002 ~~~~~~~~~~~~~~~~~~~~
2003
2004 The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues.
2005
2006 Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and
2007 Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter:
2008
2009 * Perfect match filters.
2010   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2011   The masked fields are for IP flow.
2012
2013 * Signature filters.
2014   The hardware checks a match between a hash-based signature of the masked fields of the received packet.
2015
2016 * Perfect-mac-vlan match filters.
2017   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2018   The masked fields are for MAC VLAN flow.
2019
2020 * Perfect-tunnel match filters.
2021   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2022   The masked fields are for tunnel flow.
2023
2024 The Flow Director filters can match the different fields for different type of packet: flow type, specific input set
2025 per flow type and the flexible payload.
2026
2027 The Flow Director can also mask out parts of all of these fields so that filters
2028 are only applied to certain fields or parts of the fields.
2029
2030 Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information.
2031
2032 # Commands to add flow director filters of different flow types::
2033
2034    flow_director_filter (port_id) mode IP (add|del|update) \
2035                         flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \
2036                         src (src_ip_address) dst (dst_ip_address) \
2037                         tos (tos_value) proto (proto_value) ttl (ttl_value) \
2038                         vlan (vlan_value) flexbytes (flexbytes_value) \
2039                         (drop|fwd) pf|vf(vf_id) queue (queue_id) \
2040                         fd_id (fd_id_value)
2041
2042    flow_director_filter (port_id) mode IP (add|del|update) \
2043                         flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \
2044                         src (src_ip_address) (src_port) \
2045                         dst (dst_ip_address) (dst_port) \
2046                         tos (tos_value) ttl (ttl_value) \
2047                         vlan (vlan_value) flexbytes (flexbytes_value) \
2048                         (drop|fwd) queue pf|vf(vf_id) (queue_id) \
2049                         fd_id (fd_id_value)
2050
2051    flow_director_filter (port_id) mode IP (add|del|update) \
2052                         flow (ipv4-sctp|ipv6-sctp) \
2053                         src (src_ip_address) (src_port) \
2054                         dst (dst_ip_address) (dst_port) \
2055                         tos (tos_value) ttl (ttl_value) \
2056                         tag (verification_tag) vlan (vlan_value) \
2057                         flexbytes (flexbytes_value) (drop|fwd) \
2058                         pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value)
2059
2060    flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \
2061                         ether (ethertype) flexbytes (flexbytes_value) \
2062                         (drop|fwd) pf|vf(vf_id) queue (queue_id)
2063                         fd_id (fd_id_value)
2064
2065    flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \
2066                         mac (mac_address) vlan (vlan_value) \
2067                         flexbytes (flexbytes_value) (drop|fwd) \
2068                         queue (queue_id) fd_id (fd_id_value)
2069
2070    flow_director_filter (port_id) mode Tunnel (add|del|update) \
2071                         mac (mac_address) vlan (vlan_value) \
2072                         tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \
2073                         flexbytes (flexbytes_value) (drop|fwd) \
2074                         queue (queue_id) fd_id (fd_id_value)
2075
2076 For example, to add an ipv4-udp flow type filter::
2077
2078    testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \
2079             dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \
2080             fwd pf queue 1 fd_id 1
2081
2082 For example, add an ipv4-other flow type filter::
2083
2084    testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \
2085              dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \
2086              flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1
2087
2088 flush_flow_director
2089 ~~~~~~~~~~~~~~~~~~~
2090
2091 Flush all flow director filters on a device::
2092
2093    testpmd> flush_flow_director (port_id)
2094
2095 Example, to flush all flow director filter on port 0::
2096
2097    testpmd> flush_flow_director 0
2098
2099 flow_director_mask
2100 ~~~~~~~~~~~~~~~~~~
2101
2102 Set flow director's input masks::
2103
2104    flow_director_mask (port_id) mode IP vlan (vlan_value) \
2105                       src_mask (ipv4_src) (ipv6_src) (src_port) \
2106                       dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
2107
2108    flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
2109
2110    flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
2111                       mac (mac_value) tunnel-type (tunnel_type_value) \
2112                       tunnel-id (tunnel_id_value)
2113
2114 Example, to set flow director mask on port 0::
2115
2116    testpmd> flow_director_mask 0 mode IP vlan 0xefff \
2117             src_mask 255.255.255.255 \
2118                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
2119             dst_mask 255.255.255.255 \
2120                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
2121
2122 flow_director_flex_mask
2123 ~~~~~~~~~~~~~~~~~~~~~~~
2124
2125 set masks of flow director's flexible payload based on certain flow type::
2126
2127    testpmd> flow_director_flex_mask (port_id) \
2128             flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2129                   ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \
2130                   l2_payload|all) (mask)
2131
2132 Example, to set flow director's flex mask for all flow type on port 0::
2133
2134    testpmd> flow_director_flex_mask 0 flow all \
2135             (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0)
2136
2137
2138 flow_director_flex_payload
2139 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2140
2141 Configure flexible payload selection::
2142
2143    flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
2144
2145 For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
2146
2147    testpmd> flow_director_flex_payload 0 l4 \
2148             (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
2149
2150 get_sym_hash_ena_per_port
2151 ~~~~~~~~~~~~~~~~~~~~~~~~~
2152
2153 Get symmetric hash enable configuration per port::
2154
2155    get_sym_hash_ena_per_port (port_id)
2156
2157 For example, to get symmetric hash enable configuration of port 1::
2158
2159    testpmd> get_sym_hash_ena_per_port 1
2160
2161 set_sym_hash_ena_per_port
2162 ~~~~~~~~~~~~~~~~~~~~~~~~~
2163
2164 Set symmetric hash enable configuration per port to enable or disable::
2165
2166    set_sym_hash_ena_per_port (port_id) (enable|disable)
2167
2168 For example, to set symmetric hash enable configuration of port 1 to enable::
2169
2170    testpmd> set_sym_hash_ena_per_port 1 enable
2171
2172 get_hash_global_config
2173 ~~~~~~~~~~~~~~~~~~~~~~
2174
2175 Get the global configurations of hash filters::
2176
2177    get_hash_global_config (port_id)
2178
2179 For example, to get the global configurations of hash filters of port 1::
2180
2181    testpmd> get_hash_global_config 1
2182
2183 set_hash_global_config
2184 ~~~~~~~~~~~~~~~~~~~~~~
2185
2186 Set the global configurations of hash filters::
2187
2188    set_hash_global_config (port_id) (toeplitz|simple_xor|default) \
2189    (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \
2190    ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \
2191    (enable|disable)
2192
2193 For example, to enable simple_xor for flow type of ipv6 on port 2::
2194
2195    testpmd> set_hash_global_config 2 simple_xor ipv6 enable
2196
2197 set_hash_input_set
2198 ~~~~~~~~~~~~~~~~~~
2199
2200 Set the input set for hash::
2201
2202    set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2203    ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2204    l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2205    ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \
2206    tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \
2207    udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \
2208    fld-8th|none) (select|add)
2209
2210 For example, to add source IP to hash input set for flow type of ipv4-udp on port 0::
2211
2212    testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add
2213
2214 set_fdir_input_set
2215 ~~~~~~~~~~~~~~~~~~
2216
2217 The Flow Director filters can match the different fields for different type of packet, i.e. specific input set
2218 on per flow type and the flexible payload. This command can be used to change input set for each flow type.
2219
2220 Set the input set for flow director::
2221
2222    set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2223    ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2224    l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2225    ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \
2226    tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \
2227    sctp-dst-port|sctp-veri-tag|none) (select|add)
2228
2229 For example to add source IP to FD input set for flow type of ipv4-udp on port 0::
2230
2231    testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add
2232
2233 global_config
2234 ~~~~~~~~~~~~~
2235
2236 Set different GRE key length for input set::
2237
2238    global_config (port_id) gre-key-len (number in bytes)
2239
2240 For example to set GRE key length for input set to 4 bytes on port 0::
2241
2242    testpmd> global_config 0 gre-key-len 4
2243
2244
2245 .. _testpmd_rte_flow:
2246
2247 Flow rules management
2248 ---------------------
2249
2250 Control of the generic flow API (*rte_flow*) is fully exposed through the
2251 ``flow`` command (validation, creation, destruction and queries).
2252
2253 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
2254 features simultaneously may cause undefined side-effects and is therefore
2255 not recommended.
2256
2257 ``flow`` syntax
2258 ~~~~~~~~~~~~~~~
2259
2260 Because the ``flow`` command uses dynamic tokens to handle the large number
2261 of possible flow rules combinations, its behavior differs slightly from
2262 other commands, in particular:
2263
2264 - Pressing *?* or the *<tab>* key displays contextual help for the current
2265   token, not that of the entire command.
2266
2267 - Optional and repeated parameters are supported (provided they are listed
2268   in the contextual help).
2269
2270 The first parameter stands for the operation mode. Possible operations and
2271 their general syntax are described below. They are covered in detail in the
2272 following sections.
2273
2274 - Check whether a flow rule can be created::
2275
2276    flow validate {port_id}
2277        [group {group_id}] [priority {level}] [ingress] [egress]
2278        pattern {item} [/ {item} [...]] / end
2279        actions {action} [/ {action} [...]] / end
2280
2281 - Create a flow rule::
2282
2283    flow create {port_id}
2284        [group {group_id}] [priority {level}] [ingress] [egress]
2285        pattern {item} [/ {item} [...]] / end
2286        actions {action} [/ {action} [...]] / end
2287
2288 - Destroy specific flow rules::
2289
2290    flow destroy {port_id} rule {rule_id} [...]
2291
2292 - Destroy all flow rules::
2293
2294    flow flush {port_id}
2295
2296 - Query an existing flow rule::
2297
2298    flow query {port_id} {rule_id} {action}
2299
2300 - List existing flow rules sorted by priority, filtered by group
2301   identifiers::
2302
2303    flow list {port_id} [group {group_id}] [...]
2304
2305 Validating flow rules
2306 ~~~~~~~~~~~~~~~~~~~~~
2307
2308 ``flow validate`` reports whether a flow rule would be accepted by the
2309 underlying device in its current state but stops short of creating it. It is
2310 bound to ``rte_flow_validate()``::
2311
2312    flow validate {port_id}
2313       [group {group_id}] [priority {level}] [ingress] [egress]
2314       pattern {item} [/ {item} [...]] / end
2315       actions {action} [/ {action} [...]] / end
2316
2317 If successful, it will show::
2318
2319    Flow rule validated
2320
2321 Otherwise it will show an error message of the form::
2322
2323    Caught error type [...] ([...]): [...]
2324
2325 This command uses the same parameters as ``flow create``, their format is
2326 described in `Creating flow rules`_.
2327
2328 Check whether redirecting any Ethernet packet received on port 0 to RX queue
2329 index 6 is supported::
2330
2331    testpmd> flow validate 0 ingress pattern eth / end
2332       actions queue index 6 / end
2333    Flow rule validated
2334    testpmd>
2335
2336 Port 0 does not support TCPv6 rules::
2337
2338    testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
2339       actions drop / end
2340    Caught error type 9 (specific pattern item): Invalid argument
2341    testpmd>
2342
2343 Creating flow rules
2344 ~~~~~~~~~~~~~~~~~~~
2345
2346 ``flow create`` validates and creates the specified flow rule. It is bound
2347 to ``rte_flow_create()``::
2348
2349    flow create {port_id}
2350       [group {group_id}] [priority {level}] [ingress] [egress]
2351       pattern {item} [/ {item} [...]] / end
2352       actions {action} [/ {action} [...]] / end
2353
2354 If successful, it will return a flow rule ID usable with other commands::
2355
2356    Flow rule #[...] created
2357
2358 Otherwise it will show an error message of the form::
2359
2360    Caught error type [...] ([...]): [...]
2361
2362 Parameters describe in the following order:
2363
2364 - Attributes (*group*, *priority*, *ingress*, *egress* tokens).
2365 - A matching pattern, starting with the *pattern* token and terminated by an
2366   *end* pattern item.
2367 - Actions, starting with the *actions* token and terminated by an *end*
2368   action.
2369
2370 These translate directly to *rte_flow* objects provided as-is to the
2371 underlying functions.
2372
2373 The shortest valid definition only comprises mandatory tokens::
2374
2375    testpmd> flow create 0 pattern end actions end
2376
2377 Note that PMDs may refuse rules that essentially do nothing such as this
2378 one.
2379
2380 **All unspecified object values are automatically initialized to 0.**
2381
2382 Attributes
2383 ^^^^^^^^^^
2384
2385 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
2386 specified before the ``pattern`` token.
2387
2388 - ``group {group id}``: priority group.
2389 - ``priority {level}``: priority level within group.
2390 - ``ingress``: rule applies to ingress traffic.
2391 - ``egress``: rule applies to egress traffic.
2392
2393 Each instance of an attribute specified several times overrides the previous
2394 value as shown below (group 4 is used)::
2395
2396    testpmd> flow create 0 group 42 group 24 group 4 [...]
2397
2398 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
2399
2400 While not specifying a direction is an error, some rules may allow both
2401 simultaneously.
2402
2403 Most rules affect RX therefore contain the ``ingress`` token::
2404
2405    testpmd> flow create 0 ingress pattern [...]
2406
2407 Matching pattern
2408 ^^^^^^^^^^^^^^^^
2409
2410 A matching pattern starts after the ``pattern`` token. It is made of pattern
2411 items and is terminated by a mandatory ``end`` item.
2412
2413 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
2414 rte_flow_item_type``).
2415
2416 The ``/`` token is used as a separator between pattern items as shown
2417 below::
2418
2419    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
2420
2421 Note that protocol items like these must be stacked from lowest to highest
2422 layer to make sense. For instance, the following rule is either invalid or
2423 unlikely to match any packet::
2424
2425    testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
2426
2427 More information on these restrictions can be found in the *rte_flow*
2428 documentation.
2429
2430 Several items support additional specification structures, for example
2431 ``ipv4`` allows specifying source and destination addresses as follows::
2432
2433    testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
2434       dst is 10.2.0.0 / end [...]
2435
2436 This rule matches all IPv4 traffic with the specified properties.
2437
2438 In this example, ``src`` and ``dst`` are field names of the underlying
2439 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
2440 in a similar fashion.
2441
2442 The ``is`` token means that the subsequent value must be matched exactly,
2443 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
2444 accordingly. Possible assignment tokens are:
2445
2446 - ``is``: match value perfectly (with full bit-mask).
2447 - ``spec``: match value according to configured bit-mask.
2448 - ``last``: specify upper bound to establish a range.
2449 - ``mask``: specify bit-mask with relevant bits set to one.
2450 - ``prefix``: generate bit-mask from a prefix length.
2451
2452 These yield identical results::
2453
2454    ipv4 src is 10.1.1.1
2455
2456 ::
2457
2458    ipv4 src spec 10.1.1.1 src mask 255.255.255.255
2459
2460 ::
2461
2462    ipv4 src spec 10.1.1.1 src prefix 32
2463
2464 ::
2465
2466    ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
2467
2468 ::
2469
2470    ipv4 src is 10.1.1.1 src last 0 # 0 disables range
2471
2472 Inclusive ranges can be defined with ``last``::
2473
2474    ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
2475
2476 Note that ``mask`` affects both ``spec`` and ``last``::
2477
2478    ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
2479       # matches 10.1.0.0 to 10.2.255.255
2480
2481 Properties can be modified multiple times::
2482
2483    ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
2484
2485 ::
2486
2487    ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
2488
2489 Pattern items
2490 ^^^^^^^^^^^^^
2491
2492 This section lists supported pattern items and their attributes, if any.
2493
2494 - ``end``: end list of pattern items.
2495
2496 - ``void``: no-op pattern item.
2497
2498 - ``invert``: perform actions when pattern does not match.
2499
2500 - ``any``: match any protocol for the current layer.
2501
2502   - ``num {unsigned}``: number of layers covered.
2503
2504 - ``pf``: match packets addressed to the physical function.
2505
2506 - ``vf``: match packets addressed to a virtual function ID.
2507
2508   - ``id {unsigned}``: destination VF ID.
2509
2510 - ``port``: device-specific physical port index to use.
2511
2512   - ``index {unsigned}``: physical port index.
2513
2514 - ``raw``: match an arbitrary byte string.
2515
2516   - ``relative {boolean}``: look for pattern after the previous item.
2517   - ``search {boolean}``: search pattern from offset (see also limit).
2518   - ``offset {integer}``: absolute or relative offset for pattern.
2519   - ``limit {unsigned}``: search area limit for start of pattern.
2520   - ``pattern {string}``: byte string to look for.
2521
2522 - ``eth``: match Ethernet header.
2523
2524   - ``dst {MAC-48}``: destination MAC.
2525   - ``src {MAC-48}``: source MAC.
2526   - ``type {unsigned}``: EtherType.
2527
2528 - ``vlan``: match 802.1Q/ad VLAN tag.
2529
2530   - ``tpid {unsigned}``: tag protocol identifier.
2531   - ``tci {unsigned}``: tag control information.
2532   - ``pcp {unsigned}``: priority code point.
2533   - ``dei {unsigned}``: drop eligible indicator.
2534   - ``vid {unsigned}``: VLAN identifier.
2535
2536 - ``ipv4``: match IPv4 header.
2537
2538   - ``tos {unsigned}``: type of service.
2539   - ``ttl {unsigned}``: time to live.
2540   - ``proto {unsigned}``: next protocol ID.
2541   - ``src {ipv4 address}``: source address.
2542   - ``dst {ipv4 address}``: destination address.
2543
2544 - ``ipv6``: match IPv6 header.
2545
2546   - ``tc {unsigned}``: traffic class.
2547   - ``flow {unsigned}``: flow label.
2548   - ``proto {unsigned}``: protocol (next header).
2549   - ``hop {unsigned}``: hop limit.
2550   - ``src {ipv6 address}``: source address.
2551   - ``dst {ipv6 address}``: destination address.
2552
2553 - ``icmp``: match ICMP header.
2554
2555   - ``type {unsigned}``: ICMP packet type.
2556   - ``code {unsigned}``: ICMP packet code.
2557
2558 - ``udp``: match UDP header.
2559
2560   - ``src {unsigned}``: UDP source port.
2561   - ``dst {unsigned}``: UDP destination port.
2562
2563 - ``tcp``: match TCP header.
2564
2565   - ``src {unsigned}``: TCP source port.
2566   - ``dst {unsigned}``: TCP destination port.
2567
2568 - ``sctp``: match SCTP header.
2569
2570   - ``src {unsigned}``: SCTP source port.
2571   - ``dst {unsigned}``: SCTP destination port.
2572   - ``tag {unsigned}``: validation tag.
2573   - ``cksum {unsigned}``: checksum.
2574
2575 - ``vxlan``: match VXLAN header.
2576
2577   - ``vni {unsigned}``: VXLAN identifier.
2578
2579 - ``e_tag``: match IEEE 802.1BR E-Tag header.
2580
2581   - ``grp_ecid_b {unsigned}``: GRP and E-CID base.
2582
2583 - ``nvgre``: match NVGRE header.
2584
2585   - ``tni {unsigned}``: virtual subnet ID.
2586
2587 - ``mpls``: match MPLS header.
2588
2589   - ``label {unsigned}``: MPLS label.
2590
2591 - ``gre``: match GRE header.
2592
2593   - ``protocol {unsigned}``: protocol type.
2594
2595 Actions list
2596 ^^^^^^^^^^^^
2597
2598 A list of actions starts after the ``actions`` token in the same fashion as
2599 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
2600 terminated by a mandatory ``end`` action.
2601
2602 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
2603 rte_flow_action_type``).
2604
2605 Dropping all incoming UDPv4 packets can be expressed as follows::
2606
2607    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2608       actions drop / end
2609
2610 Several actions have configurable properties which must be specified when
2611 there is no valid default value. For example, ``queue`` requires a target
2612 queue index.
2613
2614 This rule redirects incoming UDPv4 traffic to queue index 6::
2615
2616    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2617       actions queue index 6 / end
2618
2619 While this one could be rejected by PMDs (unspecified queue index)::
2620
2621    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2622       actions queue / end
2623
2624 As defined by *rte_flow*, the list is not ordered, all actions of a given
2625 rule are performed simultaneously. These are equivalent::
2626
2627    queue index 6 / void / mark id 42 / end
2628
2629 ::
2630
2631    void / mark id 42 / queue index 6 / end
2632
2633 All actions in a list should have different types, otherwise only the last
2634 action of a given type is taken into account::
2635
2636    queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
2637
2638 ::
2639
2640    drop / drop / drop / end # drop is performed only once
2641
2642 ::
2643
2644    mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
2645
2646 Considering they are performed simultaneously, opposite and overlapping
2647 actions can sometimes be combined when the end result is unambiguous::
2648
2649    drop / queue index 6 / end # drop has no effect
2650
2651 ::
2652
2653    drop / dup index 6 / end # same as above
2654
2655 ::
2656
2657    queue index 6 / rss queues 6 7 8 / end # queue has no effect
2658
2659 ::
2660
2661    drop / passthru / end # drop has no effect
2662
2663 Note that PMDs may still refuse such combinations.
2664
2665 Actions
2666 ^^^^^^^
2667
2668 This section lists supported actions and their attributes, if any.
2669
2670 - ``end``: end list of actions.
2671
2672 - ``void``: no-op action.
2673
2674 - ``passthru``: let subsequent rule process matched packets.
2675
2676 - ``mark``: attach 32 bit value to packets.
2677
2678   - ``id {unsigned}``: 32 bit value to return with packets.
2679
2680 - ``flag``: flag packets.
2681
2682 - ``queue``: assign packets to a given queue index.
2683
2684   - ``index {unsigned}``: queue index to use.
2685
2686 - ``drop``: drop packets (note: passthru has priority).
2687
2688 - ``count``: enable counters for this rule.
2689
2690 - ``dup``: duplicate packets to a given queue index.
2691
2692   - ``index {unsigned}``: queue index to duplicate packets to.
2693
2694 - ``rss``: spread packets among several queues.
2695
2696   - ``queues [{unsigned} [...]] end``: queue indices to use.
2697
2698 - ``pf``: redirect packets to physical device function.
2699
2700 - ``vf``: redirect packets to virtual device function.
2701
2702   - ``original {boolean}``: use original VF ID if possible.
2703   - ``id {unsigned}``: VF ID to redirect packets to.
2704
2705 Destroying flow rules
2706 ~~~~~~~~~~~~~~~~~~~~~
2707
2708 ``flow destroy`` destroys one or more rules from their rule ID (as returned
2709 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
2710 times as necessary::
2711
2712    flow destroy {port_id} rule {rule_id} [...]
2713
2714 If successful, it will show::
2715
2716    Flow rule #[...] destroyed
2717
2718 It does not report anything for rule IDs that do not exist. The usual error
2719 message is shown when a rule cannot be destroyed::
2720
2721    Caught error type [...] ([...]): [...]
2722
2723 ``flow flush`` destroys all rules on a device and does not take extra
2724 arguments. It is bound to ``rte_flow_flush()``::
2725
2726    flow flush {port_id}
2727
2728 Any errors are reported as above.
2729
2730 Creating several rules and destroying them::
2731
2732    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2733       actions queue index 2 / end
2734    Flow rule #0 created
2735    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2736       actions queue index 3 / end
2737    Flow rule #1 created
2738    testpmd> flow destroy 0 rule 0 rule 1
2739    Flow rule #1 destroyed
2740    Flow rule #0 destroyed
2741    testpmd>
2742
2743 The same result can be achieved using ``flow flush``::
2744
2745    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2746       actions queue index 2 / end
2747    Flow rule #0 created
2748    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2749       actions queue index 3 / end
2750    Flow rule #1 created
2751    testpmd> flow flush 0
2752    testpmd>
2753
2754 Non-existent rule IDs are ignored::
2755
2756    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2757       actions queue index 2 / end
2758    Flow rule #0 created
2759    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2760       actions queue index 3 / end
2761    Flow rule #1 created
2762    testpmd> flow destroy 0 rule 42 rule 10 rule 2
2763    testpmd>
2764    testpmd> flow destroy 0 rule 0
2765    Flow rule #0 destroyed
2766    testpmd>
2767
2768 Querying flow rules
2769 ~~~~~~~~~~~~~~~~~~~
2770
2771 ``flow query`` queries a specific action of a flow rule having that
2772 ability. Such actions collect information that can be reported using this
2773 command. It is bound to ``rte_flow_query()``::
2774
2775    flow query {port_id} {rule_id} {action}
2776
2777 If successful, it will display either the retrieved data for known actions
2778 or the following message::
2779
2780    Cannot display result for action type [...] ([...])
2781
2782 Otherwise, it will complain either that the rule does not exist or that some
2783 error occurred::
2784
2785    Flow rule #[...] not found
2786
2787 ::
2788
2789    Caught error type [...] ([...]): [...]
2790
2791 Currently only the ``count`` action is supported. This action reports the
2792 number of packets that hit the flow rule and the total number of bytes. Its
2793 output has the following format::
2794
2795    count:
2796     hits_set: [...] # whether "hits" contains a valid value
2797     bytes_set: [...] # whether "bytes" contains a valid value
2798     hits: [...] # number of packets
2799     bytes: [...] # number of bytes
2800
2801 Querying counters for TCPv6 packets redirected to queue 6::
2802
2803    testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
2804       actions queue index 6 / count / end
2805    Flow rule #4 created
2806    testpmd> flow query 0 4 count
2807    count:
2808     hits_set: 1
2809     bytes_set: 0
2810     hits: 386446
2811     bytes: 0
2812    testpmd>
2813
2814 Listing flow rules
2815 ~~~~~~~~~~~~~~~~~~
2816
2817 ``flow list`` lists existing flow rules sorted by priority and optionally
2818 filtered by group identifiers::
2819
2820    flow list {port_id} [group {group_id}] [...]
2821
2822 This command only fails with the following message if the device does not
2823 exist::
2824
2825    Invalid port [...]
2826
2827 Output consists of a header line followed by a short description of each
2828 flow rule, one per line. There is no output at all when no flow rules are
2829 configured on the device::
2830
2831    ID      Group   Prio    Attr    Rule
2832    [...]   [...]   [...]   [...]   [...]
2833
2834 ``Attr`` column flags:
2835
2836 - ``i`` for ``ingress``.
2837 - ``e`` for ``egress``.
2838
2839 Creating several flow rules and listing them::
2840
2841    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2842       actions queue index 6 / end
2843    Flow rule #0 created
2844    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2845       actions queue index 2 / end
2846    Flow rule #1 created
2847    testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
2848       actions rss queues 6 7 8 end / end
2849    Flow rule #2 created
2850    testpmd> flow list 0
2851    ID      Group   Prio    Attr    Rule
2852    0       0       0       i-      ETH IPV4 => QUEUE
2853    1       0       0       i-      ETH IPV6 => QUEUE
2854    2       0       5       i-      ETH IPV4 UDP => RSS
2855    testpmd>
2856
2857 Rules are sorted by priority (i.e. group ID first, then priority level)::
2858
2859    testpmd> flow list 1
2860    ID      Group   Prio    Attr    Rule
2861    0       0       0       i-      ETH => COUNT
2862    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2863    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2864    1       24      0       i-      ETH IPV4 UDP => QUEUE
2865    4       24      10      i-      ETH IPV4 TCP => DROP
2866    3       24      20      i-      ETH IPV4 => DROP
2867    2       24      42      i-      ETH IPV4 UDP => QUEUE
2868    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2869    testpmd>
2870
2871 Output can be limited to specific groups::
2872
2873    testpmd> flow list 1 group 0 group 63
2874    ID      Group   Prio    Attr    Rule
2875    0       0       0       i-      ETH => COUNT
2876    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2877    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2878    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2879    testpmd>
2880
2881 Sample QinQ flow rules
2882 ~~~~~~~~~~~~~~~~~~~~~~
2883
2884 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM.
2885
2886 ::
2887
2888    testpmd> flow validate 0 ingress pattern eth / vlan tpid is 0x8100 tci is 4 /
2889        vlan tpid is 0x8100 tci is 5 / end actions vf id 1 / queue index 0 / end
2890    Flow rule #0 validated
2891
2892    testpmd> flow create 0 ingress pattern eth / vlan tpid is 0x8100 tci is 4 /
2893        vlan tpid is 0x8100 tci is 5 / end actions vf id 1 / queue index 0 / end
2894    Flow rule #0 created
2895
2896    testpmd> flow list 0
2897    ID      Group   Prio    Attr    Rule
2898    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
2899
2900 Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host.
2901
2902 ::
2903
2904    testpmd> flow validate 0 ingress pattern eth / vlan tpid is 0x8100 tci is 6 /
2905         vlan tpid is 0x8100 tci is 7 / end actions pf / queue index 0 / end
2906    Flow rule #1 validated
2907
2908    testpmd> flow create 0 ingress pattern eth / vlan tpid is 0x8100 tci is 6 /
2909         vlan tpid is 0x8100 tci is 7 / end actions pf / queue index 1 / end
2910    Flow rule #1 created
2911
2912    testpmd> flow list 0
2913    ID      Group   Prio    Attr    Rule
2914    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
2915    1       0       0       i-      ETH VLAN VLAN=>PF QUEUE
2916
2917 After creating QinQ rule(s) the following command should be issued to enable QinQ::
2918
2919    testpmd> vlan set qinq on 0
2920