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