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 2697* Perfect-raw-flow-type match filters. 2698 The hardware checks a match between the masked fields of the received packets and pre-loaded raw (template) packet. 2699 The masked fields are specified by input sets. 2700 2701The Flow Director filters can match the different fields for different type of packet: flow type, specific input set 2702per flow type and the flexible payload. 2703 2704The Flow Director can also mask out parts of all of these fields so that filters 2705are only applied to certain fields or parts of the fields. 2706 2707Note that for raw flow type mode the source and destination fields in the 2708raw packet buffer need to be presented in a reversed order with respect 2709to the expected received packets. 2710For example: IP source and destination addresses or TCP/UDP/SCTP 2711source and destination ports 2712 2713Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information. 2714 2715# Commands to add flow director filters of different flow types:: 2716 2717 flow_director_filter (port_id) mode IP (add|del|update) \ 2718 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ 2719 src (src_ip_address) dst (dst_ip_address) \ 2720 tos (tos_value) proto (proto_value) ttl (ttl_value) \ 2721 vlan (vlan_value) flexbytes (flexbytes_value) \ 2722 (drop|fwd) pf|vf(vf_id) queue (queue_id) \ 2723 fd_id (fd_id_value) 2724 2725 flow_director_filter (port_id) mode IP (add|del|update) \ 2726 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ 2727 src (src_ip_address) (src_port) \ 2728 dst (dst_ip_address) (dst_port) \ 2729 tos (tos_value) ttl (ttl_value) \ 2730 vlan (vlan_value) flexbytes (flexbytes_value) \ 2731 (drop|fwd) queue pf|vf(vf_id) (queue_id) \ 2732 fd_id (fd_id_value) 2733 2734 flow_director_filter (port_id) mode IP (add|del|update) \ 2735 flow (ipv4-sctp|ipv6-sctp) \ 2736 src (src_ip_address) (src_port) \ 2737 dst (dst_ip_address) (dst_port) \ 2738 tos (tos_value) ttl (ttl_value) \ 2739 tag (verification_tag) vlan (vlan_value) \ 2740 flexbytes (flexbytes_value) (drop|fwd) \ 2741 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) 2742 2743 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ 2744 ether (ethertype) flexbytes (flexbytes_value) \ 2745 (drop|fwd) pf|vf(vf_id) queue (queue_id) 2746 fd_id (fd_id_value) 2747 2748 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ 2749 mac (mac_address) vlan (vlan_value) \ 2750 flexbytes (flexbytes_value) (drop|fwd) \ 2751 queue (queue_id) fd_id (fd_id_value) 2752 2753 flow_director_filter (port_id) mode Tunnel (add|del|update) \ 2754 mac (mac_address) vlan (vlan_value) \ 2755 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ 2756 flexbytes (flexbytes_value) (drop|fwd) \ 2757 queue (queue_id) fd_id (fd_id_value) 2758 2759 flow_director_filter (port_id) mode raw (add|del|update) flow (flow_id) \ 2760 (drop|fwd) queue (queue_id) fd_id (fd_id_value) \ 2761 packet (packet file name) 2762 2763For example, to add an ipv4-udp flow type filter:: 2764 2765 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ 2766 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ 2767 fwd pf queue 1 fd_id 1 2768 2769For example, add an ipv4-other flow type filter:: 2770 2771 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ 2772 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ 2773 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 2774 2775flush_flow_director 2776~~~~~~~~~~~~~~~~~~~ 2777 2778Flush all flow director filters on a device:: 2779 2780 testpmd> flush_flow_director (port_id) 2781 2782Example, to flush all flow director filter on port 0:: 2783 2784 testpmd> flush_flow_director 0 2785 2786flow_director_mask 2787~~~~~~~~~~~~~~~~~~ 2788 2789Set flow director's input masks:: 2790 2791 flow_director_mask (port_id) mode IP vlan (vlan_value) \ 2792 src_mask (ipv4_src) (ipv6_src) (src_port) \ 2793 dst_mask (ipv4_dst) (ipv6_dst) (dst_port) 2794 2795 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) 2796 2797 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ 2798 mac (mac_value) tunnel-type (tunnel_type_value) \ 2799 tunnel-id (tunnel_id_value) 2800 2801Example, to set flow director mask on port 0:: 2802 2803 testpmd> flow_director_mask 0 mode IP vlan 0xefff \ 2804 src_mask 255.255.255.255 \ 2805 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ 2806 dst_mask 255.255.255.255 \ 2807 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF 2808 2809flow_director_flex_mask 2810~~~~~~~~~~~~~~~~~~~~~~~ 2811 2812set masks of flow director's flexible payload based on certain flow type:: 2813 2814 testpmd> flow_director_flex_mask (port_id) \ 2815 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2816 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ 2817 l2_payload|all) (mask) 2818 2819Example, to set flow director's flex mask for all flow type on port 0:: 2820 2821 testpmd> flow_director_flex_mask 0 flow all \ 2822 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 2823 2824 2825flow_director_flex_payload 2826~~~~~~~~~~~~~~~~~~~~~~~~~~ 2827 2828Configure flexible payload selection:: 2829 2830 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) 2831 2832For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload:: 2833 2834 testpmd> flow_director_flex_payload 0 l4 \ 2835 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) 2836 2837get_sym_hash_ena_per_port 2838~~~~~~~~~~~~~~~~~~~~~~~~~ 2839 2840Get symmetric hash enable configuration per port:: 2841 2842 get_sym_hash_ena_per_port (port_id) 2843 2844For example, to get symmetric hash enable configuration of port 1:: 2845 2846 testpmd> get_sym_hash_ena_per_port 1 2847 2848set_sym_hash_ena_per_port 2849~~~~~~~~~~~~~~~~~~~~~~~~~ 2850 2851Set symmetric hash enable configuration per port to enable or disable:: 2852 2853 set_sym_hash_ena_per_port (port_id) (enable|disable) 2854 2855For example, to set symmetric hash enable configuration of port 1 to enable:: 2856 2857 testpmd> set_sym_hash_ena_per_port 1 enable 2858 2859get_hash_global_config 2860~~~~~~~~~~~~~~~~~~~~~~ 2861 2862Get the global configurations of hash filters:: 2863 2864 get_hash_global_config (port_id) 2865 2866For example, to get the global configurations of hash filters of port 1:: 2867 2868 testpmd> get_hash_global_config 1 2869 2870set_hash_global_config 2871~~~~~~~~~~~~~~~~~~~~~~ 2872 2873Set the global configurations of hash filters:: 2874 2875 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ 2876 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \ 2877 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload|<flow_id>) \ 2878 (enable|disable) 2879 2880For example, to enable simple_xor for flow type of ipv6 on port 2:: 2881 2882 testpmd> set_hash_global_config 2 simple_xor ipv6 enable 2883 2884set_hash_input_set 2885~~~~~~~~~~~~~~~~~~ 2886 2887Set the input set for hash:: 2888 2889 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2890 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2891 l2_payload|<flow_id>) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6| \ 2892 ipv4-tos|ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ 2893 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ 2894 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ 2895 fld-8th|none) (select|add) 2896 2897For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: 2898 2899 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add 2900 2901set_fdir_input_set 2902~~~~~~~~~~~~~~~~~~ 2903 2904The Flow Director filters can match the different fields for different type of packet, i.e. specific input set 2905on per flow type and the flexible payload. This command can be used to change input set for each flow type. 2906 2907Set the input set for flow director:: 2908 2909 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2910 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2911 l2_payload|<flow_id>) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6| \ 2912 ipv4-tos|ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ 2913 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ 2914 sctp-dst-port|sctp-veri-tag|none) (select|add) 2915 2916For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: 2917 2918 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add 2919 2920global_config 2921~~~~~~~~~~~~~ 2922 2923Set different GRE key length for input set:: 2924 2925 global_config (port_id) gre-key-len (number in bytes) 2926 2927For example to set GRE key length for input set to 4 bytes on port 0:: 2928 2929 testpmd> global_config 0 gre-key-len 4 2930 2931 2932.. _testpmd_rte_flow: 2933 2934Flow rules management 2935--------------------- 2936 2937Control of the generic flow API (*rte_flow*) is fully exposed through the 2938``flow`` command (validation, creation, destruction, queries and operation 2939modes). 2940 2941Considering *rte_flow* overlaps with all `Filter Functions`_, using both 2942features simultaneously may cause undefined side-effects and is therefore 2943not recommended. 2944 2945``flow`` syntax 2946~~~~~~~~~~~~~~~ 2947 2948Because the ``flow`` command uses dynamic tokens to handle the large number 2949of possible flow rules combinations, its behavior differs slightly from 2950other commands, in particular: 2951 2952- Pressing *?* or the *<tab>* key displays contextual help for the current 2953 token, not that of the entire command. 2954 2955- Optional and repeated parameters are supported (provided they are listed 2956 in the contextual help). 2957 2958The first parameter stands for the operation mode. Possible operations and 2959their general syntax are described below. They are covered in detail in the 2960following sections. 2961 2962- Check whether a flow rule can be created:: 2963 2964 flow validate {port_id} 2965 [group {group_id}] [priority {level}] [ingress] [egress] 2966 pattern {item} [/ {item} [...]] / end 2967 actions {action} [/ {action} [...]] / end 2968 2969- Create a flow rule:: 2970 2971 flow create {port_id} 2972 [group {group_id}] [priority {level}] [ingress] [egress] 2973 pattern {item} [/ {item} [...]] / end 2974 actions {action} [/ {action} [...]] / end 2975 2976- Destroy specific flow rules:: 2977 2978 flow destroy {port_id} rule {rule_id} [...] 2979 2980- Destroy all flow rules:: 2981 2982 flow flush {port_id} 2983 2984- Query an existing flow rule:: 2985 2986 flow query {port_id} {rule_id} {action} 2987 2988- List existing flow rules sorted by priority, filtered by group 2989 identifiers:: 2990 2991 flow list {port_id} [group {group_id}] [...] 2992 2993- Restrict ingress traffic to the defined flow rules:: 2994 2995 flow isolate {port_id} {boolean} 2996 2997Validating flow rules 2998~~~~~~~~~~~~~~~~~~~~~ 2999 3000``flow validate`` reports whether a flow rule would be accepted by the 3001underlying device in its current state but stops short of creating it. It is 3002bound to ``rte_flow_validate()``:: 3003 3004 flow validate {port_id} 3005 [group {group_id}] [priority {level}] [ingress] [egress] 3006 pattern {item} [/ {item} [...]] / end 3007 actions {action} [/ {action} [...]] / end 3008 3009If successful, it will show:: 3010 3011 Flow rule validated 3012 3013Otherwise it will show an error message of the form:: 3014 3015 Caught error type [...] ([...]): [...] 3016 3017This command uses the same parameters as ``flow create``, their format is 3018described in `Creating flow rules`_. 3019 3020Check whether redirecting any Ethernet packet received on port 0 to RX queue 3021index 6 is supported:: 3022 3023 testpmd> flow validate 0 ingress pattern eth / end 3024 actions queue index 6 / end 3025 Flow rule validated 3026 testpmd> 3027 3028Port 0 does not support TCPv6 rules:: 3029 3030 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end 3031 actions drop / end 3032 Caught error type 9 (specific pattern item): Invalid argument 3033 testpmd> 3034 3035Creating flow rules 3036~~~~~~~~~~~~~~~~~~~ 3037 3038``flow create`` validates and creates the specified flow rule. It is bound 3039to ``rte_flow_create()``:: 3040 3041 flow create {port_id} 3042 [group {group_id}] [priority {level}] [ingress] [egress] 3043 pattern {item} [/ {item} [...]] / end 3044 actions {action} [/ {action} [...]] / end 3045 3046If successful, it will return a flow rule ID usable with other commands:: 3047 3048 Flow rule #[...] created 3049 3050Otherwise it will show an error message of the form:: 3051 3052 Caught error type [...] ([...]): [...] 3053 3054Parameters describe in the following order: 3055 3056- Attributes (*group*, *priority*, *ingress*, *egress* tokens). 3057- A matching pattern, starting with the *pattern* token and terminated by an 3058 *end* pattern item. 3059- Actions, starting with the *actions* token and terminated by an *end* 3060 action. 3061 3062These translate directly to *rte_flow* objects provided as-is to the 3063underlying functions. 3064 3065The shortest valid definition only comprises mandatory tokens:: 3066 3067 testpmd> flow create 0 pattern end actions end 3068 3069Note that PMDs may refuse rules that essentially do nothing such as this 3070one. 3071 3072**All unspecified object values are automatically initialized to 0.** 3073 3074Attributes 3075^^^^^^^^^^ 3076 3077These tokens affect flow rule attributes (``struct rte_flow_attr``) and are 3078specified before the ``pattern`` token. 3079 3080- ``group {group id}``: priority group. 3081- ``priority {level}``: priority level within group. 3082- ``ingress``: rule applies to ingress traffic. 3083- ``egress``: rule applies to egress traffic. 3084 3085Each instance of an attribute specified several times overrides the previous 3086value as shown below (group 4 is used):: 3087 3088 testpmd> flow create 0 group 42 group 24 group 4 [...] 3089 3090Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. 3091 3092While not specifying a direction is an error, some rules may allow both 3093simultaneously. 3094 3095Most rules affect RX therefore contain the ``ingress`` token:: 3096 3097 testpmd> flow create 0 ingress pattern [...] 3098 3099Matching pattern 3100^^^^^^^^^^^^^^^^ 3101 3102A matching pattern starts after the ``pattern`` token. It is made of pattern 3103items and is terminated by a mandatory ``end`` item. 3104 3105Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum 3106rte_flow_item_type``). 3107 3108The ``/`` token is used as a separator between pattern items as shown 3109below:: 3110 3111 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] 3112 3113Note that protocol items like these must be stacked from lowest to highest 3114layer to make sense. For instance, the following rule is either invalid or 3115unlikely to match any packet:: 3116 3117 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] 3118 3119More information on these restrictions can be found in the *rte_flow* 3120documentation. 3121 3122Several items support additional specification structures, for example 3123``ipv4`` allows specifying source and destination addresses as follows:: 3124 3125 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 3126 dst is 10.2.0.0 / end [...] 3127 3128This rule matches all IPv4 traffic with the specified properties. 3129 3130In this example, ``src`` and ``dst`` are field names of the underlying 3131``struct rte_flow_item_ipv4`` object. All item properties can be specified 3132in a similar fashion. 3133 3134The ``is`` token means that the subsequent value must be matched exactly, 3135and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` 3136accordingly. Possible assignment tokens are: 3137 3138- ``is``: match value perfectly (with full bit-mask). 3139- ``spec``: match value according to configured bit-mask. 3140- ``last``: specify upper bound to establish a range. 3141- ``mask``: specify bit-mask with relevant bits set to one. 3142- ``prefix``: generate bit-mask from a prefix length. 3143 3144These yield identical results:: 3145 3146 ipv4 src is 10.1.1.1 3147 3148:: 3149 3150 ipv4 src spec 10.1.1.1 src mask 255.255.255.255 3151 3152:: 3153 3154 ipv4 src spec 10.1.1.1 src prefix 32 3155 3156:: 3157 3158 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value 3159 3160:: 3161 3162 ipv4 src is 10.1.1.1 src last 0 # 0 disables range 3163 3164Inclusive ranges can be defined with ``last``:: 3165 3166 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 3167 3168Note that ``mask`` affects both ``spec`` and ``last``:: 3169 3170 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 3171 # matches 10.1.0.0 to 10.2.255.255 3172 3173Properties can be modified multiple times:: 3174 3175 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 3176 3177:: 3178 3179 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 3180 3181Pattern items 3182^^^^^^^^^^^^^ 3183 3184This section lists supported pattern items and their attributes, if any. 3185 3186- ``end``: end list of pattern items. 3187 3188- ``void``: no-op pattern item. 3189 3190- ``invert``: perform actions when pattern does not match. 3191 3192- ``any``: match any protocol for the current layer. 3193 3194 - ``num {unsigned}``: number of layers covered. 3195 3196- ``pf``: match packets addressed to the physical function. 3197 3198- ``vf``: match packets addressed to a virtual function ID. 3199 3200 - ``id {unsigned}``: destination VF ID. 3201 3202- ``port``: device-specific physical port index to use. 3203 3204 - ``index {unsigned}``: physical port index. 3205 3206- ``raw``: match an arbitrary byte string. 3207 3208 - ``relative {boolean}``: look for pattern after the previous item. 3209 - ``search {boolean}``: search pattern from offset (see also limit). 3210 - ``offset {integer}``: absolute or relative offset for pattern. 3211 - ``limit {unsigned}``: search area limit for start of pattern. 3212 - ``pattern {string}``: byte string to look for. 3213 3214- ``eth``: match Ethernet header. 3215 3216 - ``dst {MAC-48}``: destination MAC. 3217 - ``src {MAC-48}``: source MAC. 3218 - ``type {unsigned}``: EtherType. 3219 3220- ``vlan``: match 802.1Q/ad VLAN tag. 3221 3222 - ``tpid {unsigned}``: tag protocol identifier. 3223 - ``tci {unsigned}``: tag control information. 3224 - ``pcp {unsigned}``: priority code point. 3225 - ``dei {unsigned}``: drop eligible indicator. 3226 - ``vid {unsigned}``: VLAN identifier. 3227 3228- ``ipv4``: match IPv4 header. 3229 3230 - ``tos {unsigned}``: type of service. 3231 - ``ttl {unsigned}``: time to live. 3232 - ``proto {unsigned}``: next protocol ID. 3233 - ``src {ipv4 address}``: source address. 3234 - ``dst {ipv4 address}``: destination address. 3235 3236- ``ipv6``: match IPv6 header. 3237 3238 - ``tc {unsigned}``: traffic class. 3239 - ``flow {unsigned}``: flow label. 3240 - ``proto {unsigned}``: protocol (next header). 3241 - ``hop {unsigned}``: hop limit. 3242 - ``src {ipv6 address}``: source address. 3243 - ``dst {ipv6 address}``: destination address. 3244 3245- ``icmp``: match ICMP header. 3246 3247 - ``type {unsigned}``: ICMP packet type. 3248 - ``code {unsigned}``: ICMP packet code. 3249 3250- ``udp``: match UDP header. 3251 3252 - ``src {unsigned}``: UDP source port. 3253 - ``dst {unsigned}``: UDP destination port. 3254 3255- ``tcp``: match TCP header. 3256 3257 - ``src {unsigned}``: TCP source port. 3258 - ``dst {unsigned}``: TCP destination port. 3259 3260- ``sctp``: match SCTP header. 3261 3262 - ``src {unsigned}``: SCTP source port. 3263 - ``dst {unsigned}``: SCTP destination port. 3264 - ``tag {unsigned}``: validation tag. 3265 - ``cksum {unsigned}``: checksum. 3266 3267- ``vxlan``: match VXLAN header. 3268 3269 - ``vni {unsigned}``: VXLAN identifier. 3270 3271- ``e_tag``: match IEEE 802.1BR E-Tag header. 3272 3273 - ``grp_ecid_b {unsigned}``: GRP and E-CID base. 3274 3275- ``nvgre``: match NVGRE header. 3276 3277 - ``tni {unsigned}``: virtual subnet ID. 3278 3279- ``mpls``: match MPLS header. 3280 3281 - ``label {unsigned}``: MPLS label. 3282 3283- ``gre``: match GRE header. 3284 3285 - ``protocol {unsigned}``: protocol type. 3286 3287- ``fuzzy``: fuzzy pattern match, expect faster than default. 3288 3289 - ``thresh {unsigned}``: accuracy threshold. 3290 3291- ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header. 3292 3293 - ``teid {unsigned}``: tunnel endpoint identifier. 3294 3295- ``geneve``: match GENEVE header. 3296 3297 - ``vni {unsigned}``: virtual network identifier. 3298 - ``protocol {unsigned}``: protocol type. 3299 3300Actions list 3301^^^^^^^^^^^^ 3302 3303A list of actions starts after the ``actions`` token in the same fashion as 3304`Matching pattern`_; actions are separated by ``/`` tokens and the list is 3305terminated by a mandatory ``end`` action. 3306 3307Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum 3308rte_flow_action_type``). 3309 3310Dropping all incoming UDPv4 packets can be expressed as follows:: 3311 3312 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3313 actions drop / end 3314 3315Several actions have configurable properties which must be specified when 3316there is no valid default value. For example, ``queue`` requires a target 3317queue index. 3318 3319This rule redirects incoming UDPv4 traffic to queue index 6:: 3320 3321 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3322 actions queue index 6 / end 3323 3324While this one could be rejected by PMDs (unspecified queue index):: 3325 3326 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3327 actions queue / end 3328 3329As defined by *rte_flow*, the list is not ordered, all actions of a given 3330rule are performed simultaneously. These are equivalent:: 3331 3332 queue index 6 / void / mark id 42 / end 3333 3334:: 3335 3336 void / mark id 42 / queue index 6 / end 3337 3338All actions in a list should have different types, otherwise only the last 3339action of a given type is taken into account:: 3340 3341 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 3342 3343:: 3344 3345 drop / drop / drop / end # drop is performed only once 3346 3347:: 3348 3349 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 3350 3351Considering they are performed simultaneously, opposite and overlapping 3352actions can sometimes be combined when the end result is unambiguous:: 3353 3354 drop / queue index 6 / end # drop has no effect 3355 3356:: 3357 3358 drop / dup index 6 / end # same as above 3359 3360:: 3361 3362 queue index 6 / rss queues 6 7 8 / end # queue has no effect 3363 3364:: 3365 3366 drop / passthru / end # drop has no effect 3367 3368Note that PMDs may still refuse such combinations. 3369 3370Actions 3371^^^^^^^ 3372 3373This section lists supported actions and their attributes, if any. 3374 3375- ``end``: end list of actions. 3376 3377- ``void``: no-op action. 3378 3379- ``passthru``: let subsequent rule process matched packets. 3380 3381- ``mark``: attach 32 bit value to packets. 3382 3383 - ``id {unsigned}``: 32 bit value to return with packets. 3384 3385- ``flag``: flag packets. 3386 3387- ``queue``: assign packets to a given queue index. 3388 3389 - ``index {unsigned}``: queue index to use. 3390 3391- ``drop``: drop packets (note: passthru has priority). 3392 3393- ``count``: enable counters for this rule. 3394 3395- ``dup``: duplicate packets to a given queue index. 3396 3397 - ``index {unsigned}``: queue index to duplicate packets to. 3398 3399- ``rss``: spread packets among several queues. 3400 3401 - ``queues [{unsigned} [...]] end``: queue indices to use. 3402 3403- ``pf``: redirect packets to physical device function. 3404 3405- ``vf``: redirect packets to virtual device function. 3406 3407 - ``original {boolean}``: use original VF ID if possible. 3408 - ``id {unsigned}``: VF ID to redirect packets to. 3409 3410Destroying flow rules 3411~~~~~~~~~~~~~~~~~~~~~ 3412 3413``flow destroy`` destroys one or more rules from their rule ID (as returned 3414by ``flow create``), this command calls ``rte_flow_destroy()`` as many 3415times as necessary:: 3416 3417 flow destroy {port_id} rule {rule_id} [...] 3418 3419If successful, it will show:: 3420 3421 Flow rule #[...] destroyed 3422 3423It does not report anything for rule IDs that do not exist. The usual error 3424message is shown when a rule cannot be destroyed:: 3425 3426 Caught error type [...] ([...]): [...] 3427 3428``flow flush`` destroys all rules on a device and does not take extra 3429arguments. It is bound to ``rte_flow_flush()``:: 3430 3431 flow flush {port_id} 3432 3433Any errors are reported as above. 3434 3435Creating several rules and destroying them:: 3436 3437 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3438 actions queue index 2 / end 3439 Flow rule #0 created 3440 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3441 actions queue index 3 / end 3442 Flow rule #1 created 3443 testpmd> flow destroy 0 rule 0 rule 1 3444 Flow rule #1 destroyed 3445 Flow rule #0 destroyed 3446 testpmd> 3447 3448The same result can be achieved using ``flow flush``:: 3449 3450 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3451 actions queue index 2 / end 3452 Flow rule #0 created 3453 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3454 actions queue index 3 / end 3455 Flow rule #1 created 3456 testpmd> flow flush 0 3457 testpmd> 3458 3459Non-existent rule IDs are ignored:: 3460 3461 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3462 actions queue index 2 / end 3463 Flow rule #0 created 3464 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3465 actions queue index 3 / end 3466 Flow rule #1 created 3467 testpmd> flow destroy 0 rule 42 rule 10 rule 2 3468 testpmd> 3469 testpmd> flow destroy 0 rule 0 3470 Flow rule #0 destroyed 3471 testpmd> 3472 3473Querying flow rules 3474~~~~~~~~~~~~~~~~~~~ 3475 3476``flow query`` queries a specific action of a flow rule having that 3477ability. Such actions collect information that can be reported using this 3478command. It is bound to ``rte_flow_query()``:: 3479 3480 flow query {port_id} {rule_id} {action} 3481 3482If successful, it will display either the retrieved data for known actions 3483or the following message:: 3484 3485 Cannot display result for action type [...] ([...]) 3486 3487Otherwise, it will complain either that the rule does not exist or that some 3488error occurred:: 3489 3490 Flow rule #[...] not found 3491 3492:: 3493 3494 Caught error type [...] ([...]): [...] 3495 3496Currently only the ``count`` action is supported. This action reports the 3497number of packets that hit the flow rule and the total number of bytes. Its 3498output has the following format:: 3499 3500 count: 3501 hits_set: [...] # whether "hits" contains a valid value 3502 bytes_set: [...] # whether "bytes" contains a valid value 3503 hits: [...] # number of packets 3504 bytes: [...] # number of bytes 3505 3506Querying counters for TCPv6 packets redirected to queue 6:: 3507 3508 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end 3509 actions queue index 6 / count / end 3510 Flow rule #4 created 3511 testpmd> flow query 0 4 count 3512 count: 3513 hits_set: 1 3514 bytes_set: 0 3515 hits: 386446 3516 bytes: 0 3517 testpmd> 3518 3519Listing flow rules 3520~~~~~~~~~~~~~~~~~~ 3521 3522``flow list`` lists existing flow rules sorted by priority and optionally 3523filtered by group identifiers:: 3524 3525 flow list {port_id} [group {group_id}] [...] 3526 3527This command only fails with the following message if the device does not 3528exist:: 3529 3530 Invalid port [...] 3531 3532Output consists of a header line followed by a short description of each 3533flow rule, one per line. There is no output at all when no flow rules are 3534configured on the device:: 3535 3536 ID Group Prio Attr Rule 3537 [...] [...] [...] [...] [...] 3538 3539``Attr`` column flags: 3540 3541- ``i`` for ``ingress``. 3542- ``e`` for ``egress``. 3543 3544Creating several flow rules and listing them:: 3545 3546 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3547 actions queue index 6 / end 3548 Flow rule #0 created 3549 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3550 actions queue index 2 / end 3551 Flow rule #1 created 3552 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end 3553 actions rss queues 6 7 8 end / end 3554 Flow rule #2 created 3555 testpmd> flow list 0 3556 ID Group Prio Attr Rule 3557 0 0 0 i- ETH IPV4 => QUEUE 3558 1 0 0 i- ETH IPV6 => QUEUE 3559 2 0 5 i- ETH IPV4 UDP => RSS 3560 testpmd> 3561 3562Rules are sorted by priority (i.e. group ID first, then priority level):: 3563 3564 testpmd> flow list 1 3565 ID Group Prio Attr Rule 3566 0 0 0 i- ETH => COUNT 3567 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3568 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3569 1 24 0 i- ETH IPV4 UDP => QUEUE 3570 4 24 10 i- ETH IPV4 TCP => DROP 3571 3 24 20 i- ETH IPV4 => DROP 3572 2 24 42 i- ETH IPV4 UDP => QUEUE 3573 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3574 testpmd> 3575 3576Output can be limited to specific groups:: 3577 3578 testpmd> flow list 1 group 0 group 63 3579 ID Group Prio Attr Rule 3580 0 0 0 i- ETH => COUNT 3581 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3582 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3583 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3584 testpmd> 3585 3586Toggling isolated mode 3587~~~~~~~~~~~~~~~~~~~~~~ 3588 3589``flow isolate`` can be used to tell the underlying PMD that ingress traffic 3590must only be injected from the defined flow rules; that no default traffic 3591is expected outside those rules and the driver is free to assign more 3592resources to handle them. It is bound to ``rte_flow_isolate()``:: 3593 3594 flow isolate {port_id} {boolean} 3595 3596If successful, enabling or disabling isolated mode shows either:: 3597 3598 Ingress traffic on port [...] 3599 is now restricted to the defined flow rules 3600 3601Or:: 3602 3603 Ingress traffic on port [...] 3604 is not restricted anymore to the defined flow rules 3605 3606Otherwise, in case of error:: 3607 3608 Caught error type [...] ([...]): [...] 3609 3610Mainly due to its side effects, PMDs supporting this mode may not have the 3611ability to toggle it more than once without reinitializing affected ports 3612first (e.g. by exiting testpmd). 3613 3614Enabling isolated mode:: 3615 3616 testpmd> flow isolate 0 true 3617 Ingress traffic on port 0 is now restricted to the defined flow rules 3618 testpmd> 3619 3620Disabling isolated mode:: 3621 3622 testpmd> flow isolate 0 false 3623 Ingress traffic on port 0 is not restricted anymore to the defined flow rules 3624 testpmd> 3625 3626Sample QinQ flow rules 3627~~~~~~~~~~~~~~~~~~~~~~ 3628 3629Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: 3630 3631 testpmd> port stop 0 3632 testpmd> vlan set qinq on 0 3633 3634The above command sets the inner and outer TPID's to 0x8100. 3635 3636To change the TPID's the following commands should be used:: 3637 3638 testpmd> vlan set outer tpid 0xa100 0 3639 testpmd> vlan set inner tpid 0x9100 0 3640 testpmd> port start 0 3641 3642Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. 3643 3644:: 3645 3646 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / 3647 vlan tci is 456 / end actions vf id 1 / queue index 0 / end 3648 Flow rule #0 validated 3649 3650 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / 3651 vlan tci is 456 / end actions vf id 123 / queue index 0 / end 3652 Flow rule #0 created 3653 3654 testpmd> flow list 0 3655 ID Group Prio Attr Rule 3656 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3657 3658Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. 3659 3660:: 3661 3662 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / 3663 vlan tci is 654 / end actions pf / queue index 0 / end 3664 Flow rule #1 validated 3665 3666 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / 3667 vlan tci is 654 / end actions pf / queue index 1 / end 3668 Flow rule #1 created 3669 3670 testpmd> flow list 0 3671 ID Group Prio Attr Rule 3672 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3673 1 0 0 i- ETH VLAN VLAN=>PF QUEUE 3674