1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2016 Intel Corporation.
6 Testpmd Runtime Functions
7 =========================
9 Where the testpmd application is started in interactive mode, (``-i|--interactive``),
10 it displays a prompt that can be used to start and stop forwarding,
11 configure the application, display statistics (including the extended NIC
12 statistics aka xstats) , set the Flow Director and other tasks::
16 The testpmd prompt has some, limited, readline support.
17 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
18 as well as access to the command history via the up-arrow.
20 There is also support for tab completion.
21 If you type a partial command and hit ``<TAB>`` you get a list of the available completions:
23 .. code-block:: console
25 testpmd> show port <TAB>
27 info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap X
28 info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap all
29 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap X
30 stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap all
36 Some examples in this document are too long to fit on one line are shown wrapped at `"\\"` for display purposes::
38 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
39 (pause_time) (send_xon) (port_id)
41 In the real ``testpmd>`` prompt these commands should be on a single line.
46 The testpmd has on-line help for the functions that are available at runtime.
47 These are divided into sections and can be accessed using help, help section or help all:
49 .. code-block:: console
52 Help is available for the following sections:
54 help control : Start and stop forwarding.
55 help display : Displaying port, stats and config information.
56 help config : Configuration information.
57 help ports : Configuring ports.
58 help registers : Reading and setting port registers.
59 help filters : Filters configuration help.
60 help traffic_management : Traffic Management commands.
61 help devices : Device related commands.
62 help drivers : Driver specific commands.
63 help all : All of the above sections.
65 Command File Functions
66 ----------------------
68 To facilitate loading large number of commands or to avoid cutting and pasting where not
69 practical or possible testpmd supports alternative methods for executing commands.
71 * If started with the ``--cmdline-file=FILENAME`` command line argument testpmd
72 will execute all CLI commands contained within the file immediately before
73 starting packet forwarding or entering interactive mode.
75 .. code-block:: console
77 ./dpdk-testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt
78 Interactive-mode selected
79 CLI commands to be read from /home/ubuntu/flow-create-commands.txt
80 Configuring Port 0 (socket 0)
81 Port 0: 7C:FE:90:CB:74:CE
82 Configuring Port 1 (socket 0)
83 Port 1: 7C:FE:90:CB:74:CA
84 Checking link statuses...
85 Port 0 Link Up - speed 10000 Mbps - full-duplex
86 Port 1 Link Up - speed 10000 Mbps - full-duplex
92 Flow rule #498 created
93 Flow rule #499 created
94 Read all CLI commands from /home/ubuntu/flow-create-commands.txt
98 * At run-time additional commands can be loaded in bulk by invoking the ``load FILENAME``
101 .. code-block:: console
103 testpmd> load /home/ubuntu/flow-create-commands.txt
108 Flow rule #498 created
109 Flow rule #499 created
110 Read all CLI commands from /home/ubuntu/flow-create-commands.txt
114 In all cases output from any included command will be displayed as standard output.
115 Execution will continue until the end of the file is reached regardless of
116 whether any errors occur. The end user must examine the output to determine if
117 any failures occurred.
126 Start packet forwarding with current configuration::
133 Start packet forwarding with current configuration after sending specified number of bursts of packets::
135 testpmd> start tx_first (""|burst_num)
137 The default burst number is 1 when ``burst_num`` not presented.
142 Stop packet forwarding, and display accumulated statistics::
157 The functions in the following sections are used to display information about the
158 testpmd configuration or the NIC status.
163 Display information for a given port or all ports::
165 testpmd> show port (info|summary|stats|xstats|fdir|dcb_tc|cap) (port_id|all)
167 The available information categories are:
169 * ``info``: General port information such as MAC address.
171 * ``summary``: Brief port summary such as Device Name, Driver Name etc.
173 * ``stats``: RX/TX statistics.
175 * ``xstats``: RX/TX extended NIC statistics.
177 * ``fdir``: Flow Director information and statistics.
179 * ``dcb_tc``: DCB information such as TC mapping.
183 .. code-block:: console
185 testpmd> show port info 0
187 ********************* Infos for port 0 *********************
189 MAC address: XX:XX:XX:XX:XX:XX
191 memory allocation on the socket: 0
193 Link speed: 40000 Mbps
194 Link duplex: full-duplex
195 Promiscuous mode: enabled
196 Allmulticast mode: disabled
197 Maximum number of MAC addresses: 64
198 Maximum number of MAC addresses of hash filtering: 0
200 strip on, filter on, extend off, qinq strip off
201 Redirection table size: 512
202 Supported flow types:
220 show port (module_eeprom|eeprom)
221 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223 Display the EEPROM information of a port::
225 testpmd> show port (port_id) (module_eeprom|eeprom)
230 Display the rss redirection table entry indicated by masks on port X::
232 testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
234 size is used to indicate the hardware supported reta size
239 Display the RSS hash functions and RSS hash key of a port::
241 testpmd> show port (port_id) rss-hash [key]
246 Clear the port statistics and forward engine statistics for a given port or for all ports::
248 testpmd> clear port (info|stats|xstats|fdir) (port_id|all)
252 testpmd> clear port stats all
257 Display information for a given port's RX/TX queue::
259 testpmd> show (rxq|txq) info (port_id) (queue_id)
261 show desc status(rxq|txq)
262 ~~~~~~~~~~~~~~~~~~~~~~~~~
264 Display information for a given port's RX/TX descriptor status::
266 testpmd> show port (port_id) (rxq|txq) (queue_id) desc (desc_id) status
268 show rxq desc used count
269 ~~~~~~~~~~~~~~~~~~~~~~~~
271 Display the number of receive packet descriptors currently filled by hardware
272 and ready to be processed by the driver on a given RX queue::
274 testpmd> show port (port_id) rxq (queue_id) desc used count
279 Displays the configuration of the application.
280 The configuration comes from the command-line, the runtime or the application defaults::
282 testpmd> show config (rxtx|cores|fwd|rxoffs|rxpkts|txpkts|txtimes)
284 The available information categories are:
286 * ``rxtx``: RX/TX configuration items.
288 * ``cores``: List of forwarding cores.
290 * ``fwd``: Packet forwarding configuration.
292 * ``rxoffs``: Packet offsets for RX split.
294 * ``rxpkts``: Packets to RX split configuration.
296 * ``txpkts``: Packets to TX configuration.
298 * ``txtimes``: Burst time pattern for Tx only mode.
302 .. code-block:: console
304 testpmd> show config rxtx
306 io packet forwarding - CRC stripping disabled - packets/burst=16
307 nb forwarding cores=2 - nb forwarding ports=1
308 RX queues=1 - RX desc=128 - RX free threshold=0
309 RX threshold registers: pthresh=8 hthresh=8 wthresh=4
310 TX queues=1 - TX desc=512 - TX free threshold=0
311 TX threshold registers: pthresh=36 hthresh=0 wthresh=0
312 TX RS bit threshold=0 - TXQ flags=0x0
317 Set the packet forwarding mode::
319 testpmd> set fwd (io|mac|macswap|flowgen| \
320 rxonly|txonly|csum|icmpecho|noisy|5tswap|shared-rxq) (""|retry)
322 ``retry`` can be specified for forwarding engines except ``rx_only``.
324 The available information categories are:
326 * ``io``: Forwards packets "as-is" in I/O mode.
327 This is the fastest possible forwarding operation as it does not access packets data.
328 This is the default mode.
330 * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
331 Default application behavior is to set source Ethernet address to that of the transmitting interface, and destination
332 address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
333 'eth-peers-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
335 * ``macswap``: MAC swap forwarding mode.
336 Swaps the source and the destination Ethernet addresses of packets before forwarding them.
338 * ``flowgen``: Multi-flow generation mode.
339 Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
341 * ``rxonly``: Receives packets but doesn't transmit them.
343 * ``txonly``: Generates and transmits packets without receiving any.
345 * ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
347 * ``icmpecho``: Receives a burst of packets, lookup for ICMP echo requests and, if any, send back ICMP echo replies.
349 * ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX.
351 * ``noisy``: Noisy neighbor simulation.
352 Simulate more realistic behavior of a guest machine engaged in receiving
353 and sending packets performing Virtual Network Function (VNF).
355 * ``5tswap``: Swap the source and destination of L2,L3,L4 if they exist.
357 L2 swaps the source address and destination address of Ethernet, as same as ``macswap``.
359 L3 swaps the source address and destination address of IP (v4 and v6).
361 L4 swaps the source port and destination port of transport layer (TCP and UDP).
363 * ``shared-rxq``: Receive only for shared Rx queue.
364 Resolve packet source port from mbuf and update stream statistics accordingly.
368 testpmd> set fwd rxonly
370 Set rxonly packet forwarding mode
376 When running, forwarding engines maintain statistics from the time they have been started.
377 Example for the io forwarding engine, with some packet drops on the tx side::
379 testpmd> show fwd stats all
381 ------- Forward Stats for RX Port= 0/Queue= 0 -> TX Port= 1/Queue= 0 -------
382 RX-packets: 274293770 TX-packets: 274293642 TX-dropped: 128
384 ------- Forward Stats for RX Port= 1/Queue= 0 -> TX Port= 0/Queue= 0 -------
385 RX-packets: 274301850 TX-packets: 274301850 TX-dropped: 0
387 ---------------------- Forward statistics for port 0 ----------------------
388 RX-packets: 274293802 RX-dropped: 0 RX-total: 274293802
389 TX-packets: 274301862 TX-dropped: 0 TX-total: 274301862
390 ----------------------------------------------------------------------------
392 ---------------------- Forward statistics for port 1 ----------------------
393 RX-packets: 274301894 RX-dropped: 0 RX-total: 274301894
394 TX-packets: 274293706 TX-dropped: 128 TX-total: 274293834
395 ----------------------------------------------------------------------------
397 +++++++++++++++ Accumulated forward statistics for all ports+++++++++++++++
398 RX-packets: 548595696 RX-dropped: 0 RX-total: 548595696
399 TX-packets: 548595568 TX-dropped: 128 TX-total: 548595696
400 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
406 Clear the forwarding engines statistics::
408 testpmd> clear fwd stats all
413 Display an RX descriptor for a port RX queue::
415 testpmd> read rxd (port_id) (queue_id) (rxd_id)
419 testpmd> read rxd 0 0 4
420 0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
425 Display a TX descriptor for a port TX queue::
427 testpmd> read txd (port_id) (queue_id) (txd_id)
431 testpmd> read txd 0 0 4
432 0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
437 Get loaded dynamic device personalization (DDP) package info list::
439 testpmd> ddp get list (port_id)
444 Display information about dynamic device personalization (DDP) profile::
446 testpmd> ddp get info (profile_path)
451 Display VF statistics::
453 testpmd> show vf stats (port_id) (vf_id)
458 Reset VF statistics::
460 testpmd> clear vf stats (port_id) (vf_id)
462 show port pctype mapping
463 ~~~~~~~~~~~~~~~~~~~~~~~~
465 List all items from the pctype mapping table::
467 testpmd> show port (port_id) pctype mapping
469 show rx offloading capabilities
470 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472 List all per queue and per port Rx offloading capabilities of a port::
474 testpmd> show port (port_id) rx_offload capabilities
476 show rx offloading configuration
477 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
479 List port level and all queue level Rx offloading configuration::
481 testpmd> show port (port_id) rx_offload configuration
483 show tx offloading capabilities
484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486 List all per queue and per port Tx offloading capabilities of a port::
488 testpmd> show port (port_id) tx_offload capabilities
490 show tx offloading configuration
491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
493 List port level and all queue level Tx offloading configuration::
495 testpmd> show port (port_id) tx_offload configuration
497 show tx metadata setting
498 ~~~~~~~~~~~~~~~~~~~~~~~~
500 Show Tx metadata value set for a specific port::
502 testpmd> show port (port_id) tx_metadata
504 show port supported ptypes
505 ~~~~~~~~~~~~~~~~~~~~~~~~~~
507 Show ptypes supported for a specific port::
509 testpmd> show port (port_id) ptypes
511 set port supported ptypes
512 ~~~~~~~~~~~~~~~~~~~~~~~~~
514 set packet types classification for a specific port::
516 testpmd> set port (port_id) ptypes_mask (mask)
518 show port mac addresses info
519 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
521 Show mac addresses added for a specific port::
523 testpmd> show port (port_id) macs
526 show port multicast mac addresses info
527 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
529 Show multicast mac addresses added for a specific port::
531 testpmd> show port (port_id) mcast_macs
533 show flow transfer proxy port ID for the given port
534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
536 Show proxy port ID to use as the 1st argument in commands to
537 manage ``transfer`` flows and their indirect components.
540 testpmd> show port (port_id) flow transfer proxy
545 Show general information about devices probed::
547 testpmd> show device info (<identifier>|all)
551 .. code-block:: console
553 testpmd> show device info net_pcap0
555 ********************* Infos for device net_pcap0 *********************
557 Driver name: net_pcap
558 Devargs: iface=enP2p6s0,phy_mac=1
559 Connect to socket: -1
562 MAC address: 1E:37:93:28:04:B8
563 Device name: net_pcap0
568 Dumps all physical memory segment layouts::
570 testpmd> dump_physmem
575 Dumps the layout of all memory zones::
577 testpmd> dump_memzone
582 Dumps the memory usage of all sockets::
584 testpmd> dump_socket_mem
589 Dumps the size of all memory structures::
591 testpmd> dump_struct_sizes
596 Dumps the status of all or specific element in DPDK rings::
598 testpmd> dump_ring [ring_name]
603 Dumps the statistics of all or specific memory pool::
605 testpmd> dump_mempool [mempool_name]
610 Dumps the user device list::
612 testpmd> dump_devargs
617 Dumps the log level for all the dpdk modules::
619 testpmd> dump_log_types
621 show (raw_encap|raw_decap)
622 ~~~~~~~~~~~~~~~~~~~~~~~~~~
624 Display content of raw_encap/raw_decap buffers in hex::
626 testpmd> show <raw_encap|raw_decap> <index>
627 testpmd> show <raw_encap|raw_decap> all
631 testpmd> show raw_encap 6
633 index: 6 at [0x1c565b0], len=50
634 00000000: 00 00 00 00 00 00 16 26 36 46 56 66 08 00 45 00 | .......&6FVf..E.
635 00000010: 00 00 00 00 00 00 00 11 00 00 C0 A8 01 06 C0 A8 | ................
636 00000020: 03 06 00 00 00 FA 00 00 00 00 08 00 00 00 00 00 | ................
639 show fec capabilities
640 ~~~~~~~~~~~~~~~~~~~~~
642 Show fec capabilities of a port::
644 testpmd> show port (port_id) fec capabilities
649 Show fec mode of a port::
651 testpmd> show port (port_id) fec_mode
654 Configuration Functions
655 -----------------------
657 The testpmd application can be configured from the runtime as well as from the command-line.
659 This section details the available configuration functions that are available.
663 Configuration changes only become active when forwarding is started/restarted.
668 Reset forwarding to the default configuration::
675 Set the debug verbosity level::
677 testpmd> set verbose (level)
679 Available levels are as following:
681 * ``0`` silent except for error.
682 * ``1`` fully verbose except for Tx packets.
683 * ``2`` fully verbose except for Rx packets.
684 * ``> 2`` fully verbose.
689 Set the log level for a log type::
691 testpmd> set log global|(type) (level)
695 * ``type`` is the log name.
697 * ``level`` is the log level.
699 For example, to change the global log level::
701 testpmd> set log global (level)
703 Regexes can also be used for type. To change log level of user1, user2 and user3::
705 testpmd> set log user[1-3] (level)
710 Set the number of ports used by the application:
714 This is equivalent to the ``--nb-ports`` command-line option.
719 Set the number of cores used by the application::
721 testpmd> set nbcore (num)
723 This is equivalent to the ``--nb-cores`` command-line option.
727 The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
732 Set the forwarding cores hexadecimal mask::
734 testpmd> set coremask (mask)
736 This is equivalent to the ``--coremask`` command-line option.
740 The main lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
745 Set the forwarding ports hexadecimal mask::
747 testpmd> set portmask (mask)
749 This is equivalent to the ``--portmask`` command-line option.
751 set record-core-cycles
752 ~~~~~~~~~~~~~~~~~~~~~~
754 Set the recording of CPU cycles::
756 testpmd> set record-core-cycles (on|off)
760 * ``on`` enables measurement of CPU cycles per packet.
762 * ``off`` disables measurement of CPU cycles per packet.
764 This is equivalent to the ``--record-core-cycles command-line`` option.
766 set record-burst-stats
767 ~~~~~~~~~~~~~~~~~~~~~~
769 Set the displaying of RX and TX bursts::
771 testpmd> set record-burst-stats (on|off)
775 * ``on`` enables display of RX and TX bursts.
777 * ``off`` disables display of RX and TX bursts.
779 This is equivalent to the ``--record-burst-stats command-line`` option.
784 Set number of packets per burst::
786 testpmd> set burst (num)
788 This is equivalent to the ``--burst command-line`` option.
790 When retry is enabled, the transmit delay time and number of retries can also be set::
792 testpmd> set burst tx delay (microseconds) retry (num)
797 Set the offsets of segments relating to the data buffer beginning on receiving
798 if split feature is engaged. Affects only the queues configured with split
799 offloads (currently BUFFER_SPLIT is supported only).
801 testpmd> set rxoffs (x[,y]*)
803 Where x[,y]* represents a CSV list of values, without white space. If the list
804 of offsets is shorter than the list of segments the zero offsets will be used
805 for the remaining segments.
810 Set the length of segments to scatter packets on receiving if split
811 feature is engaged. Affects only the queues configured with split offloads
812 (currently BUFFER_SPLIT is supported only). Optionally the multiple memory
813 pools can be specified with --mbuf-size command line parameter and the mbufs
814 to receive will be allocated sequentially from these extra memory pools (the
815 mbuf for the first segment is allocated from the first pool, the second one
816 from the second pool, and so on, if segment number is greater then pool's the
817 mbuf for remaining segments will be allocated from the last valid pool).
819 testpmd> set rxpkts (x[,y]*)
821 Where x[,y]* represents a CSV list of values, without white space. Zero value
822 means to use the corresponding memory pool data buffer size.
827 Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
829 testpmd> set txpkts (x[,y]*)
831 Where x[,y]* represents a CSV list of values, without white space.
836 Configure the timing burst pattern for Tx only mode. This command enables
837 the packet send scheduling on dynamic timestamp mbuf field and configures
838 timing pattern in Tx only mode. In this mode, if scheduling is enabled
839 application provides timestamps in the packets being sent. It is possible
840 to configure delay (in unspecified device clock units) between bursts
841 and between the packets within the burst::
843 testpmd> set txtimes (inter),(intra)
847 * ``inter`` is the delay between the bursts in the device clock units.
848 If ``intra`` is zero, this is the time between the beginnings of the
849 first packets in the neighbour bursts, if ``intra`` is not zero,
850 ``inter`` specifies the time between the beginning of the first packet
851 of the current burst and the beginning of the last packet of the
852 previous burst. If ``inter`` parameter is zero the send scheduling
853 on timestamps is disabled (default).
855 * ``intra`` is the delay between the packets within the burst specified
856 in the device clock units. The number of packets in the burst is defined
857 by regular burst setting. If ``intra`` parameter is zero no timestamps
858 provided in the packets excepting the first one in the burst.
860 As the result the bursts of packet will be transmitted with specific
861 delays between the packets within the burst and specific delay between
862 the bursts. The rte_eth_read_clock() must be supported by the device(s)
863 and is supposed to be engaged to get the current device clock value
864 and provide the reference for the timestamps. If there is no supported
865 rte_eth_read_clock() there will be no send scheduling provided on the port.
870 Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
872 testpmd> set txsplit (off|on|rand)
876 * ``off`` disable packet copy & split for CSUM mode.
878 * ``on`` split outgoing packet into multiple segments. Size of each segment
879 and number of segments per packet is determined by ``set txpkts`` command
882 * ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
887 Set the list of forwarding cores::
889 testpmd> set corelist (x[,y]*)
891 For example, to change the forwarding cores:
893 .. code-block:: console
895 testpmd> set corelist 3,1
896 testpmd> show config fwd
898 io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
899 Logical Core 3 (socket 0) forwards packets on 1 streams:
900 RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
901 Logical Core 1 (socket 0) forwards packets on 1 streams:
902 RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
906 The cores are used in the same order as specified on the command line.
911 Set the list of forwarding ports::
913 testpmd> set portlist (x[,y]*)
915 For example, to change the port forwarding:
917 .. code-block:: console
919 testpmd> set portlist 0,2,1,3
920 testpmd> show config fwd
922 io packet forwarding - ports=4 - cores=1 - streams=4
923 Logical Core 3 (socket 0) forwards packets on 4 streams:
924 RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
925 RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
926 RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
927 RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
932 Select how to retrieve new ports created after "port attach" command::
934 testpmd> set port setup on (iterator|event)
936 For each new port, a setup is done.
937 It will find the probed ports via RTE_ETH_FOREACH_MATCHING_DEV loop
938 in iterator mode, or via RTE_ETH_EVENT_NEW in event mode.
943 Enable/disable tx loopback::
945 testpmd> set tx loopback (port_id) (on|off)
950 set drop enable bit for all queues::
952 testpmd> set all queues drop (port_id) (on|off)
954 set split drop enable (for VF)
955 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
957 set split drop enable bit for VF from PF::
959 testpmd> set vf split drop (port_id) (vf_id) (on|off)
961 set mac antispoof (for VF)
962 ~~~~~~~~~~~~~~~~~~~~~~~~~~
964 Set mac antispoof for a VF from the PF::
966 testpmd> set vf mac antispoof (port_id) (vf_id) (on|off)
971 Enable/disable MACsec offload::
973 testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
974 testpmd> set macsec offload (port_id) off
979 Configure MACsec secure connection (SC)::
981 testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi)
985 The pi argument is ignored for tx.
986 Check the NIC Datasheet for hardware limits.
991 Configure MACsec secure association (SA)::
993 testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
997 The IDX value must be 0 or 1.
998 Check the NIC Datasheet for hardware limits.
1000 set broadcast mode (for VF)
1001 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1003 Set broadcast mode for a VF from the PF::
1005 testpmd> set vf broadcast (port_id) (vf_id) (on|off)
1010 Set the VLAN strip for a queue on a port::
1012 testpmd> vlan set stripq (on|off) (port_id,queue_id)
1014 vlan set stripq (for VF)
1015 ~~~~~~~~~~~~~~~~~~~~~~~~
1017 Set VLAN strip for all queues in a pool for a VF from the PF::
1019 testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
1021 vlan set insert (for VF)
1022 ~~~~~~~~~~~~~~~~~~~~~~~~
1024 Set VLAN insert for a VF from the PF::
1026 testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
1028 vlan set tag (for VF)
1029 ~~~~~~~~~~~~~~~~~~~~~
1031 Set VLAN tag for a VF from the PF::
1033 testpmd> set vf vlan tag (port_id) (vf_id) (on|off)
1035 vlan set antispoof (for VF)
1036 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1038 Set VLAN antispoof for a VF from the PF::
1040 testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
1042 vlan set (strip|filter|qinq_strip|extend)
1043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1044 Set the VLAN strip/filter/QinQ strip/extend on for a port::
1046 testpmd> vlan set (strip|filter|qinq_strip|extend) (on|off) (port_id)
1051 Set the inner or outer VLAN TPID for packet filtering on a port::
1053 testpmd> vlan set (inner|outer) tpid (value) (port_id)
1057 TPID value must be a 16-bit number (value <= 65536).
1062 Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
1064 testpmd> rx_vlan add (vlan_id|all) (port_id)
1068 VLAN filter must be set on that port. VLAN ID < 4096.
1069 Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
1070 in VFTA table. This is important if enabling all vlan_ids.
1075 Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
1077 testpmd> rx_vlan rm (vlan_id|all) (port_id)
1079 rx_vlan add (for VF)
1080 ~~~~~~~~~~~~~~~~~~~~
1082 Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
1084 testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
1089 Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
1091 testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
1096 Add an UDP port for VXLAN packet filter on a port::
1098 testpmd> rx_vxlan_port add (udp_port) (port_id)
1100 rx_vxlan_port remove
1101 ~~~~~~~~~~~~~~~~~~~~
1103 Remove an UDP port for VXLAN packet filter on a port::
1105 testpmd> rx_vxlan_port rm (udp_port) (port_id)
1110 Set hardware insertion of VLAN IDs in packets sent on a port::
1112 testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
1114 For example, set a single VLAN ID (5) insertion on port 0::
1118 Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
1126 Set port based hardware insertion of VLAN ID in packets sent on a port::
1128 testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
1133 Disable hardware insertion of a VLAN header in packets sent on a port::
1135 testpmd> tx_vlan reset (port_id)
1140 Select hardware or software calculation of the checksum when
1141 transmitting a packet using the ``csum`` forwarding engine::
1143 testpmd> csum set (ip|udp|tcp|sctp|outer-ip|outer-udp) (hw|sw) (port_id)
1147 * ``ip|udp|tcp|sctp`` always relate to the inner layer.
1149 * ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
1150 as a tunnel packet by the forwarding engine (geneve, gre, gtp, ipip, vxlan and vxlan-gpe are
1151 supported). See also the ``csum parse-tunnel`` command.
1153 * ``outer-udp`` relates to the outer UDP layer in the case where the packet is recognized
1154 as a tunnel packet by the forwarding engine (geneve, gtp, vxlan and vxlan-gpe are
1155 supported). See also the ``csum parse-tunnel`` command.
1159 Check the NIC Datasheet for hardware limits.
1164 Set RSS queue region span on a port::
1166 testpmd> set port (port_id) queue-region region_id (value) \
1167 queue_start_index (value) queue_num (value)
1169 Set flowtype mapping on a RSS queue region on a port::
1171 testpmd> set port (port_id) queue-region region_id (value) flowtype (value)
1175 * For the flowtype(pctype) of packet,the specific index for each type has
1176 been defined in file i40e_type.h as enum i40e_filter_pctype.
1178 Set user priority mapping on a RSS queue region on a port::
1180 testpmd> set port (port_id) queue-region UP (value) region_id (value)
1182 Flush all queue region related configuration on a port::
1184 testpmd> set port (port_id) queue-region flush (on|off)
1188 * ``on``: is just an enable function which server for other configuration,
1189 it is for all configuration about queue region from up layer,
1190 at first will only keep in DPDK software stored in driver,
1191 only after "flush on", it commit all configuration to HW.
1193 * ``"off``: is just clean all configuration about queue region just now,
1194 and restore all to DPDK i40e driver default config when start up.
1196 Show all queue region related configuration info on a port::
1198 testpmd> show port (port_id) queue-region
1202 Queue region only support on PF by now, so these command is
1203 only for configuration of queue region on PF port.
1208 Define how tunneled packets should be handled by the csum forward
1211 testpmd> csum parse-tunnel (on|off) (tx_port_id)
1213 If enabled, the csum forward engine will try to recognize supported
1214 tunnel headers (geneve, gtp, gre, ipip, vxlan, vxlan-gpe).
1216 If disabled, treat tunnel packets as non-tunneled packets (a inner
1217 header is handled as a packet payload).
1221 The port argument is the TX port like in the ``csum set`` command.
1225 Consider a packet in packet like the following::
1227 eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
1229 * If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
1230 command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
1231 ``outer-ip|outer-udp`` parameter relates to the outer headers (here ``ipv4_out`` and ``udp_out``).
1233 * If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
1234 command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
1239 Display tx checksum offload configuration::
1241 testpmd> csum show (port_id)
1246 Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
1248 testpmd> tso set (segsize) (port_id)
1252 Check the NIC datasheet for hardware limits.
1257 Display the status of TCP Segmentation Offload::
1259 testpmd> tso show (port_id)
1264 Set tso segment size of tunneled packets for a port in csum engine::
1266 testpmd> tunnel_tso set (tso_segsz) (port_id)
1271 Display the status of tunneled TCP Segmentation Offload for a port::
1273 testpmd> tunnel_tso show (port_id)
1278 Enable or disable GRO in ``csum`` forwarding engine::
1280 testpmd> set port <port_id> gro on|off
1282 If enabled, the csum forwarding engine will perform GRO on the TCP/IPv4
1283 packets received from the given port.
1285 If disabled, packets received from the given port won't be performed
1286 GRO. By default, GRO is disabled for all ports.
1290 When enable GRO for a port, TCP/IPv4 packets received from the port
1291 will be performed GRO. After GRO, all merged packets have bad
1292 checksums, since the GRO library doesn't re-calculate checksums for
1293 the merged packets. Therefore, if users want the merged packets to
1294 have correct checksums, please select HW IP checksum calculation and
1295 HW TCP checksum calculation for the port which the merged packets are
1301 Display GRO configuration for a given port::
1303 testpmd> show port <port_id> gro
1308 Set the cycle to flush the GROed packets from reassembly tables::
1310 testpmd> set gro flush <cycles>
1312 When enable GRO, the csum forwarding engine performs GRO on received
1313 packets, and the GROed packets are stored in reassembly tables. Users
1314 can use this command to determine when the GROed packets are flushed
1315 from the reassembly tables.
1317 The ``cycles`` is measured in GRO operation times. The csum forwarding
1318 engine flushes the GROed packets from the tables every ``cycles`` GRO
1321 By default, the value of ``cycles`` is 1, which means flush GROed packets
1322 from the reassembly tables as soon as one GRO operation finishes. The value
1323 of ``cycles`` should be in the range of 1 to ``GRO_MAX_FLUSH_CYCLES``.
1325 Please note that the large value of ``cycles`` may cause the poor TCP/IP
1326 stack performance. Because the GROed packets are delayed to arrive the
1327 stack, thus causing more duplicated ACKs and TCP retransmissions.
1332 Toggle per-port GSO support in ``csum`` forwarding engine::
1334 testpmd> set port <port_id> gso on|off
1336 If enabled, the csum forwarding engine will perform GSO on supported IPv4
1337 packets, transmitted on the given port.
1339 If disabled, packets transmitted on the given port will not undergo GSO.
1340 By default, GSO is disabled for all ports.
1344 When GSO is enabled on a port, supported IPv4 packets transmitted on that
1345 port undergo GSO. Afterwards, the segmented packets are represented by
1346 multi-segment mbufs; however, the csum forwarding engine doesn't calculation
1347 of checksums for GSO'd segments in SW. As a result, if users want correct
1348 checksums in GSO segments, they should enable HW checksum calculation for
1351 For example, HW checksum calculation for VxLAN GSO'd packets may be enabled
1352 by setting the following options in the csum forwarding engine:
1354 testpmd> csum set outer_ip hw <port_id>
1356 testpmd> csum set ip hw <port_id>
1358 testpmd> csum set tcp hw <port_id>
1360 UDP GSO is the same as IP fragmentation, which treats the UDP header
1361 as the payload and does not modify it during segmentation. That is,
1362 after UDP GSO, only the first output fragment has the original UDP
1363 header. Therefore, users need to enable HW IP checksum calculation
1364 and SW UDP checksum calculation for GSO-enabled ports, if they want
1365 correct checksums for UDP/IPv4 packets.
1370 Set the maximum GSO segment size (measured in bytes), which includes the
1371 packet header and the packet payload for GSO-enabled ports (global)::
1373 testpmd> set gso segsz <length>
1378 Display the status of Generic Segmentation Offload for a given port::
1380 testpmd> show port <port_id> gso
1385 Add an alternative MAC address to a port::
1387 testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
1392 Remove a MAC address from a port::
1394 testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
1399 To add the multicast MAC address to/from the set of multicast addresses
1402 testpmd> mcast_addr add (port_id) (mcast_addr)
1407 To remove the multicast MAC address to/from the set of multicast addresses
1410 testpmd> mcast_addr remove (port_id) (mcast_addr)
1412 mac_addr add (for VF)
1413 ~~~~~~~~~~~~~~~~~~~~~
1415 Add an alternative MAC address for a VF to a port::
1417 testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
1422 Set the default MAC address for a port::
1424 testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX)
1426 mac_addr set (for VF)
1427 ~~~~~~~~~~~~~~~~~~~~~
1429 Set the MAC address for a VF from the PF::
1431 testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
1436 Set the forwarding peer address for certain port::
1438 testpmd> set eth-peer (port_id) (peer_addr)
1440 This is equivalent to the ``--eth-peer`` command-line option.
1445 Set the unicast hash filter(s) on/off for a port::
1447 testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
1452 Set the promiscuous mode on for a port or for all ports.
1453 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1455 testpmd> set promisc (port_id|all) (on|off)
1460 Set the allmulti mode for a port or for all ports::
1462 testpmd> set allmulti (port_id|all) (on|off)
1464 Same as the ifconfig (8) option. Controls how multicast packets are handled.
1466 set promisc (for VF)
1467 ~~~~~~~~~~~~~~~~~~~~
1469 Set the unicast promiscuous mode for a VF from PF.
1470 It's supported by Intel i40e NICs now.
1471 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1473 testpmd> set vf promisc (port_id) (vf_id) (on|off)
1475 set allmulticast (for VF)
1476 ~~~~~~~~~~~~~~~~~~~~~~~~~
1478 Set the multicast promiscuous mode for a VF from PF.
1479 It's supported by Intel i40e NICs now.
1480 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1482 testpmd> set vf allmulti (port_id) (vf_id) (on|off)
1484 set tx max bandwidth (for VF)
1485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1487 Set TX max absolute bandwidth (Mbps) for a VF from PF::
1489 testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth)
1491 set tc tx min bandwidth (for VF)
1492 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1494 Set all TCs' TX min relative bandwidth (%) for a VF from PF::
1496 testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...)
1498 set tc tx max bandwidth (for VF)
1499 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1501 Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF::
1503 testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth)
1505 set tc strict link priority mode
1506 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1508 Set some TCs' strict link priority mode on a physical port::
1510 testpmd> set tx strict-link-priority (port_id) (tc_bitmap)
1512 set tc tx min bandwidth
1513 ~~~~~~~~~~~~~~~~~~~~~~~
1515 Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs::
1517 testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...)
1522 Set the link flow control parameter on a port::
1524 testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1525 (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
1526 autoneg (on|off) (port_id)
1530 * ``high_water`` (integer): High threshold value to trigger XOFF.
1532 * ``low_water`` (integer): Low threshold value to trigger XON.
1534 * ``pause_time`` (integer): Pause quota in the Pause frame.
1536 * ``send_xon`` (0/1): Send XON frame.
1538 * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
1540 * ``autoneg``: Change the auto-negotiation parameter.
1545 show the link flow control parameter on a port::
1547 testpmd> show port <port_id> flow_ctrl
1552 Set the priority flow control parameter on a port::
1554 testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1555 (pause_time) (priority) (port_id)
1559 * ``high_water`` (integer): High threshold value.
1561 * ``low_water`` (integer): Low threshold value.
1563 * ``pause_time`` (integer): Pause quota in the Pause frame.
1565 * ``priority`` (0-7): VLAN User Priority.
1570 Set the priority flow control parameter on a given Rx and Tx queue of a port::
1572 testpmd> set pfc_queue_ctrl <port_id> rx (on|off) <tx_qid> <tx_tc> \
1573 tx (on|off) <rx_qid> <rx_tc> <pause_time>
1577 * ``tx_qid`` (integer): Tx qid for which ``tx_tc`` will be applied and traffic
1578 will be paused when PFC frame is received with ``tx_tc`` enabled.
1580 * ``tx_tc`` (0-15): TC for which traffic is to be paused for xmit.
1582 * ``rx_qid`` (integer): Rx qid for which threshold will be applied and PFC
1583 frame will be generated with ``tx_tc`` when exceeds the threshold.
1585 * ``rx_tc`` (0-15): TC filled in PFC frame for which remote Tx is to be paused.
1587 * ``pause_time`` (integer): Pause quanta filled in the PFC frame for which
1588 interval, remote Tx will be paused. Valid only if Tx pause is on.
1590 Set Rx queue available descriptors threshold
1591 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1593 Set available descriptors threshold for a specific Rx queue of port::
1595 testpmd> set port (port_id) rxq (queue_id) avail_thresh (0..99)
1597 Use 0 value to disable the threshold and corresponding event.
1602 Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
1604 testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
1606 For example, to set rx queue 2 on port 0 to mapping 5::
1608 testpmd>set stat_qmap rx 0 2 5
1610 set xstats-hide-zero
1611 ~~~~~~~~~~~~~~~~~~~~
1613 Set the option to hide zero values for xstats display::
1615 testpmd> set xstats-hide-zero on|off
1619 By default, the zero values are displayed for xstats.
1621 set port - rx/tx (for VF)
1622 ~~~~~~~~~~~~~~~~~~~~~~~~~
1624 Set VF receive/transmit from a port::
1626 testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
1628 set port - rx mode(for VF)
1629 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1631 Set the VF receive mode of a port::
1633 testpmd> set port (port_id) vf (vf_id) \
1634 rxmode (AUPE|ROPE|BAM|MPE) (on|off)
1636 The available receive modes are:
1638 * ``AUPE``: Accepts untagged VLAN.
1640 * ``ROPE``: Accepts unicast hash.
1642 * ``BAM``: Accepts broadcast packets.
1644 * ``MPE``: Accepts all multicast packets.
1646 set port - tx_rate (for Queue)
1647 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1649 Set TX rate limitation for a queue on a port::
1651 testpmd> set port (port_id) queue (queue_id) rate (rate_value)
1653 set port - tx_rate (for VF)
1654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1656 Set TX rate limitation for queues in VF on a port::
1658 testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
1663 Set the flush on RX streams before forwarding.
1664 The default is flush ``on``.
1665 Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
1667 testpmd> set flush_rx off
1672 Set the bypass mode for the lowest port on bypass enabled NIC::
1674 testpmd> set bypass mode (normal|bypass|isolate) (port_id)
1679 Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
1681 testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
1682 mode (normal|bypass|isolate) (port_id)
1686 * ``timeout``: Enable bypass after watchdog timeout.
1688 * ``os_on``: Enable bypass when OS/board is powered on.
1690 * ``os_off``: Enable bypass when OS/board is powered off.
1692 * ``power_on``: Enable bypass when power supply is turned on.
1694 * ``power_off``: Enable bypass when power supply is turned off.
1700 Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
1702 testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
1707 Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
1709 testpmd> show bypass config (port_id)
1714 Set link up for a port::
1716 testpmd> set link-up port (port id)
1721 Set link down for a port::
1723 testpmd> set link-down port (port id)
1728 Enable E-tag insertion for a VF on a port::
1730 testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1732 Disable E-tag insertion for a VF on a port::
1734 testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1736 Enable/disable E-tag stripping on a port::
1738 testpmd> E-tag set stripping (on|off) port (port_id)
1740 Enable/disable E-tag based forwarding on a port::
1742 testpmd> E-tag set forwarding (on|off) port (port_id)
1747 Load a dynamic device personalization (DDP) profile and store backup profile::
1749 testpmd> ddp add (port_id) (profile_path[,backup_profile_path])
1754 Delete a dynamic device personalization profile and restore backup profile::
1756 testpmd> ddp del (port_id) (backup_profile_path)
1761 List all items from the ptype mapping table::
1763 testpmd> ptype mapping get (port_id) (valid_only)
1767 * ``valid_only``: A flag indicates if only list valid items(=1) or all items(=0).
1769 Replace a specific or a group of software defined ptype with a new one::
1771 testpmd> ptype mapping replace (port_id) (target) (mask) (pkt_type)
1775 * ``target``: A specific software ptype or a mask to represent a group of software ptypes.
1777 * ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1).
1779 * ``pkt_type``: The new software ptype to replace the old ones.
1781 Update hardware defined ptype to software defined packet type mapping table::
1783 testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype)
1787 * ``hw_ptype``: hardware ptype as the index of the ptype mapping table.
1789 * ``sw_ptype``: software ptype as the value of the ptype mapping table.
1791 Reset ptype mapping table::
1793 testpmd> ptype mapping reset (port_id)
1795 config per port Rx offloading
1796 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1798 Enable or disable a per port Rx offloading on all Rx queues of a port::
1800 testpmd> port config (port_id) rx_offload (offloading) on|off
1802 * ``offloading``: can be any of these offloading capability:
1803 vlan_strip, ipv4_cksum, udp_cksum, tcp_cksum, tcp_lro,
1804 qinq_strip, outer_ipv4_cksum, macsec_strip,
1805 header_split, vlan_filter, vlan_extend, jumbo_frame,
1806 scatter, timestamp, security, keep_crc, rss_hash
1808 This command should be run when the port is stopped, or else it will fail.
1810 config per queue Rx offloading
1811 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1813 Enable or disable a per queue Rx offloading only on a specific Rx queue::
1815 testpmd> port (port_id) rxq (queue_id) rx_offload (offloading) on|off
1817 * ``offloading``: can be any of these offloading capability:
1818 vlan_strip, ipv4_cksum, udp_cksum, tcp_cksum, tcp_lro,
1819 qinq_strip, outer_ipv4_cksum, macsec_strip,
1820 header_split, vlan_filter, vlan_extend, jumbo_frame,
1821 scatter, timestamp, security, keep_crc
1823 This command should be run when the port is stopped, or else it will fail.
1825 config per port Tx offloading
1826 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1828 Enable or disable a per port Tx offloading on all Tx queues of a port::
1830 testpmd> port config (port_id) tx_offload (offloading) on|off
1832 * ``offloading``: can be any of these offloading capability:
1833 vlan_insert, ipv4_cksum, udp_cksum, tcp_cksum,
1834 sctp_cksum, tcp_tso, udp_tso, outer_ipv4_cksum,
1835 qinq_insert, vxlan_tnl_tso, gre_tnl_tso,
1836 ipip_tnl_tso, geneve_tnl_tso, macsec_insert,
1837 mt_lockfree, multi_segs, mbuf_fast_free, security
1839 This command should be run when the port is stopped, or else it will fail.
1841 config per queue Tx offloading
1842 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1844 Enable or disable a per queue Tx offloading only on a specific Tx queue::
1846 testpmd> port (port_id) txq (queue_id) tx_offload (offloading) on|off
1848 * ``offloading``: can be any of these offloading capability:
1849 vlan_insert, ipv4_cksum, udp_cksum, tcp_cksum,
1850 sctp_cksum, tcp_tso, udp_tso, outer_ipv4_cksum,
1851 qinq_insert, vxlan_tnl_tso, gre_tnl_tso,
1852 ipip_tnl_tso, geneve_tnl_tso, macsec_insert,
1853 mt_lockfree, multi_segs, mbuf_fast_free, security
1855 This command should be run when the port is stopped, or else it will fail.
1857 Config VXLAN Encap outer layers
1858 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1860 Configure the outer layer to encapsulate a packet inside a VXLAN tunnel::
1862 set vxlan ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1863 udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) eth-src (eth-src) \
1866 set vxlan-with-vlan ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1867 udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) vlan-tci (vlan-tci) \
1868 eth-src (eth-src) eth-dst (eth-dst)
1870 set vxlan-tos-ttl ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1871 udp-dst (udp-dst) ip-tos (ip-tos) ip-ttl (ip-ttl) ip-src (ip-src) \
1872 ip-dst (ip-dst) eth-src (eth-src) eth-dst (eth-dst)
1874 These commands will set an internal configuration inside testpmd, any following
1875 flow rule using the action vxlan_encap will use the last configuration set.
1876 To have a different encapsulation header, one of those commands must be called
1877 before the flow rule creation.
1879 Config NVGRE Encap outer layers
1880 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1882 Configure the outer layer to encapsulate a packet inside a NVGRE tunnel::
1884 set nvgre ip-version (ipv4|ipv6) tni (tni) ip-src (ip-src) ip-dst (ip-dst) \
1885 eth-src (eth-src) eth-dst (eth-dst)
1886 set nvgre-with-vlan ip-version (ipv4|ipv6) tni (tni) ip-src (ip-src) \
1887 ip-dst (ip-dst) vlan-tci (vlan-tci) eth-src (eth-src) eth-dst (eth-dst)
1889 These commands will set an internal configuration inside testpmd, any following
1890 flow rule using the action nvgre_encap will use the last configuration set.
1891 To have a different encapsulation header, one of those commands must be called
1892 before the flow rule creation.
1897 Configure the l2 to be used when encapsulating a packet with L2::
1899 set l2_encap ip-version (ipv4|ipv6) eth-src (eth-src) eth-dst (eth-dst)
1900 set l2_encap-with-vlan ip-version (ipv4|ipv6) vlan-tci (vlan-tci) \
1901 eth-src (eth-src) eth-dst (eth-dst)
1903 Those commands will set an internal configuration inside testpmd, any following
1904 flow rule using the action l2_encap will use the last configuration set.
1905 To have a different encapsulation header, one of those commands must be called
1906 before the flow rule creation.
1911 Configure the l2 to be removed when decapsulating a packet with L2::
1913 set l2_decap ip-version (ipv4|ipv6)
1914 set l2_decap-with-vlan ip-version (ipv4|ipv6)
1916 Those commands will set an internal configuration inside testpmd, any following
1917 flow rule using the action l2_decap will use the last configuration set.
1918 To have a different encapsulation header, one of those commands must be called
1919 before the flow rule creation.
1921 Config MPLSoGRE Encap outer layers
1922 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1924 Configure the outer layer to encapsulate a packet inside a MPLSoGRE tunnel::
1926 set mplsogre_encap ip-version (ipv4|ipv6) label (label) \
1927 ip-src (ip-src) ip-dst (ip-dst) eth-src (eth-src) eth-dst (eth-dst)
1928 set mplsogre_encap-with-vlan ip-version (ipv4|ipv6) label (label) \
1929 ip-src (ip-src) ip-dst (ip-dst) vlan-tci (vlan-tci) \
1930 eth-src (eth-src) eth-dst (eth-dst)
1932 These commands will set an internal configuration inside testpmd, any following
1933 flow rule using the action mplsogre_encap will use the last configuration set.
1934 To have a different encapsulation header, one of those commands must be called
1935 before the flow rule creation.
1937 Config MPLSoGRE Decap outer layers
1938 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1940 Configure the outer layer to decapsulate MPLSoGRE packet::
1942 set mplsogre_decap ip-version (ipv4|ipv6)
1943 set mplsogre_decap-with-vlan ip-version (ipv4|ipv6)
1945 These commands will set an internal configuration inside testpmd, any following
1946 flow rule using the action mplsogre_decap will use the last configuration set.
1947 To have a different decapsulation header, one of those commands must be called
1948 before the flow rule creation.
1950 Config MPLSoUDP Encap outer layers
1951 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1953 Configure the outer layer to encapsulate a packet inside a MPLSoUDP tunnel::
1955 set mplsoudp_encap ip-version (ipv4|ipv6) label (label) udp-src (udp-src) \
1956 udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) \
1957 eth-src (eth-src) eth-dst (eth-dst)
1958 set mplsoudp_encap-with-vlan ip-version (ipv4|ipv6) label (label) \
1959 udp-src (udp-src) udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) \
1960 vlan-tci (vlan-tci) eth-src (eth-src) eth-dst (eth-dst)
1962 These commands will set an internal configuration inside testpmd, any following
1963 flow rule using the action mplsoudp_encap will use the last configuration set.
1964 To have a different encapsulation header, one of those commands must be called
1965 before the flow rule creation.
1967 Config MPLSoUDP Decap outer layers
1968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1970 Configure the outer layer to decapsulate MPLSoUDP packet::
1972 set mplsoudp_decap ip-version (ipv4|ipv6)
1973 set mplsoudp_decap-with-vlan ip-version (ipv4|ipv6)
1975 These commands will set an internal configuration inside testpmd, any following
1976 flow rule using the action mplsoudp_decap will use the last configuration set.
1977 To have a different decapsulation header, one of those commands must be called
1978 before the flow rule creation.
1980 Config Raw Encapsulation
1981 ~~~~~~~~~~~~~~~~~~~~~~~~~
1983 Configure the raw data to be used when encapsulating a packet by
1984 rte_flow_action_raw_encap::
1986 set raw_encap {index} {item} [/ {item} [...]] / end_set
1988 There are multiple global buffers for ``raw_encap``, this command will set one
1989 internal buffer index by ``{index}``.
1990 If there is no ``{index}`` specified::
1992 set raw_encap {item} [/ {item} [...]] / end_set
1994 the default index ``0`` is used.
1995 In order to use different encapsulating header, ``index`` must be specified
1996 during the flow rule creation::
1998 testpmd> flow create 0 egress pattern eth / ipv4 / end actions
1999 raw_encap index 2 / end
2001 Otherwise the default index ``0`` is used.
2003 Config Raw Decapsulation
2004 ~~~~~~~~~~~~~~~~~~~~~~~~
2006 Configure the raw data to be used when decapsulating a packet by
2007 rte_flow_action_raw_decap::
2009 set raw_decap {index} {item} [/ {item} [...]] / end_set
2011 There are multiple global buffers for ``raw_decap``, this command will set
2012 one internal buffer index by ``{index}``.
2013 If there is no ``{index}`` specified::
2015 set raw_decap {item} [/ {item} [...]] / end_set
2017 the default index ``0`` is used.
2018 In order to use different decapsulating header, ``index`` must be specified
2019 during the flow rule creation::
2021 testpmd> flow create 0 egress pattern eth / ipv4 / end actions
2022 raw_encap index 3 / end
2024 Otherwise the default index ``0`` is used.
2029 Set fec mode for a specific port::
2031 testpmd> set port (port_id) fec_mode auto|off|rs|baser
2033 Config Sample actions list
2034 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2036 Configure the sample actions list to be used when sampling a packet by
2037 rte_flow_action_sample::
2039 set sample_actions {index} {action} [/ {action} [...]] / end
2041 There are multiple global buffers for ``sample_actions``, this command will set
2042 one internal buffer index by ``{index}``.
2044 In order to use different sample actions list, ``index`` must be specified
2045 during the flow rule creation::
2047 testpmd> flow create 0 ingress pattern eth / ipv4 / end actions
2048 sample ratio 2 index 2 / end
2050 Otherwise the default index ``0`` is used.
2055 The following sections show functions for configuring ports.
2059 Port configuration changes only become active when forwarding is started/restarted.
2064 Attach a port specified by pci address or virtual device args::
2066 testpmd> port attach (identifier)
2068 To attach a new pci device, the device should be recognized by kernel first.
2069 Then it should be moved under DPDK management.
2070 Finally the port can be attached to testpmd.
2072 For example, to move a pci device using ixgbe under DPDK management:
2074 .. code-block:: console
2076 # Check the status of the available devices.
2077 ./usertools/dpdk-devbind.py --status
2079 Network devices using DPDK-compatible driver
2080 ============================================
2083 Network devices using kernel driver
2084 ===================================
2085 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
2088 # Bind the device to igb_uio.
2089 sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
2092 # Recheck the status of the devices.
2093 ./usertools/dpdk-devbind.py --status
2094 Network devices using DPDK-compatible driver
2095 ============================================
2096 0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
2098 To attach a port created by virtual device, above steps are not needed.
2100 For example, to attach a port whose pci address is 0000:0a:00.0.
2102 .. code-block:: console
2104 testpmd> port attach 0000:0a:00.0
2105 Attaching a new port...
2106 EAL: PCI device 0000:0a:00.0 on NUMA socket -1
2107 EAL: probe driver: 8086:10fb rte_ixgbe_pmd
2108 EAL: PCI memory mapped at 0x7f83bfa00000
2109 EAL: PCI memory mapped at 0x7f83bfa80000
2110 PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
2111 PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
2112 Port 0 is attached. Now total ports is 1
2115 For example, to attach a port created by pcap PMD.
2117 .. code-block:: console
2119 testpmd> port attach net_pcap0
2120 Attaching a new port...
2121 PMD: Initializing pmd_pcap for net_pcap0
2122 PMD: Creating pcap-backed ethdev on numa socket 0
2123 Port 0 is attached. Now total ports is 1
2126 In this case, identifier is ``net_pcap0``.
2127 This identifier format is the same as ``--vdev`` format of DPDK applications.
2129 For example, to re-attach a bonded port which has been previously detached,
2130 the mode and slave parameters must be given.
2132 .. code-block:: console
2134 testpmd> port attach net_bond_0,mode=0,slave=1
2135 Attaching a new port...
2136 EAL: Initializing pmd_bond for net_bond_0
2137 EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
2138 Port 0 is attached. Now total ports is 1
2145 Detach a specific port::
2147 testpmd> port detach (port_id)
2149 Before detaching a port, the port should be stopped and closed.
2151 For example, to detach a pci device port 0.
2153 .. code-block:: console
2155 testpmd> port stop 0
2158 testpmd> port close 0
2162 testpmd> port detach 0
2164 EAL: PCI device 0000:0a:00.0 on NUMA socket -1
2165 EAL: remove driver: 8086:10fb rte_ixgbe_pmd
2166 EAL: PCI memory unmapped at 0x7f83bfa00000
2167 EAL: PCI memory unmapped at 0x7f83bfa80000
2171 For example, to detach a virtual device port 0.
2173 .. code-block:: console
2175 testpmd> port stop 0
2178 testpmd> port close 0
2182 testpmd> port detach 0
2184 PMD: Closing pcap ethdev on numa socket 0
2185 Port 'net_pcap0' is detached. Now total ports is 0
2188 To remove a pci device completely from the system, first detach the port from testpmd.
2189 Then the device should be moved under kernel management.
2190 Finally the device can be removed using kernel pci hotplug functionality.
2192 For example, to move a pci device under kernel management:
2194 .. code-block:: console
2196 sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
2198 ./usertools/dpdk-devbind.py --status
2200 Network devices using DPDK-compatible driver
2201 ============================================
2204 Network devices using kernel driver
2205 ===================================
2206 0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
2208 To remove a port created by a virtual device, above steps are not needed.
2213 Start all ports or a specific port::
2215 testpmd> port start (port_id|all)
2220 Stop all ports or a specific port::
2222 testpmd> port stop (port_id|all)
2227 Close all ports or a specific port::
2229 testpmd> port close (port_id|all)
2234 Reset all ports or a specific port::
2236 testpmd> port reset (port_id|all)
2238 User should stop port(s) before resetting and (re-)start after reset.
2240 port config - queue ring size
2241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2243 Configure a rx/tx queue ring size::
2245 testpmd> port (port_id) (rxq|txq) (queue_id) ring_size (value)
2247 Only take effect after command that (re-)start the port or command that setup specific queue.
2249 port start/stop queue
2250 ~~~~~~~~~~~~~~~~~~~~~
2252 Start/stop a rx/tx queue on a specific port::
2254 testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
2256 port config - queue deferred start
2257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2259 Switch on/off deferred start of a specific port queue::
2261 testpmd> port (port_id) (rxq|txq) (queue_id) deferred_start (on|off)
2264 ~~~~~~~~~~~~~~~~~~~~~
2266 Setup a rx/tx queue on a specific port::
2268 testpmd> port (port_id) (rxq|txq) (queue_id) setup
2270 Only take effect when port is started.
2275 Set the speed and duplex mode for all ports or a specific port::
2277 testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|200000|auto) \
2278 duplex (half|full|auto)
2280 port config - queues/descriptors
2281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2283 Set number of queues/descriptors for rxq, txq, rxd and txd::
2285 testpmd> port config all (rxq|txq|rxd|txd) (value)
2287 This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
2289 port config - max-pkt-len
2290 ~~~~~~~~~~~~~~~~~~~~~~~~~
2292 Set the maximum packet length::
2294 testpmd> port config all max-pkt-len (value)
2296 This is equivalent to the ``--max-pkt-len`` command-line option.
2298 port config - max-lro-pkt-size
2299 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2301 Set the maximum LRO aggregated packet size::
2303 testpmd> port config all max-lro-pkt-size (value)
2305 This is equivalent to the ``--max-lro-pkt-size`` command-line option.
2307 port config - Drop Packets
2308 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2310 Enable or disable packet drop on all RX queues of all ports when no receive buffers available::
2312 testpmd> port config all drop-en (on|off)
2314 Packet dropping when no receive buffers available is off by default.
2316 The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
2321 Set the RSS (Receive Side Scaling) mode on or off::
2323 testpmd> port config all rss (all|default|eth|vlan|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|vxlan-gpe|l2tpv3|esp|ah|pfcp|ecpri|mpls|l2tpv2|none)
2325 RSS is on by default.
2327 The ``all`` option is equivalent to eth|vlan|ip|tcp|udp|sctp|ether|l2tpv3|esp|ah|pfcp|l2tpv2.
2329 The ``default`` option enables all supported RSS types reported by device info.
2331 The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
2333 port config - RSS Reta
2334 ~~~~~~~~~~~~~~~~~~~~~~
2336 Set the RSS (Receive Side Scaling) redirection table::
2338 testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
2343 Set the DCB mode for an individual port::
2345 testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
2347 The traffic class should be 4 or 8.
2352 Set the number of packets per burst::
2354 testpmd> port config all burst (value)
2356 This is equivalent to the ``--burst`` command-line option.
2358 port config - Threshold
2359 ~~~~~~~~~~~~~~~~~~~~~~~
2361 Set thresholds for TX/RX queues::
2363 testpmd> port config all (threshold) (value)
2365 Where the threshold type can be:
2367 * ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
2369 * ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
2371 * ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
2373 * ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
2375 * ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
2377 * ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
2379 * ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
2381 * ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
2383 * ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
2385 These threshold options are also available from the command-line.
2387 port config pctype mapping
2388 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2390 Reset pctype mapping table::
2392 testpmd> port config (port_id) pctype mapping reset
2394 Update hardware defined pctype to software defined flow type mapping table::
2396 testpmd> port config (port_id) pctype mapping update (pctype_id_0[,pctype_id_1]*) (flow_type_id)
2400 * ``pctype_id_x``: hardware pctype id as index of bit in bitmask value of the pctype mapping table.
2402 * ``flow_type_id``: software flow type id as the index of the pctype mapping table.
2404 port config input set
2405 ~~~~~~~~~~~~~~~~~~~~~
2407 Config RSS/FDIR/FDIR flexible payload input set for some pctype::
2409 testpmd> port config (port_id) pctype (pctype_id) \
2410 (hash_inset|fdir_inset|fdir_flx_inset) \
2411 (get|set|clear) field (field_idx)
2413 Clear RSS/FDIR/FDIR flexible payload input set for some pctype::
2415 testpmd> port config (port_id) pctype (pctype_id) \
2416 (hash_inset|fdir_inset|fdir_flx_inset) clear all
2420 * ``pctype_id``: hardware packet classification types.
2421 * ``field_idx``: hardware field index.
2423 port config udp_tunnel_port
2424 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2426 Add/remove UDP tunnel port for VXLAN/GENEVE tunneling protocols::
2428 testpmd> port config (port_id) udp_tunnel_port add|rm vxlan|geneve|vxlan-gpe|ecpri (udp_port)
2430 port config tx_metadata
2431 ~~~~~~~~~~~~~~~~~~~~~~~
2433 Set Tx metadata value per port.
2434 testpmd will add this value to any Tx packet sent from this port::
2436 testpmd> port config (port_id) tx_metadata (value)
2441 Set/clear dynamic flag per port.
2442 testpmd will register this flag in the mbuf (same registration
2443 for both Tx and Rx). Then set/clear this flag for each Tx
2444 packet sent from this port. The set bit only works for Tx packet::
2446 testpmd> port config (port_id) dynf (name) (set|clear)
2451 To configure MTU(Maximum Transmission Unit) on devices using testpmd::
2453 testpmd> port config mtu (port_id) (value)
2455 port config rss hash key
2456 ~~~~~~~~~~~~~~~~~~~~~~~~
2458 To configure the RSS hash key used to compute the RSS
2459 hash of input [IP] packets received on port::
2461 testpmd> port config <port_id> rss-hash-key (ipv4|ipv4-frag|\
2462 ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|\
2463 ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|\
2464 ipv6-other|l2-payload|ipv6-ex|ipv6-tcp-ex|\
2465 ipv6-udp-ex <string of hex digits \
2466 (variable length, NIC dependent)>)
2468 port cleanup txq mbufs
2469 ~~~~~~~~~~~~~~~~~~~~~~
2471 To cleanup txq mbufs currently cached by driver::
2473 testpmd> port cleanup (port_id) txq (queue_id) (free_cnt)
2475 If the value of ``free_cnt`` is 0, driver should free all cached mbufs.
2480 The following sections show functions for device operations.
2485 Detach a device specified by pci address or virtual device args::
2487 testpmd> device detach (identifier)
2489 Before detaching a device associated with ports, the ports should be stopped and closed.
2491 For example, to detach a pci device whose address is 0002:03:00.0.
2493 .. code-block:: console
2495 testpmd> device detach 0002:03:00.0
2496 Removing a device...
2497 Port 1 is now closed
2498 EAL: Releasing pci mapped resource for 0002:03:00.0
2499 EAL: Calling pci_unmap_resource for 0002:03:00.0 at 0x218a050000
2500 EAL: Calling pci_unmap_resource for 0002:03:00.0 at 0x218c050000
2501 Device 0002:03:00.0 is detached
2502 Now total ports is 1
2504 For example, to detach a port created by pcap PMD.
2506 .. code-block:: console
2508 testpmd> device detach net_pcap0
2509 Removing a device...
2510 Port 0 is now closed
2511 Device net_pcap0 is detached
2512 Now total ports is 0
2515 In this case, identifier is ``net_pcap0``.
2516 This identifier format is the same as ``--vdev`` format of DPDK applications.
2518 Link Bonding Functions
2519 ----------------------
2521 The Link Bonding functions make it possible to dynamically create and
2522 manage link bonding devices from within testpmd interactive prompt.
2524 create bonded device
2525 ~~~~~~~~~~~~~~~~~~~~
2527 Create a new bonding device::
2529 testpmd> create bonded device (mode) (socket)
2531 For example, to create a bonded device in mode 1 on socket 0::
2533 testpmd> create bonded device 1 0
2534 created new bonded device (port X)
2539 Adds Ethernet device to a Link Bonding device::
2541 testpmd> add bonding slave (slave id) (port id)
2543 For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
2545 testpmd> add bonding slave 6 10
2548 remove bonding slave
2549 ~~~~~~~~~~~~~~~~~~~~
2551 Removes an Ethernet slave device from a Link Bonding device::
2553 testpmd> remove bonding slave (slave id) (port id)
2555 For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
2557 testpmd> remove bonding slave 6 10
2562 Set the Link Bonding mode of a Link Bonding device::
2564 testpmd> set bonding mode (value) (port id)
2566 For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
2568 testpmd> set bonding mode 3 10
2573 Set an Ethernet slave device as the primary device on a Link Bonding device::
2575 testpmd> set bonding primary (slave id) (port id)
2577 For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
2579 testpmd> set bonding primary 6 10
2584 Set the MAC address of a Link Bonding device::
2586 testpmd> set bonding mac (port id) (mac)
2588 For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
2590 testpmd> set bonding mac 10 00:00:00:00:00:01
2592 set bonding balance_xmit_policy
2593 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2595 Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
2597 testpmd> set bonding balance_xmit_policy (port_id) (l2|l23|l34)
2599 For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
2601 testpmd> set bonding balance_xmit_policy 10 l34
2604 set bonding mon_period
2605 ~~~~~~~~~~~~~~~~~~~~~~
2607 Set the link status monitoring polling period in milliseconds for a bonding device.
2609 This adds support for PMD slave devices which do not support link status interrupts.
2610 When the mon_period is set to a value greater than 0 then all PMD's which do not support
2611 link status ISR will be queried every polling interval to check if their link status has changed::
2613 testpmd> set bonding mon_period (port_id) (value)
2615 For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
2617 testpmd> set bonding mon_period 5 150
2620 set bonding lacp dedicated_queue
2621 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2623 Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic
2624 when in mode 4 (link-aggregation-802.3ad)::
2626 testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable)
2629 set bonding agg_mode
2630 ~~~~~~~~~~~~~~~~~~~~
2632 Enable one of the specific aggregators mode when in mode 4 (link-aggregation-802.3ad)::
2634 testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable)
2640 Show the current configuration of a Link Bonding device::
2642 testpmd> show bonding config (port id)
2645 to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
2646 in balance mode with a transmission policy of layer 2+3::
2648 testpmd> show bonding config 9
2650 Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
2652 Active Slaves (3): [1 3 4]
2655 show bonding lacp info
2656 ~~~~~~~~~~~~~~~~~~~~~~
2658 Show information about the Link Bonding device in mode 4 (link-aggregation-802.3ad)::
2660 testpmd> show bonding lacp info (port_id)
2665 The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
2666 This is mainly useful for debugging purposes.
2667 Reference should be made to the appropriate datasheet for the network card for details on the register addresses
2668 and fields that can be accessed.
2673 Display the value of a port register::
2675 testpmd> read reg (port_id) (address)
2677 For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
2679 testpmd> read reg 0 0xEE00
2680 port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
2685 Display a port register bit field::
2687 testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
2689 For example, reading the lowest two bits from the register in the example above::
2691 testpmd> read regfield 0 0xEE00 0 1
2692 port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
2697 Display a single port register bit::
2699 testpmd> read regbit (port_id) (address) (bit_x)
2701 For example, reading the lowest bit from the register in the example above::
2703 testpmd> read regbit 0 0xEE00 0
2704 port 0 PCI register at offset 0xEE00: bit 0=1
2709 Set the value of a port register::
2711 testpmd> write reg (port_id) (address) (value)
2713 For example, to clear a register::
2715 testpmd> write reg 0 0xEE00 0x0
2716 port 0 PCI register at offset 0xEE00: 0x00000000 (0)
2721 Set bit field of a port register::
2723 testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
2725 For example, writing to the register cleared in the example above::
2727 testpmd> write regfield 0 0xEE00 0 1 2
2728 port 0 PCI register at offset 0xEE00: 0x00000002 (2)
2733 Set single bit value of a port register::
2735 testpmd> write regbit (port_id) (address) (bit_x) (value)
2737 For example, to set the high bit in the register from the example above::
2739 testpmd> write regbit 0 0xEE00 31 1
2740 port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
2742 Traffic Metering and Policing
2743 -----------------------------
2745 The following section shows functions for configuring traffic metering and
2746 policing on the ethernet device through the use of generic ethdev API.
2748 show port traffic management capability
2749 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2751 Show traffic metering and policing capability of the port::
2753 testpmd> show port meter cap (port_id)
2755 add port meter profile (srTCM rfc2967)
2756 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2758 Add meter profile (srTCM rfc2697) to the ethernet device::
2760 testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \
2761 (cir) (cbs) (ebs) (packet_mode)
2765 * ``profile_id``: ID for the meter profile.
2766 * ``cir``: Committed Information Rate (CIR) (bytes per second or packets per second).
2767 * ``cbs``: Committed Burst Size (CBS) (bytes or packets).
2768 * ``ebs``: Excess Burst Size (EBS) (bytes or packets).
2769 * ``packet_mode``: Packets mode for meter profile.
2771 add port meter profile (trTCM rfc2968)
2772 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2774 Add meter profile (srTCM rfc2698) to the ethernet device::
2776 testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \
2777 (cir) (pir) (cbs) (pbs) (packet_mode)
2781 * ``profile_id``: ID for the meter profile.
2782 * ``cir``: Committed information rate (bytes per second or packets per second).
2783 * ``pir``: Peak information rate (bytes per second or packets per second).
2784 * ``cbs``: Committed burst size (bytes or packets).
2785 * ``pbs``: Peak burst size (bytes or packets).
2786 * ``packet_mode``: Packets mode for meter profile.
2788 add port meter profile (trTCM rfc4115)
2789 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2791 Add meter profile (trTCM rfc4115) to the ethernet device::
2793 testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \
2794 (cir) (eir) (cbs) (ebs) (packet_mode)
2798 * ``profile_id``: ID for the meter profile.
2799 * ``cir``: Committed information rate (bytes per second or packets per second).
2800 * ``eir``: Excess information rate (bytes per second or packets per second).
2801 * ``cbs``: Committed burst size (bytes or packets).
2802 * ``ebs``: Excess burst size (bytes or packets).
2803 * ``packet_mode``: Packets mode for meter profile.
2805 delete port meter profile
2806 ~~~~~~~~~~~~~~~~~~~~~~~~~
2808 Delete meter profile from the ethernet device::
2810 testpmd> del port meter profile (port_id) (profile_id)
2815 Create new policy object for the ethernet device::
2817 testpmd> add port meter policy (port_id) (policy_id) g_actions \
2818 {action} y_actions {action} r_actions {action}
2822 * ``policy_id``: policy ID.
2823 * ``action``: action lists for green/yellow/red colors.
2828 Delete policy object for the ethernet device::
2830 testpmd> del port meter policy (port_id) (policy_id)
2834 * ``policy_id``: policy ID.
2839 Create new meter object for the ethernet device::
2841 testpmd> create port meter (port_id) (mtr_id) (profile_id) \
2842 (policy_id) (meter_enable) (stats_mask) (shared) \
2843 (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\
2848 * ``mtr_id``: meter object ID.
2849 * ``profile_id``: ID for the meter profile.
2850 * ``policy_id``: ID for the policy.
2851 * ``meter_enable``: When this parameter has a non-zero value, the meter object
2852 gets enabled at the time of creation, otherwise remains disabled.
2853 * ``stats_mask``: Mask of statistics counter types to be enabled for the
2855 * ``shared``: When this parameter has a non-zero value, the meter object is
2856 shared by multiple flows. Otherwise, meter object is used by single flow.
2857 * ``use_pre_meter_color``: When this parameter has a non-zero value, the
2858 input color for the current meter object is determined by the latest meter
2859 object in the same flow. Otherwise, the current meter object uses the
2860 *dscp_table* to determine the input color.
2861 * ``dscp_tbl_entryx``: DSCP table entry x providing meter providing input
2862 color, 0 <= x <= 63.
2867 Enable meter for the ethernet device::
2869 testpmd> enable port meter (port_id) (mtr_id)
2874 Disable meter for the ethernet device::
2876 testpmd> disable port meter (port_id) (mtr_id)
2881 Delete meter for the ethernet device::
2883 testpmd> del port meter (port_id) (mtr_id)
2885 Set port meter profile
2886 ~~~~~~~~~~~~~~~~~~~~~~
2888 Set meter profile for the ethernet device::
2890 testpmd> set port meter profile (port_id) (mtr_id) (profile_id)
2892 set port meter dscp table
2893 ~~~~~~~~~~~~~~~~~~~~~~~~~
2895 Set meter dscp table for the ethernet device::
2897 testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \
2898 (dscp_tbl_entry1)...(dscp_tbl_entry63)]
2900 set port meter stats mask
2901 ~~~~~~~~~~~~~~~~~~~~~~~~~
2903 Set meter stats mask for the ethernet device::
2905 testpmd> set port meter stats mask (port_id) (mtr_id) (stats_mask)
2909 * ``stats_mask``: Bit mask indicating statistics counter types to be enabled.
2911 show port meter stats
2912 ~~~~~~~~~~~~~~~~~~~~~
2914 Show meter stats of the ethernet device::
2916 testpmd> show port meter stats (port_id) (mtr_id) (clear)
2920 * ``clear``: Flag that indicates whether the statistics counters should
2921 be cleared (i.e. set to zero) immediately after they have been read or not.
2926 The following section shows functions for configuring traffic management on
2927 the ethernet device through the use of generic TM API.
2929 show port traffic management capability
2930 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2932 Show traffic management capability of the port::
2934 testpmd> show port tm cap (port_id)
2936 show port traffic management capability (hierarchy level)
2937 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2939 Show traffic management hierarchy level capability of the port::
2941 testpmd> show port tm level cap (port_id) (level_id)
2943 show port traffic management capability (hierarchy node level)
2944 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2946 Show the traffic management hierarchy node capability of the port::
2948 testpmd> show port tm node cap (port_id) (node_id)
2950 show port traffic management hierarchy node type
2951 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2953 Show the port traffic management hierarchy node type::
2955 testpmd> show port tm node type (port_id) (node_id)
2957 show port traffic management hierarchy node stats
2958 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2960 Show the port traffic management hierarchy node statistics::
2962 testpmd> show port tm node stats (port_id) (node_id) (clear)
2966 * ``clear``: When this parameter has a non-zero value, the statistics counters
2967 are cleared (i.e. set to zero) immediately after they have been read,
2968 otherwise the statistics counters are left untouched.
2970 Add port traffic management private shaper profile
2971 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2973 Add the port traffic management private shaper profile::
2975 testpmd> add port tm node shaper profile (port_id) (shaper_profile_id) \
2976 (cmit_tb_rate) (cmit_tb_size) (peak_tb_rate) (peak_tb_size) \
2977 (packet_length_adjust) (packet_mode)
2981 * ``shaper_profile id``: Shaper profile ID for the new profile.
2982 * ``cmit_tb_rate``: Committed token bucket rate (bytes per second or packets per second).
2983 * ``cmit_tb_size``: Committed token bucket size (bytes or packets).
2984 * ``peak_tb_rate``: Peak token bucket rate (bytes per second or packets per second).
2985 * ``peak_tb_size``: Peak token bucket size (bytes or packets).
2986 * ``packet_length_adjust``: The value (bytes) to be added to the length of
2987 each packet for the purpose of shaping. This parameter value can be used to
2988 correct the packet length with the framing overhead bytes that are consumed
2990 * ``packet_mode``: Shaper configured in packet mode. This parameter value if
2991 zero, configures shaper in byte mode and if non-zero configures it in packet
2994 Delete port traffic management private shaper profile
2995 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2997 Delete the port traffic management private shaper::
2999 testpmd> del port tm node shaper profile (port_id) (shaper_profile_id)
3003 * ``shaper_profile id``: Shaper profile ID that needs to be deleted.
3005 Add port traffic management shared shaper
3006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3008 Create the port traffic management shared shaper::
3010 testpmd> add port tm node shared shaper (port_id) (shared_shaper_id) \
3015 * ``shared_shaper_id``: Shared shaper ID to be created.
3016 * ``shaper_profile id``: Shaper profile ID for shared shaper.
3018 Set port traffic management shared shaper
3019 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3021 Update the port traffic management shared shaper::
3023 testpmd> set port tm node shared shaper (port_id) (shared_shaper_id) \
3028 * ``shared_shaper_id``: Shared shaper ID to be update.
3029 * ``shaper_profile id``: Shaper profile ID for shared shaper.
3031 Delete port traffic management shared shaper
3032 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3034 Delete the port traffic management shared shaper::
3036 testpmd> del port tm node shared shaper (port_id) (shared_shaper_id)
3040 * ``shared_shaper_id``: Shared shaper ID to be deleted.
3042 Set port traffic management hierarchy node private shaper
3043 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3045 set the port traffic management hierarchy node private shaper::
3047 testpmd> set port tm node shaper profile (port_id) (node_id) \
3052 * ``shaper_profile id``: Private shaper profile ID to be enabled on the
3055 Add port traffic management WRED profile
3056 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3058 Create a new WRED profile::
3060 testpmd> add port tm node wred profile (port_id) (wred_profile_id) \
3061 (color_g) (min_th_g) (max_th_g) (maxp_inv_g) (wq_log2_g) \
3062 (color_y) (min_th_y) (max_th_y) (maxp_inv_y) (wq_log2_y) \
3063 (color_r) (min_th_r) (max_th_r) (maxp_inv_r) (wq_log2_r)
3067 * ``wred_profile id``: Identifier for the newly create WRED profile
3068 * ``color_g``: Packet color (green)
3069 * ``min_th_g``: Minimum queue threshold for packet with green color
3070 * ``max_th_g``: Minimum queue threshold for packet with green color
3071 * ``maxp_inv_g``: Inverse of packet marking probability maximum value (maxp)
3072 * ``wq_log2_g``: Negated log2 of queue weight (wq)
3073 * ``color_y``: Packet color (yellow)
3074 * ``min_th_y``: Minimum queue threshold for packet with yellow color
3075 * ``max_th_y``: Minimum queue threshold for packet with yellow color
3076 * ``maxp_inv_y``: Inverse of packet marking probability maximum value (maxp)
3077 * ``wq_log2_y``: Negated log2 of queue weight (wq)
3078 * ``color_r``: Packet color (red)
3079 * ``min_th_r``: Minimum queue threshold for packet with yellow color
3080 * ``max_th_r``: Minimum queue threshold for packet with yellow color
3081 * ``maxp_inv_r``: Inverse of packet marking probability maximum value (maxp)
3082 * ``wq_log2_r``: Negated log2 of queue weight (wq)
3084 Delete port traffic management WRED profile
3085 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3087 Delete the WRED profile::
3089 testpmd> del port tm node wred profile (port_id) (wred_profile_id)
3091 Add port traffic management hierarchy nonleaf node
3092 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3094 Add nonleaf node to port traffic management hierarchy::
3096 testpmd> add port tm nonleaf node (port_id) (node_id) (parent_node_id) \
3097 (priority) (weight) (level_id) (shaper_profile_id) \
3098 (n_sp_priorities) (stats_mask) (n_shared_shapers) \
3099 [(shared_shaper_0) (shared_shaper_1) ...] \
3103 * ``parent_node_id``: Node ID of the parent.
3104 * ``priority``: Node priority (highest node priority is zero). This is used by
3105 the SP algorithm running on the parent node for scheduling this node.
3106 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3107 to the weight sum of all siblings that have the same priority. It is used by
3108 the WFQ algorithm running on the parent node for scheduling this node.
3109 * ``level_id``: Hierarchy level of the node.
3110 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3112 * ``n_sp_priorities``: Number of strict priorities.
3113 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3114 * ``n_shared_shapers``: Number of shared shapers.
3115 * ``shared_shaper_id``: Shared shaper id.
3117 Add port traffic management hierarchy nonleaf node with packet mode
3118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3120 Add nonleaf node with packet mode to port traffic management hierarchy::
3122 testpmd> add port tm nonleaf node pktmode (port_id) (node_id) (parent_node_id) \
3123 (priority) (weight) (level_id) (shaper_profile_id) \
3124 (n_sp_priorities) (stats_mask) (n_shared_shapers) \
3125 [(shared_shaper_0) (shared_shaper_1) ...] \
3129 * ``parent_node_id``: Node ID of the parent.
3130 * ``priority``: Node priority (highest node priority is zero). This is used by
3131 the SP algorithm running on the parent node for scheduling this node.
3132 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3133 to the weight sum of all siblings that have the same priority. It is used by
3134 the WFQ algorithm running on the parent node for scheduling this node.
3135 * ``level_id``: Hierarchy level of the node.
3136 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3138 * ``n_sp_priorities``: Number of strict priorities. Packet mode is enabled on
3140 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3141 * ``n_shared_shapers``: Number of shared shapers.
3142 * ``shared_shaper_id``: Shared shaper id.
3144 Add port traffic management hierarchy leaf node
3145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3147 Add leaf node to port traffic management hierarchy::
3149 testpmd> add port tm leaf node (port_id) (node_id) (parent_node_id) \
3150 (priority) (weight) (level_id) (shaper_profile_id) \
3151 (cman_mode) (wred_profile_id) (stats_mask) (n_shared_shapers) \
3152 [(shared_shaper_id) (shared_shaper_id) ...] \
3156 * ``parent_node_id``: Node ID of the parent.
3157 * ``priority``: Node priority (highest node priority is zero). This is used by
3158 the SP algorithm running on the parent node for scheduling this node.
3159 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3160 to the weight sum of all siblings that have the same priority. It is used by
3161 the WFQ algorithm running on the parent node for scheduling this node.
3162 * ``level_id``: Hierarchy level of the node.
3163 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3165 * ``cman_mode``: Congestion management mode to be enabled for this node.
3166 * ``wred_profile_id``: WRED profile id to be enabled for this node.
3167 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3168 * ``n_shared_shapers``: Number of shared shapers.
3169 * ``shared_shaper_id``: Shared shaper id.
3171 Delete port traffic management hierarchy node
3172 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3174 Delete node from port traffic management hierarchy::
3176 testpmd> del port tm node (port_id) (node_id)
3178 Update port traffic management hierarchy parent node
3179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3181 Update port traffic management hierarchy parent node::
3183 testpmd> set port tm node parent (port_id) (node_id) (parent_node_id) \
3186 This function can only be called after the hierarchy commit invocation. Its
3187 success depends on the port support for this operation, as advertised through
3188 the port capability set. This function is valid for all nodes of the traffic
3189 management hierarchy except root node.
3191 Suspend port traffic management hierarchy node
3192 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3194 testpmd> suspend port tm node (port_id) (node_id)
3196 Resume port traffic management hierarchy node
3197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3199 testpmd> resume port tm node (port_id) (node_id)
3201 Commit port traffic management hierarchy
3202 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3204 Commit the traffic management hierarchy on the port::
3206 testpmd> port tm hierarchy commit (port_id) (clean_on_fail)
3210 * ``clean_on_fail``: When set to non-zero, hierarchy is cleared on function
3211 call failure. On the other hand, hierarchy is preserved when this parameter
3214 Set port traffic management mark VLAN dei
3215 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3217 Enables/Disables the traffic management marking on the port for VLAN packets::
3219 testpmd> set port tm mark vlan_dei <port_id> <green> <yellow> <red>
3223 * ``port_id``: The port which on which VLAN packets marked as ``green`` or
3224 ``yellow`` or ``red`` will have dei bit enabled
3226 * ``green`` enable 1, disable 0 marking for dei bit of VLAN packets marked as green
3228 * ``yellow`` enable 1, disable 0 marking for dei bit of VLAN packets marked as yellow
3230 * ``red`` enable 1, disable 0 marking for dei bit of VLAN packets marked as red
3232 Set port traffic management mark IP dscp
3233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3235 Enables/Disables the traffic management marking on the port for IP dscp packets::
3237 testpmd> set port tm mark ip_dscp <port_id> <green> <yellow> <red>
3241 * ``port_id``: The port which on which IP packets marked as ``green`` or
3242 ``yellow`` or ``red`` will have IP dscp bits updated
3244 * ``green`` enable 1, disable 0 marking IP dscp to low drop precedence for green packets
3246 * ``yellow`` enable 1, disable 0 marking IP dscp to medium drop precedence for yellow packets
3248 * ``red`` enable 1, disable 0 marking IP dscp to high drop precedence for red packets
3250 Set port traffic management mark IP ecn
3251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3253 Enables/Disables the traffic management marking on the port for IP ecn packets::
3255 testpmd> set port tm mark ip_ecn <port_id> <green> <yellow> <red>
3259 * ``port_id``: The port which on which IP packets marked as ``green`` or
3260 ``yellow`` or ``red`` will have IP ecn bits updated
3262 * ``green`` enable 1, disable 0 marking IP ecn for green marked packets with ecn of 2'b01 or 2'b10
3263 to ecn of 2'b11 when IP is caring TCP or SCTP
3265 * ``yellow`` enable 1, disable 0 marking IP ecn for yellow marked packets with ecn of 2'b01 or 2'b10
3266 to ecn of 2'b11 when IP is caring TCP or SCTP
3268 * ``red`` enable 1, disable 0 marking IP ecn for yellow marked packets with ecn of 2'b01 or 2'b10
3269 to ecn of 2'b11 when IP is caring TCP or SCTP
3274 This section details the available filter functions that are available.
3276 Note these functions interface the deprecated legacy filtering framework,
3277 superseded by *rte_flow*. See `Flow rules management`_.
3279 .. _testpmd_flow_director:
3284 Set flow director's input masks::
3286 flow_director_mask (port_id) mode IP vlan (vlan_value) \
3287 src_mask (ipv4_src) (ipv6_src) (src_port) \
3288 dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
3290 flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
3292 flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
3293 mac (mac_value) tunnel-type (tunnel_type_value) \
3294 tunnel-id (tunnel_id_value)
3296 Example, to set flow director mask on port 0::
3298 testpmd> flow_director_mask 0 mode IP vlan 0xefff \
3299 src_mask 255.255.255.255 \
3300 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
3301 dst_mask 255.255.255.255 \
3302 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
3304 flow_director_flex_payload
3305 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3307 Configure flexible payload selection::
3309 flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
3311 For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
3313 testpmd> flow_director_flex_payload 0 l4 \
3314 (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
3317 .. _testpmd_rte_flow:
3319 Flow rules management
3320 ---------------------
3322 Control of the generic flow API (*rte_flow*) is fully exposed through the
3323 ``flow`` command (configuration, validation, creation, destruction, queries
3324 and operation modes).
3326 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
3327 features simultaneously may cause undefined side-effects and is therefore
3333 Because the ``flow`` command uses dynamic tokens to handle the large number
3334 of possible flow rules combinations, its behavior differs slightly from
3335 other commands, in particular:
3337 - Pressing *?* or the *<tab>* key displays contextual help for the current
3338 token, not that of the entire command.
3340 - Optional and repeated parameters are supported (provided they are listed
3341 in the contextual help).
3343 The first parameter stands for the operation mode. Possible operations and
3344 their general syntax are described below. They are covered in detail in the
3347 - Get info about flow engine::
3351 - Configure flow engine::
3353 flow configure {port_id}
3354 [queues_number {number}] [queues_size {size}]
3355 [counters_number {number}]
3356 [aging_counters_number {number}]
3357 [meters_number {number}]
3359 - Create a pattern template::
3360 flow pattern_template {port_id} create [pattern_template_id {id}]
3361 [relaxed {boolean}] [ingress] [egress] [transfer]
3362 template {item} [/ {item} [...]] / end
3364 - Destroy a pattern template::
3366 flow pattern_template {port_id} destroy pattern_template {id} [...]
3368 - Create an actions template::
3370 flow actions_template {port_id} create [actions_template_id {id}]
3371 [ingress] [egress] [transfer]
3372 template {action} [/ {action} [...]] / end
3373 mask {action} [/ {action} [...]] / end
3375 - Destroy an actions template::
3377 flow actions_template {port_id} destroy actions_template {id} [...]
3381 flow table {port_id} create
3383 [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3384 rules_number {number}
3385 pattern_template {pattern_template_id}
3386 actions_template {actions_template_id}
3390 flow table {port_id} destroy table {id} [...]
3392 - Check whether a flow rule can be created::
3394 flow validate {port_id}
3395 [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3396 pattern {item} [/ {item} [...]] / end
3397 actions {action} [/ {action} [...]] / end
3399 - Enqueue creation of a flow rule::
3401 flow queue {port_id} create {queue_id}
3402 [postpone {boolean}] template_table {table_id}
3403 pattern_template {pattern_template_index}
3404 actions_template {actions_template_index}
3405 pattern {item} [/ {item} [...]] / end
3406 actions {action} [/ {action} [...]] / end
3408 - Enqueue destruction of specific flow rules::
3410 flow queue {port_id} destroy {queue_id}
3411 [postpone {boolean}] rule {rule_id} [...]
3413 - Push enqueued operations::
3415 flow push {port_id} queue {queue_id}
3417 - Pull all operations results from a queue::
3419 flow pull {port_id} queue {queue_id}
3421 - Create a flow rule::
3423 flow create {port_id}
3424 [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3425 pattern {item} [/ {item} [...]] / end
3426 actions {action} [/ {action} [...]] / end
3428 - Destroy specific flow rules::
3430 flow destroy {port_id} rule {rule_id} [...]
3432 - Destroy all flow rules::
3434 flow flush {port_id}
3436 - Query an existing flow rule::
3438 flow query {port_id} {rule_id} {action}
3440 - List existing flow rules sorted by priority, filtered by group
3443 flow list {port_id} [group {group_id}] [...]
3445 - Restrict ingress traffic to the defined flow rules::
3447 flow isolate {port_id} {boolean}
3449 - Dump internal representation information of all flows in hardware::
3451 flow dump {port_id} all {output_file}
3455 flow dump {port_id} rule {rule_id} {output_file}
3457 - List and destroy aged flow rules::
3459 flow aged {port_id} [destroy]
3461 - Tunnel offload - create a tunnel stub::
3463 flow tunnel create {port_id} type {tunnel_type}
3465 - Tunnel offload - destroy a tunnel stub::
3467 flow tunnel destroy {port_id} id {tunnel_id}
3469 - Tunnel offload - list port tunnel stubs::
3471 flow tunnel list {port_id}
3473 Retrieving info about flow management engine
3474 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3476 ``flow info`` retrieves info on pre-configurable resources in the underlying
3477 device to give a hint of possible values for flow engine configuration.
3479 ``rte_flow_info_get()``::
3483 If successful, it will show::
3485 Flow engine resources on port #[...]:
3486 Number of queues: #[...]
3487 Size of queues: #[...]
3488 Number of counters: #[...]
3489 Number of aging objects: #[...]
3490 Number of meters: #[...]
3492 Otherwise it will show an error message of the form::
3494 Caught error type [...] ([...]): [...]
3496 Configuring flow management engine
3497 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3499 ``flow configure`` pre-allocates all the needed resources in the underlying
3500 device to be used later at the flow creation. Flow queues are allocated as well
3501 for asynchronous flow creation/destruction operations. It is bound to
3502 ``rte_flow_configure()``::
3504 flow configure {port_id}
3505 [queues_number {number}] [queues_size {size}]
3506 [counters_number {number}]
3507 [aging_counters_number {number}]
3508 [meters_number {number}]
3510 If successful, it will show::
3512 Configure flows on port #[...]: number of queues #[...] with #[...] elements
3514 Otherwise it will show an error message of the form::
3516 Caught error type [...] ([...]): [...]
3518 Creating pattern templates
3519 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3521 ``flow pattern_template create`` creates the specified pattern template.
3522 It is bound to ``rte_flow_pattern_template_create()``::
3524 flow pattern_template {port_id} create [pattern_template_id {id}]
3525 [relaxed {boolean}] [ingress] [egress] [transfer]
3526 template {item} [/ {item} [...]] / end
3528 If successful, it will show::
3530 Pattern template #[...] created
3532 Otherwise it will show an error message of the form::
3534 Caught error type [...] ([...]): [...]
3536 This command uses the same pattern items as ``flow create``,
3537 their format is described in `Creating flow rules`_.
3539 Destroying pattern templates
3540 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3542 ``flow pattern_template destroy`` destroys one or more pattern templates
3543 from their template ID (as returned by ``flow pattern_template create``),
3544 this command calls ``rte_flow_pattern_template_destroy()`` as many
3545 times as necessary::
3547 flow pattern_template {port_id} destroy pattern_template {id} [...]
3549 If successful, it will show::
3551 Pattern template #[...] destroyed
3553 It does not report anything for pattern template IDs that do not exist.
3554 The usual error message is shown when a pattern template cannot be destroyed::
3556 Caught error type [...] ([...]): [...]
3558 Creating actions templates
3559 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3561 ``flow actions_template create`` creates the specified actions template.
3562 It is bound to ``rte_flow_actions_template_create()``::
3564 flow actions_template {port_id} create [actions_template_id {id}]
3565 [ingress] [egress] [transfer]
3566 template {action} [/ {action} [...]] / end
3567 mask {action} [/ {action} [...]] / end
3569 If successful, it will show::
3571 Actions template #[...] created
3573 Otherwise it will show an error message of the form::
3575 Caught error type [...] ([...]): [...]
3577 This command uses the same actions as ``flow create``,
3578 their format is described in `Creating flow rules`_.
3580 Destroying actions templates
3581 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3583 ``flow actions_template destroy`` destroys one or more actions templates
3584 from their template ID (as returned by ``flow actions_template create``),
3585 this command calls ``rte_flow_actions_template_destroy()`` as many
3586 times as necessary::
3588 flow actions_template {port_id} destroy actions_template {id} [...]
3590 If successful, it will show::
3592 Actions template #[...] destroyed
3594 It does not report anything for actions template IDs that do not exist.
3595 The usual error message is shown when an actions template cannot be destroyed::
3597 Caught error type [...] ([...]): [...]
3599 Creating template table
3600 ~~~~~~~~~~~~~~~~~~~~~~~
3602 ``flow template_table create`` creates the specified template table.
3603 It is bound to ``rte_flow_template_table_create()``::
3605 flow template_table {port_id} create
3606 [table_id {id}] [group {group_id}]
3607 [priority {level}] [ingress] [egress] [transfer]
3608 rules_number {number}
3609 pattern_template {pattern_template_id}
3610 actions_template {actions_template_id}
3612 If successful, it will show::
3614 Template table #[...] created
3616 Otherwise it will show an error message of the form::
3618 Caught error type [...] ([...]): [...]
3620 Destroying flow table
3621 ~~~~~~~~~~~~~~~~~~~~~
3623 ``flow template_table destroy`` destroys one or more template tables
3624 from their table ID (as returned by ``flow template_table create``),
3625 this command calls ``rte_flow_template_table_destroy()`` as many
3626 times as necessary::
3628 flow template_table {port_id} destroy table {id} [...]
3630 If successful, it will show::
3632 Template table #[...] destroyed
3634 It does not report anything for table IDs that do not exist.
3635 The usual error message is shown when a table cannot be destroyed::
3637 Caught error type [...] ([...]): [...]
3639 Pushing enqueued operations
3640 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
3642 ``flow push`` pushes all the outstanding enqueued operations
3643 to the underlying device immediately.
3644 It is bound to ``rte_flow_push()``::
3646 flow push {port_id} queue {queue_id}
3648 If successful, it will show::
3650 Queue #[...] operations pushed
3652 The usual error message is shown when operations cannot be pushed::
3654 Caught error type [...] ([...]): [...]
3656 Pulling flow operations results
3657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3659 ``flow pull`` asks the underlying device about flow queue operations
3660 results and return all the processed (successfully or not) operations.
3661 It is bound to ``rte_flow_pull()``::
3663 flow pull {port_id} queue {queue_id}
3665 If successful, it will show::
3667 Queue #[...] pulled #[...] operations (#[...] failed, #[...] succeeded)
3669 The usual error message is shown when operations results cannot be pulled::
3671 Caught error type [...] ([...]): [...]
3673 Creating a tunnel stub for offload
3674 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3676 ``flow tunnel create`` setup a tunnel stub for tunnel offload flow rules::
3678 flow tunnel create {port_id} type {tunnel_type}
3680 If successful, it will return a tunnel stub ID usable with other commands::
3682 port [...]: flow tunnel #[...] type [...]
3684 Tunnel stub ID is relative to a port.
3686 Destroying tunnel offload stub
3687 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3689 ``flow tunnel destroy`` destroy port tunnel stub::
3691 flow tunnel destroy {port_id} id {tunnel_id}
3693 Listing tunnel offload stubs
3694 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3696 ``flow tunnel list`` list port tunnel offload stubs::
3698 flow tunnel list {port_id}
3700 Validating flow rules
3701 ~~~~~~~~~~~~~~~~~~~~~
3703 ``flow validate`` reports whether a flow rule would be accepted by the
3704 underlying device in its current state but stops short of creating it. It is
3705 bound to ``rte_flow_validate()``::
3707 flow validate {port_id}
3708 [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3709 pattern {item} [/ {item} [...]] / end
3710 actions {action} [/ {action} [...]] / end
3712 If successful, it will show::
3716 Otherwise it will show an error message of the form::
3718 Caught error type [...] ([...]): [...]
3720 This command uses the same parameters as ``flow create``, their format is
3721 described in `Creating flow rules`_.
3723 Check whether redirecting any Ethernet packet received on port 0 to RX queue
3724 index 6 is supported::
3726 testpmd> flow validate 0 ingress pattern eth / end
3727 actions queue index 6 / end
3731 Port 0 does not support TCPv6 rules::
3733 testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
3735 Caught error type 9 (specific pattern item): Invalid argument
3741 ``flow create`` validates and creates the specified flow rule. It is bound
3742 to ``rte_flow_create()``::
3744 flow create {port_id}
3745 [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3746 [tunnel_set {tunnel_id}] [tunnel_match {tunnel_id}]
3747 pattern {item} [/ {item} [...]] / end
3748 actions {action} [/ {action} [...]] / end
3750 If successful, it will return a flow rule ID usable with other commands::
3752 Flow rule #[...] created
3754 Otherwise it will show an error message of the form::
3756 Caught error type [...] ([...]): [...]
3758 Parameters describe in the following order:
3760 - Attributes (*group*, *priority*, *ingress*, *egress*, *transfer* tokens).
3761 - Tunnel offload specification (tunnel_set, tunnel_match)
3762 - A matching pattern, starting with the *pattern* token and terminated by an
3764 - Actions, starting with the *actions* token and terminated by an *end*
3767 These translate directly to *rte_flow* objects provided as-is to the
3768 underlying functions.
3770 The shortest valid definition only comprises mandatory tokens::
3772 testpmd> flow create 0 pattern end actions end
3774 Note that PMDs may refuse rules that essentially do nothing such as this
3777 **All unspecified object values are automatically initialized to 0.**
3779 Enqueueing creation of flow rules
3780 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3782 ``flow queue create`` adds creation operation of a flow rule to a queue.
3783 It is bound to ``rte_flow_async_create()``::
3785 flow queue {port_id} create {queue_id}
3786 [postpone {boolean}] template_table {table_id}
3787 pattern_template {pattern_template_index}
3788 actions_template {actions_template_index}
3789 pattern {item} [/ {item} [...]] / end
3790 actions {action} [/ {action} [...]] / end
3792 If successful, it will return a flow rule ID usable with other commands::
3794 Flow rule #[...] creaion enqueued
3796 Otherwise it will show an error message of the form::
3798 Caught error type [...] ([...]): [...]
3800 This command uses the same pattern items and actions as ``flow create``,
3801 their format is described in `Creating flow rules`_.
3803 ``flow queue pull`` must be called to retrieve the operation status.
3808 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
3809 specified before the ``pattern`` token.
3811 - ``group {group id}``: priority group.
3812 - ``priority {level}``: priority level within group.
3813 - ``ingress``: rule applies to ingress traffic.
3814 - ``egress``: rule applies to egress traffic.
3815 - ``transfer``: apply rule directly to endpoints found in pattern.
3817 Please note that use of ``transfer`` attribute requires that the flow and
3818 its indirect components be managed via so-called ``transfer`` proxy port.
3819 See `show flow transfer proxy port ID for the given port`_ for details.
3821 Each instance of an attribute specified several times overrides the previous
3822 value as shown below (group 4 is used)::
3824 testpmd> flow create 0 group 42 group 24 group 4 [...]
3826 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
3828 While not specifying a direction is an error, some rules may allow both
3831 Most rules affect RX therefore contain the ``ingress`` token::
3833 testpmd> flow create 0 ingress pattern [...]
3838 Indicate tunnel offload rule type
3840 - ``tunnel_set {tunnel_id}``: mark rule as tunnel offload decap_set type.
3841 - ``tunnel_match {tunnel_id}``: mark rule as tunnel offload match type.
3846 A matching pattern starts after the ``pattern`` token. It is made of pattern
3847 items and is terminated by a mandatory ``end`` item.
3849 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
3850 rte_flow_item_type``).
3852 The ``/`` token is used as a separator between pattern items as shown
3855 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
3857 Note that protocol items like these must be stacked from lowest to highest
3858 layer to make sense. For instance, the following rule is either invalid or
3859 unlikely to match any packet::
3861 testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
3863 More information on these restrictions can be found in the *rte_flow*
3866 Several items support additional specification structures, for example
3867 ``ipv4`` allows specifying source and destination addresses as follows::
3869 testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
3870 dst is 10.2.0.0 / end [...]
3872 This rule matches all IPv4 traffic with the specified properties.
3874 In this example, ``src`` and ``dst`` are field names of the underlying
3875 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
3876 in a similar fashion.
3878 The ``is`` token means that the subsequent value must be matched exactly,
3879 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
3880 accordingly. Possible assignment tokens are:
3882 - ``is``: match value perfectly (with full bit-mask).
3883 - ``spec``: match value according to configured bit-mask.
3884 - ``last``: specify upper bound to establish a range.
3885 - ``mask``: specify bit-mask with relevant bits set to one.
3886 - ``prefix``: generate bit-mask with <prefix-length> most-significant bits set to one.
3888 These yield identical results::
3890 ipv4 src is 10.1.1.1
3894 ipv4 src spec 10.1.1.1 src mask 255.255.255.255
3898 ipv4 src spec 10.1.1.1 src prefix 32
3902 ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
3906 ipv4 src is 10.1.1.1 src last 0 # 0 disables range
3908 Inclusive ranges can be defined with ``last``::
3910 ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
3912 Note that ``mask`` affects both ``spec`` and ``last``::
3914 ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
3915 # matches 10.1.0.0 to 10.2.255.255
3917 Properties can be modified multiple times::
3919 ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
3923 ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
3928 This section lists supported pattern items and their attributes, if any.
3930 - ``end``: end list of pattern items.
3932 - ``void``: no-op pattern item.
3934 - ``invert``: perform actions when pattern does not match.
3936 - ``any``: match any protocol for the current layer.
3938 - ``num {unsigned}``: number of layers covered.
3940 - ``pf``: match traffic from/to the physical function.
3942 - ``vf``: match traffic from/to a virtual function ID.
3944 - ``id {unsigned}``: VF ID.
3946 - ``phy_port``: match traffic from/to a specific physical port.
3948 - ``index {unsigned}``: physical port index.
3950 - ``port_id``: match traffic from/to a given DPDK port ID.
3952 - ``id {unsigned}``: DPDK port ID.
3954 - ``mark``: match value set in previously matched flow rule using the mark action.
3956 - ``id {unsigned}``: arbitrary integer value.
3958 - ``raw``: match an arbitrary byte string.
3960 - ``relative {boolean}``: look for pattern after the previous item.
3961 - ``search {boolean}``: search pattern from offset (see also limit).
3962 - ``offset {integer}``: absolute or relative offset for pattern.
3963 - ``limit {unsigned}``: search area limit for start of pattern.
3964 - ``pattern {string}``: byte string to look for.
3965 - ``pattern_hex {string}``: byte string (provided in hexadecimal) to look for.
3967 - ``eth``: match Ethernet header.
3969 - ``dst {MAC-48}``: destination MAC.
3970 - ``src {MAC-48}``: source MAC.
3971 - ``type {unsigned}``: EtherType or TPID.
3973 - ``vlan``: match 802.1Q/ad VLAN tag.
3975 - ``tci {unsigned}``: tag control information.
3976 - ``pcp {unsigned}``: priority code point.
3977 - ``dei {unsigned}``: drop eligible indicator.
3978 - ``vid {unsigned}``: VLAN identifier.
3979 - ``inner_type {unsigned}``: inner EtherType or TPID.
3981 - ``ipv4``: match IPv4 header.
3983 - ``version_ihl {unsigned}``: IPv4 version and IP header length.
3984 - ``tos {unsigned}``: type of service.
3985 - ``ttl {unsigned}``: time to live.
3986 - ``proto {unsigned}``: next protocol ID.
3987 - ``src {ipv4 address}``: source address.
3988 - ``dst {ipv4 address}``: destination address.
3990 - ``ipv6``: match IPv6 header.
3992 - ``tc {unsigned}``: traffic class.
3993 - ``flow {unsigned}``: flow label.
3994 - ``proto {unsigned}``: protocol (next header).
3995 - ``hop {unsigned}``: hop limit.
3996 - ``src {ipv6 address}``: source address.
3997 - ``dst {ipv6 address}``: destination address.
3999 - ``icmp``: match ICMP header.
4001 - ``type {unsigned}``: ICMP packet type.
4002 - ``code {unsigned}``: ICMP packet code.
4004 - ``udp``: match UDP header.
4006 - ``src {unsigned}``: UDP source port.
4007 - ``dst {unsigned}``: UDP destination port.
4009 - ``tcp``: match TCP header.
4011 - ``src {unsigned}``: TCP source port.
4012 - ``dst {unsigned}``: TCP destination port.
4014 - ``sctp``: match SCTP header.
4016 - ``src {unsigned}``: SCTP source port.
4017 - ``dst {unsigned}``: SCTP destination port.
4018 - ``tag {unsigned}``: validation tag.
4019 - ``cksum {unsigned}``: checksum.
4021 - ``vxlan``: match VXLAN header.
4023 - ``vni {unsigned}``: VXLAN identifier.
4024 - ``last_rsvd {unsigned}``: VXLAN last reserved 8-bits.
4026 - ``e_tag``: match IEEE 802.1BR E-Tag header.
4028 - ``grp_ecid_b {unsigned}``: GRP and E-CID base.
4030 - ``nvgre``: match NVGRE header.
4032 - ``tni {unsigned}``: virtual subnet ID.
4034 - ``mpls``: match MPLS header.
4036 - ``label {unsigned}``: MPLS label.
4038 - ``gre``: match GRE header.
4040 - ``protocol {unsigned}``: protocol type.
4042 - ``gre_key``: match GRE optional key field.
4044 - ``value {unsigned}``: key value.
4046 - ``gre_option``: match GRE optional fields(checksum/key/sequence).
4048 - ``checksum {unsigned}``: checksum value.
4049 - ``key {unsigned}``: key value.
4050 - ``sequence {unsigned}``: sequence number value.
4052 - ``fuzzy``: fuzzy pattern match, expect faster than default.
4054 - ``thresh {unsigned}``: accuracy threshold.
4056 - ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header.
4058 - ``teid {unsigned}``: tunnel endpoint identifier.
4060 - ``geneve``: match GENEVE header.
4062 - ``vni {unsigned}``: virtual network identifier.
4063 - ``protocol {unsigned}``: protocol type.
4065 - ``geneve-opt``: match GENEVE header option.
4067 - ``class {unsigned}``: GENEVE option class.
4068 - ``type {unsigned}``: GENEVE option type.
4069 - ``length {unsigned}``: GENEVE option length in 32-bit words.
4070 - ``data {hex string}``: GENEVE option data, the length is defined by
4073 - ``vxlan-gpe``: match VXLAN-GPE header.
4075 - ``vni {unsigned}``: VXLAN-GPE identifier.
4077 - ``arp_eth_ipv4``: match ARP header for Ethernet/IPv4.
4079 - ``sha {MAC-48}``: sender hardware address.
4080 - ``spa {ipv4 address}``: sender IPv4 address.
4081 - ``tha {MAC-48}``: target hardware address.
4082 - ``tpa {ipv4 address}``: target IPv4 address.
4084 - ``ipv6_ext``: match presence of any IPv6 extension header.
4086 - ``next_hdr {unsigned}``: next header.
4088 - ``icmp6``: match any ICMPv6 header.
4090 - ``type {unsigned}``: ICMPv6 type.
4091 - ``code {unsigned}``: ICMPv6 code.
4093 - ``icmp6_nd_ns``: match ICMPv6 neighbor discovery solicitation.
4095 - ``target_addr {ipv6 address}``: target address.
4097 - ``icmp6_nd_na``: match ICMPv6 neighbor discovery advertisement.
4099 - ``target_addr {ipv6 address}``: target address.
4101 - ``icmp6_nd_opt``: match presence of any ICMPv6 neighbor discovery option.
4103 - ``type {unsigned}``: ND option type.
4105 - ``icmp6_nd_opt_sla_eth``: match ICMPv6 neighbor discovery source Ethernet
4106 link-layer address option.
4108 - ``sla {MAC-48}``: source Ethernet LLA.
4110 - ``icmp6_nd_opt_tla_eth``: match ICMPv6 neighbor discovery target Ethernet
4111 link-layer address option.
4113 - ``tla {MAC-48}``: target Ethernet LLA.
4115 - ``meta``: match application specific metadata.
4117 - ``data {unsigned}``: metadata value.
4119 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
4121 - ``pdu_type {unsigned}``: PDU type.
4123 - ``qfi {unsigned}``: QoS flow identifier.
4125 - ``pppoes``, ``pppoed``: match PPPoE header.
4127 - ``session_id {unsigned}``: session identifier.
4129 - ``pppoe_proto_id``: match PPPoE session protocol identifier.
4131 - ``proto_id {unsigned}``: PPP protocol identifier.
4133 - ``l2tpv3oip``: match L2TPv3 over IP header.
4135 - ``session_id {unsigned}``: L2TPv3 over IP session identifier.
4137 - ``ah``: match AH header.
4139 - ``spi {unsigned}``: security parameters index.
4141 - ``pfcp``: match PFCP header.
4143 - ``s_field {unsigned}``: S field.
4144 - ``seid {unsigned}``: session endpoint identifier.
4146 - ``integrity``: match packet integrity.
4148 - ``level {unsigned}``: Packet encapsulation level the item should
4149 apply to. See rte_flow_action_rss for details.
4150 - ``value {unsigned}``: A bitmask that specify what packet elements
4151 must be matched for integrity.
4153 - ``conntrack``: match conntrack state.
4155 - ``port_representor``: match traffic entering the embedded switch from the given ethdev
4157 - ``port_id {unsigned}``: ethdev port ID
4159 - ``represented_port``: match traffic entering the embedded switch from
4160 the entity represented by the given ethdev
4162 - ``ethdev_port_id {unsigned}``: ethdev port ID
4164 - ``l2tpv2``: match L2TPv2 header.
4166 - ``length {unsigned}``: L2TPv2 option length.
4167 - ``tunnel_id {unsigned}``: L2TPv2 tunnel identifier.
4168 - ``session_id {unsigned}``: L2TPv2 session identifier.
4169 - ``ns {unsigned}``: L2TPv2 option ns.
4170 - ``nr {unsigned}``: L2TPv2 option nr.
4171 - ``offset_size {unsigned}``: L2TPv2 option offset.
4173 - ``ppp``: match PPP header.
4175 - ``addr {unsigned}``: PPP address.
4176 - ``ctrl {unsigned}``: PPP control.
4177 - ``proto_id {unsigned}``: PPP protocol identifier.
4182 A list of actions starts after the ``actions`` token in the same fashion as
4183 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
4184 terminated by a mandatory ``end`` action.
4186 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
4187 rte_flow_action_type``).
4189 Dropping all incoming UDPv4 packets can be expressed as follows::
4191 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
4194 Several actions have configurable properties which must be specified when
4195 there is no valid default value. For example, ``queue`` requires a target
4198 This rule redirects incoming UDPv4 traffic to queue index 6::
4200 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
4201 actions queue index 6 / end
4203 While this one could be rejected by PMDs (unspecified queue index)::
4205 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
4208 As defined by *rte_flow*, the list is not ordered, all actions of a given
4209 rule are performed simultaneously. These are equivalent::
4211 queue index 6 / void / mark id 42 / end
4215 void / mark id 42 / queue index 6 / end
4217 All actions in a list should have different types, otherwise only the last
4218 action of a given type is taken into account::
4220 queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
4224 drop / drop / drop / end # drop is performed only once
4228 mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
4230 Considering they are performed simultaneously, opposite and overlapping
4231 actions can sometimes be combined when the end result is unambiguous::
4233 drop / queue index 6 / end # drop has no effect
4237 queue index 6 / rss queues 6 7 8 / end # queue has no effect
4241 drop / passthru / end # drop has no effect
4243 Note that PMDs may still refuse such combinations.
4248 This section lists supported actions and their attributes, if any.
4250 - ``end``: end list of actions.
4252 - ``void``: no-op action.
4254 - ``passthru``: let subsequent rule process matched packets.
4256 - ``jump``: redirect traffic to group on device.
4258 - ``group {unsigned}``: group to redirect to.
4260 - ``mark``: attach 32 bit value to packets.
4262 - ``id {unsigned}``: 32 bit value to return with packets.
4264 - ``flag``: flag packets.
4266 - ``queue``: assign packets to a given queue index.
4268 - ``index {unsigned}``: queue index to use.
4270 - ``drop``: drop packets (note: passthru has priority).
4272 - ``count``: enable counters for this rule.
4274 - ``rss``: spread packets among several queues.
4276 - ``func {hash function}``: RSS hash function to apply, allowed tokens are
4277 ``toeplitz``, ``simple_xor``, ``symmetric_toeplitz`` and ``default``.
4279 - ``level {unsigned}``: encapsulation level for ``types``.
4281 - ``types [{RSS hash type} [...]] end``: specific RSS hash types.
4282 Note that an empty list does not disable RSS but instead requests
4283 unspecified "best-effort" settings.
4285 - ``key {string}``: RSS hash key, overrides ``key_len``.
4287 - ``key_len {unsigned}``: RSS hash key length in bytes, can be used in
4288 conjunction with ``key`` to pad or truncate it.
4290 - ``queues [{unsigned} [...]] end``: queue indices to use.
4292 - ``pf``: direct traffic to physical function.
4294 - ``vf``: direct traffic to a virtual function ID.
4296 - ``original {boolean}``: use original VF ID if possible.
4297 - ``id {unsigned}``: VF ID.
4299 - ``phy_port``: direct packets to physical port index.
4301 - ``original {boolean}``: use original port index if possible.
4302 - ``index {unsigned}``: physical port index.
4304 - ``port_id``: direct matching traffic to a given DPDK port ID.
4306 - ``original {boolean}``: use original DPDK port ID if possible.
4307 - ``id {unsigned}``: DPDK port ID.
4309 - ``of_set_mpls_ttl``: OpenFlow's ``OFPAT_SET_MPLS_TTL``.
4311 - ``mpls_ttl``: MPLS TTL.
4313 - ``of_dec_mpls_ttl``: OpenFlow's ``OFPAT_DEC_MPLS_TTL``.
4315 - ``of_set_nw_ttl``: OpenFlow's ``OFPAT_SET_NW_TTL``.
4317 - ``nw_ttl``: IP TTL.
4319 - ``of_dec_nw_ttl``: OpenFlow's ``OFPAT_DEC_NW_TTL``.
4321 - ``of_copy_ttl_out``: OpenFlow's ``OFPAT_COPY_TTL_OUT``.
4323 - ``of_copy_ttl_in``: OpenFlow's ``OFPAT_COPY_TTL_IN``.
4325 - ``of_pop_vlan``: OpenFlow's ``OFPAT_POP_VLAN``.
4327 - ``of_push_vlan``: OpenFlow's ``OFPAT_PUSH_VLAN``.
4329 - ``ethertype``: Ethertype.
4331 - ``of_set_vlan_vid``: OpenFlow's ``OFPAT_SET_VLAN_VID``.
4333 - ``vlan_vid``: VLAN id.
4335 - ``of_set_vlan_pcp``: OpenFlow's ``OFPAT_SET_VLAN_PCP``.
4337 - ``vlan_pcp``: VLAN priority.
4339 - ``of_pop_mpls``: OpenFlow's ``OFPAT_POP_MPLS``.
4341 - ``ethertype``: Ethertype.
4343 - ``of_push_mpls``: OpenFlow's ``OFPAT_PUSH_MPLS``.
4345 - ``ethertype``: Ethertype.
4347 - ``vxlan_encap``: Performs a VXLAN encapsulation, outer layer configuration
4348 is done through `Config VXLAN Encap outer layers`_.
4350 - ``vxlan_decap``: Performs a decapsulation action by stripping all headers of
4351 the VXLAN tunnel network overlay from the matched flow.
4353 - ``nvgre_encap``: Performs a NVGRE encapsulation, outer layer configuration
4354 is done through `Config NVGRE Encap outer layers`_.
4356 - ``nvgre_decap``: Performs a decapsulation action by stripping all headers of
4357 the NVGRE tunnel network overlay from the matched flow.
4359 - ``l2_encap``: Performs a L2 encapsulation, L2 configuration
4360 is done through `Config L2 Encap`_.
4362 - ``l2_decap``: Performs a L2 decapsulation, L2 configuration
4363 is done through `Config L2 Decap`_.
4365 - ``mplsogre_encap``: Performs a MPLSoGRE encapsulation, outer layer
4366 configuration is done through `Config MPLSoGRE Encap outer layers`_.
4368 - ``mplsogre_decap``: Performs a MPLSoGRE decapsulation, outer layer
4369 configuration is done through `Config MPLSoGRE Decap outer layers`_.
4371 - ``mplsoudp_encap``: Performs a MPLSoUDP encapsulation, outer layer
4372 configuration is done through `Config MPLSoUDP Encap outer layers`_.
4374 - ``mplsoudp_decap``: Performs a MPLSoUDP decapsulation, outer layer
4375 configuration is done through `Config MPLSoUDP Decap outer layers`_.
4377 - ``set_ipv4_src``: Set a new IPv4 source address in the outermost IPv4 header.
4379 - ``ipv4_addr``: New IPv4 source address.
4381 - ``set_ipv4_dst``: Set a new IPv4 destination address in the outermost IPv4
4384 - ``ipv4_addr``: New IPv4 destination address.
4386 - ``set_ipv6_src``: Set a new IPv6 source address in the outermost IPv6 header.
4388 - ``ipv6_addr``: New IPv6 source address.
4390 - ``set_ipv6_dst``: Set a new IPv6 destination address in the outermost IPv6
4393 - ``ipv6_addr``: New IPv6 destination address.
4395 - ``set_tp_src``: Set a new source port number in the outermost TCP/UDP
4398 - ``port``: New TCP/UDP source port number.
4400 - ``set_tp_dst``: Set a new destination port number in the outermost TCP/UDP
4403 - ``port``: New TCP/UDP destination port number.
4405 - ``mac_swap``: Swap the source and destination MAC addresses in the outermost
4408 - ``dec_ttl``: Performs a decrease TTL value action
4410 - ``set_ttl``: Set TTL value with specified value
4411 - ``ttl_value {unsigned}``: The new TTL value to be set
4413 - ``set_mac_src``: set source MAC address
4415 - ``mac_addr {MAC-48}``: new source MAC address
4417 - ``set_mac_dst``: set destination MAC address
4419 - ``mac_addr {MAC-48}``: new destination MAC address
4421 - ``inc_tcp_seq``: Increase sequence number in the outermost TCP header.
4423 - ``value {unsigned}``: Value to increase TCP sequence number by.
4425 - ``dec_tcp_seq``: Decrease sequence number in the outermost TCP header.
4427 - ``value {unsigned}``: Value to decrease TCP sequence number by.
4429 - ``inc_tcp_ack``: Increase acknowledgment number in the outermost TCP header.
4431 - ``value {unsigned}``: Value to increase TCP acknowledgment number by.
4433 - ``dec_tcp_ack``: Decrease acknowledgment number in the outermost TCP header.
4435 - ``value {unsigned}``: Value to decrease TCP acknowledgment number by.
4437 - ``set_ipv4_dscp``: Set IPv4 DSCP value with specified value
4439 - ``dscp_value {unsigned}``: The new DSCP value to be set
4441 - ``set_ipv6_dscp``: Set IPv6 DSCP value with specified value
4443 - ``dscp_value {unsigned}``: The new DSCP value to be set
4445 - ``indirect``: Use indirect action created via
4446 ``flow indirect_action {port_id} create``
4448 - ``indirect_action_id {unsigned}``: Indirect action ID to use
4450 - ``color``: Color the packet to reflect the meter color result
4452 - ``type {value}``: Set color type with specified value(green/yellow/red)
4454 - ``port_representor``: at embedded switch level, send matching traffic to
4457 - ``port_id {unsigned}``: ethdev port ID
4459 - ``represented_port``: at embedded switch level, send matching traffic to
4460 the entity represented by the given ethdev
4462 - ``ethdev_port_id {unsigned}``: ethdev port ID
4464 Destroying flow rules
4465 ~~~~~~~~~~~~~~~~~~~~~
4467 ``flow destroy`` destroys one or more rules from their rule ID (as returned
4468 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
4469 times as necessary::
4471 flow destroy {port_id} rule {rule_id} [...]
4473 If successful, it will show::
4475 Flow rule #[...] destroyed
4477 It does not report anything for rule IDs that do not exist. The usual error
4478 message is shown when a rule cannot be destroyed::
4480 Caught error type [...] ([...]): [...]
4482 ``flow flush`` destroys all rules on a device and does not take extra
4483 arguments. It is bound to ``rte_flow_flush()``::
4485 flow flush {port_id}
4487 Any errors are reported as above.
4489 Creating several rules and destroying them::
4491 testpmd> flow create 0 ingress pattern eth / ipv6 / end
4492 actions queue index 2 / end
4493 Flow rule #0 created
4494 testpmd> flow create 0 ingress pattern eth / ipv4 / end
4495 actions queue index 3 / end
4496 Flow rule #1 created
4497 testpmd> flow destroy 0 rule 0 rule 1
4498 Flow rule #1 destroyed
4499 Flow rule #0 destroyed
4502 The same result can be achieved using ``flow flush``::
4504 testpmd> flow create 0 ingress pattern eth / ipv6 / end
4505 actions queue index 2 / end
4506 Flow rule #0 created
4507 testpmd> flow create 0 ingress pattern eth / ipv4 / end
4508 actions queue index 3 / end
4509 Flow rule #1 created
4510 testpmd> flow flush 0
4513 Non-existent rule IDs are ignored::
4515 testpmd> flow create 0 ingress pattern eth / ipv6 / end
4516 actions queue index 2 / end
4517 Flow rule #0 created
4518 testpmd> flow create 0 ingress pattern eth / ipv4 / end
4519 actions queue index 3 / end
4520 Flow rule #1 created
4521 testpmd> flow destroy 0 rule 42 rule 10 rule 2
4523 testpmd> flow destroy 0 rule 0
4524 Flow rule #0 destroyed
4527 Enqueueing destruction of flow rules
4528 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4530 ``flow queue destroy`` adds destruction operations to destroy one or more rules
4531 from their rule ID (as returned by ``flow queue create``) to a queue,
4532 this command calls ``rte_flow_async_destroy()`` as many times as necessary::
4534 flow queue {port_id} destroy {queue_id}
4535 [postpone {boolean}] rule {rule_id} [...]
4537 If successful, it will show::
4539 Flow rule #[...] destruction enqueued
4541 It does not report anything for rule IDs that do not exist. The usual error
4542 message is shown when a rule cannot be destroyed::
4544 Caught error type [...] ([...]): [...]
4546 ``flow queue pull`` must be called to retrieve the operation status.
4551 ``flow query`` queries a specific action of a flow rule having that
4552 ability. Such actions collect information that can be reported using this
4553 command. It is bound to ``rte_flow_query()``::
4555 flow query {port_id} {rule_id} {action}
4557 If successful, it will display either the retrieved data for known actions
4558 or the following message::
4560 Cannot display result for action type [...] ([...])
4562 Otherwise, it will complain either that the rule does not exist or that some
4565 Flow rule #[...] not found
4569 Caught error type [...] ([...]): [...]
4571 Currently only the ``count`` action is supported. This action reports the
4572 number of packets that hit the flow rule and the total number of bytes. Its
4573 output has the following format::
4576 hits_set: [...] # whether "hits" contains a valid value
4577 bytes_set: [...] # whether "bytes" contains a valid value
4578 hits: [...] # number of packets
4579 bytes: [...] # number of bytes
4581 Querying counters for TCPv6 packets redirected to queue 6::
4583 testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
4584 actions queue index 6 / count / end
4585 Flow rule #4 created
4586 testpmd> flow query 0 4 count
4597 ``flow list`` lists existing flow rules sorted by priority and optionally
4598 filtered by group identifiers::
4600 flow list {port_id} [group {group_id}] [...]
4602 This command only fails with the following message if the device does not
4607 Output consists of a header line followed by a short description of each
4608 flow rule, one per line. There is no output at all when no flow rules are
4609 configured on the device::
4611 ID Group Prio Attr Rule
4612 [...] [...] [...] [...] [...]
4614 ``Attr`` column flags:
4616 - ``i`` for ``ingress``.
4617 - ``e`` for ``egress``.
4619 Creating several flow rules and listing them::
4621 testpmd> flow create 0 ingress pattern eth / ipv4 / end
4622 actions queue index 6 / end
4623 Flow rule #0 created
4624 testpmd> flow create 0 ingress pattern eth / ipv6 / end
4625 actions queue index 2 / end
4626 Flow rule #1 created
4627 testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
4628 actions rss queues 6 7 8 end / end
4629 Flow rule #2 created
4630 testpmd> flow list 0
4631 ID Group Prio Attr Rule
4632 0 0 0 i- ETH IPV4 => QUEUE
4633 1 0 0 i- ETH IPV6 => QUEUE
4634 2 0 5 i- ETH IPV4 UDP => RSS
4637 Rules are sorted by priority (i.e. group ID first, then priority level)::
4639 testpmd> flow list 1
4640 ID Group Prio Attr Rule
4641 0 0 0 i- ETH => COUNT
4642 6 0 500 i- ETH IPV6 TCP => DROP COUNT
4643 5 0 1000 i- ETH IPV6 ICMP => QUEUE
4644 1 24 0 i- ETH IPV4 UDP => QUEUE
4645 4 24 10 i- ETH IPV4 TCP => DROP
4646 3 24 20 i- ETH IPV4 => DROP
4647 2 24 42 i- ETH IPV4 UDP => QUEUE
4648 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE
4651 Output can be limited to specific groups::
4653 testpmd> flow list 1 group 0 group 63
4654 ID Group Prio Attr Rule
4655 0 0 0 i- ETH => COUNT
4656 6 0 500 i- ETH IPV6 TCP => DROP COUNT
4657 5 0 1000 i- ETH IPV6 ICMP => QUEUE
4658 7 63 0 i- ETH IPV6 UDP VXLAN => MARK QUEUE
4661 Toggling isolated mode
4662 ~~~~~~~~~~~~~~~~~~~~~~
4664 ``flow isolate`` can be used to tell the underlying PMD that ingress traffic
4665 must only be injected from the defined flow rules; that no default traffic
4666 is expected outside those rules and the driver is free to assign more
4667 resources to handle them. It is bound to ``rte_flow_isolate()``::
4669 flow isolate {port_id} {boolean}
4671 If successful, enabling or disabling isolated mode shows either::
4673 Ingress traffic on port [...]
4674 is now restricted to the defined flow rules
4678 Ingress traffic on port [...]
4679 is not restricted anymore to the defined flow rules
4681 Otherwise, in case of error::
4683 Caught error type [...] ([...]): [...]
4685 Mainly due to its side effects, PMDs supporting this mode may not have the
4686 ability to toggle it more than once without reinitializing affected ports
4687 first (e.g. by exiting testpmd).
4689 Enabling isolated mode::
4691 testpmd> flow isolate 0 true
4692 Ingress traffic on port 0 is now restricted to the defined flow rules
4695 Disabling isolated mode::
4697 testpmd> flow isolate 0 false
4698 Ingress traffic on port 0 is not restricted anymore to the defined flow rules
4701 Dumping HW internal information
4702 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4704 ``flow dump`` dumps the hardware's internal representation information of
4705 all flows. It is bound to ``rte_flow_dev_dump()``::
4707 flow dump {port_id} {output_file}
4709 If successful, it will show::
4713 Otherwise, it will complain error occurred::
4715 Caught error type [...] ([...]): [...]
4717 Listing and destroying aged flow rules
4718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4720 ``flow aged`` simply lists aged flow rules be get from api ``rte_flow_get_aged_flows``,
4721 and ``destroy`` parameter can be used to destroy those flow rules in PMD.
4723 flow aged {port_id} [destroy]
4725 Listing current aged flow rules::
4727 testpmd> flow aged 0
4728 Port 0 total aged flows: 0
4729 testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.14 / end
4730 actions age timeout 5 / queue index 0 / end
4731 Flow rule #0 created
4732 testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.15 / end
4733 actions age timeout 4 / queue index 0 / end
4734 Flow rule #1 created
4735 testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.16 / end
4736 actions age timeout 2 / queue index 0 / end
4737 Flow rule #2 created
4738 testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.17 / end
4739 actions age timeout 3 / queue index 0 / end
4740 Flow rule #3 created
4743 Aged Rules are simply list as command ``flow list {port_id}``, but strip the detail rule
4744 information, all the aged flows are sorted by the longest timeout time. For example, if
4745 those rules be configured in the same time, ID 2 will be the first aged out rule, the next
4746 will be ID 3, ID 1, ID 0::
4748 testpmd> flow aged 0
4749 Port 0 total aged flows: 4
4756 If attach ``destroy`` parameter, the command will destroy all the list aged flow rules.
4758 testpmd> flow aged 0 destroy
4759 Port 0 total aged flows: 4
4766 Flow rule #2 destroyed
4767 Flow rule #3 destroyed
4768 Flow rule #1 destroyed
4769 Flow rule #0 destroyed
4770 4 flows be destroyed
4771 testpmd> flow aged 0
4772 Port 0 total aged flows: 0
4774 Creating indirect actions
4775 ~~~~~~~~~~~~~~~~~~~~~~~~~
4777 ``flow indirect_action {port_id} create`` creates indirect action with optional
4778 indirect action ID. It is bound to ``rte_flow_action_handle_create()``::
4780 flow indirect_action {port_id} create [action_id {indirect_action_id}]
4781 [ingress] [egress] [transfer] action {action} / end
4783 If successful, it will show::
4785 Indirect action #[...] created
4787 Otherwise, it will complain either that indirect action already exists or that
4788 some error occurred::
4790 Indirect action #[...] is already assigned, delete it first
4794 Caught error type [...] ([...]): [...]
4796 Create indirect rss action with id 100 to queues 1 and 2 on port 0::
4798 testpmd> flow indirect_action 0 create action_id 100 \
4799 ingress action rss queues 1 2 end / end
4801 Create indirect rss action with id assigned by testpmd to queues 1 and 2 on
4804 testpmd> flow indirect_action 0 create action_id \
4805 ingress action rss queues 0 1 end / end
4807 Enqueueing creation of indirect actions
4808 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4810 ``flow queue indirect_action create`` adds creation operation of an indirect
4811 action to a queue. It is bound to ``rte_flow_async_action_handle_create()``::
4813 flow queue {port_id} create {queue_id} [postpone {boolean}]
4814 table {table_id} item_template {item_template_id}
4815 action_template {action_template_id}
4816 pattern {item} [/ {item} [...]] / end
4817 actions {action} [/ {action} [...]] / end
4819 If successful, it will show::
4821 Indirect action #[...] creation queued
4823 Otherwise it will show an error message of the form::
4825 Caught error type [...] ([...]): [...]
4827 This command uses the same parameters as ``flow indirect_action create``,
4828 described in `Creating indirect actions`_.
4830 ``flow queue pull`` must be called to retrieve the operation status.
4832 Updating indirect actions
4833 ~~~~~~~~~~~~~~~~~~~~~~~~~
4835 ``flow indirect_action {port_id} update`` updates configuration of the indirect
4836 action from its indirect action ID (as returned by
4837 ``flow indirect_action {port_id} create``). It is bound to
4838 ``rte_flow_action_handle_update()``::
4840 flow indirect_action {port_id} update {indirect_action_id}
4841 action {action} / end
4843 If successful, it will show::
4845 Indirect action #[...] updated
4847 Otherwise, it will complain either that indirect action not found or that some
4850 Failed to find indirect action #[...] on port [...]
4854 Caught error type [...] ([...]): [...]
4856 Update indirect rss action having id 100 on port 0 with rss to queues 0 and 3
4857 (in create example above rss queues were 1 and 2)::
4859 testpmd> flow indirect_action 0 update 100 action rss queues 0 3 end / end
4861 Enqueueing update of indirect actions
4862 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4864 ``flow queue indirect_action update`` adds update operation for an indirect
4865 action to a queue. It is bound to ``rte_flow_async_action_handle_update()``::
4867 flow queue {port_id} indirect_action {queue_id} update
4868 {indirect_action_id} [postpone {boolean}] action {action} / end
4870 If successful, it will show::
4872 Indirect action #[...] update queued
4874 Otherwise it will show an error message of the form::
4876 Caught error type [...] ([...]): [...]
4878 ``flow queue pull`` must be called to retrieve the operation status.
4880 Destroying indirect actions
4881 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4883 ``flow indirect_action {port_id} destroy`` destroys one or more indirect actions
4884 from their indirect action IDs (as returned by
4885 ``flow indirect_action {port_id} create``). It is bound to
4886 ``rte_flow_action_handle_destroy()``::
4888 flow indirect_action {port_id} destroy action_id {indirect_action_id} [...]
4890 If successful, it will show::
4892 Indirect action #[...] destroyed
4894 It does not report anything for indirect action IDs that do not exist.
4895 The usual error message is shown when a indirect action cannot be destroyed::
4897 Caught error type [...] ([...]): [...]
4899 Destroy indirect actions having id 100 & 101::
4901 testpmd> flow indirect_action 0 destroy action_id 100 action_id 101
4903 Enqueueing destruction of indirect actions
4904 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4906 ``flow queue indirect_action destroy`` adds destruction operation to destroy
4907 one or more indirect actions from their indirect action IDs (as returned by
4908 ``flow queue {port_id} indirect_action {queue_id} create``) to a queue.
4909 It is bound to ``rte_flow_async_action_handle_destroy()``::
4911 flow queue {port_id} indirect_action {queue_id} destroy
4912 [postpone {boolean}] action_id {indirect_action_id} [...]
4914 If successful, it will show::
4916 Indirect action #[...] destruction queued
4918 Otherwise it will show an error message of the form::
4920 Caught error type [...] ([...]): [...]
4922 ``flow queue pull`` must be called to retrieve the operation status.
4924 Query indirect actions
4925 ~~~~~~~~~~~~~~~~~~~~~~
4927 ``flow indirect_action {port_id} query`` queries the indirect action from its
4928 indirect action ID (as returned by ``flow indirect_action {port_id} create``).
4929 It is bound to ``rte_flow_action_handle_query()``::
4931 flow indirect_action {port_id} query {indirect_action_id}
4933 Currently only rss indirect action supported. If successful, it will show::
4935 Indirect RSS action:
4938 Otherwise, it will complain either that indirect action not found or that some
4941 Failed to find indirect action #[...] on port [...]
4945 Caught error type [...] ([...]): [...]
4947 Query indirect action having id 100::
4949 testpmd> flow indirect_action 0 query 100
4951 Sample QinQ flow rules
4952 ~~~~~~~~~~~~~~~~~~~~~~
4954 Before creating QinQ rule(s) the following commands should be issued to enable QinQ::
4956 testpmd> port stop 0
4957 testpmd> vlan set extend on 0
4959 The above command sets the inner and outer TPID's to 0x8100.
4961 To change the TPID's the following commands should be used::
4963 testpmd> vlan set outer tpid 0x88A8 0
4964 testpmd> vlan set inner tpid 0x8100 0
4965 testpmd> port start 0
4967 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM.
4971 testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 /
4972 vlan tci is 456 / end actions vf id 1 / queue index 0 / end
4973 Flow rule #0 validated
4975 testpmd> flow create 0 ingress pattern eth / vlan tci is 4 /
4976 vlan tci is 456 / end actions vf id 123 / queue index 0 / end
4977 Flow rule #0 created
4979 testpmd> flow list 0
4980 ID Group Prio Attr Rule
4981 0 0 0 i- ETH VLAN VLAN=>VF QUEUE
4983 Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host.
4987 testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 /
4988 vlan tci is 654 / end actions pf / queue index 0 / end
4989 Flow rule #1 validated
4991 testpmd> flow create 0 ingress pattern eth / vlan tci is 321 /
4992 vlan tci is 654 / end actions pf / queue index 1 / end
4993 Flow rule #1 created
4995 testpmd> flow list 0
4996 ID Group Prio Attr Rule
4997 0 0 0 i- ETH VLAN VLAN=>VF QUEUE
4998 1 0 0 i- ETH VLAN VLAN=>PF QUEUE
5000 Sample VXLAN flow rules
5001 ~~~~~~~~~~~~~~~~~~~~~~~
5003 Before creating VXLAN rule(s), the UDP port should be added for VXLAN packet
5006 testpmd> rx_vxlan_port add 4789 0
5008 Create VXLAN rules on port 0 to steer traffic to PF queues.
5012 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan /
5013 eth dst is 00:11:22:33:44:55 / end actions pf / queue index 1 / end
5014 Flow rule #0 created
5016 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan vni is 3 /
5017 eth dst is 00:11:22:33:44:55 / end actions pf / queue index 2 / end
5018 Flow rule #1 created
5020 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan /
5021 eth dst is 00:11:22:33:44:55 / vlan tci is 10 / end actions pf /
5023 Flow rule #2 created
5025 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan vni is 5 /
5026 eth dst is 00:11:22:33:44:55 / vlan tci is 20 / end actions pf /
5028 Flow rule #3 created
5030 testpmd> flow create 0 ingress pattern eth dst is 00:00:00:00:01:00 / ipv4 /
5031 udp / vxlan vni is 6 / eth dst is 00:11:22:33:44:55 / end actions pf /
5033 Flow rule #4 created
5035 testpmd> flow list 0
5036 ID Group Prio Attr Rule
5037 0 0 0 i- ETH IPV4 UDP VXLAN ETH => QUEUE
5038 1 0 0 i- ETH IPV4 UDP VXLAN ETH => QUEUE
5039 2 0 0 i- ETH IPV4 UDP VXLAN ETH VLAN => QUEUE
5040 3 0 0 i- ETH IPV4 UDP VXLAN ETH VLAN => QUEUE
5041 4 0 0 i- ETH IPV4 UDP VXLAN ETH => QUEUE
5043 Sample VXLAN encapsulation rule
5044 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5046 VXLAN encapsulation outer layer has default value pre-configured in testpmd
5047 source code, those can be changed by using the following commands
5049 IPv4 VXLAN outer header::
5051 testpmd> set vxlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src 127.0.0.1
5052 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5053 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5056 testpmd> set vxlan-with-vlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src
5057 127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34 eth-src 11:11:11:11:11:11
5058 eth-dst 22:22:22:22:22:22
5059 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5062 testpmd> set vxlan-tos-ttl ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-tos 0
5063 ip-ttl 255 ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
5064 eth-dst 22:22:22:22:22:22
5065 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5068 IPv6 VXLAN outer header::
5070 testpmd> set vxlan ip-version ipv6 vni 4 udp-src 4 udp-dst 4 ip-src ::1
5071 ip-dst ::2222 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5072 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5075 testpmd> set vxlan-with-vlan ip-version ipv6 vni 4 udp-src 4 udp-dst 4
5076 ip-src ::1 ip-dst ::2222 vlan-tci 34 eth-src 11:11:11:11:11:11
5077 eth-dst 22:22:22:22:22:22
5078 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5081 testpmd> set vxlan-tos-ttl ip-version ipv6 vni 4 udp-src 4 udp-dst 4
5082 ip-tos 0 ip-ttl 255 ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
5083 eth-dst 22:22:22:22:22:22
5084 testpmd> flow create 0 ingress pattern end actions vxlan_encap /
5087 Sample NVGRE encapsulation rule
5088 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5090 NVGRE encapsulation outer layer has default value pre-configured in testpmd
5091 source code, those can be changed by using the following commands
5093 IPv4 NVGRE outer header::
5095 testpmd> set nvgre ip-version ipv4 tni 4 ip-src 127.0.0.1 ip-dst 128.0.0.1
5096 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5097 testpmd> flow create 0 ingress pattern end actions nvgre_encap /
5100 testpmd> set nvgre-with-vlan ip-version ipv4 tni 4 ip-src 127.0.0.1
5101 ip-dst 128.0.0.1 vlan-tci 34 eth-src 11:11:11:11:11:11
5102 eth-dst 22:22:22:22:22:22
5103 testpmd> flow create 0 ingress pattern end actions nvgre_encap /
5106 IPv6 NVGRE outer header::
5108 testpmd> set nvgre ip-version ipv6 tni 4 ip-src ::1 ip-dst ::2222
5109 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5110 testpmd> flow create 0 ingress pattern end actions nvgre_encap /
5113 testpmd> set nvgre-with-vlan ip-version ipv6 tni 4 ip-src ::1 ip-dst ::2222
5114 vlan-tci 34 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5115 testpmd> flow create 0 ingress pattern end actions nvgre_encap /
5118 Sample L2 encapsulation rule
5119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5121 L2 encapsulation has default value pre-configured in testpmd
5122 source code, those can be changed by using the following commands
5126 testpmd> set l2_encap ip-version ipv4
5127 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5128 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
5129 mplsoudp_decap / l2_encap / end
5131 L2 with VXLAN header::
5133 testpmd> set l2_encap-with-vlan ip-version ipv4 vlan-tci 34
5134 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5135 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
5136 mplsoudp_decap / l2_encap / end
5138 Sample L2 decapsulation rule
5139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5141 L2 decapsulation has default value pre-configured in testpmd
5142 source code, those can be changed by using the following commands
5146 testpmd> set l2_decap
5147 testpmd> flow create 0 egress pattern eth / end actions l2_decap / mplsoudp_encap /
5150 L2 with VXLAN header::
5152 testpmd> set l2_encap-with-vlan
5153 testpmd> flow create 0 egress pattern eth / end actions l2_encap / mplsoudp_encap /
5156 Sample MPLSoGRE encapsulation rule
5157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5159 MPLSoGRE encapsulation outer layer has default value pre-configured in testpmd
5160 source code, those can be changed by using the following commands
5162 IPv4 MPLSoGRE outer header::
5164 testpmd> set mplsogre_encap ip-version ipv4 label 4
5165 ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
5166 eth-dst 22:22:22:22:22:22
5167 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5168 mplsogre_encap / end
5170 IPv4 MPLSoGRE with VLAN outer header::
5172 testpmd> set mplsogre_encap-with-vlan ip-version ipv4 label 4
5173 ip-src 127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34
5174 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5175 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5176 mplsogre_encap / end
5178 IPv6 MPLSoGRE outer header::
5180 testpmd> set mplsogre_encap ip-version ipv6 mask 4
5181 ip-src ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
5182 eth-dst 22:22:22:22:22:22
5183 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5184 mplsogre_encap / end
5186 IPv6 MPLSoGRE with VLAN outer header::
5188 testpmd> set mplsogre_encap-with-vlan ip-version ipv6 mask 4
5189 ip-src ::1 ip-dst ::2222 vlan-tci 34
5190 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5191 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5192 mplsogre_encap / end
5194 Sample MPLSoGRE decapsulation rule
5195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5197 MPLSoGRE decapsulation outer layer has default value pre-configured in testpmd
5198 source code, those can be changed by using the following commands
5200 IPv4 MPLSoGRE outer header::
5202 testpmd> set mplsogre_decap ip-version ipv4
5203 testpmd> flow create 0 ingress pattern eth / ipv4 / gre / mpls / end actions
5204 mplsogre_decap / l2_encap / end
5206 IPv4 MPLSoGRE with VLAN outer header::
5208 testpmd> set mplsogre_decap-with-vlan ip-version ipv4
5209 testpmd> flow create 0 ingress pattern eth / vlan / ipv4 / gre / mpls / end
5210 actions mplsogre_decap / l2_encap / end
5212 IPv6 MPLSoGRE outer header::
5214 testpmd> set mplsogre_decap ip-version ipv6
5215 testpmd> flow create 0 ingress pattern eth / ipv6 / gre / mpls / end
5216 actions mplsogre_decap / l2_encap / end
5218 IPv6 MPLSoGRE with VLAN outer header::
5220 testpmd> set mplsogre_decap-with-vlan ip-version ipv6
5221 testpmd> flow create 0 ingress pattern eth / vlan / ipv6 / gre / mpls / end
5222 actions mplsogre_decap / l2_encap / end
5224 Sample MPLSoUDP encapsulation rule
5225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5227 MPLSoUDP encapsulation outer layer has default value pre-configured in testpmd
5228 source code, those can be changed by using the following commands
5230 IPv4 MPLSoUDP outer header::
5232 testpmd> set mplsoudp_encap ip-version ipv4 label 4 udp-src 5 udp-dst 10
5233 ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
5234 eth-dst 22:22:22:22:22:22
5235 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5236 mplsoudp_encap / end
5238 IPv4 MPLSoUDP with VLAN outer header::
5240 testpmd> set mplsoudp_encap-with-vlan ip-version ipv4 label 4 udp-src 5
5241 udp-dst 10 ip-src 127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34
5242 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5243 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5244 mplsoudp_encap / end
5246 IPv6 MPLSoUDP outer header::
5248 testpmd> set mplsoudp_encap ip-version ipv6 mask 4 udp-src 5 udp-dst 10
5249 ip-src ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
5250 eth-dst 22:22:22:22:22:22
5251 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5252 mplsoudp_encap / end
5254 IPv6 MPLSoUDP with VLAN outer header::
5256 testpmd> set mplsoudp_encap-with-vlan ip-version ipv6 mask 4 udp-src 5
5257 udp-dst 10 ip-src ::1 ip-dst ::2222 vlan-tci 34
5258 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5259 testpmd> flow create 0 egress pattern eth / end actions l2_decap /
5260 mplsoudp_encap / end
5262 Sample MPLSoUDP decapsulation rule
5263 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5265 MPLSoUDP decapsulation outer layer has default value pre-configured in testpmd
5266 source code, those can be changed by using the following commands
5268 IPv4 MPLSoUDP outer header::
5270 testpmd> set mplsoudp_decap ip-version ipv4
5271 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
5272 mplsoudp_decap / l2_encap / end
5274 IPv4 MPLSoUDP with VLAN outer header::
5276 testpmd> set mplsoudp_decap-with-vlan ip-version ipv4
5277 testpmd> flow create 0 ingress pattern eth / vlan / ipv4 / udp / mpls / end
5278 actions mplsoudp_decap / l2_encap / end
5280 IPv6 MPLSoUDP outer header::
5282 testpmd> set mplsoudp_decap ip-version ipv6
5283 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / mpls / end
5284 actions mplsoudp_decap / l2_encap / end
5286 IPv6 MPLSoUDP with VLAN outer header::
5288 testpmd> set mplsoudp_decap-with-vlan ip-version ipv6
5289 testpmd> flow create 0 ingress pattern eth / vlan / ipv6 / udp / mpls / end
5290 actions mplsoudp_decap / l2_encap / end
5292 Sample Raw encapsulation rule
5293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5295 Raw encapsulation configuration can be set by the following commands
5297 Encapsulating VxLAN::
5299 testpmd> set raw_encap 4 eth src is 10:11:22:33:44:55 / vlan tci is 1
5300 inner_type is 0x0800 / ipv4 / udp dst is 4789 / vxlan vni
5302 testpmd> flow create 0 egress pattern eth / ipv4 / end actions
5303 raw_encap index 4 / end
5305 Sample Raw decapsulation rule
5306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5308 Raw decapsulation configuration can be set by the following commands
5310 Decapsulating VxLAN::
5312 testpmd> set raw_decap eth / ipv4 / udp / vxlan / end_set
5313 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan / eth / ipv4 /
5314 end actions raw_decap / queue index 0 / end
5319 ESP rules can be created by the following commands::
5321 testpmd> flow create 0 ingress pattern eth / ipv4 / esp spi is 1 / end actions
5323 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / esp spi is 1 / end
5324 actions queue index 3 / end
5325 testpmd> flow create 0 ingress pattern eth / ipv6 / esp spi is 1 / end actions
5327 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / esp spi is 1 / end
5328 actions queue index 3 / end
5333 AH rules can be created by the following commands::
5335 testpmd> flow create 0 ingress pattern eth / ipv4 / ah spi is 1 / end actions
5337 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / ah spi is 1 / end
5338 actions queue index 3 / end
5339 testpmd> flow create 0 ingress pattern eth / ipv6 / ah spi is 1 / end actions
5341 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / ah spi is 1 / end
5342 actions queue index 3 / end
5347 PFCP rules can be created by the following commands(s_field need to be 1
5350 testpmd> flow create 0 ingress pattern eth / ipv4 / pfcp s_field is 0 / end
5351 actions queue index 3 / end
5352 testpmd> flow create 0 ingress pattern eth / ipv4 / pfcp s_field is 1
5353 seid is 1 / end actions queue index 3 / end
5354 testpmd> flow create 0 ingress pattern eth / ipv6 / pfcp s_field is 0 / end
5355 actions queue index 3 / end
5356 testpmd> flow create 0 ingress pattern eth / ipv6 / pfcp s_field is 1
5357 seid is 1 / end actions queue index 3 / end
5359 Sample Sampling/Mirroring rules
5360 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5362 Sample/Mirroring rules can be set by the following commands
5364 NIC-RX Sampling rule, the matched ingress packets and sent to the queue 1,
5365 and 50% packets are duplicated and marked with 0x1234 and sent to queue 0.
5369 testpmd> set sample_actions 0 mark id 0x1234 / queue index 0 / end
5370 testpmd> flow create 0 ingress group 1 pattern eth / end actions
5371 sample ratio 2 index 0 / queue index 1 / end
5373 Mirroring rule with port representors (with "transfer" attribute), the matched
5374 ingress packets with encapsulation header are sent to port id 0, and also
5375 mirrored the packets and sent to port id 2.
5379 testpmd> set sample_actions 0 port_id id 2 / end
5380 testpmd> flow create 1 ingress transfer pattern eth / end actions
5381 sample ratio 1 index 0 / raw_encap / port_id id 0 / end
5383 Mirroring rule with port representors (with "transfer" attribute), the matched
5384 ingress packets are sent to port id 2, and also mirrored the packets with
5385 encapsulation header and sent to port id 0.
5389 testpmd> set sample_actions 0 raw_encap / port_id id 0 / end
5390 testpmd> flow create 0 ingress transfer pattern eth / end actions
5391 sample ratio 1 index 0 / port_id id 2 / end
5393 Mirroring rule with port representors (with "transfer" attribute), the matched
5394 ingress packets are sent to port id 2, and also mirrored the packets with
5395 VXLAN encapsulation header and sent to port id 0.
5399 testpmd> set vxlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src 127.0.0.1
5400 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5401 testpmd> set sample_actions 0 vxlan_encap / port_id id 0 / end
5402 testpmd> flow create 0 ingress transfer pattern eth / end actions
5403 sample ratio 1 index 0 / port_id id 2 / end
5405 Mirroring rule with port representors (with "transfer" attribute), the matched
5406 ingress packets are sent to port id 2, and also mirrored the packets with
5407 NVGRE encapsulation header and sent to port id 0.
5411 testpmd> set nvgre ip-version ipv4 tni 4 ip-src 127.0.0.1 ip-dst 128.0.0.1
5412 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
5413 testpmd> set sample_actions 0 nvgre_encap / port_id id 0 / end
5414 testpmd> flow create 0 ingress transfer pattern eth / end actions
5415 sample ratio 1 index 0 / port_id id 2 / end
5417 Sample integrity rules
5418 ~~~~~~~~~~~~~~~~~~~~~~
5420 Integrity rules can be created by the following commands:
5422 Integrity rule that forwards valid TCP packets to group 1.
5423 TCP packet integrity is matched with the ``l4_ok`` bit 3.
5427 testpmd> flow create 0 ingress
5428 pattern eth / ipv4 / tcp / integrity value mask 8 value spec 8 / end
5429 actions jump group 1 / end
5431 Integrity rule that forwards invalid packets to application.
5432 General packet integrity is matched with the ``packet_ok`` bit 0.
5436 testpmd> flow create 0 ingress pattern integrity value mask 1 value spec 0 / end actions queue index 0 / end
5438 Sample conntrack rules
5439 ~~~~~~~~~~~~~~~~~~~~~~
5441 Conntrack rules can be set by the following commands
5443 Need to construct the connection context with provided information.
5444 In the first table, create a flow rule by using conntrack action and jump to
5445 the next table. In the next table, create a rule to check the state.
5449 testpmd> set conntrack com peer 1 is_orig 1 enable 1 live 1 sack 1 cack 0
5450 last_dir 0 liberal 0 state 1 max_ack_win 7 r_lim 5 last_win 510
5451 last_seq 2632987379 last_ack 2532480967 last_end 2632987379
5453 testpmd> set conntrack orig scale 7 fin 0 acked 1 unack_data 0
5454 sent_end 2632987379 reply_end 2633016339 max_win 28960
5456 testpmd> set conntrack rply scale 7 fin 0 acked 1 unack_data 0
5457 sent_end 2532480967 reply_end 2532546247 max_win 65280
5459 testpmd> flow indirect_action 0 create ingress action conntrack / end
5460 testpmd> flow create 0 group 3 ingress pattern eth / ipv4 / tcp / end actions indirect 0 / jump group 5 / end
5461 testpmd> flow create 0 group 5 ingress pattern eth / ipv4 / tcp / conntrack is 1 / end actions queue index 5 / end
5463 Construct the conntrack again with only "is_orig" set to 0 (other fields are
5464 ignored), then use "update" interface to update the direction. Create flow
5465 rules like above for the peer port.
5469 testpmd> flow indirect_action 0 update 0 action conntrack_update dir / end
5471 Sample meter with policy rules
5472 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5474 Meter with policy rules can be created by the following commands:
5476 Need to create policy first and actions are set for green/yellow/red colors.
5477 Create meter with policy id. Create flow with meter id.
5479 Example for policy with meter color action. The purpose is to color the packet
5480 to reflect the meter color result.
5481 The meter policy action list: ``green -> green, yellow -> yellow, red -> red``.
5485 testpmd> add port meter profile srtcm_rfc2697 0 13 21504 2688 0 0
5486 testpmd> add port meter policy 0 1 g_actions color type green / end y_actions color type yellow / end
5487 r_actions color type red / end
5488 testpmd> create port meter 0 1 13 1 yes 0xffff 0 0
5489 testpmd> flow create 0 priority 0 ingress group 1 pattern eth / end actions meter mtr_id 1 / end
5491 Sample L2TPv2 RSS rules
5492 ~~~~~~~~~~~~~~~~~~~~~~~
5494 L2TPv2 RSS rules can be created by the following commands::
5496 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type control
5497 / end actions rss types l2tpv2 end queues end / end
5498 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / end
5499 actions rss types eth l2-src-only end queues end / end
5500 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / end
5501 actions rss types l2tpv2 end queues end / end
5502 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4
5503 / end actions rss types ipv4 end queues end / end
5504 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv6
5505 / udp / end actions rss types ipv6-udp end queues end / end
5506 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv4
5507 / tcp / end actions rss types ipv4-tcp end queues end / end
5508 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv6
5509 / end actions rss types ipv6 end queues end / end
5511 Sample L2TPv2 FDIR rules
5512 ~~~~~~~~~~~~~~~~~~~~~~~~
5514 L2TPv2 FDIR rules can be created by the following commands::
5516 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type control
5517 session_id is 0x1111 / end actions queue index 3 / end
5518 testpmd> flow create 0 ingress pattern eth src is 00:00:00:00:00:01 / ipv4
5519 / udp / l2tpv2 type data / end actions queue index 3 / end
5520 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type data
5521 session_id is 0x1111 / ppp / end actions queue index 3 / end
5522 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4
5523 src is 10.0.0.1 / end actions queue index 3 / end
5524 testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv6
5525 dst is ABAB:910B:6666:3457:8295:3333:1800:2929 / end actions queue index 3 / end
5526 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4
5527 / udp src is 22 / end actions queue index 3 / end
5528 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4
5529 / tcp dst is 23 / end actions queue index 3 / end
5534 A RAW rule can be created as following using ``pattern_hex`` key and mask.
5538 testpmd> flow create 0 group 0 priority 1 ingress pattern raw relative is 0 search is 0 offset
5539 is 0 limit is 0 pattern_hex spec 00000000000000000000000000000000000000000000000000000a0a0a0a
5540 pattern_hex mask 0000000000000000000000000000000000000000000000000000ffffffff / end actions
5546 The following sections show functions to load/unload eBPF based filters.
5551 Load an eBPF program as a callback for particular RX/TX queue::
5553 testpmd> bpf-load rx|tx (portid) (queueid) (load-flags) (bpf-prog-filename)
5555 The available load-flags are:
5557 * ``J``: use JIT generated native code, otherwise BPF interpreter will be used.
5559 * ``M``: assume input parameter is a pointer to rte_mbuf, otherwise assume it is a pointer to first segment's data.
5565 You'll need clang v3.7 or above to build bpf program you'd like to load
5569 .. code-block:: console
5572 clang -O2 -target bpf -c t1.c
5574 Then to load (and JIT compile) t1.o at RX queue 0, port 1:
5576 .. code-block:: console
5578 testpmd> bpf-load rx 1 0 J ./dpdk.org/examples/bpf/t1.o
5580 To load (not JITed) t1.o at TX queue 0, port 0:
5582 .. code-block:: console
5584 testpmd> bpf-load tx 0 0 - ./dpdk.org/examples/bpf/t1.o
5589 Unload previously loaded eBPF program for particular RX/TX queue::
5591 testpmd> bpf-unload rx|tx (portid) (queueid)
5593 For example to unload BPF filter from TX queue 0, port 0:
5595 .. code-block:: console
5597 testpmd> bpf-unload tx 0 0
5602 The following sections show functions that configure and create flex item object,
5603 create flex pattern and use it in a flow rule.
5604 The commands will use 20 bytes IPv4 header for examples:
5609 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
5610 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5611 | ver | IHL | TOS | length | +0
5612 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5613 | identification | flg | frag. offset | +4
5614 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5615 | TTL | protocol | checksum | +8
5616 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5617 | source IP address | +12
5618 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5619 | destination IP address | +16
5620 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
5626 Flex item object is created by PMD according to a new header configuration. The
5627 header configuration is compiled by the testpmd and stored in
5628 ``rte_flow_item_flex_conf`` type variable.
5632 # flow flex_item create <port> <flex id> <configuration file>
5633 testpmd> flow flex_item init 0 3 ipv4_flex_config.json
5634 port-0: created flex item #3
5636 Flex item configuration is kept in external JSON file.
5637 It describes the following header elements:
5639 **New header length.**
5641 Specify whether the new header has fixed or variable length and the basic/minimal
5642 header length value.
5644 If header length is not fixed, header location with a value that completes header
5645 length calculation and scale/offset function must be added.
5647 Scale function depends on port hardware.
5651 Describes location in the new header that specify following network header type.
5653 **Flow match samples.**
5655 Describes locations in the new header that will be used in flow rules.
5657 Number of flow samples and sample maximal length depend of port hardware.
5661 Describes preceding network header configuration.
5665 Describes conditions that trigger transfer to following network header
5667 .. code-block:: json
5670 "next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 20},
5671 "next_protocol": {"field_size": 8, "field_base": 72},
5673 { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0},
5674 { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32},
5675 { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64},
5676 { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96}
5679 {"item": "eth type is 0x0800"},
5680 {"item": "vlan inner_type is 0x0800"}
5683 {"item": "udp", "next": 17},
5684 {"item": "tcp", "next": 6},
5685 {"item": "icmp", "next": 1}
5690 Flex pattern and flow rules
5691 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
5693 Flex pattern describe parts of network header that will trigger flex flow item hit in a flow rule.
5694 Flex pattern directly related to flex item samples configuration.
5695 Flex pattern can be shared between ports.
5697 **Flex pattern and flow rule to match IPv4 version and 20 bytes length**
5701 # set flex_pattern <pattern_id> is <hex bytes sequence>
5702 testpmd> flow flex_item pattern 5 is 45FF
5705 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 5 / end actions mark id 1 / queue index 0 / end
5706 Flow rule #0 created
5708 **Flex pattern and flow rule to match packets with source address 1.2.3.4**
5712 testpmd> flow flex_item pattern 2 spec 45000000000000000000000001020304 mask FF0000000000000000000000FFFFFFFF
5715 testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 2 / end actions mark id 1 / queue index 0 / end
5716 Flow rule #0 created
5718 Driver specific commands
5719 ------------------------
5721 Some drivers provide specific features.