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