2 Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
33 Testpmd Runtime Functions
34 =========================
36 Where the testpmd application is started in interactive mode, (``-i|--interactive``),
37 it displays a prompt that can be used to start and stop forwarding,
38 configure the application, display statistics (including the extended NIC
39 statistics aka xstats) , set the Flow Director and other tasks::
43 The testpmd prompt has some, limited, readline support.
44 Common bash command-line functions such as ``Ctrl+a`` and ``Ctrl+e`` to go to the start and end of the prompt line are supported
45 as well as access to the command history via the up-arrow.
47 There is also support for tab completion.
48 If you type a partial command and hit ``<TAB>`` you get a list of the available completions:
50 .. code-block:: console
52 testpmd> show port <TAB>
54 info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc X
55 info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all
56 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc X
57 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all
63 Some examples in this document are too long to fit on one line are are shown wrapped at `"\\"` for display purposes::
65 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
66 (pause_time) (send_xon) (port_id)
68 In the real ``testpmd>`` prompt these commands should be on a single line.
73 The testpmd has on-line help for the functions that are available at runtime.
74 These are divided into sections and can be accessed using help, help section or help all:
76 .. code-block:: console
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.
95 Start packet forwarding with current configuration::
102 Start packet forwarding with current configuration after sending specified number of bursts of packets::
104 testpmd> start tx_first (""|burst_num)
106 The default burst number is 1 when ``burst_num`` not presented.
111 Stop packet forwarding, and display accumulated statistics::
126 The functions in the following sections are used to display information about the
127 testpmd configuration or the NIC status.
132 Display information for a given port or all ports::
134 testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc) (port_id|all)
136 The available information categories are:
138 * ``info``: General port information such as MAC address.
140 * ``stats``: RX/TX statistics.
142 * ``xstats``: RX/TX extended NIC statistics.
144 * ``fdir``: Flow Director information and statistics.
146 * ``stat_qmap``: Queue statistics mapping.
148 * ``dcb_tc``: DCB information such as TC mapping.
152 .. code-block:: console
154 testpmd> show port info 0
156 ********************* Infos for port 0 *********************
158 MAC address: XX:XX:XX:XX:XX:XX
160 memory allocation on the socket: 0
162 Link speed: 40000 Mbps
163 Link duplex: full-duplex
164 Promiscuous mode: enabled
165 Allmulticast mode: disabled
166 Maximum number of MAC addresses: 64
167 Maximum number of MAC addresses of hash filtering: 0
172 Redirection table size: 512
173 Supported flow types:
193 Display the rss redirection table entry indicated by masks on port X::
195 testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
197 size is used to indicate the hardware supported reta size
202 Display the RSS hash functions and RSS hash key of a port::
204 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]
209 Clear the port statistics for a given port or for all ports::
211 testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all)
215 testpmd> clear port stats all
220 Display information for a given port's RX/TX queue::
222 testpmd> show (rxq|txq) info (port_id) (queue_id)
227 Displays the configuration of the application.
228 The configuration comes from the command-line, the runtime or the application defaults::
230 testpmd> show config (rxtx|cores|fwd|txpkts)
232 The available information categories are:
234 * ``rxtx``: RX/TX configuration items.
236 * ``cores``: List of forwarding cores.
238 * ``fwd``: Packet forwarding configuration.
240 * ``txpkts``: Packets to TX configuration.
244 .. code-block:: console
246 testpmd> show config rxtx
248 io packet forwarding - CRC stripping disabled - packets/burst=16
249 nb forwarding cores=2 - nb forwarding ports=1
250 RX queues=1 - RX desc=128 - RX free threshold=0
251 RX threshold registers: pthresh=8 hthresh=8 wthresh=4
252 TX queues=1 - TX desc=512 - TX free threshold=0
253 TX threshold registers: pthresh=36 hthresh=0 wthresh=0
254 TX RS bit threshold=0 - TXQ flags=0x0
259 Set the packet forwarding mode::
261 testpmd> set fwd (io|mac|macswap|flowgen| \
262 rxonly|txonly|csum|icmpecho) (""|retry)
264 ``retry`` can be specified for forwarding engines except ``rx_only``.
266 The available information categories are:
268 * ``io``: Forwards packets "as-is" in I/O mode.
269 This is the fastest possible forwarding operation as it does not access packets data.
270 This is the default mode.
272 * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
273 Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination
274 address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
275 'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
277 * ``macswap``: MAC swap forwarding mode.
278 Swaps the source and the destination Ethernet addresses of packets before forwarding them.
280 * ``flowgen``: Multi-flow generation mode.
281 Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
283 * ``rxonly``: Receives packets but doesn't transmit them.
285 * ``txonly``: Generates and transmits packets without receiving any.
287 * ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
289 * ``icmpecho``: Receives a burst of packets, lookup for IMCP echo requests and, if any, send back ICMP echo replies.
291 * ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=y``.
293 Note: TX timestamping is only available in the "Full Featured" TX path. To force ``testpmd`` into this mode set ``--txqflags=0``.
297 testpmd> set fwd rxonly
299 Set rxonly packet forwarding mode
305 Display an RX descriptor for a port RX queue::
307 testpmd> read rxd (port_id) (queue_id) (rxd_id)
311 testpmd> read rxd 0 0 4
312 0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
317 Display a TX descriptor for a port TX queue::
319 testpmd> read txd (port_id) (queue_id) (txd_id)
323 testpmd> read txd 0 0 4
324 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
327 Configuration Functions
328 -----------------------
330 The testpmd application can be configured from the runtime as well as from the command-line.
332 This section details the available configuration functions that are available.
336 Configuration changes only become active when forwarding is started/restarted.
341 Reset forwarding to the default configuration::
348 Set the debug verbosity level::
350 testpmd> set verbose (level)
352 Currently the only available levels are 0 (silent except for error) and 1 (fully verbose).
357 Set the number of ports used by the application:
361 This is equivalent to the ``--nb-ports`` command-line option.
366 Set the number of cores used by the application::
368 testpmd> set nbcore (num)
370 This is equivalent to the ``--nb-cores`` command-line option.
374 The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
379 Set the forwarding cores hexadecimal mask::
381 testpmd> set coremask (mask)
383 This is equivalent to the ``--coremask`` command-line option.
387 The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
392 Set the forwarding ports hexadecimal mask::
394 testpmd> set portmask (mask)
396 This is equivalent to the ``--portmask`` command-line option.
401 Set number of packets per burst::
403 testpmd> set burst (num)
405 This is equivalent to the ``--burst command-line`` option.
407 When retry is enabled, the transmit delay time and number of retries can also be set::
409 testpmd> set burst tx delay (microseconds) retry (num)
414 Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
416 testpmd> set txpkts (x[,y]*)
418 Where x[,y]* represents a CSV list of values, without white space.
423 Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
425 testpmd> set txsplit (off|on|rand)
429 * ``off`` disable packet copy & split for CSUM mode.
431 * ``on`` split outgoing packet into multiple segments. Size of each segment
432 and number of segments per packet is determined by ``set txpkts`` command
435 * ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
440 Set the list of forwarding cores::
442 testpmd> set corelist (x[,y]*)
444 For example, to change the forwarding cores:
446 .. code-block:: console
448 testpmd> set corelist 3,1
449 testpmd> show config fwd
451 io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
452 Logical Core 3 (socket 0) forwards packets on 1 streams:
453 RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
454 Logical Core 1 (socket 0) forwards packets on 1 streams:
455 RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
459 The cores are used in the same order as specified on the command line.
464 Set the list of forwarding ports::
466 testpmd> set portlist (x[,y]*)
468 For example, to change the port forwarding:
470 .. code-block:: console
472 testpmd> set portlist 0,2,1,3
473 testpmd> show config fwd
475 io packet forwarding - ports=4 - cores=1 - streams=4
476 Logical Core 3 (socket 0) forwards packets on 4 streams:
477 RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
478 RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
479 RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
480 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
485 Enable/disable tx loopback::
487 testpmd> set tx loopback (port_id) (on|off)
492 set drop enable bit for all queues::
494 testpmd> set all queues drop (port_id) (on|off)
496 set split drop enable (for VF)
497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
499 set split drop enable bit for VF from PF::
501 testpmd> set vf split drop (port_id) (vf_id) (on|off)
503 set mac antispoof (for VF)
504 ~~~~~~~~~~~~~~~~~~~~~~~~~~
506 Set mac antispoof for a VF from the PF::
508 testpmd> set vf mac antispoof (port_id) (vf_id) (on|off)
513 Enable/disable MACsec offload::
515 testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
516 testpmd> set macsec offload (port_id) off
521 Configure MACsec secure connection (SC)::
523 testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi)
527 The pi argument is ignored for tx.
528 Check the NIC Datasheet for hardware limits.
533 Configure MACsec secure association (SA)::
535 testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
539 The IDX value must be 0 or 1.
540 Check the NIC Datasheet for hardware limits.
542 set broadcast mode (for VF)
543 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
545 Set broadcast mode for a VF from the PF::
547 testpmd> set vf broadcast (port_id) (vf_id) (on|off)
552 Set the VLAN strip on a port::
554 testpmd> vlan set strip (on|off) (port_id)
559 Set the VLAN strip for a queue on a port::
561 testpmd> vlan set stripq (on|off) (port_id,queue_id)
563 vlan set stripq (for VF)
564 ~~~~~~~~~~~~~~~~~~~~~~~~
566 Set VLAN strip for all queues in a pool for a VF from the PF::
568 testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
570 vlan set insert (for VF)
571 ~~~~~~~~~~~~~~~~~~~~~~~~
573 Set VLAN insert for a VF from the PF::
575 testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
577 vlan set antispoof (for VF)
578 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
580 Set VLAN antispoof for a VF from the PF::
582 testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
587 Set the VLAN filter on a port::
589 testpmd> vlan set filter (on|off) (port_id)
594 Set the VLAN QinQ (extended queue in queue) on for a port::
596 testpmd> vlan set qinq (on|off) (port_id)
601 Set the inner or outer VLAN TPID for packet filtering on a port::
603 testpmd> vlan set (inner|outer) tpid (value) (port_id)
607 TPID value must be a 16-bit number (value <= 65536).
612 Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
614 testpmd> rx_vlan add (vlan_id|all) (port_id)
618 VLAN filter must be set on that port. VLAN ID < 4096.
619 Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
620 in VFTA table. This is important if enabling all vlan_ids.
625 Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
627 testpmd> rx_vlan rm (vlan_id|all) (port_id)
632 Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
634 testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
639 Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
641 testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
646 Add a tunnel filter on a port::
648 testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \
649 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
650 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
652 The available information categories are:
654 * ``vxlan``: Set tunnel type as VXLAN.
656 * ``nvgre``: Set tunnel type as NVGRE.
658 * ``ipingre``: Set tunnel type as IP-in-GRE.
660 * ``imac-ivlan``: Set filter type as Inner MAC and VLAN.
662 * ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID.
664 * ``imac-tenid``: Set filter type as Inner MAC and tenant ID.
666 * ``imac``: Set filter type as Inner MAC.
668 * ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID.
670 * ``oip``: Set filter type as Outer IP.
672 * ``iip``: Set filter type as Inner IP.
676 testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \
677 192.168.2.2 0 ipingre oip 1 1
679 Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP.
684 Remove a tunnel filter on a port::
686 testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \
687 (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
688 imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
693 Add an UDP port for VXLAN packet filter on a port::
695 testpmd> rx_vxlan_port add (udp_port) (port_id)
700 Remove an UDP port for VXLAN packet filter on a port::
702 testpmd> rx_vxlan_port rm (udp_port) (port_id)
707 Set hardware insertion of VLAN IDs in packets sent on a port::
709 testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
711 For example, set a single VLAN ID (5) insertion on port 0::
715 Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
723 Set port based hardware insertion of VLAN ID in packets sent on a port::
725 testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
730 Disable hardware insertion of a VLAN header in packets sent on a port::
732 testpmd> tx_vlan reset (port_id)
737 Select hardware or software calculation of the checksum when
738 transmitting a packet using the ``csum`` forwarding engine::
740 testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)
744 * ``ip|udp|tcp|sctp`` always relate to the inner layer.
746 * ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
747 as a tunnel packet by the forwarding engine (vxlan, gre and ipip are
748 supported). See also the ``csum parse-tunnel`` command.
752 Check the NIC Datasheet for hardware limits.
757 Define how tunneled packets should be handled by the csum forward
760 testpmd> csum parse-tunnel (on|off) (tx_port_id)
762 If enabled, the csum forward engine will try to recognize supported
763 tunnel headers (vxlan, gre, ipip).
765 If disabled, treat tunnel packets as non-tunneled packets (a inner
766 header is handled as a packet payload).
770 The port argument is the TX port like in the ``csum set`` command.
774 Consider a packet in packet like the following::
776 eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
778 * If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
779 command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
780 ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``).
782 * If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
783 command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
788 Display tx checksum offload configuration::
790 testpmd> csum show (port_id)
795 Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
797 testpmd> tso set (segsize) (port_id)
801 Check the NIC datasheet for hardware limits.
806 Display the status of TCP Segmentation Offload::
808 testpmd> tso show (port_id)
813 Add an alternative MAC address to a port::
815 testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
820 Remove a MAC address from a port::
822 testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
824 mac_addr add (for VF)
825 ~~~~~~~~~~~~~~~~~~~~~
827 Add an alternative MAC address for a VF to a port::
829 testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
831 mac_addr set (for VF)
832 ~~~~~~~~~~~~~~~~~~~~~
834 Set the MAC address for a VF from the PF::
836 testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
841 Set the unicast hash filter(s) on/off for a port::
843 testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
848 Set the promiscuous mode on for a port or for all ports.
849 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
851 testpmd> set promisc (port_id|all) (on|off)
856 Set the allmulti mode for a port or for all ports::
858 testpmd> set allmulti (port_id|all) (on|off)
860 Same as the ifconfig (8) option. Controls how multicast packets are handled.
865 Set the unicast promiscuous mode for a VF from PF.
866 It's supported by Intel i40e NICs now.
867 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
869 testpmd> set vf promisc (port_id) (vf_id) (on|off)
871 set allmulticast (for VF)
872 ~~~~~~~~~~~~~~~~~~~~~~~~~
874 Set the multicast promiscuous mode for a VF from PF.
875 It's supported by Intel i40e NICs now.
876 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
878 testpmd> set vf allmulti (port_id) (vf_id) (on|off)
883 Set the link flow control parameter on a port::
885 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
886 (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
887 autoneg (on|off) (port_id)
891 * ``high_water`` (integer): High threshold value to trigger XOFF.
893 * ``low_water`` (integer): Low threshold value to trigger XON.
895 * ``pause_time`` (integer): Pause quota in the Pause frame.
897 * ``send_xon`` (0/1): Send XON frame.
899 * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
901 * ``autoneg``: Change the auto-negotiation parameter.
906 Set the priority flow control parameter on a port::
908 testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
909 (pause_time) (priority) (port_id)
913 * ``high_water`` (integer): High threshold value.
915 * ``low_water`` (integer): Low threshold value.
917 * ``pause_time`` (integer): Pause quota in the Pause frame.
919 * ``priority`` (0-7): VLAN User Priority.
924 Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
926 testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
928 For example, to set rx queue 2 on port 0 to mapping 5::
930 testpmd>set stat_qmap rx 0 2 5
932 set port - rx/tx (for VF)
933 ~~~~~~~~~~~~~~~~~~~~~~~~~
935 Set VF receive/transmit from a port::
937 testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
939 set port - mac address filter (for VF)
940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
942 Add/Remove unicast or multicast MAC addr filter for a VF::
944 testpmd> set port (port_id) vf (vf_id) (mac_addr) \
945 (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off)
947 set port - rx mode(for VF)
948 ~~~~~~~~~~~~~~~~~~~~~~~~~~
950 Set the VF receive mode of a port::
952 testpmd> set port (port_id) vf (vf_id) \
953 rxmode (AUPE|ROPE|BAM|MPE) (on|off)
955 The available receive modes are:
957 * ``AUPE``: Accepts untagged VLAN.
959 * ``ROPE``: Accepts unicast hash.
961 * ``BAM``: Accepts broadcast packets.
963 * ``MPE``: Accepts all multicast packets.
965 set port - tx_rate (for Queue)
966 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
968 Set TX rate limitation for a queue on a port::
970 testpmd> set port (port_id) queue (queue_id) rate (rate_value)
972 set port - tx_rate (for VF)
973 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
975 Set TX rate limitation for queues in VF on a port::
977 testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
979 set port - mirror rule
980 ~~~~~~~~~~~~~~~~~~~~~~
982 Set pool or vlan type mirror rule for a port::
984 testpmd> set port (port_id) mirror-rule (rule_id) \
985 (pool-mirror-up|pool-mirror-down|vlan-mirror) \
986 (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off)
988 Set link mirror rule for a port::
990 testpmd> set port (port_id) mirror-rule (rule_id) \
991 (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off)
993 For example to enable mirror traffic with vlan 0,1 to pool 0::
995 set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on
997 reset port - mirror rule
998 ~~~~~~~~~~~~~~~~~~~~~~~~
1000 Reset a mirror rule for a port::
1002 testpmd> reset port (port_id) mirror-rule (rule_id)
1007 Set the flush on RX streams before forwarding.
1008 The default is flush ``on``.
1009 Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
1011 testpmd> set flush_rx off
1016 Set the bypass mode for the lowest port on bypass enabled NIC::
1018 testpmd> set bypass mode (normal|bypass|isolate) (port_id)
1023 Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
1025 testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
1026 mode (normal|bypass|isolate) (port_id)
1030 * ``timeout``: Enable bypass after watchdog timeout.
1032 * ``os_on``: Enable bypass when OS/board is powered on.
1034 * ``os_off``: Enable bypass when OS/board is powered off.
1036 * ``power_on``: Enable bypass when power supply is turned on.
1038 * ``power_off``: Enable bypass when power supply is turned off.
1044 Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
1046 testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
1051 Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
1053 testpmd> show bypass config (port_id)
1058 Set link up for a port::
1060 testpmd> set link-up port (port id)
1065 Set link down for a port::
1067 testpmd> set link-down port (port id)
1072 Enable E-tag insertion for a VF on a port::
1074 testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1076 Disable E-tag insertion for a VF on a port::
1078 testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1080 Enable/disable E-tag stripping on a port::
1082 testpmd> E-tag set stripping (on|off) port (port_id)
1084 Enable/disable E-tag based forwarding on a port::
1086 testpmd> E-tag set forwarding (on|off) port (port_id)
1088 Add an E-tag forwarding filter on a port::
1090 testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id)
1092 Delete an E-tag forwarding filter on a port::
1093 testpmd> E-tag set filter del e-tag-id (value) port (port_id)
1099 The following sections show functions for configuring ports.
1103 Port configuration changes only become active when forwarding is started/restarted.
1108 Attach a port specified by pci address or virtual device args::
1110 testpmd> port attach (identifier)
1112 To attach a new pci device, the device should be recognized by kernel first.
1113 Then it should be moved under DPDK management.
1114 Finally the port can be attached to testpmd.
1116 For example, to move a pci device using ixgbe under DPDK management:
1118 .. code-block:: console
1120 # Check the status of the available devices.
1121 ./usertools/dpdk-devbind.py --status
1123 Network devices using DPDK-compatible driver
1124 ============================================
1127 Network devices using kernel driver
1128 ===================================
1129 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
1132 # Bind the device to igb_uio.
1133 sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
1136 # Recheck the status of the devices.
1137 ./usertools/dpdk-devbind.py --status
1138 Network devices using DPDK-compatible driver
1139 ============================================
1140 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
1142 To attach a port created by virtual device, above steps are not needed.
1144 For example, to attach a port whose pci address is 0000:0a:00.0.
1146 .. code-block:: console
1148 testpmd> port attach 0000:0a:00.0
1149 Attaching a new port...
1150 EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1151 EAL: probe driver: 8086:10fb rte_ixgbe_pmd
1152 EAL: PCI memory mapped at 0x7f83bfa00000
1153 EAL: PCI memory mapped at 0x7f83bfa80000
1154 PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
1155 PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
1156 Port 0 is attached. Now total ports is 1
1159 For example, to attach a port created by pcap PMD.
1161 .. code-block:: console
1163 testpmd> port attach net_pcap0
1164 Attaching a new port...
1165 PMD: Initializing pmd_pcap for net_pcap0
1166 PMD: Creating pcap-backed ethdev on numa socket 0
1167 Port 0 is attached. Now total ports is 1
1170 In this case, identifier is ``net_pcap0``.
1171 This identifier format is the same as ``--vdev`` format of DPDK applications.
1173 For example, to re-attach a bonded port which has been previously detached,
1174 the mode and slave parameters must be given.
1176 .. code-block:: console
1178 testpmd> port attach net_bond_0,mode=0,slave=1
1179 Attaching a new port...
1180 EAL: Initializing pmd_bond for net_bond_0
1181 EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
1182 Port 0 is attached. Now total ports is 1
1189 Detach a specific port::
1191 testpmd> port detach (port_id)
1193 Before detaching a port, the port should be stopped and closed.
1195 For example, to detach a pci device port 0.
1197 .. code-block:: console
1199 testpmd> port stop 0
1202 testpmd> port close 0
1206 testpmd> port detach 0
1208 EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1209 EAL: remove driver: 8086:10fb rte_ixgbe_pmd
1210 EAL: PCI memory unmapped at 0x7f83bfa00000
1211 EAL: PCI memory unmapped at 0x7f83bfa80000
1215 For example, to detach a virtual device port 0.
1217 .. code-block:: console
1219 testpmd> port stop 0
1222 testpmd> port close 0
1226 testpmd> port detach 0
1228 PMD: Closing pcap ethdev on numa socket 0
1229 Port 'net_pcap0' is detached. Now total ports is 0
1232 To remove a pci device completely from the system, first detach the port from testpmd.
1233 Then the device should be moved under kernel management.
1234 Finally the device can be removed using kernel pci hotplug functionality.
1236 For example, to move a pci device under kernel management:
1238 .. code-block:: console
1240 sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
1242 ./usertools/dpdk-devbind.py --status
1244 Network devices using DPDK-compatible driver
1245 ============================================
1248 Network devices using kernel driver
1249 ===================================
1250 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
1252 To remove a port created by a virtual device, above steps are not needed.
1257 Start all ports or a specific port::
1259 testpmd> port start (port_id|all)
1264 Stop all ports or a specific port::
1266 testpmd> port stop (port_id|all)
1271 Close all ports or a specific port::
1273 testpmd> port close (port_id|all)
1275 port start/stop queue
1276 ~~~~~~~~~~~~~~~~~~~~~
1278 Start/stop a rx/tx queue on a specific port::
1280 testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
1282 Only take effect when port is started.
1287 Set the speed and duplex mode for all ports or a specific port::
1289 testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \
1290 duplex (half|full|auto)
1292 port config - queues/descriptors
1293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1295 Set number of queues/descriptors for rxq, txq, rxd and txd::
1297 testpmd> port config all (rxq|txq|rxd|txd) (value)
1299 This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
1301 port config - max-pkt-len
1302 ~~~~~~~~~~~~~~~~~~~~~~~~~
1304 Set the maximum packet length::
1306 testpmd> port config all max-pkt-len (value)
1308 This is equivalent to the ``--max-pkt-len`` command-line option.
1310 port config - CRC Strip
1311 ~~~~~~~~~~~~~~~~~~~~~~~
1313 Set hardware CRC stripping on or off for all ports::
1315 testpmd> port config all crc-strip (on|off)
1317 CRC stripping is off by default.
1319 The ``on`` option is equivalent to the ``--crc-strip`` command-line option.
1321 port config - scatter
1322 ~~~~~~~~~~~~~~~~~~~~~~~
1324 Set RX scatter mode on or off for all ports::
1326 testpmd> port config all scatter (on|off)
1328 RX scatter mode is off by default.
1330 The ``on`` option is equivalent to the ``--enable-scatter`` command-line option.
1332 port config - TX queue flags
1333 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1335 Set a hexadecimal bitmap of TX queue flags for all ports::
1337 testpmd> port config all txqflags value
1339 This command is equivalent to the ``--txqflags`` command-line option.
1341 port config - RX Checksum
1342 ~~~~~~~~~~~~~~~~~~~~~~~~~
1344 Set hardware RX checksum offload to on or off for all ports::
1346 testpmd> port config all rx-cksum (on|off)
1348 Checksum offload is off by default.
1350 The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option.
1355 Set hardware VLAN on or off for all ports::
1357 testpmd> port config all hw-vlan (on|off)
1359 Hardware VLAN is on by default.
1361 The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option.
1363 port config - VLAN filter
1364 ~~~~~~~~~~~~~~~~~~~~~~~~~
1366 Set hardware VLAN filter on or off for all ports::
1368 testpmd> port config all hw-vlan-filter (on|off)
1370 Hardware VLAN filter is on by default.
1372 The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option.
1374 port config - VLAN strip
1375 ~~~~~~~~~~~~~~~~~~~~~~~~
1377 Set hardware VLAN strip on or off for all ports::
1379 testpmd> port config all hw-vlan-strip (on|off)
1381 Hardware VLAN strip is on by default.
1383 The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option.
1385 port config - VLAN extend
1386 ~~~~~~~~~~~~~~~~~~~~~~~~~
1388 Set hardware VLAN extend on or off for all ports::
1390 testpmd> port config all hw-vlan-extend (on|off)
1392 Hardware VLAN extend is off by default.
1394 The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option.
1396 port config - Drop Packets
1397 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1399 Set packet drop for packets with no descriptors on or off for all ports::
1401 testpmd> port config all drop-en (on|off)
1403 Packet dropping for packets with no descriptors is off by default.
1405 The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
1410 Set the RSS (Receive Side Scaling) mode on or off::
1412 testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none)
1414 RSS is on by default.
1416 The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
1418 port config - RSS Reta
1419 ~~~~~~~~~~~~~~~~~~~~~~
1421 Set the RSS (Receive Side Scaling) redirection table::
1423 testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
1428 Set the DCB mode for an individual port::
1430 testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
1432 The traffic class should be 4 or 8.
1437 Set the number of packets per burst::
1439 testpmd> port config all burst (value)
1441 This is equivalent to the ``--burst`` command-line option.
1443 port config - Threshold
1444 ~~~~~~~~~~~~~~~~~~~~~~~
1446 Set thresholds for TX/RX queues::
1448 testpmd> port config all (threshold) (value)
1450 Where the threshold type can be:
1452 * ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
1454 * ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
1456 * ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
1458 * ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
1460 * ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
1462 * ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
1464 * ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
1466 * ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
1468 * ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
1470 These threshold options are also available from the command-line.
1475 Set the value of ether-type for E-tag::
1477 testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value)
1479 Enable/disable the E-tag support::
1481 testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable)
1484 Link Bonding Functions
1485 ----------------------
1487 The Link Bonding functions make it possible to dynamically create and
1488 manage link bonding devices from within testpmd interactive prompt.
1490 create bonded device
1491 ~~~~~~~~~~~~~~~~~~~~
1493 Create a new bonding device::
1495 testpmd> create bonded device (mode) (socket)
1497 For example, to create a bonded device in mode 1 on socket 0::
1499 testpmd> create bonded 1 0
1500 created new bonded device (port X)
1505 Adds Ethernet device to a Link Bonding device::
1507 testpmd> add bonding slave (slave id) (port id)
1509 For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
1511 testpmd> add bonding slave 6 10
1514 remove bonding slave
1515 ~~~~~~~~~~~~~~~~~~~~
1517 Removes an Ethernet slave device from a Link Bonding device::
1519 testpmd> remove bonding slave (slave id) (port id)
1521 For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
1523 testpmd> remove bonding slave 6 10
1528 Set the Link Bonding mode of a Link Bonding device::
1530 testpmd> set bonding mode (value) (port id)
1532 For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
1534 testpmd> set bonding mode 3 10
1539 Set an Ethernet slave device as the primary device on a Link Bonding device::
1541 testpmd> set bonding primary (slave id) (port id)
1543 For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
1545 testpmd> set bonding primary 6 10
1550 Set the MAC address of a Link Bonding device::
1552 testpmd> set bonding mac (port id) (mac)
1554 For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
1556 testpmd> set bonding mac 10 00:00:00:00:00:01
1558 set bonding xmit_balance_policy
1559 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1561 Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
1563 testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34)
1565 For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
1567 testpmd> set bonding xmit_balance_policy 10 l34
1570 set bonding mon_period
1571 ~~~~~~~~~~~~~~~~~~~~~~
1573 Set the link status monitoring polling period in milliseconds for a bonding device.
1575 This adds support for PMD slave devices which do not support link status interrupts.
1576 When the mon_period is set to a value greater than 0 then all PMD's which do not support
1577 link status ISR will be queried every polling interval to check if their link status has changed::
1579 testpmd> set bonding mon_period (port_id) (value)
1581 For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
1583 testpmd> set bonding mon_period 5 150
1589 Show the current configuration of a Link Bonding device::
1591 testpmd> show bonding config (port id)
1594 to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
1595 in balance mode with a transmission policy of layer 2+3::
1597 testpmd> show bonding config 9
1599 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
1601 Active Slaves (3): [1 3 4]
1608 The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
1609 This is mainly useful for debugging purposes.
1610 Reference should be made to the appropriate datasheet for the network card for details on the register addresses
1611 and fields that can be accessed.
1616 Display the value of a port register::
1618 testpmd> read reg (port_id) (address)
1620 For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
1622 testpmd> read reg 0 0xEE00
1623 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
1628 Display a port register bit field::
1630 testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
1632 For example, reading the lowest two bits from the register in the example above::
1634 testpmd> read regfield 0 0xEE00 0 1
1635 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
1640 Display a single port register bit::
1642 testpmd> read regbit (port_id) (address) (bit_x)
1644 For example, reading the lowest bit from the register in the example above::
1646 testpmd> read regbit 0 0xEE00 0
1647 port 0 PCI register at offset 0xEE00: bit 0=1
1652 Set the value of a port register::
1654 testpmd> write reg (port_id) (address) (value)
1656 For example, to clear a register::
1658 testpmd> write reg 0 0xEE00 0x0
1659 port 0 PCI register at offset 0xEE00: 0x00000000 (0)
1664 Set bit field of a port register::
1666 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
1668 For example, writing to the register cleared in the example above::
1670 testpmd> write regfield 0 0xEE00 0 1 2
1671 port 0 PCI register at offset 0xEE00: 0x00000002 (2)
1676 Set single bit value of a port register::
1678 testpmd> write regbit (port_id) (address) (bit_x) (value)
1680 For example, to set the high bit in the register from the example above::
1682 testpmd> write regbit 0 0xEE00 31 1
1683 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
1689 This section details the available filter functions that are available.
1691 Note these functions interface the deprecated legacy filtering framework,
1692 superseded by *rte_flow*. See `Flow rules management`_.
1695 ~~~~~~~~~~~~~~~~~~~~
1697 Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue::
1699 ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \
1700 ethertype (ether_type) (drop|fwd) queue (queue_id)
1702 The available information parameters are:
1704 * ``port_id``: The port which the Ethertype filter assigned on.
1706 * ``mac_addr``: Compare destination mac address.
1708 * ``mac_ignr``: Ignore destination mac address match.
1710 * ``mac_address``: Destination mac address to match.
1712 * ``ether_type``: The EtherType value want to match,
1713 for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid.
1715 * ``queue_id``: The receive queue associated with this EtherType filter.
1716 It is meaningless when deleting or dropping.
1718 Example, to add/remove an ethertype filter rule::
1720 testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \
1721 ethertype 0x0806 fwd queue 3
1723 testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \
1724 ethertype 0x0806 fwd queue 3
1729 Add or delete a 2-tuple filter,
1730 which identifies packets by specific protocol and destination TCP/UDP port
1731 and forwards packets into one of the receive queues::
1733 2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \
1734 protocol (protocol_value) mask (mask_value) \
1735 tcp_flags (tcp_flags_value) priority (prio_value) \
1738 The available information parameters are:
1740 * ``port_id``: The port which the 2-tuple filter assigned on.
1742 * ``dst_port_value``: Destination port in L4.
1744 * ``protocol_value``: IP L4 protocol.
1746 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate.
1748 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP).
1750 * ``prio_value``: Priority of this filter.
1752 * ``queue_id``: The receive queue associated with this 2-tuple filter.
1754 Example, to add/remove an 2tuple filter rule::
1756 testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \
1757 tcp_flags 0x02 priority 3 queue 3
1759 testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \
1760 tcp_flags 0x02 priority 3 queue 3
1765 Add or delete a 5-tuple filter,
1766 which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port)
1767 and routes packets into one of the receive queues::
1769 5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \
1770 (src_address) dst_port (dst_port_value) \
1771 src_port (src_port_value) protocol (protocol_value) \
1772 mask (mask_value) tcp_flags (tcp_flags_value) \
1773 priority (prio_value) queue (queue_id)
1775 The available information parameters are:
1777 * ``port_id``: The port which the 5-tuple filter assigned on.
1779 * ``dst_address``: Destination IP address.
1781 * ``src_address``: Source IP address.
1783 * ``dst_port_value``: TCP/UDP destination port.
1785 * ``src_port_value``: TCP/UDP source port.
1787 * ``protocol_value``: L4 protocol.
1789 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate
1791 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP).
1793 * ``prio_value``: The priority of this filter.
1795 * ``queue_id``: The receive queue associated with this 5-tuple filter.
1797 Example, to add/remove an 5tuple filter rule::
1799 testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1800 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1801 flags 0x0 priority 3 queue 3
1803 testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1804 dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1805 flags 0x0 priority 3 queue 3
1810 Using the SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue::
1812 syn_filter (port_id) (add|del) priority (high|low) queue (queue_id)
1814 The available information parameters are:
1816 * ``port_id``: The port which the SYN filter assigned on.
1818 * ``high``: This SYN filter has higher priority than other filters.
1820 * ``low``: This SYN filter has lower priority than other filters.
1822 * ``queue_id``: The receive queue associated with this SYN filter
1826 testpmd> syn_filter 0 add priority high queue 3
1831 With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet
1832 and routed into one of the receive queues::
1834 flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \
1835 mask (mask_value) priority (prio_value) queue (queue_id)
1837 The available information parameters are:
1839 * ``port_id``: The port which the Flex filter is assigned on.
1841 * ``len_value``: Filter length in bytes, no greater than 128.
1843 * ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match.
1845 * ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match.
1847 * ``prio_value``: The priority of this filter.
1849 * ``queue_id``: The receive queue associated with this Flex filter.
1853 testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \
1854 mask 000C priority 3 queue 3
1856 testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \
1857 mask 000C priority 3 queue 3
1860 .. _testpmd_flow_director:
1862 flow_director_filter
1863 ~~~~~~~~~~~~~~~~~~~~
1865 The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues.
1867 Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and
1868 Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter:
1870 * Perfect match filters.
1871 The hardware checks a match between the masked fields of the received packets and the programmed filters.
1872 The masked fields are for IP flow.
1874 * Signature filters.
1875 The hardware checks a match between a hash-based signature of the masked fields of the received packet.
1877 * Perfect-mac-vlan match filters.
1878 The hardware checks a match between the masked fields of the received packets and the programmed filters.
1879 The masked fields are for MAC VLAN flow.
1881 * Perfect-tunnel match filters.
1882 The hardware checks a match between the masked fields of the received packets and the programmed filters.
1883 The masked fields are for tunnel flow.
1885 The Flow Director filters can match the different fields for different type of packet: flow type, specific input set
1886 per flow type and the flexible payload.
1888 The Flow Director can also mask out parts of all of these fields so that filters
1889 are only applied to certain fields or parts of the fields.
1891 Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information.
1893 # Commands to add flow director filters of different flow types::
1895 flow_director_filter (port_id) mode IP (add|del|update) \
1896 flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \
1897 src (src_ip_address) dst (dst_ip_address) \
1898 tos (tos_value) proto (proto_value) ttl (ttl_value) \
1899 vlan (vlan_value) flexbytes (flexbytes_value) \
1900 (drop|fwd) pf|vf(vf_id) queue (queue_id) \
1903 flow_director_filter (port_id) mode IP (add|del|update) \
1904 flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \
1905 src (src_ip_address) (src_port) \
1906 dst (dst_ip_address) (dst_port) \
1907 tos (tos_value) ttl (ttl_value) \
1908 vlan (vlan_value) flexbytes (flexbytes_value) \
1909 (drop|fwd) queue pf|vf(vf_id) (queue_id) \
1912 flow_director_filter (port_id) mode IP (add|del|update) \
1913 flow (ipv4-sctp|ipv6-sctp) \
1914 src (src_ip_address) (src_port) \
1915 dst (dst_ip_address) (dst_port) \
1916 tos (tos_value) ttl (ttl_value) \
1917 tag (verification_tag) vlan (vlan_value) \
1918 flexbytes (flexbytes_value) (drop|fwd) \
1919 pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value)
1921 flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \
1922 ether (ethertype) flexbytes (flexbytes_value) \
1923 (drop|fwd) pf|vf(vf_id) queue (queue_id)
1926 flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \
1927 mac (mac_address) vlan (vlan_value) \
1928 flexbytes (flexbytes_value) (drop|fwd) \
1929 queue (queue_id) fd_id (fd_id_value)
1931 flow_director_filter (port_id) mode Tunnel (add|del|update) \
1932 mac (mac_address) vlan (vlan_value) \
1933 tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \
1934 flexbytes (flexbytes_value) (drop|fwd) \
1935 queue (queue_id) fd_id (fd_id_value)
1937 For example, to add an ipv4-udp flow type filter::
1939 testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \
1940 dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \
1941 fwd pf queue 1 fd_id 1
1943 For example, add an ipv4-other flow type filter::
1945 testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \
1946 dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \
1947 flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1
1952 Flush all flow director filters on a device::
1954 testpmd> flush_flow_director (port_id)
1956 Example, to flush all flow director filter on port 0::
1958 testpmd> flush_flow_director 0
1963 Set flow director's input masks::
1965 flow_director_mask (port_id) mode IP vlan (vlan_value) \
1966 src_mask (ipv4_src) (ipv6_src) (src_port) \
1967 dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
1969 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
1971 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
1972 mac (mac_value) tunnel-type (tunnel_type_value) \
1973 tunnel-id (tunnel_id_value)
1975 Example, to set flow director mask on port 0::
1977 testpmd> flow_director_mask 0 mode IP vlan 0xefff \
1978 src_mask 255.255.255.255 \
1979 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
1980 dst_mask 255.255.255.255 \
1981 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
1983 flow_director_flex_mask
1984 ~~~~~~~~~~~~~~~~~~~~~~~
1986 set masks of flow director's flexible payload based on certain flow type::
1988 testpmd> flow_director_flex_mask (port_id) \
1989 flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
1990 ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \
1991 l2_payload|all) (mask)
1993 Example, to set flow director's flex mask for all flow type on port 0::
1995 testpmd> flow_director_flex_mask 0 flow all \
1996 (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0)
1999 flow_director_flex_payload
2000 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2002 Configure flexible payload selection::
2004 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
2006 For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
2008 testpmd> flow_director_flex_payload 0 l4 \
2009 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
2011 get_sym_hash_ena_per_port
2012 ~~~~~~~~~~~~~~~~~~~~~~~~~
2014 Get symmetric hash enable configuration per port::
2016 get_sym_hash_ena_per_port (port_id)
2018 For example, to get symmetric hash enable configuration of port 1::
2020 testpmd> get_sym_hash_ena_per_port 1
2022 set_sym_hash_ena_per_port
2023 ~~~~~~~~~~~~~~~~~~~~~~~~~
2025 Set symmetric hash enable configuration per port to enable or disable::
2027 set_sym_hash_ena_per_port (port_id) (enable|disable)
2029 For example, to set symmetric hash enable configuration of port 1 to enable::
2031 testpmd> set_sym_hash_ena_per_port 1 enable
2033 get_hash_global_config
2034 ~~~~~~~~~~~~~~~~~~~~~~
2036 Get the global configurations of hash filters::
2038 get_hash_global_config (port_id)
2040 For example, to get the global configurations of hash filters of port 1::
2042 testpmd> get_hash_global_config 1
2044 set_hash_global_config
2045 ~~~~~~~~~~~~~~~~~~~~~~
2047 Set the global configurations of hash filters::
2049 set_hash_global_config (port_id) (toeplitz|simple_xor|default) \
2050 (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \
2051 ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \
2054 For example, to enable simple_xor for flow type of ipv6 on port 2::
2056 testpmd> set_hash_global_config 2 simple_xor ipv6 enable
2061 Set the input set for hash::
2063 set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2064 ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2065 l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2066 ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \
2067 tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \
2068 udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \
2069 fld-8th|none) (select|add)
2071 For example, to add source IP to hash input set for flow type of ipv4-udp on port 0::
2073 testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add
2078 The Flow Director filters can match the different fields for different type of packet, i.e. specific input set
2079 on per flow type and the flexible payload. This command can be used to change input set for each flow type.
2081 Set the input set for flow director::
2083 set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2084 ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2085 l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2086 ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \
2087 tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \
2088 sctp-dst-port|sctp-veri-tag|none) (select|add)
2090 For example to add source IP to FD input set for flow type of ipv4-udp on port 0::
2092 testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add
2097 Set different GRE key length for input set::
2099 global_config (port_id) gre-key-len (number in bytes)
2101 For example to set GRE key length for input set to 4 bytes on port 0::
2103 testpmd> global_config 0 gre-key-len 4
2106 .. _testpmd_rte_flow:
2108 Flow rules management
2109 ---------------------
2111 Control of the generic flow API (*rte_flow*) is fully exposed through the
2112 ``flow`` command (validation, creation, destruction and queries).
2114 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
2115 features simultaneously may cause undefined side-effects and is therefore
2121 Because the ``flow`` command uses dynamic tokens to handle the large number
2122 of possible flow rules combinations, its behavior differs slightly from
2123 other commands, in particular:
2125 - Pressing *?* or the *<tab>* key displays contextual help for the current
2126 token, not that of the entire command.
2128 - Optional and repeated parameters are supported (provided they are listed
2129 in the contextual help).
2131 The first parameter stands for the operation mode. Possible operations and
2132 their general syntax are described below. They are covered in detail in the
2135 - Check whether a flow rule can be created::
2137 flow validate {port_id}
2138 [group {group_id}] [priority {level}] [ingress] [egress]
2139 pattern {item} [/ {item} [...]] / end
2140 actions {action} [/ {action} [...]] / end
2142 - Create a flow rule::
2144 flow create {port_id}
2145 [group {group_id}] [priority {level}] [ingress] [egress]
2146 pattern {item} [/ {item} [...]] / end
2147 actions {action} [/ {action} [...]] / end
2149 - Destroy specific flow rules::
2151 flow destroy {port_id} rule {rule_id} [...]
2153 - Destroy all flow rules::
2155 flow flush {port_id}
2157 - Query an existing flow rule::
2159 flow query {port_id} {rule_id} {action}
2161 - List existing flow rules sorted by priority, filtered by group
2164 flow list {port_id} [group {group_id}] [...]
2166 Validating flow rules
2167 ~~~~~~~~~~~~~~~~~~~~~
2169 ``flow validate`` reports whether a flow rule would be accepted by the
2170 underlying device in its current state but stops short of creating it. It is
2171 bound to ``rte_flow_validate()``::
2173 flow validate {port_id}
2174 [group {group_id}] [priority {level}] [ingress] [egress]
2175 pattern {item} [/ {item} [...]] / end
2176 actions {action} [/ {action} [...]] / end
2178 If successful, it will show::
2182 Otherwise it will show an error message of the form::
2184 Caught error type [...] ([...]): [...]
2186 This command uses the same parameters as ``flow create``, their format is
2187 described in `Creating flow rules`_.
2189 Check whether redirecting any Ethernet packet received on port 0 to RX queue
2190 index 6 is supported::
2192 testpmd> flow validate 0 ingress pattern eth / end
2193 actions queue index 6 / end
2197 Port 0 does not support TCPv6 rules::
2199 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
2201 Caught error type 9 (specific pattern item): Invalid argument
2207 ``flow create`` validates and creates the specified flow rule. It is bound
2208 to ``rte_flow_create()``::
2210 flow create {port_id}
2211 [group {group_id}] [priority {level}] [ingress] [egress]
2212 pattern {item} [/ {item} [...]] / end
2213 actions {action} [/ {action} [...]] / end
2215 If successful, it will return a flow rule ID usable with other commands::
2217 Flow rule #[...] created
2219 Otherwise it will show an error message of the form::
2221 Caught error type [...] ([...]): [...]
2223 Parameters describe in the following order:
2225 - Attributes (*group*, *priority*, *ingress*, *egress* tokens).
2226 - A matching pattern, starting with the *pattern* token and terminated by an
2228 - Actions, starting with the *actions* token and terminated by an *end*
2231 These translate directly to *rte_flow* objects provided as-is to the
2232 underlying functions.
2234 The shortest valid definition only comprises mandatory tokens::
2236 testpmd> flow create 0 pattern end actions end
2238 Note that PMDs may refuse rules that essentially do nothing such as this
2241 **All unspecified object values are automatically initialized to 0.**
2246 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
2247 specified before the ``pattern`` token.
2249 - ``group {group id}``: priority group.
2250 - ``priority {level}``: priority level within group.
2251 - ``ingress``: rule applies to ingress traffic.
2252 - ``egress``: rule applies to egress traffic.
2254 Each instance of an attribute specified several times overrides the previous
2255 value as shown below (group 4 is used)::
2257 testpmd> flow create 0 group 42 group 24 group 4 [...]
2259 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
2261 While not specifying a direction is an error, some rules may allow both
2264 Most rules affect RX therefore contain the ``ingress`` token::
2266 testpmd> flow create 0 ingress pattern [...]
2271 A matching pattern starts after the ``pattern`` token. It is made of pattern
2272 items and is terminated by a mandatory ``end`` item.
2274 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
2275 rte_flow_item_type``).
2277 The ``/`` token is used as a separator between pattern items as shown
2280 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
2282 Note that protocol items like these must be stacked from lowest to highest
2283 layer to make sense. For instance, the following rule is either invalid or
2284 unlikely to match any packet::
2286 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
2288 More information on these restrictions can be found in the *rte_flow*
2291 Several items support additional specification structures, for example
2292 ``ipv4`` allows specifying source and destination addresses as follows::
2294 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
2295 dst is 10.2.0.0 / end [...]
2297 This rule matches all IPv4 traffic with the specified properties.
2299 In this example, ``src`` and ``dst`` are field names of the underlying
2300 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
2301 in a similar fashion.
2303 The ``is`` token means that the subsequent value must be matched exactly,
2304 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
2305 accordingly. Possible assignment tokens are:
2307 - ``is``: match value perfectly (with full bit-mask).
2308 - ``spec``: match value according to configured bit-mask.
2309 - ``last``: specify upper bound to establish a range.
2310 - ``mask``: specify bit-mask with relevant bits set to one.
2311 - ``prefix``: generate bit-mask from a prefix length.
2313 These yield identical results::
2315 ipv4 src is 10.1.1.1
2319 ipv4 src spec 10.1.1.1 src mask 255.255.255.255
2323 ipv4 src spec 10.1.1.1 src prefix 32
2327 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
2331 ipv4 src is 10.1.1.1 src last 0 # 0 disables range
2333 Inclusive ranges can be defined with ``last``::
2335 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
2337 Note that ``mask`` affects both ``spec`` and ``last``::
2339 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
2340 # matches 10.1.0.0 to 10.2.255.255
2342 Properties can be modified multiple times::
2344 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
2348 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
2353 This section lists supported pattern items and their attributes, if any.
2355 - ``end``: end list of pattern items.
2357 - ``void``: no-op pattern item.
2359 - ``invert``: perform actions when pattern does not match.
2361 - ``any``: match any protocol for the current layer.
2363 - ``num {unsigned}``: number of layers covered.
2365 - ``pf``: match packets addressed to the physical function.
2367 - ``vf``: match packets addressed to a virtual function ID.
2369 - ``id {unsigned}``: destination VF ID.
2371 - ``port``: device-specific physical port index to use.
2373 - ``index {unsigned}``: physical port index.
2375 - ``raw``: match an arbitrary byte string.
2377 - ``relative {boolean}``: look for pattern after the previous item.
2378 - ``search {boolean}``: search pattern from offset (see also limit).
2379 - ``offset {integer}``: absolute or relative offset for pattern.
2380 - ``limit {unsigned}``: search area limit for start of pattern.
2381 - ``pattern {string}``: byte string to look for.
2383 - ``eth``: match Ethernet header.
2385 - ``dst {MAC-48}``: destination MAC.
2386 - ``src {MAC-48}``: source MAC.
2387 - ``type {unsigned}``: EtherType.
2389 - ``vlan``: match 802.1Q/ad VLAN tag.
2391 - ``tpid {unsigned}``: tag protocol identifier.
2392 - ``tci {unsigned}``: tag control information.
2393 - ``pcp {unsigned}``: priority code point.
2394 - ``dei {unsigned}``: drop eligible indicator.
2395 - ``vid {unsigned}``: VLAN identifier.
2397 - ``ipv4``: match IPv4 header.
2399 - ``tos {unsigned}``: type of service.
2400 - ``ttl {unsigned}``: time to live.
2401 - ``proto {unsigned}``: next protocol ID.
2402 - ``src {ipv4 address}``: source address.
2403 - ``dst {ipv4 address}``: destination address.
2405 - ``ipv6``: match IPv6 header.
2407 - ``tc {unsigned}``: traffic class.
2408 - ``flow {unsigned}``: flow label.
2409 - ``proto {unsigned}``: protocol (next header).
2410 - ``hop {unsigned}``: hop limit.
2411 - ``src {ipv6 address}``: source address.
2412 - ``dst {ipv6 address}``: destination address.
2414 - ``icmp``: match ICMP header.
2416 - ``type {unsigned}``: ICMP packet type.
2417 - ``code {unsigned}``: ICMP packet code.
2419 - ``udp``: match UDP header.
2421 - ``src {unsigned}``: UDP source port.
2422 - ``dst {unsigned}``: UDP destination port.
2424 - ``tcp``: match TCP header.
2426 - ``src {unsigned}``: TCP source port.
2427 - ``dst {unsigned}``: TCP destination port.
2429 - ``sctp``: match SCTP header.
2431 - ``src {unsigned}``: SCTP source port.
2432 - ``dst {unsigned}``: SCTP destination port.
2433 - ``tag {unsigned}``: validation tag.
2434 - ``cksum {unsigned}``: checksum.
2436 - ``vxlan``: match VXLAN header.
2438 - ``vni {unsigned}``: VXLAN identifier.
2443 A list of actions starts after the ``actions`` token in the same fashion as
2444 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
2445 terminated by a mandatory ``end`` action.
2447 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
2448 rte_flow_action_type``).
2450 Dropping all incoming UDPv4 packets can be expressed as follows::
2452 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2455 Several actions have configurable properties which must be specified when
2456 there is no valid default value. For example, ``queue`` requires a target
2459 This rule redirects incoming UDPv4 traffic to queue index 6::
2461 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2462 actions queue index 6 / end
2464 While this one could be rejected by PMDs (unspecified queue index)::
2466 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2469 As defined by *rte_flow*, the list is not ordered, all actions of a given
2470 rule are performed simultaneously. These are equivalent::
2472 queue index 6 / void / mark id 42 / end
2476 void / mark id 42 / queue index 6 / end
2478 All actions in a list should have different types, otherwise only the last
2479 action of a given type is taken into account::
2481 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
2485 drop / drop / drop / end # drop is performed only once
2489 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
2491 Considering they are performed simultaneously, opposite and overlapping
2492 actions can sometimes be combined when the end result is unambiguous::
2494 drop / queue index 6 / end # drop has no effect
2498 drop / dup index 6 / end # same as above
2502 queue index 6 / rss queues 6 7 8 / end # queue has no effect
2506 drop / passthru / end # drop has no effect
2508 Note that PMDs may still refuse such combinations.
2513 This section lists supported actions and their attributes, if any.
2515 - ``end``: end list of actions.
2517 - ``void``: no-op action.
2519 - ``passthru``: let subsequent rule process matched packets.
2521 - ``mark``: attach 32 bit value to packets.
2523 - ``id {unsigned}``: 32 bit value to return with packets.
2525 - ``flag``: flag packets.
2527 - ``queue``: assign packets to a given queue index.
2529 - ``index {unsigned}``: queue index to use.
2531 - ``drop``: drop packets (note: passthru has priority).
2533 - ``count``: enable counters for this rule.
2535 - ``dup``: duplicate packets to a given queue index.
2537 - ``index {unsigned}``: queue index to duplicate packets to.
2539 - ``rss``: spread packets among several queues.
2541 - ``queues [{unsigned} [...]] end``: queue indices to use.
2543 - ``pf``: redirect packets to physical device function.
2545 - ``vf``: redirect packets to virtual device function.
2547 - ``original {boolean}``: use original VF ID if possible.
2548 - ``id {unsigned}``: VF ID to redirect packets to.
2550 Destroying flow rules
2551 ~~~~~~~~~~~~~~~~~~~~~
2553 ``flow destroy`` destroys one or more rules from their rule ID (as returned
2554 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
2555 times as necessary::
2557 flow destroy {port_id} rule {rule_id} [...]
2559 If successful, it will show::
2561 Flow rule #[...] destroyed
2563 It does not report anything for rule IDs that do not exist. The usual error
2564 message is shown when a rule cannot be destroyed::
2566 Caught error type [...] ([...]): [...]
2568 ``flow flush`` destroys all rules on a device and does not take extra
2569 arguments. It is bound to ``rte_flow_flush()``::
2571 flow flush {port_id}
2573 Any errors are reported as above.
2575 Creating several rules and destroying them::
2577 testpmd> flow create 0 ingress pattern eth / ipv6 / end
2578 actions queue index 2 / end
2579 Flow rule #0 created
2580 testpmd> flow create 0 ingress pattern eth / ipv4 / end
2581 actions queue index 3 / end
2582 Flow rule #1 created
2583 testpmd> flow destroy 0 rule 0 rule 1
2584 Flow rule #1 destroyed
2585 Flow rule #0 destroyed
2588 The same result can be achieved using ``flow flush``::
2590 testpmd> flow create 0 ingress pattern eth / ipv6 / end
2591 actions queue index 2 / end
2592 Flow rule #0 created
2593 testpmd> flow create 0 ingress pattern eth / ipv4 / end
2594 actions queue index 3 / end
2595 Flow rule #1 created
2596 testpmd> flow flush 0
2599 Non-existent rule IDs are ignored::
2601 testpmd> flow create 0 ingress pattern eth / ipv6 / end
2602 actions queue index 2 / end
2603 Flow rule #0 created
2604 testpmd> flow create 0 ingress pattern eth / ipv4 / end
2605 actions queue index 3 / end
2606 Flow rule #1 created
2607 testpmd> flow destroy 0 rule 42 rule 10 rule 2
2609 testpmd> flow destroy 0 rule 0
2610 Flow rule #0 destroyed
2616 ``flow query`` queries a specific action of a flow rule having that
2617 ability. Such actions collect information that can be reported using this
2618 command. It is bound to ``rte_flow_query()``::
2620 flow query {port_id} {rule_id} {action}
2622 If successful, it will display either the retrieved data for known actions
2623 or the following message::
2625 Cannot display result for action type [...] ([...])
2627 Otherwise, it will complain either that the rule does not exist or that some
2630 Flow rule #[...] not found
2634 Caught error type [...] ([...]): [...]
2636 Currently only the ``count`` action is supported. This action reports the
2637 number of packets that hit the flow rule and the total number of bytes. Its
2638 output has the following format::
2641 hits_set: [...] # whether "hits" contains a valid value
2642 bytes_set: [...] # whether "bytes" contains a valid value
2643 hits: [...] # number of packets
2644 bytes: [...] # number of bytes
2646 Querying counters for TCPv6 packets redirected to queue 6::
2648 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
2649 actions queue index 6 / count / end
2650 Flow rule #4 created
2651 testpmd> flow query 0 4 count
2662 ``flow list`` lists existing flow rules sorted by priority and optionally
2663 filtered by group identifiers::
2665 flow list {port_id} [group {group_id}] [...]
2667 This command only fails with the following message if the device does not
2672 Output consists of a header line followed by a short description of each
2673 flow rule, one per line. There is no output at all when no flow rules are
2674 configured on the device::
2676 ID Group Prio Attr Rule
2677 [...] [...] [...] [...] [...]
2679 ``Attr`` column flags:
2681 - ``i`` for ``ingress``.
2682 - ``e`` for ``egress``.
2684 Creating several flow rules and listing them::
2686 testpmd> flow create 0 ingress pattern eth / ipv4 / end
2687 actions queue index 6 / end
2688 Flow rule #0 created
2689 testpmd> flow create 0 ingress pattern eth / ipv6 / end
2690 actions queue index 2 / end
2691 Flow rule #1 created
2692 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
2693 actions rss queues 6 7 8 end / end
2694 Flow rule #2 created
2695 testpmd> flow list 0
2696 ID Group Prio Attr Rule
2697 0 0 0 i- ETH IPV4 => QUEUE
2698 1 0 0 i- ETH IPV6 => QUEUE
2699 2 0 5 i- ETH IPV4 UDP => RSS
2702 Rules are sorted by priority (i.e. group ID first, then priority level)::
2704 testpmd> flow list 1
2705 ID Group Prio Attr Rule
2706 0 0 0 i- ETH => COUNT
2707 6 0 500 i- ETH IPV6 TCP => DROP COUNT
2708 5 0 1000 i- ETH IPV6 ICMP => QUEUE
2709 1 24 0 i- ETH IPV4 UDP => QUEUE
2710 4 24 10 i- ETH IPV4 TCP => DROP
2711 3 24 20 i- ETH IPV4 => DROP
2712 2 24 42 i- ETH IPV4 UDP => QUEUE
2713 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE
2716 Output can be limited to specific groups::
2718 testpmd> flow list 1 group 0 group 63
2719 ID Group Prio Attr Rule
2720 0 0 0 i- ETH => COUNT
2721 6 0 500 i- ETH IPV6 TCP => DROP COUNT
2722 5 0 1000 i- ETH IPV6 ICMP => QUEUE
2723 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE