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, queries and operation
2268 modes).
2269
2270 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
2271 features simultaneously may cause undefined side-effects and is therefore
2272 not recommended.
2273
2274 ``flow`` syntax
2275 ~~~~~~~~~~~~~~~
2276
2277 Because the ``flow`` command uses dynamic tokens to handle the large number
2278 of possible flow rules combinations, its behavior differs slightly from
2279 other commands, in particular:
2280
2281 - Pressing *?* or the *<tab>* key displays contextual help for the current
2282   token, not that of the entire command.
2283
2284 - Optional and repeated parameters are supported (provided they are listed
2285   in the contextual help).
2286
2287 The first parameter stands for the operation mode. Possible operations and
2288 their general syntax are described below. They are covered in detail in the
2289 following sections.
2290
2291 - Check whether a flow rule can be created::
2292
2293    flow validate {port_id}
2294        [group {group_id}] [priority {level}] [ingress] [egress]
2295        pattern {item} [/ {item} [...]] / end
2296        actions {action} [/ {action} [...]] / end
2297
2298 - Create a flow rule::
2299
2300    flow create {port_id}
2301        [group {group_id}] [priority {level}] [ingress] [egress]
2302        pattern {item} [/ {item} [...]] / end
2303        actions {action} [/ {action} [...]] / end
2304
2305 - Destroy specific flow rules::
2306
2307    flow destroy {port_id} rule {rule_id} [...]
2308
2309 - Destroy all flow rules::
2310
2311    flow flush {port_id}
2312
2313 - Query an existing flow rule::
2314
2315    flow query {port_id} {rule_id} {action}
2316
2317 - List existing flow rules sorted by priority, filtered by group
2318   identifiers::
2319
2320    flow list {port_id} [group {group_id}] [...]
2321
2322 - Restrict ingress traffic to the defined flow rules::
2323
2324    flow isolate {port_id} {boolean}
2325
2326 Validating flow rules
2327 ~~~~~~~~~~~~~~~~~~~~~
2328
2329 ``flow validate`` reports whether a flow rule would be accepted by the
2330 underlying device in its current state but stops short of creating it. It is
2331 bound to ``rte_flow_validate()``::
2332
2333    flow validate {port_id}
2334       [group {group_id}] [priority {level}] [ingress] [egress]
2335       pattern {item} [/ {item} [...]] / end
2336       actions {action} [/ {action} [...]] / end
2337
2338 If successful, it will show::
2339
2340    Flow rule validated
2341
2342 Otherwise it will show an error message of the form::
2343
2344    Caught error type [...] ([...]): [...]
2345
2346 This command uses the same parameters as ``flow create``, their format is
2347 described in `Creating flow rules`_.
2348
2349 Check whether redirecting any Ethernet packet received on port 0 to RX queue
2350 index 6 is supported::
2351
2352    testpmd> flow validate 0 ingress pattern eth / end
2353       actions queue index 6 / end
2354    Flow rule validated
2355    testpmd>
2356
2357 Port 0 does not support TCPv6 rules::
2358
2359    testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
2360       actions drop / end
2361    Caught error type 9 (specific pattern item): Invalid argument
2362    testpmd>
2363
2364 Creating flow rules
2365 ~~~~~~~~~~~~~~~~~~~
2366
2367 ``flow create`` validates and creates the specified flow rule. It is bound
2368 to ``rte_flow_create()``::
2369
2370    flow create {port_id}
2371       [group {group_id}] [priority {level}] [ingress] [egress]
2372       pattern {item} [/ {item} [...]] / end
2373       actions {action} [/ {action} [...]] / end
2374
2375 If successful, it will return a flow rule ID usable with other commands::
2376
2377    Flow rule #[...] created
2378
2379 Otherwise it will show an error message of the form::
2380
2381    Caught error type [...] ([...]): [...]
2382
2383 Parameters describe in the following order:
2384
2385 - Attributes (*group*, *priority*, *ingress*, *egress* tokens).
2386 - A matching pattern, starting with the *pattern* token and terminated by an
2387   *end* pattern item.
2388 - Actions, starting with the *actions* token and terminated by an *end*
2389   action.
2390
2391 These translate directly to *rte_flow* objects provided as-is to the
2392 underlying functions.
2393
2394 The shortest valid definition only comprises mandatory tokens::
2395
2396    testpmd> flow create 0 pattern end actions end
2397
2398 Note that PMDs may refuse rules that essentially do nothing such as this
2399 one.
2400
2401 **All unspecified object values are automatically initialized to 0.**
2402
2403 Attributes
2404 ^^^^^^^^^^
2405
2406 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
2407 specified before the ``pattern`` token.
2408
2409 - ``group {group id}``: priority group.
2410 - ``priority {level}``: priority level within group.
2411 - ``ingress``: rule applies to ingress traffic.
2412 - ``egress``: rule applies to egress traffic.
2413
2414 Each instance of an attribute specified several times overrides the previous
2415 value as shown below (group 4 is used)::
2416
2417    testpmd> flow create 0 group 42 group 24 group 4 [...]
2418
2419 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
2420
2421 While not specifying a direction is an error, some rules may allow both
2422 simultaneously.
2423
2424 Most rules affect RX therefore contain the ``ingress`` token::
2425
2426    testpmd> flow create 0 ingress pattern [...]
2427
2428 Matching pattern
2429 ^^^^^^^^^^^^^^^^
2430
2431 A matching pattern starts after the ``pattern`` token. It is made of pattern
2432 items and is terminated by a mandatory ``end`` item.
2433
2434 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
2435 rte_flow_item_type``).
2436
2437 The ``/`` token is used as a separator between pattern items as shown
2438 below::
2439
2440    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
2441
2442 Note that protocol items like these must be stacked from lowest to highest
2443 layer to make sense. For instance, the following rule is either invalid or
2444 unlikely to match any packet::
2445
2446    testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
2447
2448 More information on these restrictions can be found in the *rte_flow*
2449 documentation.
2450
2451 Several items support additional specification structures, for example
2452 ``ipv4`` allows specifying source and destination addresses as follows::
2453
2454    testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
2455       dst is 10.2.0.0 / end [...]
2456
2457 This rule matches all IPv4 traffic with the specified properties.
2458
2459 In this example, ``src`` and ``dst`` are field names of the underlying
2460 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
2461 in a similar fashion.
2462
2463 The ``is`` token means that the subsequent value must be matched exactly,
2464 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
2465 accordingly. Possible assignment tokens are:
2466
2467 - ``is``: match value perfectly (with full bit-mask).
2468 - ``spec``: match value according to configured bit-mask.
2469 - ``last``: specify upper bound to establish a range.
2470 - ``mask``: specify bit-mask with relevant bits set to one.
2471 - ``prefix``: generate bit-mask from a prefix length.
2472
2473 These yield identical results::
2474
2475    ipv4 src is 10.1.1.1
2476
2477 ::
2478
2479    ipv4 src spec 10.1.1.1 src mask 255.255.255.255
2480
2481 ::
2482
2483    ipv4 src spec 10.1.1.1 src prefix 32
2484
2485 ::
2486
2487    ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
2488
2489 ::
2490
2491    ipv4 src is 10.1.1.1 src last 0 # 0 disables range
2492
2493 Inclusive ranges can be defined with ``last``::
2494
2495    ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
2496
2497 Note that ``mask`` affects both ``spec`` and ``last``::
2498
2499    ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
2500       # matches 10.1.0.0 to 10.2.255.255
2501
2502 Properties can be modified multiple times::
2503
2504    ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
2505
2506 ::
2507
2508    ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
2509
2510 Pattern items
2511 ^^^^^^^^^^^^^
2512
2513 This section lists supported pattern items and their attributes, if any.
2514
2515 - ``end``: end list of pattern items.
2516
2517 - ``void``: no-op pattern item.
2518
2519 - ``invert``: perform actions when pattern does not match.
2520
2521 - ``any``: match any protocol for the current layer.
2522
2523   - ``num {unsigned}``: number of layers covered.
2524
2525 - ``pf``: match packets addressed to the physical function.
2526
2527 - ``vf``: match packets addressed to a virtual function ID.
2528
2529   - ``id {unsigned}``: destination VF ID.
2530
2531 - ``port``: device-specific physical port index to use.
2532
2533   - ``index {unsigned}``: physical port index.
2534
2535 - ``raw``: match an arbitrary byte string.
2536
2537   - ``relative {boolean}``: look for pattern after the previous item.
2538   - ``search {boolean}``: search pattern from offset (see also limit).
2539   - ``offset {integer}``: absolute or relative offset for pattern.
2540   - ``limit {unsigned}``: search area limit for start of pattern.
2541   - ``pattern {string}``: byte string to look for.
2542
2543 - ``eth``: match Ethernet header.
2544
2545   - ``dst {MAC-48}``: destination MAC.
2546   - ``src {MAC-48}``: source MAC.
2547   - ``type {unsigned}``: EtherType.
2548
2549 - ``vlan``: match 802.1Q/ad VLAN tag.
2550
2551   - ``tpid {unsigned}``: tag protocol identifier.
2552   - ``tci {unsigned}``: tag control information.
2553   - ``pcp {unsigned}``: priority code point.
2554   - ``dei {unsigned}``: drop eligible indicator.
2555   - ``vid {unsigned}``: VLAN identifier.
2556
2557 - ``ipv4``: match IPv4 header.
2558
2559   - ``tos {unsigned}``: type of service.
2560   - ``ttl {unsigned}``: time to live.
2561   - ``proto {unsigned}``: next protocol ID.
2562   - ``src {ipv4 address}``: source address.
2563   - ``dst {ipv4 address}``: destination address.
2564
2565 - ``ipv6``: match IPv6 header.
2566
2567   - ``tc {unsigned}``: traffic class.
2568   - ``flow {unsigned}``: flow label.
2569   - ``proto {unsigned}``: protocol (next header).
2570   - ``hop {unsigned}``: hop limit.
2571   - ``src {ipv6 address}``: source address.
2572   - ``dst {ipv6 address}``: destination address.
2573
2574 - ``icmp``: match ICMP header.
2575
2576   - ``type {unsigned}``: ICMP packet type.
2577   - ``code {unsigned}``: ICMP packet code.
2578
2579 - ``udp``: match UDP header.
2580
2581   - ``src {unsigned}``: UDP source port.
2582   - ``dst {unsigned}``: UDP destination port.
2583
2584 - ``tcp``: match TCP header.
2585
2586   - ``src {unsigned}``: TCP source port.
2587   - ``dst {unsigned}``: TCP destination port.
2588
2589 - ``sctp``: match SCTP header.
2590
2591   - ``src {unsigned}``: SCTP source port.
2592   - ``dst {unsigned}``: SCTP destination port.
2593   - ``tag {unsigned}``: validation tag.
2594   - ``cksum {unsigned}``: checksum.
2595
2596 - ``vxlan``: match VXLAN header.
2597
2598   - ``vni {unsigned}``: VXLAN identifier.
2599
2600 - ``e_tag``: match IEEE 802.1BR E-Tag header.
2601
2602   - ``grp_ecid_b {unsigned}``: GRP and E-CID base.
2603
2604 - ``nvgre``: match NVGRE header.
2605
2606   - ``tni {unsigned}``: virtual subnet ID.
2607
2608 - ``mpls``: match MPLS header.
2609
2610   - ``label {unsigned}``: MPLS label.
2611
2612 - ``gre``: match GRE header.
2613
2614   - ``protocol {unsigned}``: protocol type.
2615
2616 - ``fuzzy``: fuzzy pattern match, expect faster than default.
2617
2618   - ``thresh {unsigned}``: accuracy threshold.
2619
2620 Actions list
2621 ^^^^^^^^^^^^
2622
2623 A list of actions starts after the ``actions`` token in the same fashion as
2624 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
2625 terminated by a mandatory ``end`` action.
2626
2627 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
2628 rte_flow_action_type``).
2629
2630 Dropping all incoming UDPv4 packets can be expressed as follows::
2631
2632    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2633       actions drop / end
2634
2635 Several actions have configurable properties which must be specified when
2636 there is no valid default value. For example, ``queue`` requires a target
2637 queue index.
2638
2639 This rule redirects incoming UDPv4 traffic to queue index 6::
2640
2641    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2642       actions queue index 6 / end
2643
2644 While this one could be rejected by PMDs (unspecified queue index)::
2645
2646    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2647       actions queue / end
2648
2649 As defined by *rte_flow*, the list is not ordered, all actions of a given
2650 rule are performed simultaneously. These are equivalent::
2651
2652    queue index 6 / void / mark id 42 / end
2653
2654 ::
2655
2656    void / mark id 42 / queue index 6 / end
2657
2658 All actions in a list should have different types, otherwise only the last
2659 action of a given type is taken into account::
2660
2661    queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
2662
2663 ::
2664
2665    drop / drop / drop / end # drop is performed only once
2666
2667 ::
2668
2669    mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
2670
2671 Considering they are performed simultaneously, opposite and overlapping
2672 actions can sometimes be combined when the end result is unambiguous::
2673
2674    drop / queue index 6 / end # drop has no effect
2675
2676 ::
2677
2678    drop / dup index 6 / end # same as above
2679
2680 ::
2681
2682    queue index 6 / rss queues 6 7 8 / end # queue has no effect
2683
2684 ::
2685
2686    drop / passthru / end # drop has no effect
2687
2688 Note that PMDs may still refuse such combinations.
2689
2690 Actions
2691 ^^^^^^^
2692
2693 This section lists supported actions and their attributes, if any.
2694
2695 - ``end``: end list of actions.
2696
2697 - ``void``: no-op action.
2698
2699 - ``passthru``: let subsequent rule process matched packets.
2700
2701 - ``mark``: attach 32 bit value to packets.
2702
2703   - ``id {unsigned}``: 32 bit value to return with packets.
2704
2705 - ``flag``: flag packets.
2706
2707 - ``queue``: assign packets to a given queue index.
2708
2709   - ``index {unsigned}``: queue index to use.
2710
2711 - ``drop``: drop packets (note: passthru has priority).
2712
2713 - ``count``: enable counters for this rule.
2714
2715 - ``dup``: duplicate packets to a given queue index.
2716
2717   - ``index {unsigned}``: queue index to duplicate packets to.
2718
2719 - ``rss``: spread packets among several queues.
2720
2721   - ``queues [{unsigned} [...]] end``: queue indices to use.
2722
2723 - ``pf``: redirect packets to physical device function.
2724
2725 - ``vf``: redirect packets to virtual device function.
2726
2727   - ``original {boolean}``: use original VF ID if possible.
2728   - ``id {unsigned}``: VF ID to redirect packets to.
2729
2730 Destroying flow rules
2731 ~~~~~~~~~~~~~~~~~~~~~
2732
2733 ``flow destroy`` destroys one or more rules from their rule ID (as returned
2734 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
2735 times as necessary::
2736
2737    flow destroy {port_id} rule {rule_id} [...]
2738
2739 If successful, it will show::
2740
2741    Flow rule #[...] destroyed
2742
2743 It does not report anything for rule IDs that do not exist. The usual error
2744 message is shown when a rule cannot be destroyed::
2745
2746    Caught error type [...] ([...]): [...]
2747
2748 ``flow flush`` destroys all rules on a device and does not take extra
2749 arguments. It is bound to ``rte_flow_flush()``::
2750
2751    flow flush {port_id}
2752
2753 Any errors are reported as above.
2754
2755 Creating several rules and destroying them::
2756
2757    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2758       actions queue index 2 / end
2759    Flow rule #0 created
2760    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2761       actions queue index 3 / end
2762    Flow rule #1 created
2763    testpmd> flow destroy 0 rule 0 rule 1
2764    Flow rule #1 destroyed
2765    Flow rule #0 destroyed
2766    testpmd>
2767
2768 The same result can be achieved using ``flow flush``::
2769
2770    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2771       actions queue index 2 / end
2772    Flow rule #0 created
2773    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2774       actions queue index 3 / end
2775    Flow rule #1 created
2776    testpmd> flow flush 0
2777    testpmd>
2778
2779 Non-existent rule IDs are ignored::
2780
2781    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2782       actions queue index 2 / end
2783    Flow rule #0 created
2784    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2785       actions queue index 3 / end
2786    Flow rule #1 created
2787    testpmd> flow destroy 0 rule 42 rule 10 rule 2
2788    testpmd>
2789    testpmd> flow destroy 0 rule 0
2790    Flow rule #0 destroyed
2791    testpmd>
2792
2793 Querying flow rules
2794 ~~~~~~~~~~~~~~~~~~~
2795
2796 ``flow query`` queries a specific action of a flow rule having that
2797 ability. Such actions collect information that can be reported using this
2798 command. It is bound to ``rte_flow_query()``::
2799
2800    flow query {port_id} {rule_id} {action}
2801
2802 If successful, it will display either the retrieved data for known actions
2803 or the following message::
2804
2805    Cannot display result for action type [...] ([...])
2806
2807 Otherwise, it will complain either that the rule does not exist or that some
2808 error occurred::
2809
2810    Flow rule #[...] not found
2811
2812 ::
2813
2814    Caught error type [...] ([...]): [...]
2815
2816 Currently only the ``count`` action is supported. This action reports the
2817 number of packets that hit the flow rule and the total number of bytes. Its
2818 output has the following format::
2819
2820    count:
2821     hits_set: [...] # whether "hits" contains a valid value
2822     bytes_set: [...] # whether "bytes" contains a valid value
2823     hits: [...] # number of packets
2824     bytes: [...] # number of bytes
2825
2826 Querying counters for TCPv6 packets redirected to queue 6::
2827
2828    testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
2829       actions queue index 6 / count / end
2830    Flow rule #4 created
2831    testpmd> flow query 0 4 count
2832    count:
2833     hits_set: 1
2834     bytes_set: 0
2835     hits: 386446
2836     bytes: 0
2837    testpmd>
2838
2839 Listing flow rules
2840 ~~~~~~~~~~~~~~~~~~
2841
2842 ``flow list`` lists existing flow rules sorted by priority and optionally
2843 filtered by group identifiers::
2844
2845    flow list {port_id} [group {group_id}] [...]
2846
2847 This command only fails with the following message if the device does not
2848 exist::
2849
2850    Invalid port [...]
2851
2852 Output consists of a header line followed by a short description of each
2853 flow rule, one per line. There is no output at all when no flow rules are
2854 configured on the device::
2855
2856    ID      Group   Prio    Attr    Rule
2857    [...]   [...]   [...]   [...]   [...]
2858
2859 ``Attr`` column flags:
2860
2861 - ``i`` for ``ingress``.
2862 - ``e`` for ``egress``.
2863
2864 Creating several flow rules and listing them::
2865
2866    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2867       actions queue index 6 / end
2868    Flow rule #0 created
2869    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2870       actions queue index 2 / end
2871    Flow rule #1 created
2872    testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
2873       actions rss queues 6 7 8 end / end
2874    Flow rule #2 created
2875    testpmd> flow list 0
2876    ID      Group   Prio    Attr    Rule
2877    0       0       0       i-      ETH IPV4 => QUEUE
2878    1       0       0       i-      ETH IPV6 => QUEUE
2879    2       0       5       i-      ETH IPV4 UDP => RSS
2880    testpmd>
2881
2882 Rules are sorted by priority (i.e. group ID first, then priority level)::
2883
2884    testpmd> flow list 1
2885    ID      Group   Prio    Attr    Rule
2886    0       0       0       i-      ETH => COUNT
2887    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2888    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2889    1       24      0       i-      ETH IPV4 UDP => QUEUE
2890    4       24      10      i-      ETH IPV4 TCP => DROP
2891    3       24      20      i-      ETH IPV4 => DROP
2892    2       24      42      i-      ETH IPV4 UDP => QUEUE
2893    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2894    testpmd>
2895
2896 Output can be limited to specific groups::
2897
2898    testpmd> flow list 1 group 0 group 63
2899    ID      Group   Prio    Attr    Rule
2900    0       0       0       i-      ETH => COUNT
2901    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2902    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2903    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2904    testpmd>
2905
2906 Toggling isolated mode
2907 ~~~~~~~~~~~~~~~~~~~~~~
2908
2909 ``flow isolate`` can be used to tell the underlying PMD that ingress traffic
2910 must only be injected from the defined flow rules; that no default traffic
2911 is expected outside those rules and the driver is free to assign more
2912 resources to handle them. It is bound to ``rte_flow_isolate()``::
2913
2914  flow isolate {port_id} {boolean}
2915
2916 If successful, enabling or disabling isolated mode shows either::
2917
2918  Ingress traffic on port [...]
2919     is now restricted to the defined flow rules
2920
2921 Or::
2922
2923  Ingress traffic on port [...]
2924     is not restricted anymore to the defined flow rules
2925
2926 Otherwise, in case of error::
2927
2928    Caught error type [...] ([...]): [...]
2929
2930 Mainly due to its side effects, PMDs supporting this mode may not have the
2931 ability to toggle it more than once without reinitializing affected ports
2932 first (e.g. by exiting testpmd).
2933
2934 Enabling isolated mode::
2935
2936  testpmd> flow isolate 0 true
2937  Ingress traffic on port 0 is now restricted to the defined flow rules
2938  testpmd>
2939
2940 Disabling isolated mode::
2941
2942  testpmd> flow isolate 0 false
2943  Ingress traffic on port 0 is not restricted anymore to the defined flow rules
2944  testpmd>
2945
2946 Sample QinQ flow rules
2947 ~~~~~~~~~~~~~~~~~~~~~~
2948
2949 Before creating QinQ rule(s) the following commands should be issued to enable QinQ::
2950
2951    testpmd> port stop 0
2952    testpmd> vlan set qinq on 0
2953
2954 The above command sets the inner and outer TPID's to 0x8100.
2955
2956 To change the TPID's the following commands should be used::
2957
2958    testpmd> vlan set outer tpid 0xa100 0
2959    testpmd> vlan set inner tpid 0x9100 0
2960    testpmd> port start 0
2961
2962 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM.
2963
2964 ::
2965
2966    testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 /
2967        vlan tci is 456 / end actions vf id 1 / queue index 0 / end
2968    Flow rule #0 validated
2969
2970    testpmd> flow create 0 ingress pattern eth / vlan tci is 4 /
2971        vlan tci is 456 / end actions vf id 123 / queue index 0 / end
2972    Flow rule #0 created
2973
2974    testpmd> flow list 0
2975    ID      Group   Prio    Attr    Rule
2976    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
2977
2978 Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host.
2979
2980 ::
2981
2982    testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 /
2983         vlan tci is 654 / end actions pf / queue index 0 / end
2984    Flow rule #1 validated
2985
2986    testpmd> flow create 0 ingress pattern eth / vlan tci is 321 /
2987         vlan tci is 654 / end actions pf / queue index 1 / end
2988    Flow rule #1 created
2989
2990    testpmd> flow list 0
2991    ID      Group   Prio    Attr    Rule
2992    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
2993    1       0       0       i-      ETH VLAN VLAN=>PF QUEUE