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