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