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|cap X 55 info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all 56 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X 57 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap 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 89Command File Functions 90---------------------- 91 92To facilitate loading large number of commands or to avoid cutting and pasting where not 93practical or possible testpmd supports alternative methods for executing commands. 94 95* If started with the ``--cmdline-file=FILENAME`` command line argument testpmd 96 will execute all CLI commands contained within the file immediately before 97 starting packet forwarding or entering interactive mode. 98 99.. code-block:: console 100 101 ./testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt 102 Interactive-mode selected 103 CLI commands to be read from /home/ubuntu/flow-create-commands.txt 104 Configuring Port 0 (socket 0) 105 Port 0: 7C:FE:90:CB:74:CE 106 Configuring Port 1 (socket 0) 107 Port 1: 7C:FE:90:CB:74:CA 108 Checking link statuses... 109 Port 0 Link Up - speed 10000 Mbps - full-duplex 110 Port 1 Link Up - speed 10000 Mbps - full-duplex 111 Done 112 Flow rule #0 created 113 Flow rule #1 created 114 ... 115 ... 116 Flow rule #498 created 117 Flow rule #499 created 118 Read all CLI commands from /home/ubuntu/flow-create-commands.txt 119 testpmd> 120 121 122* At run-time additional commands can be loaded in bulk by invoking the ``load FILENAME`` 123 command. 124 125.. code-block:: console 126 127 testpmd> load /home/ubuntu/flow-create-commands.txt 128 Flow rule #0 created 129 Flow rule #1 created 130 ... 131 ... 132 Flow rule #498 created 133 Flow rule #499 created 134 Read all CLI commands from /home/ubuntu/flow-create-commands.txt 135 testpmd> 136 137 138In all cases output from any included command will be displayed as standard output. 139Execution will continue until the end of the file is reached regardless of 140whether any errors occur. The end user must examine the output to determine if 141any failures occurred. 142 143 144Control Functions 145----------------- 146 147start 148~~~~~ 149 150Start packet forwarding with current configuration:: 151 152 testpmd> start 153 154start tx_first 155~~~~~~~~~~~~~~ 156 157Start packet forwarding with current configuration after sending specified number of bursts of packets:: 158 159 testpmd> start tx_first (""|burst_num) 160 161The default burst number is 1 when ``burst_num`` not presented. 162 163stop 164~~~~ 165 166Stop packet forwarding, and display accumulated statistics:: 167 168 testpmd> stop 169 170quit 171~~~~ 172 173Quit to prompt:: 174 175 testpmd> quit 176 177 178Display Functions 179----------------- 180 181The functions in the following sections are used to display information about the 182testpmd configuration or the NIC status. 183 184show port 185~~~~~~~~~ 186 187Display information for a given port or all ports:: 188 189 testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc|cap) (port_id|all) 190 191The available information categories are: 192 193* ``info``: General port information such as MAC address. 194 195* ``stats``: RX/TX statistics. 196 197* ``xstats``: RX/TX extended NIC statistics. 198 199* ``fdir``: Flow Director information and statistics. 200 201* ``stat_qmap``: Queue statistics mapping. 202 203* ``dcb_tc``: DCB information such as TC mapping. 204 205* ``cap``: Supported offload capabilities. 206 207For example: 208 209.. code-block:: console 210 211 testpmd> show port info 0 212 213 ********************* Infos for port 0 ********************* 214 215 MAC address: XX:XX:XX:XX:XX:XX 216 Connect to socket: 0 217 memory allocation on the socket: 0 218 Link status: up 219 Link speed: 40000 Mbps 220 Link duplex: full-duplex 221 Promiscuous mode: enabled 222 Allmulticast mode: disabled 223 Maximum number of MAC addresses: 64 224 Maximum number of MAC addresses of hash filtering: 0 225 VLAN offload: 226 strip on 227 filter on 228 qinq(extend) off 229 Redirection table size: 512 230 Supported flow types: 231 ipv4-frag 232 ipv4-tcp 233 ipv4-udp 234 ipv4-sctp 235 ipv4-other 236 ipv6-frag 237 ipv6-tcp 238 ipv6-udp 239 ipv6-sctp 240 ipv6-other 241 l2_payload 242 port 243 vxlan 244 geneve 245 nvgre 246 247show port rss reta 248~~~~~~~~~~~~~~~~~~ 249 250Display the rss redirection table entry indicated by masks on port X:: 251 252 testpmd> show port (port_id) rss reta (size) (mask0, mask1...) 253 254size is used to indicate the hardware supported reta size 255 256show port rss-hash 257~~~~~~~~~~~~~~~~~~ 258 259Display the RSS hash functions and RSS hash key of a port:: 260 261 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] 262 263clear port 264~~~~~~~~~~ 265 266Clear the port statistics for a given port or for all ports:: 267 268 testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all) 269 270For example:: 271 272 testpmd> clear port stats all 273 274show (rxq|txq) 275~~~~~~~~~~~~~~ 276 277Display information for a given port's RX/TX queue:: 278 279 testpmd> show (rxq|txq) info (port_id) (queue_id) 280 281show config 282~~~~~~~~~~~ 283 284Displays the configuration of the application. 285The configuration comes from the command-line, the runtime or the application defaults:: 286 287 testpmd> show config (rxtx|cores|fwd|txpkts) 288 289The available information categories are: 290 291* ``rxtx``: RX/TX configuration items. 292 293* ``cores``: List of forwarding cores. 294 295* ``fwd``: Packet forwarding configuration. 296 297* ``txpkts``: Packets to TX configuration. 298 299For example: 300 301.. code-block:: console 302 303 testpmd> show config rxtx 304 305 io packet forwarding - CRC stripping disabled - packets/burst=16 306 nb forwarding cores=2 - nb forwarding ports=1 307 RX queues=1 - RX desc=128 - RX free threshold=0 308 RX threshold registers: pthresh=8 hthresh=8 wthresh=4 309 TX queues=1 - TX desc=512 - TX free threshold=0 310 TX threshold registers: pthresh=36 hthresh=0 wthresh=0 311 TX RS bit threshold=0 - TXQ flags=0x0 312 313set fwd 314~~~~~~~ 315 316Set the packet forwarding mode:: 317 318 testpmd> set fwd (io|mac|macswap|flowgen| \ 319 rxonly|txonly|csum|icmpecho) (""|retry) 320 321``retry`` can be specified for forwarding engines except ``rx_only``. 322 323The available information categories are: 324 325* ``io``: Forwards packets "as-is" in I/O mode. 326 This is the fastest possible forwarding operation as it does not access packets data. 327 This is the default mode. 328 329* ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them. 330 Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination 331 address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or 332 'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address. 333 334* ``macswap``: MAC swap forwarding mode. 335 Swaps the source and the destination Ethernet addresses of packets before forwarding them. 336 337* ``flowgen``: Multi-flow generation mode. 338 Originates a number of flows (with varying destination IP addresses), and terminate receive traffic. 339 340* ``rxonly``: Receives packets but doesn't transmit them. 341 342* ``txonly``: Generates and transmits packets without receiving any. 343 344* ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet. 345 346* ``icmpecho``: Receives a burst of packets, lookup for IMCP echo requests and, if any, send back ICMP echo replies. 347 348* ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=y``. 349 350* ``tm``: Traffic Management forwarding mode 351 Demonstrates the use of ethdev traffic management APIs and softnic PMD for 352 QoS traffic management. In this mode, 5-level hierarchical QoS scheduler is 353 available as an default option that can be enabled through CLI. The user can 354 also modify the default hierarchy or specify the new hierarchy through CLI for 355 implementing QoS scheduler. Requires ``CONFIG_RTE_LIBRTE_PMD_SOFTNIC=y`` ``CONFIG_RTE_LIBRTE_SCHED=y``. 356 357Example:: 358 359 testpmd> set fwd rxonly 360 361 Set rxonly packet forwarding mode 362 363 364read rxd 365~~~~~~~~ 366 367Display an RX descriptor for a port RX queue:: 368 369 testpmd> read rxd (port_id) (queue_id) (rxd_id) 370 371For example:: 372 373 testpmd> read rxd 0 0 4 374 0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180 375 376read txd 377~~~~~~~~ 378 379Display a TX descriptor for a port TX queue:: 380 381 testpmd> read txd (port_id) (queue_id) (txd_id) 382 383For example:: 384 385 testpmd> read txd 0 0 4 386 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C 387 388ddp get list 389~~~~~~~~~~~~ 390 391Get loaded dynamic device personalization (DDP) package info list:: 392 393 testpmd> ddp get list (port_id) 394 395ddp get info 396~~~~~~~~~~~~ 397 398Display information about dynamic device personalization (DDP) profile:: 399 400 testpmd> ddp get info (profile_path) 401 402show vf stats 403~~~~~~~~~~~~~ 404 405Display VF statistics:: 406 407 testpmd> show vf stats (port_id) (vf_id) 408 409clear vf stats 410~~~~~~~~~~~~~~ 411 412Reset VF statistics:: 413 414 testpmd> clear vf stats (port_id) (vf_id) 415 416show port pctype mapping 417~~~~~~~~~~~~~~~~~~~~~~~~ 418 419List all items from the pctype mapping table:: 420 421 testpmd> show port (port_id) pctype mapping 422 423 424Configuration Functions 425----------------------- 426 427The testpmd application can be configured from the runtime as well as from the command-line. 428 429This section details the available configuration functions that are available. 430 431.. note:: 432 433 Configuration changes only become active when forwarding is started/restarted. 434 435set default 436~~~~~~~~~~~ 437 438Reset forwarding to the default configuration:: 439 440 testpmd> set default 441 442set verbose 443~~~~~~~~~~~ 444 445Set the debug verbosity level:: 446 447 testpmd> set verbose (level) 448 449Currently the only available levels are 0 (silent except for error) and 1 (fully verbose). 450 451set nbport 452~~~~~~~~~~ 453 454Set the number of ports used by the application: 455 456set nbport (num) 457 458This is equivalent to the ``--nb-ports`` command-line option. 459 460set nbcore 461~~~~~~~~~~ 462 463Set the number of cores used by the application:: 464 465 testpmd> set nbcore (num) 466 467This is equivalent to the ``--nb-cores`` command-line option. 468 469.. note:: 470 471 The number of cores used must not be greater than number of ports used multiplied by the number of queues per port. 472 473set coremask 474~~~~~~~~~~~~ 475 476Set the forwarding cores hexadecimal mask:: 477 478 testpmd> set coremask (mask) 479 480This is equivalent to the ``--coremask`` command-line option. 481 482.. note:: 483 484 The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding. 485 486set portmask 487~~~~~~~~~~~~ 488 489Set the forwarding ports hexadecimal mask:: 490 491 testpmd> set portmask (mask) 492 493This is equivalent to the ``--portmask`` command-line option. 494 495set burst 496~~~~~~~~~ 497 498Set number of packets per burst:: 499 500 testpmd> set burst (num) 501 502This is equivalent to the ``--burst command-line`` option. 503 504When retry is enabled, the transmit delay time and number of retries can also be set:: 505 506 testpmd> set burst tx delay (microseconds) retry (num) 507 508set txpkts 509~~~~~~~~~~ 510 511Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode:: 512 513 testpmd> set txpkts (x[,y]*) 514 515Where x[,y]* represents a CSV list of values, without white space. 516 517set txsplit 518~~~~~~~~~~~ 519 520Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes:: 521 522 testpmd> set txsplit (off|on|rand) 523 524Where: 525 526* ``off`` disable packet copy & split for CSUM mode. 527 528* ``on`` split outgoing packet into multiple segments. Size of each segment 529 and number of segments per packet is determined by ``set txpkts`` command 530 (see above). 531 532* ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments. 533 534set corelist 535~~~~~~~~~~~~ 536 537Set the list of forwarding cores:: 538 539 testpmd> set corelist (x[,y]*) 540 541For example, to change the forwarding cores: 542 543.. code-block:: console 544 545 testpmd> set corelist 3,1 546 testpmd> show config fwd 547 548 io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled 549 Logical Core 3 (socket 0) forwards packets on 1 streams: 550 RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01 551 Logical Core 1 (socket 0) forwards packets on 1 streams: 552 RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00 553 554.. note:: 555 556 The cores are used in the same order as specified on the command line. 557 558set portlist 559~~~~~~~~~~~~ 560 561Set the list of forwarding ports:: 562 563 testpmd> set portlist (x[,y]*) 564 565For example, to change the port forwarding: 566 567.. code-block:: console 568 569 testpmd> set portlist 0,2,1,3 570 testpmd> show config fwd 571 572 io packet forwarding - ports=4 - cores=1 - streams=4 573 Logical Core 3 (socket 0) forwards packets on 4 streams: 574 RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01 575 RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00 576 RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03 577 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02 578 579set tx loopback 580~~~~~~~~~~~~~~~ 581 582Enable/disable tx loopback:: 583 584 testpmd> set tx loopback (port_id) (on|off) 585 586set drop enable 587~~~~~~~~~~~~~~~ 588 589set drop enable bit for all queues:: 590 591 testpmd> set all queues drop (port_id) (on|off) 592 593set split drop enable (for VF) 594~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 595 596set split drop enable bit for VF from PF:: 597 598 testpmd> set vf split drop (port_id) (vf_id) (on|off) 599 600set mac antispoof (for VF) 601~~~~~~~~~~~~~~~~~~~~~~~~~~ 602 603Set mac antispoof for a VF from the PF:: 604 605 testpmd> set vf mac antispoof (port_id) (vf_id) (on|off) 606 607set macsec offload 608~~~~~~~~~~~~~~~~~~ 609 610Enable/disable MACsec offload:: 611 612 testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off) 613 testpmd> set macsec offload (port_id) off 614 615set macsec sc 616~~~~~~~~~~~~~ 617 618Configure MACsec secure connection (SC):: 619 620 testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi) 621 622.. note:: 623 624 The pi argument is ignored for tx. 625 Check the NIC Datasheet for hardware limits. 626 627set macsec sa 628~~~~~~~~~~~~~ 629 630Configure MACsec secure association (SA):: 631 632 testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key) 633 634.. note:: 635 636 The IDX value must be 0 or 1. 637 Check the NIC Datasheet for hardware limits. 638 639set broadcast mode (for VF) 640~~~~~~~~~~~~~~~~~~~~~~~~~~~ 641 642Set broadcast mode for a VF from the PF:: 643 644 testpmd> set vf broadcast (port_id) (vf_id) (on|off) 645 646vlan set strip 647~~~~~~~~~~~~~~ 648 649Set the VLAN strip on a port:: 650 651 testpmd> vlan set strip (on|off) (port_id) 652 653vlan set stripq 654~~~~~~~~~~~~~~~ 655 656Set the VLAN strip for a queue on a port:: 657 658 testpmd> vlan set stripq (on|off) (port_id,queue_id) 659 660vlan set stripq (for VF) 661~~~~~~~~~~~~~~~~~~~~~~~~ 662 663Set VLAN strip for all queues in a pool for a VF from the PF:: 664 665 testpmd> set vf vlan stripq (port_id) (vf_id) (on|off) 666 667vlan set insert (for VF) 668~~~~~~~~~~~~~~~~~~~~~~~~ 669 670Set VLAN insert for a VF from the PF:: 671 672 testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id) 673 674vlan set tag (for VF) 675~~~~~~~~~~~~~~~~~~~~~ 676 677Set VLAN tag for a VF from the PF:: 678 679 testpmd> set vf vlan tag (port_id) (vf_id) (on|off) 680 681vlan set antispoof (for VF) 682~~~~~~~~~~~~~~~~~~~~~~~~~~~ 683 684Set VLAN antispoof for a VF from the PF:: 685 686 testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off) 687 688vlan set filter 689~~~~~~~~~~~~~~~ 690 691Set the VLAN filter on a port:: 692 693 testpmd> vlan set filter (on|off) (port_id) 694 695vlan set qinq 696~~~~~~~~~~~~~ 697 698Set the VLAN QinQ (extended queue in queue) on for a port:: 699 700 testpmd> vlan set qinq (on|off) (port_id) 701 702vlan set tpid 703~~~~~~~~~~~~~ 704 705Set the inner or outer VLAN TPID for packet filtering on a port:: 706 707 testpmd> vlan set (inner|outer) tpid (value) (port_id) 708 709.. note:: 710 711 TPID value must be a 16-bit number (value <= 65536). 712 713rx_vlan add 714~~~~~~~~~~~ 715 716Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID:: 717 718 testpmd> rx_vlan add (vlan_id|all) (port_id) 719 720.. note:: 721 722 VLAN filter must be set on that port. VLAN ID < 4096. 723 Depending on the NIC used, number of vlan_ids may be limited to the maximum entries 724 in VFTA table. This is important if enabling all vlan_ids. 725 726rx_vlan rm 727~~~~~~~~~~ 728 729Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID:: 730 731 testpmd> rx_vlan rm (vlan_id|all) (port_id) 732 733rx_vlan add (for VF) 734~~~~~~~~~~~~~~~~~~~~ 735 736Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID:: 737 738 testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask) 739 740rx_vlan rm (for VF) 741~~~~~~~~~~~~~~~~~~~ 742 743Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID:: 744 745 testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask) 746 747tunnel_filter add 748~~~~~~~~~~~~~~~~~ 749 750Add a tunnel filter on a port:: 751 752 testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \ 753 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ 754 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) 755 756The available information categories are: 757 758* ``vxlan``: Set tunnel type as VXLAN. 759 760* ``nvgre``: Set tunnel type as NVGRE. 761 762* ``ipingre``: Set tunnel type as IP-in-GRE. 763 764* ``imac-ivlan``: Set filter type as Inner MAC and VLAN. 765 766* ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID. 767 768* ``imac-tenid``: Set filter type as Inner MAC and tenant ID. 769 770* ``imac``: Set filter type as Inner MAC. 771 772* ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID. 773 774* ``oip``: Set filter type as Outer IP. 775 776* ``iip``: Set filter type as Inner IP. 777 778Example:: 779 780 testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \ 781 192.168.2.2 0 ipingre oip 1 1 782 783 Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP. 784 785tunnel_filter remove 786~~~~~~~~~~~~~~~~~~~~ 787 788Remove a tunnel filter on a port:: 789 790 testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \ 791 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ 792 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) 793 794rx_vxlan_port add 795~~~~~~~~~~~~~~~~~ 796 797Add an UDP port for VXLAN packet filter on a port:: 798 799 testpmd> rx_vxlan_port add (udp_port) (port_id) 800 801rx_vxlan_port remove 802~~~~~~~~~~~~~~~~~~~~ 803 804Remove an UDP port for VXLAN packet filter on a port:: 805 806 testpmd> rx_vxlan_port rm (udp_port) (port_id) 807 808tx_vlan set 809~~~~~~~~~~~ 810 811Set hardware insertion of VLAN IDs in packets sent on a port:: 812 813 testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer] 814 815For example, set a single VLAN ID (5) insertion on port 0:: 816 817 tx_vlan set 0 5 818 819Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1:: 820 821 tx_vlan set 1 2 3 822 823 824tx_vlan set pvid 825~~~~~~~~~~~~~~~~ 826 827Set port based hardware insertion of VLAN ID in packets sent on a port:: 828 829 testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off) 830 831tx_vlan reset 832~~~~~~~~~~~~~ 833 834Disable hardware insertion of a VLAN header in packets sent on a port:: 835 836 testpmd> tx_vlan reset (port_id) 837 838csum set 839~~~~~~~~ 840 841Select hardware or software calculation of the checksum when 842transmitting a packet using the ``csum`` forwarding engine:: 843 844 testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id) 845 846Where: 847 848* ``ip|udp|tcp|sctp`` always relate to the inner layer. 849 850* ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized 851 as a tunnel packet by the forwarding engine (vxlan, gre and ipip are 852 supported). See also the ``csum parse-tunnel`` command. 853 854.. note:: 855 856 Check the NIC Datasheet for hardware limits. 857 858RSS queue region 859~~~~~~~~~~~~~~~~ 860 861Set RSS queue region span on a port:: 862 863 testpmd> set port (port_id) queue-region region_id (value) \ 864 queue_start_index (value) queue_num (value) 865 866Set flowtype mapping on a RSS queue region on a port:: 867 868 testpmd> set port (port_id) queue-region region_id (value) flowtype (value) 869 870where: 871 872* For the flowtype(pctype) of packet,the specific index for each type has 873 been defined in file i40e_type.h as enum i40e_filter_pctype. 874 875Set user priority mapping on a RSS queue region on a port:: 876 877 testpmd> set port (port_id) queue-region UP (value) region_id (value) 878 879Flush all queue region related configuration on a port:: 880 881 testpmd> set port (port_id) queue-region flush (on|off) 882 883where: 884 885* "on"is just an enable function which server for other configuration, 886 it is for all configuration about queue region from up layer, 887 at first will only keep in DPDK softwarestored in driver, 888 only after "flush on", it commit all configuration to HW. 889 "off" is just clean all configuration about queue region just now, 890 and restore all to DPDK i40e driver default config when start up. 891 892Show all queue region related configuration info on a port:: 893 894 testpmd> show port (port_id) queue-region 895 896.. note:: 897 898 Queue region only support on PF by now, so these command is 899 only for configuration of queue region on PF port. 900 901csum parse-tunnel 902~~~~~~~~~~~~~~~~~ 903 904Define how tunneled packets should be handled by the csum forward 905engine:: 906 907 testpmd> csum parse-tunnel (on|off) (tx_port_id) 908 909If enabled, the csum forward engine will try to recognize supported 910tunnel headers (vxlan, gre, ipip). 911 912If disabled, treat tunnel packets as non-tunneled packets (a inner 913header is handled as a packet payload). 914 915.. note:: 916 917 The port argument is the TX port like in the ``csum set`` command. 918 919Example: 920 921Consider a packet in packet like the following:: 922 923 eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in 924 925* If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set`` 926 command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the 927 ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``). 928 929* If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set`` 930 command relate to the outer headers, here ``ipv4_out`` and ``udp_out``. 931 932csum show 933~~~~~~~~~ 934 935Display tx checksum offload configuration:: 936 937 testpmd> csum show (port_id) 938 939tso set 940~~~~~~~ 941 942Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine:: 943 944 testpmd> tso set (segsize) (port_id) 945 946.. note:: 947 948 Check the NIC datasheet for hardware limits. 949 950tso show 951~~~~~~~~ 952 953Display the status of TCP Segmentation Offload:: 954 955 testpmd> tso show (port_id) 956 957set port - gro 958~~~~~~~~~~~~~~ 959 960Enable or disable GRO in ``csum`` forwarding engine:: 961 962 testpmd> set port <port_id> gro on|off 963 964If enabled, the csum forwarding engine will perform GRO on the TCP/IPv4 965packets received from the given port. 966 967If disabled, packets received from the given port won't be performed 968GRO. By default, GRO is disabled for all ports. 969 970.. note:: 971 972 When enable GRO for a port, TCP/IPv4 packets received from the port 973 will be performed GRO. After GRO, all merged packets have bad 974 checksums, since the GRO library doesn't re-calculate checksums for 975 the merged packets. Therefore, if users want the merged packets to 976 have correct checksums, please select HW IP checksum calculation and 977 HW TCP checksum calculation for the port which the merged packets are 978 transmitted to. 979 980show port - gro 981~~~~~~~~~~~~~~~ 982 983Display GRO configuration for a given port:: 984 985 testpmd> show port <port_id> gro 986 987set gro flush 988~~~~~~~~~~~~~ 989 990Set the cycle to flush the GROed packets from reassembly tables:: 991 992 testpmd> set gro flush <cycles> 993 994When enable GRO, the csum forwarding engine performs GRO on received 995packets, and the GROed packets are stored in reassembly tables. Users 996can use this command to determine when the GROed packets are flushed 997from the reassembly tables. 998 999The ``cycles`` is measured in GRO operation times. The csum forwarding 1000engine flushes the GROed packets from the tables every ``cycles`` GRO 1001operations. 1002 1003By default, the value of ``cycles`` is 1, which means flush GROed packets 1004from the reassembly tables as soon as one GRO operation finishes. The value 1005of ``cycles`` should be in the range of 1 to ``GRO_MAX_FLUSH_CYCLES``. 1006 1007Please note that the large value of ``cycles`` may cause the poor TCP/IP 1008stack performance. Because the GROed packets are delayed to arrive the 1009stack, thus causing more duplicated ACKs and TCP retransmissions. 1010 1011set port - gso 1012~~~~~~~~~~~~~~ 1013 1014Toggle per-port GSO support in ``csum`` forwarding engine:: 1015 1016 testpmd> set port <port_id> gso on|off 1017 1018If enabled, the csum forwarding engine will perform GSO on supported IPv4 1019packets, transmitted on the given port. 1020 1021If disabled, packets transmitted on the given port will not undergo GSO. 1022By default, GSO is disabled for all ports. 1023 1024.. note:: 1025 1026 When GSO is enabled on a port, supported IPv4 packets transmitted on that 1027 port undergo GSO. Afterwards, the segmented packets are represented by 1028 multi-segment mbufs; however, the csum forwarding engine doesn't calculation 1029 of checksums for GSO'd segments in SW. As a result, if users want correct 1030 checksums in GSO segments, they should enable HW checksum calculation for 1031 GSO-enabled ports. 1032 1033 For example, HW checksum calculation for VxLAN GSO'd packets may be enabled 1034 by setting the following options in the csum forwarding engine: 1035 1036 testpmd> csum set outer_ip hw <port_id> 1037 1038 testpmd> csum set ip hw <port_id> 1039 1040 testpmd> csum set tcp hw <port_id> 1041 1042set gso segsz 1043~~~~~~~~~~~~~ 1044 1045Set the maximum GSO segment size (measured in bytes), which includes the 1046packet header and the packet payload for GSO-enabled ports (global):: 1047 1048 testpmd> set gso segsz <length> 1049 1050show port - gso 1051~~~~~~~~~~~~~~~ 1052 1053Display the status of Generic Segmentation Offload for a given port:: 1054 1055 testpmd> show port <port_id> gso 1056 1057mac_addr add 1058~~~~~~~~~~~~ 1059 1060Add an alternative MAC address to a port:: 1061 1062 testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX) 1063 1064mac_addr remove 1065~~~~~~~~~~~~~~~ 1066 1067Remove a MAC address from a port:: 1068 1069 testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) 1070 1071mac_addr add (for VF) 1072~~~~~~~~~~~~~~~~~~~~~ 1073 1074Add an alternative MAC address for a VF to a port:: 1075 1076 testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) 1077 1078mac_addr set 1079~~~~~~~~~~~~ 1080 1081Set the default MAC address for a port:: 1082 1083 testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX) 1084 1085mac_addr set (for VF) 1086~~~~~~~~~~~~~~~~~~~~~ 1087 1088Set the MAC address for a VF from the PF:: 1089 1090 testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX) 1091 1092set port-uta 1093~~~~~~~~~~~~ 1094 1095Set the unicast hash filter(s) on/off for a port:: 1096 1097 testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off) 1098 1099set promisc 1100~~~~~~~~~~~ 1101 1102Set the promiscuous mode on for a port or for all ports. 1103In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1104 1105 testpmd> set promisc (port_id|all) (on|off) 1106 1107set allmulti 1108~~~~~~~~~~~~ 1109 1110Set the allmulti mode for a port or for all ports:: 1111 1112 testpmd> set allmulti (port_id|all) (on|off) 1113 1114Same as the ifconfig (8) option. Controls how multicast packets are handled. 1115 1116set promisc (for VF) 1117~~~~~~~~~~~~~~~~~~~~ 1118 1119Set the unicast promiscuous mode for a VF from PF. 1120It's supported by Intel i40e NICs now. 1121In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1122 1123 testpmd> set vf promisc (port_id) (vf_id) (on|off) 1124 1125set allmulticast (for VF) 1126~~~~~~~~~~~~~~~~~~~~~~~~~ 1127 1128Set the multicast promiscuous mode for a VF from PF. 1129It's supported by Intel i40e NICs now. 1130In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1131 1132 testpmd> set vf allmulti (port_id) (vf_id) (on|off) 1133 1134set tx max bandwidth (for VF) 1135~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1136 1137Set TX max absolute bandwidth (Mbps) for a VF from PF:: 1138 1139 testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth) 1140 1141set tc tx min bandwidth (for VF) 1142~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1143 1144Set all TCs' TX min relative bandwidth (%) for a VF from PF:: 1145 1146 testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...) 1147 1148set tc tx max bandwidth (for VF) 1149~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1150 1151Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF:: 1152 1153 testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth) 1154 1155set tc strict link priority mode 1156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1157 1158Set some TCs' strict link priority mode on a physical port:: 1159 1160 testpmd> set tx strict-link-priority (port_id) (tc_bitmap) 1161 1162set tc tx min bandwidth 1163~~~~~~~~~~~~~~~~~~~~~~~ 1164 1165Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs:: 1166 1167 testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...) 1168 1169set flow_ctrl rx 1170~~~~~~~~~~~~~~~~ 1171 1172Set the link flow control parameter on a port:: 1173 1174 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1175 (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \ 1176 autoneg (on|off) (port_id) 1177 1178Where: 1179 1180* ``high_water`` (integer): High threshold value to trigger XOFF. 1181 1182* ``low_water`` (integer): Low threshold value to trigger XON. 1183 1184* ``pause_time`` (integer): Pause quota in the Pause frame. 1185 1186* ``send_xon`` (0/1): Send XON frame. 1187 1188* ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames. 1189 1190* ``autoneg``: Change the auto-negotiation parameter. 1191 1192set pfc_ctrl rx 1193~~~~~~~~~~~~~~~ 1194 1195Set the priority flow control parameter on a port:: 1196 1197 testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1198 (pause_time) (priority) (port_id) 1199 1200Where: 1201 1202* ``high_water`` (integer): High threshold value. 1203 1204* ``low_water`` (integer): Low threshold value. 1205 1206* ``pause_time`` (integer): Pause quota in the Pause frame. 1207 1208* ``priority`` (0-7): VLAN User Priority. 1209 1210set stat_qmap 1211~~~~~~~~~~~~~ 1212 1213Set statistics mapping (qmapping 0..15) for RX/TX queue on port:: 1214 1215 testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping) 1216 1217For example, to set rx queue 2 on port 0 to mapping 5:: 1218 1219 testpmd>set stat_qmap rx 0 2 5 1220 1221set xstats-hide-zero 1222~~~~~~~~~~~~~~~~~~~~ 1223 1224Set the option to hide zero values for xstats display:: 1225 1226 testpmd> set xstats-hide-zero on|off 1227 1228.. note:: 1229 1230 By default, the zero values are displayed for xstats. 1231 1232set port - rx/tx (for VF) 1233~~~~~~~~~~~~~~~~~~~~~~~~~ 1234 1235Set VF receive/transmit from a port:: 1236 1237 testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off) 1238 1239set port - mac address filter (for VF) 1240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1241 1242Add/Remove unicast or multicast MAC addr filter for a VF:: 1243 1244 testpmd> set port (port_id) vf (vf_id) (mac_addr) \ 1245 (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off) 1246 1247set port - rx mode(for VF) 1248~~~~~~~~~~~~~~~~~~~~~~~~~~ 1249 1250Set the VF receive mode of a port:: 1251 1252 testpmd> set port (port_id) vf (vf_id) \ 1253 rxmode (AUPE|ROPE|BAM|MPE) (on|off) 1254 1255The available receive modes are: 1256 1257* ``AUPE``: Accepts untagged VLAN. 1258 1259* ``ROPE``: Accepts unicast hash. 1260 1261* ``BAM``: Accepts broadcast packets. 1262 1263* ``MPE``: Accepts all multicast packets. 1264 1265set port - tx_rate (for Queue) 1266~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1267 1268Set TX rate limitation for a queue on a port:: 1269 1270 testpmd> set port (port_id) queue (queue_id) rate (rate_value) 1271 1272set port - tx_rate (for VF) 1273~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1274 1275Set TX rate limitation for queues in VF on a port:: 1276 1277 testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask) 1278 1279set port - mirror rule 1280~~~~~~~~~~~~~~~~~~~~~~ 1281 1282Set pool or vlan type mirror rule for a port:: 1283 1284 testpmd> set port (port_id) mirror-rule (rule_id) \ 1285 (pool-mirror-up|pool-mirror-down|vlan-mirror) \ 1286 (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) 1287 1288Set link mirror rule for a port:: 1289 1290 testpmd> set port (port_id) mirror-rule (rule_id) \ 1291 (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off) 1292 1293For example to enable mirror traffic with vlan 0,1 to pool 0:: 1294 1295 set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on 1296 1297reset port - mirror rule 1298~~~~~~~~~~~~~~~~~~~~~~~~ 1299 1300Reset a mirror rule for a port:: 1301 1302 testpmd> reset port (port_id) mirror-rule (rule_id) 1303 1304set flush_rx 1305~~~~~~~~~~~~ 1306 1307Set the flush on RX streams before forwarding. 1308The default is flush ``on``. 1309Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams:: 1310 1311 testpmd> set flush_rx off 1312 1313set bypass mode 1314~~~~~~~~~~~~~~~ 1315 1316Set the bypass mode for the lowest port on bypass enabled NIC:: 1317 1318 testpmd> set bypass mode (normal|bypass|isolate) (port_id) 1319 1320set bypass event 1321~~~~~~~~~~~~~~~~ 1322 1323Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled:: 1324 1325 testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \ 1326 mode (normal|bypass|isolate) (port_id) 1327 1328Where: 1329 1330* ``timeout``: Enable bypass after watchdog timeout. 1331 1332* ``os_on``: Enable bypass when OS/board is powered on. 1333 1334* ``os_off``: Enable bypass when OS/board is powered off. 1335 1336* ``power_on``: Enable bypass when power supply is turned on. 1337 1338* ``power_off``: Enable bypass when power supply is turned off. 1339 1340 1341set bypass timeout 1342~~~~~~~~~~~~~~~~~~ 1343 1344Set the bypass watchdog timeout to ``n`` seconds where 0 = instant:: 1345 1346 testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32) 1347 1348show bypass config 1349~~~~~~~~~~~~~~~~~~ 1350 1351Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC:: 1352 1353 testpmd> show bypass config (port_id) 1354 1355set link up 1356~~~~~~~~~~~ 1357 1358Set link up for a port:: 1359 1360 testpmd> set link-up port (port id) 1361 1362set link down 1363~~~~~~~~~~~~~ 1364 1365Set link down for a port:: 1366 1367 testpmd> set link-down port (port id) 1368 1369E-tag set 1370~~~~~~~~~ 1371 1372Enable E-tag insertion for a VF on a port:: 1373 1374 testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id) 1375 1376Disable E-tag insertion for a VF on a port:: 1377 1378 testpmd> E-tag set insertion off port (port_id) vf (vf_id) 1379 1380Enable/disable E-tag stripping on a port:: 1381 1382 testpmd> E-tag set stripping (on|off) port (port_id) 1383 1384Enable/disable E-tag based forwarding on a port:: 1385 1386 testpmd> E-tag set forwarding (on|off) port (port_id) 1387 1388Add an E-tag forwarding filter on a port:: 1389 1390 testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id) 1391 1392Delete an E-tag forwarding filter on a port:: 1393 testpmd> E-tag set filter del e-tag-id (value) port (port_id) 1394 1395ddp add 1396~~~~~~~ 1397 1398Load a dynamic device personalization (DDP) package:: 1399 1400 testpmd> ddp add (port_id) (package_path[,output_path]) 1401 1402ddp del 1403~~~~~~~ 1404 1405Delete a dynamic device personalization package:: 1406 1407 testpmd> ddp del (port_id) (package_path) 1408 1409ptype mapping 1410~~~~~~~~~~~~~ 1411 1412List all items from the ptype mapping table:: 1413 1414 testpmd> ptype mapping get (port_id) (valid_only) 1415 1416Where: 1417 1418* ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0). 1419 1420Replace a specific or a group of software defined ptype with a new one:: 1421 1422 testpmd> ptype mapping replace (port_id) (target) (mask) (pkt_type) 1423 1424where: 1425 1426* ``target``: A specific software ptype or a mask to represent a group of software ptypes. 1427 1428* ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1). 1429 1430* ``pkt_type``: The new software ptype to replace the old ones. 1431 1432Update hardware defined ptype to software defined packet type mapping table:: 1433 1434 testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype) 1435 1436where: 1437 1438* ``hw_ptype``: hardware ptype as the index of the ptype mapping table. 1439 1440* ``sw_ptype``: software ptype as the value of the ptype mapping table. 1441 1442Reset ptype mapping table:: 1443 1444 testpmd> ptype mapping reset (port_id) 1445 1446Port Functions 1447-------------- 1448 1449The following sections show functions for configuring ports. 1450 1451.. note:: 1452 1453 Port configuration changes only become active when forwarding is started/restarted. 1454 1455port attach 1456~~~~~~~~~~~ 1457 1458Attach a port specified by pci address or virtual device args:: 1459 1460 testpmd> port attach (identifier) 1461 1462To attach a new pci device, the device should be recognized by kernel first. 1463Then it should be moved under DPDK management. 1464Finally the port can be attached to testpmd. 1465 1466For example, to move a pci device using ixgbe under DPDK management: 1467 1468.. code-block:: console 1469 1470 # Check the status of the available devices. 1471 ./usertools/dpdk-devbind.py --status 1472 1473 Network devices using DPDK-compatible driver 1474 ============================================ 1475 <none> 1476 1477 Network devices using kernel driver 1478 =================================== 1479 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused= 1480 1481 1482 # Bind the device to igb_uio. 1483 sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0 1484 1485 1486 # Recheck the status of the devices. 1487 ./usertools/dpdk-devbind.py --status 1488 Network devices using DPDK-compatible driver 1489 ============================================ 1490 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= 1491 1492To attach a port created by virtual device, above steps are not needed. 1493 1494For example, to attach a port whose pci address is 0000:0a:00.0. 1495 1496.. code-block:: console 1497 1498 testpmd> port attach 0000:0a:00.0 1499 Attaching a new port... 1500 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1501 EAL: probe driver: 8086:10fb rte_ixgbe_pmd 1502 EAL: PCI memory mapped at 0x7f83bfa00000 1503 EAL: PCI memory mapped at 0x7f83bfa80000 1504 PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5 1505 PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb 1506 Port 0 is attached. Now total ports is 1 1507 Done 1508 1509For example, to attach a port created by pcap PMD. 1510 1511.. code-block:: console 1512 1513 testpmd> port attach net_pcap0 1514 Attaching a new port... 1515 PMD: Initializing pmd_pcap for net_pcap0 1516 PMD: Creating pcap-backed ethdev on numa socket 0 1517 Port 0 is attached. Now total ports is 1 1518 Done 1519 1520In this case, identifier is ``net_pcap0``. 1521This identifier format is the same as ``--vdev`` format of DPDK applications. 1522 1523For example, to re-attach a bonded port which has been previously detached, 1524the mode and slave parameters must be given. 1525 1526.. code-block:: console 1527 1528 testpmd> port attach net_bond_0,mode=0,slave=1 1529 Attaching a new port... 1530 EAL: Initializing pmd_bond for net_bond_0 1531 EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0. 1532 Port 0 is attached. Now total ports is 1 1533 Done 1534 1535 1536port detach 1537~~~~~~~~~~~ 1538 1539Detach a specific port:: 1540 1541 testpmd> port detach (port_id) 1542 1543Before detaching a port, the port should be stopped and closed. 1544 1545For example, to detach a pci device port 0. 1546 1547.. code-block:: console 1548 1549 testpmd> port stop 0 1550 Stopping ports... 1551 Done 1552 testpmd> port close 0 1553 Closing ports... 1554 Done 1555 1556 testpmd> port detach 0 1557 Detaching a port... 1558 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1559 EAL: remove driver: 8086:10fb rte_ixgbe_pmd 1560 EAL: PCI memory unmapped at 0x7f83bfa00000 1561 EAL: PCI memory unmapped at 0x7f83bfa80000 1562 Done 1563 1564 1565For example, to detach a virtual device port 0. 1566 1567.. code-block:: console 1568 1569 testpmd> port stop 0 1570 Stopping ports... 1571 Done 1572 testpmd> port close 0 1573 Closing ports... 1574 Done 1575 1576 testpmd> port detach 0 1577 Detaching a port... 1578 PMD: Closing pcap ethdev on numa socket 0 1579 Port 'net_pcap0' is detached. Now total ports is 0 1580 Done 1581 1582To remove a pci device completely from the system, first detach the port from testpmd. 1583Then the device should be moved under kernel management. 1584Finally the device can be removed using kernel pci hotplug functionality. 1585 1586For example, to move a pci device under kernel management: 1587 1588.. code-block:: console 1589 1590 sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0 1591 1592 ./usertools/dpdk-devbind.py --status 1593 1594 Network devices using DPDK-compatible driver 1595 ============================================ 1596 <none> 1597 1598 Network devices using kernel driver 1599 =================================== 1600 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio 1601 1602To remove a port created by a virtual device, above steps are not needed. 1603 1604port start 1605~~~~~~~~~~ 1606 1607Start all ports or a specific port:: 1608 1609 testpmd> port start (port_id|all) 1610 1611port stop 1612~~~~~~~~~ 1613 1614Stop all ports or a specific port:: 1615 1616 testpmd> port stop (port_id|all) 1617 1618port close 1619~~~~~~~~~~ 1620 1621Close all ports or a specific port:: 1622 1623 testpmd> port close (port_id|all) 1624 1625port start/stop queue 1626~~~~~~~~~~~~~~~~~~~~~ 1627 1628Start/stop a rx/tx queue on a specific port:: 1629 1630 testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop) 1631 1632Only take effect when port is started. 1633 1634port config - speed 1635~~~~~~~~~~~~~~~~~~~ 1636 1637Set the speed and duplex mode for all ports or a specific port:: 1638 1639 testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \ 1640 duplex (half|full|auto) 1641 1642port config - queues/descriptors 1643~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1644 1645Set number of queues/descriptors for rxq, txq, rxd and txd:: 1646 1647 testpmd> port config all (rxq|txq|rxd|txd) (value) 1648 1649This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options. 1650 1651port config - max-pkt-len 1652~~~~~~~~~~~~~~~~~~~~~~~~~ 1653 1654Set the maximum packet length:: 1655 1656 testpmd> port config all max-pkt-len (value) 1657 1658This is equivalent to the ``--max-pkt-len`` command-line option. 1659 1660port config - CRC Strip 1661~~~~~~~~~~~~~~~~~~~~~~~ 1662 1663Set hardware CRC stripping on or off for all ports:: 1664 1665 testpmd> port config all crc-strip (on|off) 1666 1667CRC stripping is on by default. 1668 1669The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option. 1670 1671port config - scatter 1672~~~~~~~~~~~~~~~~~~~~~~~ 1673 1674Set RX scatter mode on or off for all ports:: 1675 1676 testpmd> port config all scatter (on|off) 1677 1678RX scatter mode is off by default. 1679 1680The ``on`` option is equivalent to the ``--enable-scatter`` command-line option. 1681 1682port config - RX Checksum 1683~~~~~~~~~~~~~~~~~~~~~~~~~ 1684 1685Set hardware RX checksum offload to on or off for all ports:: 1686 1687 testpmd> port config all rx-cksum (on|off) 1688 1689Checksum offload is off by default. 1690 1691The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option. 1692 1693port config - VLAN 1694~~~~~~~~~~~~~~~~~~ 1695 1696Set hardware VLAN on or off for all ports:: 1697 1698 testpmd> port config all hw-vlan (on|off) 1699 1700Hardware VLAN is on by default. 1701 1702The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option. 1703 1704port config - VLAN filter 1705~~~~~~~~~~~~~~~~~~~~~~~~~ 1706 1707Set hardware VLAN filter on or off for all ports:: 1708 1709 testpmd> port config all hw-vlan-filter (on|off) 1710 1711Hardware VLAN filter is on by default. 1712 1713The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option. 1714 1715port config - VLAN strip 1716~~~~~~~~~~~~~~~~~~~~~~~~ 1717 1718Set hardware VLAN strip on or off for all ports:: 1719 1720 testpmd> port config all hw-vlan-strip (on|off) 1721 1722Hardware VLAN strip is on by default. 1723 1724The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option. 1725 1726port config - VLAN extend 1727~~~~~~~~~~~~~~~~~~~~~~~~~ 1728 1729Set hardware VLAN extend on or off for all ports:: 1730 1731 testpmd> port config all hw-vlan-extend (on|off) 1732 1733Hardware VLAN extend is off by default. 1734 1735The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option. 1736 1737port config - Drop Packets 1738~~~~~~~~~~~~~~~~~~~~~~~~~~ 1739 1740Set packet drop for packets with no descriptors on or off for all ports:: 1741 1742 testpmd> port config all drop-en (on|off) 1743 1744Packet dropping for packets with no descriptors is off by default. 1745 1746The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option. 1747 1748port config - RSS 1749~~~~~~~~~~~~~~~~~ 1750 1751Set the RSS (Receive Side Scaling) mode on or off:: 1752 1753 testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none) 1754 1755RSS is on by default. 1756 1757The ``none`` option is equivalent to the ``--disable-rss`` command-line option. 1758 1759port config - RSS Reta 1760~~~~~~~~~~~~~~~~~~~~~~ 1761 1762Set the RSS (Receive Side Scaling) redirection table:: 1763 1764 testpmd> port config all rss reta (hash,queue)[,(hash,queue)] 1765 1766port config - DCB 1767~~~~~~~~~~~~~~~~~ 1768 1769Set the DCB mode for an individual port:: 1770 1771 testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off) 1772 1773The traffic class should be 4 or 8. 1774 1775port config - Burst 1776~~~~~~~~~~~~~~~~~~~ 1777 1778Set the number of packets per burst:: 1779 1780 testpmd> port config all burst (value) 1781 1782This is equivalent to the ``--burst`` command-line option. 1783 1784port config - Threshold 1785~~~~~~~~~~~~~~~~~~~~~~~ 1786 1787Set thresholds for TX/RX queues:: 1788 1789 testpmd> port config all (threshold) (value) 1790 1791Where the threshold type can be: 1792 1793* ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255. 1794 1795* ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255. 1796 1797* ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255. 1798 1799* ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255. 1800 1801* ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255. 1802 1803* ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255. 1804 1805* ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd. 1806 1807* ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd. 1808 1809* ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd. 1810 1811These threshold options are also available from the command-line. 1812 1813port config - E-tag 1814~~~~~~~~~~~~~~~~~~~ 1815 1816Set the value of ether-type for E-tag:: 1817 1818 testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value) 1819 1820Enable/disable the E-tag support:: 1821 1822 testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable) 1823 1824port config pctype mapping 1825~~~~~~~~~~~~~~~~~~~~~~~~~~ 1826 1827Reset pctype mapping table:: 1828 1829 testpmd> port config (port_id) pctype mapping reset 1830 1831Update hardware defined pctype to software defined flow type mapping table:: 1832 1833 testpmd> port config (port_id) pctype mapping update (pctype_id_0[,pctype_id_1]*) (flow_type_id) 1834 1835where: 1836 1837* ``pctype_id_x``: hardware pctype id as index of bit in bitmask value of the pctype mapping table. 1838 1839* ``flow_type_id``: software flow type id as the index of the pctype mapping table. 1840 1841 1842Link Bonding Functions 1843---------------------- 1844 1845The Link Bonding functions make it possible to dynamically create and 1846manage link bonding devices from within testpmd interactive prompt. 1847 1848create bonded device 1849~~~~~~~~~~~~~~~~~~~~ 1850 1851Create a new bonding device:: 1852 1853 testpmd> create bonded device (mode) (socket) 1854 1855For example, to create a bonded device in mode 1 on socket 0:: 1856 1857 testpmd> create bonded 1 0 1858 created new bonded device (port X) 1859 1860add bonding slave 1861~~~~~~~~~~~~~~~~~ 1862 1863Adds Ethernet device to a Link Bonding device:: 1864 1865 testpmd> add bonding slave (slave id) (port id) 1866 1867For example, to add Ethernet device (port 6) to a Link Bonding device (port 10):: 1868 1869 testpmd> add bonding slave 6 10 1870 1871 1872remove bonding slave 1873~~~~~~~~~~~~~~~~~~~~ 1874 1875Removes an Ethernet slave device from a Link Bonding device:: 1876 1877 testpmd> remove bonding slave (slave id) (port id) 1878 1879For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10):: 1880 1881 testpmd> remove bonding slave 6 10 1882 1883set bonding mode 1884~~~~~~~~~~~~~~~~ 1885 1886Set the Link Bonding mode of a Link Bonding device:: 1887 1888 testpmd> set bonding mode (value) (port id) 1889 1890For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3):: 1891 1892 testpmd> set bonding mode 3 10 1893 1894set bonding primary 1895~~~~~~~~~~~~~~~~~~~ 1896 1897Set an Ethernet slave device as the primary device on a Link Bonding device:: 1898 1899 testpmd> set bonding primary (slave id) (port id) 1900 1901For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10):: 1902 1903 testpmd> set bonding primary 6 10 1904 1905set bonding mac 1906~~~~~~~~~~~~~~~ 1907 1908Set the MAC address of a Link Bonding device:: 1909 1910 testpmd> set bonding mac (port id) (mac) 1911 1912For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01:: 1913 1914 testpmd> set bonding mac 10 00:00:00:00:00:01 1915 1916set bonding xmit_balance_policy 1917~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1918 1919Set the transmission policy for a Link Bonding device when it is in Balance XOR mode:: 1920 1921 testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34) 1922 1923For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports):: 1924 1925 testpmd> set bonding xmit_balance_policy 10 l34 1926 1927 1928set bonding mon_period 1929~~~~~~~~~~~~~~~~~~~~~~ 1930 1931Set the link status monitoring polling period in milliseconds for a bonding device. 1932 1933This adds support for PMD slave devices which do not support link status interrupts. 1934When the mon_period is set to a value greater than 0 then all PMD's which do not support 1935link status ISR will be queried every polling interval to check if their link status has changed:: 1936 1937 testpmd> set bonding mon_period (port_id) (value) 1938 1939For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms:: 1940 1941 testpmd> set bonding mon_period 5 150 1942 1943 1944set bonding lacp dedicated_queue 1945~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1946 1947Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic 1948when in mode 4 (link-aggregration-802.3ad):: 1949 1950 testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable) 1951 1952 1953set bonding agg_mode 1954~~~~~~~~~~~~~~~~~~~~ 1955 1956Enable one of the specific aggregators mode when in mode 4 (link-aggregration-802.3ad):: 1957 1958 testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable) 1959 1960 1961show bonding config 1962~~~~~~~~~~~~~~~~~~~ 1963 1964Show the current configuration of a Link Bonding device:: 1965 1966 testpmd> show bonding config (port id) 1967 1968For example, 1969to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4) 1970in balance mode with a transmission policy of layer 2+3:: 1971 1972 testpmd> show bonding config 9 1973 Bonding mode: 2 1974 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23 1975 Slaves (3): [1 3 4] 1976 Active Slaves (3): [1 3 4] 1977 Primary: [3] 1978 1979 1980Register Functions 1981------------------ 1982 1983The Register Functions can be used to read from and write to registers on the network card referenced by a port number. 1984This is mainly useful for debugging purposes. 1985Reference should be made to the appropriate datasheet for the network card for details on the register addresses 1986and fields that can be accessed. 1987 1988read reg 1989~~~~~~~~ 1990 1991Display the value of a port register:: 1992 1993 testpmd> read reg (port_id) (address) 1994 1995For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller:: 1996 1997 testpmd> read reg 0 0xEE00 1998 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) 1999 2000read regfield 2001~~~~~~~~~~~~~ 2002 2003Display a port register bit field:: 2004 2005 testpmd> read regfield (port_id) (address) (bit_x) (bit_y) 2006 2007For example, reading the lowest two bits from the register in the example above:: 2008 2009 testpmd> read regfield 0 0xEE00 0 1 2010 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1) 2011 2012read regbit 2013~~~~~~~~~~~ 2014 2015Display a single port register bit:: 2016 2017 testpmd> read regbit (port_id) (address) (bit_x) 2018 2019For example, reading the lowest bit from the register in the example above:: 2020 2021 testpmd> read regbit 0 0xEE00 0 2022 port 0 PCI register at offset 0xEE00: bit 0=1 2023 2024write reg 2025~~~~~~~~~ 2026 2027Set the value of a port register:: 2028 2029 testpmd> write reg (port_id) (address) (value) 2030 2031For example, to clear a register:: 2032 2033 testpmd> write reg 0 0xEE00 0x0 2034 port 0 PCI register at offset 0xEE00: 0x00000000 (0) 2035 2036write regfield 2037~~~~~~~~~~~~~~ 2038 2039Set bit field of a port register:: 2040 2041 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value) 2042 2043For example, writing to the register cleared in the example above:: 2044 2045 testpmd> write regfield 0 0xEE00 0 1 2 2046 port 0 PCI register at offset 0xEE00: 0x00000002 (2) 2047 2048write regbit 2049~~~~~~~~~~~~ 2050 2051Set single bit value of a port register:: 2052 2053 testpmd> write regbit (port_id) (address) (bit_x) (value) 2054 2055For example, to set the high bit in the register from the example above:: 2056 2057 testpmd> write regbit 0 0xEE00 31 1 2058 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) 2059 2060Traffic Metering and Policing 2061----------------------------- 2062 2063The following section shows functions for configuring traffic metering and 2064policing on the ethernet device through the use of generic ethdev API. 2065 2066show port traffic management capability 2067~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2068 2069Show traffic metering and policing capability of the port:: 2070 2071 testpmd> show port meter cap (port_id) 2072 2073add port meter profile (srTCM rfc2967) 2074~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2075 2076Add meter profile (srTCM rfc2697) to the ethernet device:: 2077 2078 testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \ 2079 (cir) (cbs) (ebs) 2080 2081where: 2082 2083* ``profile_id``: ID for the meter profile. 2084* ``cir``: Committed Information Rate (CIR) (bytes/second). 2085* ``cbs``: Committed Burst Size (CBS) (bytes). 2086* ``ebs``: Excess Burst Size (EBS) (bytes). 2087 2088add port meter profile (trTCM rfc2968) 2089~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2090 2091Add meter profile (srTCM rfc2698) to the ethernet device:: 2092 2093 testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \ 2094 (cir) (pir) (cbs) (pbs) 2095 2096where: 2097 2098* ``profile_id``: ID for the meter profile. 2099* ``cir``: Committed information rate (bytes/second). 2100* ``pir``: Peak information rate (bytes/second). 2101* ``cbs``: Committed burst size (bytes). 2102* ``pbs``: Peak burst size (bytes). 2103 2104add port meter profile (trTCM rfc4115) 2105~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2106 2107Add meter profile (trTCM rfc4115) to the ethernet device:: 2108 2109 testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \ 2110 (cir) (eir) (cbs) (ebs) 2111 2112where: 2113 2114* ``profile_id``: ID for the meter profile. 2115* ``cir``: Committed information rate (bytes/second). 2116* ``eir``: Excess information rate (bytes/second). 2117* ``cbs``: Committed burst size (bytes). 2118* ``ebs``: Excess burst size (bytes). 2119 2120delete port meter profile 2121~~~~~~~~~~~~~~~~~~~~~~~~~ 2122 2123Delete meter profile from the ethernet device:: 2124 2125 testpmd> del port meter profile (port_id) (profile_id) 2126 2127create port meter 2128~~~~~~~~~~~~~~~~~ 2129 2130Create new meter object for the ethernet device:: 2131 2132 testpmd> create port meter (port_id) (mtr_id) (profile_id) \ 2133 (meter_enable) (g_action) (y_action) (r_action) (stats_mask) (shared) \ 2134 (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\ 2135 (dscp_tbl_entry63)] 2136 2137where: 2138 2139* ``mtr_id``: meter object ID. 2140* ``profile_id``: ID for the meter profile. 2141* ``meter_enable``: When this parameter has a non-zero value, the meter object 2142 gets enabled at the time of creation, otherwise remains disabled. 2143* ``g_action``: Policer action for the packet with green color. 2144* ``y_action``: Policer action for the packet with yellow color. 2145* ``r_action``: Policer action for the packet with red color. 2146* ``stats_mask``: Mask of statistics counter types to be enabled for the 2147 meter object. 2148* ``shared``: When this parameter has a non-zero value, the meter object is 2149 shared by multiple flows. Otherwise, meter object is used by single flow. 2150* ``use_pre_meter_color``: When this parameter has a non-zero value, the 2151 input color for the current meter object is determined by the latest meter 2152 object in the same flow. Otherwise, the current meter object uses the 2153 *dscp_table* to determine the input color. 2154* ``dscp_tbl_entryx``: DSCP table entry x providing meter providing input 2155 color, 0 <= x <= 63. 2156 2157enable port meter 2158~~~~~~~~~~~~~~~~~ 2159 2160Enable meter for the ethernet device:: 2161 2162 testpmd> enable port meter (port_id) (mtr_id) 2163 2164disable port meter 2165~~~~~~~~~~~~~~~~~~ 2166 2167Disable meter for the ethernet device:: 2168 2169 testpmd> disable port meter (port_id) (mtr_id) 2170 2171delete port meter 2172~~~~~~~~~~~~~~~~~ 2173 2174Delete meter for the ethernet device:: 2175 2176 testpmd> del port meter (port_id) (mtr_id) 2177 2178Set port meter profile 2179~~~~~~~~~~~~~~~~~~~~~~ 2180 2181Set meter profile for the ethernet device:: 2182 2183 testpmd> set port meter profile (port_id) (mtr_id) (profile_id) 2184 2185set port meter dscp table 2186~~~~~~~~~~~~~~~~~~~~~~~~~ 2187 2188Set meter dscp table for the ethernet device:: 2189 2190 testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \ 2191 (dscp_tbl_entry1)...(dscp_tbl_entry63)] 2192 2193set port meter policer action 2194~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2195 2196Set meter policer action for the ethernet device:: 2197 2198 testpmd> set port meter policer action (port_id) (mtr_id) (action_mask) \ 2199 (action0) [(action1) (action1)] 2200 2201where: 2202 2203* ``action_mask``: Bit mask indicating which policer actions need to be 2204 updated. One or more policer actions can be updated in a single function 2205 invocation. To update the policer action associated with color C, bit 2206 (1 << C) needs to be set in *action_mask* and element at position C 2207 in the *actions* array needs to be valid. 2208* ``actionx``: Policer action for the color x, 2209 RTE_MTR_GREEN <= x < RTE_MTR_COLORS 2210 2211set port meter stats mask 2212~~~~~~~~~~~~~~~~~~~~~~~~~ 2213 2214Set meter stats mask for the ethernet device:: 2215 2216 testpmd> set port meter stats mask (port_id) (mtr_id) (stats_mask) 2217 2218where: 2219 2220* ``stats_mask``: Bit mask indicating statistics counter types to be enabled. 2221 2222show port meter stats 2223~~~~~~~~~~~~~~~~~~~~~ 2224 2225Show meter stats of the ethernet device:: 2226 2227 testpmd> show port meter stats (port_id) (mtr_id) (clear) 2228 2229where: 2230 2231* ``clear``: Flag that indicates whether the statistics counters should 2232 be cleared (i.e. set to zero) immediately after they have been read or not. 2233 2234Traffic Management 2235------------------ 2236 2237The following section shows functions for configuring traffic management on 2238on the ethernet device through the use of generic TM API. 2239 2240show port traffic management capability 2241~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2242 2243Show traffic management capability of the port:: 2244 2245 testpmd> show port tm cap (port_id) 2246 2247show port traffic management capability (hierarchy level) 2248~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2249 2250Show traffic management hierarchy level capability of the port:: 2251 2252 testpmd> show port tm cap (port_id) (level_id) 2253 2254show port traffic management capability (hierarchy node level) 2255~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2256 2257Show the traffic management hierarchy node capability of the port:: 2258 2259 testpmd> show port tm cap (port_id) (node_id) 2260 2261show port traffic management hierarchy node type 2262~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2263 2264Show the port traffic management hierarchy node type:: 2265 2266 testpmd> show port tm node type (port_id) (node_id) 2267 2268show port traffic management hierarchy node stats 2269~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2270 2271Show the port traffic management hierarchy node statistics:: 2272 2273 testpmd> show port tm node stats (port_id) (node_id) (clear) 2274 2275where: 2276 2277* ``clear``: When this parameter has a non-zero value, the statistics counters 2278 are cleared (i.e. set to zero) immediately after they have been read, 2279 otherwise the statistics counters are left untouched. 2280 2281Add port traffic management private shaper profile 2282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2283 2284Add the port traffic management private shaper profile:: 2285 2286 testpmd> add port tm node shaper profile (port_id) (shaper_profile_id) \ 2287 (tb_rate) (tb_size) (packet_length_adjust) 2288 2289where: 2290 2291* ``shaper_profile id``: Shaper profile ID for the new profile. 2292* ``tb_rate``: Token bucket rate (bytes per second). 2293* ``tb_size``: Token bucket size (bytes). 2294* ``packet_length_adjust``: The value (bytes) to be added to the length of 2295 each packet for the purpose of shaping. This parameter value can be used to 2296 correct the packet length with the framing overhead bytes that are consumed 2297 on the wire. 2298 2299Delete port traffic management private shaper profile 2300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2301 2302Delete the port traffic management private shaper:: 2303 2304 testpmd> del port tm node shaper profile (port_id) (shaper_profile_id) 2305 2306where: 2307 2308* ``shaper_profile id``: Shaper profile ID that needs to be deleted. 2309 2310Add port traffic management shared shaper 2311~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2312 2313Create the port traffic management shared shaper:: 2314 2315 testpmd> add port tm node shared shaper (port_id) (shared_shaper_id) \ 2316 (shaper_profile_id) 2317 2318where: 2319 2320* ``shared_shaper_id``: Shared shaper ID to be created. 2321* ``shaper_profile id``: Shaper profile ID for shared shaper. 2322 2323Set port traffic management shared shaper 2324~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2325 2326Update the port traffic management shared shaper:: 2327 2328 testpmd> set port tm node shared shaper (port_id) (shared_shaper_id) \ 2329 (shaper_profile_id) 2330 2331where: 2332 2333* ``shared_shaper_id``: Shared shaper ID to be update. 2334* ``shaper_profile id``: Shaper profile ID for shared shaper. 2335 2336Delete port traffic management shared shaper 2337~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2338 2339Delete the port traffic management shared shaper:: 2340 2341 testpmd> del port tm node shared shaper (port_id) (shared_shaper_id) 2342 2343where: 2344 2345* ``shared_shaper_id``: Shared shaper ID to be deleted. 2346 2347Set port traffic management hiearchy node private shaper 2348~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2349 2350set the port traffic management hierarchy node private shaper:: 2351 2352 testpmd> set port tm node shaper profile (port_id) (node_id) \ 2353 (shaper_profile_id) 2354 2355where: 2356 2357* ``shaper_profile id``: Private shaper profile ID to be enabled on the 2358 hierarchy node. 2359 2360Add port traffic management WRED profile 2361~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2362 2363Create a new WRED profile:: 2364 2365 testpmd> add port tm node wred profile (port_id) (wred_profile_id) \ 2366 (color_g) (min_th_g) (max_th_g) (maxp_inv_g) (wq_log2_g) \ 2367 (color_y) (min_th_y) (max_th_y) (maxp_inv_y) (wq_log2_y) \ 2368 (color_r) (min_th_r) (max_th_r) (maxp_inv_r) (wq_log2_r) 2369 2370where: 2371 2372* ``wred_profile id``: Identifier for the newly create WRED profile 2373* ``color_g``: Packet color (green) 2374* ``min_th_g``: Minimum queue threshold for packet with green color 2375* ``max_th_g``: Minimum queue threshold for packet with green color 2376* ``maxp_inv_g``: Inverse of packet marking probability maximum value (maxp) 2377* ``wq_log2_g``: Negated log2 of queue weight (wq) 2378* ``color_y``: Packet color (yellow) 2379* ``min_th_y``: Minimum queue threshold for packet with yellow color 2380* ``max_th_y``: Minimum queue threshold for packet with yellow color 2381* ``maxp_inv_y``: Inverse of packet marking probability maximum value (maxp) 2382* ``wq_log2_y``: Negated log2 of queue weight (wq) 2383* ``color_r``: Packet color (red) 2384* ``min_th_r``: Minimum queue threshold for packet with yellow color 2385* ``max_th_r``: Minimum queue threshold for packet with yellow color 2386* ``maxp_inv_r``: Inverse of packet marking probability maximum value (maxp) 2387* ``wq_log2_r``: Negated log2 of queue weight (wq) 2388 2389Delete port traffic management WRED profile 2390~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2391 2392Delete the WRED profile:: 2393 2394 testpmd> del port tm node wred profile (port_id) (wred_profile_id) 2395 2396Add port traffic management hierarchy nonleaf node 2397~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2398 2399Add nonleaf node to port traffic management hiearchy:: 2400 2401 testpmd> add port tm nonleaf node (port_id) (node_id) (parent_node_id) \ 2402 (priority) (weight) (level_id) (shaper_profile_id) \ 2403 (n_sp_priorities) (stats_mask) (n_shared_shapers) \ 2404 [(shared_shaper_0) (shared_shaper_1) ...] \ 2405 2406where: 2407 2408* ``parent_node_id``: Node ID of the parent. 2409* ``priority``: Node priority (highest node priority is zero). This is used by 2410 the SP algorithm running on the parent node for scheduling this node. 2411* ``weight``: Node weight (lowest weight is one). The node weight is relative 2412 to the weight sum of all siblings that have the same priority. It is used by 2413 the WFQ algorithm running on the parent node for scheduling this node. 2414* ``level_id``: Hiearchy level of the node. 2415* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2416 the node. 2417* ``n_sp_priorities``: Number of strict priorities. 2418* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2419* ``n_shared_shapers``: Number of shared shapers. 2420* ``shared_shaper_id``: Shared shaper id. 2421 2422Add port traffic management hierarchy leaf node 2423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2424 2425Add leaf node to port traffic management hiearchy:: 2426 2427 testpmd> add port tm leaf node (port_id) (node_id) (parent_node_id) \ 2428 (priority) (weight) (level_id) (shaper_profile_id) \ 2429 (cman_mode) (wred_profile_id) (stats_mask) (n_shared_shapers) \ 2430 [(shared_shaper_id) (shared_shaper_id) ...] \ 2431 2432where: 2433 2434* ``parent_node_id``: Node ID of the parent. 2435* ``priority``: Node priority (highest node priority is zero). This is used by 2436 the SP algorithm running on the parent node for scheduling this node. 2437* ``weight``: Node weight (lowest weight is one). The node weight is relative 2438 to the weight sum of all siblings that have the same priority. It is used by 2439 the WFQ algorithm running on the parent node for scheduling this node. 2440* ``level_id``: Hiearchy level of the node. 2441* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2442 the node. 2443* ``cman_mode``: Congestion management mode to be enabled for this node. 2444* ``wred_profile_id``: WRED profile id to be enabled for this node. 2445* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2446* ``n_shared_shapers``: Number of shared shapers. 2447* ``shared_shaper_id``: Shared shaper id. 2448 2449Delete port traffic management hierarchy node 2450~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2451 2452Delete node from port traffic management hiearchy:: 2453 2454 testpmd> del port tm node (port_id) (node_id) 2455 2456Update port traffic management hierarchy parent node 2457~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2458 2459Update port traffic management hierarchy parent node:: 2460 2461 testpmd> set port tm node parent (port_id) (node_id) (parent_node_id) \ 2462 (priority) (weight) 2463 2464This function can only be called after the hierarchy commit invocation. Its 2465success depends on the port support for this operation, as advertised through 2466the port capability set. This function is valid for all nodes of the traffic 2467management hierarchy except root node. 2468 2469Commit port traffic management hierarchy 2470~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2471 2472Commit the traffic management hierarchy on the port:: 2473 2474 testpmd> port tm hierarchy commit (port_id) (clean_on_fail) 2475 2476where: 2477 2478* ``clean_on_fail``: When set to non-zero, hierarchy is cleared on function 2479 call failure. On the other hand, hierarchy is preserved when this parameter 2480 is equal to zero. 2481 2482Set port traffic management default hierarchy (tm forwarding mode) 2483~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2484 2485set the traffic management default hierarchy on the port:: 2486 2487 testpmd> set port tm hierarchy default (port_id) 2488 2489Filter Functions 2490---------------- 2491 2492This section details the available filter functions that are available. 2493 2494Note these functions interface the deprecated legacy filtering framework, 2495superseded by *rte_flow*. See `Flow rules management`_. 2496 2497ethertype_filter 2498~~~~~~~~~~~~~~~~~~~~ 2499 2500Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue:: 2501 2502 ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \ 2503 ethertype (ether_type) (drop|fwd) queue (queue_id) 2504 2505The available information parameters are: 2506 2507* ``port_id``: The port which the Ethertype filter assigned on. 2508 2509* ``mac_addr``: Compare destination mac address. 2510 2511* ``mac_ignr``: Ignore destination mac address match. 2512 2513* ``mac_address``: Destination mac address to match. 2514 2515* ``ether_type``: The EtherType value want to match, 2516 for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid. 2517 2518* ``queue_id``: The receive queue associated with this EtherType filter. 2519 It is meaningless when deleting or dropping. 2520 2521Example, to add/remove an ethertype filter rule:: 2522 2523 testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \ 2524 ethertype 0x0806 fwd queue 3 2525 2526 testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \ 2527 ethertype 0x0806 fwd queue 3 2528 25292tuple_filter 2530~~~~~~~~~~~~~~~~~ 2531 2532Add or delete a 2-tuple filter, 2533which identifies packets by specific protocol and destination TCP/UDP port 2534and forwards packets into one of the receive queues:: 2535 2536 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \ 2537 protocol (protocol_value) mask (mask_value) \ 2538 tcp_flags (tcp_flags_value) priority (prio_value) \ 2539 queue (queue_id) 2540 2541The available information parameters are: 2542 2543* ``port_id``: The port which the 2-tuple filter assigned on. 2544 2545* ``dst_port_value``: Destination port in L4. 2546 2547* ``protocol_value``: IP L4 protocol. 2548 2549* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate. 2550 2551* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP). 2552 2553* ``prio_value``: Priority of this filter. 2554 2555* ``queue_id``: The receive queue associated with this 2-tuple filter. 2556 2557Example, to add/remove an 2tuple filter rule:: 2558 2559 testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \ 2560 tcp_flags 0x02 priority 3 queue 3 2561 2562 testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \ 2563 tcp_flags 0x02 priority 3 queue 3 2564 25655tuple_filter 2566~~~~~~~~~~~~~~~~~ 2567 2568Add or delete a 5-tuple filter, 2569which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port) 2570and routes packets into one of the receive queues:: 2571 2572 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \ 2573 (src_address) dst_port (dst_port_value) \ 2574 src_port (src_port_value) protocol (protocol_value) \ 2575 mask (mask_value) tcp_flags (tcp_flags_value) \ 2576 priority (prio_value) queue (queue_id) 2577 2578The available information parameters are: 2579 2580* ``port_id``: The port which the 5-tuple filter assigned on. 2581 2582* ``dst_address``: Destination IP address. 2583 2584* ``src_address``: Source IP address. 2585 2586* ``dst_port_value``: TCP/UDP destination port. 2587 2588* ``src_port_value``: TCP/UDP source port. 2589 2590* ``protocol_value``: L4 protocol. 2591 2592* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate 2593 2594* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP). 2595 2596* ``prio_value``: The priority of this filter. 2597 2598* ``queue_id``: The receive queue associated with this 5-tuple filter. 2599 2600Example, to add/remove an 5tuple filter rule:: 2601 2602 testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2603 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2604 flags 0x0 priority 3 queue 3 2605 2606 testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2607 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2608 flags 0x0 priority 3 queue 3 2609 2610syn_filter 2611~~~~~~~~~~ 2612 2613Using the SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue:: 2614 2615 syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) 2616 2617The available information parameters are: 2618 2619* ``port_id``: The port which the SYN filter assigned on. 2620 2621* ``high``: This SYN filter has higher priority than other filters. 2622 2623* ``low``: This SYN filter has lower priority than other filters. 2624 2625* ``queue_id``: The receive queue associated with this SYN filter 2626 2627Example:: 2628 2629 testpmd> syn_filter 0 add priority high queue 3 2630 2631flex_filter 2632~~~~~~~~~~~ 2633 2634With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet 2635and routed into one of the receive queues:: 2636 2637 flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \ 2638 mask (mask_value) priority (prio_value) queue (queue_id) 2639 2640The available information parameters are: 2641 2642* ``port_id``: The port which the Flex filter is assigned on. 2643 2644* ``len_value``: Filter length in bytes, no greater than 128. 2645 2646* ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match. 2647 2648* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match. 2649 2650* ``prio_value``: The priority of this filter. 2651 2652* ``queue_id``: The receive queue associated with this Flex filter. 2653 2654Example:: 2655 2656 testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \ 2657 mask 000C priority 3 queue 3 2658 2659 testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \ 2660 mask 000C priority 3 queue 3 2661 2662 2663.. _testpmd_flow_director: 2664 2665flow_director_filter 2666~~~~~~~~~~~~~~~~~~~~ 2667 2668The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues. 2669 2670Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and 2671Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter: 2672 2673* Perfect match filters. 2674 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2675 The masked fields are for IP flow. 2676 2677* Signature filters. 2678 The hardware checks a match between a hash-based signature of the masked fields of the received packet. 2679 2680* Perfect-mac-vlan match filters. 2681 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2682 The masked fields are for MAC VLAN flow. 2683 2684* Perfect-tunnel match filters. 2685 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2686 The masked fields are for tunnel flow. 2687 2688The Flow Director filters can match the different fields for different type of packet: flow type, specific input set 2689per flow type and the flexible payload. 2690 2691The Flow Director can also mask out parts of all of these fields so that filters 2692are only applied to certain fields or parts of the fields. 2693 2694Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information. 2695 2696# Commands to add flow director filters of different flow types:: 2697 2698 flow_director_filter (port_id) mode IP (add|del|update) \ 2699 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ 2700 src (src_ip_address) dst (dst_ip_address) \ 2701 tos (tos_value) proto (proto_value) ttl (ttl_value) \ 2702 vlan (vlan_value) flexbytes (flexbytes_value) \ 2703 (drop|fwd) pf|vf(vf_id) queue (queue_id) \ 2704 fd_id (fd_id_value) 2705 2706 flow_director_filter (port_id) mode IP (add|del|update) \ 2707 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ 2708 src (src_ip_address) (src_port) \ 2709 dst (dst_ip_address) (dst_port) \ 2710 tos (tos_value) ttl (ttl_value) \ 2711 vlan (vlan_value) flexbytes (flexbytes_value) \ 2712 (drop|fwd) queue pf|vf(vf_id) (queue_id) \ 2713 fd_id (fd_id_value) 2714 2715 flow_director_filter (port_id) mode IP (add|del|update) \ 2716 flow (ipv4-sctp|ipv6-sctp) \ 2717 src (src_ip_address) (src_port) \ 2718 dst (dst_ip_address) (dst_port) \ 2719 tos (tos_value) ttl (ttl_value) \ 2720 tag (verification_tag) vlan (vlan_value) \ 2721 flexbytes (flexbytes_value) (drop|fwd) \ 2722 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) 2723 2724 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ 2725 ether (ethertype) flexbytes (flexbytes_value) \ 2726 (drop|fwd) pf|vf(vf_id) queue (queue_id) 2727 fd_id (fd_id_value) 2728 2729 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ 2730 mac (mac_address) vlan (vlan_value) \ 2731 flexbytes (flexbytes_value) (drop|fwd) \ 2732 queue (queue_id) fd_id (fd_id_value) 2733 2734 flow_director_filter (port_id) mode Tunnel (add|del|update) \ 2735 mac (mac_address) vlan (vlan_value) \ 2736 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ 2737 flexbytes (flexbytes_value) (drop|fwd) \ 2738 queue (queue_id) fd_id (fd_id_value) 2739 2740For example, to add an ipv4-udp flow type filter:: 2741 2742 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ 2743 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ 2744 fwd pf queue 1 fd_id 1 2745 2746For example, add an ipv4-other flow type filter:: 2747 2748 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ 2749 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ 2750 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 2751 2752flush_flow_director 2753~~~~~~~~~~~~~~~~~~~ 2754 2755Flush all flow director filters on a device:: 2756 2757 testpmd> flush_flow_director (port_id) 2758 2759Example, to flush all flow director filter on port 0:: 2760 2761 testpmd> flush_flow_director 0 2762 2763flow_director_mask 2764~~~~~~~~~~~~~~~~~~ 2765 2766Set flow director's input masks:: 2767 2768 flow_director_mask (port_id) mode IP vlan (vlan_value) \ 2769 src_mask (ipv4_src) (ipv6_src) (src_port) \ 2770 dst_mask (ipv4_dst) (ipv6_dst) (dst_port) 2771 2772 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) 2773 2774 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ 2775 mac (mac_value) tunnel-type (tunnel_type_value) \ 2776 tunnel-id (tunnel_id_value) 2777 2778Example, to set flow director mask on port 0:: 2779 2780 testpmd> flow_director_mask 0 mode IP vlan 0xefff \ 2781 src_mask 255.255.255.255 \ 2782 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ 2783 dst_mask 255.255.255.255 \ 2784 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF 2785 2786flow_director_flex_mask 2787~~~~~~~~~~~~~~~~~~~~~~~ 2788 2789set masks of flow director's flexible payload based on certain flow type:: 2790 2791 testpmd> flow_director_flex_mask (port_id) \ 2792 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2793 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ 2794 l2_payload|all) (mask) 2795 2796Example, to set flow director's flex mask for all flow type on port 0:: 2797 2798 testpmd> flow_director_flex_mask 0 flow all \ 2799 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 2800 2801 2802flow_director_flex_payload 2803~~~~~~~~~~~~~~~~~~~~~~~~~~ 2804 2805Configure flexible payload selection:: 2806 2807 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) 2808 2809For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload:: 2810 2811 testpmd> flow_director_flex_payload 0 l4 \ 2812 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) 2813 2814get_sym_hash_ena_per_port 2815~~~~~~~~~~~~~~~~~~~~~~~~~ 2816 2817Get symmetric hash enable configuration per port:: 2818 2819 get_sym_hash_ena_per_port (port_id) 2820 2821For example, to get symmetric hash enable configuration of port 1:: 2822 2823 testpmd> get_sym_hash_ena_per_port 1 2824 2825set_sym_hash_ena_per_port 2826~~~~~~~~~~~~~~~~~~~~~~~~~ 2827 2828Set symmetric hash enable configuration per port to enable or disable:: 2829 2830 set_sym_hash_ena_per_port (port_id) (enable|disable) 2831 2832For example, to set symmetric hash enable configuration of port 1 to enable:: 2833 2834 testpmd> set_sym_hash_ena_per_port 1 enable 2835 2836get_hash_global_config 2837~~~~~~~~~~~~~~~~~~~~~~ 2838 2839Get the global configurations of hash filters:: 2840 2841 get_hash_global_config (port_id) 2842 2843For example, to get the global configurations of hash filters of port 1:: 2844 2845 testpmd> get_hash_global_config 1 2846 2847set_hash_global_config 2848~~~~~~~~~~~~~~~~~~~~~~ 2849 2850Set the global configurations of hash filters:: 2851 2852 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ 2853 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \ 2854 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \ 2855 (enable|disable) 2856 2857For example, to enable simple_xor for flow type of ipv6 on port 2:: 2858 2859 testpmd> set_hash_global_config 2 simple_xor ipv6 enable 2860 2861set_hash_input_set 2862~~~~~~~~~~~~~~~~~~ 2863 2864Set the input set for hash:: 2865 2866 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2867 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2868 l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2869 ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ 2870 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ 2871 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ 2872 fld-8th|none) (select|add) 2873 2874For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: 2875 2876 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add 2877 2878set_fdir_input_set 2879~~~~~~~~~~~~~~~~~~ 2880 2881The Flow Director filters can match the different fields for different type of packet, i.e. specific input set 2882on per flow type and the flexible payload. This command can be used to change input set for each flow type. 2883 2884Set the input set for flow director:: 2885 2886 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2887 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2888 l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2889 ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ 2890 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ 2891 sctp-dst-port|sctp-veri-tag|none) (select|add) 2892 2893For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: 2894 2895 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add 2896 2897global_config 2898~~~~~~~~~~~~~ 2899 2900Set different GRE key length for input set:: 2901 2902 global_config (port_id) gre-key-len (number in bytes) 2903 2904For example to set GRE key length for input set to 4 bytes on port 0:: 2905 2906 testpmd> global_config 0 gre-key-len 4 2907 2908 2909.. _testpmd_rte_flow: 2910 2911Flow rules management 2912--------------------- 2913 2914Control of the generic flow API (*rte_flow*) is fully exposed through the 2915``flow`` command (validation, creation, destruction, queries and operation 2916modes). 2917 2918Considering *rte_flow* overlaps with all `Filter Functions`_, using both 2919features simultaneously may cause undefined side-effects and is therefore 2920not recommended. 2921 2922``flow`` syntax 2923~~~~~~~~~~~~~~~ 2924 2925Because the ``flow`` command uses dynamic tokens to handle the large number 2926of possible flow rules combinations, its behavior differs slightly from 2927other commands, in particular: 2928 2929- Pressing *?* or the *<tab>* key displays contextual help for the current 2930 token, not that of the entire command. 2931 2932- Optional and repeated parameters are supported (provided they are listed 2933 in the contextual help). 2934 2935The first parameter stands for the operation mode. Possible operations and 2936their general syntax are described below. They are covered in detail in the 2937following sections. 2938 2939- Check whether a flow rule can be created:: 2940 2941 flow validate {port_id} 2942 [group {group_id}] [priority {level}] [ingress] [egress] 2943 pattern {item} [/ {item} [...]] / end 2944 actions {action} [/ {action} [...]] / end 2945 2946- Create a flow rule:: 2947 2948 flow create {port_id} 2949 [group {group_id}] [priority {level}] [ingress] [egress] 2950 pattern {item} [/ {item} [...]] / end 2951 actions {action} [/ {action} [...]] / end 2952 2953- Destroy specific flow rules:: 2954 2955 flow destroy {port_id} rule {rule_id} [...] 2956 2957- Destroy all flow rules:: 2958 2959 flow flush {port_id} 2960 2961- Query an existing flow rule:: 2962 2963 flow query {port_id} {rule_id} {action} 2964 2965- List existing flow rules sorted by priority, filtered by group 2966 identifiers:: 2967 2968 flow list {port_id} [group {group_id}] [...] 2969 2970- Restrict ingress traffic to the defined flow rules:: 2971 2972 flow isolate {port_id} {boolean} 2973 2974Validating flow rules 2975~~~~~~~~~~~~~~~~~~~~~ 2976 2977``flow validate`` reports whether a flow rule would be accepted by the 2978underlying device in its current state but stops short of creating it. It is 2979bound to ``rte_flow_validate()``:: 2980 2981 flow validate {port_id} 2982 [group {group_id}] [priority {level}] [ingress] [egress] 2983 pattern {item} [/ {item} [...]] / end 2984 actions {action} [/ {action} [...]] / end 2985 2986If successful, it will show:: 2987 2988 Flow rule validated 2989 2990Otherwise it will show an error message of the form:: 2991 2992 Caught error type [...] ([...]): [...] 2993 2994This command uses the same parameters as ``flow create``, their format is 2995described in `Creating flow rules`_. 2996 2997Check whether redirecting any Ethernet packet received on port 0 to RX queue 2998index 6 is supported:: 2999 3000 testpmd> flow validate 0 ingress pattern eth / end 3001 actions queue index 6 / end 3002 Flow rule validated 3003 testpmd> 3004 3005Port 0 does not support TCPv6 rules:: 3006 3007 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end 3008 actions drop / end 3009 Caught error type 9 (specific pattern item): Invalid argument 3010 testpmd> 3011 3012Creating flow rules 3013~~~~~~~~~~~~~~~~~~~ 3014 3015``flow create`` validates and creates the specified flow rule. It is bound 3016to ``rte_flow_create()``:: 3017 3018 flow create {port_id} 3019 [group {group_id}] [priority {level}] [ingress] [egress] 3020 pattern {item} [/ {item} [...]] / end 3021 actions {action} [/ {action} [...]] / end 3022 3023If successful, it will return a flow rule ID usable with other commands:: 3024 3025 Flow rule #[...] created 3026 3027Otherwise it will show an error message of the form:: 3028 3029 Caught error type [...] ([...]): [...] 3030 3031Parameters describe in the following order: 3032 3033- Attributes (*group*, *priority*, *ingress*, *egress* tokens). 3034- A matching pattern, starting with the *pattern* token and terminated by an 3035 *end* pattern item. 3036- Actions, starting with the *actions* token and terminated by an *end* 3037 action. 3038 3039These translate directly to *rte_flow* objects provided as-is to the 3040underlying functions. 3041 3042The shortest valid definition only comprises mandatory tokens:: 3043 3044 testpmd> flow create 0 pattern end actions end 3045 3046Note that PMDs may refuse rules that essentially do nothing such as this 3047one. 3048 3049**All unspecified object values are automatically initialized to 0.** 3050 3051Attributes 3052^^^^^^^^^^ 3053 3054These tokens affect flow rule attributes (``struct rte_flow_attr``) and are 3055specified before the ``pattern`` token. 3056 3057- ``group {group id}``: priority group. 3058- ``priority {level}``: priority level within group. 3059- ``ingress``: rule applies to ingress traffic. 3060- ``egress``: rule applies to egress traffic. 3061 3062Each instance of an attribute specified several times overrides the previous 3063value as shown below (group 4 is used):: 3064 3065 testpmd> flow create 0 group 42 group 24 group 4 [...] 3066 3067Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. 3068 3069While not specifying a direction is an error, some rules may allow both 3070simultaneously. 3071 3072Most rules affect RX therefore contain the ``ingress`` token:: 3073 3074 testpmd> flow create 0 ingress pattern [...] 3075 3076Matching pattern 3077^^^^^^^^^^^^^^^^ 3078 3079A matching pattern starts after the ``pattern`` token. It is made of pattern 3080items and is terminated by a mandatory ``end`` item. 3081 3082Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum 3083rte_flow_item_type``). 3084 3085The ``/`` token is used as a separator between pattern items as shown 3086below:: 3087 3088 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] 3089 3090Note that protocol items like these must be stacked from lowest to highest 3091layer to make sense. For instance, the following rule is either invalid or 3092unlikely to match any packet:: 3093 3094 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] 3095 3096More information on these restrictions can be found in the *rte_flow* 3097documentation. 3098 3099Several items support additional specification structures, for example 3100``ipv4`` allows specifying source and destination addresses as follows:: 3101 3102 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 3103 dst is 10.2.0.0 / end [...] 3104 3105This rule matches all IPv4 traffic with the specified properties. 3106 3107In this example, ``src`` and ``dst`` are field names of the underlying 3108``struct rte_flow_item_ipv4`` object. All item properties can be specified 3109in a similar fashion. 3110 3111The ``is`` token means that the subsequent value must be matched exactly, 3112and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` 3113accordingly. Possible assignment tokens are: 3114 3115- ``is``: match value perfectly (with full bit-mask). 3116- ``spec``: match value according to configured bit-mask. 3117- ``last``: specify upper bound to establish a range. 3118- ``mask``: specify bit-mask with relevant bits set to one. 3119- ``prefix``: generate bit-mask from a prefix length. 3120 3121These yield identical results:: 3122 3123 ipv4 src is 10.1.1.1 3124 3125:: 3126 3127 ipv4 src spec 10.1.1.1 src mask 255.255.255.255 3128 3129:: 3130 3131 ipv4 src spec 10.1.1.1 src prefix 32 3132 3133:: 3134 3135 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value 3136 3137:: 3138 3139 ipv4 src is 10.1.1.1 src last 0 # 0 disables range 3140 3141Inclusive ranges can be defined with ``last``:: 3142 3143 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 3144 3145Note that ``mask`` affects both ``spec`` and ``last``:: 3146 3147 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 3148 # matches 10.1.0.0 to 10.2.255.255 3149 3150Properties can be modified multiple times:: 3151 3152 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 3153 3154:: 3155 3156 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 3157 3158Pattern items 3159^^^^^^^^^^^^^ 3160 3161This section lists supported pattern items and their attributes, if any. 3162 3163- ``end``: end list of pattern items. 3164 3165- ``void``: no-op pattern item. 3166 3167- ``invert``: perform actions when pattern does not match. 3168 3169- ``any``: match any protocol for the current layer. 3170 3171 - ``num {unsigned}``: number of layers covered. 3172 3173- ``pf``: match packets addressed to the physical function. 3174 3175- ``vf``: match packets addressed to a virtual function ID. 3176 3177 - ``id {unsigned}``: destination VF ID. 3178 3179- ``port``: device-specific physical port index to use. 3180 3181 - ``index {unsigned}``: physical port index. 3182 3183- ``raw``: match an arbitrary byte string. 3184 3185 - ``relative {boolean}``: look for pattern after the previous item. 3186 - ``search {boolean}``: search pattern from offset (see also limit). 3187 - ``offset {integer}``: absolute or relative offset for pattern. 3188 - ``limit {unsigned}``: search area limit for start of pattern. 3189 - ``pattern {string}``: byte string to look for. 3190 3191- ``eth``: match Ethernet header. 3192 3193 - ``dst {MAC-48}``: destination MAC. 3194 - ``src {MAC-48}``: source MAC. 3195 - ``type {unsigned}``: EtherType. 3196 3197- ``vlan``: match 802.1Q/ad VLAN tag. 3198 3199 - ``tpid {unsigned}``: tag protocol identifier. 3200 - ``tci {unsigned}``: tag control information. 3201 - ``pcp {unsigned}``: priority code point. 3202 - ``dei {unsigned}``: drop eligible indicator. 3203 - ``vid {unsigned}``: VLAN identifier. 3204 3205- ``ipv4``: match IPv4 header. 3206 3207 - ``tos {unsigned}``: type of service. 3208 - ``ttl {unsigned}``: time to live. 3209 - ``proto {unsigned}``: next protocol ID. 3210 - ``src {ipv4 address}``: source address. 3211 - ``dst {ipv4 address}``: destination address. 3212 3213- ``ipv6``: match IPv6 header. 3214 3215 - ``tc {unsigned}``: traffic class. 3216 - ``flow {unsigned}``: flow label. 3217 - ``proto {unsigned}``: protocol (next header). 3218 - ``hop {unsigned}``: hop limit. 3219 - ``src {ipv6 address}``: source address. 3220 - ``dst {ipv6 address}``: destination address. 3221 3222- ``icmp``: match ICMP header. 3223 3224 - ``type {unsigned}``: ICMP packet type. 3225 - ``code {unsigned}``: ICMP packet code. 3226 3227- ``udp``: match UDP header. 3228 3229 - ``src {unsigned}``: UDP source port. 3230 - ``dst {unsigned}``: UDP destination port. 3231 3232- ``tcp``: match TCP header. 3233 3234 - ``src {unsigned}``: TCP source port. 3235 - ``dst {unsigned}``: TCP destination port. 3236 3237- ``sctp``: match SCTP header. 3238 3239 - ``src {unsigned}``: SCTP source port. 3240 - ``dst {unsigned}``: SCTP destination port. 3241 - ``tag {unsigned}``: validation tag. 3242 - ``cksum {unsigned}``: checksum. 3243 3244- ``vxlan``: match VXLAN header. 3245 3246 - ``vni {unsigned}``: VXLAN identifier. 3247 3248- ``e_tag``: match IEEE 802.1BR E-Tag header. 3249 3250 - ``grp_ecid_b {unsigned}``: GRP and E-CID base. 3251 3252- ``nvgre``: match NVGRE header. 3253 3254 - ``tni {unsigned}``: virtual subnet ID. 3255 3256- ``mpls``: match MPLS header. 3257 3258 - ``label {unsigned}``: MPLS label. 3259 3260- ``gre``: match GRE header. 3261 3262 - ``protocol {unsigned}``: protocol type. 3263 3264- ``fuzzy``: fuzzy pattern match, expect faster than default. 3265 3266 - ``thresh {unsigned}``: accuracy threshold. 3267 3268- ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header. 3269 3270 - ``teid {unsigned}``: tunnel endpoint identifier. 3271 3272Actions list 3273^^^^^^^^^^^^ 3274 3275A list of actions starts after the ``actions`` token in the same fashion as 3276`Matching pattern`_; actions are separated by ``/`` tokens and the list is 3277terminated by a mandatory ``end`` action. 3278 3279Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum 3280rte_flow_action_type``). 3281 3282Dropping all incoming UDPv4 packets can be expressed as follows:: 3283 3284 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3285 actions drop / end 3286 3287Several actions have configurable properties which must be specified when 3288there is no valid default value. For example, ``queue`` requires a target 3289queue index. 3290 3291This rule redirects incoming UDPv4 traffic to queue index 6:: 3292 3293 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3294 actions queue index 6 / end 3295 3296While this one could be rejected by PMDs (unspecified queue index):: 3297 3298 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3299 actions queue / end 3300 3301As defined by *rte_flow*, the list is not ordered, all actions of a given 3302rule are performed simultaneously. These are equivalent:: 3303 3304 queue index 6 / void / mark id 42 / end 3305 3306:: 3307 3308 void / mark id 42 / queue index 6 / end 3309 3310All actions in a list should have different types, otherwise only the last 3311action of a given type is taken into account:: 3312 3313 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 3314 3315:: 3316 3317 drop / drop / drop / end # drop is performed only once 3318 3319:: 3320 3321 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 3322 3323Considering they are performed simultaneously, opposite and overlapping 3324actions can sometimes be combined when the end result is unambiguous:: 3325 3326 drop / queue index 6 / end # drop has no effect 3327 3328:: 3329 3330 drop / dup index 6 / end # same as above 3331 3332:: 3333 3334 queue index 6 / rss queues 6 7 8 / end # queue has no effect 3335 3336:: 3337 3338 drop / passthru / end # drop has no effect 3339 3340Note that PMDs may still refuse such combinations. 3341 3342Actions 3343^^^^^^^ 3344 3345This section lists supported actions and their attributes, if any. 3346 3347- ``end``: end list of actions. 3348 3349- ``void``: no-op action. 3350 3351- ``passthru``: let subsequent rule process matched packets. 3352 3353- ``mark``: attach 32 bit value to packets. 3354 3355 - ``id {unsigned}``: 32 bit value to return with packets. 3356 3357- ``flag``: flag packets. 3358 3359- ``queue``: assign packets to a given queue index. 3360 3361 - ``index {unsigned}``: queue index to use. 3362 3363- ``drop``: drop packets (note: passthru has priority). 3364 3365- ``count``: enable counters for this rule. 3366 3367- ``dup``: duplicate packets to a given queue index. 3368 3369 - ``index {unsigned}``: queue index to duplicate packets to. 3370 3371- ``rss``: spread packets among several queues. 3372 3373 - ``queues [{unsigned} [...]] end``: queue indices to use. 3374 3375- ``pf``: redirect packets to physical device function. 3376 3377- ``vf``: redirect packets to virtual device function. 3378 3379 - ``original {boolean}``: use original VF ID if possible. 3380 - ``id {unsigned}``: VF ID to redirect packets to. 3381 3382Destroying flow rules 3383~~~~~~~~~~~~~~~~~~~~~ 3384 3385``flow destroy`` destroys one or more rules from their rule ID (as returned 3386by ``flow create``), this command calls ``rte_flow_destroy()`` as many 3387times as necessary:: 3388 3389 flow destroy {port_id} rule {rule_id} [...] 3390 3391If successful, it will show:: 3392 3393 Flow rule #[...] destroyed 3394 3395It does not report anything for rule IDs that do not exist. The usual error 3396message is shown when a rule cannot be destroyed:: 3397 3398 Caught error type [...] ([...]): [...] 3399 3400``flow flush`` destroys all rules on a device and does not take extra 3401arguments. It is bound to ``rte_flow_flush()``:: 3402 3403 flow flush {port_id} 3404 3405Any errors are reported as above. 3406 3407Creating several rules and destroying them:: 3408 3409 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3410 actions queue index 2 / end 3411 Flow rule #0 created 3412 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3413 actions queue index 3 / end 3414 Flow rule #1 created 3415 testpmd> flow destroy 0 rule 0 rule 1 3416 Flow rule #1 destroyed 3417 Flow rule #0 destroyed 3418 testpmd> 3419 3420The same result can be achieved using ``flow flush``:: 3421 3422 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3423 actions queue index 2 / end 3424 Flow rule #0 created 3425 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3426 actions queue index 3 / end 3427 Flow rule #1 created 3428 testpmd> flow flush 0 3429 testpmd> 3430 3431Non-existent rule IDs are ignored:: 3432 3433 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3434 actions queue index 2 / end 3435 Flow rule #0 created 3436 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3437 actions queue index 3 / end 3438 Flow rule #1 created 3439 testpmd> flow destroy 0 rule 42 rule 10 rule 2 3440 testpmd> 3441 testpmd> flow destroy 0 rule 0 3442 Flow rule #0 destroyed 3443 testpmd> 3444 3445Querying flow rules 3446~~~~~~~~~~~~~~~~~~~ 3447 3448``flow query`` queries a specific action of a flow rule having that 3449ability. Such actions collect information that can be reported using this 3450command. It is bound to ``rte_flow_query()``:: 3451 3452 flow query {port_id} {rule_id} {action} 3453 3454If successful, it will display either the retrieved data for known actions 3455or the following message:: 3456 3457 Cannot display result for action type [...] ([...]) 3458 3459Otherwise, it will complain either that the rule does not exist or that some 3460error occurred:: 3461 3462 Flow rule #[...] not found 3463 3464:: 3465 3466 Caught error type [...] ([...]): [...] 3467 3468Currently only the ``count`` action is supported. This action reports the 3469number of packets that hit the flow rule and the total number of bytes. Its 3470output has the following format:: 3471 3472 count: 3473 hits_set: [...] # whether "hits" contains a valid value 3474 bytes_set: [...] # whether "bytes" contains a valid value 3475 hits: [...] # number of packets 3476 bytes: [...] # number of bytes 3477 3478Querying counters for TCPv6 packets redirected to queue 6:: 3479 3480 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end 3481 actions queue index 6 / count / end 3482 Flow rule #4 created 3483 testpmd> flow query 0 4 count 3484 count: 3485 hits_set: 1 3486 bytes_set: 0 3487 hits: 386446 3488 bytes: 0 3489 testpmd> 3490 3491Listing flow rules 3492~~~~~~~~~~~~~~~~~~ 3493 3494``flow list`` lists existing flow rules sorted by priority and optionally 3495filtered by group identifiers:: 3496 3497 flow list {port_id} [group {group_id}] [...] 3498 3499This command only fails with the following message if the device does not 3500exist:: 3501 3502 Invalid port [...] 3503 3504Output consists of a header line followed by a short description of each 3505flow rule, one per line. There is no output at all when no flow rules are 3506configured on the device:: 3507 3508 ID Group Prio Attr Rule 3509 [...] [...] [...] [...] [...] 3510 3511``Attr`` column flags: 3512 3513- ``i`` for ``ingress``. 3514- ``e`` for ``egress``. 3515 3516Creating several flow rules and listing them:: 3517 3518 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3519 actions queue index 6 / end 3520 Flow rule #0 created 3521 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3522 actions queue index 2 / end 3523 Flow rule #1 created 3524 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end 3525 actions rss queues 6 7 8 end / end 3526 Flow rule #2 created 3527 testpmd> flow list 0 3528 ID Group Prio Attr Rule 3529 0 0 0 i- ETH IPV4 => QUEUE 3530 1 0 0 i- ETH IPV6 => QUEUE 3531 2 0 5 i- ETH IPV4 UDP => RSS 3532 testpmd> 3533 3534Rules are sorted by priority (i.e. group ID first, then priority level):: 3535 3536 testpmd> flow list 1 3537 ID Group Prio Attr Rule 3538 0 0 0 i- ETH => COUNT 3539 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3540 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3541 1 24 0 i- ETH IPV4 UDP => QUEUE 3542 4 24 10 i- ETH IPV4 TCP => DROP 3543 3 24 20 i- ETH IPV4 => DROP 3544 2 24 42 i- ETH IPV4 UDP => QUEUE 3545 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3546 testpmd> 3547 3548Output can be limited to specific groups:: 3549 3550 testpmd> flow list 1 group 0 group 63 3551 ID Group Prio Attr Rule 3552 0 0 0 i- ETH => COUNT 3553 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3554 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3555 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3556 testpmd> 3557 3558Toggling isolated mode 3559~~~~~~~~~~~~~~~~~~~~~~ 3560 3561``flow isolate`` can be used to tell the underlying PMD that ingress traffic 3562must only be injected from the defined flow rules; that no default traffic 3563is expected outside those rules and the driver is free to assign more 3564resources to handle them. It is bound to ``rte_flow_isolate()``:: 3565 3566 flow isolate {port_id} {boolean} 3567 3568If successful, enabling or disabling isolated mode shows either:: 3569 3570 Ingress traffic on port [...] 3571 is now restricted to the defined flow rules 3572 3573Or:: 3574 3575 Ingress traffic on port [...] 3576 is not restricted anymore to the defined flow rules 3577 3578Otherwise, in case of error:: 3579 3580 Caught error type [...] ([...]): [...] 3581 3582Mainly due to its side effects, PMDs supporting this mode may not have the 3583ability to toggle it more than once without reinitializing affected ports 3584first (e.g. by exiting testpmd). 3585 3586Enabling isolated mode:: 3587 3588 testpmd> flow isolate 0 true 3589 Ingress traffic on port 0 is now restricted to the defined flow rules 3590 testpmd> 3591 3592Disabling isolated mode:: 3593 3594 testpmd> flow isolate 0 false 3595 Ingress traffic on port 0 is not restricted anymore to the defined flow rules 3596 testpmd> 3597 3598Sample QinQ flow rules 3599~~~~~~~~~~~~~~~~~~~~~~ 3600 3601Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: 3602 3603 testpmd> port stop 0 3604 testpmd> vlan set qinq on 0 3605 3606The above command sets the inner and outer TPID's to 0x8100. 3607 3608To change the TPID's the following commands should be used:: 3609 3610 testpmd> vlan set outer tpid 0xa100 0 3611 testpmd> vlan set inner tpid 0x9100 0 3612 testpmd> port start 0 3613 3614Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. 3615 3616:: 3617 3618 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / 3619 vlan tci is 456 / end actions vf id 1 / queue index 0 / end 3620 Flow rule #0 validated 3621 3622 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / 3623 vlan tci is 456 / end actions vf id 123 / queue index 0 / end 3624 Flow rule #0 created 3625 3626 testpmd> flow list 0 3627 ID Group Prio Attr Rule 3628 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3629 3630Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. 3631 3632:: 3633 3634 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / 3635 vlan tci is 654 / end actions pf / queue index 0 / end 3636 Flow rule #1 validated 3637 3638 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / 3639 vlan tci is 654 / end actions pf / queue index 1 / end 3640 Flow rule #1 created 3641 3642 testpmd> flow list 0 3643 ID Group Prio Attr Rule 3644 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3645 1 0 0 i- ETH VLAN VLAN=>PF QUEUE 3646