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