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