X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftestpmd_app_ug%2Ftestpmd_funcs.rst;h=cafcd1d11f33e079c884203907f921afaba9a03e;hb=b40f8d782ba18e97ca4270823320dfe3242d8684;hp=957f8897b1c756fcab35c45fdfdfc2f8de11eeed;hpb=34a068db146fe806539ce194749862d7031b4c6b;p=dpdk.git diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst index 957f8897b1..cafcd1d11f 100644 --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst @@ -1,5 +1,5 @@ .. BSD LICENSE - Copyright(c) 2010-2015 Intel Corporation. All rights reserved. + Copyright(c) 2010-2016 Intel Corporation. All rights reserved. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -35,7 +35,8 @@ Testpmd Runtime Functions Where the testpmd application is started in interactive mode, (``-i|--interactive``), it displays a prompt that can be used to start and stop forwarding, -configure the application, display statistics, set the Flow Director and other tasks:: +configure the application, display statistics (including the extended NIC +statistics aka xstats) , set the Flow Director and other tasks:: testpmd> @@ -50,10 +51,10 @@ If you type a partial command and hit ```` you get a list of the available testpmd> show port - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc X - info [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc all - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc X - stats [Mul-choice STRING]: show|clear port info|stats|fdir|stat_qmap|dcb_tc all + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all ... @@ -85,6 +86,61 @@ These are divided into sections and can be accessed using help, help section or help all : All of the above sections. +Command File Functions +---------------------- + +To facilitate loading large number of commands or to avoid cutting and pasting where not +practical or possible testpmd supports alternative methods for executing commands. + +* If started with the ``--cmdline-file=FILENAME`` command line argument testpmd + will execute all CLI commands contained within the file immediately before + starting packet forwarding or entering interactive mode. + +.. code-block:: console + + ./testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt + Interactive-mode selected + CLI commands to be read from /home/ubuntu/flow-create-commands.txt + Configuring Port 0 (socket 0) + Port 0: 7C:FE:90:CB:74:CE + Configuring Port 1 (socket 0) + Port 1: 7C:FE:90:CB:74:CA + Checking link statuses... + Port 0 Link Up - speed 10000 Mbps - full-duplex + Port 1 Link Up - speed 10000 Mbps - full-duplex + Done + Flow rule #0 created + Flow rule #1 created + ... + ... + Flow rule #498 created + Flow rule #499 created + Read all CLI commands from /home/ubuntu/flow-create-commands.txt + testpmd> + + +* At run-time additional commands can be loaded in bulk by invoking the ``load FILENAME`` + command. + +.. code-block:: console + + testpmd> load /home/ubuntu/flow-create-commands.txt + Flow rule #0 created + Flow rule #1 created + ... + ... + Flow rule #498 created + Flow rule #499 created + Read all CLI commands from /home/ubuntu/flow-create-commands.txt + testpmd> + + +In all cases output from any included command will be displayed as standard output. +Execution will continue until the end of the file is reached regardless of +whether any errors occur. The end user must examine the output to determine if +any failures occurred. + + Control Functions ----------------- @@ -98,9 +154,11 @@ Start packet forwarding with current configuration:: start tx_first ~~~~~~~~~~~~~~ -Start packet forwarding with current configuration after sending one burst of packets:: +Start packet forwarding with current configuration after sending specified number of bursts of packets:: - testpmd> start tx_first + testpmd> start tx_first (""|burst_num) + +The default burst number is 1 when ``burst_num`` not presented. stop ~~~~ @@ -128,7 +186,7 @@ show port Display information for a given port or all ports:: - testpmd> show port (info|stats|fdir|stat_qmap|dcb_tc) (port_id|all) + testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc|cap) (port_id|all) The available information categories are: @@ -136,12 +194,16 @@ The available information categories are: * ``stats``: RX/TX statistics. +* ``xstats``: RX/TX extended NIC statistics. + * ``fdir``: Flow Director information and statistics. * ``stat_qmap``: Queue statistics mapping. * ``dcb_tc``: DCB information such as TC mapping. +* ``cap``: Supported offload capabilities. + For example: .. code-block:: console @@ -177,6 +239,10 @@ For example: ipv6-sctp ipv6-other l2_payload + port + vxlan + geneve + nvgre show port rss reta ~~~~~~~~~~~~~~~~~~ @@ -199,19 +265,26 @@ clear port Clear the port statistics for a given port or for all ports:: - testpmd> clear port (info|stats|fdir|stat_qmap) (port_id|all) + testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all) For example:: testpmd> clear port stats all +show (rxq|txq) +~~~~~~~~~~~~~~ + +Display information for a given port's RX/TX queue:: + + testpmd> show (rxq|txq) info (port_id) (queue_id) + show config ~~~~~~~~~~~ Displays the configuration of the application. The configuration comes from the command-line, the runtime or the application defaults:: - testpmd> show config (rxtx|cores|fwd) + testpmd> show config (rxtx|cores|fwd|txpkts) The available information categories are: @@ -221,6 +294,8 @@ The available information categories are: * ``fwd``: Packet forwarding configuration. +* ``txpkts``: Packets to TX configuration. + For example: .. code-block:: console @@ -240,8 +315,10 @@ set fwd Set the packet forwarding mode:: - testpmd> set fwd (io|mac|mac_retry|macswap|flowgen| \ - rxonly|txonly|csum|icmpecho) + testpmd> set fwd (io|mac|macswap|flowgen| \ + rxonly|txonly|csum|icmpecho) (""|retry) + +``retry`` can be specified for forwarding engines except ``rx_only``. The available information categories are: @@ -250,8 +327,9 @@ The available information categories are: This is the default mode. * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them. - -* ``mac_retry``: Same as "mac" forwarding mode, but includes retries if the destination queue is full. + Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination + address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or + 'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address. * ``macswap``: MAC swap forwarding mode. Swaps the source and the destination Ethernet addresses of packets before forwarding them. @@ -302,6 +380,33 @@ For example:: testpmd> read txd 0 0 4 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C +ddp get list +~~~~~~~~~~~~ + +Get loaded dynamic device personalization (DDP) package info list:: + + testpmd> ddp get list (port_id) + +ddp get info +~~~~~~~~~~~~ + +Display information about dynamic device personalization (DDP) profile:: + + testpmd> ddp get info (profile_patch) + +show vf stats +~~~~~~~~~~~~~ + +Display VF statistics:: + + testpmd> show vf stats (port_id) (vf_id) + +clear vf stats +~~~~~~~~~~~~~~ + +Reset VF statistics:: + + testpmd> clear vf stats (port_id) (vf_id) Configuration Functions ----------------------- @@ -383,19 +488,36 @@ Set number of packets per burst:: This is equivalent to the ``--burst command-line`` option. -In ``mac_retry`` forwarding mode, the transmit delay time and number of retries can also be set:: +When retry is enabled, the transmit delay time and number of retries can also be set:: - testpmd> set burst tx delay (micrseconds) retry (num) + testpmd> set burst tx delay (microseconds) retry (num) set txpkts ~~~~~~~~~~ -Set the length of each segment of the TX-ONLY packets:: +Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode:: testpmd> set txpkts (x[,y]*) Where x[,y]* represents a CSV list of values, without white space. +set txsplit +~~~~~~~~~~~ + +Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes:: + + testpmd> set txsplit (off|on|rand) + +Where: + +* ``off`` disable packet copy & split for CSUM mode. + +* ``on`` split outgoing packet into multiple segments. Size of each segment + and number of segments per packet is determined by ``set txpkts`` command + (see above). + +* ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments. + set corelist ~~~~~~~~~~~~ @@ -441,6 +563,73 @@ For example, to change the port forwarding: RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02 +set tx loopback +~~~~~~~~~~~~~~~ + +Enable/disable tx loopback:: + + testpmd> set tx loopback (port_id) (on|off) + +set drop enable +~~~~~~~~~~~~~~~ + +set drop enable bit for all queues:: + + testpmd> set all queues drop (port_id) (on|off) + +set split drop enable (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +set split drop enable bit for VF from PF:: + + testpmd> set vf split drop (port_id) (vf_id) (on|off) + +set mac antispoof (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set mac antispoof for a VF from the PF:: + + testpmd> set vf mac antispoof (port_id) (vf_id) (on|off) + +set macsec offload +~~~~~~~~~~~~~~~~~~ + +Enable/disable MACsec offload:: + + testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off) + testpmd> set macsec offload (port_id) off + +set macsec sc +~~~~~~~~~~~~~ + +Configure MACsec secure connection (SC):: + + testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi) + +.. note:: + + The pi argument is ignored for tx. + Check the NIC Datasheet for hardware limits. + +set macsec sa +~~~~~~~~~~~~~ + +Configure MACsec secure association (SA):: + + testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key) + +.. note:: + + The IDX value must be 0 or 1. + Check the NIC Datasheet for hardware limits. + +set broadcast mode (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set broadcast mode for a VF from the PF:: + + testpmd> set vf broadcast (port_id) (vf_id) (on|off) + vlan set strip ~~~~~~~~~~~~~~ @@ -455,6 +644,34 @@ Set the VLAN strip for a queue on a port:: testpmd> vlan set stripq (on|off) (port_id,queue_id) +vlan set stripq (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN strip for all queues in a pool for a VF from the PF:: + + testpmd> set vf vlan stripq (port_id) (vf_id) (on|off) + +vlan set insert (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN insert for a VF from the PF:: + + testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id) + +vlan set tag (for VF) +~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN tag for a VF from the PF:: + + testpmd> set vf vlan tag (port_id) (vf_id) (on|off) + +vlan set antispoof (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set VLAN antispoof for a VF from the PF:: + + testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off) + vlan set filter ~~~~~~~~~~~~~~~ @@ -472,9 +689,9 @@ Set the VLAN QinQ (extended queue in queue) on for a port:: vlan set tpid ~~~~~~~~~~~~~ -Set the outer VLAN TPID for packet filtering on a port:: +Set the inner or outer VLAN TPID for packet filtering on a port:: - testpmd> vlan set tpid (value) (port_id) + testpmd> vlan set (inner|outer) tpid (value) (port_id) .. note:: @@ -514,20 +731,43 @@ Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port I testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask) -rx_vlan set tpid -~~~~~~~~~~~~~~~~ - -Set the outer VLAN TPID for packet filtering on a port:: - - testpmd> rx_vlan set tpid (value) (port_id) - tunnel_filter add ~~~~~~~~~~~~~~~~~ Add a tunnel filter on a port:: testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \ - (inner_vlan) (tunnel_type) (filter_type) (tenant_id) (queue_id) + (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ + imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) + +The available information categories are: + +* ``vxlan``: Set tunnel type as VXLAN. + +* ``nvgre``: Set tunnel type as NVGRE. + +* ``ipingre``: Set tunnel type as IP-in-GRE. + +* ``imac-ivlan``: Set filter type as Inner MAC and VLAN. + +* ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID. + +* ``imac-tenid``: Set filter type as Inner MAC and tenant ID. + +* ``imac``: Set filter type as Inner MAC. + +* ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID. + +* ``oip``: Set filter type as Outer IP. + +* ``iip``: Set filter type as Inner IP. + +Example:: + + testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \ + 192.168.2.2 0 ipingre oip 1 1 + + Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP. tunnel_filter remove ~~~~~~~~~~~~~~~~~~~~ @@ -535,7 +775,8 @@ tunnel_filter remove Remove a tunnel filter on a port:: testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \ - (inner_vlan) (tunnel_type) (filter_type) (tenant_id) (queue_id) + (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\ + imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id) rx_vxlan_port add ~~~~~~~~~~~~~~~~~ @@ -657,6 +898,40 @@ Display the status of TCP Segmentation Offload:: testpmd> tso show (port_id) +gro +~~~ + +Enable or disable GRO in ``csum`` forwarding engine:: + + testpmd> gro (on|off) (port_id) + +If enabled, the csum forwarding engine will perform GRO on the TCP/IPv4 +packets received from the given port. + +If disabled, packets received from the given port won't be performed +GRO. By default, GRO is disabled for all ports. + +.. note:: + + When enable GRO for a port, TCP/IPv4 packets received from the port + will be performed GRO. After GRO, the merged packets are multi-segments. + But csum forwarding engine doesn't support to calculate TCP checksum + for multi-segment packets in SW. So please select TCP HW checksum + calculation for the port which GROed packets are transmitted to. + +gro set +~~~~~~~ + +Set max flow number and max packet number per-flow for GRO:: + + testpmd> gro set (max_flow_num) (max_item_num_per_flow) (port_id) + +The product of ``max_flow_num`` and ``max_item_num_per_flow`` is the max +number of packets a GRO table can store. + +If current packet number is greater than or equal to the max value, GRO +will stop processing incoming packets. + mac_addr add ~~~~~~~~~~~~ @@ -671,13 +946,27 @@ Remove a MAC address from a port:: testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX) -mac_addr add(for VF) -~~~~~~~~~~~~~~~~~~~~ +mac_addr add (for VF) +~~~~~~~~~~~~~~~~~~~~~ Add an alternative MAC address for a VF to a port:: testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX) +mac_addr set +~~~~~~~~~~~~ + +Set the default MAC address for a port:: + + testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX) + +mac_addr set (for VF) +~~~~~~~~~~~~~~~~~~~~~ + +Set the MAC address for a VF from the PF:: + + testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX) + set port-uta ~~~~~~~~~~~~ @@ -702,6 +991,59 @@ Set the allmulti mode for a port or for all ports:: Same as the ifconfig (8) option. Controls how multicast packets are handled. +set promisc (for VF) +~~~~~~~~~~~~~~~~~~~~ + +Set the unicast promiscuous mode for a VF from PF. +It's supported by Intel i40e NICs now. +In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: + + testpmd> set vf promisc (port_id) (vf_id) (on|off) + +set allmulticast (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set the multicast promiscuous mode for a VF from PF. +It's supported by Intel i40e NICs now. +In promiscuous mode packets are not dropped if they aren't for the specified MAC address:: + + testpmd> set vf allmulti (port_id) (vf_id) (on|off) + +set tx max bandwidth (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set TX max absolute bandwidth (Mbps) for a VF from PF:: + + testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth) + +set tc tx min bandwidth (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set all TCs' TX min relative bandwidth (%) for a VF from PF:: + + testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...) + +set tc tx max bandwidth (for VF) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF:: + + testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth) + +set tc strict link priority mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set some TCs' strict link priority mode on a physical port:: + + testpmd> set tx strict-link-priority (port_id) (tc_bitmap) + +set tc tx min bandwidth +~~~~~~~~~~~~~~~~~~~~~~~ + +Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs:: + + testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...) + set flow_ctrl rx ~~~~~~~~~~~~~~~~ @@ -723,7 +1065,7 @@ Where: * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames. -* ``autoneg``: Change the auto-negotiation para mete. +* ``autoneg``: Change the auto-negotiation parameter. set pfc_ctrl rx ~~~~~~~~~~~~~~~ @@ -891,6 +1233,82 @@ Set link down for a port:: testpmd> set link-down port (port id) +E-tag set +~~~~~~~~~ + +Enable E-tag insertion for a VF on a port:: + + testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id) + +Disable E-tag insertion for a VF on a port:: + + testpmd> E-tag set insertion off port (port_id) vf (vf_id) + +Enable/disable E-tag stripping on a port:: + + testpmd> E-tag set stripping (on|off) port (port_id) + +Enable/disable E-tag based forwarding on a port:: + + testpmd> E-tag set forwarding (on|off) port (port_id) + +Add an E-tag forwarding filter on a port:: + + testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id) + +Delete an E-tag forwarding filter on a port:: + testpmd> E-tag set filter del e-tag-id (value) port (port_id) + +ddp add +~~~~~~~ + +Load a dynamic device personalization (DDP) package:: + + testpmd> ddp add (port_id) (package_path[,output_path]) + +ddp del +~~~~~~~ + +Delete a dynamic device personalization package:: + + testpmd> ddp del (port_id) (package_path) + +ptype mapping +~~~~~~~~~~~~~ + +List all items from the ptype mapping table:: + + testpmd> ptype mapping get (port_id) (valid_only) + +Where: + +* ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0). + +Replace a specific or a group of software defined ptype with a new one:: + + testpmd> ptype mapping replace (port_id) (target) (mask) (pkt_type) + +where: + +* ``target``: A specific software ptype or a mask to represent a group of software ptypes. + +* ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1). + +* ``pkt_type``: The new software ptype to replace the old ones. + +Update hardware defined ptype to software defined packet type mapping table:: + + testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype) + +where: + +* ``hw_ptype``: hardware ptype as the index of the ptype mapping table. + +* ``sw_ptype``: software ptype as the value of the ptype mapping table. + +Reset ptype mapping table:: + + testpmd> ptype mapping reset (port_id) Port Functions -------------- @@ -904,7 +1322,9 @@ The following sections show functions for configuring ports. port attach ~~~~~~~~~~~ -Attach a port specified by pci address or virtual device args. +Attach a port specified by pci address or virtual device args:: + + testpmd> port attach (identifier) To attach a new pci device, the device should be recognized by kernel first. Then it should be moved under DPDK management. @@ -915,7 +1335,7 @@ For example, to move a pci device using ixgbe under DPDK management: .. code-block:: console # Check the status of the available devices. - ./tools/dpdk_nic_bind.py --status + ./usertools/dpdk-devbind.py --status Network devices using DPDK-compatible driver ============================================ @@ -927,19 +1347,17 @@ For example, to move a pci device using ixgbe under DPDK management: # Bind the device to igb_uio. - sudo ./tools/dpdk_nic_bind.py -b igb_uio 0000:0a:00.0 + sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0 # Recheck the status of the devices. - ./tools/dpdk_nic_bind.py --status + ./usertools/dpdk-devbind.py --status Network devices using DPDK-compatible driver ============================================ 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused= To attach a port created by virtual device, above steps are not needed. -port attach (identifier) - For example, to attach a port whose pci address is 0000:0a:00.0. .. code-block:: console @@ -959,14 +1377,14 @@ For example, to attach a port created by pcap PMD. .. code-block:: console - testpmd> port attach eth_pcap0 + testpmd> port attach net_pcap0 Attaching a new port... - PMD: Initializing pmd_pcap for eth_pcap0 + PMD: Initializing pmd_pcap for net_pcap0 PMD: Creating pcap-backed ethdev on numa socket 0 Port 0 is attached. Now total ports is 1 Done -In this case, identifier is ``eth_pcap0``. +In this case, identifier is ``net_pcap0``. This identifier format is the same as ``--vdev`` format of DPDK applications. For example, to re-attach a bonded port which has been previously detached, @@ -974,10 +1392,10 @@ the mode and slave parameters must be given. .. code-block:: console - testpmd> port attach eth_bond_0,mode=0,slave=1 + testpmd> port attach net_bond_0,mode=0,slave=1 Attaching a new port... - EAL: Initializing pmd_bond for eth_bond_0 - EAL: Create bonded device eth_bond_0 on port 0 in mode 0 on socket 0. + EAL: Initializing pmd_bond for net_bond_0 + EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0. Port 0 is attached. Now total ports is 1 Done @@ -985,16 +1403,19 @@ the mode and slave parameters must be given. port detach ~~~~~~~~~~~ -Detach a specific port. - -Before detaching a port, the port should be closed:: +Detach a specific port:: testpmd> port detach (port_id) +Before detaching a port, the port should be stopped and closed. + For example, to detach a pci device port 0. .. code-block:: console + testpmd> port stop 0 + Stopping ports... + Done testpmd> port close 0 Closing ports... Done @@ -1012,6 +1433,9 @@ For example, to detach a virtual device port 0. .. code-block:: console + testpmd> port stop 0 + Stopping ports... + Done testpmd> port close 0 Closing ports... Done @@ -1019,7 +1443,7 @@ For example, to detach a virtual device port 0. testpmd> port detach 0 Detaching a port... PMD: Closing pcap ethdev on numa socket 0 - Port 'eth_pcap0' is detached. Now total ports is 0 + Port 'net_pcap0' is detached. Now total ports is 0 Done To remove a pci device completely from the system, first detach the port from testpmd. @@ -1030,9 +1454,9 @@ For example, to move a pci device under kernel management: .. code-block:: console - sudo ./tools/dpdk_nic_bind.py -b ixgbe 0000:0a:00.0 + sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0 - ./tools/dpdk_nic_bind.py --status + ./usertools/dpdk-devbind.py --status Network devices using DPDK-compatible driver ============================================ @@ -1079,7 +1503,7 @@ port config - speed Set the speed and duplex mode for all ports or a specific port:: - testpmd> port config (port_id|all) speed (10|100|1000|10000|auto) \ + testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \ duplex (half|full|auto) port config - queues/descriptors @@ -1107,9 +1531,29 @@ Set hardware CRC stripping on or off for all ports:: testpmd> port config all crc-strip (on|off) -CRC stripping is off by default. +CRC stripping is on by default. + +The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option. + +port config - scatter +~~~~~~~~~~~~~~~~~~~~~~~ + +Set RX scatter mode on or off for all ports:: + + testpmd> port config all scatter (on|off) -The ``on`` option is equivalent to the ``--crc-strip`` command-line option. +RX scatter mode is off by default. + +The ``on`` option is equivalent to the ``--enable-scatter`` command-line option. + +port config - TX queue flags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Set a hexadecimal bitmap of TX queue flags for all ports:: + + testpmd> port config all txqflags value + +This command is equivalent to the ``--txqflags`` command-line option. port config - RX Checksum ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1182,7 +1626,7 @@ port config - RSS Set the RSS (Receive Side Scaling) mode on or off:: - testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|none) + testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none) RSS is on by default. @@ -1242,6 +1686,17 @@ Where the threshold type can be: These threshold options are also available from the command-line. +port config - E-tag +~~~~~~~~~~~~~~~~~~~ + +Set the value of ether-type for E-tag:: + + testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value) + +Enable/disable the E-tag support:: + + testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable) + Link Bonding Functions ---------------------- @@ -1345,6 +1800,15 @@ For example, to set the link status monitoring polling period of bonded device ( testpmd> set bonding mon_period 5 150 +set bonding lacp dedicated_queue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic +when in mode 4 (link-aggregration-802.3ad) + + testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable) + + show bonding config ~~~~~~~~~~~~~~~~~~~ @@ -1450,6 +1914,9 @@ Filter Functions This section details the available filter functions that are available. +Note these functions interface the deprecated legacy filtering framework, +superseded by *rte_flow*. See `Flow rules management`_. + ethertype_filter ~~~~~~~~~~~~~~~~~~~~ @@ -1623,15 +2090,24 @@ flow_director_filter The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues. -Two types of filtering are supported which are referred to as Perfect Match and Signature filters, the match mode -is set by the ``--pkt-filter-mode`` command-line parameter: +Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and +Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter: * Perfect match filters. The hardware checks a match between the masked fields of the received packets and the programmed filters. + The masked fields are for IP flow. * Signature filters. The hardware checks a match between a hash-based signature of the masked fields of the received packet. +* Perfect-mac-vlan match filters. + The hardware checks a match between the masked fields of the received packets and the programmed filters. + The masked fields are for MAC VLAN flow. + +* Perfect-tunnel match filters. + The hardware checks a match between the masked fields of the received packets and the programmed filters. + The masked fields are for tunnel flow. + The Flow Director filters can match the different fields for different type of packet: flow type, specific input set per flow type and the flexible payload. @@ -1642,40 +2118,59 @@ Different NICs may have different capabilities, command show port fdir (port_id) # Commands to add flow director filters of different flow types:: - flow_director_filter (port_id) (add|del|update) \ - flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) + flow_director_filter (port_id) mode IP (add|del|update) \ + flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \ src (src_ip_address) dst (dst_ip_address) \ + tos (tos_value) proto (proto_value) ttl (ttl_value) \ vlan (vlan_value) flexbytes (flexbytes_value) \ - (drop|fwd) queue (queue_id) fd_id (fd_id_value) + (drop|fwd) pf|vf(vf_id) queue (queue_id) \ + fd_id (fd_id_value) - flow_director_filter (port_id) (add|del|update) \ + flow_director_filter (port_id) mode IP (add|del|update) \ flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \ src (src_ip_address) (src_port) \ dst (dst_ip_address) (dst_port) \ + tos (tos_value) ttl (ttl_value) \ vlan (vlan_value) flexbytes (flexbytes_value) \ - (drop|fwd) queue (queue_id) fd_id (fd_id_value) + (drop|fwd) queue pf|vf(vf_id) (queue_id) \ + fd_id (fd_id_value) - flow_director_filter (port_id) (add|del|update) \ + flow_director_filter (port_id) mode IP (add|del|update) \ flow (ipv4-sctp|ipv6-sctp) \ src (src_ip_address) (src_port) \ - dst (dst_ip_address) (dst_port) + dst (dst_ip_address) (dst_port) \ + tos (tos_value) ttl (ttl_value) \ tag (verification_tag) vlan (vlan_value) \ flexbytes (flexbytes_value) (drop|fwd) \ - queue (queue_id) fd_id (fd_id_value) + pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value) - flow_director_filter (port_id) (add|del|update) flow l2_payload \ + flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \ ether (ethertype) flexbytes (flexbytes_value) \ - (drop|fwd) queue (queue_id) fd_id (fd_id_value) + (drop|fwd) pf|vf(vf_id) queue (queue_id) + fd_id (fd_id_value) + + flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \ + mac (mac_address) vlan (vlan_value) \ + flexbytes (flexbytes_value) (drop|fwd) \ + queue (queue_id) fd_id (fd_id_value) + + flow_director_filter (port_id) mode Tunnel (add|del|update) \ + mac (mac_address) vlan (vlan_value) \ + tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \ + flexbytes (flexbytes_value) (drop|fwd) \ + queue (queue_id) fd_id (fd_id_value) For example, to add an ipv4-udp flow type filter:: - testpmd> flow_director_filter 0 add flow ipv4-udp src 2.2.2.3 32 \ - dst 2.2.2.5 33 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd_id 1 + testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \ + dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \ + fwd pf queue 1 fd_id 1 For example, add an ipv4-other flow type filter:: - testpmd> flow_director_filter 0 add flow ipv4-other src 2.2.2.3 \ - dst 2.2.2.5 vlan 0x1 flexbytes (0x88,0x48) fwd queue 1 fd_id 1 + testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \ + dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \ + flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1 flush_flow_director ~~~~~~~~~~~~~~~~~~~ @@ -1693,13 +2188,19 @@ flow_director_mask Set flow director's input masks:: - flow_director_mask (port_id) vlan (vlan_value) \ + flow_director_mask (port_id) mode IP vlan (vlan_value) \ src_mask (ipv4_src) (ipv6_src) (src_port) \ dst_mask (ipv4_dst) (ipv6_dst) (dst_port) + flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value) + + flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \ + mac (mac_value) tunnel-type (tunnel_type_value) \ + tunnel-id (tunnel_id_value) + Example, to set flow director mask on port 0:: - testpmd> flow_director_mask 0 vlan 0xefff \ + testpmd> flow_director_mask 0 mode IP vlan 0xefff \ src_mask 255.255.255.255 \ FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \ dst_mask 255.255.255.255 \ @@ -1785,33 +2286,36 @@ set_hash_input_set Set the input set for hash:: - set_hash_input_set (port_id) (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ - ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ + set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ + ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \ tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \ fld-8th|none) (select|add) -For example, to add source IP to hash input set for flow type of ipv4 on port 0:: +For example, to add source IP to hash input set for flow type of ipv4-udp on port 0:: - testpmd> set_hash_input_set 0 ipv4 src-ipv4 add + testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add set_fdir_input_set ~~~~~~~~~~~~~~~~~~ -Set the input set for Fdir:: +The Flow Director filters can match the different fields for different type of packet, i.e. specific input set +on per flow type and the flexible payload. This command can be used to change input set for each flow type. - set_fdir_input_set (port_id) (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ - ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) - (src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|udp-src-port|udp-dst-port| \ - tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \ - fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th|fld-8th|none) \ - (select|add) +Set the input set for flow director:: + + set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \ + ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \ + l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \ + ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \ + tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \ + sctp-dst-port|sctp-veri-tag|none) (select|add) -For example to add source IP to FD input set for flow type of ipv4 on port 0:: +For example to add source IP to FD input set for flow type of ipv4-udp on port 0:: - testpmd> set_fdir_input_set 0 ipv4 src-ipv4 add + testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add global_config ~~~~~~~~~~~~~ @@ -1823,3 +2327,738 @@ Set different GRE key length for input set:: For example to set GRE key length for input set to 4 bytes on port 0:: testpmd> global_config 0 gre-key-len 4 + + +.. _testpmd_rte_flow: + +Flow rules management +--------------------- + +Control of the generic flow API (*rte_flow*) is fully exposed through the +``flow`` command (validation, creation, destruction, queries and operation +modes). + +Considering *rte_flow* overlaps with all `Filter Functions`_, using both +features simultaneously may cause undefined side-effects and is therefore +not recommended. + +``flow`` syntax +~~~~~~~~~~~~~~~ + +Because the ``flow`` command uses dynamic tokens to handle the large number +of possible flow rules combinations, its behavior differs slightly from +other commands, in particular: + +- Pressing *?* or the ** key displays contextual help for the current + token, not that of the entire command. + +- Optional and repeated parameters are supported (provided they are listed + in the contextual help). + +The first parameter stands for the operation mode. Possible operations and +their general syntax are described below. They are covered in detail in the +following sections. + +- Check whether a flow rule can be created:: + + flow validate {port_id} + [group {group_id}] [priority {level}] [ingress] [egress] + pattern {item} [/ {item} [...]] / end + actions {action} [/ {action} [...]] / end + +- Create a flow rule:: + + flow create {port_id} + [group {group_id}] [priority {level}] [ingress] [egress] + pattern {item} [/ {item} [...]] / end + actions {action} [/ {action} [...]] / end + +- Destroy specific flow rules:: + + flow destroy {port_id} rule {rule_id} [...] + +- Destroy all flow rules:: + + flow flush {port_id} + +- Query an existing flow rule:: + + flow query {port_id} {rule_id} {action} + +- List existing flow rules sorted by priority, filtered by group + identifiers:: + + flow list {port_id} [group {group_id}] [...] + +- Restrict ingress traffic to the defined flow rules:: + + flow isolate {port_id} {boolean} + +Validating flow rules +~~~~~~~~~~~~~~~~~~~~~ + +``flow validate`` reports whether a flow rule would be accepted by the +underlying device in its current state but stops short of creating it. It is +bound to ``rte_flow_validate()``:: + + flow validate {port_id} + [group {group_id}] [priority {level}] [ingress] [egress] + pattern {item} [/ {item} [...]] / end + actions {action} [/ {action} [...]] / end + +If successful, it will show:: + + Flow rule validated + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +This command uses the same parameters as ``flow create``, their format is +described in `Creating flow rules`_. + +Check whether redirecting any Ethernet packet received on port 0 to RX queue +index 6 is supported:: + + testpmd> flow validate 0 ingress pattern eth / end + actions queue index 6 / end + Flow rule validated + testpmd> + +Port 0 does not support TCPv6 rules:: + + testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end + actions drop / end + Caught error type 9 (specific pattern item): Invalid argument + testpmd> + +Creating flow rules +~~~~~~~~~~~~~~~~~~~ + +``flow create`` validates and creates the specified flow rule. It is bound +to ``rte_flow_create()``:: + + flow create {port_id} + [group {group_id}] [priority {level}] [ingress] [egress] + pattern {item} [/ {item} [...]] / end + actions {action} [/ {action} [...]] / end + +If successful, it will return a flow rule ID usable with other commands:: + + Flow rule #[...] created + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +Parameters describe in the following order: + +- Attributes (*group*, *priority*, *ingress*, *egress* tokens). +- A matching pattern, starting with the *pattern* token and terminated by an + *end* pattern item. +- Actions, starting with the *actions* token and terminated by an *end* + action. + +These translate directly to *rte_flow* objects provided as-is to the +underlying functions. + +The shortest valid definition only comprises mandatory tokens:: + + testpmd> flow create 0 pattern end actions end + +Note that PMDs may refuse rules that essentially do nothing such as this +one. + +**All unspecified object values are automatically initialized to 0.** + +Attributes +^^^^^^^^^^ + +These tokens affect flow rule attributes (``struct rte_flow_attr``) and are +specified before the ``pattern`` token. + +- ``group {group id}``: priority group. +- ``priority {level}``: priority level within group. +- ``ingress``: rule applies to ingress traffic. +- ``egress``: rule applies to egress traffic. + +Each instance of an attribute specified several times overrides the previous +value as shown below (group 4 is used):: + + testpmd> flow create 0 group 42 group 24 group 4 [...] + +Note that once enabled, ``ingress`` and ``egress`` cannot be disabled. + +While not specifying a direction is an error, some rules may allow both +simultaneously. + +Most rules affect RX therefore contain the ``ingress`` token:: + + testpmd> flow create 0 ingress pattern [...] + +Matching pattern +^^^^^^^^^^^^^^^^ + +A matching pattern starts after the ``pattern`` token. It is made of pattern +items and is terminated by a mandatory ``end`` item. + +Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum +rte_flow_item_type``). + +The ``/`` token is used as a separator between pattern items as shown +below:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...] + +Note that protocol items like these must be stacked from lowest to highest +layer to make sense. For instance, the following rule is either invalid or +unlikely to match any packet:: + + testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...] + +More information on these restrictions can be found in the *rte_flow* +documentation. + +Several items support additional specification structures, for example +``ipv4`` allows specifying source and destination addresses as follows:: + + testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1 + dst is 10.2.0.0 / end [...] + +This rule matches all IPv4 traffic with the specified properties. + +In this example, ``src`` and ``dst`` are field names of the underlying +``struct rte_flow_item_ipv4`` object. All item properties can be specified +in a similar fashion. + +The ``is`` token means that the subsequent value must be matched exactly, +and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item`` +accordingly. Possible assignment tokens are: + +- ``is``: match value perfectly (with full bit-mask). +- ``spec``: match value according to configured bit-mask. +- ``last``: specify upper bound to establish a range. +- ``mask``: specify bit-mask with relevant bits set to one. +- ``prefix``: generate bit-mask from a prefix length. + +These yield identical results:: + + ipv4 src is 10.1.1.1 + +:: + + ipv4 src spec 10.1.1.1 src mask 255.255.255.255 + +:: + + ipv4 src spec 10.1.1.1 src prefix 32 + +:: + + ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value + +:: + + ipv4 src is 10.1.1.1 src last 0 # 0 disables range + +Inclusive ranges can be defined with ``last``:: + + ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4 + +Note that ``mask`` affects both ``spec`` and ``last``:: + + ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0 + # matches 10.1.0.0 to 10.2.255.255 + +Properties can be modified multiple times:: + + ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4 + +:: + + ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16 + +Pattern items +^^^^^^^^^^^^^ + +This section lists supported pattern items and their attributes, if any. + +- ``end``: end list of pattern items. + +- ``void``: no-op pattern item. + +- ``invert``: perform actions when pattern does not match. + +- ``any``: match any protocol for the current layer. + + - ``num {unsigned}``: number of layers covered. + +- ``pf``: match packets addressed to the physical function. + +- ``vf``: match packets addressed to a virtual function ID. + + - ``id {unsigned}``: destination VF ID. + +- ``port``: device-specific physical port index to use. + + - ``index {unsigned}``: physical port index. + +- ``raw``: match an arbitrary byte string. + + - ``relative {boolean}``: look for pattern after the previous item. + - ``search {boolean}``: search pattern from offset (see also limit). + - ``offset {integer}``: absolute or relative offset for pattern. + - ``limit {unsigned}``: search area limit for start of pattern. + - ``pattern {string}``: byte string to look for. + +- ``eth``: match Ethernet header. + + - ``dst {MAC-48}``: destination MAC. + - ``src {MAC-48}``: source MAC. + - ``type {unsigned}``: EtherType. + +- ``vlan``: match 802.1Q/ad VLAN tag. + + - ``tpid {unsigned}``: tag protocol identifier. + - ``tci {unsigned}``: tag control information. + - ``pcp {unsigned}``: priority code point. + - ``dei {unsigned}``: drop eligible indicator. + - ``vid {unsigned}``: VLAN identifier. + +- ``ipv4``: match IPv4 header. + + - ``tos {unsigned}``: type of service. + - ``ttl {unsigned}``: time to live. + - ``proto {unsigned}``: next protocol ID. + - ``src {ipv4 address}``: source address. + - ``dst {ipv4 address}``: destination address. + +- ``ipv6``: match IPv6 header. + + - ``tc {unsigned}``: traffic class. + - ``flow {unsigned}``: flow label. + - ``proto {unsigned}``: protocol (next header). + - ``hop {unsigned}``: hop limit. + - ``src {ipv6 address}``: source address. + - ``dst {ipv6 address}``: destination address. + +- ``icmp``: match ICMP header. + + - ``type {unsigned}``: ICMP packet type. + - ``code {unsigned}``: ICMP packet code. + +- ``udp``: match UDP header. + + - ``src {unsigned}``: UDP source port. + - ``dst {unsigned}``: UDP destination port. + +- ``tcp``: match TCP header. + + - ``src {unsigned}``: TCP source port. + - ``dst {unsigned}``: TCP destination port. + +- ``sctp``: match SCTP header. + + - ``src {unsigned}``: SCTP source port. + - ``dst {unsigned}``: SCTP destination port. + - ``tag {unsigned}``: validation tag. + - ``cksum {unsigned}``: checksum. + +- ``vxlan``: match VXLAN header. + + - ``vni {unsigned}``: VXLAN identifier. + +- ``e_tag``: match IEEE 802.1BR E-Tag header. + + - ``grp_ecid_b {unsigned}``: GRP and E-CID base. + +- ``nvgre``: match NVGRE header. + + - ``tni {unsigned}``: virtual subnet ID. + +- ``mpls``: match MPLS header. + + - ``label {unsigned}``: MPLS label. + +- ``gre``: match GRE header. + + - ``protocol {unsigned}``: protocol type. + +- ``fuzzy``: fuzzy pattern match, expect faster than default. + + - ``thresh {unsigned}``: accuracy threshold. + +Actions list +^^^^^^^^^^^^ + +A list of actions starts after the ``actions`` token in the same fashion as +`Matching pattern`_; actions are separated by ``/`` tokens and the list is +terminated by a mandatory ``end`` action. + +Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum +rte_flow_action_type``). + +Dropping all incoming UDPv4 packets can be expressed as follows:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end + actions drop / end + +Several actions have configurable properties which must be specified when +there is no valid default value. For example, ``queue`` requires a target +queue index. + +This rule redirects incoming UDPv4 traffic to queue index 6:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end + actions queue index 6 / end + +While this one could be rejected by PMDs (unspecified queue index):: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end + actions queue / end + +As defined by *rte_flow*, the list is not ordered, all actions of a given +rule are performed simultaneously. These are equivalent:: + + queue index 6 / void / mark id 42 / end + +:: + + void / mark id 42 / queue index 6 / end + +All actions in a list should have different types, otherwise only the last +action of a given type is taken into account:: + + queue index 4 / queue index 5 / queue index 6 / end # will use queue 6 + +:: + + drop / drop / drop / end # drop is performed only once + +:: + + mark id 42 / queue index 3 / mark id 24 / end # mark will be 24 + +Considering they are performed simultaneously, opposite and overlapping +actions can sometimes be combined when the end result is unambiguous:: + + drop / queue index 6 / end # drop has no effect + +:: + + drop / dup index 6 / end # same as above + +:: + + queue index 6 / rss queues 6 7 8 / end # queue has no effect + +:: + + drop / passthru / end # drop has no effect + +Note that PMDs may still refuse such combinations. + +Actions +^^^^^^^ + +This section lists supported actions and their attributes, if any. + +- ``end``: end list of actions. + +- ``void``: no-op action. + +- ``passthru``: let subsequent rule process matched packets. + +- ``mark``: attach 32 bit value to packets. + + - ``id {unsigned}``: 32 bit value to return with packets. + +- ``flag``: flag packets. + +- ``queue``: assign packets to a given queue index. + + - ``index {unsigned}``: queue index to use. + +- ``drop``: drop packets (note: passthru has priority). + +- ``count``: enable counters for this rule. + +- ``dup``: duplicate packets to a given queue index. + + - ``index {unsigned}``: queue index to duplicate packets to. + +- ``rss``: spread packets among several queues. + + - ``queues [{unsigned} [...]] end``: queue indices to use. + +- ``pf``: redirect packets to physical device function. + +- ``vf``: redirect packets to virtual device function. + + - ``original {boolean}``: use original VF ID if possible. + - ``id {unsigned}``: VF ID to redirect packets to. + +Destroying flow rules +~~~~~~~~~~~~~~~~~~~~~ + +``flow destroy`` destroys one or more rules from their rule ID (as returned +by ``flow create``), this command calls ``rte_flow_destroy()`` as many +times as necessary:: + + flow destroy {port_id} rule {rule_id} [...] + +If successful, it will show:: + + Flow rule #[...] destroyed + +It does not report anything for rule IDs that do not exist. The usual error +message is shown when a rule cannot be destroyed:: + + Caught error type [...] ([...]): [...] + +``flow flush`` destroys all rules on a device and does not take extra +arguments. It is bound to ``rte_flow_flush()``:: + + flow flush {port_id} + +Any errors are reported as above. + +Creating several rules and destroying them:: + + testpmd> flow create 0 ingress pattern eth / ipv6 / end + actions queue index 2 / end + Flow rule #0 created + testpmd> flow create 0 ingress pattern eth / ipv4 / end + actions queue index 3 / end + Flow rule #1 created + testpmd> flow destroy 0 rule 0 rule 1 + Flow rule #1 destroyed + Flow rule #0 destroyed + testpmd> + +The same result can be achieved using ``flow flush``:: + + testpmd> flow create 0 ingress pattern eth / ipv6 / end + actions queue index 2 / end + Flow rule #0 created + testpmd> flow create 0 ingress pattern eth / ipv4 / end + actions queue index 3 / end + Flow rule #1 created + testpmd> flow flush 0 + testpmd> + +Non-existent rule IDs are ignored:: + + testpmd> flow create 0 ingress pattern eth / ipv6 / end + actions queue index 2 / end + Flow rule #0 created + testpmd> flow create 0 ingress pattern eth / ipv4 / end + actions queue index 3 / end + Flow rule #1 created + testpmd> flow destroy 0 rule 42 rule 10 rule 2 + testpmd> + testpmd> flow destroy 0 rule 0 + Flow rule #0 destroyed + testpmd> + +Querying flow rules +~~~~~~~~~~~~~~~~~~~ + +``flow query`` queries a specific action of a flow rule having that +ability. Such actions collect information that can be reported using this +command. It is bound to ``rte_flow_query()``:: + + flow query {port_id} {rule_id} {action} + +If successful, it will display either the retrieved data for known actions +or the following message:: + + Cannot display result for action type [...] ([...]) + +Otherwise, it will complain either that the rule does not exist or that some +error occurred:: + + Flow rule #[...] not found + +:: + + Caught error type [...] ([...]): [...] + +Currently only the ``count`` action is supported. This action reports the +number of packets that hit the flow rule and the total number of bytes. Its +output has the following format:: + + count: + hits_set: [...] # whether "hits" contains a valid value + bytes_set: [...] # whether "bytes" contains a valid value + hits: [...] # number of packets + bytes: [...] # number of bytes + +Querying counters for TCPv6 packets redirected to queue 6:: + + testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end + actions queue index 6 / count / end + Flow rule #4 created + testpmd> flow query 0 4 count + count: + hits_set: 1 + bytes_set: 0 + hits: 386446 + bytes: 0 + testpmd> + +Listing flow rules +~~~~~~~~~~~~~~~~~~ + +``flow list`` lists existing flow rules sorted by priority and optionally +filtered by group identifiers:: + + flow list {port_id} [group {group_id}] [...] + +This command only fails with the following message if the device does not +exist:: + + Invalid port [...] + +Output consists of a header line followed by a short description of each +flow rule, one per line. There is no output at all when no flow rules are +configured on the device:: + + ID Group Prio Attr Rule + [...] [...] [...] [...] [...] + +``Attr`` column flags: + +- ``i`` for ``ingress``. +- ``e`` for ``egress``. + +Creating several flow rules and listing them:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / end + actions queue index 6 / end + Flow rule #0 created + testpmd> flow create 0 ingress pattern eth / ipv6 / end + actions queue index 2 / end + Flow rule #1 created + testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end + actions rss queues 6 7 8 end / end + Flow rule #2 created + testpmd> flow list 0 + ID Group Prio Attr Rule + 0 0 0 i- ETH IPV4 => QUEUE + 1 0 0 i- ETH IPV6 => QUEUE + 2 0 5 i- ETH IPV4 UDP => RSS + testpmd> + +Rules are sorted by priority (i.e. group ID first, then priority level):: + + testpmd> flow list 1 + ID Group Prio Attr Rule + 0 0 0 i- ETH => COUNT + 6 0 500 i- ETH IPV6 TCP => DROP COUNT + 5 0 1000 i- ETH IPV6 ICMP => QUEUE + 1 24 0 i- ETH IPV4 UDP => QUEUE + 4 24 10 i- ETH IPV4 TCP => DROP + 3 24 20 i- ETH IPV4 => DROP + 2 24 42 i- ETH IPV4 UDP => QUEUE + 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE + testpmd> + +Output can be limited to specific groups:: + + testpmd> flow list 1 group 0 group 63 + ID Group Prio Attr Rule + 0 0 0 i- ETH => COUNT + 6 0 500 i- ETH IPV6 TCP => DROP COUNT + 5 0 1000 i- ETH IPV6 ICMP => QUEUE + 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE + testpmd> + +Toggling isolated mode +~~~~~~~~~~~~~~~~~~~~~~ + +``flow isolate`` can be used to tell the underlying PMD that ingress traffic +must only be injected from the defined flow rules; that no default traffic +is expected outside those rules and the driver is free to assign more +resources to handle them. It is bound to ``rte_flow_isolate()``:: + + flow isolate {port_id} {boolean} + +If successful, enabling or disabling isolated mode shows either:: + + Ingress traffic on port [...] + is now restricted to the defined flow rules + +Or:: + + Ingress traffic on port [...] + is not restricted anymore to the defined flow rules + +Otherwise, in case of error:: + + Caught error type [...] ([...]): [...] + +Mainly due to its side effects, PMDs supporting this mode may not have the +ability to toggle it more than once without reinitializing affected ports +first (e.g. by exiting testpmd). + +Enabling isolated mode:: + + testpmd> flow isolate 0 true + Ingress traffic on port 0 is now restricted to the defined flow rules + testpmd> + +Disabling isolated mode:: + + testpmd> flow isolate 0 false + Ingress traffic on port 0 is not restricted anymore to the defined flow rules + testpmd> + +Sample QinQ flow rules +~~~~~~~~~~~~~~~~~~~~~~ + +Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: + + testpmd> port stop 0 + testpmd> vlan set qinq on 0 + +The above command sets the inner and outer TPID's to 0x8100. + +To change the TPID's the following commands should be used:: + + testpmd> vlan set outer tpid 0xa100 0 + testpmd> vlan set inner tpid 0x9100 0 + testpmd> port start 0 + +Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. + +:: + + testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 / + vlan tci is 456 / end actions vf id 1 / queue index 0 / end + Flow rule #0 validated + + testpmd> flow create 0 ingress pattern eth / vlan tci is 4 / + vlan tci is 456 / end actions vf id 123 / queue index 0 / end + Flow rule #0 created + + testpmd> flow list 0 + ID Group Prio Attr Rule + 0 0 0 i- ETH VLAN VLAN=>VF QUEUE + +Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host. + +:: + + testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 / + vlan tci is 654 / end actions pf / queue index 0 / end + Flow rule #1 validated + + testpmd> flow create 0 ingress pattern eth / vlan tci is 321 / + vlan tci is 654 / end actions pf / queue index 1 / end + Flow rule #1 created + + testpmd> flow list 0 + ID Group Prio Attr Rule + 0 0 0 i- ETH VLAN VLAN=>VF QUEUE + 1 0 0 i- ETH VLAN VLAN=>PF QUEUE