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 350Note: TX timestamping is only available in the "Full Featured" TX path. To force ``testpmd`` into this mode set ``--txqflags=0``. 351 352Example:: 353 354 testpmd> set fwd rxonly 355 356 Set rxonly packet forwarding mode 357 358 359read rxd 360~~~~~~~~ 361 362Display an RX descriptor for a port RX queue:: 363 364 testpmd> read rxd (port_id) (queue_id) (rxd_id) 365 366For example:: 367 368 testpmd> read rxd 0 0 4 369 0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180 370 371read txd 372~~~~~~~~ 373 374Display a TX descriptor for a port TX queue:: 375 376 testpmd> read txd (port_id) (queue_id) (txd_id) 377 378For example:: 379 380 testpmd> read txd 0 0 4 381 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C 382 383ddp get list 384~~~~~~~~~~~~ 385 386Get loaded dynamic device personalization (DDP) package info list:: 387 388 testpmd> ddp get list (port_id) 389 390ddp get info 391~~~~~~~~~~~~ 392 393Display information about dynamic device personalization (DDP) profile:: 394 395 testpmd> ddp get info (profile_path) 396 397show vf stats 398~~~~~~~~~~~~~ 399 400Display VF statistics:: 401 402 testpmd> show vf stats (port_id) (vf_id) 403 404clear vf stats 405~~~~~~~~~~~~~~ 406 407Reset VF statistics:: 408 409 testpmd> clear vf stats (port_id) (vf_id) 410 411show port pctype mapping 412~~~~~~~~~~~~~~~~~~~~~~~~ 413 414List all items from the pctype mapping table:: 415 416 testpmd> show port (port_id) pctype mapping 417 418 419Configuration Functions 420----------------------- 421 422The testpmd application can be configured from the runtime as well as from the command-line. 423 424This section details the available configuration functions that are available. 425 426.. note:: 427 428 Configuration changes only become active when forwarding is started/restarted. 429 430set default 431~~~~~~~~~~~ 432 433Reset forwarding to the default configuration:: 434 435 testpmd> set default 436 437set verbose 438~~~~~~~~~~~ 439 440Set the debug verbosity level:: 441 442 testpmd> set verbose (level) 443 444Currently the only available levels are 0 (silent except for error) and 1 (fully verbose). 445 446set nbport 447~~~~~~~~~~ 448 449Set the number of ports used by the application: 450 451set nbport (num) 452 453This is equivalent to the ``--nb-ports`` command-line option. 454 455set nbcore 456~~~~~~~~~~ 457 458Set the number of cores used by the application:: 459 460 testpmd> set nbcore (num) 461 462This is equivalent to the ``--nb-cores`` command-line option. 463 464.. note:: 465 466 The number of cores used must not be greater than number of ports used multiplied by the number of queues per port. 467 468set coremask 469~~~~~~~~~~~~ 470 471Set the forwarding cores hexadecimal mask:: 472 473 testpmd> set coremask (mask) 474 475This is equivalent to the ``--coremask`` command-line option. 476 477.. note:: 478 479 The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding. 480 481set portmask 482~~~~~~~~~~~~ 483 484Set the forwarding ports hexadecimal mask:: 485 486 testpmd> set portmask (mask) 487 488This is equivalent to the ``--portmask`` command-line option. 489 490set burst 491~~~~~~~~~ 492 493Set number of packets per burst:: 494 495 testpmd> set burst (num) 496 497This is equivalent to the ``--burst command-line`` option. 498 499When retry is enabled, the transmit delay time and number of retries can also be set:: 500 501 testpmd> set burst tx delay (microseconds) retry (num) 502 503set txpkts 504~~~~~~~~~~ 505 506Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode:: 507 508 testpmd> set txpkts (x[,y]*) 509 510Where x[,y]* represents a CSV list of values, without white space. 511 512set txsplit 513~~~~~~~~~~~ 514 515Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes:: 516 517 testpmd> set txsplit (off|on|rand) 518 519Where: 520 521* ``off`` disable packet copy & split for CSUM mode. 522 523* ``on`` split outgoing packet into multiple segments. Size of each segment 524 and number of segments per packet is determined by ``set txpkts`` command 525 (see above). 526 527* ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments. 528 529set corelist 530~~~~~~~~~~~~ 531 532Set the list of forwarding cores:: 533 534 testpmd> set corelist (x[,y]*) 535 536For example, to change the forwarding cores: 537 538.. code-block:: console 539 540 testpmd> set corelist 3,1 541 testpmd> show config fwd 542 543 io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled 544 Logical Core 3 (socket 0) forwards packets on 1 streams: 545 RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01 546 Logical Core 1 (socket 0) forwards packets on 1 streams: 547 RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00 548 549.. note:: 550 551 The cores are used in the same order as specified on the command line. 552 553set portlist 554~~~~~~~~~~~~ 555 556Set the list of forwarding ports:: 557 558 testpmd> set portlist (x[,y]*) 559 560For example, to change the port forwarding: 561 562.. code-block:: console 563 564 testpmd> set portlist 0,2,1,3 565 testpmd> show config fwd 566 567 io packet forwarding - ports=4 - cores=1 - streams=4 568 Logical Core 3 (socket 0) forwards packets on 4 streams: 569 RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01 570 RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00 571 RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03 572 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02 573 574set tx loopback 575~~~~~~~~~~~~~~~ 576 577Enable/disable tx loopback:: 578 579 testpmd> set tx loopback (port_id) (on|off) 580 581set drop enable 582~~~~~~~~~~~~~~~ 583 584set drop enable bit for all queues:: 585 586 testpmd> set all queues drop (port_id) (on|off) 587 588set split drop enable (for VF) 589~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 590 591set split drop enable bit for VF from PF:: 592 593 testpmd> set vf split drop (port_id) (vf_id) (on|off) 594 595set mac antispoof (for VF) 596~~~~~~~~~~~~~~~~~~~~~~~~~~ 597 598Set mac antispoof for a VF from the PF:: 599 600 testpmd> set vf mac antispoof (port_id) (vf_id) (on|off) 601 602set macsec offload 603~~~~~~~~~~~~~~~~~~ 604 605Enable/disable MACsec offload:: 606 607 testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off) 608 testpmd> set macsec offload (port_id) off 609 610set macsec sc 611~~~~~~~~~~~~~ 612 613Configure MACsec secure connection (SC):: 614 615 testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi) 616 617.. note:: 618 619 The pi argument is ignored for tx. 620 Check the NIC Datasheet for hardware limits. 621 622set macsec sa 623~~~~~~~~~~~~~ 624 625Configure MACsec secure association (SA):: 626 627 testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key) 628 629.. note:: 630 631 The IDX value must be 0 or 1. 632 Check the NIC Datasheet for hardware limits. 633 634set broadcast mode (for VF) 635~~~~~~~~~~~~~~~~~~~~~~~~~~~ 636 637Set broadcast mode for a VF from the PF:: 638 639 testpmd> set vf broadcast (port_id) (vf_id) (on|off) 640 641vlan set strip 642~~~~~~~~~~~~~~ 643 644Set the VLAN strip on a port:: 645 646 testpmd> vlan set strip (on|off) (port_id) 647 648vlan set stripq 649~~~~~~~~~~~~~~~ 650 651Set the VLAN strip for a queue on a port:: 652 653 testpmd> vlan set stripq (on|off) (port_id,queue_id) 654 655vlan set stripq (for VF) 656~~~~~~~~~~~~~~~~~~~~~~~~ 657 658Set VLAN strip for all queues in a pool for a VF from the PF:: 659 660 testpmd> set vf vlan stripq (port_id) (vf_id) (on|off) 661 662vlan set insert (for VF) 663~~~~~~~~~~~~~~~~~~~~~~~~ 664 665Set VLAN insert for a VF from the PF:: 666 667 testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id) 668 669vlan set tag (for VF) 670~~~~~~~~~~~~~~~~~~~~~ 671 672Set VLAN tag for a VF from the PF:: 673 674 testpmd> set vf vlan tag (port_id) (vf_id) (on|off) 675 676vlan set antispoof (for VF) 677~~~~~~~~~~~~~~~~~~~~~~~~~~~ 678 679Set VLAN antispoof for a VF from the PF:: 680 681 testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off) 682 683vlan set filter 684~~~~~~~~~~~~~~~ 685 686Set the VLAN filter on a port:: 687 688 testpmd> vlan set filter (on|off) (port_id) 689 690vlan set qinq 691~~~~~~~~~~~~~ 692 693Set the VLAN QinQ (extended queue in queue) on for a port:: 694 695 testpmd> vlan set qinq (on|off) (port_id) 696 697vlan set tpid 698~~~~~~~~~~~~~ 699 700Set the inner or outer VLAN TPID for packet filtering on a port:: 701 702 testpmd> vlan set (inner|outer) tpid (value) (port_id) 703 704.. note:: 705 706 TPID value must be a 16-bit number (value <= 65536). 707 708rx_vlan add 709~~~~~~~~~~~ 710 711Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID:: 712 713 testpmd> rx_vlan add (vlan_id|all) (port_id) 714 715.. note:: 716 717 VLAN filter must be set on that port. VLAN ID < 4096. 718 Depending on the NIC used, number of vlan_ids may be limited to the maximum entries 719 in VFTA table. This is important if enabling all vlan_ids. 720 721rx_vlan rm 722~~~~~~~~~~ 723 724Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID:: 725 726 testpmd> rx_vlan rm (vlan_id|all) (port_id) 727 728rx_vlan add (for VF) 729~~~~~~~~~~~~~~~~~~~~ 730 731Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID:: 732 733 testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask) 734 735rx_vlan rm (for VF) 736~~~~~~~~~~~~~~~~~~~ 737 738Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID:: 739 740 testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask) 741 742tunnel_filter add 743~~~~~~~~~~~~~~~~~ 744 745Add a tunnel filter on a port:: 746 747 testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \ 748 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ 749 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) 750 751The available information categories are: 752 753* ``vxlan``: Set tunnel type as VXLAN. 754 755* ``nvgre``: Set tunnel type as NVGRE. 756 757* ``ipingre``: Set tunnel type as IP-in-GRE. 758 759* ``imac-ivlan``: Set filter type as Inner MAC and VLAN. 760 761* ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID. 762 763* ``imac-tenid``: Set filter type as Inner MAC and tenant ID. 764 765* ``imac``: Set filter type as Inner MAC. 766 767* ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID. 768 769* ``oip``: Set filter type as Outer IP. 770 771* ``iip``: Set filter type as Inner IP. 772 773Example:: 774 775 testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \ 776 192.168.2.2 0 ipingre oip 1 1 777 778 Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP. 779 780tunnel_filter remove 781~~~~~~~~~~~~~~~~~~~~ 782 783Remove a tunnel filter on a port:: 784 785 testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \ 786 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ 787 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) 788 789rx_vxlan_port add 790~~~~~~~~~~~~~~~~~ 791 792Add an UDP port for VXLAN packet filter on a port:: 793 794 testpmd> rx_vxlan_port add (udp_port) (port_id) 795 796rx_vxlan_port remove 797~~~~~~~~~~~~~~~~~~~~ 798 799Remove an UDP port for VXLAN packet filter on a port:: 800 801 testpmd> rx_vxlan_port rm (udp_port) (port_id) 802 803tx_vlan set 804~~~~~~~~~~~ 805 806Set hardware insertion of VLAN IDs in packets sent on a port:: 807 808 testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer] 809 810For example, set a single VLAN ID (5) insertion on port 0:: 811 812 tx_vlan set 0 5 813 814Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1:: 815 816 tx_vlan set 1 2 3 817 818 819tx_vlan set pvid 820~~~~~~~~~~~~~~~~ 821 822Set port based hardware insertion of VLAN ID in packets sent on a port:: 823 824 testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off) 825 826tx_vlan reset 827~~~~~~~~~~~~~ 828 829Disable hardware insertion of a VLAN header in packets sent on a port:: 830 831 testpmd> tx_vlan reset (port_id) 832 833csum set 834~~~~~~~~ 835 836Select hardware or software calculation of the checksum when 837transmitting a packet using the ``csum`` forwarding engine:: 838 839 testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id) 840 841Where: 842 843* ``ip|udp|tcp|sctp`` always relate to the inner layer. 844 845* ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized 846 as a tunnel packet by the forwarding engine (vxlan, gre and ipip are 847 supported). See also the ``csum parse-tunnel`` command. 848 849.. note:: 850 851 Check the NIC Datasheet for hardware limits. 852 853csum parse-tunnel 854~~~~~~~~~~~~~~~~~ 855 856Define how tunneled packets should be handled by the csum forward 857engine:: 858 859 testpmd> csum parse-tunnel (on|off) (tx_port_id) 860 861If enabled, the csum forward engine will try to recognize supported 862tunnel headers (vxlan, gre, ipip). 863 864If disabled, treat tunnel packets as non-tunneled packets (a inner 865header is handled as a packet payload). 866 867.. note:: 868 869 The port argument is the TX port like in the ``csum set`` command. 870 871Example: 872 873Consider a packet in packet like the following:: 874 875 eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in 876 877* If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set`` 878 command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the 879 ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``). 880 881* If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set`` 882 command relate to the outer headers, here ``ipv4_out`` and ``udp_out``. 883 884csum show 885~~~~~~~~~ 886 887Display tx checksum offload configuration:: 888 889 testpmd> csum show (port_id) 890 891tso set 892~~~~~~~ 893 894Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine:: 895 896 testpmd> tso set (segsize) (port_id) 897 898.. note:: 899 900 Check the NIC datasheet for hardware limits. 901 902tso show 903~~~~~~~~ 904 905Display the status of TCP Segmentation Offload:: 906 907 testpmd> tso show (port_id) 908 909gro 910~~~ 911 912Enable or disable GRO in ``csum`` forwarding engine:: 913 914 testpmd> gro (on|off) (port_id) 915 916If enabled, the csum forwarding engine will perform GRO on the TCP/IPv4 917packets received from the given port. 918 919If disabled, packets received from the given port won't be performed 920GRO. By default, GRO is disabled for all ports. 921 922.. note:: 923 924 When enable GRO for a port, TCP/IPv4 packets received from the port 925 will be performed GRO. After GRO, the merged packets are multi-segments. 926 But csum forwarding engine doesn't support to calculate TCP checksum 927 for multi-segment packets in SW. So please select TCP HW checksum 928 calculation for the port which GROed packets are transmitted to. 929 930gro set 931~~~~~~~ 932 933Set max flow number and max packet number per-flow for GRO:: 934 935 testpmd> gro set (max_flow_num) (max_item_num_per_flow) (port_id) 936 937The product of ``max_flow_num`` and ``max_item_num_per_flow`` is the max 938number of packets a GRO table can store. 939 940If current packet number is greater than or equal to the max value, GRO 941will stop processing incoming packets. 942 943mac_addr add 944~~~~~~~~~~~~ 945 946Add an alternative MAC address to a port:: 947 948 testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX) 949 950mac_addr remove 951~~~~~~~~~~~~~~~ 952 953Remove a MAC address from a port:: 954 955 testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) 956 957mac_addr add (for VF) 958~~~~~~~~~~~~~~~~~~~~~ 959 960Add an alternative MAC address for a VF to a port:: 961 962 testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) 963 964mac_addr set 965~~~~~~~~~~~~ 966 967Set the default MAC address for a port:: 968 969 testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX) 970 971mac_addr set (for VF) 972~~~~~~~~~~~~~~~~~~~~~ 973 974Set the MAC address for a VF from the PF:: 975 976 testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX) 977 978set port-uta 979~~~~~~~~~~~~ 980 981Set the unicast hash filter(s) on/off for a port:: 982 983 testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off) 984 985set promisc 986~~~~~~~~~~~ 987 988Set the promiscuous mode on for a port or for all ports. 989In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 990 991 testpmd> set promisc (port_id|all) (on|off) 992 993set allmulti 994~~~~~~~~~~~~ 995 996Set the allmulti mode for a port or for all ports:: 997 998 testpmd> set allmulti (port_id|all) (on|off) 999 1000Same as the ifconfig (8) option. Controls how multicast packets are handled. 1001 1002set promisc (for VF) 1003~~~~~~~~~~~~~~~~~~~~ 1004 1005Set the unicast promiscuous mode for a VF from PF. 1006It's supported by Intel i40e NICs now. 1007In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1008 1009 testpmd> set vf promisc (port_id) (vf_id) (on|off) 1010 1011set allmulticast (for VF) 1012~~~~~~~~~~~~~~~~~~~~~~~~~ 1013 1014Set the multicast promiscuous mode for a VF from PF. 1015It's supported by Intel i40e NICs now. 1016In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: 1017 1018 testpmd> set vf allmulti (port_id) (vf_id) (on|off) 1019 1020set tx max bandwidth (for VF) 1021~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1022 1023Set TX max absolute bandwidth (Mbps) for a VF from PF:: 1024 1025 testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth) 1026 1027set tc tx min bandwidth (for VF) 1028~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1029 1030Set all TCs' TX min relative bandwidth (%) for a VF from PF:: 1031 1032 testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...) 1033 1034set tc tx max bandwidth (for VF) 1035~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1036 1037Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF:: 1038 1039 testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth) 1040 1041set tc strict link priority mode 1042~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1043 1044Set some TCs' strict link priority mode on a physical port:: 1045 1046 testpmd> set tx strict-link-priority (port_id) (tc_bitmap) 1047 1048set tc tx min bandwidth 1049~~~~~~~~~~~~~~~~~~~~~~~ 1050 1051Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs:: 1052 1053 testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...) 1054 1055set flow_ctrl rx 1056~~~~~~~~~~~~~~~~ 1057 1058Set the link flow control parameter on a port:: 1059 1060 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1061 (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \ 1062 autoneg (on|off) (port_id) 1063 1064Where: 1065 1066* ``high_water`` (integer): High threshold value to trigger XOFF. 1067 1068* ``low_water`` (integer): Low threshold value to trigger XON. 1069 1070* ``pause_time`` (integer): Pause quota in the Pause frame. 1071 1072* ``send_xon`` (0/1): Send XON frame. 1073 1074* ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames. 1075 1076* ``autoneg``: Change the auto-negotiation parameter. 1077 1078set pfc_ctrl rx 1079~~~~~~~~~~~~~~~ 1080 1081Set the priority flow control parameter on a port:: 1082 1083 testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \ 1084 (pause_time) (priority) (port_id) 1085 1086Where: 1087 1088* ``high_water`` (integer): High threshold value. 1089 1090* ``low_water`` (integer): Low threshold value. 1091 1092* ``pause_time`` (integer): Pause quota in the Pause frame. 1093 1094* ``priority`` (0-7): VLAN User Priority. 1095 1096set stat_qmap 1097~~~~~~~~~~~~~ 1098 1099Set statistics mapping (qmapping 0..15) for RX/TX queue on port:: 1100 1101 testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping) 1102 1103For example, to set rx queue 2 on port 0 to mapping 5:: 1104 1105 testpmd>set stat_qmap rx 0 2 5 1106 1107set port - rx/tx (for VF) 1108~~~~~~~~~~~~~~~~~~~~~~~~~ 1109 1110Set VF receive/transmit from a port:: 1111 1112 testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off) 1113 1114set port - mac address filter (for VF) 1115~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1116 1117Add/Remove unicast or multicast MAC addr filter for a VF:: 1118 1119 testpmd> set port (port_id) vf (vf_id) (mac_addr) \ 1120 (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off) 1121 1122set port - rx mode(for VF) 1123~~~~~~~~~~~~~~~~~~~~~~~~~~ 1124 1125Set the VF receive mode of a port:: 1126 1127 testpmd> set port (port_id) vf (vf_id) \ 1128 rxmode (AUPE|ROPE|BAM|MPE) (on|off) 1129 1130The available receive modes are: 1131 1132* ``AUPE``: Accepts untagged VLAN. 1133 1134* ``ROPE``: Accepts unicast hash. 1135 1136* ``BAM``: Accepts broadcast packets. 1137 1138* ``MPE``: Accepts all multicast packets. 1139 1140set port - tx_rate (for Queue) 1141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1142 1143Set TX rate limitation for a queue on a port:: 1144 1145 testpmd> set port (port_id) queue (queue_id) rate (rate_value) 1146 1147set port - tx_rate (for VF) 1148~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1149 1150Set TX rate limitation for queues in VF on a port:: 1151 1152 testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask) 1153 1154set port - mirror rule 1155~~~~~~~~~~~~~~~~~~~~~~ 1156 1157Set pool or vlan type mirror rule for a port:: 1158 1159 testpmd> set port (port_id) mirror-rule (rule_id) \ 1160 (pool-mirror-up|pool-mirror-down|vlan-mirror) \ 1161 (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) 1162 1163Set link mirror rule for a port:: 1164 1165 testpmd> set port (port_id) mirror-rule (rule_id) \ 1166 (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off) 1167 1168For example to enable mirror traffic with vlan 0,1 to pool 0:: 1169 1170 set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on 1171 1172reset port - mirror rule 1173~~~~~~~~~~~~~~~~~~~~~~~~ 1174 1175Reset a mirror rule for a port:: 1176 1177 testpmd> reset port (port_id) mirror-rule (rule_id) 1178 1179set flush_rx 1180~~~~~~~~~~~~ 1181 1182Set the flush on RX streams before forwarding. 1183The default is flush ``on``. 1184Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams:: 1185 1186 testpmd> set flush_rx off 1187 1188set bypass mode 1189~~~~~~~~~~~~~~~ 1190 1191Set the bypass mode for the lowest port on bypass enabled NIC:: 1192 1193 testpmd> set bypass mode (normal|bypass|isolate) (port_id) 1194 1195set bypass event 1196~~~~~~~~~~~~~~~~ 1197 1198Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled:: 1199 1200 testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \ 1201 mode (normal|bypass|isolate) (port_id) 1202 1203Where: 1204 1205* ``timeout``: Enable bypass after watchdog timeout. 1206 1207* ``os_on``: Enable bypass when OS/board is powered on. 1208 1209* ``os_off``: Enable bypass when OS/board is powered off. 1210 1211* ``power_on``: Enable bypass when power supply is turned on. 1212 1213* ``power_off``: Enable bypass when power supply is turned off. 1214 1215 1216set bypass timeout 1217~~~~~~~~~~~~~~~~~~ 1218 1219Set the bypass watchdog timeout to ``n`` seconds where 0 = instant:: 1220 1221 testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32) 1222 1223show bypass config 1224~~~~~~~~~~~~~~~~~~ 1225 1226Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC:: 1227 1228 testpmd> show bypass config (port_id) 1229 1230set link up 1231~~~~~~~~~~~ 1232 1233Set link up for a port:: 1234 1235 testpmd> set link-up port (port id) 1236 1237set link down 1238~~~~~~~~~~~~~ 1239 1240Set link down for a port:: 1241 1242 testpmd> set link-down port (port id) 1243 1244E-tag set 1245~~~~~~~~~ 1246 1247Enable E-tag insertion for a VF on a port:: 1248 1249 testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id) 1250 1251Disable E-tag insertion for a VF on a port:: 1252 1253 testpmd> E-tag set insertion off port (port_id) vf (vf_id) 1254 1255Enable/disable E-tag stripping on a port:: 1256 1257 testpmd> E-tag set stripping (on|off) port (port_id) 1258 1259Enable/disable E-tag based forwarding on a port:: 1260 1261 testpmd> E-tag set forwarding (on|off) port (port_id) 1262 1263Add an E-tag forwarding filter on a port:: 1264 1265 testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id) 1266 1267Delete an E-tag forwarding filter on a port:: 1268 testpmd> E-tag set filter del e-tag-id (value) port (port_id) 1269 1270ddp add 1271~~~~~~~ 1272 1273Load a dynamic device personalization (DDP) package:: 1274 1275 testpmd> ddp add (port_id) (package_path[,output_path]) 1276 1277ddp del 1278~~~~~~~ 1279 1280Delete a dynamic device personalization package:: 1281 1282 testpmd> ddp del (port_id) (package_path) 1283 1284ptype mapping 1285~~~~~~~~~~~~~ 1286 1287List all items from the ptype mapping table:: 1288 1289 testpmd> ptype mapping get (port_id) (valid_only) 1290 1291Where: 1292 1293* ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0). 1294 1295Replace a specific or a group of software defined ptype with a new one:: 1296 1297 testpmd> ptype mapping replace (port_id) (target) (mask) (pkt_type) 1298 1299where: 1300 1301* ``target``: A specific software ptype or a mask to represent a group of software ptypes. 1302 1303* ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1). 1304 1305* ``pkt_type``: The new software ptype to replace the old ones. 1306 1307Update hardware defined ptype to software defined packet type mapping table:: 1308 1309 testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype) 1310 1311where: 1312 1313* ``hw_ptype``: hardware ptype as the index of the ptype mapping table. 1314 1315* ``sw_ptype``: software ptype as the value of the ptype mapping table. 1316 1317Reset ptype mapping table:: 1318 1319 testpmd> ptype mapping reset (port_id) 1320 1321Port Functions 1322-------------- 1323 1324The following sections show functions for configuring ports. 1325 1326.. note:: 1327 1328 Port configuration changes only become active when forwarding is started/restarted. 1329 1330port attach 1331~~~~~~~~~~~ 1332 1333Attach a port specified by pci address or virtual device args:: 1334 1335 testpmd> port attach (identifier) 1336 1337To attach a new pci device, the device should be recognized by kernel first. 1338Then it should be moved under DPDK management. 1339Finally the port can be attached to testpmd. 1340 1341For example, to move a pci device using ixgbe under DPDK management: 1342 1343.. code-block:: console 1344 1345 # Check the status of the available devices. 1346 ./usertools/dpdk-devbind.py --status 1347 1348 Network devices using DPDK-compatible driver 1349 ============================================ 1350 <none> 1351 1352 Network devices using kernel driver 1353 =================================== 1354 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused= 1355 1356 1357 # Bind the device to igb_uio. 1358 sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0 1359 1360 1361 # Recheck the status of the devices. 1362 ./usertools/dpdk-devbind.py --status 1363 Network devices using DPDK-compatible driver 1364 ============================================ 1365 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= 1366 1367To attach a port created by virtual device, above steps are not needed. 1368 1369For example, to attach a port whose pci address is 0000:0a:00.0. 1370 1371.. code-block:: console 1372 1373 testpmd> port attach 0000:0a:00.0 1374 Attaching a new port... 1375 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1376 EAL: probe driver: 8086:10fb rte_ixgbe_pmd 1377 EAL: PCI memory mapped at 0x7f83bfa00000 1378 EAL: PCI memory mapped at 0x7f83bfa80000 1379 PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5 1380 PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb 1381 Port 0 is attached. Now total ports is 1 1382 Done 1383 1384For example, to attach a port created by pcap PMD. 1385 1386.. code-block:: console 1387 1388 testpmd> port attach net_pcap0 1389 Attaching a new port... 1390 PMD: Initializing pmd_pcap for net_pcap0 1391 PMD: Creating pcap-backed ethdev on numa socket 0 1392 Port 0 is attached. Now total ports is 1 1393 Done 1394 1395In this case, identifier is ``net_pcap0``. 1396This identifier format is the same as ``--vdev`` format of DPDK applications. 1397 1398For example, to re-attach a bonded port which has been previously detached, 1399the mode and slave parameters must be given. 1400 1401.. code-block:: console 1402 1403 testpmd> port attach net_bond_0,mode=0,slave=1 1404 Attaching a new port... 1405 EAL: Initializing pmd_bond for net_bond_0 1406 EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0. 1407 Port 0 is attached. Now total ports is 1 1408 Done 1409 1410 1411port detach 1412~~~~~~~~~~~ 1413 1414Detach a specific port:: 1415 1416 testpmd> port detach (port_id) 1417 1418Before detaching a port, the port should be stopped and closed. 1419 1420For example, to detach a pci device port 0. 1421 1422.. code-block:: console 1423 1424 testpmd> port stop 0 1425 Stopping ports... 1426 Done 1427 testpmd> port close 0 1428 Closing ports... 1429 Done 1430 1431 testpmd> port detach 0 1432 Detaching a port... 1433 EAL: PCI device 0000:0a:00.0 on NUMA socket -1 1434 EAL: remove driver: 8086:10fb rte_ixgbe_pmd 1435 EAL: PCI memory unmapped at 0x7f83bfa00000 1436 EAL: PCI memory unmapped at 0x7f83bfa80000 1437 Done 1438 1439 1440For example, to detach a virtual device port 0. 1441 1442.. code-block:: console 1443 1444 testpmd> port stop 0 1445 Stopping ports... 1446 Done 1447 testpmd> port close 0 1448 Closing ports... 1449 Done 1450 1451 testpmd> port detach 0 1452 Detaching a port... 1453 PMD: Closing pcap ethdev on numa socket 0 1454 Port 'net_pcap0' is detached. Now total ports is 0 1455 Done 1456 1457To remove a pci device completely from the system, first detach the port from testpmd. 1458Then the device should be moved under kernel management. 1459Finally the device can be removed using kernel pci hotplug functionality. 1460 1461For example, to move a pci device under kernel management: 1462 1463.. code-block:: console 1464 1465 sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0 1466 1467 ./usertools/dpdk-devbind.py --status 1468 1469 Network devices using DPDK-compatible driver 1470 ============================================ 1471 <none> 1472 1473 Network devices using kernel driver 1474 =================================== 1475 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio 1476 1477To remove a port created by a virtual device, above steps are not needed. 1478 1479port start 1480~~~~~~~~~~ 1481 1482Start all ports or a specific port:: 1483 1484 testpmd> port start (port_id|all) 1485 1486port stop 1487~~~~~~~~~ 1488 1489Stop all ports or a specific port:: 1490 1491 testpmd> port stop (port_id|all) 1492 1493port close 1494~~~~~~~~~~ 1495 1496Close all ports or a specific port:: 1497 1498 testpmd> port close (port_id|all) 1499 1500port start/stop queue 1501~~~~~~~~~~~~~~~~~~~~~ 1502 1503Start/stop a rx/tx queue on a specific port:: 1504 1505 testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop) 1506 1507Only take effect when port is started. 1508 1509port config - speed 1510~~~~~~~~~~~~~~~~~~~ 1511 1512Set the speed and duplex mode for all ports or a specific port:: 1513 1514 testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \ 1515 duplex (half|full|auto) 1516 1517port config - queues/descriptors 1518~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1519 1520Set number of queues/descriptors for rxq, txq, rxd and txd:: 1521 1522 testpmd> port config all (rxq|txq|rxd|txd) (value) 1523 1524This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options. 1525 1526port config - max-pkt-len 1527~~~~~~~~~~~~~~~~~~~~~~~~~ 1528 1529Set the maximum packet length:: 1530 1531 testpmd> port config all max-pkt-len (value) 1532 1533This is equivalent to the ``--max-pkt-len`` command-line option. 1534 1535port config - CRC Strip 1536~~~~~~~~~~~~~~~~~~~~~~~ 1537 1538Set hardware CRC stripping on or off for all ports:: 1539 1540 testpmd> port config all crc-strip (on|off) 1541 1542CRC stripping is on by default. 1543 1544The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option. 1545 1546port config - scatter 1547~~~~~~~~~~~~~~~~~~~~~~~ 1548 1549Set RX scatter mode on or off for all ports:: 1550 1551 testpmd> port config all scatter (on|off) 1552 1553RX scatter mode is off by default. 1554 1555The ``on`` option is equivalent to the ``--enable-scatter`` command-line option. 1556 1557port config - TX queue flags 1558~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1559 1560Set a hexadecimal bitmap of TX queue flags for all ports:: 1561 1562 testpmd> port config all txqflags value 1563 1564This command is equivalent to the ``--txqflags`` command-line option. 1565 1566port config - RX Checksum 1567~~~~~~~~~~~~~~~~~~~~~~~~~ 1568 1569Set hardware RX checksum offload to on or off for all ports:: 1570 1571 testpmd> port config all rx-cksum (on|off) 1572 1573Checksum offload is off by default. 1574 1575The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option. 1576 1577port config - VLAN 1578~~~~~~~~~~~~~~~~~~ 1579 1580Set hardware VLAN on or off for all ports:: 1581 1582 testpmd> port config all hw-vlan (on|off) 1583 1584Hardware VLAN is on by default. 1585 1586The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option. 1587 1588port config - VLAN filter 1589~~~~~~~~~~~~~~~~~~~~~~~~~ 1590 1591Set hardware VLAN filter on or off for all ports:: 1592 1593 testpmd> port config all hw-vlan-filter (on|off) 1594 1595Hardware VLAN filter is on by default. 1596 1597The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option. 1598 1599port config - VLAN strip 1600~~~~~~~~~~~~~~~~~~~~~~~~ 1601 1602Set hardware VLAN strip on or off for all ports:: 1603 1604 testpmd> port config all hw-vlan-strip (on|off) 1605 1606Hardware VLAN strip is on by default. 1607 1608The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option. 1609 1610port config - VLAN extend 1611~~~~~~~~~~~~~~~~~~~~~~~~~ 1612 1613Set hardware VLAN extend on or off for all ports:: 1614 1615 testpmd> port config all hw-vlan-extend (on|off) 1616 1617Hardware VLAN extend is off by default. 1618 1619The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option. 1620 1621port config - Drop Packets 1622~~~~~~~~~~~~~~~~~~~~~~~~~~ 1623 1624Set packet drop for packets with no descriptors on or off for all ports:: 1625 1626 testpmd> port config all drop-en (on|off) 1627 1628Packet dropping for packets with no descriptors is off by default. 1629 1630The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option. 1631 1632port config - RSS 1633~~~~~~~~~~~~~~~~~ 1634 1635Set the RSS (Receive Side Scaling) mode on or off:: 1636 1637 testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none) 1638 1639RSS is on by default. 1640 1641The ``none`` option is equivalent to the ``--disable-rss`` command-line option. 1642 1643port config - RSS Reta 1644~~~~~~~~~~~~~~~~~~~~~~ 1645 1646Set the RSS (Receive Side Scaling) redirection table:: 1647 1648 testpmd> port config all rss reta (hash,queue)[,(hash,queue)] 1649 1650port config - DCB 1651~~~~~~~~~~~~~~~~~ 1652 1653Set the DCB mode for an individual port:: 1654 1655 testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off) 1656 1657The traffic class should be 4 or 8. 1658 1659port config - Burst 1660~~~~~~~~~~~~~~~~~~~ 1661 1662Set the number of packets per burst:: 1663 1664 testpmd> port config all burst (value) 1665 1666This is equivalent to the ``--burst`` command-line option. 1667 1668port config - Threshold 1669~~~~~~~~~~~~~~~~~~~~~~~ 1670 1671Set thresholds for TX/RX queues:: 1672 1673 testpmd> port config all (threshold) (value) 1674 1675Where the threshold type can be: 1676 1677* ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255. 1678 1679* ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255. 1680 1681* ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255. 1682 1683* ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255. 1684 1685* ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255. 1686 1687* ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255. 1688 1689* ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd. 1690 1691* ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd. 1692 1693* ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd. 1694 1695These threshold options are also available from the command-line. 1696 1697port config - E-tag 1698~~~~~~~~~~~~~~~~~~~ 1699 1700Set the value of ether-type for E-tag:: 1701 1702 testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value) 1703 1704Enable/disable the E-tag support:: 1705 1706 testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable) 1707 1708port config pctype mapping 1709~~~~~~~~~~~~~~~~~~~~~~~~~~ 1710 1711Reset pctype mapping table:: 1712 1713 testpmd> port config (port_id) pctype mapping reset 1714 1715Update hardware defined pctype to software defined flow type mapping table:: 1716 1717 testpmd> port config (port_id) pctype mapping update (pctype_id_0[,pctype_id_1]*) (flow_type_id) 1718 1719where: 1720 1721* ``pctype_id_x``: hardware pctype id as index of bit in bitmask value of the pctype mapping table. 1722 1723* ``flow_type_id``: software flow type id as the index of the pctype mapping table. 1724 1725 1726Link Bonding Functions 1727---------------------- 1728 1729The Link Bonding functions make it possible to dynamically create and 1730manage link bonding devices from within testpmd interactive prompt. 1731 1732create bonded device 1733~~~~~~~~~~~~~~~~~~~~ 1734 1735Create a new bonding device:: 1736 1737 testpmd> create bonded device (mode) (socket) 1738 1739For example, to create a bonded device in mode 1 on socket 0:: 1740 1741 testpmd> create bonded 1 0 1742 created new bonded device (port X) 1743 1744add bonding slave 1745~~~~~~~~~~~~~~~~~ 1746 1747Adds Ethernet device to a Link Bonding device:: 1748 1749 testpmd> add bonding slave (slave id) (port id) 1750 1751For example, to add Ethernet device (port 6) to a Link Bonding device (port 10):: 1752 1753 testpmd> add bonding slave 6 10 1754 1755 1756remove bonding slave 1757~~~~~~~~~~~~~~~~~~~~ 1758 1759Removes an Ethernet slave device from a Link Bonding device:: 1760 1761 testpmd> remove bonding slave (slave id) (port id) 1762 1763For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10):: 1764 1765 testpmd> remove bonding slave 6 10 1766 1767set bonding mode 1768~~~~~~~~~~~~~~~~ 1769 1770Set the Link Bonding mode of a Link Bonding device:: 1771 1772 testpmd> set bonding mode (value) (port id) 1773 1774For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3):: 1775 1776 testpmd> set bonding mode 3 10 1777 1778set bonding primary 1779~~~~~~~~~~~~~~~~~~~ 1780 1781Set an Ethernet slave device as the primary device on a Link Bonding device:: 1782 1783 testpmd> set bonding primary (slave id) (port id) 1784 1785For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10):: 1786 1787 testpmd> set bonding primary 6 10 1788 1789set bonding mac 1790~~~~~~~~~~~~~~~ 1791 1792Set the MAC address of a Link Bonding device:: 1793 1794 testpmd> set bonding mac (port id) (mac) 1795 1796For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01:: 1797 1798 testpmd> set bonding mac 10 00:00:00:00:00:01 1799 1800set bonding xmit_balance_policy 1801~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1802 1803Set the transmission policy for a Link Bonding device when it is in Balance XOR mode:: 1804 1805 testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34) 1806 1807For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports):: 1808 1809 testpmd> set bonding xmit_balance_policy 10 l34 1810 1811 1812set bonding mon_period 1813~~~~~~~~~~~~~~~~~~~~~~ 1814 1815Set the link status monitoring polling period in milliseconds for a bonding device. 1816 1817This adds support for PMD slave devices which do not support link status interrupts. 1818When the mon_period is set to a value greater than 0 then all PMD's which do not support 1819link status ISR will be queried every polling interval to check if their link status has changed:: 1820 1821 testpmd> set bonding mon_period (port_id) (value) 1822 1823For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms:: 1824 1825 testpmd> set bonding mon_period 5 150 1826 1827 1828set bonding lacp dedicated_queue 1829~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1830 1831Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic 1832when in mode 4 (link-aggregration-802.3ad):: 1833 1834 testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable) 1835 1836 1837set bonding agg_mode 1838~~~~~~~~~~~~~~~~~~~~ 1839 1840Enable one of the specific aggregators mode when in mode 4 (link-aggregration-802.3ad):: 1841 1842 testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable) 1843 1844 1845show bonding config 1846~~~~~~~~~~~~~~~~~~~ 1847 1848Show the current configuration of a Link Bonding device:: 1849 1850 testpmd> show bonding config (port id) 1851 1852For example, 1853to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4) 1854in balance mode with a transmission policy of layer 2+3:: 1855 1856 testpmd> show bonding config 9 1857 Bonding mode: 2 1858 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23 1859 Slaves (3): [1 3 4] 1860 Active Slaves (3): [1 3 4] 1861 Primary: [3] 1862 1863 1864Register Functions 1865------------------ 1866 1867The Register Functions can be used to read from and write to registers on the network card referenced by a port number. 1868This is mainly useful for debugging purposes. 1869Reference should be made to the appropriate datasheet for the network card for details on the register addresses 1870and fields that can be accessed. 1871 1872read reg 1873~~~~~~~~ 1874 1875Display the value of a port register:: 1876 1877 testpmd> read reg (port_id) (address) 1878 1879For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller:: 1880 1881 testpmd> read reg 0 0xEE00 1882 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241) 1883 1884read regfield 1885~~~~~~~~~~~~~ 1886 1887Display a port register bit field:: 1888 1889 testpmd> read regfield (port_id) (address) (bit_x) (bit_y) 1890 1891For example, reading the lowest two bits from the register in the example above:: 1892 1893 testpmd> read regfield 0 0xEE00 0 1 1894 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1) 1895 1896read regbit 1897~~~~~~~~~~~ 1898 1899Display a single port register bit:: 1900 1901 testpmd> read regbit (port_id) (address) (bit_x) 1902 1903For example, reading the lowest bit from the register in the example above:: 1904 1905 testpmd> read regbit 0 0xEE00 0 1906 port 0 PCI register at offset 0xEE00: bit 0=1 1907 1908write reg 1909~~~~~~~~~ 1910 1911Set the value of a port register:: 1912 1913 testpmd> write reg (port_id) (address) (value) 1914 1915For example, to clear a register:: 1916 1917 testpmd> write reg 0 0xEE00 0x0 1918 port 0 PCI register at offset 0xEE00: 0x00000000 (0) 1919 1920write regfield 1921~~~~~~~~~~~~~~ 1922 1923Set bit field of a port register:: 1924 1925 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value) 1926 1927For example, writing to the register cleared in the example above:: 1928 1929 testpmd> write regfield 0 0xEE00 0 1 2 1930 port 0 PCI register at offset 0xEE00: 0x00000002 (2) 1931 1932write regbit 1933~~~~~~~~~~~~ 1934 1935Set single bit value of a port register:: 1936 1937 testpmd> write regbit (port_id) (address) (bit_x) (value) 1938 1939For example, to set the high bit in the register from the example above:: 1940 1941 testpmd> write regbit 0 0xEE00 31 1 1942 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658) 1943 1944 1945Filter Functions 1946---------------- 1947 1948This section details the available filter functions that are available. 1949 1950Note these functions interface the deprecated legacy filtering framework, 1951superseded by *rte_flow*. See `Flow rules management`_. 1952 1953ethertype_filter 1954~~~~~~~~~~~~~~~~~~~~ 1955 1956Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue:: 1957 1958 ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \ 1959 ethertype (ether_type) (drop|fwd) queue (queue_id) 1960 1961The available information parameters are: 1962 1963* ``port_id``: The port which the Ethertype filter assigned on. 1964 1965* ``mac_addr``: Compare destination mac address. 1966 1967* ``mac_ignr``: Ignore destination mac address match. 1968 1969* ``mac_address``: Destination mac address to match. 1970 1971* ``ether_type``: The EtherType value want to match, 1972 for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid. 1973 1974* ``queue_id``: The receive queue associated with this EtherType filter. 1975 It is meaningless when deleting or dropping. 1976 1977Example, to add/remove an ethertype filter rule:: 1978 1979 testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \ 1980 ethertype 0x0806 fwd queue 3 1981 1982 testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \ 1983 ethertype 0x0806 fwd queue 3 1984 19852tuple_filter 1986~~~~~~~~~~~~~~~~~ 1987 1988Add or delete a 2-tuple filter, 1989which identifies packets by specific protocol and destination TCP/UDP port 1990and forwards packets into one of the receive queues:: 1991 1992 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \ 1993 protocol (protocol_value) mask (mask_value) \ 1994 tcp_flags (tcp_flags_value) priority (prio_value) \ 1995 queue (queue_id) 1996 1997The available information parameters are: 1998 1999* ``port_id``: The port which the 2-tuple filter assigned on. 2000 2001* ``dst_port_value``: Destination port in L4. 2002 2003* ``protocol_value``: IP L4 protocol. 2004 2005* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate. 2006 2007* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP). 2008 2009* ``prio_value``: Priority of this filter. 2010 2011* ``queue_id``: The receive queue associated with this 2-tuple filter. 2012 2013Example, to add/remove an 2tuple filter rule:: 2014 2015 testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \ 2016 tcp_flags 0x02 priority 3 queue 3 2017 2018 testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \ 2019 tcp_flags 0x02 priority 3 queue 3 2020 20215tuple_filter 2022~~~~~~~~~~~~~~~~~ 2023 2024Add or delete a 5-tuple filter, 2025which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port) 2026and routes packets into one of the receive queues:: 2027 2028 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \ 2029 (src_address) dst_port (dst_port_value) \ 2030 src_port (src_port_value) protocol (protocol_value) \ 2031 mask (mask_value) tcp_flags (tcp_flags_value) \ 2032 priority (prio_value) queue (queue_id) 2033 2034The available information parameters are: 2035 2036* ``port_id``: The port which the 5-tuple filter assigned on. 2037 2038* ``dst_address``: Destination IP address. 2039 2040* ``src_address``: Source IP address. 2041 2042* ``dst_port_value``: TCP/UDP destination port. 2043 2044* ``src_port_value``: TCP/UDP source port. 2045 2046* ``protocol_value``: L4 protocol. 2047 2048* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate 2049 2050* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP). 2051 2052* ``prio_value``: The priority of this filter. 2053 2054* ``queue_id``: The receive queue associated with this 5-tuple filter. 2055 2056Example, to add/remove an 5tuple filter rule:: 2057 2058 testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2059 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2060 flags 0x0 priority 3 queue 3 2061 2062 testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \ 2063 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \ 2064 flags 0x0 priority 3 queue 3 2065 2066syn_filter 2067~~~~~~~~~~ 2068 2069Using the SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue:: 2070 2071 syn_filter (port_id) (add|del) priority (high|low) queue (queue_id) 2072 2073The available information parameters are: 2074 2075* ``port_id``: The port which the SYN filter assigned on. 2076 2077* ``high``: This SYN filter has higher priority than other filters. 2078 2079* ``low``: This SYN filter has lower priority than other filters. 2080 2081* ``queue_id``: The receive queue associated with this SYN filter 2082 2083Example:: 2084 2085 testpmd> syn_filter 0 add priority high queue 3 2086 2087flex_filter 2088~~~~~~~~~~~ 2089 2090With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet 2091and routed into one of the receive queues:: 2092 2093 flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \ 2094 mask (mask_value) priority (prio_value) queue (queue_id) 2095 2096The available information parameters are: 2097 2098* ``port_id``: The port which the Flex filter is assigned on. 2099 2100* ``len_value``: Filter length in bytes, no greater than 128. 2101 2102* ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match. 2103 2104* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match. 2105 2106* ``prio_value``: The priority of this filter. 2107 2108* ``queue_id``: The receive queue associated with this Flex filter. 2109 2110Example:: 2111 2112 testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \ 2113 mask 000C priority 3 queue 3 2114 2115 testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \ 2116 mask 000C priority 3 queue 3 2117 2118 2119.. _testpmd_flow_director: 2120 2121flow_director_filter 2122~~~~~~~~~~~~~~~~~~~~ 2123 2124The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues. 2125 2126Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and 2127Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter: 2128 2129* Perfect match filters. 2130 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2131 The masked fields are for IP flow. 2132 2133* Signature filters. 2134 The hardware checks a match between a hash-based signature of the masked fields of the received packet. 2135 2136* Perfect-mac-vlan match filters. 2137 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2138 The masked fields are for MAC VLAN flow. 2139 2140* Perfect-tunnel match filters. 2141 The hardware checks a match between the masked fields of the received packets and the programmed filters. 2142 The masked fields are for tunnel flow. 2143 2144The Flow Director filters can match the different fields for different type of packet: flow type, specific input set 2145per flow type and the flexible payload. 2146 2147The Flow Director can also mask out parts of all of these fields so that filters 2148are only applied to certain fields or parts of the fields. 2149 2150Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information. 2151 2152# Commands to add flow director filters of different flow types:: 2153 2154 flow_director_filter (port_id) mode IP (add|del|update) \ 2155 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ 2156 src (src_ip_address) dst (dst_ip_address) \ 2157 tos (tos_value) proto (proto_value) ttl (ttl_value) \ 2158 vlan (vlan_value) flexbytes (flexbytes_value) \ 2159 (drop|fwd) pf|vf(vf_id) queue (queue_id) \ 2160 fd_id (fd_id_value) 2161 2162 flow_director_filter (port_id) mode IP (add|del|update) \ 2163 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ 2164 src (src_ip_address) (src_port) \ 2165 dst (dst_ip_address) (dst_port) \ 2166 tos (tos_value) ttl (ttl_value) \ 2167 vlan (vlan_value) flexbytes (flexbytes_value) \ 2168 (drop|fwd) queue pf|vf(vf_id) (queue_id) \ 2169 fd_id (fd_id_value) 2170 2171 flow_director_filter (port_id) mode IP (add|del|update) \ 2172 flow (ipv4-sctp|ipv6-sctp) \ 2173 src (src_ip_address) (src_port) \ 2174 dst (dst_ip_address) (dst_port) \ 2175 tos (tos_value) ttl (ttl_value) \ 2176 tag (verification_tag) vlan (vlan_value) \ 2177 flexbytes (flexbytes_value) (drop|fwd) \ 2178 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) 2179 2180 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ 2181 ether (ethertype) flexbytes (flexbytes_value) \ 2182 (drop|fwd) pf|vf(vf_id) queue (queue_id) 2183 fd_id (fd_id_value) 2184 2185 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ 2186 mac (mac_address) vlan (vlan_value) \ 2187 flexbytes (flexbytes_value) (drop|fwd) \ 2188 queue (queue_id) fd_id (fd_id_value) 2189 2190 flow_director_filter (port_id) mode Tunnel (add|del|update) \ 2191 mac (mac_address) vlan (vlan_value) \ 2192 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ 2193 flexbytes (flexbytes_value) (drop|fwd) \ 2194 queue (queue_id) fd_id (fd_id_value) 2195 2196For example, to add an ipv4-udp flow type filter:: 2197 2198 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ 2199 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ 2200 fwd pf queue 1 fd_id 1 2201 2202For example, add an ipv4-other flow type filter:: 2203 2204 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ 2205 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ 2206 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 2207 2208flush_flow_director 2209~~~~~~~~~~~~~~~~~~~ 2210 2211Flush all flow director filters on a device:: 2212 2213 testpmd> flush_flow_director (port_id) 2214 2215Example, to flush all flow director filter on port 0:: 2216 2217 testpmd> flush_flow_director 0 2218 2219flow_director_mask 2220~~~~~~~~~~~~~~~~~~ 2221 2222Set flow director's input masks:: 2223 2224 flow_director_mask (port_id) mode IP vlan (vlan_value) \ 2225 src_mask (ipv4_src) (ipv6_src) (src_port) \ 2226 dst_mask (ipv4_dst) (ipv6_dst) (dst_port) 2227 2228 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) 2229 2230 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ 2231 mac (mac_value) tunnel-type (tunnel_type_value) \ 2232 tunnel-id (tunnel_id_value) 2233 2234Example, to set flow director mask on port 0:: 2235 2236 testpmd> flow_director_mask 0 mode IP vlan 0xefff \ 2237 src_mask 255.255.255.255 \ 2238 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ 2239 dst_mask 255.255.255.255 \ 2240 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF 2241 2242flow_director_flex_mask 2243~~~~~~~~~~~~~~~~~~~~~~~ 2244 2245set masks of flow director's flexible payload based on certain flow type:: 2246 2247 testpmd> flow_director_flex_mask (port_id) \ 2248 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2249 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \ 2250 l2_payload|all) (mask) 2251 2252Example, to set flow director's flex mask for all flow type on port 0:: 2253 2254 testpmd> flow_director_flex_mask 0 flow all \ 2255 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0) 2256 2257 2258flow_director_flex_payload 2259~~~~~~~~~~~~~~~~~~~~~~~~~~ 2260 2261Configure flexible payload selection:: 2262 2263 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config) 2264 2265For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload:: 2266 2267 testpmd> flow_director_flex_payload 0 l4 \ 2268 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19) 2269 2270get_sym_hash_ena_per_port 2271~~~~~~~~~~~~~~~~~~~~~~~~~ 2272 2273Get symmetric hash enable configuration per port:: 2274 2275 get_sym_hash_ena_per_port (port_id) 2276 2277For example, to get symmetric hash enable configuration of port 1:: 2278 2279 testpmd> get_sym_hash_ena_per_port 1 2280 2281set_sym_hash_ena_per_port 2282~~~~~~~~~~~~~~~~~~~~~~~~~ 2283 2284Set symmetric hash enable configuration per port to enable or disable:: 2285 2286 set_sym_hash_ena_per_port (port_id) (enable|disable) 2287 2288For example, to set symmetric hash enable configuration of port 1 to enable:: 2289 2290 testpmd> set_sym_hash_ena_per_port 1 enable 2291 2292get_hash_global_config 2293~~~~~~~~~~~~~~~~~~~~~~ 2294 2295Get the global configurations of hash filters:: 2296 2297 get_hash_global_config (port_id) 2298 2299For example, to get the global configurations of hash filters of port 1:: 2300 2301 testpmd> get_hash_global_config 1 2302 2303set_hash_global_config 2304~~~~~~~~~~~~~~~~~~~~~~ 2305 2306Set the global configurations of hash filters:: 2307 2308 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \ 2309 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \ 2310 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \ 2311 (enable|disable) 2312 2313For example, to enable simple_xor for flow type of ipv6 on port 2:: 2314 2315 testpmd> set_hash_global_config 2 simple_xor ipv6 enable 2316 2317set_hash_input_set 2318~~~~~~~~~~~~~~~~~~ 2319 2320Set the input set for hash:: 2321 2322 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2323 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2324 l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2325 ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ 2326 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ 2327 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ 2328 fld-8th|none) (select|add) 2329 2330For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: 2331 2332 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add 2333 2334set_fdir_input_set 2335~~~~~~~~~~~~~~~~~~ 2336 2337The Flow Director filters can match the different fields for different type of packet, i.e. specific input set 2338on per flow type and the flexible payload. This command can be used to change input set for each flow type. 2339 2340Set the input set for flow director:: 2341 2342 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ 2343 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ 2344 l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ 2345 ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ 2346 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ 2347 sctp-dst-port|sctp-veri-tag|none) (select|add) 2348 2349For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: 2350 2351 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add 2352 2353global_config 2354~~~~~~~~~~~~~ 2355 2356Set different GRE key length for input set:: 2357 2358 global_config (port_id) gre-key-len (number in bytes) 2359 2360For example to set GRE key length for input set to 4 bytes on port 0:: 2361 2362 testpmd> global_config 0 gre-key-len 4 2363 2364 2365.. _testpmd_rte_flow: 2366 2367Flow rules management 2368--------------------- 2369 2370Control of the generic flow API (*rte_flow*) is fully exposed through the 2371``flow`` command (validation, creation, destruction, queries and operation 2372modes). 2373 2374Considering *rte_flow* overlaps with all `Filter Functions`_, using both 2375features simultaneously may cause undefined side-effects and is therefore 2376not recommended. 2377 2378``flow`` syntax 2379~~~~~~~~~~~~~~~ 2380 2381Because the ``flow`` command uses dynamic tokens to handle the large number 2382of possible flow rules combinations, its behavior differs slightly from 2383other commands, in particular: 2384 2385- Pressing *?* or the *<tab>* key displays contextual help for the current 2386 token, not that of the entire command. 2387 2388- Optional and repeated parameters are supported (provided they are listed 2389 in the contextual help). 2390 2391The first parameter stands for the operation mode. Possible operations and 2392their general syntax are described below. They are covered in detail in the 2393following sections. 2394 2395- Check whether a flow rule can be created:: 2396 2397 flow validate {port_id} 2398 [group {group_id}] [priority {level}] [ingress] [egress] 2399 pattern {item} [/ {item} [...]] / end 2400 actions {action} [/ {action} [...]] / end 2401 2402- Create a flow rule:: 2403 2404 flow create {port_id} 2405 [group {group_id}] [priority {level}] [ingress] [egress] 2406 pattern {item} [/ {item} [...]] / end 2407 actions {action} [/ {action} [...]] / end 2408 2409- Destroy specific flow rules:: 2410 2411 flow destroy {port_id} rule {rule_id} [...] 2412 2413- Destroy all flow rules:: 2414 2415 flow flush {port_id} 2416 2417- Query an existing flow rule:: 2418 2419 flow query {port_id} {rule_id} {action} 2420 2421- List existing flow rules sorted by priority, filtered by group 2422 identifiers:: 2423 2424 flow list {port_id} [group {group_id}] [...] 2425 2426- Restrict ingress traffic to the defined flow rules:: 2427 2428 flow isolate {port_id} {boolean} 2429 2430Validating flow rules 2431~~~~~~~~~~~~~~~~~~~~~ 2432 2433``flow validate`` reports whether a flow rule would be accepted by the 2434underlying device in its current state but stops short of creating it. It is 2435bound to ``rte_flow_validate()``:: 2436 2437 flow validate {port_id} 2438 [group {group_id}] [priority {level}] [ingress] [egress] 2439 pattern {item} [/ {item} [...]] / end 2440 actions {action} [/ {action} [...]] / end 2441 2442If successful, it will show:: 2443 2444 Flow rule validated 2445 2446Otherwise it will show an error message of the form:: 2447 2448 Caught error type [...] ([...]): [...] 2449 2450This command uses the same parameters as ``flow create``, their format is 2451described in `Creating flow rules`_. 2452 2453Check whether redirecting any Ethernet packet received on port 0 to RX queue 2454index 6 is supported:: 2455 2456 testpmd> flow validate 0 ingress pattern eth / end 2457 actions queue index 6 / end 2458 Flow rule validated 2459 testpmd> 2460 2461Port 0 does not support TCPv6 rules:: 2462 2463 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end 2464 actions drop / end 2465 Caught error type 9 (specific pattern item): Invalid argument 2466 testpmd> 2467 2468Creating flow rules 2469~~~~~~~~~~~~~~~~~~~ 2470 2471``flow create`` validates and creates the specified flow rule. It is bound 2472to ``rte_flow_create()``:: 2473 2474 flow create {port_id} 2475 [group {group_id}] [priority {level}] [ingress] [egress] 2476 pattern {item} [/ {item} [...]] / end 2477 actions {action} [/ {action} [...]] / end 2478 2479If successful, it will return a flow rule ID usable with other commands:: 2480 2481 Flow rule #[...] created 2482 2483Otherwise it will show an error message of the form:: 2484 2485 Caught error type [...] ([...]): [...] 2486 2487Parameters describe in the following order: 2488 2489- Attributes (*group*, *priority*, *ingress*, *egress* tokens). 2490- A matching pattern, starting with the *pattern* token and terminated by an 2491 *end* pattern item. 2492- Actions, starting with the *actions* token and terminated by an *end* 2493 action. 2494 2495These translate directly to *rte_flow* objects provided as-is to the 2496underlying functions. 2497 2498The shortest valid definition only comprises mandatory tokens:: 2499 2500 testpmd> flow create 0 pattern end actions end 2501 2502Note that PMDs may refuse rules that essentially do nothing such as this 2503one. 2504 2505**All unspecified object values are automatically initialized to 0.** 2506 2507Attributes 2508^^^^^^^^^^ 2509 2510These tokens affect flow rule attributes (``struct rte_flow_attr``) and are 2511specified before the ``pattern`` token. 2512 2513- ``group {group id}``: priority group. 2514- ``priority {level}``: priority level within group. 2515- ``ingress``: rule applies to ingress traffic. 2516- ``egress``: rule applies to egress traffic. 2517 2518Each instance of an attribute specified several times overrides the previous 2519value as shown below (group 4 is used):: 2520 2521 testpmd> flow create 0 group 42 group 24 group 4 [...] 2522 2523Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. 2524 2525While not specifying a direction is an error, some rules may allow both 2526simultaneously. 2527 2528Most rules affect RX therefore contain the ``ingress`` token:: 2529 2530 testpmd> flow create 0 ingress pattern [...] 2531 2532Matching pattern 2533^^^^^^^^^^^^^^^^ 2534 2535A matching pattern starts after the ``pattern`` token. It is made of pattern 2536items and is terminated by a mandatory ``end`` item. 2537 2538Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum 2539rte_flow_item_type``). 2540 2541The ``/`` token is used as a separator between pattern items as shown 2542below:: 2543 2544 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] 2545 2546Note that protocol items like these must be stacked from lowest to highest 2547layer to make sense. For instance, the following rule is either invalid or 2548unlikely to match any packet:: 2549 2550 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] 2551 2552More information on these restrictions can be found in the *rte_flow* 2553documentation. 2554 2555Several items support additional specification structures, for example 2556``ipv4`` allows specifying source and destination addresses as follows:: 2557 2558 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 2559 dst is 10.2.0.0 / end [...] 2560 2561This rule matches all IPv4 traffic with the specified properties. 2562 2563In this example, ``src`` and ``dst`` are field names of the underlying 2564``struct rte_flow_item_ipv4`` object. All item properties can be specified 2565in a similar fashion. 2566 2567The ``is`` token means that the subsequent value must be matched exactly, 2568and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` 2569accordingly. Possible assignment tokens are: 2570 2571- ``is``: match value perfectly (with full bit-mask). 2572- ``spec``: match value according to configured bit-mask. 2573- ``last``: specify upper bound to establish a range. 2574- ``mask``: specify bit-mask with relevant bits set to one. 2575- ``prefix``: generate bit-mask from a prefix length. 2576 2577These yield identical results:: 2578 2579 ipv4 src is 10.1.1.1 2580 2581:: 2582 2583 ipv4 src spec 10.1.1.1 src mask 255.255.255.255 2584 2585:: 2586 2587 ipv4 src spec 10.1.1.1 src prefix 32 2588 2589:: 2590 2591 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value 2592 2593:: 2594 2595 ipv4 src is 10.1.1.1 src last 0 # 0 disables range 2596 2597Inclusive ranges can be defined with ``last``:: 2598 2599 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 2600 2601Note that ``mask`` affects both ``spec`` and ``last``:: 2602 2603 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 2604 # matches 10.1.0.0 to 10.2.255.255 2605 2606Properties can be modified multiple times:: 2607 2608 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 2609 2610:: 2611 2612 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 2613 2614Pattern items 2615^^^^^^^^^^^^^ 2616 2617This section lists supported pattern items and their attributes, if any. 2618 2619- ``end``: end list of pattern items. 2620 2621- ``void``: no-op pattern item. 2622 2623- ``invert``: perform actions when pattern does not match. 2624 2625- ``any``: match any protocol for the current layer. 2626 2627 - ``num {unsigned}``: number of layers covered. 2628 2629- ``pf``: match packets addressed to the physical function. 2630 2631- ``vf``: match packets addressed to a virtual function ID. 2632 2633 - ``id {unsigned}``: destination VF ID. 2634 2635- ``port``: device-specific physical port index to use. 2636 2637 - ``index {unsigned}``: physical port index. 2638 2639- ``raw``: match an arbitrary byte string. 2640 2641 - ``relative {boolean}``: look for pattern after the previous item. 2642 - ``search {boolean}``: search pattern from offset (see also limit). 2643 - ``offset {integer}``: absolute or relative offset for pattern. 2644 - ``limit {unsigned}``: search area limit for start of pattern. 2645 - ``pattern {string}``: byte string to look for. 2646 2647- ``eth``: match Ethernet header. 2648 2649 - ``dst {MAC-48}``: destination MAC. 2650 - ``src {MAC-48}``: source MAC. 2651 - ``type {unsigned}``: EtherType. 2652 2653- ``vlan``: match 802.1Q/ad VLAN tag. 2654 2655 - ``tpid {unsigned}``: tag protocol identifier. 2656 - ``tci {unsigned}``: tag control information. 2657 - ``pcp {unsigned}``: priority code point. 2658 - ``dei {unsigned}``: drop eligible indicator. 2659 - ``vid {unsigned}``: VLAN identifier. 2660 2661- ``ipv4``: match IPv4 header. 2662 2663 - ``tos {unsigned}``: type of service. 2664 - ``ttl {unsigned}``: time to live. 2665 - ``proto {unsigned}``: next protocol ID. 2666 - ``src {ipv4 address}``: source address. 2667 - ``dst {ipv4 address}``: destination address. 2668 2669- ``ipv6``: match IPv6 header. 2670 2671 - ``tc {unsigned}``: traffic class. 2672 - ``flow {unsigned}``: flow label. 2673 - ``proto {unsigned}``: protocol (next header). 2674 - ``hop {unsigned}``: hop limit. 2675 - ``src {ipv6 address}``: source address. 2676 - ``dst {ipv6 address}``: destination address. 2677 2678- ``icmp``: match ICMP header. 2679 2680 - ``type {unsigned}``: ICMP packet type. 2681 - ``code {unsigned}``: ICMP packet code. 2682 2683- ``udp``: match UDP header. 2684 2685 - ``src {unsigned}``: UDP source port. 2686 - ``dst {unsigned}``: UDP destination port. 2687 2688- ``tcp``: match TCP header. 2689 2690 - ``src {unsigned}``: TCP source port. 2691 - ``dst {unsigned}``: TCP destination port. 2692 2693- ``sctp``: match SCTP header. 2694 2695 - ``src {unsigned}``: SCTP source port. 2696 - ``dst {unsigned}``: SCTP destination port. 2697 - ``tag {unsigned}``: validation tag. 2698 - ``cksum {unsigned}``: checksum. 2699 2700- ``vxlan``: match VXLAN header. 2701 2702 - ``vni {unsigned}``: VXLAN identifier. 2703 2704- ``e_tag``: match IEEE 802.1BR E-Tag header. 2705 2706 - ``grp_ecid_b {unsigned}``: GRP and E-CID base. 2707 2708- ``nvgre``: match NVGRE header. 2709 2710 - ``tni {unsigned}``: virtual subnet ID. 2711 2712- ``mpls``: match MPLS header. 2713 2714 - ``label {unsigned}``: MPLS label. 2715 2716- ``gre``: match GRE header. 2717 2718 - ``protocol {unsigned}``: protocol type. 2719 2720- ``fuzzy``: fuzzy pattern match, expect faster than default. 2721 2722 - ``thresh {unsigned}``: accuracy threshold. 2723 2724- ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header. 2725 2726 - ``teid {unsigned}``: tunnel endpoint identifier. 2727 2728Actions list 2729^^^^^^^^^^^^ 2730 2731A list of actions starts after the ``actions`` token in the same fashion as 2732`Matching pattern`_; actions are separated by ``/`` tokens and the list is 2733terminated by a mandatory ``end`` action. 2734 2735Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum 2736rte_flow_action_type``). 2737 2738Dropping all incoming UDPv4 packets can be expressed as follows:: 2739 2740 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 2741 actions drop / end 2742 2743Several actions have configurable properties which must be specified when 2744there is no valid default value. For example, ``queue`` requires a target 2745queue index. 2746 2747This rule redirects incoming UDPv4 traffic to queue index 6:: 2748 2749 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 2750 actions queue index 6 / end 2751 2752While this one could be rejected by PMDs (unspecified queue index):: 2753 2754 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end 2755 actions queue / end 2756 2757As defined by *rte_flow*, the list is not ordered, all actions of a given 2758rule are performed simultaneously. These are equivalent:: 2759 2760 queue index 6 / void / mark id 42 / end 2761 2762:: 2763 2764 void / mark id 42 / queue index 6 / end 2765 2766All actions in a list should have different types, otherwise only the last 2767action of a given type is taken into account:: 2768 2769 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 2770 2771:: 2772 2773 drop / drop / drop / end # drop is performed only once 2774 2775:: 2776 2777 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 2778 2779Considering they are performed simultaneously, opposite and overlapping 2780actions can sometimes be combined when the end result is unambiguous:: 2781 2782 drop / queue index 6 / end # drop has no effect 2783 2784:: 2785 2786 drop / dup index 6 / end # same as above 2787 2788:: 2789 2790 queue index 6 / rss queues 6 7 8 / end # queue has no effect 2791 2792:: 2793 2794 drop / passthru / end # drop has no effect 2795 2796Note that PMDs may still refuse such combinations. 2797 2798Actions 2799^^^^^^^ 2800 2801This section lists supported actions and their attributes, if any. 2802 2803- ``end``: end list of actions. 2804 2805- ``void``: no-op action. 2806 2807- ``passthru``: let subsequent rule process matched packets. 2808 2809- ``mark``: attach 32 bit value to packets. 2810 2811 - ``id {unsigned}``: 32 bit value to return with packets. 2812 2813- ``flag``: flag packets. 2814 2815- ``queue``: assign packets to a given queue index. 2816 2817 - ``index {unsigned}``: queue index to use. 2818 2819- ``drop``: drop packets (note: passthru has priority). 2820 2821- ``count``: enable counters for this rule. 2822 2823- ``dup``: duplicate packets to a given queue index. 2824 2825 - ``index {unsigned}``: queue index to duplicate packets to. 2826 2827- ``rss``: spread packets among several queues. 2828 2829 - ``queues [{unsigned} [...]] end``: queue indices to use. 2830 2831- ``pf``: redirect packets to physical device function. 2832 2833- ``vf``: redirect packets to virtual device function. 2834 2835 - ``original {boolean}``: use original VF ID if possible. 2836 - ``id {unsigned}``: VF ID to redirect packets to. 2837 2838Destroying flow rules 2839~~~~~~~~~~~~~~~~~~~~~ 2840 2841``flow destroy`` destroys one or more rules from their rule ID (as returned 2842by ``flow create``), this command calls ``rte_flow_destroy()`` as many 2843times as necessary:: 2844 2845 flow destroy {port_id} rule {rule_id} [...] 2846 2847If successful, it will show:: 2848 2849 Flow rule #[...] destroyed 2850 2851It does not report anything for rule IDs that do not exist. The usual error 2852message is shown when a rule cannot be destroyed:: 2853 2854 Caught error type [...] ([...]): [...] 2855 2856``flow flush`` destroys all rules on a device and does not take extra 2857arguments. It is bound to ``rte_flow_flush()``:: 2858 2859 flow flush {port_id} 2860 2861Any errors are reported as above. 2862 2863Creating several rules and destroying them:: 2864 2865 testpmd> flow create 0 ingress pattern eth / ipv6 / end 2866 actions queue index 2 / end 2867 Flow rule #0 created 2868 testpmd> flow create 0 ingress pattern eth / ipv4 / end 2869 actions queue index 3 / end 2870 Flow rule #1 created 2871 testpmd> flow destroy 0 rule 0 rule 1 2872 Flow rule #1 destroyed 2873 Flow rule #0 destroyed 2874 testpmd> 2875 2876The same result can be achieved using ``flow flush``:: 2877 2878 testpmd> flow create 0 ingress pattern eth / ipv6 / end 2879 actions queue index 2 / end 2880 Flow rule #0 created 2881 testpmd> flow create 0 ingress pattern eth / ipv4 / end 2882 actions queue index 3 / end 2883 Flow rule #1 created 2884 testpmd> flow flush 0 2885 testpmd> 2886 2887Non-existent rule IDs are ignored:: 2888 2889 testpmd> flow create 0 ingress pattern eth / ipv6 / end 2890 actions queue index 2 / end 2891 Flow rule #0 created 2892 testpmd> flow create 0 ingress pattern eth / ipv4 / end 2893 actions queue index 3 / end 2894 Flow rule #1 created 2895 testpmd> flow destroy 0 rule 42 rule 10 rule 2 2896 testpmd> 2897 testpmd> flow destroy 0 rule 0 2898 Flow rule #0 destroyed 2899 testpmd> 2900 2901Querying flow rules 2902~~~~~~~~~~~~~~~~~~~ 2903 2904``flow query`` queries a specific action of a flow rule having that 2905ability. Such actions collect information that can be reported using this 2906command. It is bound to ``rte_flow_query()``:: 2907 2908 flow query {port_id} {rule_id} {action} 2909 2910If successful, it will display either the retrieved data for known actions 2911or the following message:: 2912 2913 Cannot display result for action type [...] ([...]) 2914 2915Otherwise, it will complain either that the rule does not exist or that some 2916error occurred:: 2917 2918 Flow rule #[...] not found 2919 2920:: 2921 2922 Caught error type [...] ([...]): [...] 2923 2924Currently only the ``count`` action is supported. This action reports the 2925number of packets that hit the flow rule and the total number of bytes. Its 2926output has the following format:: 2927 2928 count: 2929 hits_set: [...] # whether "hits" contains a valid value 2930 bytes_set: [...] # whether "bytes" contains a valid value 2931 hits: [...] # number of packets 2932 bytes: [...] # number of bytes 2933 2934Querying counters for TCPv6 packets redirected to queue 6:: 2935 2936 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end 2937 actions queue index 6 / count / end 2938 Flow rule #4 created 2939 testpmd> flow query 0 4 count 2940 count: 2941 hits_set: 1 2942 bytes_set: 0 2943 hits: 386446 2944 bytes: 0 2945 testpmd> 2946 2947Listing flow rules 2948~~~~~~~~~~~~~~~~~~ 2949 2950``flow list`` lists existing flow rules sorted by priority and optionally 2951filtered by group identifiers:: 2952 2953 flow list {port_id} [group {group_id}] [...] 2954 2955This command only fails with the following message if the device does not 2956exist:: 2957 2958 Invalid port [...] 2959 2960Output consists of a header line followed by a short description of each 2961flow rule, one per line. There is no output at all when no flow rules are 2962configured on the device:: 2963 2964 ID Group Prio Attr Rule 2965 [...] [...] [...] [...] [...] 2966 2967``Attr`` column flags: 2968 2969- ``i`` for ``ingress``. 2970- ``e`` for ``egress``. 2971 2972Creating several flow rules and listing them:: 2973 2974 testpmd> flow create 0 ingress pattern eth / ipv4 / end 2975 actions queue index 6 / end 2976 Flow rule #0 created 2977 testpmd> flow create 0 ingress pattern eth / ipv6 / end 2978 actions queue index 2 / end 2979 Flow rule #1 created 2980 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end 2981 actions rss queues 6 7 8 end / end 2982 Flow rule #2 created 2983 testpmd> flow list 0 2984 ID Group Prio Attr Rule 2985 0 0 0 i- ETH IPV4 => QUEUE 2986 1 0 0 i- ETH IPV6 => QUEUE 2987 2 0 5 i- ETH IPV4 UDP => RSS 2988 testpmd> 2989 2990Rules are sorted by priority (i.e. group ID first, then priority level):: 2991 2992 testpmd> flow list 1 2993 ID Group Prio Attr Rule 2994 0 0 0 i- ETH => COUNT 2995 6 0 500 i- ETH IPV6 TCP => DROP COUNT 2996 5 0 1000 i- ETH IPV6 ICMP => QUEUE 2997 1 24 0 i- ETH IPV4 UDP => QUEUE 2998 4 24 10 i- ETH IPV4 TCP => DROP 2999 3 24 20 i- ETH IPV4 => DROP 3000 2 24 42 i- ETH IPV4 UDP => QUEUE 3001 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3002 testpmd> 3003 3004Output can be limited to specific groups:: 3005 3006 testpmd> flow list 1 group 0 group 63 3007 ID Group Prio Attr Rule 3008 0 0 0 i- ETH => COUNT 3009 6 0 500 i- ETH IPV6 TCP => DROP COUNT 3010 5 0 1000 i- ETH IPV6 ICMP => QUEUE 3011 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE 3012 testpmd> 3013 3014Toggling isolated mode 3015~~~~~~~~~~~~~~~~~~~~~~ 3016 3017``flow isolate`` can be used to tell the underlying PMD that ingress traffic 3018must only be injected from the defined flow rules; that no default traffic 3019is expected outside those rules and the driver is free to assign more 3020resources to handle them. It is bound to ``rte_flow_isolate()``:: 3021 3022 flow isolate {port_id} {boolean} 3023 3024If successful, enabling or disabling isolated mode shows either:: 3025 3026 Ingress traffic on port [...] 3027 is now restricted to the defined flow rules 3028 3029Or:: 3030 3031 Ingress traffic on port [...] 3032 is not restricted anymore to the defined flow rules 3033 3034Otherwise, in case of error:: 3035 3036 Caught error type [...] ([...]): [...] 3037 3038Mainly due to its side effects, PMDs supporting this mode may not have the 3039ability to toggle it more than once without reinitializing affected ports 3040first (e.g. by exiting testpmd). 3041 3042Enabling isolated mode:: 3043 3044 testpmd> flow isolate 0 true 3045 Ingress traffic on port 0 is now restricted to the defined flow rules 3046 testpmd> 3047 3048Disabling isolated mode:: 3049 3050 testpmd> flow isolate 0 false 3051 Ingress traffic on port 0 is not restricted anymore to the defined flow rules 3052 testpmd> 3053 3054Sample QinQ flow rules 3055~~~~~~~~~~~~~~~~~~~~~~ 3056 3057Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: 3058 3059 testpmd> port stop 0 3060 testpmd> vlan set qinq on 0 3061 3062The above command sets the inner and outer TPID's to 0x8100. 3063 3064To change the TPID's the following commands should be used:: 3065 3066 testpmd> vlan set outer tpid 0xa100 0 3067 testpmd> vlan set inner tpid 0x9100 0 3068 testpmd> port start 0 3069 3070Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. 3071 3072:: 3073 3074 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / 3075 vlan tci is 456 / end actions vf id 1 / queue index 0 / end 3076 Flow rule #0 validated 3077 3078 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / 3079 vlan tci is 456 / end actions vf id 123 / queue index 0 / end 3080 Flow rule #0 created 3081 3082 testpmd> flow list 0 3083 ID Group Prio Attr Rule 3084 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3085 3086Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. 3087 3088:: 3089 3090 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / 3091 vlan tci is 654 / end actions pf / queue index 0 / end 3092 Flow rule #1 validated 3093 3094 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / 3095 vlan tci is 654 / end actions pf / queue index 1 / end 3096 Flow rule #1 created 3097 3098 testpmd> flow list 0 3099 ID Group Prio Attr Rule 3100 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 3101 1 0 0 i- ETH VLAN VLAN=>PF QUEUE 3102