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