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 1850port config input set 1851~~~~~~~~~~~~~~~~~~~~~ 1852 1853Config RSS/FDIR/FDIR flexible payload input set for some pctype:: 1854 testpmd> port config (port_id) pctype (pctype_id) \ 1855 (hash_inset|fdir_inset|fdir_flx_inset) \ 1856 (get|set|clear) field (field_idx) 1857 1858Clear RSS/FDIR/FDIR flexible payload input set for some pctype:: 1859 testpmd> port config (port_id) pctype (pctype_id) \ 1860 (hash_inset|fdir_inset|fdir_flx_inset) clear all 1861 1862where: 1863 1864* ``pctype_id``: hardware packet classification types. 1865* ``field_idx``: hardware field index. 1866 1867Link Bonding Functions 1868---------------------- 1869 1870The Link Bonding functions make it possible to dynamically create and 1871manage link bonding devices from within testpmd interactive prompt. 1872 1873create bonded device 1874~~~~~~~~~~~~~~~~~~~~ 1875 1876Create a new bonding device:: 1877 1878 testpmd> create bonded device (mode) (socket) 1879 1880For example, to create a bonded device in mode 1 on socket 0:: 1881 1882 testpmd> create bonded 1 0 1883 created new bonded device (port X) 1884 1885add bonding slave 1886~~~~~~~~~~~~~~~~~ 1887 1888Adds Ethernet device to a Link Bonding device:: 1889 1890 testpmd> add bonding slave (slave id) (port id) 1891 1892For example, to add Ethernet device (port 6) to a Link Bonding device (port 10):: 1893 1894 testpmd> add bonding slave 6 10 1895 1896 1897remove bonding slave 1898~~~~~~~~~~~~~~~~~~~~ 1899 1900Removes an Ethernet slave device from a Link Bonding device:: 1901 1902 testpmd> remove bonding slave (slave id) (port id) 1903 1904For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10):: 1905 1906 testpmd> remove bonding slave 6 10 1907 1908set bonding mode 1909~~~~~~~~~~~~~~~~ 1910 1911Set the Link Bonding mode of a Link Bonding device:: 1912 1913 testpmd> set bonding mode (value) (port id) 1914 1915For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3):: 1916 1917 testpmd> set bonding mode 3 10 1918 1919set bonding primary 1920~~~~~~~~~~~~~~~~~~~ 1921 1922Set an Ethernet slave device as the primary device on a Link Bonding device:: 1923 1924 testpmd> set bonding primary (slave id) (port id) 1925 1926For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10):: 1927 1928 testpmd> set bonding primary 6 10 1929 1930set bonding mac 1931~~~~~~~~~~~~~~~ 1932 1933Set the MAC address of a Link Bonding device:: 1934 1935 testpmd> set bonding mac (port id) (mac) 1936 1937For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01:: 1938 1939 testpmd> set bonding mac 10 00:00:00:00:00:01 1940 1941set bonding xmit_balance_policy 1942~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1943 1944Set the transmission policy for a Link Bonding device when it is in Balance XOR mode:: 1945 1946 testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34) 1947 1948For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports):: 1949 1950 testpmd> set bonding xmit_balance_policy 10 l34 1951 1952 1953set bonding mon_period 1954~~~~~~~~~~~~~~~~~~~~~~ 1955 1956Set the link status monitoring polling period in milliseconds for a bonding device. 1957 1958This adds support for PMD slave devices which do not support link status interrupts. 1959When the mon_period is set to a value greater than 0 then all PMD's which do not support 1960link status ISR will be queried every polling interval to check if their link status has changed:: 1961 1962 testpmd> set bonding mon_period (port_id) (value) 1963 1964For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms:: 1965 1966 testpmd> set bonding mon_period 5 150 1967 1968 1969set bonding lacp dedicated_queue 1970~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1971 1972Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic 1973when in mode 4 (link-aggregration-802.3ad):: 1974 1975 testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable) 1976 1977 1978set bonding agg_mode 1979~~~~~~~~~~~~~~~~~~~~ 1980 1981Enable one of the specific aggregators mode when in mode 4 (link-aggregration-802.3ad):: 1982 1983 testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable) 1984 1985 1986show bonding config 1987~~~~~~~~~~~~~~~~~~~ 1988 1989Show the current configuration of a Link Bonding device:: 1990 1991 testpmd> show bonding config (port id) 1992 1993For example, 1994to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4) 1995in balance mode with a transmission policy of layer 2+3:: 1996 1997 testpmd> show bonding config 9 1998 Bonding mode: 2 1999 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23 2000 Slaves (3): [1 3 4] 2001 Active Slaves (3): [1 3 4] 2002 Primary: [3] 2003 2004 2005Register Functions 2006------------------ 2007 2008The Register Functions can be used to read from and write to registers on the network card referenced by a port number. 2009This is mainly useful for debugging purposes. 2010Reference should be made to the appropriate datasheet for the network card for details on the register addresses 2011and fields that can be accessed. 2012 2013read reg 2014~~~~~~~~ 2015 2016Display the value of a port register:: 2017 2018 testpmd> read reg (port_id) (address) 2019 2020For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller:: 2021 2022 testpmd> read reg 0 0xEE00 2023 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) 2024 2025read regfield 2026~~~~~~~~~~~~~ 2027 2028Display a port register bit field:: 2029 2030 testpmd> read regfield (port_id) (address) (bit_x) (bit_y) 2031 2032For example, reading the lowest two bits from the register in the example above:: 2033 2034 testpmd> read regfield 0 0xEE00 0 1 2035 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1) 2036 2037read regbit 2038~~~~~~~~~~~ 2039 2040Display a single port register bit:: 2041 2042 testpmd> read regbit (port_id) (address) (bit_x) 2043 2044For example, reading the lowest bit from the register in the example above:: 2045 2046 testpmd> read regbit 0 0xEE00 0 2047 port 0 PCI register at offset 0xEE00: bit 0=1 2048 2049write reg 2050~~~~~~~~~ 2051 2052Set the value of a port register:: 2053 2054 testpmd> write reg (port_id) (address) (value) 2055 2056For example, to clear a register:: 2057 2058 testpmd> write reg 0 0xEE00 0x0 2059 port 0 PCI register at offset 0xEE00: 0x00000000 (0) 2060 2061write regfield 2062~~~~~~~~~~~~~~ 2063 2064Set bit field of a port register:: 2065 2066 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value) 2067 2068For example, writing to the register cleared in the example above:: 2069 2070 testpmd> write regfield 0 0xEE00 0 1 2 2071 port 0 PCI register at offset 0xEE00: 0x00000002 (2) 2072 2073write regbit 2074~~~~~~~~~~~~ 2075 2076Set single bit value of a port register:: 2077 2078 testpmd> write regbit (port_id) (address) (bit_x) (value) 2079 2080For example, to set the high bit in the register from the example above:: 2081 2082 testpmd> write regbit 0 0xEE00 31 1 2083 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) 2084 2085Traffic Metering and Policing 2086----------------------------- 2087 2088The following section shows functions for configuring traffic metering and 2089policing on the ethernet device through the use of generic ethdev API. 2090 2091show port traffic management capability 2092~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2093 2094Show traffic metering and policing capability of the port:: 2095 2096 testpmd> show port meter cap (port_id) 2097 2098add port meter profile (srTCM rfc2967) 2099~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2100 2101Add meter profile (srTCM rfc2697) to the ethernet device:: 2102 2103 testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \ 2104 (cir) (cbs) (ebs) 2105 2106where: 2107 2108* ``profile_id``: ID for the meter profile. 2109* ``cir``: Committed Information Rate (CIR) (bytes/second). 2110* ``cbs``: Committed Burst Size (CBS) (bytes). 2111* ``ebs``: Excess Burst Size (EBS) (bytes). 2112 2113add port meter profile (trTCM rfc2968) 2114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2115 2116Add meter profile (srTCM rfc2698) to the ethernet device:: 2117 2118 testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \ 2119 (cir) (pir) (cbs) (pbs) 2120 2121where: 2122 2123* ``profile_id``: ID for the meter profile. 2124* ``cir``: Committed information rate (bytes/second). 2125* ``pir``: Peak information rate (bytes/second). 2126* ``cbs``: Committed burst size (bytes). 2127* ``pbs``: Peak burst size (bytes). 2128 2129add port meter profile (trTCM rfc4115) 2130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2131 2132Add meter profile (trTCM rfc4115) to the ethernet device:: 2133 2134 testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \ 2135 (cir) (eir) (cbs) (ebs) 2136 2137where: 2138 2139* ``profile_id``: ID for the meter profile. 2140* ``cir``: Committed information rate (bytes/second). 2141* ``eir``: Excess information rate (bytes/second). 2142* ``cbs``: Committed burst size (bytes). 2143* ``ebs``: Excess burst size (bytes). 2144 2145delete port meter profile 2146~~~~~~~~~~~~~~~~~~~~~~~~~ 2147 2148Delete meter profile from the ethernet device:: 2149 2150 testpmd> del port meter profile (port_id) (profile_id) 2151 2152create port meter 2153~~~~~~~~~~~~~~~~~ 2154 2155Create new meter object for the ethernet device:: 2156 2157 testpmd> create port meter (port_id) (mtr_id) (profile_id) \ 2158 (meter_enable) (g_action) (y_action) (r_action) (stats_mask) (shared) \ 2159 (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\ 2160 (dscp_tbl_entry63)] 2161 2162where: 2163 2164* ``mtr_id``: meter object ID. 2165* ``profile_id``: ID for the meter profile. 2166* ``meter_enable``: When this parameter has a non-zero value, the meter object 2167 gets enabled at the time of creation, otherwise remains disabled. 2168* ``g_action``: Policer action for the packet with green color. 2169* ``y_action``: Policer action for the packet with yellow color. 2170* ``r_action``: Policer action for the packet with red color. 2171* ``stats_mask``: Mask of statistics counter types to be enabled for the 2172 meter object. 2173* ``shared``: When this parameter has a non-zero value, the meter object is 2174 shared by multiple flows. Otherwise, meter object is used by single flow. 2175* ``use_pre_meter_color``: When this parameter has a non-zero value, the 2176 input color for the current meter object is determined by the latest meter 2177 object in the same flow. Otherwise, the current meter object uses the 2178 *dscp_table* to determine the input color. 2179* ``dscp_tbl_entryx``: DSCP table entry x providing meter providing input 2180 color, 0 <= x <= 63. 2181 2182enable port meter 2183~~~~~~~~~~~~~~~~~ 2184 2185Enable meter for the ethernet device:: 2186 2187 testpmd> enable port meter (port_id) (mtr_id) 2188 2189disable port meter 2190~~~~~~~~~~~~~~~~~~ 2191 2192Disable meter for the ethernet device:: 2193 2194 testpmd> disable port meter (port_id) (mtr_id) 2195 2196delete port meter 2197~~~~~~~~~~~~~~~~~ 2198 2199Delete meter for the ethernet device:: 2200 2201 testpmd> del port meter (port_id) (mtr_id) 2202 2203Set port meter profile 2204~~~~~~~~~~~~~~~~~~~~~~ 2205 2206Set meter profile for the ethernet device:: 2207 2208 testpmd> set port meter profile (port_id) (mtr_id) (profile_id) 2209 2210set port meter dscp table 2211~~~~~~~~~~~~~~~~~~~~~~~~~ 2212 2213Set meter dscp table for the ethernet device:: 2214 2215 testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \ 2216 (dscp_tbl_entry1)...(dscp_tbl_entry63)] 2217 2218set port meter policer action 2219~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2220 2221Set meter policer action for the ethernet device:: 2222 2223 testpmd> set port meter policer action (port_id) (mtr_id) (action_mask) \ 2224 (action0) [(action1) (action1)] 2225 2226where: 2227 2228* ``action_mask``: Bit mask indicating which policer actions need to be 2229 updated. One or more policer actions can be updated in a single function 2230 invocation. To update the policer action associated with color C, bit 2231 (1 << C) needs to be set in *action_mask* and element at position C 2232 in the *actions* array needs to be valid. 2233* ``actionx``: Policer action for the color x, 2234 RTE_MTR_GREEN <= x < RTE_MTR_COLORS 2235 2236set port meter stats mask 2237~~~~~~~~~~~~~~~~~~~~~~~~~ 2238 2239Set meter stats mask for the ethernet device:: 2240 2241 testpmd> set port meter stats mask (port_id) (mtr_id) (stats_mask) 2242 2243where: 2244 2245* ``stats_mask``: Bit mask indicating statistics counter types to be enabled. 2246 2247show port meter stats 2248~~~~~~~~~~~~~~~~~~~~~ 2249 2250Show meter stats of the ethernet device:: 2251 2252 testpmd> show port meter stats (port_id) (mtr_id) (clear) 2253 2254where: 2255 2256* ``clear``: Flag that indicates whether the statistics counters should 2257 be cleared (i.e. set to zero) immediately after they have been read or not. 2258 2259Traffic Management 2260------------------ 2261 2262The following section shows functions for configuring traffic management on 2263on the ethernet device through the use of generic TM API. 2264 2265show port traffic management capability 2266~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2267 2268Show traffic management capability of the port:: 2269 2270 testpmd> show port tm cap (port_id) 2271 2272show port traffic management capability (hierarchy level) 2273~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2274 2275Show traffic management hierarchy level capability of the port:: 2276 2277 testpmd> show port tm cap (port_id) (level_id) 2278 2279show port traffic management capability (hierarchy node level) 2280~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2281 2282Show the traffic management hierarchy node capability of the port:: 2283 2284 testpmd> show port tm cap (port_id) (node_id) 2285 2286show port traffic management hierarchy node type 2287~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2288 2289Show the port traffic management hierarchy node type:: 2290 2291 testpmd> show port tm node type (port_id) (node_id) 2292 2293show port traffic management hierarchy node stats 2294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2295 2296Show the port traffic management hierarchy node statistics:: 2297 2298 testpmd> show port tm node stats (port_id) (node_id) (clear) 2299 2300where: 2301 2302* ``clear``: When this parameter has a non-zero value, the statistics counters 2303 are cleared (i.e. set to zero) immediately after they have been read, 2304 otherwise the statistics counters are left untouched. 2305 2306Add port traffic management private shaper profile 2307~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2308 2309Add the port traffic management private shaper profile:: 2310 2311 testpmd> add port tm node shaper profile (port_id) (shaper_profile_id) \ 2312 (tb_rate) (tb_size) (packet_length_adjust) 2313 2314where: 2315 2316* ``shaper_profile id``: Shaper profile ID for the new profile. 2317* ``tb_rate``: Token bucket rate (bytes per second). 2318* ``tb_size``: Token bucket size (bytes). 2319* ``packet_length_adjust``: The value (bytes) to be added to the length of 2320 each packet for the purpose of shaping. This parameter value can be used to 2321 correct the packet length with the framing overhead bytes that are consumed 2322 on the wire. 2323 2324Delete port traffic management private shaper profile 2325~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2326 2327Delete the port traffic management private shaper:: 2328 2329 testpmd> del port tm node shaper profile (port_id) (shaper_profile_id) 2330 2331where: 2332 2333* ``shaper_profile id``: Shaper profile ID that needs to be deleted. 2334 2335Add port traffic management shared shaper 2336~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2337 2338Create the port traffic management shared shaper:: 2339 2340 testpmd> add port tm node shared shaper (port_id) (shared_shaper_id) \ 2341 (shaper_profile_id) 2342 2343where: 2344 2345* ``shared_shaper_id``: Shared shaper ID to be created. 2346* ``shaper_profile id``: Shaper profile ID for shared shaper. 2347 2348Set port traffic management shared shaper 2349~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2350 2351Update the port traffic management shared shaper:: 2352 2353 testpmd> set port tm node shared shaper (port_id) (shared_shaper_id) \ 2354 (shaper_profile_id) 2355 2356where: 2357 2358* ``shared_shaper_id``: Shared shaper ID to be update. 2359* ``shaper_profile id``: Shaper profile ID for shared shaper. 2360 2361Delete port traffic management shared shaper 2362~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2363 2364Delete the port traffic management shared shaper:: 2365 2366 testpmd> del port tm node shared shaper (port_id) (shared_shaper_id) 2367 2368where: 2369 2370* ``shared_shaper_id``: Shared shaper ID to be deleted. 2371 2372Set port traffic management hiearchy node private shaper 2373~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2374 2375set the port traffic management hierarchy node private shaper:: 2376 2377 testpmd> set port tm node shaper profile (port_id) (node_id) \ 2378 (shaper_profile_id) 2379 2380where: 2381 2382* ``shaper_profile id``: Private shaper profile ID to be enabled on the 2383 hierarchy node. 2384 2385Add port traffic management WRED profile 2386~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2387 2388Create a new WRED profile:: 2389 2390 testpmd> add port tm node wred profile (port_id) (wred_profile_id) \ 2391 (color_g) (min_th_g) (max_th_g) (maxp_inv_g) (wq_log2_g) \ 2392 (color_y) (min_th_y) (max_th_y) (maxp_inv_y) (wq_log2_y) \ 2393 (color_r) (min_th_r) (max_th_r) (maxp_inv_r) (wq_log2_r) 2394 2395where: 2396 2397* ``wred_profile id``: Identifier for the newly create WRED profile 2398* ``color_g``: Packet color (green) 2399* ``min_th_g``: Minimum queue threshold for packet with green color 2400* ``max_th_g``: Minimum queue threshold for packet with green color 2401* ``maxp_inv_g``: Inverse of packet marking probability maximum value (maxp) 2402* ``wq_log2_g``: Negated log2 of queue weight (wq) 2403* ``color_y``: Packet color (yellow) 2404* ``min_th_y``: Minimum queue threshold for packet with yellow color 2405* ``max_th_y``: Minimum queue threshold for packet with yellow color 2406* ``maxp_inv_y``: Inverse of packet marking probability maximum value (maxp) 2407* ``wq_log2_y``: Negated log2 of queue weight (wq) 2408* ``color_r``: Packet color (red) 2409* ``min_th_r``: Minimum queue threshold for packet with yellow color 2410* ``max_th_r``: Minimum queue threshold for packet with yellow color 2411* ``maxp_inv_r``: Inverse of packet marking probability maximum value (maxp) 2412* ``wq_log2_r``: Negated log2 of queue weight (wq) 2413 2414Delete port traffic management WRED profile 2415~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2416 2417Delete the WRED profile:: 2418 2419 testpmd> del port tm node wred profile (port_id) (wred_profile_id) 2420 2421Add port traffic management hierarchy nonleaf node 2422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2423 2424Add nonleaf node to port traffic management hiearchy:: 2425 2426 testpmd> add port tm nonleaf node (port_id) (node_id) (parent_node_id) \ 2427 (priority) (weight) (level_id) (shaper_profile_id) \ 2428 (n_sp_priorities) (stats_mask) (n_shared_shapers) \ 2429 [(shared_shaper_0) (shared_shaper_1) ...] \ 2430 2431where: 2432 2433* ``parent_node_id``: Node ID of the parent. 2434* ``priority``: Node priority (highest node priority is zero). This is used by 2435 the SP algorithm running on the parent node for scheduling this node. 2436* ``weight``: Node weight (lowest weight is one). The node weight is relative 2437 to the weight sum of all siblings that have the same priority. It is used by 2438 the WFQ algorithm running on the parent node for scheduling this node. 2439* ``level_id``: Hiearchy level of the node. 2440* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2441 the node. 2442* ``n_sp_priorities``: Number of strict priorities. 2443* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2444* ``n_shared_shapers``: Number of shared shapers. 2445* ``shared_shaper_id``: Shared shaper id. 2446 2447Add port traffic management hierarchy leaf node 2448~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2449 2450Add leaf node to port traffic management hiearchy:: 2451 2452 testpmd> add port tm leaf node (port_id) (node_id) (parent_node_id) \ 2453 (priority) (weight) (level_id) (shaper_profile_id) \ 2454 (cman_mode) (wred_profile_id) (stats_mask) (n_shared_shapers) \ 2455 [(shared_shaper_id) (shared_shaper_id) ...] \ 2456 2457where: 2458 2459* ``parent_node_id``: Node ID of the parent. 2460* ``priority``: Node priority (highest node priority is zero). This is used by 2461 the SP algorithm running on the parent node for scheduling this node. 2462* ``weight``: Node weight (lowest weight is one). The node weight is relative 2463 to the weight sum of all siblings that have the same priority. It is used by 2464 the WFQ algorithm running on the parent node for scheduling this node. 2465* ``level_id``: Hiearchy level of the node. 2466* ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by 2467 the node. 2468* ``cman_mode``: Congestion management mode to be enabled for this node. 2469* ``wred_profile_id``: WRED profile id to be enabled for this node. 2470* ``stats_mask``: Mask of statistics counter types to be enabled for this node. 2471* ``n_shared_shapers``: Number of shared shapers. 2472* ``shared_shaper_id``: Shared shaper id. 2473 2474Delete port traffic management hierarchy node 2475~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2476 2477Delete node from port traffic management hiearchy:: 2478 2479 testpmd> del port tm node (port_id) (node_id) 2480 2481Update port traffic management hierarchy parent node 2482~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2483 2484Update port traffic management hierarchy parent node:: 2485 2486 testpmd> set port tm node parent (port_id) (node_id) (parent_node_id) \ 2487 (priority) (weight) 2488 2489This function can only be called after the hierarchy commit invocation. Its 2490success depends on the port support for this operation, as advertised through 2491the port capability set. This function is valid for all nodes of the traffic 2492management hierarchy except root node. 2493 2494Commit port traffic management hierarchy 2495~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2496 2497Commit the traffic management hierarchy on the port:: 2498 2499 testpmd> port tm hierarchy commit (port_id) (clean_on_fail) 2500 2501where: 2502 2503* ``clean_on_fail``: When set to non-zero, hierarchy is cleared on function 2504 call failure. On the other hand, hierarchy is preserved when this parameter 2505 is equal to zero. 2506 2507Set port traffic management default hierarchy (tm forwarding mode) 2508~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2509 2510set the traffic management default hierarchy on the port:: 2511 2512 testpmd> set port tm hierarchy default (port_id) 2513 2514Filter Functions 2515---------------- 2516 2517This section details the available filter functions that are available. 2518 2519Note these functions interface the deprecated legacy filtering framework, 2520superseded by *rte_flow*. See `Flow rules management`_. 2521 2522ethertype_filter 2523~~~~~~~~~~~~~~~~~~~~ 2524 2525Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue:: 2526 2527 ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \ 2528 ethertype (ether_type) (drop|fwd) queue (queue_id) 2529 2530The available information parameters are: 2531 2532* ``port_id``: The port which the Ethertype filter assigned on. 2533 2534* ``mac_addr``: Compare destination mac address. 2535 2536* ``mac_ignr``: Ignore destination mac address match. 2537 2538* ``mac_address``: Destination mac address to match. 2539 2540* ``ether_type``: The EtherType value want to match, 2541 for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid. 2542 2543* ``queue_id``: The receive queue associated with this EtherType filter. 2544 It is meaningless when deleting or dropping. 2545 2546Example, to add/remove an ethertype filter rule:: 2547 2548 testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \ 2549 ethertype 0x0806 fwd queue 3 2550 2551 testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \ 2552 ethertype 0x0806 fwd queue 3 2553 25542tuple_filter 2555~~~~~~~~~~~~~~~~~ 2556 2557Add or delete a 2-tuple filter, 2558which identifies packets by specific protocol and destination TCP/UDP port 2559and forwards packets into one of the receive queues:: 2560 2561 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \ 2562 protocol (protocol_value) mask (mask_value) \ 2563 tcp_flags (tcp_flags_value) priority (prio_value) \ 2564 queue (queue_id) 2565 2566The available information parameters are: 2567 2568* ``port_id``: The port which the 2-tuple filter assigned on. 2569 2570* ``dst_port_value``: Destination port in L4. 2571 2572* ``protocol_value``: IP L4 protocol. 2573 2574* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate. 2575 2576* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP). 2577 2578* ``prio_value``: Priority of this filter. 2579 2580* ``queue_id``: The receive queue associated with this 2-tuple filter. 2581 2582Example, to add/remove an 2tuple filter rule:: 2583 2584 testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \ 2585 tcp_flags 0x02 priority 3 queue 3 2586 2587 testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \ 2588 tcp_flags 0x02 priority 3 queue 3 2589 25905tuple_filter 2591~~~~~~~~~~~~~~~~~ 2592 2593Add or delete a 5-tuple filter, 2594which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port) 2595and routes packets into one of the receive queues:: 2596 2597 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \ 2598 (src_address) dst_port (dst_port_value) \ 2599 src_port (src_port_value) protocol (protocol_value) \ 2600 mask (mask_value) tcp_flags (tcp_flags_value) \ 2601 priority (prio_value) queue (queue_id) 2602 2603The available information parameters are: 2604 2605* ``port_id``: The port which the 5-tuple filter assigned on. 2606 2607* ``dst_address``: Destination IP address. 2608 2609* ``src_address``: Source IP address. 2610 2611* ``dst_port_value``: TCP/UDP destination port. 2612 2613* ``src_port_value``: TCP/UDP source port. 2614 2615* ``protocol_value``: L4 protocol. 2616 2617* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate 2618 2619* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP). 2620 2621* ``prio_value``: The priority of this filter. 2622 2623* ``queue_id``: The receive queue associated with this 5-tuple filter. 2624 2625Example, to add/remove an 5tuple filter rule:: 2626 2627 testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2628 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2629 flags 0x0 priority 3 queue 3 2630 2631 testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2632 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2633 flags 0x0 priority 3 queue 3 2634 2635syn_filter 2636~~~~~~~~~~ 2637 2638Using the SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue:: 2639 2640 syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) 2641 2642The available information parameters are: 2643 2644* ``port_id``: The port which the SYN filter assigned on. 2645 2646* ``high``: This SYN filter has higher priority than other filters. 2647 2648* ``low``: This SYN filter has lower priority than other filters. 2649 2650* ``queue_id``: The receive queue associated with this SYN filter 2651 2652Example:: 2653 2654 testpmd> syn_filter 0 add priority high queue 3 2655 2656flex_filter 2657~~~~~~~~~~~ 2658 2659With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet 2660and routed into one of the receive queues:: 2661 2662 flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \ 2663 mask (mask_value) priority (prio_value) queue (queue_id) 2664 2665The available information parameters are: 2666 2667* ``port_id``: The port which the Flex filter is assigned on. 2668 2669* ``len_value``: Filter length in bytes, no greater than 128. 2670 2671* ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match. 2672 2673* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match. 2674 2675* ``prio_value``: The priority of this filter. 2676 2677* ``queue_id``: The receive queue associated with this Flex filter. 2678 2679Example:: 2680 2681 testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \ 2682 mask 000C priority 3 queue 3 2683 2684 testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \ 2685 mask 000C priority 3 queue 3 2686 2687 2688.. _testpmd_flow_director: 2689 2690flow_director_filter 2691~~~~~~~~~~~~~~~~~~~~ 2692 2693The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues. 2694 2695Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and 2696Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter: 2697 2698* Perfect match filters. 2699 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2700 The masked fields are for IP flow. 2701 2702* Signature filters. 2703 The hardware checks a match between a hash-based signature of the masked fields of the received packet. 2704 2705* Perfect-mac-vlan match filters. 2706 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2707 The masked fields are for MAC VLAN flow. 2708 2709* Perfect-tunnel match filters. 2710 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2711 The masked fields are for tunnel flow. 2712 2713* Perfect-raw-flow-type match filters. 2714 The hardware checks a match between the masked fields of the received packets and pre-loaded raw (template) packet. 2715 The masked fields are specified by input sets. 2716 2717The Flow Director filters can match the different fields for different type of packet: flow type, specific input set 2718per flow type and the flexible payload. 2719 2720The Flow Director can also mask out parts of all of these fields so that filters 2721are only applied to certain fields or parts of the fields. 2722 2723Note that for raw flow type mode the source and destination fields in the 2724raw packet buffer need to be presented in a reversed order with respect 2725to the expected received packets. 2726For example: IP source and destination addresses or TCP/UDP/SCTP 2727source and destination ports 2728 2729Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information. 2730 2731# Commands to add flow director filters of different flow types:: 2732 2733 flow_director_filter (port_id) mode IP (add|del|update) \ 2734 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ 2735 src (src_ip_address) dst (dst_ip_address) \ 2736 tos (tos_value) proto (proto_value) ttl (ttl_value) \ 2737 vlan (vlan_value) flexbytes (flexbytes_value) \ 2738 (drop|fwd) pf|vf(vf_id) queue (queue_id) \ 2739 fd_id (fd_id_value) 2740 2741 flow_director_filter (port_id) mode IP (add|del|update) \ 2742 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ 2743 src (src_ip_address) (src_port) \ 2744 dst (dst_ip_address) (dst_port) \ 2745 tos (tos_value) ttl (ttl_value) \ 2746 vlan (vlan_value) flexbytes (flexbytes_value) \ 2747 (drop|fwd) queue pf|vf(vf_id) (queue_id) \ 2748 fd_id (fd_id_value) 2749 2750 flow_director_filter (port_id) mode IP (add|del|update) \ 2751 flow (ipv4-sctp|ipv6-sctp) \ 2752 src (src_ip_address) (src_port) \ 2753 dst (dst_ip_address) (dst_port) \ 2754 tos (tos_value) ttl (ttl_value) \ 2755 tag (verification_tag) vlan (vlan_value) \ 2756 flexbytes (flexbytes_value) (drop|fwd) \ 2757 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) 2758 2759 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ 2760 ether (ethertype) flexbytes (flexbytes_value) \ 2761 (drop|fwd) pf|vf(vf_id) queue (queue_id) 2762 fd_id (fd_id_value) 2763 2764 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ 2765 mac (mac_address) vlan (vlan_value) \ 2766 flexbytes (flexbytes_value) (drop|fwd) \ 2767 queue (queue_id) fd_id (fd_id_value) 2768 2769 flow_director_filter (port_id) mode Tunnel (add|del|update) \ 2770 mac (mac_address) vlan (vlan_value) \ 2771 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ 2772 flexbytes (flexbytes_value) (drop|fwd) \ 2773 queue (queue_id) fd_id (fd_id_value) 2774 2775 flow_director_filter (port_id) mode raw (add|del|update) flow (flow_id) \ 2776 (drop|fwd) queue (queue_id) fd_id (fd_id_value) \ 2777 packet (packet file name) 2778 2779For example, to add an ipv4-udp flow type filter:: 2780 2781 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ 2782 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ 2783 fwd pf queue 1 fd_id 1 2784 2785For example, add an ipv4-other flow type filter:: 2786 2787 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ 2788 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ 2789 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 2790 2791flush_flow_director 2792~~~~~~~~~~~~~~~~~~~ 2793 2794Flush all flow director filters on a device:: 2795 2796 testpmd> flush_flow_director (port_id) 2797 2798Example, to flush all flow director filter on port 0:: 2799 2800 testpmd> flush_flow_director 0 2801 2802flow_director_mask 2803~~~~~~~~~~~~~~~~~~ 2804 2805Set flow director's input masks:: 2806 2807 flow_director_mask (port_id) mode IP vlan (vlan_value) \ 2808 src_mask (ipv4_src) (ipv6_src) (src_port) \ 2809 dst_mask (ipv4_dst) (ipv6_dst) (dst_port) 2810 2811 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) 2812 2813 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ 2814 mac (mac_value) tunnel-type (tunnel_type_value) \ 2815 tunnel-id (tunnel_id_value) 2816 2817Example, to set flow director mask on port 0:: 2818 2819 testpmd> flow_director_mask 0 mode IP vlan 0xefff \ 2820 src_mask 255.255.255.255 \ 2821 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ 2822 dst_mask 255.255.255.255 \ 2823 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF 2824 2825flow_director_flex_mask 2826~~~~~~~~~~~~~~~~~~~~~~~ 2827 2828set masks of flow director's flexible payload based on certain flow type:: 2829 2830 testpmd> flow_director_flex_mask (port_id) \ 2831 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2832 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ 2833 l2_payload|all) (mask) 2834 2835Example, to set flow director's flex mask for all flow type on port 0:: 2836 2837 testpmd> flow_director_flex_mask 0 flow all \ 2838 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 2839 2840 2841flow_director_flex_payload 2842~~~~~~~~~~~~~~~~~~~~~~~~~~ 2843 2844Configure flexible payload selection:: 2845 2846 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) 2847 2848For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload:: 2849 2850 testpmd> flow_director_flex_payload 0 l4 \ 2851 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) 2852 2853get_sym_hash_ena_per_port 2854~~~~~~~~~~~~~~~~~~~~~~~~~ 2855 2856Get symmetric hash enable configuration per port:: 2857 2858 get_sym_hash_ena_per_port (port_id) 2859 2860For example, to get symmetric hash enable configuration of port 1:: 2861 2862 testpmd> get_sym_hash_ena_per_port 1 2863 2864set_sym_hash_ena_per_port 2865~~~~~~~~~~~~~~~~~~~~~~~~~ 2866 2867Set symmetric hash enable configuration per port to enable or disable:: 2868 2869 set_sym_hash_ena_per_port (port_id) (enable|disable) 2870 2871For example, to set symmetric hash enable configuration of port 1 to enable:: 2872 2873 testpmd> set_sym_hash_ena_per_port 1 enable 2874 2875get_hash_global_config 2876~~~~~~~~~~~~~~~~~~~~~~ 2877 2878Get the global configurations of hash filters:: 2879 2880 get_hash_global_config (port_id) 2881 2882For example, to get the global configurations of hash filters of port 1:: 2883 2884 testpmd> get_hash_global_config 1 2885 2886set_hash_global_config 2887~~~~~~~~~~~~~~~~~~~~~~ 2888 2889Set the global configurations of hash filters:: 2890 2891 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ 2892 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \ 2893 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload|<flow_id>) \ 2894 (enable|disable) 2895 2896For example, to enable simple_xor for flow type of ipv6 on port 2:: 2897 2898 testpmd> set_hash_global_config 2 simple_xor ipv6 enable 2899 2900set_hash_input_set 2901~~~~~~~~~~~~~~~~~~ 2902 2903Set the input set for hash:: 2904 2905 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2906 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2907 l2_payload|<flow_id>) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6| \ 2908 ipv4-tos|ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ 2909 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ 2910 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ 2911 fld-8th|none) (select|add) 2912 2913For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: 2914 2915 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add 2916 2917set_fdir_input_set 2918~~~~~~~~~~~~~~~~~~ 2919 2920The Flow Director filters can match the different fields for different type of packet, i.e. specific input set 2921on per flow type and the flexible payload. This command can be used to change input set for each flow type. 2922 2923Set the input set for flow director:: 2924 2925 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2926 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2927 l2_payload|<flow_id>) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6| \ 2928 ipv4-tos|ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ 2929 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ 2930 sctp-dst-port|sctp-veri-tag|none) (select|add) 2931 2932For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: 2933 2934 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add 2935 2936global_config 2937~~~~~~~~~~~~~ 2938 2939Set different GRE key length for input set:: 2940 2941 global_config (port_id) gre-key-len (number in bytes) 2942 2943For example to set GRE key length for input set to 4 bytes on port 0:: 2944 2945 testpmd> global_config 0 gre-key-len 4 2946 2947 2948.. _testpmd_rte_flow: 2949 2950Flow rules management 2951--------------------- 2952 2953Control of the generic flow API (*rte_flow*) is fully exposed through the 2954``flow`` command (validation, creation, destruction, queries and operation 2955modes). 2956 2957Considering *rte_flow* overlaps with all `Filter Functions`_, using both 2958features simultaneously may cause undefined side-effects and is therefore 2959not recommended. 2960 2961``flow`` syntax 2962~~~~~~~~~~~~~~~ 2963 2964Because the ``flow`` command uses dynamic tokens to handle the large number 2965of possible flow rules combinations, its behavior differs slightly from 2966other commands, in particular: 2967 2968- Pressing *?* or the *<tab>* key displays contextual help for the current 2969 token, not that of the entire command. 2970 2971- Optional and repeated parameters are supported (provided they are listed 2972 in the contextual help). 2973 2974The first parameter stands for the operation mode. Possible operations and 2975their general syntax are described below. They are covered in detail in the 2976following sections. 2977 2978- Check whether a flow rule can be created:: 2979 2980 flow validate {port_id} 2981 [group {group_id}] [priority {level}] [ingress] [egress] 2982 pattern {item} [/ {item} [...]] / end 2983 actions {action} [/ {action} [...]] / end 2984 2985- Create a flow rule:: 2986 2987 flow create {port_id} 2988 [group {group_id}] [priority {level}] [ingress] [egress] 2989 pattern {item} [/ {item} [...]] / end 2990 actions {action} [/ {action} [...]] / end 2991 2992- Destroy specific flow rules:: 2993 2994 flow destroy {port_id} rule {rule_id} [...] 2995 2996- Destroy all flow rules:: 2997 2998 flow flush {port_id} 2999 3000- Query an existing flow rule:: 3001 3002 flow query {port_id} {rule_id} {action} 3003 3004- List existing flow rules sorted by priority, filtered by group 3005 identifiers:: 3006 3007 flow list {port_id} [group {group_id}] [...] 3008 3009- Restrict ingress traffic to the defined flow rules:: 3010 3011 flow isolate {port_id} {boolean} 3012 3013Validating flow rules 3014~~~~~~~~~~~~~~~~~~~~~ 3015 3016``flow validate`` reports whether a flow rule would be accepted by the 3017underlying device in its current state but stops short of creating it. It is 3018bound to ``rte_flow_validate()``:: 3019 3020 flow validate {port_id} 3021 [group {group_id}] [priority {level}] [ingress] [egress] 3022 pattern {item} [/ {item} [...]] / end 3023 actions {action} [/ {action} [...]] / end 3024 3025If successful, it will show:: 3026 3027 Flow rule validated 3028 3029Otherwise it will show an error message of the form:: 3030 3031 Caught error type [...] ([...]): [...] 3032 3033This command uses the same parameters as ``flow create``, their format is 3034described in `Creating flow rules`_. 3035 3036Check whether redirecting any Ethernet packet received on port 0 to RX queue 3037index 6 is supported:: 3038 3039 testpmd> flow validate 0 ingress pattern eth / end 3040 actions queue index 6 / end 3041 Flow rule validated 3042 testpmd> 3043 3044Port 0 does not support TCPv6 rules:: 3045 3046 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end 3047 actions drop / end 3048 Caught error type 9 (specific pattern item): Invalid argument 3049 testpmd> 3050 3051Creating flow rules 3052~~~~~~~~~~~~~~~~~~~ 3053 3054``flow create`` validates and creates the specified flow rule. It is bound 3055to ``rte_flow_create()``:: 3056 3057 flow create {port_id} 3058 [group {group_id}] [priority {level}] [ingress] [egress] 3059 pattern {item} [/ {item} [...]] / end 3060 actions {action} [/ {action} [...]] / end 3061 3062If successful, it will return a flow rule ID usable with other commands:: 3063 3064 Flow rule #[...] created 3065 3066Otherwise it will show an error message of the form:: 3067 3068 Caught error type [...] ([...]): [...] 3069 3070Parameters describe in the following order: 3071 3072- Attributes (*group*, *priority*, *ingress*, *egress* tokens). 3073- A matching pattern, starting with the *pattern* token and terminated by an 3074 *end* pattern item. 3075- Actions, starting with the *actions* token and terminated by an *end* 3076 action. 3077 3078These translate directly to *rte_flow* objects provided as-is to the 3079underlying functions. 3080 3081The shortest valid definition only comprises mandatory tokens:: 3082 3083 testpmd> flow create 0 pattern end actions end 3084 3085Note that PMDs may refuse rules that essentially do nothing such as this 3086one. 3087 3088**All unspecified object values are automatically initialized to 0.** 3089 3090Attributes 3091^^^^^^^^^^ 3092 3093These tokens affect flow rule attributes (``struct rte_flow_attr``) and are 3094specified before the ``pattern`` token. 3095 3096- ``group {group id}``: priority group. 3097- ``priority {level}``: priority level within group. 3098- ``ingress``: rule applies to ingress traffic. 3099- ``egress``: rule applies to egress traffic. 3100 3101Each instance of an attribute specified several times overrides the previous 3102value as shown below (group 4 is used):: 3103 3104 testpmd> flow create 0 group 42 group 24 group 4 [...] 3105 3106Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. 3107 3108While not specifying a direction is an error, some rules may allow both 3109simultaneously. 3110 3111Most rules affect RX therefore contain the ``ingress`` token:: 3112 3113 testpmd> flow create 0 ingress pattern [...] 3114 3115Matching pattern 3116^^^^^^^^^^^^^^^^ 3117 3118A matching pattern starts after the ``pattern`` token. It is made of pattern 3119items and is terminated by a mandatory ``end`` item. 3120 3121Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum 3122rte_flow_item_type``). 3123 3124The ``/`` token is used as a separator between pattern items as shown 3125below:: 3126 3127 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] 3128 3129Note that protocol items like these must be stacked from lowest to highest 3130layer to make sense. For instance, the following rule is either invalid or 3131unlikely to match any packet:: 3132 3133 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] 3134 3135More information on these restrictions can be found in the *rte_flow* 3136documentation. 3137 3138Several items support additional specification structures, for example 3139``ipv4`` allows specifying source and destination addresses as follows:: 3140 3141 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 3142 dst is 10.2.0.0 / end [...] 3143 3144This rule matches all IPv4 traffic with the specified properties. 3145 3146In this example, ``src`` and ``dst`` are field names of the underlying 3147``struct rte_flow_item_ipv4`` object. All item properties can be specified 3148in a similar fashion. 3149 3150The ``is`` token means that the subsequent value must be matched exactly, 3151and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` 3152accordingly. Possible assignment tokens are: 3153 3154- ``is``: match value perfectly (with full bit-mask). 3155- ``spec``: match value according to configured bit-mask. 3156- ``last``: specify upper bound to establish a range. 3157- ``mask``: specify bit-mask with relevant bits set to one. 3158- ``prefix``: generate bit-mask from a prefix length. 3159 3160These yield identical results:: 3161 3162 ipv4 src is 10.1.1.1 3163 3164:: 3165 3166 ipv4 src spec 10.1.1.1 src mask 255.255.255.255 3167 3168:: 3169 3170 ipv4 src spec 10.1.1.1 src prefix 32 3171 3172:: 3173 3174 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value 3175 3176:: 3177 3178 ipv4 src is 10.1.1.1 src last 0 # 0 disables range 3179 3180Inclusive ranges can be defined with ``last``:: 3181 3182 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 3183 3184Note that ``mask`` affects both ``spec`` and ``last``:: 3185 3186 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 3187 # matches 10.1.0.0 to 10.2.255.255 3188 3189Properties can be modified multiple times:: 3190 3191 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 3192 3193:: 3194 3195 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 3196 3197Pattern items 3198^^^^^^^^^^^^^ 3199 3200This section lists supported pattern items and their attributes, if any. 3201 3202- ``end``: end list of pattern items. 3203 3204- ``void``: no-op pattern item. 3205 3206- ``invert``: perform actions when pattern does not match. 3207 3208- ``any``: match any protocol for the current layer. 3209 3210 - ``num {unsigned}``: number of layers covered. 3211 3212- ``pf``: match packets addressed to the physical function. 3213 3214- ``vf``: match packets addressed to a virtual function ID. 3215 3216 - ``id {unsigned}``: destination VF ID. 3217 3218- ``port``: device-specific physical port index to use. 3219 3220 - ``index {unsigned}``: physical port index. 3221 3222- ``raw``: match an arbitrary byte string. 3223 3224 - ``relative {boolean}``: look for pattern after the previous item. 3225 - ``search {boolean}``: search pattern from offset (see also limit). 3226 - ``offset {integer}``: absolute or relative offset for pattern. 3227 - ``limit {unsigned}``: search area limit for start of pattern. 3228 - ``pattern {string}``: byte string to look for. 3229 3230- ``eth``: match Ethernet header. 3231 3232 - ``dst {MAC-48}``: destination MAC. 3233 - ``src {MAC-48}``: source MAC. 3234 - ``type {unsigned}``: EtherType. 3235 3236- ``vlan``: match 802.1Q/ad VLAN tag. 3237 3238 - ``tpid {unsigned}``: tag protocol identifier. 3239 - ``tci {unsigned}``: tag control information. 3240 - ``pcp {unsigned}``: priority code point. 3241 - ``dei {unsigned}``: drop eligible indicator. 3242 - ``vid {unsigned}``: VLAN identifier. 3243 3244- ``ipv4``: match IPv4 header. 3245 3246 - ``tos {unsigned}``: type of service. 3247 - ``ttl {unsigned}``: time to live. 3248 - ``proto {unsigned}``: next protocol ID. 3249 - ``src {ipv4 address}``: source address. 3250 - ``dst {ipv4 address}``: destination address. 3251 3252- ``ipv6``: match IPv6 header. 3253 3254 - ``tc {unsigned}``: traffic class. 3255 - ``flow {unsigned}``: flow label. 3256 - ``proto {unsigned}``: protocol (next header). 3257 - ``hop {unsigned}``: hop limit. 3258 - ``src {ipv6 address}``: source address. 3259 - ``dst {ipv6 address}``: destination address. 3260 3261- ``icmp``: match ICMP header. 3262 3263 - ``type {unsigned}``: ICMP packet type. 3264 - ``code {unsigned}``: ICMP packet code. 3265 3266- ``udp``: match UDP header. 3267 3268 - ``src {unsigned}``: UDP source port. 3269 - ``dst {unsigned}``: UDP destination port. 3270 3271- ``tcp``: match TCP header. 3272 3273 - ``src {unsigned}``: TCP source port. 3274 - ``dst {unsigned}``: TCP destination port. 3275 3276- ``sctp``: match SCTP header. 3277 3278 - ``src {unsigned}``: SCTP source port. 3279 - ``dst {unsigned}``: SCTP destination port. 3280 - ``tag {unsigned}``: validation tag. 3281 - ``cksum {unsigned}``: checksum. 3282 3283- ``vxlan``: match VXLAN header. 3284 3285 - ``vni {unsigned}``: VXLAN identifier. 3286 3287- ``e_tag``: match IEEE 802.1BR E-Tag header. 3288 3289 - ``grp_ecid_b {unsigned}``: GRP and E-CID base. 3290 3291- ``nvgre``: match NVGRE header. 3292 3293 - ``tni {unsigned}``: virtual subnet ID. 3294 3295- ``mpls``: match MPLS header. 3296 3297 - ``label {unsigned}``: MPLS label. 3298 3299- ``gre``: match GRE header. 3300 3301 - ``protocol {unsigned}``: protocol type. 3302 3303- ``fuzzy``: fuzzy pattern match, expect faster than default. 3304 3305 - ``thresh {unsigned}``: accuracy threshold. 3306 3307- ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header. 3308 3309 - ``teid {unsigned}``: tunnel endpoint identifier. 3310 3311- ``geneve``: match GENEVE header. 3312 3313 - ``vni {unsigned}``: virtual network identifier. 3314 - ``protocol {unsigned}``: protocol type. 3315 3316Actions list 3317^^^^^^^^^^^^ 3318 3319A list of actions starts after the ``actions`` token in the same fashion as 3320`Matching pattern`_; actions are separated by ``/`` tokens and the list is 3321terminated by a mandatory ``end`` action. 3322 3323Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum 3324rte_flow_action_type``). 3325 3326Dropping all incoming UDPv4 packets can be expressed as follows:: 3327 3328 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3329 actions drop / end 3330 3331Several actions have configurable properties which must be specified when 3332there is no valid default value. For example, ``queue`` requires a target 3333queue index. 3334 3335This rule redirects incoming UDPv4 traffic to queue index 6:: 3336 3337 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3338 actions queue index 6 / end 3339 3340While this one could be rejected by PMDs (unspecified queue index):: 3341 3342 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 3343 actions queue / end 3344 3345As defined by *rte_flow*, the list is not ordered, all actions of a given 3346rule are performed simultaneously. These are equivalent:: 3347 3348 queue index 6 / void / mark id 42 / end 3349 3350:: 3351 3352 void / mark id 42 / queue index 6 / end 3353 3354All actions in a list should have different types, otherwise only the last 3355action of a given type is taken into account:: 3356 3357 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 3358 3359:: 3360 3361 drop / drop / drop / end # drop is performed only once 3362 3363:: 3364 3365 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 3366 3367Considering they are performed simultaneously, opposite and overlapping 3368actions can sometimes be combined when the end result is unambiguous:: 3369 3370 drop / queue index 6 / end # drop has no effect 3371 3372:: 3373 3374 drop / dup index 6 / end # same as above 3375 3376:: 3377 3378 queue index 6 / rss queues 6 7 8 / end # queue has no effect 3379 3380:: 3381 3382 drop / passthru / end # drop has no effect 3383 3384Note that PMDs may still refuse such combinations. 3385 3386Actions 3387^^^^^^^ 3388 3389This section lists supported actions and their attributes, if any. 3390 3391- ``end``: end list of actions. 3392 3393- ``void``: no-op action. 3394 3395- ``passthru``: let subsequent rule process matched packets. 3396 3397- ``mark``: attach 32 bit value to packets. 3398 3399 - ``id {unsigned}``: 32 bit value to return with packets. 3400 3401- ``flag``: flag packets. 3402 3403- ``queue``: assign packets to a given queue index. 3404 3405 - ``index {unsigned}``: queue index to use. 3406 3407- ``drop``: drop packets (note: passthru has priority). 3408 3409- ``count``: enable counters for this rule. 3410 3411- ``dup``: duplicate packets to a given queue index. 3412 3413 - ``index {unsigned}``: queue index to duplicate packets to. 3414 3415- ``rss``: spread packets among several queues. 3416 3417 - ``queues [{unsigned} [...]] end``: queue indices to use. 3418 3419- ``pf``: redirect packets to physical device function. 3420 3421- ``vf``: redirect packets to virtual device function. 3422 3423 - ``original {boolean}``: use original VF ID if possible. 3424 - ``id {unsigned}``: VF ID to redirect packets to. 3425 3426Destroying flow rules 3427~~~~~~~~~~~~~~~~~~~~~ 3428 3429``flow destroy`` destroys one or more rules from their rule ID (as returned 3430by ``flow create``), this command calls ``rte_flow_destroy()`` as many 3431times as necessary:: 3432 3433 flow destroy {port_id} rule {rule_id} [...] 3434 3435If successful, it will show:: 3436 3437 Flow rule #[...] destroyed 3438 3439It does not report anything for rule IDs that do not exist. The usual error 3440message is shown when a rule cannot be destroyed:: 3441 3442 Caught error type [...] ([...]): [...] 3443 3444``flow flush`` destroys all rules on a device and does not take extra 3445arguments. It is bound to ``rte_flow_flush()``:: 3446 3447 flow flush {port_id} 3448 3449Any errors are reported as above. 3450 3451Creating several rules and destroying them:: 3452 3453 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3454 actions queue index 2 / end 3455 Flow rule #0 created 3456 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3457 actions queue index 3 / end 3458 Flow rule #1 created 3459 testpmd> flow destroy 0 rule 0 rule 1 3460 Flow rule #1 destroyed 3461 Flow rule #0 destroyed 3462 testpmd> 3463 3464The same result can be achieved using ``flow flush``:: 3465 3466 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3467 actions queue index 2 / end 3468 Flow rule #0 created 3469 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3470 actions queue index 3 / end 3471 Flow rule #1 created 3472 testpmd> flow flush 0 3473 testpmd> 3474 3475Non-existent rule IDs are ignored:: 3476 3477 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3478 actions queue index 2 / end 3479 Flow rule #0 created 3480 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3481 actions queue index 3 / end 3482 Flow rule #1 created 3483 testpmd> flow destroy 0 rule 42 rule 10 rule 2 3484 testpmd> 3485 testpmd> flow destroy 0 rule 0 3486 Flow rule #0 destroyed 3487 testpmd> 3488 3489Querying flow rules 3490~~~~~~~~~~~~~~~~~~~ 3491 3492``flow query`` queries a specific action of a flow rule having that 3493ability. Such actions collect information that can be reported using this 3494command. It is bound to ``rte_flow_query()``:: 3495 3496 flow query {port_id} {rule_id} {action} 3497 3498If successful, it will display either the retrieved data for known actions 3499or the following message:: 3500 3501 Cannot display result for action type [...] ([...]) 3502 3503Otherwise, it will complain either that the rule does not exist or that some 3504error occurred:: 3505 3506 Flow rule #[...] not found 3507 3508:: 3509 3510 Caught error type [...] ([...]): [...] 3511 3512Currently only the ``count`` action is supported. This action reports the 3513number of packets that hit the flow rule and the total number of bytes. Its 3514output has the following format:: 3515 3516 count: 3517 hits_set: [...] # whether "hits" contains a valid value 3518 bytes_set: [...] # whether "bytes" contains a valid value 3519 hits: [...] # number of packets 3520 bytes: [...] # number of bytes 3521 3522Querying counters for TCPv6 packets redirected to queue 6:: 3523 3524 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end 3525 actions queue index 6 / count / end 3526 Flow rule #4 created 3527 testpmd> flow query 0 4 count 3528 count: 3529 hits_set: 1 3530 bytes_set: 0 3531 hits: 386446 3532 bytes: 0 3533 testpmd> 3534 3535Listing flow rules 3536~~~~~~~~~~~~~~~~~~ 3537 3538``flow list`` lists existing flow rules sorted by priority and optionally 3539filtered by group identifiers:: 3540 3541 flow list {port_id} [group {group_id}] [...] 3542 3543This command only fails with the following message if the device does not 3544exist:: 3545 3546 Invalid port [...] 3547 3548Output consists of a header line followed by a short description of each 3549flow rule, one per line. There is no output at all when no flow rules are 3550configured on the device:: 3551 3552 ID Group Prio Attr Rule 3553 [...] [...] [...] [...] [...] 3554 3555``Attr`` column flags: 3556 3557- ``i`` for ``ingress``. 3558- ``e`` for ``egress``. 3559 3560Creating several flow rules and listing them:: 3561 3562 testpmd> flow create 0 ingress pattern eth / ipv4 / end 3563 actions queue index 6 / end 3564 Flow rule #0 created 3565 testpmd> flow create 0 ingress pattern eth / ipv6 / end 3566 actions queue index 2 / end 3567 Flow rule #1 created 3568 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end 3569 actions rss queues 6 7 8 end / end 3570 Flow rule #2 created 3571 testpmd> flow list 0 3572 ID Group Prio Attr Rule 3573 0 0 0 i- ETH IPV4 => QUEUE 3574 1 0 0 i- ETH IPV6 => QUEUE 3575 2 0 5 i- ETH IPV4 UDP => RSS 3576 testpmd> 3577 3578Rules are sorted by priority (i.e. group ID first, then priority level):: 3579 3580 testpmd> flow list 1 3581 ID Group Prio Attr Rule 3582 0 0 0 i- ETH => COUNT 3583 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3584 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3585 1 24 0 i- ETH IPV4 UDP => QUEUE 3586 4 24 10 i- ETH IPV4 TCP => DROP 3587 3 24 20 i- ETH IPV4 => DROP 3588 2 24 42 i- ETH IPV4 UDP => QUEUE 3589 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3590 testpmd> 3591 3592Output can be limited to specific groups:: 3593 3594 testpmd> flow list 1 group 0 group 63 3595 ID Group Prio Attr Rule 3596 0 0 0 i- ETH => COUNT 3597 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3598 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3599 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3600 testpmd> 3601 3602Toggling isolated mode 3603~~~~~~~~~~~~~~~~~~~~~~ 3604 3605``flow isolate`` can be used to tell the underlying PMD that ingress traffic 3606must only be injected from the defined flow rules; that no default traffic 3607is expected outside those rules and the driver is free to assign more 3608resources to handle them. It is bound to ``rte_flow_isolate()``:: 3609 3610 flow isolate {port_id} {boolean} 3611 3612If successful, enabling or disabling isolated mode shows either:: 3613 3614 Ingress traffic on port [...] 3615 is now restricted to the defined flow rules 3616 3617Or:: 3618 3619 Ingress traffic on port [...] 3620 is not restricted anymore to the defined flow rules 3621 3622Otherwise, in case of error:: 3623 3624 Caught error type [...] ([...]): [...] 3625 3626Mainly due to its side effects, PMDs supporting this mode may not have the 3627ability to toggle it more than once without reinitializing affected ports 3628first (e.g. by exiting testpmd). 3629 3630Enabling isolated mode:: 3631 3632 testpmd> flow isolate 0 true 3633 Ingress traffic on port 0 is now restricted to the defined flow rules 3634 testpmd> 3635 3636Disabling isolated mode:: 3637 3638 testpmd> flow isolate 0 false 3639 Ingress traffic on port 0 is not restricted anymore to the defined flow rules 3640 testpmd> 3641 3642Sample QinQ flow rules 3643~~~~~~~~~~~~~~~~~~~~~~ 3644 3645Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: 3646 3647 testpmd> port stop 0 3648 testpmd> vlan set qinq on 0 3649 3650The above command sets the inner and outer TPID's to 0x8100. 3651 3652To change the TPID's the following commands should be used:: 3653 3654 testpmd> vlan set outer tpid 0xa100 0 3655 testpmd> vlan set inner tpid 0x9100 0 3656 testpmd> port start 0 3657 3658Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. 3659 3660:: 3661 3662 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / 3663 vlan tci is 456 / end actions vf id 1 / queue index 0 / end 3664 Flow rule #0 validated 3665 3666 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / 3667 vlan tci is 456 / end actions vf id 123 / queue index 0 / end 3668 Flow rule #0 created 3669 3670 testpmd> flow list 0 3671 ID Group Prio Attr Rule 3672 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3673 3674Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. 3675 3676:: 3677 3678 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / 3679 vlan tci is 654 / end actions pf / queue index 0 / end 3680 Flow rule #1 validated 3681 3682 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / 3683 vlan tci is 654 / end actions pf / queue index 1 / end 3684 Flow rule #1 created 3685 3686 testpmd> flow list 0 3687 ID Group Prio Attr Rule 3688 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3689 1 0 0 i- ETH VLAN VLAN=>PF QUEUE 3690