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