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