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