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 eth-peer 1093~~~~~~~~~~~~ 1094 1095Set the forwarding peer address for certain port:: 1096 1097 testpmd> set eth-peer (port_id) (perr_addr) 1098 1099This is equivalent to the ``--eth-peer`` command-line option. 1100 1101set port-uta 1102~~~~~~~~~~~~ 1103 1104Set the unicast hash filter(s) on/off for a port:: 1105 1106 testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off) 1107 1108set promisc 1109~~~~~~~~~~~ 1110 1111Set the promiscuous mode on for a port or for all ports. 1112In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1113 1114 testpmd> set promisc (port_id|all) (on|off) 1115 1116set allmulti 1117~~~~~~~~~~~~ 1118 1119Set the allmulti mode for a port or for all ports:: 1120 1121 testpmd> set allmulti (port_id|all) (on|off) 1122 1123Same as the ifconfig (8) option. Controls how multicast packets are handled. 1124 1125set promisc (for VF) 1126~~~~~~~~~~~~~~~~~~~~ 1127 1128Set the unicast 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 promisc (port_id) (vf_id) (on|off) 1133 1134set allmulticast (for VF) 1135~~~~~~~~~~~~~~~~~~~~~~~~~ 1136 1137Set the multicast promiscuous mode for a VF from PF. 1138It's supported by Intel i40e NICs now. 1139In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1140 1141 testpmd> set vf allmulti (port_id) (vf_id) (on|off) 1142 1143set tx max bandwidth (for VF) 1144~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1145 1146Set TX max absolute bandwidth (Mbps) for a VF from PF:: 1147 1148 testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth) 1149 1150set tc tx min bandwidth (for VF) 1151~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1152 1153Set all TCs' TX min relative bandwidth (%) for a VF from PF:: 1154 1155 testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...) 1156 1157set tc tx max bandwidth (for VF) 1158~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1159 1160Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF:: 1161 1162 testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth) 1163 1164set tc strict link priority mode 1165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1166 1167Set some TCs' strict link priority mode on a physical port:: 1168 1169 testpmd> set tx strict-link-priority (port_id) (tc_bitmap) 1170 1171set tc tx min bandwidth 1172~~~~~~~~~~~~~~~~~~~~~~~ 1173 1174Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs:: 1175 1176 testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...) 1177 1178set flow_ctrl rx 1179~~~~~~~~~~~~~~~~ 1180 1181Set the link flow control parameter on a port:: 1182 1183 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1184 (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \ 1185 autoneg (on|off) (port_id) 1186 1187Where: 1188 1189* ``high_water`` (integer): High threshold value to trigger XOFF. 1190 1191* ``low_water`` (integer): Low threshold value to trigger XON. 1192 1193* ``pause_time`` (integer): Pause quota in the Pause frame. 1194 1195* ``send_xon`` (0/1): Send XON frame. 1196 1197* ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames. 1198 1199* ``autoneg``: Change the auto-negotiation parameter. 1200 1201set pfc_ctrl rx 1202~~~~~~~~~~~~~~~ 1203 1204Set the priority flow control parameter on a port:: 1205 1206 testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1207 (pause_time) (priority) (port_id) 1208 1209Where: 1210 1211* ``high_water`` (integer): High threshold value. 1212 1213* ``low_water`` (integer): Low threshold value. 1214 1215* ``pause_time`` (integer): Pause quota in the Pause frame. 1216 1217* ``priority`` (0-7): VLAN User Priority. 1218 1219set stat_qmap 1220~~~~~~~~~~~~~ 1221 1222Set statistics mapping (qmapping 0..15) for RX/TX queue on port:: 1223 1224 testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping) 1225 1226For example, to set rx queue 2 on port 0 to mapping 5:: 1227 1228 testpmd>set stat_qmap rx 0 2 5 1229 1230set xstats-hide-zero 1231~~~~~~~~~~~~~~~~~~~~ 1232 1233Set the option to hide zero values for xstats display:: 1234 1235 testpmd> set xstats-hide-zero on|off 1236 1237.. note:: 1238 1239 By default, the zero values are displayed for xstats. 1240 1241set port - rx/tx (for VF) 1242~~~~~~~~~~~~~~~~~~~~~~~~~ 1243 1244Set VF receive/transmit from a port:: 1245 1246 testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off) 1247 1248set port - mac address filter (for VF) 1249~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1250 1251Add/Remove unicast or multicast MAC addr filter for a VF:: 1252 1253 testpmd> set port (port_id) vf (vf_id) (mac_addr) \ 1254 (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off) 1255 1256set port - rx mode(for VF) 1257~~~~~~~~~~~~~~~~~~~~~~~~~~ 1258 1259Set the VF receive mode of a port:: 1260 1261 testpmd> set port (port_id) vf (vf_id) \ 1262 rxmode (AUPE|ROPE|BAM|MPE) (on|off) 1263 1264The available receive modes are: 1265 1266* ``AUPE``: Accepts untagged VLAN. 1267 1268* ``ROPE``: Accepts unicast hash. 1269 1270* ``BAM``: Accepts broadcast packets. 1271 1272* ``MPE``: Accepts all multicast packets. 1273 1274set port - tx_rate (for Queue) 1275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1276 1277Set TX rate limitation for a queue on a port:: 1278 1279 testpmd> set port (port_id) queue (queue_id) rate (rate_value) 1280 1281set port - tx_rate (for VF) 1282~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1283 1284Set TX rate limitation for queues in VF on a port:: 1285 1286 testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask) 1287 1288set port - mirror rule 1289~~~~~~~~~~~~~~~~~~~~~~ 1290 1291Set pool or vlan type mirror rule for a port:: 1292 1293 testpmd> set port (port_id) mirror-rule (rule_id) \ 1294 (pool-mirror-up|pool-mirror-down|vlan-mirror) \ 1295 (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) 1296 1297Set link mirror rule for a port:: 1298 1299 testpmd> set port (port_id) mirror-rule (rule_id) \ 1300 (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off) 1301 1302For example to enable mirror traffic with vlan 0,1 to pool 0:: 1303 1304 set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on 1305 1306reset port - mirror rule 1307~~~~~~~~~~~~~~~~~~~~~~~~ 1308 1309Reset a mirror rule for a port:: 1310 1311 testpmd> reset port (port_id) mirror-rule (rule_id) 1312 1313set flush_rx 1314~~~~~~~~~~~~ 1315 1316Set the flush on RX streams before forwarding. 1317The default is flush ``on``. 1318Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams:: 1319 1320 testpmd> set flush_rx off 1321 1322set bypass mode 1323~~~~~~~~~~~~~~~ 1324 1325Set the bypass mode for the lowest port on bypass enabled NIC:: 1326 1327 testpmd> set bypass mode (normal|bypass|isolate) (port_id) 1328 1329set bypass event 1330~~~~~~~~~~~~~~~~ 1331 1332Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled:: 1333 1334 testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \ 1335 mode (normal|bypass|isolate) (port_id) 1336 1337Where: 1338 1339* ``timeout``: Enable bypass after watchdog timeout. 1340 1341* ``os_on``: Enable bypass when OS/board is powered on. 1342 1343* ``os_off``: Enable bypass when OS/board is powered off. 1344 1345* ``power_on``: Enable bypass when power supply is turned on. 1346 1347* ``power_off``: Enable bypass when power supply is turned off. 1348 1349 1350set bypass timeout 1351~~~~~~~~~~~~~~~~~~ 1352 1353Set the bypass watchdog timeout to ``n`` seconds where 0 = instant:: 1354 1355 testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32) 1356 1357show bypass config 1358~~~~~~~~~~~~~~~~~~ 1359 1360Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC:: 1361 1362 testpmd> show bypass config (port_id) 1363 1364set link up 1365~~~~~~~~~~~ 1366 1367Set link up for a port:: 1368 1369 testpmd> set link-up port (port id) 1370 1371set link down 1372~~~~~~~~~~~~~ 1373 1374Set link down for a port:: 1375 1376 testpmd> set link-down port (port id) 1377 1378E-tag set 1379~~~~~~~~~ 1380 1381Enable E-tag insertion for a VF on a port:: 1382 1383 testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id) 1384 1385Disable E-tag insertion for a VF on a port:: 1386 1387 testpmd> E-tag set insertion off port (port_id) vf (vf_id) 1388 1389Enable/disable E-tag stripping on a port:: 1390 1391 testpmd> E-tag set stripping (on|off) port (port_id) 1392 1393Enable/disable E-tag based forwarding on a port:: 1394 1395 testpmd> E-tag set forwarding (on|off) port (port_id) 1396 1397Add an E-tag forwarding filter on a port:: 1398 1399 testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id) 1400 1401Delete an E-tag forwarding filter on a port:: 1402 testpmd> E-tag set filter del e-tag-id (value) port (port_id) 1403 1404ddp add 1405~~~~~~~ 1406 1407Load a dynamic device personalization (DDP) package:: 1408 1409 testpmd> ddp add (port_id) (package_path[,output_path]) 1410 1411ddp del 1412~~~~~~~ 1413 1414Delete a dynamic device personalization package:: 1415 1416 testpmd> ddp del (port_id) (package_path) 1417 1418ptype mapping 1419~~~~~~~~~~~~~ 1420 1421List all items from the ptype mapping table:: 1422 1423 testpmd> ptype mapping get (port_id) (valid_only) 1424 1425Where: 1426 1427* ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0). 1428 1429Replace a specific or a group of software defined ptype with a new one:: 1430 1431 testpmd> ptype mapping replace (port_id) (target) (mask) (pkt_type) 1432 1433where: 1434 1435* ``target``: A specific software ptype or a mask to represent a group of software ptypes. 1436 1437* ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1). 1438 1439* ``pkt_type``: The new software ptype to replace the old ones. 1440 1441Update hardware defined ptype to software defined packet type mapping table:: 1442 1443 testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype) 1444 1445where: 1446 1447* ``hw_ptype``: hardware ptype as the index of the ptype mapping table. 1448 1449* ``sw_ptype``: software ptype as the value of the ptype mapping table. 1450 1451Reset ptype mapping table:: 1452 1453 testpmd> ptype mapping reset (port_id) 1454 1455Port Functions 1456-------------- 1457 1458The following sections show functions for configuring ports. 1459 1460.. note:: 1461 1462 Port configuration changes only become active when forwarding is started/restarted. 1463 1464port attach 1465~~~~~~~~~~~ 1466 1467Attach a port specified by pci address or virtual device args:: 1468 1469 testpmd> port attach (identifier) 1470 1471To attach a new pci device, the device should be recognized by kernel first. 1472Then it should be moved under DPDK management. 1473Finally the port can be attached to testpmd. 1474 1475For example, to move a pci device using ixgbe under DPDK management: 1476 1477.. code-block:: console 1478 1479 # Check the status of the available devices. 1480 ./usertools/dpdk-devbind.py --status 1481 1482 Network devices using DPDK-compatible driver 1483 ============================================ 1484 <none> 1485 1486 Network devices using kernel driver 1487 =================================== 1488 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused= 1489 1490 1491 # Bind the device to igb_uio. 1492 sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0 1493 1494 1495 # Recheck the status of the devices. 1496 ./usertools/dpdk-devbind.py --status 1497 Network devices using DPDK-compatible driver 1498 ============================================ 1499 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= 1500 1501To attach a port created by virtual device, above steps are not needed. 1502 1503For example, to attach a port whose pci address is 0000:0a:00.0. 1504 1505.. code-block:: console 1506 1507 testpmd> port attach 0000:0a:00.0 1508 Attaching a new port... 1509 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1510 EAL: probe driver: 8086:10fb rte_ixgbe_pmd 1511 EAL: PCI memory mapped at 0x7f83bfa00000 1512 EAL: PCI memory mapped at 0x7f83bfa80000 1513 PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5 1514 PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb 1515 Port 0 is attached. Now total ports is 1 1516 Done 1517 1518For example, to attach a port created by pcap PMD. 1519 1520.. code-block:: console 1521 1522 testpmd> port attach net_pcap0 1523 Attaching a new port... 1524 PMD: Initializing pmd_pcap for net_pcap0 1525 PMD: Creating pcap-backed ethdev on numa socket 0 1526 Port 0 is attached. Now total ports is 1 1527 Done 1528 1529In this case, identifier is ``net_pcap0``. 1530This identifier format is the same as ``--vdev`` format of DPDK applications. 1531 1532For example, to re-attach a bonded port which has been previously detached, 1533the mode and slave parameters must be given. 1534 1535.. code-block:: console 1536 1537 testpmd> port attach net_bond_0,mode=0,slave=1 1538 Attaching a new port... 1539 EAL: Initializing pmd_bond for net_bond_0 1540 EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0. 1541 Port 0 is attached. Now total ports is 1 1542 Done 1543 1544 1545port detach 1546~~~~~~~~~~~ 1547 1548Detach a specific port:: 1549 1550 testpmd> port detach (port_id) 1551 1552Before detaching a port, the port should be stopped and closed. 1553 1554For example, to detach a pci device port 0. 1555 1556.. code-block:: console 1557 1558 testpmd> port stop 0 1559 Stopping ports... 1560 Done 1561 testpmd> port close 0 1562 Closing ports... 1563 Done 1564 1565 testpmd> port detach 0 1566 Detaching a port... 1567 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1568 EAL: remove driver: 8086:10fb rte_ixgbe_pmd 1569 EAL: PCI memory unmapped at 0x7f83bfa00000 1570 EAL: PCI memory unmapped at 0x7f83bfa80000 1571 Done 1572 1573 1574For example, to detach a virtual device port 0. 1575 1576.. code-block:: console 1577 1578 testpmd> port stop 0 1579 Stopping ports... 1580 Done 1581 testpmd> port close 0 1582 Closing ports... 1583 Done 1584 1585 testpmd> port detach 0 1586 Detaching a port... 1587 PMD: Closing pcap ethdev on numa socket 0 1588 Port 'net_pcap0' is detached. Now total ports is 0 1589 Done 1590 1591To remove a pci device completely from the system, first detach the port from testpmd. 1592Then the device should be moved under kernel management. 1593Finally the device can be removed using kernel pci hotplug functionality. 1594 1595For example, to move a pci device under kernel management: 1596 1597.. code-block:: console 1598 1599 sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0 1600 1601 ./usertools/dpdk-devbind.py --status 1602 1603 Network devices using DPDK-compatible driver 1604 ============================================ 1605 <none> 1606 1607 Network devices using kernel driver 1608 =================================== 1609 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio 1610 1611To remove a port created by a virtual device, above steps are not needed. 1612 1613port start 1614~~~~~~~~~~ 1615 1616Start all ports or a specific port:: 1617 1618 testpmd> port start (port_id|all) 1619 1620port stop 1621~~~~~~~~~ 1622 1623Stop all ports or a specific port:: 1624 1625 testpmd> port stop (port_id|all) 1626 1627port close 1628~~~~~~~~~~ 1629 1630Close all ports or a specific port:: 1631 1632 testpmd> port close (port_id|all) 1633 1634port start/stop queue 1635~~~~~~~~~~~~~~~~~~~~~ 1636 1637Start/stop a rx/tx queue on a specific port:: 1638 1639 testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop) 1640 1641Only take effect when port is started. 1642 1643port config - speed 1644~~~~~~~~~~~~~~~~~~~ 1645 1646Set the speed and duplex mode for all ports or a specific port:: 1647 1648 testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \ 1649 duplex (half|full|auto) 1650 1651port config - queues/descriptors 1652~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1653 1654Set number of queues/descriptors for rxq, txq, rxd and txd:: 1655 1656 testpmd> port config all (rxq|txq|rxd|txd) (value) 1657 1658This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options. 1659 1660port config - max-pkt-len 1661~~~~~~~~~~~~~~~~~~~~~~~~~ 1662 1663Set the maximum packet length:: 1664 1665 testpmd> port config all max-pkt-len (value) 1666 1667This is equivalent to the ``--max-pkt-len`` command-line option. 1668 1669port config - CRC Strip 1670~~~~~~~~~~~~~~~~~~~~~~~ 1671 1672Set hardware CRC stripping on or off for all ports:: 1673 1674 testpmd> port config all crc-strip (on|off) 1675 1676CRC stripping is on by default. 1677 1678The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option. 1679 1680port config - scatter 1681~~~~~~~~~~~~~~~~~~~~~~~ 1682 1683Set RX scatter mode on or off for all ports:: 1684 1685 testpmd> port config all scatter (on|off) 1686 1687RX scatter mode is off by default. 1688 1689The ``on`` option is equivalent to the ``--enable-scatter`` command-line option. 1690 1691port config - RX Checksum 1692~~~~~~~~~~~~~~~~~~~~~~~~~ 1693 1694Set hardware RX checksum offload to on or off for all ports:: 1695 1696 testpmd> port config all rx-cksum (on|off) 1697 1698Checksum offload is off by default. 1699 1700The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option. 1701 1702port config - VLAN 1703~~~~~~~~~~~~~~~~~~ 1704 1705Set hardware VLAN on or off for all ports:: 1706 1707 testpmd> port config all hw-vlan (on|off) 1708 1709Hardware VLAN is on by default. 1710 1711The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option. 1712 1713port config - VLAN filter 1714~~~~~~~~~~~~~~~~~~~~~~~~~ 1715 1716Set hardware VLAN filter on or off for all ports:: 1717 1718 testpmd> port config all hw-vlan-filter (on|off) 1719 1720Hardware VLAN filter is on by default. 1721 1722The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option. 1723 1724port config - VLAN strip 1725~~~~~~~~~~~~~~~~~~~~~~~~ 1726 1727Set hardware VLAN strip on or off for all ports:: 1728 1729 testpmd> port config all hw-vlan-strip (on|off) 1730 1731Hardware VLAN strip is on by default. 1732 1733The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option. 1734 1735port config - VLAN extend 1736~~~~~~~~~~~~~~~~~~~~~~~~~ 1737 1738Set hardware VLAN extend on or off for all ports:: 1739 1740 testpmd> port config all hw-vlan-extend (on|off) 1741 1742Hardware VLAN extend is off by default. 1743 1744The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option. 1745 1746port config - Drop Packets 1747~~~~~~~~~~~~~~~~~~~~~~~~~~ 1748 1749Set packet drop for packets with no descriptors on or off for all ports:: 1750 1751 testpmd> port config all drop-en (on|off) 1752 1753Packet dropping for packets with no descriptors is off by default. 1754 1755The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option. 1756 1757port config - RSS 1758~~~~~~~~~~~~~~~~~ 1759 1760Set the RSS (Receive Side Scaling) mode on or off:: 1761 1762 testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none) 1763 1764RSS is on by default. 1765 1766The ``none`` option is equivalent to the ``--disable-rss`` command-line option. 1767 1768port config - RSS Reta 1769~~~~~~~~~~~~~~~~~~~~~~ 1770 1771Set the RSS (Receive Side Scaling) redirection table:: 1772 1773 testpmd> port config all rss reta (hash,queue)[,(hash,queue)] 1774 1775port config - DCB 1776~~~~~~~~~~~~~~~~~ 1777 1778Set the DCB mode for an individual port:: 1779 1780 testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off) 1781 1782The traffic class should be 4 or 8. 1783 1784port config - Burst 1785~~~~~~~~~~~~~~~~~~~ 1786 1787Set the number of packets per burst:: 1788 1789 testpmd> port config all burst (value) 1790 1791This is equivalent to the ``--burst`` command-line option. 1792 1793port config - Threshold 1794~~~~~~~~~~~~~~~~~~~~~~~ 1795 1796Set thresholds for TX/RX queues:: 1797 1798 testpmd> port config all (threshold) (value) 1799 1800Where the threshold type can be: 1801 1802* ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255. 1803 1804* ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255. 1805 1806* ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255. 1807 1808* ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255. 1809 1810* ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255. 1811 1812* ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255. 1813 1814* ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd. 1815 1816* ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd. 1817 1818* ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd. 1819 1820These threshold options are also available from the command-line. 1821 1822port config - E-tag 1823~~~~~~~~~~~~~~~~~~~ 1824 1825Set the value of ether-type for E-tag:: 1826 1827 testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value) 1828 1829Enable/disable the E-tag support:: 1830 1831 testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable) 1832 1833port config pctype mapping 1834~~~~~~~~~~~~~~~~~~~~~~~~~~ 1835 1836Reset pctype mapping table:: 1837 1838 testpmd> port config (port_id) pctype mapping reset 1839 1840Update hardware defined pctype to software defined flow type mapping table:: 1841 1842 testpmd> port config (port_id) pctype mapping update (pctype_id_0[,pctype_id_1]*) (flow_type_id) 1843 1844where: 1845 1846* ``pctype_id_x``: hardware pctype id as index of bit in bitmask value of the pctype mapping table. 1847 1848* ``flow_type_id``: software flow type id as the index of the pctype mapping table. 1849 1850 1851Link Bonding Functions 1852---------------------- 1853 1854The Link Bonding functions make it possible to dynamically create and 1855manage link bonding devices from within testpmd interactive prompt. 1856 1857create bonded device 1858~~~~~~~~~~~~~~~~~~~~ 1859 1860Create a new bonding device:: 1861 1862 testpmd> create bonded device (mode) (socket) 1863 1864For example, to create a bonded device in mode 1 on socket 0:: 1865 1866 testpmd> create bonded 1 0 1867 created new bonded device (port X) 1868 1869add bonding slave 1870~~~~~~~~~~~~~~~~~ 1871 1872Adds Ethernet device to a Link Bonding device:: 1873 1874 testpmd> add bonding slave (slave id) (port id) 1875 1876For example, to add Ethernet device (port 6) to a Link Bonding device (port 10):: 1877 1878 testpmd> add bonding slave 6 10 1879 1880 1881remove bonding slave 1882~~~~~~~~~~~~~~~~~~~~ 1883 1884Removes an Ethernet slave device from a Link Bonding device:: 1885 1886 testpmd> remove bonding slave (slave id) (port id) 1887 1888For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10):: 1889 1890 testpmd> remove bonding slave 6 10 1891 1892set bonding mode 1893~~~~~~~~~~~~~~~~ 1894 1895Set the Link Bonding mode of a Link Bonding device:: 1896 1897 testpmd> set bonding mode (value) (port id) 1898 1899For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3):: 1900 1901 testpmd> set bonding mode 3 10 1902 1903set bonding primary 1904~~~~~~~~~~~~~~~~~~~ 1905 1906Set an Ethernet slave device as the primary device on a Link Bonding device:: 1907 1908 testpmd> set bonding primary (slave id) (port id) 1909 1910For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10):: 1911 1912 testpmd> set bonding primary 6 10 1913 1914set bonding mac 1915~~~~~~~~~~~~~~~ 1916 1917Set the MAC address of a Link Bonding device:: 1918 1919 testpmd> set bonding mac (port id) (mac) 1920 1921For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01:: 1922 1923 testpmd> set bonding mac 10 00:00:00:00:00:01 1924 1925set bonding xmit_balance_policy 1926~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1927 1928Set the transmission policy for a Link Bonding device when it is in Balance XOR mode:: 1929 1930 testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34) 1931 1932For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports):: 1933 1934 testpmd> set bonding xmit_balance_policy 10 l34 1935 1936 1937set bonding mon_period 1938~~~~~~~~~~~~~~~~~~~~~~ 1939 1940Set the link status monitoring polling period in milliseconds for a bonding device. 1941 1942This adds support for PMD slave devices which do not support link status interrupts. 1943When the mon_period is set to a value greater than 0 then all PMD's which do not support 1944link status ISR will be queried every polling interval to check if their link status has changed:: 1945 1946 testpmd> set bonding mon_period (port_id) (value) 1947 1948For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms:: 1949 1950 testpmd> set bonding mon_period 5 150 1951 1952 1953set bonding lacp dedicated_queue 1954~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1955 1956Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic 1957when in mode 4 (link-aggregration-802.3ad):: 1958 1959 testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable) 1960 1961 1962set bonding agg_mode 1963~~~~~~~~~~~~~~~~~~~~ 1964 1965Enable one of the specific aggregators mode when in mode 4 (link-aggregration-802.3ad):: 1966 1967 testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable) 1968 1969 1970show bonding config 1971~~~~~~~~~~~~~~~~~~~ 1972 1973Show the current configuration of a Link Bonding device:: 1974 1975 testpmd> show bonding config (port id) 1976 1977For example, 1978to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4) 1979in balance mode with a transmission policy of layer 2+3:: 1980 1981 testpmd> show bonding config 9 1982 Bonding mode: 2 1983 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23 1984 Slaves (3): [1 3 4] 1985 Active Slaves (3): [1 3 4] 1986 Primary: [3] 1987 1988 1989Register Functions 1990------------------ 1991 1992The Register Functions can be used to read from and write to registers on the network card referenced by a port number. 1993This is mainly useful for debugging purposes. 1994Reference should be made to the appropriate datasheet for the network card for details on the register addresses 1995and fields that can be accessed. 1996 1997read reg 1998~~~~~~~~ 1999 2000Display the value of a port register:: 2001 2002 testpmd> read reg (port_id) (address) 2003 2004For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller:: 2005 2006 testpmd> read reg 0 0xEE00 2007 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) 2008 2009read regfield 2010~~~~~~~~~~~~~ 2011 2012Display a port register bit field:: 2013 2014 testpmd> read regfield (port_id) (address) (bit_x) (bit_y) 2015 2016For example, reading the lowest two bits from the register in the example above:: 2017 2018 testpmd> read regfield 0 0xEE00 0 1 2019 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1) 2020 2021read regbit 2022~~~~~~~~~~~ 2023 2024Display a single port register bit:: 2025 2026 testpmd> read regbit (port_id) (address) (bit_x) 2027 2028For example, reading the lowest bit from the register in the example above:: 2029 2030 testpmd> read regbit 0 0xEE00 0 2031 port 0 PCI register at offset 0xEE00: bit 0=1 2032 2033write reg 2034~~~~~~~~~ 2035 2036Set the value of a port register:: 2037 2038 testpmd> write reg (port_id) (address) (value) 2039 2040For example, to clear a register:: 2041 2042 testpmd> write reg 0 0xEE00 0x0 2043 port 0 PCI register at offset 0xEE00: 0x00000000 (0) 2044 2045write regfield 2046~~~~~~~~~~~~~~ 2047 2048Set bit field of a port register:: 2049 2050 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value) 2051 2052For example, writing to the register cleared in the example above:: 2053 2054 testpmd> write regfield 0 0xEE00 0 1 2 2055 port 0 PCI register at offset 0xEE00: 0x00000002 (2) 2056 2057write regbit 2058~~~~~~~~~~~~ 2059 2060Set single bit value of a port register:: 2061 2062 testpmd> write regbit (port_id) (address) (bit_x) (value) 2063 2064For example, to set the high bit in the register from the example above:: 2065 2066 testpmd> write regbit 0 0xEE00 31 1 2067 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) 2068 2069Traffic Metering and Policing 2070----------------------------- 2071 2072The following section shows functions for configuring traffic metering and 2073policing on the ethernet device through the use of generic ethdev API. 2074 2075show port traffic management capability 2076~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2077 2078Show traffic metering and policing capability of the port:: 2079 2080 testpmd> show port meter cap (port_id) 2081 2082add port meter profile (srTCM rfc2967) 2083~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2084 2085Add meter profile (srTCM rfc2697) to the ethernet device:: 2086 2087 testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \ 2088 (cir) (cbs) (ebs) 2089 2090where: 2091 2092* ``profile_id``: ID for the meter profile. 2093* ``cir``: Committed Information Rate (CIR) (bytes/second). 2094* ``cbs``: Committed Burst Size (CBS) (bytes). 2095* ``ebs``: Excess Burst Size (EBS) (bytes). 2096 2097add port meter profile (trTCM rfc2968) 2098~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2099 2100Add meter profile (srTCM rfc2698) to the ethernet device:: 2101 2102 testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \ 2103 (cir) (pir) (cbs) (pbs) 2104 2105where: 2106 2107* ``profile_id``: ID for the meter profile. 2108* ``cir``: Committed information rate (bytes/second). 2109* ``pir``: Peak information rate (bytes/second). 2110* ``cbs``: Committed burst size (bytes). 2111* ``pbs``: Peak burst size (bytes). 2112 2113add port meter profile (trTCM rfc4115) 2114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2115 2116Add meter profile (trTCM rfc4115) to the ethernet device:: 2117 2118 testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \ 2119 (cir) (eir) (cbs) (ebs) 2120 2121where: 2122 2123* ``profile_id``: ID for the meter profile. 2124* ``cir``: Committed information rate (bytes/second). 2125* ``eir``: Excess information rate (bytes/second). 2126* ``cbs``: Committed burst size (bytes). 2127* ``ebs``: Excess burst size (bytes). 2128 2129delete port meter profile 2130~~~~~~~~~~~~~~~~~~~~~~~~~ 2131 2132Delete meter profile from the ethernet device:: 2133 2134 testpmd> del port meter profile (port_id) (profile_id) 2135 2136create port meter 2137~~~~~~~~~~~~~~~~~ 2138 2139Create new meter object for the ethernet device:: 2140 2141 testpmd> create port meter (port_id) (mtr_id) (profile_id) \ 2142 (meter_enable) (g_action) (y_action) (r_action) (stats_mask) (shared) \ 2143 (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\ 2144 (dscp_tbl_entry63)] 2145 2146where: 2147 2148* ``mtr_id``: meter object ID. 2149* ``profile_id``: ID for the meter profile. 2150* ``meter_enable``: When this parameter has a non-zero value, the meter object 2151 gets enabled at the time of creation, otherwise remains disabled. 2152* ``g_action``: Policer action for the packet with green color. 2153* ``y_action``: Policer action for the packet with yellow color. 2154* ``r_action``: Policer action for the packet with red color. 2155* ``stats_mask``: Mask of statistics counter types to be enabled for the 2156 meter object. 2157* ``shared``: When this parameter has a non-zero value, the meter object is 2158 shared by multiple flows. Otherwise, meter object is used by single flow. 2159* ``use_pre_meter_color``: When this parameter has a non-zero value, the 2160 input color for the current meter object is determined by the latest meter 2161 object in the same flow. Otherwise, the current meter object uses the 2162 *dscp_table* to determine the input color. 2163* ``dscp_tbl_entryx``: DSCP table entry x providing meter providing input 2164 color, 0 <= x <= 63. 2165 2166enable port meter 2167~~~~~~~~~~~~~~~~~ 2168 2169Enable meter for the ethernet device:: 2170 2171 testpmd> enable port meter (port_id) (mtr_id) 2172 2173disable port meter 2174~~~~~~~~~~~~~~~~~~ 2175 2176Disable meter for the ethernet device:: 2177 2178 testpmd> disable port meter (port_id) (mtr_id) 2179 2180delete port meter 2181~~~~~~~~~~~~~~~~~ 2182 2183Delete meter for the ethernet device:: 2184 2185 testpmd> del port meter (port_id) (mtr_id) 2186 2187Set port meter profile 2188~~~~~~~~~~~~~~~~~~~~~~ 2189 2190Set meter profile for the ethernet device:: 2191 2192 testpmd> set port meter profile (port_id) (mtr_id) (profile_id) 2193 2194set port meter dscp table 2195~~~~~~~~~~~~~~~~~~~~~~~~~ 2196 2197Set meter dscp table for the ethernet device:: 2198 2199 testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \ 2200 (dscp_tbl_entry1)...(dscp_tbl_entry63)] 2201 2202set port meter policer action 2203~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2204 2205Set meter policer action for the ethernet device:: 2206 2207 testpmd> set port meter policer action (port_id) (mtr_id) (action_mask) \ 2208 (action0) [(action1) (action1)] 2209 2210where: 2211 2212* ``action_mask``: Bit mask indicating which policer actions need to be 2213 updated. One or more policer actions can be updated in a single function 2214 invocation. To update the policer action associated with color C, bit 2215 (1 << C) needs to be set in *action_mask* and element at position C 2216 in the *actions* array needs to be valid. 2217* ``actionx``: Policer action for the color x, 2218 RTE_MTR_GREEN <= x < RTE_MTR_COLORS 2219 2220set port meter stats mask 2221~~~~~~~~~~~~~~~~~~~~~~~~~ 2222 2223Set meter stats mask for the ethernet device:: 2224 2225 testpmd> set port meter stats mask (port_id) (mtr_id) (stats_mask) 2226 2227where: 2228 2229* ``stats_mask``: Bit mask indicating statistics counter types to be enabled. 2230 2231show port meter stats 2232~~~~~~~~~~~~~~~~~~~~~ 2233 2234Show meter stats of the ethernet device:: 2235 2236 testpmd> show port meter stats (port_id) (mtr_id) (clear) 2237 2238where: 2239 2240* ``clear``: Flag that indicates whether the statistics counters should 2241 be cleared (i.e. set to zero) immediately after they have been read or not. 2242 2243Traffic Management 2244------------------ 2245 2246The following section shows functions for configuring traffic management on 2247on the ethernet device through the use of generic TM API. 2248 2249show port traffic management capability 2250~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2251 2252Show traffic management capability of the port:: 2253 2254 testpmd> show port tm cap (port_id) 2255 2256show port traffic management capability (hierarchy level) 2257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2258 2259Show traffic management hierarchy level capability of the port:: 2260 2261 testpmd> show port tm cap (port_id) (level_id) 2262 2263show port traffic management capability (hierarchy node level) 2264~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2265 2266Show the traffic management hierarchy node capability of the port:: 2267 2268 testpmd> show port tm cap (port_id) (node_id) 2269 2270show port traffic management hierarchy node type 2271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2272 2273Show the port traffic management hierarchy node type:: 2274 2275 testpmd> show port tm node type (port_id) (node_id) 2276 2277show port traffic management hierarchy node stats 2278~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2279 2280Show the port traffic management hierarchy node statistics:: 2281 2282 testpmd> show port tm node stats (port_id) (node_id) (clear) 2283 2284where: 2285 2286* ``clear``: When this parameter has a non-zero value, the statistics counters 2287 are cleared (i.e. set to zero) immediately after they have been read, 2288 otherwise the statistics counters are left untouched. 2289 2290Add port traffic management private shaper profile 2291~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2292 2293Add the port traffic management private shaper profile:: 2294 2295 testpmd> add port tm node shaper profile (port_id) (shaper_profile_id) \ 2296 (tb_rate) (tb_size) (packet_length_adjust) 2297 2298where: 2299 2300* ``shaper_profile id``: Shaper profile ID for the new profile. 2301* ``tb_rate``: Token bucket rate (bytes per second). 2302* ``tb_size``: Token bucket size (bytes). 2303* ``packet_length_adjust``: The value (bytes) to be added to the length of 2304 each packet for the purpose of shaping. This parameter value can be used to 2305 correct the packet length with the framing overhead bytes that are consumed 2306 on the wire. 2307 2308Delete port traffic management private shaper profile 2309~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2310 2311Delete the port traffic management private shaper:: 2312 2313 testpmd> del port tm node shaper profile (port_id) (shaper_profile_id) 2314 2315where: 2316 2317* ``shaper_profile id``: Shaper profile ID that needs to be deleted. 2318 2319Add port traffic management shared shaper 2320~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2321 2322Create the port traffic management shared shaper:: 2323 2324 testpmd> add port tm node shared shaper (port_id) (shared_shaper_id) \ 2325 (shaper_profile_id) 2326 2327where: 2328 2329* ``shared_shaper_id``: Shared shaper ID to be created. 2330* ``shaper_profile id``: Shaper profile ID for shared shaper. 2331 2332Set port traffic management shared shaper 2333~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2334 2335Update the port traffic management shared shaper:: 2336 2337 testpmd> set port tm node shared shaper (port_id) (shared_shaper_id) \ 2338 (shaper_profile_id) 2339 2340where: 2341 2342* ``shared_shaper_id``: Shared shaper ID to be update. 2343* ``shaper_profile id``: Shaper profile ID for shared shaper. 2344 2345Delete port traffic management shared shaper 2346~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2347 2348Delete the port traffic management shared shaper:: 2349 2350 testpmd> del port tm node shared shaper (port_id) (shared_shaper_id) 2351 2352where: 2353 2354* ``shared_shaper_id``: Shared shaper ID to be deleted. 2355 2356Set port traffic management hiearchy node private shaper 2357~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2358 2359set the port traffic management hierarchy node private shaper:: 2360 2361 testpmd> set port tm node shaper profile (port_id) (node_id) \ 2362 (shaper_profile_id) 2363 2364where: 2365 2366* ``shaper_profile id``: Private shaper profile ID to be enabled on the 2367 hierarchy node. 2368 2369Add port traffic management WRED profile 2370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2371 2372Create a new WRED profile:: 2373 2374 testpmd> add port tm node wred profile (port_id) (wred_profile_id) \ 2375 (color_g) (min_th_g) (max_th_g) (maxp_inv_g) (wq_log2_g) \ 2376 (color_y) (min_th_y) (max_th_y) (maxp_inv_y) (wq_log2_y) \ 2377 (color_r) (min_th_r) (max_th_r) (maxp_inv_r) (wq_log2_r) 2378 2379where: 2380 2381* ``wred_profile id``: Identifier for the newly create WRED profile 2382* ``color_g``: Packet color (green) 2383* ``min_th_g``: Minimum queue threshold for packet with green color 2384* ``max_th_g``: Minimum queue threshold for packet with green color 2385* ``maxp_inv_g``: Inverse of packet marking probability maximum value (maxp) 2386* ``wq_log2_g``: Negated log2 of queue weight (wq) 2387* ``color_y``: Packet color (yellow) 2388* ``min_th_y``: Minimum queue threshold for packet with yellow color 2389* ``max_th_y``: Minimum queue threshold for packet with yellow color 2390* ``maxp_inv_y``: Inverse of packet marking probability maximum value (maxp) 2391* ``wq_log2_y``: Negated log2 of queue weight (wq) 2392* ``color_r``: Packet color (red) 2393* ``min_th_r``: Minimum queue threshold for packet with yellow color 2394* ``max_th_r``: Minimum queue threshold for packet with yellow color 2395* ``maxp_inv_r``: Inverse of packet marking probability maximum value (maxp) 2396* ``wq_log2_r``: Negated log2 of queue weight (wq) 2397 2398Delete port traffic management WRED profile 2399~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2400 2401Delete the WRED profile:: 2402 2403 testpmd> del port tm node wred profile (port_id) (wred_profile_id) 2404 2405Add port traffic management hierarchy nonleaf node 2406~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2407 2408Add nonleaf node to port traffic management hiearchy:: 2409 2410 testpmd> add port tm nonleaf node (port_id) (node_id) (parent_node_id) \ 2411 (priority) (weight) (level_id) (shaper_profile_id) \ 2412 (n_sp_priorities) (stats_mask) (n_shared_shapers) \ 2413 [(shared_shaper_0) (shared_shaper_1) ...] \ 2414 2415where: 2416 2417* ``parent_node_id``: Node ID of the parent. 2418* ``priority``: Node priority (highest node priority is zero). This is used by 2419 the SP algorithm running on the parent node for scheduling this node. 2420* ``weight``: Node weight (lowest weight is one). The node weight is relative 2421 to the weight sum of all siblings that have the same priority. It is used by 2422 the WFQ algorithm running on the parent node for scheduling this node. 2423* ``level_id``: Hiearchy level of the node. 2424* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2425 the node. 2426* ``n_sp_priorities``: Number of strict priorities. 2427* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2428* ``n_shared_shapers``: Number of shared shapers. 2429* ``shared_shaper_id``: Shared shaper id. 2430 2431Add port traffic management hierarchy leaf node 2432~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2433 2434Add leaf node to port traffic management hiearchy:: 2435 2436 testpmd> add port tm leaf node (port_id) (node_id) (parent_node_id) \ 2437 (priority) (weight) (level_id) (shaper_profile_id) \ 2438 (cman_mode) (wred_profile_id) (stats_mask) (n_shared_shapers) \ 2439 [(shared_shaper_id) (shared_shaper_id) ...] \ 2440 2441where: 2442 2443* ``parent_node_id``: Node ID of the parent. 2444* ``priority``: Node priority (highest node priority is zero). This is used by 2445 the SP algorithm running on the parent node for scheduling this node. 2446* ``weight``: Node weight (lowest weight is one). The node weight is relative 2447 to the weight sum of all siblings that have the same priority. It is used by 2448 the WFQ algorithm running on the parent node for scheduling this node. 2449* ``level_id``: Hiearchy level of the node. 2450* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2451 the node. 2452* ``cman_mode``: Congestion management mode to be enabled for this node. 2453* ``wred_profile_id``: WRED profile id to be enabled for this node. 2454* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2455* ``n_shared_shapers``: Number of shared shapers. 2456* ``shared_shaper_id``: Shared shaper id. 2457 2458Delete port traffic management hierarchy node 2459~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2460 2461Delete node from port traffic management hiearchy:: 2462 2463 testpmd> del port tm node (port_id) (node_id) 2464 2465Update port traffic management hierarchy parent node 2466~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2467 2468Update port traffic management hierarchy parent node:: 2469 2470 testpmd> set port tm node parent (port_id) (node_id) (parent_node_id) \ 2471 (priority) (weight) 2472 2473This function can only be called after the hierarchy commit invocation. Its 2474success depends on the port support for this operation, as advertised through 2475the port capability set. This function is valid for all nodes of the traffic 2476management hierarchy except root node. 2477 2478Commit port traffic management hierarchy 2479~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2480 2481Commit the traffic management hierarchy on the port:: 2482 2483 testpmd> port tm hierarchy commit (port_id) (clean_on_fail) 2484 2485where: 2486 2487* ``clean_on_fail``: When set to non-zero, hierarchy is cleared on function 2488 call failure. On the other hand, hierarchy is preserved when this parameter 2489 is equal to zero. 2490 2491Set port traffic management default hierarchy (tm forwarding mode) 2492~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2493 2494set the traffic management default hierarchy on the port:: 2495 2496 testpmd> set port tm hierarchy default (port_id) 2497 2498Filter Functions 2499---------------- 2500 2501This section details the available filter functions that are available. 2502 2503Note these functions interface the deprecated legacy filtering framework, 2504superseded by *rte_flow*. See `Flow rules management`_. 2505 2506ethertype_filter 2507~~~~~~~~~~~~~~~~~~~~ 2508 2509Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue:: 2510 2511 ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \ 2512 ethertype (ether_type) (drop|fwd) queue (queue_id) 2513 2514The available information parameters are: 2515 2516* ``port_id``: The port which the Ethertype filter assigned on. 2517 2518* ``mac_addr``: Compare destination mac address. 2519 2520* ``mac_ignr``: Ignore destination mac address match. 2521 2522* ``mac_address``: Destination mac address to match. 2523 2524* ``ether_type``: The EtherType value want to match, 2525 for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid. 2526 2527* ``queue_id``: The receive queue associated with this EtherType filter. 2528 It is meaningless when deleting or dropping. 2529 2530Example, to add/remove an ethertype filter rule:: 2531 2532 testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \ 2533 ethertype 0x0806 fwd queue 3 2534 2535 testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \ 2536 ethertype 0x0806 fwd queue 3 2537 25382tuple_filter 2539~~~~~~~~~~~~~~~~~ 2540 2541Add or delete a 2-tuple filter, 2542which identifies packets by specific protocol and destination TCP/UDP port 2543and forwards packets into one of the receive queues:: 2544 2545 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \ 2546 protocol (protocol_value) mask (mask_value) \ 2547 tcp_flags (tcp_flags_value) priority (prio_value) \ 2548 queue (queue_id) 2549 2550The available information parameters are: 2551 2552* ``port_id``: The port which the 2-tuple filter assigned on. 2553 2554* ``dst_port_value``: Destination port in L4. 2555 2556* ``protocol_value``: IP L4 protocol. 2557 2558* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate. 2559 2560* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP). 2561 2562* ``prio_value``: Priority of this filter. 2563 2564* ``queue_id``: The receive queue associated with this 2-tuple filter. 2565 2566Example, to add/remove an 2tuple filter rule:: 2567 2568 testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \ 2569 tcp_flags 0x02 priority 3 queue 3 2570 2571 testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \ 2572 tcp_flags 0x02 priority 3 queue 3 2573 25745tuple_filter 2575~~~~~~~~~~~~~~~~~ 2576 2577Add or delete a 5-tuple filter, 2578which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port) 2579and routes packets into one of the receive queues:: 2580 2581 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \ 2582 (src_address) dst_port (dst_port_value) \ 2583 src_port (src_port_value) protocol (protocol_value) \ 2584 mask (mask_value) tcp_flags (tcp_flags_value) \ 2585 priority (prio_value) queue (queue_id) 2586 2587The available information parameters are: 2588 2589* ``port_id``: The port which the 5-tuple filter assigned on. 2590 2591* ``dst_address``: Destination IP address. 2592 2593* ``src_address``: Source IP address. 2594 2595* ``dst_port_value``: TCP/UDP destination port. 2596 2597* ``src_port_value``: TCP/UDP source port. 2598 2599* ``protocol_value``: L4 protocol. 2600 2601* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate 2602 2603* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP). 2604 2605* ``prio_value``: The priority of this filter. 2606 2607* ``queue_id``: The receive queue associated with this 5-tuple filter. 2608 2609Example, to add/remove an 5tuple filter rule:: 2610 2611 testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2612 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2613 flags 0x0 priority 3 queue 3 2614 2615 testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2616 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2617 flags 0x0 priority 3 queue 3 2618 2619syn_filter 2620~~~~~~~~~~ 2621 2622Using the SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue:: 2623 2624 syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) 2625 2626The available information parameters are: 2627 2628* ``port_id``: The port which the SYN filter assigned on. 2629 2630* ``high``: This SYN filter has higher priority than other filters. 2631 2632* ``low``: This SYN filter has lower priority than other filters. 2633 2634* ``queue_id``: The receive queue associated with this SYN filter 2635 2636Example:: 2637 2638 testpmd> syn_filter 0 add priority high queue 3 2639 2640flex_filter 2641~~~~~~~~~~~ 2642 2643With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet 2644and routed into one of the receive queues:: 2645 2646 flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \ 2647 mask (mask_value) priority (prio_value) queue (queue_id) 2648 2649The available information parameters are: 2650 2651* ``port_id``: The port which the Flex filter is assigned on. 2652 2653* ``len_value``: Filter length in bytes, no greater than 128. 2654 2655* ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match. 2656 2657* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match. 2658 2659* ``prio_value``: The priority of this filter. 2660 2661* ``queue_id``: The receive queue associated with this Flex filter. 2662 2663Example:: 2664 2665 testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \ 2666 mask 000C priority 3 queue 3 2667 2668 testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \ 2669 mask 000C priority 3 queue 3 2670 2671 2672.. _testpmd_flow_director: 2673 2674flow_director_filter 2675~~~~~~~~~~~~~~~~~~~~ 2676 2677The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues. 2678 2679Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and 2680Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter: 2681 2682* Perfect match filters. 2683 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2684 The masked fields are for IP flow. 2685 2686* Signature filters. 2687 The hardware checks a match between a hash-based signature of the masked fields of the received packet. 2688 2689* Perfect-mac-vlan match filters. 2690 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2691 The masked fields are for MAC VLAN flow. 2692 2693* Perfect-tunnel match filters. 2694 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2695 The masked fields are for tunnel flow. 2696 2697The Flow Director filters can match the different fields for different type of packet: flow type, specific input set 2698per flow type and the flexible payload. 2699 2700The Flow Director can also mask out parts of all of these fields so that filters 2701are only applied to certain fields or parts of the fields. 2702 2703Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information. 2704 2705# Commands to add flow director filters of different flow types:: 2706 2707 flow_director_filter (port_id) mode IP (add|del|update) \ 2708 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ 2709 src (src_ip_address) dst (dst_ip_address) \ 2710 tos (tos_value) proto (proto_value) ttl (ttl_value) \ 2711 vlan (vlan_value) flexbytes (flexbytes_value) \ 2712 (drop|fwd) pf|vf(vf_id) queue (queue_id) \ 2713 fd_id (fd_id_value) 2714 2715 flow_director_filter (port_id) mode IP (add|del|update) \ 2716 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ 2717 src (src_ip_address) (src_port) \ 2718 dst (dst_ip_address) (dst_port) \ 2719 tos (tos_value) ttl (ttl_value) \ 2720 vlan (vlan_value) flexbytes (flexbytes_value) \ 2721 (drop|fwd) queue pf|vf(vf_id) (queue_id) \ 2722 fd_id (fd_id_value) 2723 2724 flow_director_filter (port_id) mode IP (add|del|update) \ 2725 flow (ipv4-sctp|ipv6-sctp) \ 2726 src (src_ip_address) (src_port) \ 2727 dst (dst_ip_address) (dst_port) \ 2728 tos (tos_value) ttl (ttl_value) \ 2729 tag (verification_tag) vlan (vlan_value) \ 2730 flexbytes (flexbytes_value) (drop|fwd) \ 2731 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) 2732 2733 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ 2734 ether (ethertype) flexbytes (flexbytes_value) \ 2735 (drop|fwd) pf|vf(vf_id) queue (queue_id) 2736 fd_id (fd_id_value) 2737 2738 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ 2739 mac (mac_address) vlan (vlan_value) \ 2740 flexbytes (flexbytes_value) (drop|fwd) \ 2741 queue (queue_id) fd_id (fd_id_value) 2742 2743 flow_director_filter (port_id) mode Tunnel (add|del|update) \ 2744 mac (mac_address) vlan (vlan_value) \ 2745 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ 2746 flexbytes (flexbytes_value) (drop|fwd) \ 2747 queue (queue_id) fd_id (fd_id_value) 2748 2749For example, to add an ipv4-udp flow type filter:: 2750 2751 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ 2752 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ 2753 fwd pf queue 1 fd_id 1 2754 2755For example, add an ipv4-other flow type filter:: 2756 2757 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ 2758 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ 2759 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 2760 2761flush_flow_director 2762~~~~~~~~~~~~~~~~~~~ 2763 2764Flush all flow director filters on a device:: 2765 2766 testpmd> flush_flow_director (port_id) 2767 2768Example, to flush all flow director filter on port 0:: 2769 2770 testpmd> flush_flow_director 0 2771 2772flow_director_mask 2773~~~~~~~~~~~~~~~~~~ 2774 2775Set flow director's input masks:: 2776 2777 flow_director_mask (port_id) mode IP vlan (vlan_value) \ 2778 src_mask (ipv4_src) (ipv6_src) (src_port) \ 2779 dst_mask (ipv4_dst) (ipv6_dst) (dst_port) 2780 2781 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) 2782 2783 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ 2784 mac (mac_value) tunnel-type (tunnel_type_value) \ 2785 tunnel-id (tunnel_id_value) 2786 2787Example, to set flow director mask on port 0:: 2788 2789 testpmd> flow_director_mask 0 mode IP vlan 0xefff \ 2790 src_mask 255.255.255.255 \ 2791 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ 2792 dst_mask 255.255.255.255 \ 2793 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF 2794 2795flow_director_flex_mask 2796~~~~~~~~~~~~~~~~~~~~~~~ 2797 2798set masks of flow director's flexible payload based on certain flow type:: 2799 2800 testpmd> flow_director_flex_mask (port_id) \ 2801 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2802 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ 2803 l2_payload|all) (mask) 2804 2805Example, to set flow director's flex mask for all flow type on port 0:: 2806 2807 testpmd> flow_director_flex_mask 0 flow all \ 2808 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 2809 2810 2811flow_director_flex_payload 2812~~~~~~~~~~~~~~~~~~~~~~~~~~ 2813 2814Configure flexible payload selection:: 2815 2816 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) 2817 2818For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload:: 2819 2820 testpmd> flow_director_flex_payload 0 l4 \ 2821 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) 2822 2823get_sym_hash_ena_per_port 2824~~~~~~~~~~~~~~~~~~~~~~~~~ 2825 2826Get symmetric hash enable configuration per port:: 2827 2828 get_sym_hash_ena_per_port (port_id) 2829 2830For example, to get symmetric hash enable configuration of port 1:: 2831 2832 testpmd> get_sym_hash_ena_per_port 1 2833 2834set_sym_hash_ena_per_port 2835~~~~~~~~~~~~~~~~~~~~~~~~~ 2836 2837Set symmetric hash enable configuration per port to enable or disable:: 2838 2839 set_sym_hash_ena_per_port (port_id) (enable|disable) 2840 2841For example, to set symmetric hash enable configuration of port 1 to enable:: 2842 2843 testpmd> set_sym_hash_ena_per_port 1 enable 2844 2845get_hash_global_config 2846~~~~~~~~~~~~~~~~~~~~~~ 2847 2848Get the global configurations of hash filters:: 2849 2850 get_hash_global_config (port_id) 2851 2852For example, to get the global configurations of hash filters of port 1:: 2853 2854 testpmd> get_hash_global_config 1 2855 2856set_hash_global_config 2857~~~~~~~~~~~~~~~~~~~~~~ 2858 2859Set the global configurations of hash filters:: 2860 2861 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ 2862 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \ 2863 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \ 2864 (enable|disable) 2865 2866For example, to enable simple_xor for flow type of ipv6 on port 2:: 2867 2868 testpmd> set_hash_global_config 2 simple_xor ipv6 enable 2869 2870set_hash_input_set 2871~~~~~~~~~~~~~~~~~~ 2872 2873Set the input set for hash:: 2874 2875 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2876 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2877 l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2878 ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ 2879 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ 2880 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ 2881 fld-8th|none) (select|add) 2882 2883For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: 2884 2885 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add 2886 2887set_fdir_input_set 2888~~~~~~~~~~~~~~~~~~ 2889 2890The Flow Director filters can match the different fields for different type of packet, i.e. specific input set 2891on per flow type and the flexible payload. This command can be used to change input set for each flow type. 2892 2893Set the input set for flow director:: 2894 2895 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2896 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2897 l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2898 ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ 2899 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ 2900 sctp-dst-port|sctp-veri-tag|none) (select|add) 2901 2902For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: 2903 2904 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add 2905 2906global_config 2907~~~~~~~~~~~~~ 2908 2909Set different GRE key length for input set:: 2910 2911 global_config (port_id) gre-key-len (number in bytes) 2912 2913For example to set GRE key length for input set to 4 bytes on port 0:: 2914 2915 testpmd> global_config 0 gre-key-len 4 2916 2917 2918.. _testpmd_rte_flow: 2919 2920Flow rules management 2921--------------------- 2922 2923Control of the generic flow API (*rte_flow*) is fully exposed through the 2924``flow`` command (validation, creation, destruction, queries and operation 2925modes). 2926 2927Considering *rte_flow* overlaps with all `Filter Functions`_, using both 2928features simultaneously may cause undefined side-effects and is therefore 2929not recommended. 2930 2931``flow`` syntax 2932~~~~~~~~~~~~~~~ 2933 2934Because the ``flow`` command uses dynamic tokens to handle the large number 2935of possible flow rules combinations, its behavior differs slightly from 2936other commands, in particular: 2937 2938- Pressing *?* or the *<tab>* key displays contextual help for the current 2939 token, not that of the entire command. 2940 2941- Optional and repeated parameters are supported (provided they are listed 2942 in the contextual help). 2943 2944The first parameter stands for the operation mode. Possible operations and 2945their general syntax are described below. They are covered in detail in the 2946following sections. 2947 2948- Check whether a flow rule can be created:: 2949 2950 flow validate {port_id} 2951 [group {group_id}] [priority {level}] [ingress] [egress] 2952 pattern {item} [/ {item} [...]] / end 2953 actions {action} [/ {action} [...]] / end 2954 2955- Create a flow rule:: 2956 2957 flow create {port_id} 2958 [group {group_id}] [priority {level}] [ingress] [egress] 2959 pattern {item} [/ {item} [...]] / end 2960 actions {action} [/ {action} [...]] / end 2961 2962- Destroy specific flow rules:: 2963 2964 flow destroy {port_id} rule {rule_id} [...] 2965 2966- Destroy all flow rules:: 2967 2968 flow flush {port_id} 2969 2970- Query an existing flow rule:: 2971 2972 flow query {port_id} {rule_id} {action} 2973 2974- List existing flow rules sorted by priority, filtered by group 2975 identifiers:: 2976 2977 flow list {port_id} [group {group_id}] [...] 2978 2979- Restrict ingress traffic to the defined flow rules:: 2980 2981 flow isolate {port_id} {boolean} 2982 2983Validating flow rules 2984~~~~~~~~~~~~~~~~~~~~~ 2985 2986``flow validate`` reports whether a flow rule would be accepted by the 2987underlying device in its current state but stops short of creating it. It is 2988bound to ``rte_flow_validate()``:: 2989 2990 flow validate {port_id} 2991 [group {group_id}] [priority {level}] [ingress] [egress] 2992 pattern {item} [/ {item} [...]] / end 2993 actions {action} [/ {action} [...]] / end 2994 2995If successful, it will show:: 2996 2997 Flow rule validated 2998 2999Otherwise it will show an error message of the form:: 3000 3001 Caught error type [...] ([...]): [...] 3002 3003This command uses the same parameters as ``flow create``, their format is 3004described in `Creating flow rules`_. 3005 3006Check whether redirecting any Ethernet packet received on port 0 to RX queue 3007index 6 is supported:: 3008 3009 testpmd> flow validate 0 ingress pattern eth / end 3010 actions queue index 6 / end 3011 Flow rule validated 3012 testpmd> 3013 3014Port 0 does not support TCPv6 rules:: 3015 3016 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end 3017 actions drop / end 3018 Caught error type 9 (specific pattern item): Invalid argument 3019 testpmd> 3020 3021Creating flow rules 3022~~~~~~~~~~~~~~~~~~~ 3023 3024``flow create`` validates and creates the specified flow rule. It is bound 3025to ``rte_flow_create()``:: 3026 3027 flow create {port_id} 3028 [group {group_id}] [priority {level}] [ingress] [egress] 3029 pattern {item} [/ {item} [...]] / end 3030 actions {action} [/ {action} [...]] / end 3031 3032If successful, it will return a flow rule ID usable with other commands:: 3033 3034 Flow rule #[...] created 3035 3036Otherwise it will show an error message of the form:: 3037 3038 Caught error type [...] ([...]): [...] 3039 3040Parameters describe in the following order: 3041 3042- Attributes (*group*, *priority*, *ingress*, *egress* tokens). 3043- A matching pattern, starting with the *pattern* token and terminated by an 3044 *end* pattern item. 3045- Actions, starting with the *actions* token and terminated by an *end* 3046 action. 3047 3048These translate directly to *rte_flow* objects provided as-is to the 3049underlying functions. 3050 3051The shortest valid definition only comprises mandatory tokens:: 3052 3053 testpmd> flow create 0 pattern end actions end 3054 3055Note that PMDs may refuse rules that essentially do nothing such as this 3056one. 3057 3058**All unspecified object values are automatically initialized to 0.** 3059 3060Attributes 3061^^^^^^^^^^ 3062 3063These tokens affect flow rule attributes (``struct rte_flow_attr``) and are 3064specified before the ``pattern`` token. 3065 3066- ``group {group id}``: priority group. 3067- ``priority {level}``: priority level within group. 3068- ``ingress``: rule applies to ingress traffic. 3069- ``egress``: rule applies to egress traffic. 3070 3071Each instance of an attribute specified several times overrides the previous 3072value as shown below (group 4 is used):: 3073 3074 testpmd> flow create 0 group 42 group 24 group 4 [...] 3075 3076Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. 3077 3078While not specifying a direction is an error, some rules may allow both 3079simultaneously. 3080 3081Most rules affect RX therefore contain the ``ingress`` token:: 3082 3083 testpmd> flow create 0 ingress pattern [...] 3084 3085Matching pattern 3086^^^^^^^^^^^^^^^^ 3087 3088A matching pattern starts after the ``pattern`` token. It is made of pattern 3089items and is terminated by a mandatory ``end`` item. 3090 3091Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum 3092rte_flow_item_type``). 3093 3094The ``/`` token is used as a separator between pattern items as shown 3095below:: 3096 3097 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] 3098 3099Note that protocol items like these must be stacked from lowest to highest 3100layer to make sense. For instance, the following rule is either invalid or 3101unlikely to match any packet:: 3102 3103 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] 3104 3105More information on these restrictions can be found in the *rte_flow* 3106documentation. 3107 3108Several items support additional specification structures, for example 3109``ipv4`` allows specifying source and destination addresses as follows:: 3110 3111 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 3112 dst is 10.2.0.0 / end [...] 3113 3114This rule matches all IPv4 traffic with the specified properties. 3115 3116In this example, ``src`` and ``dst`` are field names of the underlying 3117``struct rte_flow_item_ipv4`` object. All item properties can be specified 3118in a similar fashion. 3119 3120The ``is`` token means that the subsequent value must be matched exactly, 3121and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` 3122accordingly. Possible assignment tokens are: 3123 3124- ``is``: match value perfectly (with full bit-mask). 3125- ``spec``: match value according to configured bit-mask. 3126- ``last``: specify upper bound to establish a range. 3127- ``mask``: specify bit-mask with relevant bits set to one. 3128- ``prefix``: generate bit-mask from a prefix length. 3129 3130These yield identical results:: 3131 3132 ipv4 src is 10.1.1.1 3133 3134:: 3135 3136 ipv4 src spec 10.1.1.1 src mask 255.255.255.255 3137 3138:: 3139 3140 ipv4 src spec 10.1.1.1 src prefix 32 3141 3142:: 3143 3144 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value 3145 3146:: 3147 3148 ipv4 src is 10.1.1.1 src last 0 # 0 disables range 3149 3150Inclusive ranges can be defined with ``last``:: 3151 3152 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 3153 3154Note that ``mask`` affects both ``spec`` and ``last``:: 3155 3156 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 3157 # matches 10.1.0.0 to 10.2.255.255 3158 3159Properties can be modified multiple times:: 3160 3161 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 3162 3163:: 3164 3165 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 3166 3167Pattern items 3168^^^^^^^^^^^^^ 3169 3170This section lists supported pattern items and their attributes, if any. 3171 3172- ``end``: end list of pattern items. 3173 3174- ``void``: no-op pattern item. 3175 3176- ``invert``: perform actions when pattern does not match. 3177 3178- ``any``: match any protocol for the current layer. 3179 3180 - ``num {unsigned}``: number of layers covered. 3181 3182- ``pf``: match packets addressed to the physical function. 3183 3184- ``vf``: match packets addressed to a virtual function ID. 3185 3186 - ``id {unsigned}``: destination VF ID. 3187 3188- ``port``: device-specific physical port index to use. 3189 3190 - ``index {unsigned}``: physical port index. 3191 3192- ``raw``: match an arbitrary byte string. 3193 3194 - ``relative {boolean}``: look for pattern after the previous item. 3195 - ``search {boolean}``: search pattern from offset (see also limit). 3196 - ``offset {integer}``: absolute or relative offset for pattern. 3197 - ``limit {unsigned}``: search area limit for start of pattern. 3198 - ``pattern {string}``: byte string to look for. 3199 3200- ``eth``: match Ethernet header. 3201 3202 - ``dst {MAC-48}``: destination MAC. 3203 - ``src {MAC-48}``: source MAC. 3204 - ``type {unsigned}``: EtherType. 3205 3206- ``vlan``: match 802.1Q/ad VLAN tag. 3207 3208 - ``tpid {unsigned}``: tag protocol identifier. 3209 - ``tci {unsigned}``: tag control information. 3210 - ``pcp {unsigned}``: priority code point. 3211 - ``dei {unsigned}``: drop eligible indicator. 3212 - ``vid {unsigned}``: VLAN identifier. 3213 3214- ``ipv4``: match IPv4 header. 3215 3216 - ``tos {unsigned}``: type of service. 3217 - ``ttl {unsigned}``: time to live. 3218 - ``proto {unsigned}``: next protocol ID. 3219 - ``src {ipv4 address}``: source address. 3220 - ``dst {ipv4 address}``: destination address. 3221 3222- ``ipv6``: match IPv6 header. 3223 3224 - ``tc {unsigned}``: traffic class. 3225 - ``flow {unsigned}``: flow label. 3226 - ``proto {unsigned}``: protocol (next header). 3227 - ``hop {unsigned}``: hop limit. 3228 - ``src {ipv6 address}``: source address. 3229 - ``dst {ipv6 address}``: destination address. 3230 3231- ``icmp``: match ICMP header. 3232 3233 - ``type {unsigned}``: ICMP packet type. 3234 - ``code {unsigned}``: ICMP packet code. 3235 3236- ``udp``: match UDP header. 3237 3238 - ``src {unsigned}``: UDP source port. 3239 - ``dst {unsigned}``: UDP destination port. 3240 3241- ``tcp``: match TCP header. 3242 3243 - ``src {unsigned}``: TCP source port. 3244 - ``dst {unsigned}``: TCP destination port. 3245 3246- ``sctp``: match SCTP header. 3247 3248 - ``src {unsigned}``: SCTP source port. 3249 - ``dst {unsigned}``: SCTP destination port. 3250 - ``tag {unsigned}``: validation tag. 3251 - ``cksum {unsigned}``: checksum. 3252 3253- ``vxlan``: match VXLAN header. 3254 3255 - ``vni {unsigned}``: VXLAN identifier. 3256 3257- ``e_tag``: match IEEE 802.1BR E-Tag header. 3258 3259 - ``grp_ecid_b {unsigned}``: GRP and E-CID base. 3260 3261- ``nvgre``: match NVGRE header. 3262 3263 - ``tni {unsigned}``: virtual subnet ID. 3264 3265- ``mpls``: match MPLS header. 3266 3267 - ``label {unsigned}``: MPLS label. 3268 3269- ``gre``: match GRE header. 3270 3271 - ``protocol {unsigned}``: protocol type. 3272 3273- ``fuzzy``: fuzzy pattern match, expect faster than default. 3274 3275 - ``thresh {unsigned}``: accuracy threshold. 3276 3277- ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header. 3278 3279 - ``teid {unsigned}``: tunnel endpoint identifier. 3280 3281Actions list 3282^^^^^^^^^^^^ 3283 3284A list of actions starts after the ``actions`` token in the same fashion as 3285`Matching pattern`_; actions are separated by ``/`` tokens and the list is 3286terminated by a mandatory ``end`` action. 3287 3288Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum 3289rte_flow_action_type``). 3290 3291Dropping all incoming UDPv4 packets can be expressed as follows:: 3292 3293 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3294 actions drop / end 3295 3296Several actions have configurable properties which must be specified when 3297there is no valid default value. For example, ``queue`` requires a target 3298queue index. 3299 3300This rule redirects incoming UDPv4 traffic to queue index 6:: 3301 3302 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3303 actions queue index 6 / end 3304 3305While this one could be rejected by PMDs (unspecified queue index):: 3306 3307 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3308 actions queue / end 3309 3310As defined by *rte_flow*, the list is not ordered, all actions of a given 3311rule are performed simultaneously. These are equivalent:: 3312 3313 queue index 6 / void / mark id 42 / end 3314 3315:: 3316 3317 void / mark id 42 / queue index 6 / end 3318 3319All actions in a list should have different types, otherwise only the last 3320action of a given type is taken into account:: 3321 3322 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 3323 3324:: 3325 3326 drop / drop / drop / end # drop is performed only once 3327 3328:: 3329 3330 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 3331 3332Considering they are performed simultaneously, opposite and overlapping 3333actions can sometimes be combined when the end result is unambiguous:: 3334 3335 drop / queue index 6 / end # drop has no effect 3336 3337:: 3338 3339 drop / dup index 6 / end # same as above 3340 3341:: 3342 3343 queue index 6 / rss queues 6 7 8 / end # queue has no effect 3344 3345:: 3346 3347 drop / passthru / end # drop has no effect 3348 3349Note that PMDs may still refuse such combinations. 3350 3351Actions 3352^^^^^^^ 3353 3354This section lists supported actions and their attributes, if any. 3355 3356- ``end``: end list of actions. 3357 3358- ``void``: no-op action. 3359 3360- ``passthru``: let subsequent rule process matched packets. 3361 3362- ``mark``: attach 32 bit value to packets. 3363 3364 - ``id {unsigned}``: 32 bit value to return with packets. 3365 3366- ``flag``: flag packets. 3367 3368- ``queue``: assign packets to a given queue index. 3369 3370 - ``index {unsigned}``: queue index to use. 3371 3372- ``drop``: drop packets (note: passthru has priority). 3373 3374- ``count``: enable counters for this rule. 3375 3376- ``dup``: duplicate packets to a given queue index. 3377 3378 - ``index {unsigned}``: queue index to duplicate packets to. 3379 3380- ``rss``: spread packets among several queues. 3381 3382 - ``queues [{unsigned} [...]] end``: queue indices to use. 3383 3384- ``pf``: redirect packets to physical device function. 3385 3386- ``vf``: redirect packets to virtual device function. 3387 3388 - ``original {boolean}``: use original VF ID if possible. 3389 - ``id {unsigned}``: VF ID to redirect packets to. 3390 3391Destroying flow rules 3392~~~~~~~~~~~~~~~~~~~~~ 3393 3394``flow destroy`` destroys one or more rules from their rule ID (as returned 3395by ``flow create``), this command calls ``rte_flow_destroy()`` as many 3396times as necessary:: 3397 3398 flow destroy {port_id} rule {rule_id} [...] 3399 3400If successful, it will show:: 3401 3402 Flow rule #[...] destroyed 3403 3404It does not report anything for rule IDs that do not exist. The usual error 3405message is shown when a rule cannot be destroyed:: 3406 3407 Caught error type [...] ([...]): [...] 3408 3409``flow flush`` destroys all rules on a device and does not take extra 3410arguments. It is bound to ``rte_flow_flush()``:: 3411 3412 flow flush {port_id} 3413 3414Any errors are reported as above. 3415 3416Creating several rules and destroying them:: 3417 3418 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3419 actions queue index 2 / end 3420 Flow rule #0 created 3421 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3422 actions queue index 3 / end 3423 Flow rule #1 created 3424 testpmd> flow destroy 0 rule 0 rule 1 3425 Flow rule #1 destroyed 3426 Flow rule #0 destroyed 3427 testpmd> 3428 3429The same result can be achieved using ``flow flush``:: 3430 3431 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3432 actions queue index 2 / end 3433 Flow rule #0 created 3434 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3435 actions queue index 3 / end 3436 Flow rule #1 created 3437 testpmd> flow flush 0 3438 testpmd> 3439 3440Non-existent rule IDs are ignored:: 3441 3442 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3443 actions queue index 2 / end 3444 Flow rule #0 created 3445 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3446 actions queue index 3 / end 3447 Flow rule #1 created 3448 testpmd> flow destroy 0 rule 42 rule 10 rule 2 3449 testpmd> 3450 testpmd> flow destroy 0 rule 0 3451 Flow rule #0 destroyed 3452 testpmd> 3453 3454Querying flow rules 3455~~~~~~~~~~~~~~~~~~~ 3456 3457``flow query`` queries a specific action of a flow rule having that 3458ability. Such actions collect information that can be reported using this 3459command. It is bound to ``rte_flow_query()``:: 3460 3461 flow query {port_id} {rule_id} {action} 3462 3463If successful, it will display either the retrieved data for known actions 3464or the following message:: 3465 3466 Cannot display result for action type [...] ([...]) 3467 3468Otherwise, it will complain either that the rule does not exist or that some 3469error occurred:: 3470 3471 Flow rule #[...] not found 3472 3473:: 3474 3475 Caught error type [...] ([...]): [...] 3476 3477Currently only the ``count`` action is supported. This action reports the 3478number of packets that hit the flow rule and the total number of bytes. Its 3479output has the following format:: 3480 3481 count: 3482 hits_set: [...] # whether "hits" contains a valid value 3483 bytes_set: [...] # whether "bytes" contains a valid value 3484 hits: [...] # number of packets 3485 bytes: [...] # number of bytes 3486 3487Querying counters for TCPv6 packets redirected to queue 6:: 3488 3489 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end 3490 actions queue index 6 / count / end 3491 Flow rule #4 created 3492 testpmd> flow query 0 4 count 3493 count: 3494 hits_set: 1 3495 bytes_set: 0 3496 hits: 386446 3497 bytes: 0 3498 testpmd> 3499 3500Listing flow rules 3501~~~~~~~~~~~~~~~~~~ 3502 3503``flow list`` lists existing flow rules sorted by priority and optionally 3504filtered by group identifiers:: 3505 3506 flow list {port_id} [group {group_id}] [...] 3507 3508This command only fails with the following message if the device does not 3509exist:: 3510 3511 Invalid port [...] 3512 3513Output consists of a header line followed by a short description of each 3514flow rule, one per line. There is no output at all when no flow rules are 3515configured on the device:: 3516 3517 ID Group Prio Attr Rule 3518 [...] [...] [...] [...] [...] 3519 3520``Attr`` column flags: 3521 3522- ``i`` for ``ingress``. 3523- ``e`` for ``egress``. 3524 3525Creating several flow rules and listing them:: 3526 3527 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3528 actions queue index 6 / end 3529 Flow rule #0 created 3530 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3531 actions queue index 2 / end 3532 Flow rule #1 created 3533 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end 3534 actions rss queues 6 7 8 end / end 3535 Flow rule #2 created 3536 testpmd> flow list 0 3537 ID Group Prio Attr Rule 3538 0 0 0 i- ETH IPV4 => QUEUE 3539 1 0 0 i- ETH IPV6 => QUEUE 3540 2 0 5 i- ETH IPV4 UDP => RSS 3541 testpmd> 3542 3543Rules are sorted by priority (i.e. group ID first, then priority level):: 3544 3545 testpmd> flow list 1 3546 ID Group Prio Attr Rule 3547 0 0 0 i- ETH => COUNT 3548 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3549 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3550 1 24 0 i- ETH IPV4 UDP => QUEUE 3551 4 24 10 i- ETH IPV4 TCP => DROP 3552 3 24 20 i- ETH IPV4 => DROP 3553 2 24 42 i- ETH IPV4 UDP => QUEUE 3554 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3555 testpmd> 3556 3557Output can be limited to specific groups:: 3558 3559 testpmd> flow list 1 group 0 group 63 3560 ID Group Prio Attr Rule 3561 0 0 0 i- ETH => COUNT 3562 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3563 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3564 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3565 testpmd> 3566 3567Toggling isolated mode 3568~~~~~~~~~~~~~~~~~~~~~~ 3569 3570``flow isolate`` can be used to tell the underlying PMD that ingress traffic 3571must only be injected from the defined flow rules; that no default traffic 3572is expected outside those rules and the driver is free to assign more 3573resources to handle them. It is bound to ``rte_flow_isolate()``:: 3574 3575 flow isolate {port_id} {boolean} 3576 3577If successful, enabling or disabling isolated mode shows either:: 3578 3579 Ingress traffic on port [...] 3580 is now restricted to the defined flow rules 3581 3582Or:: 3583 3584 Ingress traffic on port [...] 3585 is not restricted anymore to the defined flow rules 3586 3587Otherwise, in case of error:: 3588 3589 Caught error type [...] ([...]): [...] 3590 3591Mainly due to its side effects, PMDs supporting this mode may not have the 3592ability to toggle it more than once without reinitializing affected ports 3593first (e.g. by exiting testpmd). 3594 3595Enabling isolated mode:: 3596 3597 testpmd> flow isolate 0 true 3598 Ingress traffic on port 0 is now restricted to the defined flow rules 3599 testpmd> 3600 3601Disabling isolated mode:: 3602 3603 testpmd> flow isolate 0 false 3604 Ingress traffic on port 0 is not restricted anymore to the defined flow rules 3605 testpmd> 3606 3607Sample QinQ flow rules 3608~~~~~~~~~~~~~~~~~~~~~~ 3609 3610Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: 3611 3612 testpmd> port stop 0 3613 testpmd> vlan set qinq on 0 3614 3615The above command sets the inner and outer TPID's to 0x8100. 3616 3617To change the TPID's the following commands should be used:: 3618 3619 testpmd> vlan set outer tpid 0xa100 0 3620 testpmd> vlan set inner tpid 0x9100 0 3621 testpmd> port start 0 3622 3623Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. 3624 3625:: 3626 3627 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / 3628 vlan tci is 456 / end actions vf id 1 / queue index 0 / end 3629 Flow rule #0 validated 3630 3631 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / 3632 vlan tci is 456 / end actions vf id 123 / queue index 0 / end 3633 Flow rule #0 created 3634 3635 testpmd> flow list 0 3636 ID Group Prio Attr Rule 3637 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3638 3639Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. 3640 3641:: 3642 3643 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / 3644 vlan tci is 654 / end actions pf / queue index 0 / end 3645 Flow rule #1 validated 3646 3647 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / 3648 vlan tci is 654 / end actions pf / queue index 1 / end 3649 Flow rule #1 created 3650 3651 testpmd> flow list 0 3652 ID Group Prio Attr Rule 3653 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3654 1 0 0 i- ETH VLAN VLAN=>PF QUEUE 3655