doc: support IPsec Multi-buffer lib v1.0
[dpdk.git] / doc / guides / testpmd_app_ug / testpmd_funcs.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2010-2016 Intel Corporation.
3
4 .. _testpmd_runtime:
5
6 Testpmd Runtime Functions
7 =========================
8
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::
13
14    testpmd>
15
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.
19
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:
22
23 .. code-block:: console
24
25    testpmd> show port <TAB>
26
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
31        ...
32
33
34 .. note::
35
36    Some examples in this document are too long to fit on one line are shown wrapped at `"\\"` for display purposes::
37
38       testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
39                (pause_time) (send_xon) (port_id)
40
41 In the real ``testpmd>`` prompt these commands should be on a single line.
42
43 Help Functions
44 --------------
45
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:
48
49 .. code-block:: console
50
51    testpmd> help
52
53        help control    : Start and stop forwarding.
54        help display    : Displaying port, stats and config information.
55        help config     : Configuration information.
56        help ports      : Configuring ports.
57        help registers  : Reading and setting port registers.
58        help filters    : Filters configuration help.
59        help all        : All of the above sections.
60
61
62 Command File Functions
63 ----------------------
64
65 To facilitate loading large number of commands or to avoid cutting and pasting where not
66 practical or possible testpmd supports alternative methods for executing commands.
67
68 * If started with the ``--cmdline-file=FILENAME`` command line argument testpmd
69   will execute all CLI commands contained within the file immediately before
70   starting packet forwarding or entering interactive mode.
71
72 .. code-block:: console
73
74    ./dpdk-testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt
75    Interactive-mode selected
76    CLI commands to be read from /home/ubuntu/flow-create-commands.txt
77    Configuring Port 0 (socket 0)
78    Port 0: 7C:FE:90:CB:74:CE
79    Configuring Port 1 (socket 0)
80    Port 1: 7C:FE:90:CB:74:CA
81    Checking link statuses...
82    Port 0 Link Up - speed 10000 Mbps - full-duplex
83    Port 1 Link Up - speed 10000 Mbps - full-duplex
84    Done
85    Flow rule #0 created
86    Flow rule #1 created
87    ...
88    ...
89    Flow rule #498 created
90    Flow rule #499 created
91    Read all CLI commands from /home/ubuntu/flow-create-commands.txt
92    testpmd>
93
94
95 * At run-time additional commands can be loaded in bulk by invoking the ``load FILENAME``
96   command.
97
98 .. code-block:: console
99
100    testpmd> load /home/ubuntu/flow-create-commands.txt
101    Flow rule #0 created
102    Flow rule #1 created
103    ...
104    ...
105    Flow rule #498 created
106    Flow rule #499 created
107    Read all CLI commands from /home/ubuntu/flow-create-commands.txt
108    testpmd>
109
110
111 In all cases output from any included command will be displayed as standard output.
112 Execution will continue until the end of the file is reached regardless of
113 whether any errors occur.  The end user must examine the output to determine if
114 any failures occurred.
115
116
117 Control Functions
118 -----------------
119
120 start
121 ~~~~~
122
123 Start packet forwarding with current configuration::
124
125    testpmd> start
126
127 start tx_first
128 ~~~~~~~~~~~~~~
129
130 Start packet forwarding with current configuration after sending specified number of bursts of packets::
131
132    testpmd> start tx_first (""|burst_num)
133
134 The default burst number is 1 when ``burst_num`` not presented.
135
136 stop
137 ~~~~
138
139 Stop packet forwarding, and display accumulated statistics::
140
141    testpmd> stop
142
143 quit
144 ~~~~
145
146 Quit to prompt::
147
148    testpmd> quit
149
150
151 Display Functions
152 -----------------
153
154 The functions in the following sections are used to display information about the
155 testpmd configuration or the NIC status.
156
157 show port
158 ~~~~~~~~~
159
160 Display information for a given port or all ports::
161
162    testpmd> show port (info|summary|stats|xstats|fdir|dcb_tc|cap) (port_id|all)
163
164 The available information categories are:
165
166 * ``info``: General port information such as MAC address.
167
168 * ``summary``: Brief port summary such as Device Name, Driver Name etc.
169
170 * ``stats``: RX/TX statistics.
171
172 * ``xstats``: RX/TX extended NIC statistics.
173
174 * ``fdir``: Flow Director information and statistics.
175
176 * ``dcb_tc``: DCB information such as TC mapping.
177
178 For example:
179
180 .. code-block:: console
181
182    testpmd> show port info 0
183
184    ********************* Infos for port 0 *********************
185
186    MAC address: XX:XX:XX:XX:XX:XX
187    Connect to socket: 0
188    memory allocation on the socket: 0
189    Link status: up
190    Link speed: 40000 Mbps
191    Link duplex: full-duplex
192    Promiscuous mode: enabled
193    Allmulticast mode: disabled
194    Maximum number of MAC addresses: 64
195    Maximum number of MAC addresses of hash filtering: 0
196    VLAN offload:
197        strip on, filter on, extend off, qinq strip off
198    Redirection table size: 512
199    Supported flow types:
200      ipv4-frag
201      ipv4-tcp
202      ipv4-udp
203      ipv4-sctp
204      ipv4-other
205      ipv6-frag
206      ipv6-tcp
207      ipv6-udp
208      ipv6-sctp
209      ipv6-other
210      l2_payload
211      port
212      vxlan
213      geneve
214      nvgre
215      vxlan-gpe
216
217 show port (module_eeprom|eeprom)
218 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
219
220 Display the EEPROM information of a port::
221
222    testpmd> show port (port_id) (module_eeprom|eeprom)
223
224 show port rss reta
225 ~~~~~~~~~~~~~~~~~~
226
227 Display the rss redirection table entry indicated by masks on port X::
228
229    testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
230
231 size is used to indicate the hardware supported reta size
232
233 show port rss-hash
234 ~~~~~~~~~~~~~~~~~~
235
236 Display the RSS hash functions and RSS hash key of a port::
237
238    testpmd> show port (port_id) rss-hash [key]
239
240 clear port
241 ~~~~~~~~~~
242
243 Clear the port statistics and forward engine statistics for a given port or for all ports::
244
245    testpmd> clear port (info|stats|xstats|fdir) (port_id|all)
246
247 For example::
248
249    testpmd> clear port stats all
250
251 show (rxq|txq)
252 ~~~~~~~~~~~~~~
253
254 Display information for a given port's RX/TX queue::
255
256    testpmd> show (rxq|txq) info (port_id) (queue_id)
257
258 show desc status(rxq|txq)
259 ~~~~~~~~~~~~~~~~~~~~~~~~~
260
261 Display information for a given port's RX/TX descriptor status::
262
263    testpmd> show port (port_id) (rxq|txq) (queue_id) desc (desc_id) status
264
265 show rxq desc used count
266 ~~~~~~~~~~~~~~~~~~~~~~~~
267
268 Display the number of receive packet descriptors currently filled by hardware
269 and ready to be processed by the driver on a given RX queue::
270
271    testpmd> show port (port_id) rxq (queue_id) desc used count
272
273 show config
274 ~~~~~~~~~~~
275
276 Displays the configuration of the application.
277 The configuration comes from the command-line, the runtime or the application defaults::
278
279    testpmd> show config (rxtx|cores|fwd|rxoffs|rxpkts|txpkts|txtimes)
280
281 The available information categories are:
282
283 * ``rxtx``: RX/TX configuration items.
284
285 * ``cores``: List of forwarding cores.
286
287 * ``fwd``: Packet forwarding configuration.
288
289 * ``rxoffs``: Packet offsets for RX split.
290
291 * ``rxpkts``: Packets to RX split configuration.
292
293 * ``txpkts``: Packets to TX configuration.
294
295 * ``txtimes``: Burst time pattern for Tx only mode.
296
297 For example:
298
299 .. code-block:: console
300
301    testpmd> show config rxtx
302
303    io packet forwarding - CRC stripping disabled - packets/burst=16
304    nb forwarding cores=2 - nb forwarding ports=1
305    RX queues=1 - RX desc=128 - RX free threshold=0
306    RX threshold registers: pthresh=8 hthresh=8 wthresh=4
307    TX queues=1 - TX desc=512 - TX free threshold=0
308    TX threshold registers: pthresh=36 hthresh=0 wthresh=0
309    TX RS bit threshold=0 - TXQ flags=0x0
310
311 set fwd
312 ~~~~~~~
313
314 Set the packet forwarding mode::
315
316    testpmd> set fwd (io|mac|macswap|flowgen| \
317                      rxonly|txonly|csum|icmpecho|noisy|5tswap) (""|retry)
318
319 ``retry`` can be specified for forwarding engines except ``rx_only``.
320
321 The available information categories are:
322
323 * ``io``: Forwards packets "as-is" in I/O mode.
324   This is the fastest possible forwarding operation as it does not access packets data.
325   This is the default mode.
326
327 * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
328   Default application behavior is to set source Ethernet address to that of the transmitting interface, and destination
329   address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
330   'eth-peers-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
331
332 * ``macswap``: MAC swap forwarding mode.
333   Swaps the source and the destination Ethernet addresses of packets before forwarding them.
334
335 * ``flowgen``: Multi-flow generation mode.
336   Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
337
338 * ``rxonly``: Receives packets but doesn't transmit them.
339
340 * ``txonly``: Generates and transmits packets without receiving any.
341
342 * ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
343
344 * ``icmpecho``: Receives a burst of packets, lookup for ICMP echo requests and, if any, send back ICMP echo replies.
345
346 * ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX.
347
348 * ``noisy``: Noisy neighbor simulation.
349   Simulate more realistic behavior of a guest machine engaged in receiving
350   and sending packets performing Virtual Network Function (VNF).
351
352 * ``5tswap``: Swap the source and destination of L2,L3,L4 if they exist.
353
354   L2 swaps the source address and destination address of Ethernet, as same as ``macswap``.
355
356   L3 swaps the source address and destination address of IP (v4 and v6).
357
358   L4 swaps the source port and destination port of transport layer (TCP and UDP).
359
360 Example::
361
362    testpmd> set fwd rxonly
363
364    Set rxonly packet forwarding mode
365
366
367 show fwd
368 ~~~~~~~~
369
370 When running, forwarding engines maintain statistics from the time they have been started.
371 Example for the io forwarding engine, with some packet drops on the tx side::
372
373    testpmd> show fwd stats all
374
375      ------- Forward Stats for RX Port= 0/Queue= 0 -> TX Port= 1/Queue= 0 -------
376      RX-packets: 274293770      TX-packets: 274293642      TX-dropped: 128
377
378      ------- Forward Stats for RX Port= 1/Queue= 0 -> TX Port= 0/Queue= 0 -------
379      RX-packets: 274301850      TX-packets: 274301850      TX-dropped: 0
380
381      ---------------------- Forward statistics for port 0  ----------------------
382      RX-packets: 274293802      RX-dropped: 0             RX-total: 274293802
383      TX-packets: 274301862      TX-dropped: 0             TX-total: 274301862
384      ----------------------------------------------------------------------------
385
386      ---------------------- Forward statistics for port 1  ----------------------
387      RX-packets: 274301894      RX-dropped: 0             RX-total: 274301894
388      TX-packets: 274293706      TX-dropped: 128           TX-total: 274293834
389      ----------------------------------------------------------------------------
390
391      +++++++++++++++ Accumulated forward statistics for all ports+++++++++++++++
392      RX-packets: 548595696      RX-dropped: 0             RX-total: 548595696
393      TX-packets: 548595568      TX-dropped: 128           TX-total: 548595696
394      ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
395
396
397 clear fwd
398 ~~~~~~~~~
399
400 Clear the forwarding engines statistics::
401
402    testpmd> clear fwd stats all
403
404 read rxd
405 ~~~~~~~~
406
407 Display an RX descriptor for a port RX queue::
408
409    testpmd> read rxd (port_id) (queue_id) (rxd_id)
410
411 For example::
412
413    testpmd> read rxd 0 0 4
414         0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
415
416 read txd
417 ~~~~~~~~
418
419 Display a TX descriptor for a port TX queue::
420
421    testpmd> read txd (port_id) (queue_id) (txd_id)
422
423 For example::
424
425    testpmd> read txd 0 0 4
426         0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
427
428 ddp get list
429 ~~~~~~~~~~~~
430
431 Get loaded dynamic device personalization (DDP) package info list::
432
433    testpmd> ddp get list (port_id)
434
435 ddp get info
436 ~~~~~~~~~~~~
437
438 Display information about dynamic device personalization (DDP) profile::
439
440    testpmd> ddp get info (profile_path)
441
442 show vf stats
443 ~~~~~~~~~~~~~
444
445 Display VF statistics::
446
447    testpmd> show vf stats (port_id) (vf_id)
448
449 clear vf stats
450 ~~~~~~~~~~~~~~
451
452 Reset VF statistics::
453
454    testpmd> clear vf stats (port_id) (vf_id)
455
456 show port pctype mapping
457 ~~~~~~~~~~~~~~~~~~~~~~~~
458
459 List all items from the pctype mapping table::
460
461    testpmd> show port (port_id) pctype mapping
462
463 show rx offloading capabilities
464 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465
466 List all per queue and per port Rx offloading capabilities of a port::
467
468    testpmd> show port (port_id) rx_offload capabilities
469
470 show rx offloading configuration
471 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472
473 List port level and all queue level Rx offloading configuration::
474
475    testpmd> show port (port_id) rx_offload configuration
476
477 show tx offloading capabilities
478 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
479
480 List all per queue and per port Tx offloading capabilities of a port::
481
482    testpmd> show port (port_id) tx_offload capabilities
483
484 show tx offloading configuration
485 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
486
487 List port level and all queue level Tx offloading configuration::
488
489    testpmd> show port (port_id) tx_offload configuration
490
491 show tx metadata setting
492 ~~~~~~~~~~~~~~~~~~~~~~~~
493
494 Show Tx metadata value set for a specific port::
495
496    testpmd> show port (port_id) tx_metadata
497
498 show port supported ptypes
499 ~~~~~~~~~~~~~~~~~~~~~~~~~~
500
501 Show ptypes supported for a specific port::
502
503    testpmd> show port (port_id) ptypes
504
505 set port supported ptypes
506 ~~~~~~~~~~~~~~~~~~~~~~~~~
507
508 set packet types classification for a specific port::
509
510    testpmd> set port (port_id) ptypes_mask (mask)
511
512 show port mac addresses info
513 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
514
515 Show mac addresses added for a specific port::
516
517    testpmd> show port (port_id) macs
518
519
520 show port multicast mac addresses info
521 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
522
523 Show multicast mac addresses added for a specific port::
524
525    testpmd> show port (port_id) mcast_macs
526
527 show device info
528 ~~~~~~~~~~~~~~~~
529
530 Show general information about devices probed::
531
532    testpmd> show device info (<identifier>|all)
533
534 For example:
535
536 .. code-block:: console
537
538     testpmd> show device info net_pcap0
539
540     ********************* Infos for device net_pcap0 *********************
541     Bus name: vdev
542     Driver name: net_pcap
543     Devargs: iface=enP2p6s0,phy_mac=1
544     Connect to socket: -1
545
546             Port id: 2
547             MAC address: 1E:37:93:28:04:B8
548             Device name: net_pcap0
549
550 dump physmem
551 ~~~~~~~~~~~~
552
553 Dumps all physical memory segment layouts::
554
555    testpmd> dump_physmem
556
557 dump memzone
558 ~~~~~~~~~~~~
559
560 Dumps the layout of all memory zones::
561
562    testpmd> dump_memzone
563
564 dump socket memory
565 ~~~~~~~~~~~~~~~~~~
566
567 Dumps the memory usage of all sockets::
568
569    testpmd> dump_socket_mem
570
571 dump struct size
572 ~~~~~~~~~~~~~~~~
573
574 Dumps the size of all memory structures::
575
576    testpmd> dump_struct_sizes
577
578 dump ring
579 ~~~~~~~~~
580
581 Dumps the status of all or specific element in DPDK rings::
582
583    testpmd> dump_ring [ring_name]
584
585 dump mempool
586 ~~~~~~~~~~~~
587
588 Dumps the statistics of all or specific memory pool::
589
590    testpmd> dump_mempool [mempool_name]
591
592 dump devargs
593 ~~~~~~~~~~~~
594
595 Dumps the user device list::
596
597    testpmd> dump_devargs
598
599 dump log types
600 ~~~~~~~~~~~~~~
601
602 Dumps the log level for all the dpdk modules::
603
604    testpmd> dump_log_types
605
606 show (raw_encap|raw_decap)
607 ~~~~~~~~~~~~~~~~~~~~~~~~~~
608
609 Display content of raw_encap/raw_decap buffers in hex::
610
611   testpmd> show <raw_encap|raw_decap> <index>
612   testpmd> show <raw_encap|raw_decap> all
613
614 For example::
615
616   testpmd> show raw_encap 6
617
618   index: 6 at [0x1c565b0], len=50
619   00000000: 00 00 00 00 00 00 16 26 36 46 56 66 08 00 45 00 | .......&6FVf..E.
620   00000010: 00 00 00 00 00 00 00 11 00 00 C0 A8 01 06 C0 A8 | ................
621   00000020: 03 06 00 00 00 FA 00 00 00 00 08 00 00 00 00 00 | ................
622   00000030: 06 00                                           | ..
623
624 show fec capabilities
625 ~~~~~~~~~~~~~~~~~~~~~
626
627 Show fec capabilities of a port::
628
629   testpmd> show port (port_id) fec capabilities
630
631 show fec mode
632 ~~~~~~~~~~~~~
633
634 Show fec mode of a port::
635
636   testpmd> show port (port_id) fec_mode
637
638
639 Configuration Functions
640 -----------------------
641
642 The testpmd application can be configured from the runtime as well as from the command-line.
643
644 This section details the available configuration functions that are available.
645
646 .. note::
647
648    Configuration changes only become active when forwarding is started/restarted.
649
650 set default
651 ~~~~~~~~~~~
652
653 Reset forwarding to the default configuration::
654
655    testpmd> set default
656
657 set verbose
658 ~~~~~~~~~~~
659
660 Set the debug verbosity level::
661
662    testpmd> set verbose (level)
663
664 Available levels are as following:
665
666 * ``0`` silent except for error.
667 * ``1`` fully verbose except for Tx packets.
668 * ``2`` fully verbose except for Rx packets.
669 * ``> 2`` fully verbose.
670
671 set log
672 ~~~~~~~
673
674 Set the log level for a log type::
675
676         testpmd> set log global|(type) (level)
677
678 Where:
679
680 * ``type`` is the log name.
681
682 * ``level`` is the log level.
683
684 For example, to change the global log level::
685
686         testpmd> set log global (level)
687
688 Regexes can also be used for type. To change log level of user1, user2 and user3::
689
690         testpmd> set log user[1-3] (level)
691
692 set nbport
693 ~~~~~~~~~~
694
695 Set the number of ports used by the application:
696
697 set nbport (num)
698
699 This is equivalent to the ``--nb-ports`` command-line option.
700
701 set nbcore
702 ~~~~~~~~~~
703
704 Set the number of cores used by the application::
705
706    testpmd> set nbcore (num)
707
708 This is equivalent to the ``--nb-cores`` command-line option.
709
710 .. note::
711
712    The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
713
714 set coremask
715 ~~~~~~~~~~~~
716
717 Set the forwarding cores hexadecimal mask::
718
719    testpmd> set coremask (mask)
720
721 This is equivalent to the ``--coremask`` command-line option.
722
723 .. note::
724
725    The main lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
726
727 set portmask
728 ~~~~~~~~~~~~
729
730 Set the forwarding ports hexadecimal mask::
731
732    testpmd> set portmask (mask)
733
734 This is equivalent to the ``--portmask`` command-line option.
735
736 set record-core-cycles
737 ~~~~~~~~~~~~~~~~~~~~~~
738
739 Set the recording of CPU cycles::
740
741    testpmd> set record-core-cycles (on|off)
742
743 Where:
744
745 * ``on`` enables measurement of CPU cycles per packet.
746
747 * ``off`` disables measurement of CPU cycles per packet.
748
749 This is equivalent to the ``--record-core-cycles command-line`` option.
750
751 set record-burst-stats
752 ~~~~~~~~~~~~~~~~~~~~~~
753
754 Set the displaying of RX and TX bursts::
755
756    testpmd> set record-burst-stats (on|off)
757
758 Where:
759
760 * ``on`` enables display of RX and TX bursts.
761
762 * ``off`` disables display of RX and TX bursts.
763
764 This is equivalent to the ``--record-burst-stats command-line`` option.
765
766 set burst
767 ~~~~~~~~~
768
769 Set number of packets per burst::
770
771    testpmd> set burst (num)
772
773 This is equivalent to the ``--burst command-line`` option.
774
775 When retry is enabled, the transmit delay time and number of retries can also be set::
776
777    testpmd> set burst tx delay (microseconds) retry (num)
778
779 set rxoffs
780 ~~~~~~~~~~
781
782 Set the offsets of segments relating to the data buffer beginning on receiving
783 if split feature is engaged. Affects only the queues configured with split
784 offloads (currently BUFFER_SPLIT is supported only).
785
786    testpmd> set rxoffs (x[,y]*)
787
788 Where x[,y]* represents a CSV list of values, without white space. If the list
789 of offsets is shorter than the list of segments the zero offsets will be used
790 for the remaining segments.
791
792 set rxpkts
793 ~~~~~~~~~~
794
795 Set the length of segments to scatter packets on receiving if split
796 feature is engaged. Affects only the queues configured with split offloads
797 (currently BUFFER_SPLIT is supported only). Optionally the multiple memory
798 pools can be specified with --mbuf-size command line parameter and the mbufs
799 to receive will be allocated sequentially from these extra memory pools (the
800 mbuf for the first segment is allocated from the first pool, the second one
801 from the second pool, and so on, if segment number is greater then pool's the
802 mbuf for remaining segments will be allocated from the last valid pool).
803
804    testpmd> set rxpkts (x[,y]*)
805
806 Where x[,y]* represents a CSV list of values, without white space. Zero value
807 means to use the corresponding memory pool data buffer size.
808
809 set txpkts
810 ~~~~~~~~~~
811
812 Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
813
814    testpmd> set txpkts (x[,y]*)
815
816 Where x[,y]* represents a CSV list of values, without white space.
817
818 set txtimes
819 ~~~~~~~~~~~
820
821 Configure the timing burst pattern for Tx only mode. This command enables
822 the packet send scheduling on dynamic timestamp mbuf field and configures
823 timing pattern in Tx only mode. In this mode, if scheduling is enabled
824 application provides timestamps in the packets being sent. It is possible
825 to configure delay (in unspecified device clock units) between bursts
826 and between the packets within the burst::
827
828    testpmd> set txtimes (inter),(intra)
829
830 where:
831
832 * ``inter``  is the delay between the bursts in the device clock units.
833   If ``intra`` is zero, this is the time between the beginnings of the
834   first packets in the neighbour bursts, if ``intra`` is not zero,
835   ``inter`` specifies the time between the beginning of the first packet
836   of the current burst and the beginning of the last packet of the
837   previous burst. If ``inter`` parameter is zero the send scheduling
838   on timestamps is disabled (default).
839
840 * ``intra`` is the delay between the packets within the burst specified
841   in the device clock units. The number of packets in the burst is defined
842   by regular burst setting. If ``intra`` parameter is zero no timestamps
843   provided in the packets excepting the first one in the burst.
844
845 As the result the bursts of packet will be transmitted with specific
846 delays between the packets within the burst and specific delay between
847 the bursts. The rte_eth_read_clock() must be supported by the device(s)
848 and is supposed to be engaged to get the current device clock value
849 and provide the reference for the timestamps. If there is no supported
850 rte_eth_read_clock() there will be no send scheduling provided on the port.
851
852 set txsplit
853 ~~~~~~~~~~~
854
855 Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
856
857    testpmd> set txsplit (off|on|rand)
858
859 Where:
860
861 * ``off`` disable packet copy & split for CSUM mode.
862
863 * ``on`` split outgoing packet into multiple segments. Size of each segment
864   and number of segments per packet is determined by ``set txpkts`` command
865   (see above).
866
867 * ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
868
869 set corelist
870 ~~~~~~~~~~~~
871
872 Set the list of forwarding cores::
873
874    testpmd> set corelist (x[,y]*)
875
876 For example, to change the forwarding cores:
877
878 .. code-block:: console
879
880    testpmd> set corelist 3,1
881    testpmd> show config fwd
882
883    io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
884    Logical Core 3 (socket 0) forwards packets on 1 streams:
885    RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
886    Logical Core 1 (socket 0) forwards packets on 1 streams:
887    RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
888
889 .. note::
890
891    The cores are used in the same order as specified on the command line.
892
893 set portlist
894 ~~~~~~~~~~~~
895
896 Set the list of forwarding ports::
897
898    testpmd> set portlist (x[,y]*)
899
900 For example, to change the port forwarding:
901
902 .. code-block:: console
903
904    testpmd> set portlist 0,2,1,3
905    testpmd> show config fwd
906
907    io packet forwarding - ports=4 - cores=1 - streams=4
908    Logical Core 3 (socket 0) forwards packets on 4 streams:
909    RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
910    RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
911    RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
912    RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
913
914 set port setup on
915 ~~~~~~~~~~~~~~~~~
916
917 Select how to retrieve new ports created after "port attach" command::
918
919    testpmd> set port setup on (iterator|event)
920
921 For each new port, a setup is done.
922 It will find the probed ports via RTE_ETH_FOREACH_MATCHING_DEV loop
923 in iterator mode, or via RTE_ETH_EVENT_NEW in event mode.
924
925 set tx loopback
926 ~~~~~~~~~~~~~~~
927
928 Enable/disable tx loopback::
929
930    testpmd> set tx loopback (port_id) (on|off)
931
932 set drop enable
933 ~~~~~~~~~~~~~~~
934
935 set drop enable bit for all queues::
936
937    testpmd> set all queues drop (port_id) (on|off)
938
939 set split drop enable (for VF)
940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
941
942 set split drop enable bit for VF from PF::
943
944    testpmd> set vf split drop (port_id) (vf_id) (on|off)
945
946 set mac antispoof (for VF)
947 ~~~~~~~~~~~~~~~~~~~~~~~~~~
948
949 Set mac antispoof for a VF from the PF::
950
951    testpmd> set vf mac antispoof  (port_id) (vf_id) (on|off)
952
953 set macsec offload
954 ~~~~~~~~~~~~~~~~~~
955
956 Enable/disable MACsec offload::
957
958    testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
959    testpmd> set macsec offload (port_id) off
960
961 set macsec sc
962 ~~~~~~~~~~~~~
963
964 Configure MACsec secure connection (SC)::
965
966    testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi)
967
968 .. note::
969
970    The pi argument is ignored for tx.
971    Check the NIC Datasheet for hardware limits.
972
973 set macsec sa
974 ~~~~~~~~~~~~~
975
976 Configure MACsec secure association (SA)::
977
978    testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
979
980 .. note::
981
982    The IDX value must be 0 or 1.
983    Check the NIC Datasheet for hardware limits.
984
985 set broadcast mode (for VF)
986 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
987
988 Set broadcast mode for a VF from the PF::
989
990    testpmd> set vf broadcast (port_id) (vf_id) (on|off)
991
992 vlan set stripq
993 ~~~~~~~~~~~~~~~
994
995 Set the VLAN strip for a queue on a port::
996
997    testpmd> vlan set stripq (on|off) (port_id,queue_id)
998
999 vlan set stripq (for VF)
1000 ~~~~~~~~~~~~~~~~~~~~~~~~
1001
1002 Set VLAN strip for all queues in a pool for a VF from the PF::
1003
1004    testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
1005
1006 vlan set insert (for VF)
1007 ~~~~~~~~~~~~~~~~~~~~~~~~
1008
1009 Set VLAN insert for a VF from the PF::
1010
1011    testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
1012
1013 vlan set tag (for VF)
1014 ~~~~~~~~~~~~~~~~~~~~~
1015
1016 Set VLAN tag for a VF from the PF::
1017
1018    testpmd> set vf vlan tag (port_id) (vf_id) (on|off)
1019
1020 vlan set antispoof (for VF)
1021 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1022
1023 Set VLAN antispoof for a VF from the PF::
1024
1025    testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
1026
1027 vlan set (strip|filter|qinq_strip|extend)
1028 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1029 Set the VLAN strip/filter/QinQ strip/extend on for a port::
1030
1031    testpmd> vlan set (strip|filter|qinq_strip|extend) (on|off) (port_id)
1032
1033 vlan set tpid
1034 ~~~~~~~~~~~~~
1035
1036 Set the inner or outer VLAN TPID for packet filtering on a port::
1037
1038    testpmd> vlan set (inner|outer) tpid (value) (port_id)
1039
1040 .. note::
1041
1042    TPID value must be a 16-bit number (value <= 65536).
1043
1044 rx_vlan add
1045 ~~~~~~~~~~~
1046
1047 Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
1048
1049    testpmd> rx_vlan add (vlan_id|all) (port_id)
1050
1051 .. note::
1052
1053    VLAN filter must be set on that port. VLAN ID < 4096.
1054    Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
1055    in VFTA table. This is important if enabling all vlan_ids.
1056
1057 rx_vlan rm
1058 ~~~~~~~~~~
1059
1060 Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
1061
1062    testpmd> rx_vlan rm (vlan_id|all) (port_id)
1063
1064 rx_vlan add (for VF)
1065 ~~~~~~~~~~~~~~~~~~~~
1066
1067 Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
1068
1069    testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
1070
1071 rx_vlan rm (for VF)
1072 ~~~~~~~~~~~~~~~~~~~
1073
1074 Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
1075
1076    testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
1077
1078 rx_vxlan_port add
1079 ~~~~~~~~~~~~~~~~~
1080
1081 Add an UDP port for VXLAN packet filter on a port::
1082
1083    testpmd> rx_vxlan_port add (udp_port) (port_id)
1084
1085 rx_vxlan_port remove
1086 ~~~~~~~~~~~~~~~~~~~~
1087
1088 Remove an UDP port for VXLAN packet filter on a port::
1089
1090    testpmd> rx_vxlan_port rm (udp_port) (port_id)
1091
1092 tx_vlan set
1093 ~~~~~~~~~~~
1094
1095 Set hardware insertion of VLAN IDs in packets sent on a port::
1096
1097    testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
1098
1099 For example, set a single VLAN ID (5) insertion on port 0::
1100
1101    tx_vlan set 0 5
1102
1103 Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
1104
1105    tx_vlan set 1 2 3
1106
1107
1108 tx_vlan set pvid
1109 ~~~~~~~~~~~~~~~~
1110
1111 Set port based hardware insertion of VLAN ID in packets sent on a port::
1112
1113    testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
1114
1115 tx_vlan reset
1116 ~~~~~~~~~~~~~
1117
1118 Disable hardware insertion of a VLAN header in packets sent on a port::
1119
1120    testpmd> tx_vlan reset (port_id)
1121
1122 csum set
1123 ~~~~~~~~
1124
1125 Select hardware or software calculation of the checksum when
1126 transmitting a packet using the ``csum`` forwarding engine::
1127
1128    testpmd> csum set (ip|udp|tcp|sctp|outer-ip|outer-udp) (hw|sw) (port_id)
1129
1130 Where:
1131
1132 * ``ip|udp|tcp|sctp`` always relate to  the inner layer.
1133
1134 * ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
1135   as a tunnel packet by the forwarding engine (geneve, gre, gtp, ipip, vxlan and vxlan-gpe are
1136   supported). See also the ``csum parse-tunnel`` command.
1137
1138 * ``outer-udp`` relates to the outer UDP layer in the case where the packet is recognized
1139   as a tunnel packet by the forwarding engine (geneve, gtp, vxlan and vxlan-gpe are
1140   supported). See also the ``csum parse-tunnel`` command.
1141
1142 .. note::
1143
1144    Check the NIC Datasheet for hardware limits.
1145
1146 RSS queue region
1147 ~~~~~~~~~~~~~~~~
1148
1149 Set RSS queue region span on a port::
1150
1151    testpmd> set port (port_id) queue-region region_id (value) \
1152                 queue_start_index (value) queue_num (value)
1153
1154 Set flowtype mapping on a RSS queue region on a port::
1155
1156    testpmd> set port (port_id) queue-region region_id (value) flowtype (value)
1157
1158 where:
1159
1160 * For the flowtype(pctype) of packet,the specific index for each type has
1161   been defined in file i40e_type.h as enum i40e_filter_pctype.
1162
1163 Set user priority mapping on a RSS queue region on a port::
1164
1165    testpmd> set port (port_id) queue-region UP (value) region_id (value)
1166
1167 Flush all queue region related configuration on a port::
1168
1169    testpmd> set port (port_id) queue-region flush (on|off)
1170
1171 where:
1172
1173 * ``on``: is just an enable function which server for other configuration,
1174   it is for all configuration about queue region from up layer,
1175   at first will only keep in DPDK software stored in driver,
1176   only after "flush on", it commit all configuration to HW.
1177
1178 * ``"off``: is just clean all configuration about queue region just now,
1179   and restore all to DPDK i40e driver default config when start up.
1180
1181 Show all queue region related configuration info on a port::
1182
1183    testpmd> show port (port_id) queue-region
1184
1185 .. note::
1186
1187   Queue region only support on PF by now, so these command is
1188   only for configuration of queue region on PF port.
1189
1190 csum parse-tunnel
1191 ~~~~~~~~~~~~~~~~~
1192
1193 Define how tunneled packets should be handled by the csum forward
1194 engine::
1195
1196    testpmd> csum parse-tunnel (on|off) (tx_port_id)
1197
1198 If enabled, the csum forward engine will try to recognize supported
1199 tunnel headers (geneve, gtp, gre, ipip, vxlan, vxlan-gpe).
1200
1201 If disabled, treat tunnel packets as non-tunneled packets (a inner
1202 header is handled as a packet payload).
1203
1204 .. note::
1205
1206    The port argument is the TX port like in the ``csum set`` command.
1207
1208 Example:
1209
1210 Consider a packet in packet like the following::
1211
1212    eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
1213
1214 * If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
1215   command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
1216   ``outer-ip|outer-udp`` parameter relates to the outer headers (here ``ipv4_out`` and ``udp_out``).
1217
1218 * If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum  set``
1219    command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
1220
1221 csum show
1222 ~~~~~~~~~
1223
1224 Display tx checksum offload configuration::
1225
1226    testpmd> csum show (port_id)
1227
1228 tso set
1229 ~~~~~~~
1230
1231 Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
1232
1233    testpmd> tso set (segsize) (port_id)
1234
1235 .. note::
1236
1237    Check the NIC datasheet for hardware limits.
1238
1239 tso show
1240 ~~~~~~~~
1241
1242 Display the status of TCP Segmentation Offload::
1243
1244    testpmd> tso show (port_id)
1245
1246 tunnel tso set
1247 ~~~~~~~~~~~~~~
1248
1249 Set tso segment size of tunneled packets for a port in csum engine::
1250
1251    testpmd> tunnel_tso set (tso_segsz) (port_id)
1252
1253 tunnel tso show
1254 ~~~~~~~~~~~~~~~
1255
1256 Display the status of tunneled TCP Segmentation Offload for a port::
1257
1258    testpmd> tunnel_tso show (port_id)
1259
1260 set port - gro
1261 ~~~~~~~~~~~~~~
1262
1263 Enable or disable GRO in ``csum`` forwarding engine::
1264
1265    testpmd> set port <port_id> gro on|off
1266
1267 If enabled, the csum forwarding engine will perform GRO on the TCP/IPv4
1268 packets received from the given port.
1269
1270 If disabled, packets received from the given port won't be performed
1271 GRO. By default, GRO is disabled for all ports.
1272
1273 .. note::
1274
1275    When enable GRO for a port, TCP/IPv4 packets received from the port
1276    will be performed GRO. After GRO, all merged packets have bad
1277    checksums, since the GRO library doesn't re-calculate checksums for
1278    the merged packets. Therefore, if users want the merged packets to
1279    have correct checksums, please select HW IP checksum calculation and
1280    HW TCP checksum calculation for the port which the merged packets are
1281    transmitted to.
1282
1283 show port - gro
1284 ~~~~~~~~~~~~~~~
1285
1286 Display GRO configuration for a given port::
1287
1288    testpmd> show port <port_id> gro
1289
1290 set gro flush
1291 ~~~~~~~~~~~~~
1292
1293 Set the cycle to flush the GROed packets from reassembly tables::
1294
1295    testpmd> set gro flush <cycles>
1296
1297 When enable GRO, the csum forwarding engine performs GRO on received
1298 packets, and the GROed packets are stored in reassembly tables. Users
1299 can use this command to determine when the GROed packets are flushed
1300 from the reassembly tables.
1301
1302 The ``cycles`` is measured in GRO operation times. The csum forwarding
1303 engine flushes the GROed packets from the tables every ``cycles`` GRO
1304 operations.
1305
1306 By default, the value of ``cycles`` is 1, which means flush GROed packets
1307 from the reassembly tables as soon as one GRO operation finishes. The value
1308 of ``cycles`` should be in the range of 1 to ``GRO_MAX_FLUSH_CYCLES``.
1309
1310 Please note that the large value of ``cycles`` may cause the poor TCP/IP
1311 stack performance. Because the GROed packets are delayed to arrive the
1312 stack, thus causing more duplicated ACKs and TCP retransmissions.
1313
1314 set port - gso
1315 ~~~~~~~~~~~~~~
1316
1317 Toggle per-port GSO support in ``csum`` forwarding engine::
1318
1319    testpmd> set port <port_id> gso on|off
1320
1321 If enabled, the csum forwarding engine will perform GSO on supported IPv4
1322 packets, transmitted on the given port.
1323
1324 If disabled, packets transmitted on the given port will not undergo GSO.
1325 By default, GSO is disabled for all ports.
1326
1327 .. note::
1328
1329    When GSO is enabled on a port, supported IPv4 packets transmitted on that
1330    port undergo GSO. Afterwards, the segmented packets are represented by
1331    multi-segment mbufs; however, the csum forwarding engine doesn't calculation
1332    of checksums for GSO'd segments in SW. As a result, if users want correct
1333    checksums in GSO segments, they should enable HW checksum calculation for
1334    GSO-enabled ports.
1335
1336    For example, HW checksum calculation for VxLAN GSO'd packets may be enabled
1337    by setting the following options in the csum forwarding engine:
1338
1339    testpmd> csum set outer_ip hw <port_id>
1340
1341    testpmd> csum set ip hw <port_id>
1342
1343    testpmd> csum set tcp hw <port_id>
1344
1345    UDP GSO is the same as IP fragmentation, which treats the UDP header
1346    as the payload and does not modify it during segmentation. That is,
1347    after UDP GSO, only the first output fragment has the original UDP
1348    header. Therefore, users need to enable HW IP checksum calculation
1349    and SW UDP checksum calculation for GSO-enabled ports, if they want
1350    correct checksums for UDP/IPv4 packets.
1351
1352 set gso segsz
1353 ~~~~~~~~~~~~~
1354
1355 Set the maximum GSO segment size (measured in bytes), which includes the
1356 packet header and the packet payload for GSO-enabled ports (global)::
1357
1358    testpmd> set gso segsz <length>
1359
1360 show port - gso
1361 ~~~~~~~~~~~~~~~
1362
1363 Display the status of Generic Segmentation Offload for a given port::
1364
1365    testpmd> show port <port_id> gso
1366
1367 mac_addr add
1368 ~~~~~~~~~~~~
1369
1370 Add an alternative MAC address to a port::
1371
1372    testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
1373
1374 mac_addr remove
1375 ~~~~~~~~~~~~~~~
1376
1377 Remove a MAC address from a port::
1378
1379    testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
1380
1381 mcast_addr add
1382 ~~~~~~~~~~~~~~
1383
1384 To add the multicast MAC address to/from the set of multicast addresses
1385 filtered by port::
1386
1387    testpmd> mcast_addr add (port_id) (mcast_addr)
1388
1389 mcast_addr remove
1390 ~~~~~~~~~~~~~~~~~
1391
1392 To remove the multicast MAC address to/from the set of multicast addresses
1393 filtered by port::
1394
1395    testpmd> mcast_addr remove (port_id) (mcast_addr)
1396
1397 mac_addr add (for VF)
1398 ~~~~~~~~~~~~~~~~~~~~~
1399
1400 Add an alternative MAC address for a VF to a port::
1401
1402    testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
1403
1404 mac_addr set
1405 ~~~~~~~~~~~~
1406
1407 Set the default MAC address for a port::
1408
1409    testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX)
1410
1411 mac_addr set (for VF)
1412 ~~~~~~~~~~~~~~~~~~~~~
1413
1414 Set the MAC address for a VF from the PF::
1415
1416    testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
1417
1418 set eth-peer
1419 ~~~~~~~~~~~~
1420
1421 Set the forwarding peer address for certain port::
1422
1423    testpmd> set eth-peer (port_id) (peer_addr)
1424
1425 This is equivalent to the ``--eth-peer`` command-line option.
1426
1427 set port-uta
1428 ~~~~~~~~~~~~
1429
1430 Set the unicast hash filter(s) on/off for a port::
1431
1432    testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
1433
1434 set promisc
1435 ~~~~~~~~~~~
1436
1437 Set the promiscuous mode on for a port or for all ports.
1438 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1439
1440    testpmd> set promisc (port_id|all) (on|off)
1441
1442 set allmulti
1443 ~~~~~~~~~~~~
1444
1445 Set the allmulti mode for a port or for all ports::
1446
1447    testpmd> set allmulti (port_id|all) (on|off)
1448
1449 Same as the ifconfig (8) option. Controls how multicast packets are handled.
1450
1451 set promisc (for VF)
1452 ~~~~~~~~~~~~~~~~~~~~
1453
1454 Set the unicast promiscuous mode for a VF from PF.
1455 It's supported by Intel i40e NICs now.
1456 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1457
1458    testpmd> set vf promisc (port_id) (vf_id) (on|off)
1459
1460 set allmulticast (for VF)
1461 ~~~~~~~~~~~~~~~~~~~~~~~~~
1462
1463 Set the multicast promiscuous mode for a VF from PF.
1464 It's supported by Intel i40e NICs now.
1465 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
1466
1467    testpmd> set vf allmulti (port_id) (vf_id) (on|off)
1468
1469 set tx max bandwidth (for VF)
1470 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1471
1472 Set TX max absolute bandwidth (Mbps) for a VF from PF::
1473
1474    testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth)
1475
1476 set tc tx min bandwidth (for VF)
1477 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1478
1479 Set all TCs' TX min relative bandwidth (%) for a VF from PF::
1480
1481    testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...)
1482
1483 set tc tx max bandwidth (for VF)
1484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1485
1486 Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF::
1487
1488    testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth)
1489
1490 set tc strict link priority mode
1491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1492
1493 Set some TCs' strict link priority mode on a physical port::
1494
1495    testpmd> set tx strict-link-priority (port_id) (tc_bitmap)
1496
1497 set tc tx min bandwidth
1498 ~~~~~~~~~~~~~~~~~~~~~~~
1499
1500 Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs::
1501
1502    testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...)
1503
1504 set flow_ctrl rx
1505 ~~~~~~~~~~~~~~~~
1506
1507 Set the link flow control parameter on a port::
1508
1509    testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1510             (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
1511             autoneg (on|off) (port_id)
1512
1513 Where:
1514
1515 * ``high_water`` (integer): High threshold value to trigger XOFF.
1516
1517 * ``low_water`` (integer): Low threshold value to trigger XON.
1518
1519 * ``pause_time`` (integer): Pause quota in the Pause frame.
1520
1521 * ``send_xon`` (0/1): Send XON frame.
1522
1523 * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
1524
1525 * ``autoneg``: Change the auto-negotiation parameter.
1526
1527 show flow control
1528 ~~~~~~~~~~~~~~~~~
1529
1530 show the link flow control parameter on a port::
1531
1532    testpmd> show port <port_id> flow_ctrl
1533
1534 set pfc_ctrl rx
1535 ~~~~~~~~~~~~~~~
1536
1537 Set the priority flow control parameter on a port::
1538
1539    testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1540             (pause_time) (priority) (port_id)
1541
1542 Where:
1543
1544 * ``high_water`` (integer): High threshold value.
1545
1546 * ``low_water`` (integer): Low threshold value.
1547
1548 * ``pause_time`` (integer): Pause quota in the Pause frame.
1549
1550 * ``priority`` (0-7): VLAN User Priority.
1551
1552 set stat_qmap
1553 ~~~~~~~~~~~~~
1554
1555 Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
1556
1557    testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
1558
1559 For example, to set rx queue 2 on port 0 to mapping 5::
1560
1561    testpmd>set stat_qmap rx 0 2 5
1562
1563 set xstats-hide-zero
1564 ~~~~~~~~~~~~~~~~~~~~
1565
1566 Set the option to hide zero values for xstats display::
1567
1568         testpmd> set xstats-hide-zero on|off
1569
1570 .. note::
1571
1572         By default, the zero values are displayed for xstats.
1573
1574 set port - rx/tx (for VF)
1575 ~~~~~~~~~~~~~~~~~~~~~~~~~
1576
1577 Set VF receive/transmit from a port::
1578
1579    testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
1580
1581 set port - rx mode(for VF)
1582 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1583
1584 Set the VF receive mode of a port::
1585
1586    testpmd> set port (port_id) vf (vf_id) \
1587             rxmode (AUPE|ROPE|BAM|MPE) (on|off)
1588
1589 The available receive modes are:
1590
1591 * ``AUPE``: Accepts untagged VLAN.
1592
1593 * ``ROPE``: Accepts unicast hash.
1594
1595 * ``BAM``: Accepts broadcast packets.
1596
1597 * ``MPE``: Accepts all multicast packets.
1598
1599 set port - tx_rate (for Queue)
1600 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1601
1602 Set TX rate limitation for a queue on a port::
1603
1604    testpmd> set port (port_id) queue (queue_id) rate (rate_value)
1605
1606 set port - tx_rate (for VF)
1607 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1608
1609 Set TX rate limitation for queues in VF on a port::
1610
1611    testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
1612
1613 set port - mirror rule
1614 ~~~~~~~~~~~~~~~~~~~~~~
1615
1616 Set pool or vlan type mirror rule for a port::
1617
1618    testpmd> set port (port_id) mirror-rule (rule_id) \
1619             (pool-mirror-up|pool-mirror-down|vlan-mirror) \
1620             (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off)
1621
1622 Set link mirror rule for a port::
1623
1624    testpmd> set port (port_id) mirror-rule (rule_id) \
1625            (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off)
1626
1627 For example to enable mirror traffic with vlan 0,1 to pool 0::
1628
1629    set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on
1630
1631 reset port - mirror rule
1632 ~~~~~~~~~~~~~~~~~~~~~~~~
1633
1634 Reset a mirror rule for a port::
1635
1636    testpmd> reset port (port_id) mirror-rule (rule_id)
1637
1638 set flush_rx
1639 ~~~~~~~~~~~~
1640
1641 Set the flush on RX streams before forwarding.
1642 The default is flush ``on``.
1643 Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
1644
1645    testpmd> set flush_rx off
1646
1647 set bypass mode
1648 ~~~~~~~~~~~~~~~
1649
1650 Set the bypass mode for the lowest port on bypass enabled NIC::
1651
1652    testpmd> set bypass mode (normal|bypass|isolate) (port_id)
1653
1654 set bypass event
1655 ~~~~~~~~~~~~~~~~
1656
1657 Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
1658
1659    testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
1660             mode (normal|bypass|isolate) (port_id)
1661
1662 Where:
1663
1664 * ``timeout``: Enable bypass after watchdog timeout.
1665
1666 * ``os_on``: Enable bypass when OS/board is powered on.
1667
1668 * ``os_off``: Enable bypass when OS/board is powered off.
1669
1670 * ``power_on``: Enable bypass when power supply is turned on.
1671
1672 * ``power_off``: Enable bypass when power supply is turned off.
1673
1674
1675 set bypass timeout
1676 ~~~~~~~~~~~~~~~~~~
1677
1678 Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
1679
1680    testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
1681
1682 show bypass config
1683 ~~~~~~~~~~~~~~~~~~
1684
1685 Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
1686
1687    testpmd> show bypass config (port_id)
1688
1689 set link up
1690 ~~~~~~~~~~~
1691
1692 Set link up for a port::
1693
1694    testpmd> set link-up port (port id)
1695
1696 set link down
1697 ~~~~~~~~~~~~~
1698
1699 Set link down for a port::
1700
1701    testpmd> set link-down port (port id)
1702
1703 E-tag set
1704 ~~~~~~~~~
1705
1706 Enable E-tag insertion for a VF on a port::
1707
1708    testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1709
1710 Disable E-tag insertion for a VF on a port::
1711
1712    testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1713
1714 Enable/disable E-tag stripping on a port::
1715
1716    testpmd> E-tag set stripping (on|off) port (port_id)
1717
1718 Enable/disable E-tag based forwarding on a port::
1719
1720    testpmd> E-tag set forwarding (on|off) port (port_id)
1721
1722 ddp add
1723 ~~~~~~~
1724
1725 Load a dynamic device personalization (DDP) profile and store backup profile::
1726
1727    testpmd> ddp add (port_id) (profile_path[,backup_profile_path])
1728
1729 ddp del
1730 ~~~~~~~
1731
1732 Delete a dynamic device personalization profile and restore backup profile::
1733
1734    testpmd> ddp del (port_id) (backup_profile_path)
1735
1736 ptype mapping
1737 ~~~~~~~~~~~~~
1738
1739 List all items from the ptype mapping table::
1740
1741    testpmd> ptype mapping get (port_id) (valid_only)
1742
1743 Where:
1744
1745 * ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0).
1746
1747 Replace a specific or a group of software defined ptype with a new one::
1748
1749    testpmd> ptype mapping replace  (port_id) (target) (mask) (pkt_type)
1750
1751 where:
1752
1753 * ``target``: A specific software ptype or a mask to represent a group of software ptypes.
1754
1755 * ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1).
1756
1757 * ``pkt_type``: The new software ptype to replace the old ones.
1758
1759 Update hardware defined ptype to software defined packet type mapping table::
1760
1761    testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype)
1762
1763 where:
1764
1765 * ``hw_ptype``: hardware ptype as the index of the ptype mapping table.
1766
1767 * ``sw_ptype``: software ptype as the value of the ptype mapping table.
1768
1769 Reset ptype mapping table::
1770
1771    testpmd> ptype mapping reset (port_id)
1772
1773 config per port Rx offloading
1774 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1775
1776 Enable or disable a per port Rx offloading on all Rx queues of a port::
1777
1778    testpmd> port config (port_id) rx_offload (offloading) on|off
1779
1780 * ``offloading``: can be any of these offloading capability:
1781                   vlan_strip, ipv4_cksum, udp_cksum, tcp_cksum, tcp_lro,
1782                   qinq_strip, outer_ipv4_cksum, macsec_strip,
1783                   header_split, vlan_filter, vlan_extend, jumbo_frame,
1784                   scatter, timestamp, security, keep_crc, rss_hash
1785
1786 This command should be run when the port is stopped, or else it will fail.
1787
1788 config per queue Rx offloading
1789 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1790
1791 Enable or disable a per queue Rx offloading only on a specific Rx queue::
1792
1793    testpmd> port (port_id) rxq (queue_id) rx_offload (offloading) on|off
1794
1795 * ``offloading``: can be any of these offloading capability:
1796                   vlan_strip, ipv4_cksum, udp_cksum, tcp_cksum, tcp_lro,
1797                   qinq_strip, outer_ipv4_cksum, macsec_strip,
1798                   header_split, vlan_filter, vlan_extend, jumbo_frame,
1799                   scatter, timestamp, security, keep_crc
1800
1801 This command should be run when the port is stopped, or else it will fail.
1802
1803 config per port Tx offloading
1804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1805
1806 Enable or disable a per port Tx offloading on all Tx queues of a port::
1807
1808    testpmd> port config (port_id) tx_offload (offloading) on|off
1809
1810 * ``offloading``: can be any of these offloading capability:
1811                   vlan_insert, ipv4_cksum, udp_cksum, tcp_cksum,
1812                   sctp_cksum, tcp_tso, udp_tso, outer_ipv4_cksum,
1813                   qinq_insert, vxlan_tnl_tso, gre_tnl_tso,
1814                   ipip_tnl_tso, geneve_tnl_tso, macsec_insert,
1815                   mt_lockfree, multi_segs, mbuf_fast_free, security
1816
1817 This command should be run when the port is stopped, or else it will fail.
1818
1819 config per queue Tx offloading
1820 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1821
1822 Enable or disable a per queue Tx offloading only on a specific Tx queue::
1823
1824    testpmd> port (port_id) txq (queue_id) tx_offload (offloading) on|off
1825
1826 * ``offloading``: can be any of these offloading capability:
1827                   vlan_insert, ipv4_cksum, udp_cksum, tcp_cksum,
1828                   sctp_cksum, tcp_tso, udp_tso, outer_ipv4_cksum,
1829                   qinq_insert, vxlan_tnl_tso, gre_tnl_tso,
1830                   ipip_tnl_tso, geneve_tnl_tso, macsec_insert,
1831                   mt_lockfree, multi_segs, mbuf_fast_free, security
1832
1833 This command should be run when the port is stopped, or else it will fail.
1834
1835 Config VXLAN Encap outer layers
1836 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1837
1838 Configure the outer layer to encapsulate a packet inside a VXLAN tunnel::
1839
1840  set vxlan ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1841  udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) eth-src (eth-src) \
1842  eth-dst (eth-dst)
1843
1844  set vxlan-with-vlan ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1845  udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) vlan-tci (vlan-tci) \
1846  eth-src (eth-src) eth-dst (eth-dst)
1847
1848  set vxlan-tos-ttl ip-version (ipv4|ipv6) vni (vni) udp-src (udp-src) \
1849  udp-dst (udp-dst) ip-tos (ip-tos) ip-ttl (ip-ttl) ip-src (ip-src) \
1850  ip-dst (ip-dst) eth-src (eth-src) eth-dst (eth-dst)
1851
1852 These commands will set an internal configuration inside testpmd, any following
1853 flow rule using the action vxlan_encap will use the last configuration set.
1854 To have a different encapsulation header, one of those commands must be called
1855 before the flow rule creation.
1856
1857 Config NVGRE Encap outer layers
1858 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1859
1860 Configure the outer layer to encapsulate a packet inside a NVGRE tunnel::
1861
1862  set nvgre ip-version (ipv4|ipv6) tni (tni) ip-src (ip-src) ip-dst (ip-dst) \
1863         eth-src (eth-src) eth-dst (eth-dst)
1864  set nvgre-with-vlan ip-version (ipv4|ipv6) tni (tni) ip-src (ip-src) \
1865         ip-dst (ip-dst) vlan-tci (vlan-tci) eth-src (eth-src) eth-dst (eth-dst)
1866
1867 These commands will set an internal configuration inside testpmd, any following
1868 flow rule using the action nvgre_encap will use the last configuration set.
1869 To have a different encapsulation header, one of those commands must be called
1870 before the flow rule creation.
1871
1872 Config L2 Encap
1873 ~~~~~~~~~~~~~~~
1874
1875 Configure the l2 to be used when encapsulating a packet with L2::
1876
1877  set l2_encap ip-version (ipv4|ipv6) eth-src (eth-src) eth-dst (eth-dst)
1878  set l2_encap-with-vlan ip-version (ipv4|ipv6) vlan-tci (vlan-tci) \
1879         eth-src (eth-src) eth-dst (eth-dst)
1880
1881 Those commands will set an internal configuration inside testpmd, any following
1882 flow rule using the action l2_encap will use the last configuration set.
1883 To have a different encapsulation header, one of those commands must be called
1884 before the flow rule creation.
1885
1886 Config L2 Decap
1887 ~~~~~~~~~~~~~~~
1888
1889 Configure the l2 to be removed when decapsulating a packet with L2::
1890
1891  set l2_decap ip-version (ipv4|ipv6)
1892  set l2_decap-with-vlan ip-version (ipv4|ipv6)
1893
1894 Those commands will set an internal configuration inside testpmd, any following
1895 flow rule using the action l2_decap will use the last configuration set.
1896 To have a different encapsulation header, one of those commands must be called
1897 before the flow rule creation.
1898
1899 Config MPLSoGRE Encap outer layers
1900 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1901
1902 Configure the outer layer to encapsulate a packet inside a MPLSoGRE tunnel::
1903
1904  set mplsogre_encap ip-version (ipv4|ipv6) label (label) \
1905         ip-src (ip-src) ip-dst (ip-dst) eth-src (eth-src) eth-dst (eth-dst)
1906  set mplsogre_encap-with-vlan ip-version (ipv4|ipv6) label (label) \
1907         ip-src (ip-src) ip-dst (ip-dst) vlan-tci (vlan-tci) \
1908         eth-src (eth-src) eth-dst (eth-dst)
1909
1910 These commands will set an internal configuration inside testpmd, any following
1911 flow rule using the action mplsogre_encap will use the last configuration set.
1912 To have a different encapsulation header, one of those commands must be called
1913 before the flow rule creation.
1914
1915 Config MPLSoGRE Decap outer layers
1916 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1917
1918 Configure the outer layer to decapsulate MPLSoGRE packet::
1919
1920  set mplsogre_decap ip-version (ipv4|ipv6)
1921  set mplsogre_decap-with-vlan ip-version (ipv4|ipv6)
1922
1923 These commands will set an internal configuration inside testpmd, any following
1924 flow rule using the action mplsogre_decap will use the last configuration set.
1925 To have a different decapsulation header, one of those commands must be called
1926 before the flow rule creation.
1927
1928 Config MPLSoUDP Encap outer layers
1929 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1930
1931 Configure the outer layer to encapsulate a packet inside a MPLSoUDP tunnel::
1932
1933  set mplsoudp_encap ip-version (ipv4|ipv6) label (label) udp-src (udp-src) \
1934         udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) \
1935         eth-src (eth-src) eth-dst (eth-dst)
1936  set mplsoudp_encap-with-vlan ip-version (ipv4|ipv6) label (label) \
1937         udp-src (udp-src) udp-dst (udp-dst) ip-src (ip-src) ip-dst (ip-dst) \
1938         vlan-tci (vlan-tci) eth-src (eth-src) eth-dst (eth-dst)
1939
1940 These commands will set an internal configuration inside testpmd, any following
1941 flow rule using the action mplsoudp_encap will use the last configuration set.
1942 To have a different encapsulation header, one of those commands must be called
1943 before the flow rule creation.
1944
1945 Config MPLSoUDP Decap outer layers
1946 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1947
1948 Configure the outer layer to decapsulate MPLSoUDP packet::
1949
1950  set mplsoudp_decap ip-version (ipv4|ipv6)
1951  set mplsoudp_decap-with-vlan ip-version (ipv4|ipv6)
1952
1953 These commands will set an internal configuration inside testpmd, any following
1954 flow rule using the action mplsoudp_decap will use the last configuration set.
1955 To have a different decapsulation header, one of those commands must be called
1956 before the flow rule creation.
1957
1958 Config Raw Encapsulation
1959 ~~~~~~~~~~~~~~~~~~~~~~~~~
1960
1961 Configure the raw data to be used when encapsulating a packet by
1962 rte_flow_action_raw_encap::
1963
1964  set raw_encap {index} {item} [/ {item} [...]] / end_set
1965
1966 There are multiple global buffers for ``raw_encap``, this command will set one
1967 internal buffer index by ``{index}``.
1968 If there is no ``{index}`` specified::
1969
1970  set raw_encap {item} [/ {item} [...]] / end_set
1971
1972 the default index ``0`` is used.
1973 In order to use different encapsulating header, ``index`` must be specified
1974 during the flow rule creation::
1975
1976  testpmd> flow create 0 egress pattern eth / ipv4 / end actions
1977         raw_encap index 2 / end
1978
1979 Otherwise the default index ``0`` is used.
1980
1981 Config Raw Decapsulation
1982 ~~~~~~~~~~~~~~~~~~~~~~~~
1983
1984 Configure the raw data to be used when decapsulating a packet by
1985 rte_flow_action_raw_decap::
1986
1987  set raw_decap {index} {item} [/ {item} [...]] / end_set
1988
1989 There are multiple global buffers for ``raw_decap``, this command will set
1990 one internal buffer index by ``{index}``.
1991 If there is no ``{index}`` specified::
1992
1993  set raw_decap {item} [/ {item} [...]] / end_set
1994
1995 the default index ``0`` is used.
1996 In order to use different decapsulating header, ``index`` must be specified
1997 during the flow rule creation::
1998
1999  testpmd> flow create 0 egress pattern eth / ipv4 / end actions
2000           raw_encap index 3 / end
2001
2002 Otherwise the default index ``0`` is used.
2003
2004 Set fec mode
2005 ~~~~~~~~~~~~
2006
2007 Set fec mode for a specific port::
2008
2009   testpmd> set port (port_id) fec_mode auto|off|rs|baser
2010
2011 Config Sample actions list
2012 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2013
2014 Configure the sample actions list to be used when sampling a packet by
2015 rte_flow_action_sample::
2016
2017  set sample_actions {index} {action} [/ {action} [...]] / end
2018
2019 There are multiple global buffers for ``sample_actions``, this command will set
2020 one internal buffer index by ``{index}``.
2021
2022 In order to use different sample actions list, ``index`` must be specified
2023 during the flow rule creation::
2024
2025  testpmd> flow create 0 ingress pattern eth / ipv4 / end actions
2026         sample ratio 2 index 2 / end
2027
2028 Otherwise the default index ``0`` is used.
2029
2030 Port Functions
2031 --------------
2032
2033 The following sections show functions for configuring ports.
2034
2035 .. note::
2036
2037    Port configuration changes only become active when forwarding is started/restarted.
2038
2039 port attach
2040 ~~~~~~~~~~~
2041
2042 Attach a port specified by pci address or virtual device args::
2043
2044    testpmd> port attach (identifier)
2045
2046 To attach a new pci device, the device should be recognized by kernel first.
2047 Then it should be moved under DPDK management.
2048 Finally the port can be attached to testpmd.
2049
2050 For example, to move a pci device using ixgbe under DPDK management:
2051
2052 .. code-block:: console
2053
2054    # Check the status of the available devices.
2055    ./usertools/dpdk-devbind.py --status
2056
2057    Network devices using DPDK-compatible driver
2058    ============================================
2059    <none>
2060
2061    Network devices using kernel driver
2062    ===================================
2063    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
2064
2065
2066    # Bind the device to igb_uio.
2067    sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
2068
2069
2070    # Recheck the status of the devices.
2071    ./usertools/dpdk-devbind.py --status
2072    Network devices using DPDK-compatible driver
2073    ============================================
2074    0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
2075
2076 To attach a port created by virtual device, above steps are not needed.
2077
2078 For example, to attach a port whose pci address is 0000:0a:00.0.
2079
2080 .. code-block:: console
2081
2082    testpmd> port attach 0000:0a:00.0
2083    Attaching a new port...
2084    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
2085    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
2086    EAL:   PCI memory mapped at 0x7f83bfa00000
2087    EAL:   PCI memory mapped at 0x7f83bfa80000
2088    PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
2089    PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
2090    Port 0 is attached. Now total ports is 1
2091    Done
2092
2093 For example, to attach a port created by pcap PMD.
2094
2095 .. code-block:: console
2096
2097    testpmd> port attach net_pcap0
2098    Attaching a new port...
2099    PMD: Initializing pmd_pcap for net_pcap0
2100    PMD: Creating pcap-backed ethdev on numa socket 0
2101    Port 0 is attached. Now total ports is 1
2102    Done
2103
2104 In this case, identifier is ``net_pcap0``.
2105 This identifier format is the same as ``--vdev`` format of DPDK applications.
2106
2107 For example, to re-attach a bonded port which has been previously detached,
2108 the mode and slave parameters must be given.
2109
2110 .. code-block:: console
2111
2112    testpmd> port attach net_bond_0,mode=0,slave=1
2113    Attaching a new port...
2114    EAL: Initializing pmd_bond for net_bond_0
2115    EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
2116    Port 0 is attached. Now total ports is 1
2117    Done
2118
2119
2120 port detach
2121 ~~~~~~~~~~~
2122
2123 Detach a specific port::
2124
2125    testpmd> port detach (port_id)
2126
2127 Before detaching a port, the port should be stopped and closed.
2128
2129 For example, to detach a pci device port 0.
2130
2131 .. code-block:: console
2132
2133    testpmd> port stop 0
2134    Stopping ports...
2135    Done
2136    testpmd> port close 0
2137    Closing ports...
2138    Done
2139
2140    testpmd> port detach 0
2141    Detaching a port...
2142    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
2143    EAL:   remove driver: 8086:10fb rte_ixgbe_pmd
2144    EAL:   PCI memory unmapped at 0x7f83bfa00000
2145    EAL:   PCI memory unmapped at 0x7f83bfa80000
2146    Done
2147
2148
2149 For example, to detach a virtual device port 0.
2150
2151 .. code-block:: console
2152
2153    testpmd> port stop 0
2154    Stopping ports...
2155    Done
2156    testpmd> port close 0
2157    Closing ports...
2158    Done
2159
2160    testpmd> port detach 0
2161    Detaching a port...
2162    PMD: Closing pcap ethdev on numa socket 0
2163    Port 'net_pcap0' is detached. Now total ports is 0
2164    Done
2165
2166 To remove a pci device completely from the system, first detach the port from testpmd.
2167 Then the device should be moved under kernel management.
2168 Finally the device can be removed using kernel pci hotplug functionality.
2169
2170 For example, to move a pci device under kernel management:
2171
2172 .. code-block:: console
2173
2174    sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
2175
2176    ./usertools/dpdk-devbind.py --status
2177
2178    Network devices using DPDK-compatible driver
2179    ============================================
2180    <none>
2181
2182    Network devices using kernel driver
2183    ===================================
2184    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
2185
2186 To remove a port created by a virtual device, above steps are not needed.
2187
2188 port start
2189 ~~~~~~~~~~
2190
2191 Start all ports or a specific port::
2192
2193    testpmd> port start (port_id|all)
2194
2195 port stop
2196 ~~~~~~~~~
2197
2198 Stop all ports or a specific port::
2199
2200    testpmd> port stop (port_id|all)
2201
2202 port close
2203 ~~~~~~~~~~
2204
2205 Close all ports or a specific port::
2206
2207    testpmd> port close (port_id|all)
2208
2209 port reset
2210 ~~~~~~~~~~
2211
2212 Reset all ports or a specific port::
2213
2214    testpmd> port reset (port_id|all)
2215
2216 User should stop port(s) before resetting and (re-)start after reset.
2217
2218 port config - queue ring size
2219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2220
2221 Configure a rx/tx queue ring size::
2222
2223    testpmd> port (port_id) (rxq|txq) (queue_id) ring_size (value)
2224
2225 Only take effect after command that (re-)start the port or command that setup specific queue.
2226
2227 port start/stop queue
2228 ~~~~~~~~~~~~~~~~~~~~~
2229
2230 Start/stop a rx/tx queue on a specific port::
2231
2232    testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
2233
2234 port config - queue deferred start
2235 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2236
2237 Switch on/off deferred start of a specific port queue::
2238
2239    testpmd> port (port_id) (rxq|txq) (queue_id) deferred_start (on|off)
2240
2241 port setup queue
2242 ~~~~~~~~~~~~~~~~~~~~~
2243
2244 Setup a rx/tx queue on a specific port::
2245
2246    testpmd> port (port_id) (rxq|txq) (queue_id) setup
2247
2248 Only take effect when port is started.
2249
2250 port config - speed
2251 ~~~~~~~~~~~~~~~~~~~
2252
2253 Set the speed and duplex mode for all ports or a specific port::
2254
2255    testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|200000|auto) \
2256             duplex (half|full|auto)
2257
2258 port config - queues/descriptors
2259 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2260
2261 Set number of queues/descriptors for rxq, txq, rxd and txd::
2262
2263    testpmd> port config all (rxq|txq|rxd|txd) (value)
2264
2265 This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
2266
2267 port config - max-pkt-len
2268 ~~~~~~~~~~~~~~~~~~~~~~~~~
2269
2270 Set the maximum packet length::
2271
2272    testpmd> port config all max-pkt-len (value)
2273
2274 This is equivalent to the ``--max-pkt-len`` command-line option.
2275
2276 port config - max-lro-pkt-size
2277 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2278
2279 Set the maximum LRO aggregated packet size::
2280
2281    testpmd> port config all max-lro-pkt-size (value)
2282
2283 This is equivalent to the ``--max-lro-pkt-size`` command-line option.
2284
2285 port config - Drop Packets
2286 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2287
2288 Enable or disable packet drop on all RX queues of all ports when no receive buffers available::
2289
2290    testpmd> port config all drop-en (on|off)
2291
2292 Packet dropping when no receive buffers available is off by default.
2293
2294 The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
2295
2296 port config - RSS
2297 ~~~~~~~~~~~~~~~~~
2298
2299 Set the RSS (Receive Side Scaling) mode on or off::
2300
2301    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|none)
2302
2303 RSS is on by default.
2304
2305 The ``all`` option is equivalent to eth|vlan|ip|tcp|udp|sctp|ether|l2tpv3|esp|ah|pfcp.
2306
2307 The ``default`` option enables all supported RSS types reported by device info.
2308
2309 The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
2310
2311 port config - RSS Reta
2312 ~~~~~~~~~~~~~~~~~~~~~~
2313
2314 Set the RSS (Receive Side Scaling) redirection table::
2315
2316    testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
2317
2318 port config - DCB
2319 ~~~~~~~~~~~~~~~~~
2320
2321 Set the DCB mode for an individual port::
2322
2323    testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
2324
2325 The traffic class should be 4 or 8.
2326
2327 port config - Burst
2328 ~~~~~~~~~~~~~~~~~~~
2329
2330 Set the number of packets per burst::
2331
2332    testpmd> port config all burst (value)
2333
2334 This is equivalent to the ``--burst`` command-line option.
2335
2336 port config - Threshold
2337 ~~~~~~~~~~~~~~~~~~~~~~~
2338
2339 Set thresholds for TX/RX queues::
2340
2341    testpmd> port config all (threshold) (value)
2342
2343 Where the threshold type can be:
2344
2345 * ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
2346
2347 * ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
2348
2349 * ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
2350
2351 * ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
2352
2353 * ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
2354
2355 * ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
2356
2357 * ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
2358
2359 * ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
2360
2361 * ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
2362
2363 These threshold options are also available from the command-line.
2364
2365 port config pctype mapping
2366 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2367
2368 Reset pctype mapping table::
2369
2370    testpmd> port config (port_id) pctype mapping reset
2371
2372 Update hardware defined pctype to software defined flow type mapping table::
2373
2374    testpmd> port config (port_id) pctype mapping update (pctype_id_0[,pctype_id_1]*) (flow_type_id)
2375
2376 where:
2377
2378 * ``pctype_id_x``: hardware pctype id as index of bit in bitmask value of the pctype mapping table.
2379
2380 * ``flow_type_id``: software flow type id as the index of the pctype mapping table.
2381
2382 port config input set
2383 ~~~~~~~~~~~~~~~~~~~~~
2384
2385 Config RSS/FDIR/FDIR flexible payload input set for some pctype::
2386
2387    testpmd> port config (port_id) pctype (pctype_id) \
2388             (hash_inset|fdir_inset|fdir_flx_inset) \
2389             (get|set|clear) field (field_idx)
2390
2391 Clear RSS/FDIR/FDIR flexible payload input set for some pctype::
2392
2393    testpmd> port config (port_id) pctype (pctype_id) \
2394             (hash_inset|fdir_inset|fdir_flx_inset) clear all
2395
2396 where:
2397
2398 * ``pctype_id``: hardware packet classification types.
2399 * ``field_idx``: hardware field index.
2400
2401 port config udp_tunnel_port
2402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
2403
2404 Add/remove UDP tunnel port for VXLAN/GENEVE tunneling protocols::
2405
2406     testpmd> port config (port_id) udp_tunnel_port add|rm vxlan|geneve|vxlan-gpe|ecpri (udp_port)
2407
2408 port config tx_metadata
2409 ~~~~~~~~~~~~~~~~~~~~~~~
2410
2411 Set Tx metadata value per port.
2412 testpmd will add this value to any Tx packet sent from this port::
2413
2414    testpmd> port config (port_id) tx_metadata (value)
2415
2416 port config dynf
2417 ~~~~~~~~~~~~~~~~
2418
2419 Set/clear dynamic flag per port.
2420 testpmd will register this flag in the mbuf (same registration
2421 for both Tx and Rx). Then set/clear this flag for each Tx
2422 packet sent from this port. The set bit only works for Tx packet::
2423
2424    testpmd> port config (port_id) dynf (name) (set|clear)
2425
2426 port config mtu
2427 ~~~~~~~~~~~~~~~
2428
2429 To configure MTU(Maximum Transmission Unit) on devices using testpmd::
2430
2431    testpmd> port config mtu (port_id) (value)
2432
2433 port config rss hash key
2434 ~~~~~~~~~~~~~~~~~~~~~~~~
2435
2436 To configure the RSS hash key used to compute the RSS
2437 hash of input [IP] packets received on port::
2438
2439    testpmd> port config <port_id> rss-hash-key (ipv4|ipv4-frag|\
2440                      ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|\
2441                      ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|\
2442                      ipv6-other|l2-payload|ipv6-ex|ipv6-tcp-ex|\
2443                      ipv6-udp-ex <string of hex digits \
2444                      (variable length, NIC dependent)>)
2445
2446 port cleanup txq mbufs
2447 ~~~~~~~~~~~~~~~~~~~~~~
2448
2449 To cleanup txq mbufs currently cached by driver::
2450
2451    testpmd> port cleanup (port_id) txq (queue_id) (free_cnt)
2452
2453 If the value of ``free_cnt`` is 0, driver should free all cached mbufs.
2454
2455 Device Functions
2456 ----------------
2457
2458 The following sections show functions for device operations.
2459
2460 device detach
2461 ~~~~~~~~~~~~~
2462
2463 Detach a device specified by pci address or virtual device args::
2464
2465    testpmd> device detach (identifier)
2466
2467 Before detaching a device associated with ports, the ports should be stopped and closed.
2468
2469 For example, to detach a pci device whose address is 0002:03:00.0.
2470
2471 .. code-block:: console
2472
2473     testpmd> device detach 0002:03:00.0
2474     Removing a device...
2475     Port 1 is now closed
2476     EAL: Releasing pci mapped resource for 0002:03:00.0
2477     EAL: Calling pci_unmap_resource for 0002:03:00.0 at 0x218a050000
2478     EAL: Calling pci_unmap_resource for 0002:03:00.0 at 0x218c050000
2479     Device 0002:03:00.0 is detached
2480     Now total ports is 1
2481
2482 For example, to detach a port created by pcap PMD.
2483
2484 .. code-block:: console
2485
2486     testpmd> device detach net_pcap0
2487     Removing a device...
2488     Port 0 is now closed
2489     Device net_pcap0 is detached
2490     Now total ports is 0
2491     Done
2492
2493 In this case, identifier is ``net_pcap0``.
2494 This identifier format is the same as ``--vdev`` format of DPDK applications.
2495
2496 Link Bonding Functions
2497 ----------------------
2498
2499 The Link Bonding functions make it possible to dynamically create and
2500 manage link bonding devices from within testpmd interactive prompt.
2501
2502 create bonded device
2503 ~~~~~~~~~~~~~~~~~~~~
2504
2505 Create a new bonding device::
2506
2507    testpmd> create bonded device (mode) (socket)
2508
2509 For example, to create a bonded device in mode 1 on socket 0::
2510
2511    testpmd> create bonded device 1 0
2512    created new bonded device (port X)
2513
2514 add bonding slave
2515 ~~~~~~~~~~~~~~~~~
2516
2517 Adds Ethernet device to a Link Bonding device::
2518
2519    testpmd> add bonding slave (slave id) (port id)
2520
2521 For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
2522
2523    testpmd> add bonding slave 6 10
2524
2525
2526 remove bonding slave
2527 ~~~~~~~~~~~~~~~~~~~~
2528
2529 Removes an Ethernet slave device from a Link Bonding device::
2530
2531    testpmd> remove bonding slave (slave id) (port id)
2532
2533 For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
2534
2535    testpmd> remove bonding slave 6 10
2536
2537 set bonding mode
2538 ~~~~~~~~~~~~~~~~
2539
2540 Set the Link Bonding mode of a Link Bonding device::
2541
2542    testpmd> set bonding mode (value) (port id)
2543
2544 For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
2545
2546    testpmd> set bonding mode 3 10
2547
2548 set bonding primary
2549 ~~~~~~~~~~~~~~~~~~~
2550
2551 Set an Ethernet slave device as the primary device on a Link Bonding device::
2552
2553    testpmd> set bonding primary (slave id) (port id)
2554
2555 For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
2556
2557    testpmd> set bonding primary 6 10
2558
2559 set bonding mac
2560 ~~~~~~~~~~~~~~~
2561
2562 Set the MAC address of a Link Bonding device::
2563
2564    testpmd> set bonding mac (port id) (mac)
2565
2566 For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
2567
2568    testpmd> set bonding mac 10 00:00:00:00:00:01
2569
2570 set bonding balance_xmit_policy
2571 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2572
2573 Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
2574
2575    testpmd> set bonding balance_xmit_policy (port_id) (l2|l23|l34)
2576
2577 For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
2578
2579    testpmd> set bonding balance_xmit_policy 10 l34
2580
2581
2582 set bonding mon_period
2583 ~~~~~~~~~~~~~~~~~~~~~~
2584
2585 Set the link status monitoring polling period in milliseconds for a bonding device.
2586
2587 This adds support for PMD slave devices which do not support link status interrupts.
2588 When the mon_period is set to a value greater than 0 then all PMD's which do not support
2589 link status ISR will be queried every polling interval to check if their link status has changed::
2590
2591    testpmd> set bonding mon_period (port_id) (value)
2592
2593 For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
2594
2595    testpmd> set bonding mon_period 5 150
2596
2597
2598 set bonding lacp dedicated_queue
2599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2600
2601 Enable dedicated tx/rx queues on bonding devices slaves to handle LACP control plane traffic
2602 when in mode 4 (link-aggregation-802.3ad)::
2603
2604    testpmd> set bonding lacp dedicated_queues (port_id) (enable|disable)
2605
2606
2607 set bonding agg_mode
2608 ~~~~~~~~~~~~~~~~~~~~
2609
2610 Enable one of the specific aggregators mode when in mode 4 (link-aggregation-802.3ad)::
2611
2612    testpmd> set bonding agg_mode (port_id) (bandwidth|count|stable)
2613
2614
2615 show bonding config
2616 ~~~~~~~~~~~~~~~~~~~
2617
2618 Show the current configuration of a Link Bonding device::
2619
2620    testpmd> show bonding config (port id)
2621
2622 For example,
2623 to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
2624 in balance mode with a transmission policy of layer 2+3::
2625
2626    testpmd> show bonding config 9
2627         Bonding mode: 2
2628         Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
2629         Slaves (3): [1 3 4]
2630         Active Slaves (3): [1 3 4]
2631         Primary: [3]
2632
2633
2634 Register Functions
2635 ------------------
2636
2637 The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
2638 This is mainly useful for debugging purposes.
2639 Reference should be made to the appropriate datasheet for the network card for details on the register addresses
2640 and fields that can be accessed.
2641
2642 read reg
2643 ~~~~~~~~
2644
2645 Display the value of a port register::
2646
2647    testpmd> read reg (port_id) (address)
2648
2649 For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
2650
2651    testpmd> read reg 0 0xEE00
2652    port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
2653
2654 read regfield
2655 ~~~~~~~~~~~~~
2656
2657 Display a port register bit field::
2658
2659    testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
2660
2661 For example, reading the lowest two bits from the register in the example above::
2662
2663    testpmd> read regfield 0 0xEE00 0 1
2664    port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
2665
2666 read regbit
2667 ~~~~~~~~~~~
2668
2669 Display a single port register bit::
2670
2671    testpmd> read regbit (port_id) (address) (bit_x)
2672
2673 For example, reading the lowest bit from the register in the example above::
2674
2675    testpmd> read regbit 0 0xEE00 0
2676    port 0 PCI register at offset 0xEE00: bit 0=1
2677
2678 write reg
2679 ~~~~~~~~~
2680
2681 Set the value of a port register::
2682
2683    testpmd> write reg (port_id) (address) (value)
2684
2685 For example, to clear a register::
2686
2687    testpmd> write reg 0 0xEE00 0x0
2688    port 0 PCI register at offset 0xEE00: 0x00000000 (0)
2689
2690 write regfield
2691 ~~~~~~~~~~~~~~
2692
2693 Set bit field of a port register::
2694
2695    testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
2696
2697 For example, writing to the register cleared in the example above::
2698
2699    testpmd> write regfield 0 0xEE00 0 1 2
2700    port 0 PCI register at offset 0xEE00: 0x00000002 (2)
2701
2702 write regbit
2703 ~~~~~~~~~~~~
2704
2705 Set single bit value of a port register::
2706
2707    testpmd> write regbit (port_id) (address) (bit_x) (value)
2708
2709 For example, to set the high bit in the register from the example above::
2710
2711    testpmd> write regbit 0 0xEE00 31 1
2712    port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
2713
2714 Traffic Metering and Policing
2715 -----------------------------
2716
2717 The following section shows functions for configuring traffic metering and
2718 policing on the ethernet device through the use of generic ethdev API.
2719
2720 show port traffic management capability
2721 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2722
2723 Show traffic metering and policing capability of the port::
2724
2725    testpmd> show port meter cap (port_id)
2726
2727 add port meter profile (srTCM rfc2967)
2728 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2729
2730 Add meter profile (srTCM rfc2697) to the ethernet device::
2731
2732    testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \
2733    (cir) (cbs) (ebs) (packet_mode)
2734
2735 where:
2736
2737 * ``profile_id``: ID for the meter profile.
2738 * ``cir``: Committed Information Rate (CIR) (bytes per second or packets per second).
2739 * ``cbs``: Committed Burst Size (CBS) (bytes or packets).
2740 * ``ebs``: Excess Burst Size (EBS) (bytes or packets).
2741 * ``packet_mode``: Packets mode for meter profile.
2742
2743 add port meter profile (trTCM rfc2968)
2744 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2745
2746 Add meter profile (srTCM rfc2698) to the ethernet device::
2747
2748    testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \
2749    (cir) (pir) (cbs) (pbs) (packet_mode)
2750
2751 where:
2752
2753 * ``profile_id``: ID for the meter profile.
2754 * ``cir``: Committed information rate (bytes per second or packets per second).
2755 * ``pir``: Peak information rate (bytes per second or packets per second).
2756 * ``cbs``: Committed burst size (bytes or packets).
2757 * ``pbs``: Peak burst size (bytes or packets).
2758 * ``packet_mode``: Packets mode for meter profile.
2759
2760 add port meter profile (trTCM rfc4115)
2761 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2762
2763 Add meter profile (trTCM rfc4115) to the ethernet device::
2764
2765    testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \
2766    (cir) (eir) (cbs) (ebs) (packet_mode)
2767
2768 where:
2769
2770 * ``profile_id``: ID for the meter profile.
2771 * ``cir``: Committed information rate (bytes per second or packets per second).
2772 * ``eir``: Excess information rate (bytes per second or packets per second).
2773 * ``cbs``: Committed burst size (bytes or packets).
2774 * ``ebs``: Excess burst size (bytes or packets).
2775 * ``packet_mode``: Packets mode for meter profile.
2776
2777 delete port meter profile
2778 ~~~~~~~~~~~~~~~~~~~~~~~~~
2779
2780 Delete meter profile from the ethernet device::
2781
2782    testpmd> del port meter profile (port_id) (profile_id)
2783
2784 create port policy
2785 ~~~~~~~~~~~~~~~~~~
2786
2787 Create new policy object for the ethernet device::
2788
2789    testpmd> add port meter policy (port_id) (policy_id) g_actions \
2790    {action} y_actions {action} r_actions {action}
2791
2792 where:
2793
2794 * ``policy_id``: policy ID.
2795 * ``action``: action lists for green/yellow/red colors.
2796
2797 delete port policy
2798 ~~~~~~~~~~~~~~~~~~
2799
2800 Delete policy object for the ethernet device::
2801
2802    testpmd> del port meter policy (port_id) (policy_id)
2803
2804 where:
2805
2806 * ``policy_id``: policy ID.
2807
2808 create port meter
2809 ~~~~~~~~~~~~~~~~~
2810
2811 Create new meter object for the ethernet device::
2812
2813    testpmd> create port meter (port_id) (mtr_id) (profile_id) \
2814    (policy_id) (meter_enable) (stats_mask) (shared) \
2815    (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\
2816    (dscp_tbl_entry63)]
2817
2818 where:
2819
2820 * ``mtr_id``: meter object ID.
2821 * ``profile_id``: ID for the meter profile.
2822 * ``policy_id``: ID for the policy.
2823 * ``meter_enable``: When this parameter has a non-zero value, the meter object
2824   gets enabled at the time of creation, otherwise remains disabled.
2825 * ``stats_mask``: Mask of statistics counter types to be enabled for the
2826   meter object.
2827 * ``shared``:  When this parameter has a non-zero value, the meter object is
2828   shared by multiple flows. Otherwise, meter object is used by single flow.
2829 * ``use_pre_meter_color``: When this parameter has a non-zero value, the
2830   input color for the current meter object is determined by the latest meter
2831   object in the same flow. Otherwise, the current meter object uses the
2832   *dscp_table* to determine the input color.
2833 * ``dscp_tbl_entryx``: DSCP table entry x providing meter providing input
2834   color, 0 <= x <= 63.
2835
2836 enable port meter
2837 ~~~~~~~~~~~~~~~~~
2838
2839 Enable meter for the ethernet device::
2840
2841    testpmd> enable port meter (port_id) (mtr_id)
2842
2843 disable port meter
2844 ~~~~~~~~~~~~~~~~~~
2845
2846 Disable meter for the ethernet device::
2847
2848    testpmd> disable port meter (port_id) (mtr_id)
2849
2850 delete port meter
2851 ~~~~~~~~~~~~~~~~~
2852
2853 Delete meter for the ethernet device::
2854
2855    testpmd> del port meter (port_id) (mtr_id)
2856
2857 Set port meter profile
2858 ~~~~~~~~~~~~~~~~~~~~~~
2859
2860 Set meter profile for the ethernet device::
2861
2862    testpmd> set port meter profile (port_id) (mtr_id) (profile_id)
2863
2864 set port meter dscp table
2865 ~~~~~~~~~~~~~~~~~~~~~~~~~
2866
2867 Set meter dscp table for the ethernet device::
2868
2869    testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \
2870    (dscp_tbl_entry1)...(dscp_tbl_entry63)]
2871
2872 set port meter stats mask
2873 ~~~~~~~~~~~~~~~~~~~~~~~~~
2874
2875 Set meter stats mask for the ethernet device::
2876
2877    testpmd> set port meter stats mask (port_id) (mtr_id) (stats_mask)
2878
2879 where:
2880
2881 * ``stats_mask``: Bit mask indicating statistics counter types to be enabled.
2882
2883 show port meter stats
2884 ~~~~~~~~~~~~~~~~~~~~~
2885
2886 Show meter stats of the ethernet device::
2887
2888    testpmd> show port meter stats (port_id) (mtr_id) (clear)
2889
2890 where:
2891
2892 * ``clear``: Flag that indicates whether the statistics counters should
2893   be cleared (i.e. set to zero) immediately after they have been read or not.
2894
2895 Traffic Management
2896 ------------------
2897
2898 The following section shows functions for configuring traffic management on
2899 the ethernet device through the use of generic TM API.
2900
2901 show port traffic management capability
2902 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2903
2904 Show traffic management capability of the port::
2905
2906    testpmd> show port tm cap (port_id)
2907
2908 show port traffic management capability (hierarchy level)
2909 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2910
2911 Show traffic management hierarchy level capability of the port::
2912
2913    testpmd> show port tm level cap (port_id) (level_id)
2914
2915 show port traffic management capability (hierarchy node level)
2916 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2917
2918 Show the traffic management hierarchy node capability of the port::
2919
2920    testpmd> show port tm node cap (port_id) (node_id)
2921
2922 show port traffic management hierarchy node type
2923 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2924
2925 Show the port traffic management hierarchy node type::
2926
2927    testpmd> show port tm node type (port_id) (node_id)
2928
2929 show port traffic management hierarchy node stats
2930 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2931
2932 Show the port traffic management hierarchy node statistics::
2933
2934    testpmd> show port tm node stats (port_id) (node_id) (clear)
2935
2936 where:
2937
2938 * ``clear``: When this parameter has a non-zero value, the statistics counters
2939   are cleared (i.e. set to zero) immediately after they have been read,
2940   otherwise the statistics counters are left untouched.
2941
2942 Add port traffic management private shaper profile
2943 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2944
2945 Add the port traffic management private shaper profile::
2946
2947    testpmd> add port tm node shaper profile (port_id) (shaper_profile_id) \
2948    (cmit_tb_rate) (cmit_tb_size) (peak_tb_rate) (peak_tb_size) \
2949    (packet_length_adjust) (packet_mode)
2950
2951 where:
2952
2953 * ``shaper_profile id``: Shaper profile ID for the new profile.
2954 * ``cmit_tb_rate``: Committed token bucket rate (bytes per second or packets per second).
2955 * ``cmit_tb_size``: Committed token bucket size (bytes or packets).
2956 * ``peak_tb_rate``: Peak token bucket rate (bytes per second or packets per second).
2957 * ``peak_tb_size``: Peak token bucket size (bytes or packets).
2958 * ``packet_length_adjust``: The value (bytes) to be added to the length of
2959   each packet for the purpose of shaping. This parameter value can be used to
2960   correct the packet length with the framing overhead bytes that are consumed
2961   on the wire.
2962 * ``packet_mode``: Shaper configured in packet mode. This parameter value if
2963   zero, configures shaper in byte mode and if non-zero configures it in packet
2964   mode.
2965
2966 Delete port traffic management private shaper profile
2967 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2968
2969 Delete the port traffic management private shaper::
2970
2971    testpmd> del port tm node shaper profile (port_id) (shaper_profile_id)
2972
2973 where:
2974
2975 * ``shaper_profile id``: Shaper profile ID that needs to be deleted.
2976
2977 Add port traffic management shared shaper
2978 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2979
2980 Create the port traffic management shared shaper::
2981
2982    testpmd> add port tm node shared shaper (port_id) (shared_shaper_id) \
2983    (shaper_profile_id)
2984
2985 where:
2986
2987 * ``shared_shaper_id``: Shared shaper ID to be created.
2988 * ``shaper_profile id``: Shaper profile ID for shared shaper.
2989
2990 Set port traffic management shared shaper
2991 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2992
2993 Update the port traffic management shared shaper::
2994
2995    testpmd> set port tm node shared shaper (port_id) (shared_shaper_id) \
2996    (shaper_profile_id)
2997
2998 where:
2999
3000 * ``shared_shaper_id``: Shared shaper ID to be update.
3001 * ``shaper_profile id``: Shaper profile ID for shared shaper.
3002
3003 Delete port traffic management shared shaper
3004 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3005
3006 Delete the port traffic management shared shaper::
3007
3008    testpmd> del port tm node shared shaper (port_id) (shared_shaper_id)
3009
3010 where:
3011
3012 * ``shared_shaper_id``: Shared shaper ID to be deleted.
3013
3014 Set port traffic management hierarchy node private shaper
3015 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3016
3017 set the port traffic management hierarchy node private shaper::
3018
3019    testpmd> set port tm node shaper profile (port_id) (node_id) \
3020    (shaper_profile_id)
3021
3022 where:
3023
3024 * ``shaper_profile id``: Private shaper profile ID to be enabled on the
3025   hierarchy node.
3026
3027 Add port traffic management WRED profile
3028 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3029
3030 Create a new WRED profile::
3031
3032    testpmd> add port tm node wred profile (port_id) (wred_profile_id) \
3033    (color_g) (min_th_g) (max_th_g) (maxp_inv_g) (wq_log2_g) \
3034    (color_y) (min_th_y) (max_th_y) (maxp_inv_y) (wq_log2_y) \
3035    (color_r) (min_th_r) (max_th_r) (maxp_inv_r) (wq_log2_r)
3036
3037 where:
3038
3039 * ``wred_profile id``: Identifier for the newly create WRED profile
3040 * ``color_g``: Packet color (green)
3041 * ``min_th_g``: Minimum queue threshold for packet with green color
3042 * ``max_th_g``: Minimum queue threshold for packet with green color
3043 * ``maxp_inv_g``: Inverse of packet marking probability maximum value (maxp)
3044 * ``wq_log2_g``: Negated log2 of queue weight (wq)
3045 * ``color_y``: Packet color (yellow)
3046 * ``min_th_y``: Minimum queue threshold for packet with yellow color
3047 * ``max_th_y``: Minimum queue threshold for packet with yellow color
3048 * ``maxp_inv_y``: Inverse of packet marking probability maximum value (maxp)
3049 * ``wq_log2_y``: Negated log2 of queue weight (wq)
3050 * ``color_r``: Packet color (red)
3051 * ``min_th_r``: Minimum queue threshold for packet with yellow color
3052 * ``max_th_r``: Minimum queue threshold for packet with yellow color
3053 * ``maxp_inv_r``: Inverse of packet marking probability maximum value (maxp)
3054 * ``wq_log2_r``: Negated log2 of queue weight (wq)
3055
3056 Delete port traffic management WRED profile
3057 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3058
3059 Delete the WRED profile::
3060
3061    testpmd> del port tm node wred profile (port_id) (wred_profile_id)
3062
3063 Add port traffic management hierarchy nonleaf node
3064 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3065
3066 Add nonleaf node to port traffic management hierarchy::
3067
3068    testpmd> add port tm nonleaf node (port_id) (node_id) (parent_node_id) \
3069    (priority) (weight) (level_id) (shaper_profile_id) \
3070    (n_sp_priorities) (stats_mask) (n_shared_shapers) \
3071    [(shared_shaper_0) (shared_shaper_1) ...] \
3072
3073 where:
3074
3075 * ``parent_node_id``: Node ID of the parent.
3076 * ``priority``: Node priority (highest node priority is zero). This is used by
3077   the SP algorithm running on the parent node for scheduling this node.
3078 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3079   to the weight sum of all siblings that have the same priority. It is used by
3080   the WFQ algorithm running on the parent node for scheduling this node.
3081 * ``level_id``: Hierarchy level of the node.
3082 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3083   the node.
3084 * ``n_sp_priorities``: Number of strict priorities.
3085 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3086 * ``n_shared_shapers``: Number of shared shapers.
3087 * ``shared_shaper_id``: Shared shaper id.
3088
3089 Add port traffic management hierarchy nonleaf node with packet mode
3090 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3091
3092 Add nonleaf node with packet mode to port traffic management hierarchy::
3093
3094    testpmd> add port tm nonleaf node pktmode (port_id) (node_id) (parent_node_id) \
3095    (priority) (weight) (level_id) (shaper_profile_id) \
3096    (n_sp_priorities) (stats_mask) (n_shared_shapers) \
3097    [(shared_shaper_0) (shared_shaper_1) ...] \
3098
3099 where:
3100
3101 * ``parent_node_id``: Node ID of the parent.
3102 * ``priority``: Node priority (highest node priority is zero). This is used by
3103   the SP algorithm running on the parent node for scheduling this node.
3104 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3105   to the weight sum of all siblings that have the same priority. It is used by
3106   the WFQ algorithm running on the parent node for scheduling this node.
3107 * ``level_id``: Hierarchy level of the node.
3108 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3109   the node.
3110 * ``n_sp_priorities``: Number of strict priorities. Packet mode is enabled on
3111   all of them.
3112 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3113 * ``n_shared_shapers``: Number of shared shapers.
3114 * ``shared_shaper_id``: Shared shaper id.
3115
3116 Add port traffic management hierarchy leaf node
3117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3118
3119 Add leaf node to port traffic management hierarchy::
3120
3121    testpmd> add port tm leaf node (port_id) (node_id) (parent_node_id) \
3122    (priority) (weight) (level_id) (shaper_profile_id) \
3123    (cman_mode) (wred_profile_id) (stats_mask) (n_shared_shapers) \
3124    [(shared_shaper_id) (shared_shaper_id) ...] \
3125
3126 where:
3127
3128 * ``parent_node_id``: Node ID of the parent.
3129 * ``priority``: Node priority (highest node priority is zero). This is used by
3130   the SP algorithm running on the parent node for scheduling this node.
3131 * ``weight``: Node weight (lowest weight is one). The node weight is relative
3132   to the weight sum of all siblings that have the same priority. It is used by
3133   the WFQ algorithm running on the parent node for scheduling this node.
3134 * ``level_id``: Hierarchy level of the node.
3135 * ``shaper_profile_id``: Shaper profile ID of the private shaper to be used by
3136   the node.
3137 * ``cman_mode``: Congestion management mode to be enabled for this node.
3138 * ``wred_profile_id``: WRED profile id to be enabled for this node.
3139 * ``stats_mask``: Mask of statistics counter types to be enabled for this node.
3140 * ``n_shared_shapers``: Number of shared shapers.
3141 * ``shared_shaper_id``: Shared shaper id.
3142
3143 Delete port traffic management hierarchy node
3144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3145
3146 Delete node from port traffic management hierarchy::
3147
3148    testpmd> del port tm node (port_id) (node_id)
3149
3150 Update port traffic management hierarchy parent node
3151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3152
3153 Update port traffic management hierarchy parent node::
3154
3155    testpmd> set port tm node parent (port_id) (node_id) (parent_node_id) \
3156    (priority) (weight)
3157
3158 This function can only be called after the hierarchy commit invocation. Its
3159 success depends on the port support for this operation, as advertised through
3160 the port capability set. This function is valid for all nodes of the traffic
3161 management hierarchy except root node.
3162
3163 Suspend port traffic management hierarchy node
3164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3165
3166    testpmd> suspend port tm node (port_id) (node_id)
3167
3168 Resume port traffic management hierarchy node
3169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3170
3171    testpmd> resume port tm node (port_id) (node_id)
3172
3173 Commit port traffic management hierarchy
3174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3175
3176 Commit the traffic management hierarchy on the port::
3177
3178    testpmd> port tm hierarchy commit (port_id) (clean_on_fail)
3179
3180 where:
3181
3182 * ``clean_on_fail``: When set to non-zero, hierarchy is cleared on function
3183   call failure. On the other hand, hierarchy is preserved when this parameter
3184   is equal to zero.
3185
3186 Set port traffic management mark VLAN dei
3187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3188
3189 Enables/Disables the traffic management marking on the port for VLAN packets::
3190
3191    testpmd> set port tm mark vlan_dei <port_id> <green> <yellow> <red>
3192
3193 where:
3194
3195 * ``port_id``: The port which on which VLAN packets marked as ``green`` or
3196   ``yellow`` or ``red`` will have dei bit enabled
3197
3198 * ``green`` enable 1, disable 0 marking for dei bit of VLAN packets marked as green
3199
3200 * ``yellow`` enable 1, disable 0 marking for dei bit of VLAN packets marked as yellow
3201
3202 * ``red`` enable 1, disable 0 marking for dei bit of VLAN packets marked as red
3203
3204 Set port traffic management mark IP dscp
3205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3206
3207 Enables/Disables the traffic management marking on the port for IP dscp packets::
3208
3209    testpmd> set port tm mark ip_dscp <port_id> <green> <yellow> <red>
3210
3211 where:
3212
3213 * ``port_id``: The port which on which IP packets marked as ``green`` or
3214   ``yellow`` or ``red`` will have IP dscp bits updated
3215
3216 * ``green`` enable 1, disable 0 marking IP dscp to low drop precedence for green packets
3217
3218 * ``yellow`` enable 1, disable 0 marking IP dscp to medium drop precedence for yellow packets
3219
3220 * ``red`` enable 1, disable 0 marking IP dscp to high drop precedence for red packets
3221
3222 Set port traffic management mark IP ecn
3223 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3224
3225 Enables/Disables the traffic management marking on the port for IP ecn packets::
3226
3227    testpmd> set port tm mark ip_ecn <port_id> <green> <yellow> <red>
3228
3229 where:
3230
3231 * ``port_id``: The port which on which IP packets marked as ``green`` or
3232   ``yellow`` or ``red`` will have IP ecn bits updated
3233
3234 * ``green`` enable 1, disable 0 marking IP ecn for green marked packets with ecn of 2'b01  or 2'b10
3235   to ecn of 2'b11 when IP is caring TCP or SCTP
3236
3237 * ``yellow`` enable 1, disable 0 marking IP ecn for yellow marked packets with ecn of 2'b01  or 2'b10
3238   to ecn of 2'b11 when IP is caring TCP or SCTP
3239
3240 * ``red`` enable 1, disable 0 marking IP ecn for yellow marked packets with ecn of 2'b01  or 2'b10
3241   to ecn of 2'b11 when IP is caring TCP or SCTP
3242
3243 Filter Functions
3244 ----------------
3245
3246 This section details the available filter functions that are available.
3247
3248 Note these functions interface the deprecated legacy filtering framework,
3249 superseded by *rte_flow*. See `Flow rules management`_.
3250
3251 .. _testpmd_flow_director:
3252
3253 flow_director_mask
3254 ~~~~~~~~~~~~~~~~~~
3255
3256 Set flow director's input masks::
3257
3258    flow_director_mask (port_id) mode IP vlan (vlan_value) \
3259                       src_mask (ipv4_src) (ipv6_src) (src_port) \
3260                       dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
3261
3262    flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
3263
3264    flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
3265                       mac (mac_value) tunnel-type (tunnel_type_value) \
3266                       tunnel-id (tunnel_id_value)
3267
3268 Example, to set flow director mask on port 0::
3269
3270    testpmd> flow_director_mask 0 mode IP vlan 0xefff \
3271             src_mask 255.255.255.255 \
3272                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
3273             dst_mask 255.255.255.255 \
3274                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
3275
3276 flow_director_flex_payload
3277 ~~~~~~~~~~~~~~~~~~~~~~~~~~
3278
3279 Configure flexible payload selection::
3280
3281    flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
3282
3283 For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
3284
3285    testpmd> flow_director_flex_payload 0 l4 \
3286             (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
3287
3288
3289 .. _testpmd_rte_flow:
3290
3291 Flow rules management
3292 ---------------------
3293
3294 Control of the generic flow API (*rte_flow*) is fully exposed through the
3295 ``flow`` command (validation, creation, destruction, queries and operation
3296 modes).
3297
3298 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
3299 features simultaneously may cause undefined side-effects and is therefore
3300 not recommended.
3301
3302 ``flow`` syntax
3303 ~~~~~~~~~~~~~~~
3304
3305 Because the ``flow`` command uses dynamic tokens to handle the large number
3306 of possible flow rules combinations, its behavior differs slightly from
3307 other commands, in particular:
3308
3309 - Pressing *?* or the *<tab>* key displays contextual help for the current
3310   token, not that of the entire command.
3311
3312 - Optional and repeated parameters are supported (provided they are listed
3313   in the contextual help).
3314
3315 The first parameter stands for the operation mode. Possible operations and
3316 their general syntax are described below. They are covered in detail in the
3317 following sections.
3318
3319 - Check whether a flow rule can be created::
3320
3321    flow validate {port_id}
3322        [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3323        pattern {item} [/ {item} [...]] / end
3324        actions {action} [/ {action} [...]] / end
3325
3326 - Create a flow rule::
3327
3328    flow create {port_id}
3329        [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3330        pattern {item} [/ {item} [...]] / end
3331        actions {action} [/ {action} [...]] / end
3332
3333 - Destroy specific flow rules::
3334
3335    flow destroy {port_id} rule {rule_id} [...]
3336
3337 - Destroy all flow rules::
3338
3339    flow flush {port_id}
3340
3341 - Query an existing flow rule::
3342
3343    flow query {port_id} {rule_id} {action}
3344
3345 - List existing flow rules sorted by priority, filtered by group
3346   identifiers::
3347
3348    flow list {port_id} [group {group_id}] [...]
3349
3350 - Restrict ingress traffic to the defined flow rules::
3351
3352    flow isolate {port_id} {boolean}
3353
3354 - Dump internal representation information of all flows in hardware::
3355
3356    flow dump {port_id} all {output_file}
3357
3358   for one flow::
3359
3360    flow dump {port_id} rule {rule_id} {output_file}
3361
3362 - List and destroy aged flow rules::
3363
3364    flow aged {port_id} [destroy]
3365
3366 - Tunnel offload - create a tunnel stub::
3367
3368    flow tunnel create {port_id} type {tunnel_type}
3369
3370 - Tunnel offload - destroy a tunnel stub::
3371
3372    flow tunnel destroy {port_id} id {tunnel_id}
3373
3374 - Tunnel offload - list port tunnel stubs::
3375
3376    flow tunnel list {port_id}
3377
3378 Creating a tunnel stub for offload
3379 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3380
3381 ``flow tunnel create`` setup a tunnel stub for tunnel offload flow rules::
3382
3383    flow tunnel create {port_id} type {tunnel_type}
3384
3385 If successful, it will return a tunnel stub ID usable with other commands::
3386
3387    port [...]: flow tunnel #[...] type [...]
3388
3389 Tunnel stub ID is relative to a port.
3390
3391 Destroying tunnel offload stub
3392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3393
3394 ``flow tunnel destroy`` destroy port tunnel stub::
3395
3396    flow tunnel destroy {port_id} id {tunnel_id}
3397
3398 Listing tunnel offload stubs
3399 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3400
3401 ``flow tunnel list`` list port tunnel offload stubs::
3402
3403    flow tunnel list {port_id}
3404
3405 Validating flow rules
3406 ~~~~~~~~~~~~~~~~~~~~~
3407
3408 ``flow validate`` reports whether a flow rule would be accepted by the
3409 underlying device in its current state but stops short of creating it. It is
3410 bound to ``rte_flow_validate()``::
3411
3412    flow validate {port_id}
3413       [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3414       pattern {item} [/ {item} [...]] / end
3415       actions {action} [/ {action} [...]] / end
3416
3417 If successful, it will show::
3418
3419    Flow rule validated
3420
3421 Otherwise it will show an error message of the form::
3422
3423    Caught error type [...] ([...]): [...]
3424
3425 This command uses the same parameters as ``flow create``, their format is
3426 described in `Creating flow rules`_.
3427
3428 Check whether redirecting any Ethernet packet received on port 0 to RX queue
3429 index 6 is supported::
3430
3431    testpmd> flow validate 0 ingress pattern eth / end
3432       actions queue index 6 / end
3433    Flow rule validated
3434    testpmd>
3435
3436 Port 0 does not support TCPv6 rules::
3437
3438    testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
3439       actions drop / end
3440    Caught error type 9 (specific pattern item): Invalid argument
3441    testpmd>
3442
3443 Creating flow rules
3444 ~~~~~~~~~~~~~~~~~~~
3445
3446 ``flow create`` validates and creates the specified flow rule. It is bound
3447 to ``rte_flow_create()``::
3448
3449    flow create {port_id}
3450       [group {group_id}] [priority {level}] [ingress] [egress] [transfer]
3451       [tunnel_set {tunnel_id}] [tunnel_match {tunnel_id}]
3452       pattern {item} [/ {item} [...]] / end
3453       actions {action} [/ {action} [...]] / end
3454
3455 If successful, it will return a flow rule ID usable with other commands::
3456
3457    Flow rule #[...] created
3458
3459 Otherwise it will show an error message of the form::
3460
3461    Caught error type [...] ([...]): [...]
3462
3463 Parameters describe in the following order:
3464
3465 - Attributes (*group*, *priority*, *ingress*, *egress*, *transfer* tokens).
3466 - Tunnel offload specification (tunnel_set, tunnel_match)
3467 - A matching pattern, starting with the *pattern* token and terminated by an
3468   *end* pattern item.
3469 - Actions, starting with the *actions* token and terminated by an *end*
3470   action.
3471
3472 These translate directly to *rte_flow* objects provided as-is to the
3473 underlying functions.
3474
3475 The shortest valid definition only comprises mandatory tokens::
3476
3477    testpmd> flow create 0 pattern end actions end
3478
3479 Note that PMDs may refuse rules that essentially do nothing such as this
3480 one.
3481
3482 **All unspecified object values are automatically initialized to 0.**
3483
3484 Attributes
3485 ^^^^^^^^^^
3486
3487 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
3488 specified before the ``pattern`` token.
3489
3490 - ``group {group id}``: priority group.
3491 - ``priority {level}``: priority level within group.
3492 - ``ingress``: rule applies to ingress traffic.
3493 - ``egress``: rule applies to egress traffic.
3494 - ``transfer``: apply rule directly to endpoints found in pattern.
3495
3496 Each instance of an attribute specified several times overrides the previous
3497 value as shown below (group 4 is used)::
3498
3499    testpmd> flow create 0 group 42 group 24 group 4 [...]
3500
3501 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
3502
3503 While not specifying a direction is an error, some rules may allow both
3504 simultaneously.
3505
3506 Most rules affect RX therefore contain the ``ingress`` token::
3507
3508    testpmd> flow create 0 ingress pattern [...]
3509
3510 Tunnel offload
3511 ^^^^^^^^^^^^^^
3512
3513 Indicate tunnel offload rule type
3514
3515 - ``tunnel_set {tunnel_id}``: mark rule as tunnel offload decap_set type.
3516 - ``tunnel_match {tunnel_id}``:  mark rule as tunel offload match type.
3517
3518 Matching pattern
3519 ^^^^^^^^^^^^^^^^
3520
3521 A matching pattern starts after the ``pattern`` token. It is made of pattern
3522 items and is terminated by a mandatory ``end`` item.
3523
3524 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
3525 rte_flow_item_type``).
3526
3527 The ``/`` token is used as a separator between pattern items as shown
3528 below::
3529
3530    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
3531
3532 Note that protocol items like these must be stacked from lowest to highest
3533 layer to make sense. For instance, the following rule is either invalid or
3534 unlikely to match any packet::
3535
3536    testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
3537
3538 More information on these restrictions can be found in the *rte_flow*
3539 documentation.
3540
3541 Several items support additional specification structures, for example
3542 ``ipv4`` allows specifying source and destination addresses as follows::
3543
3544    testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
3545       dst is 10.2.0.0 / end [...]
3546
3547 This rule matches all IPv4 traffic with the specified properties.
3548
3549 In this example, ``src`` and ``dst`` are field names of the underlying
3550 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
3551 in a similar fashion.
3552
3553 The ``is`` token means that the subsequent value must be matched exactly,
3554 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
3555 accordingly. Possible assignment tokens are:
3556
3557 - ``is``: match value perfectly (with full bit-mask).
3558 - ``spec``: match value according to configured bit-mask.
3559 - ``last``: specify upper bound to establish a range.
3560 - ``mask``: specify bit-mask with relevant bits set to one.
3561 - ``prefix``: generate bit-mask with <prefix-length> most-significant bits set to one.
3562
3563 These yield identical results::
3564
3565    ipv4 src is 10.1.1.1
3566
3567 ::
3568
3569    ipv4 src spec 10.1.1.1 src mask 255.255.255.255
3570
3571 ::
3572
3573    ipv4 src spec 10.1.1.1 src prefix 32
3574
3575 ::
3576
3577    ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
3578
3579 ::
3580
3581    ipv4 src is 10.1.1.1 src last 0 # 0 disables range
3582
3583 Inclusive ranges can be defined with ``last``::
3584
3585    ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
3586
3587 Note that ``mask`` affects both ``spec`` and ``last``::
3588
3589    ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
3590       # matches 10.1.0.0 to 10.2.255.255
3591
3592 Properties can be modified multiple times::
3593
3594    ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
3595
3596 ::
3597
3598    ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
3599
3600 Pattern items
3601 ^^^^^^^^^^^^^
3602
3603 This section lists supported pattern items and their attributes, if any.
3604
3605 - ``end``: end list of pattern items.
3606
3607 - ``void``: no-op pattern item.
3608
3609 - ``invert``: perform actions when pattern does not match.
3610
3611 - ``any``: match any protocol for the current layer.
3612
3613   - ``num {unsigned}``: number of layers covered.
3614
3615 - ``pf``: match traffic from/to the physical function.
3616
3617 - ``vf``: match traffic from/to a virtual function ID.
3618
3619   - ``id {unsigned}``: VF ID.
3620
3621 - ``phy_port``: match traffic from/to a specific physical port.
3622
3623   - ``index {unsigned}``: physical port index.
3624
3625 - ``port_id``: match traffic from/to a given DPDK port ID.
3626
3627   - ``id {unsigned}``: DPDK port ID.
3628
3629 - ``mark``: match value set in previously matched flow rule using the mark action.
3630
3631   - ``id {unsigned}``: arbitrary integer value.
3632
3633 - ``raw``: match an arbitrary byte string.
3634
3635   - ``relative {boolean}``: look for pattern after the previous item.
3636   - ``search {boolean}``: search pattern from offset (see also limit).
3637   - ``offset {integer}``: absolute or relative offset for pattern.
3638   - ``limit {unsigned}``: search area limit for start of pattern.
3639   - ``pattern {string}``: byte string to look for.
3640
3641 - ``eth``: match Ethernet header.
3642
3643   - ``dst {MAC-48}``: destination MAC.
3644   - ``src {MAC-48}``: source MAC.
3645   - ``type {unsigned}``: EtherType or TPID.
3646
3647 - ``vlan``: match 802.1Q/ad VLAN tag.
3648
3649   - ``tci {unsigned}``: tag control information.
3650   - ``pcp {unsigned}``: priority code point.
3651   - ``dei {unsigned}``: drop eligible indicator.
3652   - ``vid {unsigned}``: VLAN identifier.
3653   - ``inner_type {unsigned}``: inner EtherType or TPID.
3654
3655 - ``ipv4``: match IPv4 header.
3656
3657   - ``tos {unsigned}``: type of service.
3658   - ``ttl {unsigned}``: time to live.
3659   - ``proto {unsigned}``: next protocol ID.
3660   - ``src {ipv4 address}``: source address.
3661   - ``dst {ipv4 address}``: destination address.
3662
3663 - ``ipv6``: match IPv6 header.
3664
3665   - ``tc {unsigned}``: traffic class.
3666   - ``flow {unsigned}``: flow label.
3667   - ``proto {unsigned}``: protocol (next header).
3668   - ``hop {unsigned}``: hop limit.
3669   - ``src {ipv6 address}``: source address.
3670   - ``dst {ipv6 address}``: destination address.
3671
3672 - ``icmp``: match ICMP header.
3673
3674   - ``type {unsigned}``: ICMP packet type.
3675   - ``code {unsigned}``: ICMP packet code.
3676
3677 - ``udp``: match UDP header.
3678
3679   - ``src {unsigned}``: UDP source port.
3680   - ``dst {unsigned}``: UDP destination port.
3681
3682 - ``tcp``: match TCP header.
3683
3684   - ``src {unsigned}``: TCP source port.
3685   - ``dst {unsigned}``: TCP destination port.
3686
3687 - ``sctp``: match SCTP header.
3688
3689   - ``src {unsigned}``: SCTP source port.
3690   - ``dst {unsigned}``: SCTP destination port.
3691   - ``tag {unsigned}``: validation tag.
3692   - ``cksum {unsigned}``: checksum.
3693
3694 - ``vxlan``: match VXLAN header.
3695
3696   - ``vni {unsigned}``: VXLAN identifier.
3697
3698 - ``e_tag``: match IEEE 802.1BR E-Tag header.
3699
3700   - ``grp_ecid_b {unsigned}``: GRP and E-CID base.
3701
3702 - ``nvgre``: match NVGRE header.
3703
3704   - ``tni {unsigned}``: virtual subnet ID.
3705
3706 - ``mpls``: match MPLS header.
3707
3708   - ``label {unsigned}``: MPLS label.
3709
3710 - ``gre``: match GRE header.
3711
3712   - ``protocol {unsigned}``: protocol type.
3713
3714 - ``gre_key``: match GRE optional key field.
3715
3716   - ``value {unsigned}``: key value.
3717
3718 - ``fuzzy``: fuzzy pattern match, expect faster than default.
3719
3720   - ``thresh {unsigned}``: accuracy threshold.
3721
3722 - ``gtp``, ``gtpc``, ``gtpu``: match GTPv1 header.
3723
3724   - ``teid {unsigned}``: tunnel endpoint identifier.
3725
3726 - ``geneve``: match GENEVE header.
3727
3728   - ``vni {unsigned}``: virtual network identifier.
3729   - ``protocol {unsigned}``: protocol type.
3730
3731 - ``geneve-opt``: match GENEVE header option.
3732
3733   - ``class {unsigned}``: GENEVE option class.
3734   - ``type {unsigned}``: GENEVE option type.
3735   - ``length {unsigned}``: GENEVE option length in 32-bit words.
3736   - ``data {hex string}``: GENEVE option data, the length is defined by
3737     ``length`` field.
3738
3739 - ``vxlan-gpe``: match VXLAN-GPE header.
3740
3741   - ``vni {unsigned}``: VXLAN-GPE identifier.
3742
3743 - ``arp_eth_ipv4``: match ARP header for Ethernet/IPv4.
3744
3745   - ``sha {MAC-48}``: sender hardware address.
3746   - ``spa {ipv4 address}``: sender IPv4 address.
3747   - ``tha {MAC-48}``: target hardware address.
3748   - ``tpa {ipv4 address}``: target IPv4 address.
3749
3750 - ``ipv6_ext``: match presence of any IPv6 extension header.
3751
3752   - ``next_hdr {unsigned}``: next header.
3753
3754 - ``icmp6``: match any ICMPv6 header.
3755
3756   - ``type {unsigned}``: ICMPv6 type.
3757   - ``code {unsigned}``: ICMPv6 code.
3758
3759 - ``icmp6_nd_ns``: match ICMPv6 neighbor discovery solicitation.
3760
3761   - ``target_addr {ipv6 address}``: target address.
3762
3763 - ``icmp6_nd_na``: match ICMPv6 neighbor discovery advertisement.
3764
3765   - ``target_addr {ipv6 address}``: target address.
3766
3767 - ``icmp6_nd_opt``: match presence of any ICMPv6 neighbor discovery option.
3768
3769   - ``type {unsigned}``: ND option type.
3770
3771 - ``icmp6_nd_opt_sla_eth``: match ICMPv6 neighbor discovery source Ethernet
3772   link-layer address option.
3773
3774   - ``sla {MAC-48}``: source Ethernet LLA.
3775
3776 - ``icmp6_nd_opt_tla_eth``: match ICMPv6 neighbor discovery target Ethernet
3777   link-layer address option.
3778
3779   - ``tla {MAC-48}``: target Ethernet LLA.
3780
3781 - ``meta``: match application specific metadata.
3782
3783   - ``data {unsigned}``: metadata value.
3784
3785 - ``gtp_psc``: match GTP PDU extension header with type 0x85.
3786
3787   - ``pdu_type {unsigned}``: PDU type.
3788
3789   - ``qfi {unsigned}``: PPP, RQI and QoS flow identifier.
3790
3791 - ``pppoes``, ``pppoed``: match PPPoE header.
3792
3793   - ``session_id {unsigned}``: session identifier.
3794
3795 - ``pppoe_proto_id``: match PPPoE session protocol identifier.
3796
3797   - ``proto_id {unsigned}``: PPP protocol identifier.
3798
3799 - ``l2tpv3oip``: match L2TPv3 over IP header.
3800
3801   - ``session_id {unsigned}``: L2TPv3 over IP session identifier.
3802
3803 - ``ah``: match AH header.
3804
3805   - ``spi {unsigned}``: security parameters index.
3806
3807 - ``pfcp``: match PFCP header.
3808
3809   - ``s_field {unsigned}``: S field.
3810   - ``seid {unsigned}``: session endpoint identifier.
3811
3812 - ``integrity``: match packet integrity.
3813
3814    - ``level {unsigned}``: Packet encapsulation level the item should
3815      apply to. See rte_flow_action_rss for details.
3816    - ``value {unsigned}``: A bitmask that specify what packet elements
3817      must be matched for integrity.
3818
3819 - ``conntrack``: match conntrack state.
3820
3821 Actions list
3822 ^^^^^^^^^^^^
3823
3824 A list of actions starts after the ``actions`` token in the same fashion as
3825 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
3826 terminated by a mandatory ``end`` action.
3827
3828 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
3829 rte_flow_action_type``).
3830
3831 Dropping all incoming UDPv4 packets can be expressed as follows::
3832
3833    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
3834       actions drop / end
3835
3836 Several actions have configurable properties which must be specified when
3837 there is no valid default value. For example, ``queue`` requires a target
3838 queue index.
3839
3840 This rule redirects incoming UDPv4 traffic to queue index 6::
3841
3842    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
3843       actions queue index 6 / end
3844
3845 While this one could be rejected by PMDs (unspecified queue index)::
3846
3847    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
3848       actions queue / end
3849
3850 As defined by *rte_flow*, the list is not ordered, all actions of a given
3851 rule are performed simultaneously. These are equivalent::
3852
3853    queue index 6 / void / mark id 42 / end
3854
3855 ::
3856
3857    void / mark id 42 / queue index 6 / end
3858
3859 All actions in a list should have different types, otherwise only the last
3860 action of a given type is taken into account::
3861
3862    queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
3863
3864 ::
3865
3866    drop / drop / drop / end # drop is performed only once
3867
3868 ::
3869
3870    mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
3871
3872 Considering they are performed simultaneously, opposite and overlapping
3873 actions can sometimes be combined when the end result is unambiguous::
3874
3875    drop / queue index 6 / end # drop has no effect
3876
3877 ::
3878
3879    queue index 6 / rss queues 6 7 8 / end # queue has no effect
3880
3881 ::
3882
3883    drop / passthru / end # drop has no effect
3884
3885 Note that PMDs may still refuse such combinations.
3886
3887 Actions
3888 ^^^^^^^
3889
3890 This section lists supported actions and their attributes, if any.
3891
3892 - ``end``: end list of actions.
3893
3894 - ``void``: no-op action.
3895
3896 - ``passthru``: let subsequent rule process matched packets.
3897
3898 - ``jump``: redirect traffic to group on device.
3899
3900   - ``group {unsigned}``: group to redirect to.
3901
3902 - ``mark``: attach 32 bit value to packets.
3903
3904   - ``id {unsigned}``: 32 bit value to return with packets.
3905
3906 - ``flag``: flag packets.
3907
3908 - ``queue``: assign packets to a given queue index.
3909
3910   - ``index {unsigned}``: queue index to use.
3911
3912 - ``drop``: drop packets (note: passthru has priority).
3913
3914 - ``count``: enable counters for this rule.
3915
3916 - ``rss``: spread packets among several queues.
3917
3918   - ``func {hash function}``: RSS hash function to apply, allowed tokens are
3919     ``toeplitz``, ``simple_xor``, ``symmetric_toeplitz`` and ``default``.
3920
3921   - ``level {unsigned}``: encapsulation level for ``types``.
3922
3923   - ``types [{RSS hash type} [...]] end``: specific RSS hash types.
3924     Note that an empty list does not disable RSS but instead requests
3925     unspecified "best-effort" settings.
3926
3927   - ``key {string}``: RSS hash key, overrides ``key_len``.
3928
3929   - ``key_len {unsigned}``: RSS hash key length in bytes, can be used in
3930     conjunction with ``key`` to pad or truncate it.
3931
3932   - ``queues [{unsigned} [...]] end``: queue indices to use.
3933
3934 - ``pf``: direct traffic to physical function.
3935
3936 - ``vf``: direct traffic to a virtual function ID.
3937
3938   - ``original {boolean}``: use original VF ID if possible.
3939   - ``id {unsigned}``: VF ID.
3940
3941 - ``phy_port``: direct packets to physical port index.
3942
3943   - ``original {boolean}``: use original port index if possible.
3944   - ``index {unsigned}``: physical port index.
3945
3946 - ``port_id``: direct matching traffic to a given DPDK port ID.
3947
3948   - ``original {boolean}``: use original DPDK port ID if possible.
3949   - ``id {unsigned}``: DPDK port ID.
3950
3951 - ``of_set_mpls_ttl``: OpenFlow's ``OFPAT_SET_MPLS_TTL``.
3952
3953   - ``mpls_ttl``: MPLS TTL.
3954
3955 - ``of_dec_mpls_ttl``: OpenFlow's ``OFPAT_DEC_MPLS_TTL``.
3956
3957 - ``of_set_nw_ttl``: OpenFlow's ``OFPAT_SET_NW_TTL``.
3958
3959   - ``nw_ttl``: IP TTL.
3960
3961 - ``of_dec_nw_ttl``: OpenFlow's ``OFPAT_DEC_NW_TTL``.
3962
3963 - ``of_copy_ttl_out``: OpenFlow's ``OFPAT_COPY_TTL_OUT``.
3964
3965 - ``of_copy_ttl_in``: OpenFlow's ``OFPAT_COPY_TTL_IN``.
3966
3967 - ``of_pop_vlan``: OpenFlow's ``OFPAT_POP_VLAN``.
3968
3969 - ``of_push_vlan``: OpenFlow's ``OFPAT_PUSH_VLAN``.
3970
3971   - ``ethertype``: Ethertype.
3972
3973 - ``of_set_vlan_vid``: OpenFlow's ``OFPAT_SET_VLAN_VID``.
3974
3975   - ``vlan_vid``: VLAN id.
3976
3977 - ``of_set_vlan_pcp``: OpenFlow's ``OFPAT_SET_VLAN_PCP``.
3978
3979   - ``vlan_pcp``: VLAN priority.
3980
3981 - ``of_pop_mpls``: OpenFlow's ``OFPAT_POP_MPLS``.
3982
3983   - ``ethertype``: Ethertype.
3984
3985 - ``of_push_mpls``: OpenFlow's ``OFPAT_PUSH_MPLS``.
3986
3987   - ``ethertype``: Ethertype.
3988
3989 - ``vxlan_encap``: Performs a VXLAN encapsulation, outer layer configuration
3990   is done through `Config VXLAN Encap outer layers`_.
3991
3992 - ``vxlan_decap``: Performs a decapsulation action by stripping all headers of
3993   the VXLAN tunnel network overlay from the matched flow.
3994
3995 - ``nvgre_encap``: Performs a NVGRE encapsulation, outer layer configuration
3996   is done through `Config NVGRE Encap outer layers`_.
3997
3998 - ``nvgre_decap``: Performs a decapsulation action by stripping all headers of
3999   the NVGRE tunnel network overlay from the matched flow.
4000
4001 - ``l2_encap``: Performs a L2 encapsulation, L2 configuration
4002   is done through `Config L2 Encap`_.
4003
4004 - ``l2_decap``: Performs a L2 decapsulation, L2 configuration
4005   is done through `Config L2 Decap`_.
4006
4007 - ``mplsogre_encap``: Performs a MPLSoGRE encapsulation, outer layer
4008   configuration is done through `Config MPLSoGRE Encap outer layers`_.
4009
4010 - ``mplsogre_decap``: Performs a MPLSoGRE decapsulation, outer layer
4011   configuration is done through `Config MPLSoGRE Decap outer layers`_.
4012
4013 - ``mplsoudp_encap``: Performs a MPLSoUDP encapsulation, outer layer
4014   configuration is done through `Config MPLSoUDP Encap outer layers`_.
4015
4016 - ``mplsoudp_decap``: Performs a MPLSoUDP decapsulation, outer layer
4017   configuration is done through `Config MPLSoUDP Decap outer layers`_.
4018
4019 - ``set_ipv4_src``: Set a new IPv4 source address in the outermost IPv4 header.
4020
4021   - ``ipv4_addr``: New IPv4 source address.
4022
4023 - ``set_ipv4_dst``: Set a new IPv4 destination address in the outermost IPv4
4024   header.
4025
4026   - ``ipv4_addr``: New IPv4 destination address.
4027
4028 - ``set_ipv6_src``: Set a new IPv6 source address in the outermost IPv6 header.
4029
4030   - ``ipv6_addr``: New IPv6 source address.
4031
4032 - ``set_ipv6_dst``: Set a new IPv6 destination address in the outermost IPv6
4033   header.
4034
4035   - ``ipv6_addr``: New IPv6 destination address.
4036
4037 - ``set_tp_src``: Set a new source port number in the outermost TCP/UDP
4038   header.
4039
4040   - ``port``: New TCP/UDP source port number.
4041
4042 - ``set_tp_dst``: Set a new destination port number in the outermost TCP/UDP
4043   header.
4044
4045   - ``port``: New TCP/UDP destination port number.
4046
4047 - ``mac_swap``: Swap the source and destination MAC addresses in the outermost
4048   Ethernet header.
4049
4050 - ``dec_ttl``: Performs a decrease TTL value action
4051
4052 - ``set_ttl``: Set TTL value with specified value
4053   - ``ttl_value {unsigned}``: The new TTL value to be set
4054
4055 - ``set_mac_src``: set source MAC address
4056
4057   - ``mac_addr {MAC-48}``: new source MAC address
4058
4059 - ``set_mac_dst``: set destination MAC address
4060
4061   - ``mac_addr {MAC-48}``: new destination MAC address
4062
4063 - ``inc_tcp_seq``: Increase sequence number in the outermost TCP header.
4064
4065   - ``value {unsigned}``: Value to increase TCP sequence number by.
4066
4067 - ``dec_tcp_seq``: Decrease sequence number in the outermost TCP header.
4068
4069   - ``value {unsigned}``: Value to decrease TCP sequence number by.
4070
4071 - ``inc_tcp_ack``: Increase acknowledgment number in the outermost TCP header.
4072
4073   - ``value {unsigned}``: Value to increase TCP acknowledgment number by.
4074
4075 - ``dec_tcp_ack``: Decrease acknowledgment number in the outermost TCP header.
4076
4077   - ``value {unsigned}``: Value to decrease TCP acknowledgment number by.
4078
4079 - ``set_ipv4_dscp``: Set IPv4 DSCP value with specified value
4080
4081   - ``dscp_value {unsigned}``: The new DSCP value to be set
4082
4083 - ``set_ipv6_dscp``: Set IPv6 DSCP value with specified value
4084
4085   - ``dscp_value {unsigned}``: The new DSCP value to be set
4086
4087 - ``indirect``: Use indirect action created via
4088   ``flow indirect_action {port_id} create``
4089
4090   - ``indirect_action_id {unsigned}``: Indirect action ID to use
4091
4092 - ``color``: Color the packet to reflect the meter color result
4093
4094   - ``type {value}``: Set color type with specified value(green/yellow/red)
4095
4096 Destroying flow rules
4097 ~~~~~~~~~~~~~~~~~~~~~
4098
4099 ``flow destroy`` destroys one or more rules from their rule ID (as returned
4100 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
4101 times as necessary::
4102
4103    flow destroy {port_id} rule {rule_id} [...]
4104
4105 If successful, it will show::
4106
4107    Flow rule #[...] destroyed
4108
4109 It does not report anything for rule IDs that do not exist. The usual error
4110 message is shown when a rule cannot be destroyed::
4111
4112    Caught error type [...] ([...]): [...]
4113
4114 ``flow flush`` destroys all rules on a device and does not take extra
4115 arguments. It is bound to ``rte_flow_flush()``::
4116
4117    flow flush {port_id}
4118
4119 Any errors are reported as above.
4120
4121 Creating several rules and destroying them::
4122
4123    testpmd> flow create 0 ingress pattern eth / ipv6 / end
4124       actions queue index 2 / end
4125    Flow rule #0 created
4126    testpmd> flow create 0 ingress pattern eth / ipv4 / end
4127       actions queue index 3 / end
4128    Flow rule #1 created
4129    testpmd> flow destroy 0 rule 0 rule 1
4130    Flow rule #1 destroyed
4131    Flow rule #0 destroyed
4132    testpmd>
4133
4134 The same result can be achieved using ``flow flush``::
4135
4136    testpmd> flow create 0 ingress pattern eth / ipv6 / end
4137       actions queue index 2 / end
4138    Flow rule #0 created
4139    testpmd> flow create 0 ingress pattern eth / ipv4 / end
4140       actions queue index 3 / end
4141    Flow rule #1 created
4142    testpmd> flow flush 0
4143    testpmd>
4144
4145 Non-existent rule IDs are ignored::
4146
4147    testpmd> flow create 0 ingress pattern eth / ipv6 / end
4148       actions queue index 2 / end
4149    Flow rule #0 created
4150    testpmd> flow create 0 ingress pattern eth / ipv4 / end
4151       actions queue index 3 / end
4152    Flow rule #1 created
4153    testpmd> flow destroy 0 rule 42 rule 10 rule 2
4154    testpmd>
4155    testpmd> flow destroy 0 rule 0
4156    Flow rule #0 destroyed
4157    testpmd>
4158
4159 Querying flow rules
4160 ~~~~~~~~~~~~~~~~~~~
4161
4162 ``flow query`` queries a specific action of a flow rule having that
4163 ability. Such actions collect information that can be reported using this
4164 command. It is bound to ``rte_flow_query()``::
4165
4166    flow query {port_id} {rule_id} {action}
4167
4168 If successful, it will display either the retrieved data for known actions
4169 or the following message::
4170
4171    Cannot display result for action type [...] ([...])
4172
4173 Otherwise, it will complain either that the rule does not exist or that some
4174 error occurred::
4175
4176    Flow rule #[...] not found
4177
4178 ::
4179
4180    Caught error type [...] ([...]): [...]
4181
4182 Currently only the ``count`` action is supported. This action reports the
4183 number of packets that hit the flow rule and the total number of bytes. Its
4184 output has the following format::
4185
4186    count:
4187     hits_set: [...] # whether "hits" contains a valid value
4188     bytes_set: [...] # whether "bytes" contains a valid value
4189     hits: [...] # number of packets
4190     bytes: [...] # number of bytes
4191
4192 Querying counters for TCPv6 packets redirected to queue 6::
4193
4194    testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
4195       actions queue index 6 / count / end
4196    Flow rule #4 created
4197    testpmd> flow query 0 4 count
4198    count:
4199     hits_set: 1
4200     bytes_set: 0
4201     hits: 386446
4202     bytes: 0
4203    testpmd>
4204
4205 Listing flow rules
4206 ~~~~~~~~~~~~~~~~~~
4207
4208 ``flow list`` lists existing flow rules sorted by priority and optionally
4209 filtered by group identifiers::
4210
4211    flow list {port_id} [group {group_id}] [...]
4212
4213 This command only fails with the following message if the device does not
4214 exist::
4215
4216    Invalid port [...]
4217
4218 Output consists of a header line followed by a short description of each
4219 flow rule, one per line. There is no output at all when no flow rules are
4220 configured on the device::
4221
4222    ID      Group   Prio    Attr    Rule
4223    [...]   [...]   [...]   [...]   [...]
4224
4225 ``Attr`` column flags:
4226
4227 - ``i`` for ``ingress``.
4228 - ``e`` for ``egress``.
4229
4230 Creating several flow rules and listing them::
4231
4232    testpmd> flow create 0 ingress pattern eth / ipv4 / end
4233       actions queue index 6 / end
4234    Flow rule #0 created
4235    testpmd> flow create 0 ingress pattern eth / ipv6 / end
4236       actions queue index 2 / end
4237    Flow rule #1 created
4238    testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
4239       actions rss queues 6 7 8 end / end
4240    Flow rule #2 created
4241    testpmd> flow list 0
4242    ID      Group   Prio    Attr    Rule
4243    0       0       0       i-      ETH IPV4 => QUEUE
4244    1       0       0       i-      ETH IPV6 => QUEUE
4245    2       0       5       i-      ETH IPV4 UDP => RSS
4246    testpmd>
4247
4248 Rules are sorted by priority (i.e. group ID first, then priority level)::
4249
4250    testpmd> flow list 1
4251    ID      Group   Prio    Attr    Rule
4252    0       0       0       i-      ETH => COUNT
4253    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
4254    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
4255    1       24      0       i-      ETH IPV4 UDP => QUEUE
4256    4       24      10      i-      ETH IPV4 TCP => DROP
4257    3       24      20      i-      ETH IPV4 => DROP
4258    2       24      42      i-      ETH IPV4 UDP => QUEUE
4259    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
4260    testpmd>
4261
4262 Output can be limited to specific groups::
4263
4264    testpmd> flow list 1 group 0 group 63
4265    ID      Group   Prio    Attr    Rule
4266    0       0       0       i-      ETH => COUNT
4267    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
4268    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
4269    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
4270    testpmd>
4271
4272 Toggling isolated mode
4273 ~~~~~~~~~~~~~~~~~~~~~~
4274
4275 ``flow isolate`` can be used to tell the underlying PMD that ingress traffic
4276 must only be injected from the defined flow rules; that no default traffic
4277 is expected outside those rules and the driver is free to assign more
4278 resources to handle them. It is bound to ``rte_flow_isolate()``::
4279
4280  flow isolate {port_id} {boolean}
4281
4282 If successful, enabling or disabling isolated mode shows either::
4283
4284  Ingress traffic on port [...]
4285     is now restricted to the defined flow rules
4286
4287 Or::
4288
4289  Ingress traffic on port [...]
4290     is not restricted anymore to the defined flow rules
4291
4292 Otherwise, in case of error::
4293
4294    Caught error type [...] ([...]): [...]
4295
4296 Mainly due to its side effects, PMDs supporting this mode may not have the
4297 ability to toggle it more than once without reinitializing affected ports
4298 first (e.g. by exiting testpmd).
4299
4300 Enabling isolated mode::
4301
4302  testpmd> flow isolate 0 true
4303  Ingress traffic on port 0 is now restricted to the defined flow rules
4304  testpmd>
4305
4306 Disabling isolated mode::
4307
4308  testpmd> flow isolate 0 false
4309  Ingress traffic on port 0 is not restricted anymore to the defined flow rules
4310  testpmd>
4311
4312 Dumping HW internal information
4313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4314
4315 ``flow dump`` dumps the hardware's internal representation information of
4316 all flows. It is bound to ``rte_flow_dev_dump()``::
4317
4318    flow dump {port_id} {output_file}
4319
4320 If successful, it will show::
4321
4322    Flow dump finished
4323
4324 Otherwise, it will complain error occurred::
4325
4326    Caught error type [...] ([...]): [...]
4327
4328 Listing and destroying aged flow rules
4329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4330
4331 ``flow aged`` simply lists aged flow rules be get from api ``rte_flow_get_aged_flows``,
4332 and ``destroy`` parameter can be used to destroy those flow rules in PMD.
4333
4334    flow aged {port_id} [destroy]
4335
4336 Listing current aged flow rules::
4337
4338    testpmd> flow aged 0
4339    Port 0 total aged flows: 0
4340    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.14 / end
4341       actions age timeout 5 / queue index 0 /  end
4342    Flow rule #0 created
4343    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.15 / end
4344       actions age timeout 4 / queue index 0 /  end
4345    Flow rule #1 created
4346    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.16 / end
4347       actions age timeout 2 / queue index 0 /  end
4348    Flow rule #2 created
4349    testpmd> flow create 0 ingress pattern eth / ipv4 src is 2.2.2.17 / end
4350       actions age timeout 3 / queue index 0 /  end
4351    Flow rule #3 created
4352
4353
4354 Aged Rules are simply list as command ``flow list {port_id}``, but strip the detail rule
4355 information, all the aged flows are sorted by the longest timeout time. For example, if
4356 those rules be configured in the same time, ID 2 will be the first aged out rule, the next
4357 will be ID 3, ID 1, ID 0::
4358
4359    testpmd> flow aged 0
4360    Port 0 total aged flows: 4
4361    ID      Group   Prio    Attr
4362    2       0       0       i--
4363    3       0       0       i--
4364    1       0       0       i--
4365    0       0       0       i--
4366
4367 If attach ``destroy`` parameter, the command will destroy all the list aged flow rules.
4368
4369    testpmd> flow aged 0 destroy
4370    Port 0 total aged flows: 4
4371    ID      Group   Prio    Attr
4372    2       0       0       i--
4373    3       0       0       i--
4374    1       0       0       i--
4375    0       0       0       i--
4376
4377    Flow rule #2 destroyed
4378    Flow rule #3 destroyed
4379    Flow rule #1 destroyed
4380    Flow rule #0 destroyed
4381    4 flows be destroyed
4382    testpmd> flow aged 0
4383    Port 0 total aged flows: 0
4384
4385 Creating indirect actions
4386 ~~~~~~~~~~~~~~~~~~~~~~~~~
4387
4388 ``flow indirect_action {port_id} create`` creates indirect action with optional
4389 indirect action ID. It is bound to ``rte_flow_action_handle_create()``::
4390
4391    flow indirect_action {port_id} create [action_id {indirect_action_id}]
4392       [ingress] [egress] [transfer] action {action} / end
4393
4394 If successful, it will show::
4395
4396    Indirect action #[...] created
4397
4398 Otherwise, it will complain either that indirect action already exists or that
4399 some error occurred::
4400
4401    Indirect action #[...] is already assigned, delete it first
4402
4403 ::
4404
4405    Caught error type [...] ([...]): [...]
4406
4407 Create indirect rss action with id 100 to queues 1 and 2 on port 0::
4408
4409    testpmd> flow indirect_action 0 create action_id 100 \
4410       ingress action rss queues 1 2 end / end
4411
4412 Create indirect rss action with id assigned by testpmd to queues 1 and 2 on
4413 port 0::
4414
4415         testpmd> flow indirect_action 0 create action_id \
4416                 ingress action rss queues 0 1 end / end
4417
4418 Updating indirect actions
4419 ~~~~~~~~~~~~~~~~~~~~~~~~~
4420
4421 ``flow indirect_action {port_id} update`` updates configuration of the indirect
4422 action from its indirect action ID (as returned by
4423 ``flow indirect_action {port_id} create``). It is bound to
4424 ``rte_flow_action_handle_update()``::
4425
4426    flow indirect_action {port_id} update {indirect_action_id}
4427       action {action} / end
4428
4429 If successful, it will show::
4430
4431    Indirect action #[...] updated
4432
4433 Otherwise, it will complain either that indirect action not found or that some
4434 error occurred::
4435
4436    Failed to find indirect action #[...] on port [...]
4437
4438 ::
4439
4440    Caught error type [...] ([...]): [...]
4441
4442 Update indirect rss action having id 100 on port 0 with rss to queues 0 and 3
4443 (in create example above rss queues were 1 and 2)::
4444
4445    testpmd> flow indirect_action 0 update 100 action rss queues 0 3 end / end
4446
4447 Destroying indirect actions
4448 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4449
4450 ``flow indirect_action {port_id} destroy`` destroys one or more indirect actions
4451 from their indirect action IDs (as returned by
4452 ``flow indirect_action {port_id} create``). It is bound to
4453 ``rte_flow_action_handle_destroy()``::
4454
4455    flow indirect_action {port_id} destroy action_id {indirect_action_id} [...]
4456
4457 If successful, it will show::
4458
4459    Indirect action #[...] destroyed
4460
4461 It does not report anything for indirect action IDs that do not exist.
4462 The usual error message is shown when a indirect action cannot be destroyed::
4463
4464    Caught error type [...] ([...]): [...]
4465
4466 Destroy indirect actions having id 100 & 101::
4467
4468    testpmd> flow indirect_action 0 destroy action_id 100 action_id 101
4469
4470 Query indirect actions
4471 ~~~~~~~~~~~~~~~~~~~~~~
4472
4473 ``flow indirect_action {port_id} query`` queries the indirect action from its
4474 indirect action ID (as returned by ``flow indirect_action {port_id} create``).
4475 It is bound to ``rte_flow_action_handle_query()``::
4476
4477   flow indirect_action {port_id} query {indirect_action_id}
4478
4479 Currently only rss indirect action supported. If successful, it will show::
4480
4481    Indirect RSS action:
4482       refs:[...]
4483
4484 Otherwise, it will complain either that indirect action not found or that some
4485 error occurred::
4486
4487    Failed to find indirect action #[...] on port [...]
4488
4489 ::
4490
4491    Caught error type [...] ([...]): [...]
4492
4493 Query indirect action having id 100::
4494
4495    testpmd> flow indirect_action 0 query 100
4496
4497 Sample QinQ flow rules
4498 ~~~~~~~~~~~~~~~~~~~~~~
4499
4500 Before creating QinQ rule(s) the following commands should be issued to enable QinQ::
4501
4502    testpmd> port stop 0
4503    testpmd> vlan set extend on 0
4504
4505 The above command sets the inner and outer TPID's to 0x8100.
4506
4507 To change the TPID's the following commands should be used::
4508
4509    testpmd> vlan set outer tpid 0x88A8 0
4510    testpmd> vlan set inner tpid 0x8100 0
4511    testpmd> port start 0
4512
4513 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM.
4514
4515 ::
4516
4517    testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 /
4518        vlan tci is 456 / end actions vf id 1 / queue index 0 / end
4519    Flow rule #0 validated
4520
4521    testpmd> flow create 0 ingress pattern eth / vlan tci is 4 /
4522        vlan tci is 456 / end actions vf id 123 / queue index 0 / end
4523    Flow rule #0 created
4524
4525    testpmd> flow list 0
4526    ID      Group   Prio    Attr    Rule
4527    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
4528
4529 Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host.
4530
4531 ::
4532
4533    testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 /
4534         vlan tci is 654 / end actions pf / queue index 0 / end
4535    Flow rule #1 validated
4536
4537    testpmd> flow create 0 ingress pattern eth / vlan tci is 321 /
4538         vlan tci is 654 / end actions pf / queue index 1 / end
4539    Flow rule #1 created
4540
4541    testpmd> flow list 0
4542    ID      Group   Prio    Attr    Rule
4543    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
4544    1       0       0       i-      ETH VLAN VLAN=>PF QUEUE
4545
4546 Sample VXLAN flow rules
4547 ~~~~~~~~~~~~~~~~~~~~~~~
4548
4549 Before creating VXLAN rule(s), the UDP port should be added for VXLAN packet
4550 filter on a port::
4551
4552   testpmd> rx_vxlan_port add 4789 0
4553
4554 Create VXLAN rules on port 0 to steer traffic to PF queues.
4555
4556 ::
4557
4558   testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan /
4559          eth dst is 00:11:22:33:44:55 / end actions pf / queue index 1 / end
4560   Flow rule #0 created
4561
4562   testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan vni is 3 /
4563          eth dst is 00:11:22:33:44:55 / end actions pf / queue index 2 / end
4564   Flow rule #1 created
4565
4566   testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan /
4567          eth dst is 00:11:22:33:44:55 / vlan tci is 10 / end actions pf /
4568          queue index 3 / end
4569   Flow rule #2 created
4570
4571   testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan vni is 5 /
4572          eth dst is 00:11:22:33:44:55 / vlan tci is 20 / end actions pf /
4573          queue index 4 / end
4574   Flow rule #3 created
4575
4576   testpmd> flow create 0 ingress pattern eth dst is 00:00:00:00:01:00 / ipv4 /
4577          udp / vxlan vni is 6 /  eth dst is 00:11:22:33:44:55 / end actions pf /
4578          queue index 5 / end
4579   Flow rule #4 created
4580
4581   testpmd> flow list 0
4582   ID      Group   Prio    Attr    Rule
4583   0       0       0       i-      ETH IPV4 UDP VXLAN ETH => QUEUE
4584   1       0       0       i-      ETH IPV4 UDP VXLAN ETH => QUEUE
4585   2       0       0       i-      ETH IPV4 UDP VXLAN ETH VLAN => QUEUE
4586   3       0       0       i-      ETH IPV4 UDP VXLAN ETH VLAN => QUEUE
4587   4       0       0       i-      ETH IPV4 UDP VXLAN ETH => QUEUE
4588
4589 Sample VXLAN encapsulation rule
4590 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4591
4592 VXLAN encapsulation outer layer has default value pre-configured in testpmd
4593 source code, those can be changed by using the following commands
4594
4595 IPv4 VXLAN outer header::
4596
4597  testpmd> set vxlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src 127.0.0.1
4598         ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4599  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4600         queue index 0 / end
4601
4602  testpmd> set vxlan-with-vlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src
4603          127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34 eth-src 11:11:11:11:11:11
4604          eth-dst 22:22:22:22:22:22
4605  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4606          queue index 0 / end
4607
4608  testpmd> set vxlan-tos-ttl ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-tos 0
4609          ip-ttl 255 ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
4610          eth-dst 22:22:22:22:22:22
4611  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4612          queue index 0 / end
4613
4614 IPv6 VXLAN outer header::
4615
4616  testpmd> set vxlan ip-version ipv6 vni 4 udp-src 4 udp-dst 4 ip-src ::1
4617         ip-dst ::2222 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4618  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4619          queue index 0 / end
4620
4621  testpmd> set vxlan-with-vlan ip-version ipv6 vni 4 udp-src 4 udp-dst 4
4622          ip-src ::1 ip-dst ::2222 vlan-tci 34 eth-src 11:11:11:11:11:11
4623          eth-dst 22:22:22:22:22:22
4624  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4625          queue index 0 / end
4626
4627  testpmd> set vxlan-tos-ttl ip-version ipv6 vni 4 udp-src 4 udp-dst 4
4628          ip-tos 0 ip-ttl 255 ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
4629          eth-dst 22:22:22:22:22:22
4630  testpmd> flow create 0 ingress pattern end actions vxlan_encap /
4631          queue index 0 / end
4632
4633 Sample NVGRE encapsulation rule
4634 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4635
4636 NVGRE encapsulation outer layer has default value pre-configured in testpmd
4637 source code, those can be changed by using the following commands
4638
4639 IPv4 NVGRE outer header::
4640
4641  testpmd> set nvgre ip-version ipv4 tni 4 ip-src 127.0.0.1 ip-dst 128.0.0.1
4642         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4643  testpmd> flow create 0 ingress pattern end actions nvgre_encap /
4644         queue index 0 / end
4645
4646  testpmd> set nvgre-with-vlan ip-version ipv4 tni 4 ip-src 127.0.0.1
4647          ip-dst 128.0.0.1 vlan-tci 34 eth-src 11:11:11:11:11:11
4648          eth-dst 22:22:22:22:22:22
4649  testpmd> flow create 0 ingress pattern end actions nvgre_encap /
4650          queue index 0 / end
4651
4652 IPv6 NVGRE outer header::
4653
4654  testpmd> set nvgre ip-version ipv6 tni 4 ip-src ::1 ip-dst ::2222
4655         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4656  testpmd> flow create 0 ingress pattern end actions nvgre_encap /
4657         queue index 0 / end
4658
4659  testpmd> set nvgre-with-vlan ip-version ipv6 tni 4 ip-src ::1 ip-dst ::2222
4660         vlan-tci 34 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4661  testpmd> flow create 0 ingress pattern end actions nvgre_encap /
4662         queue index 0 / end
4663
4664 Sample L2 encapsulation rule
4665 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4666
4667 L2 encapsulation has default value pre-configured in testpmd
4668 source code, those can be changed by using the following commands
4669
4670 L2 header::
4671
4672  testpmd> set l2_encap ip-version ipv4
4673         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4674  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
4675         mplsoudp_decap / l2_encap / end
4676
4677 L2 with VXLAN header::
4678
4679  testpmd> set l2_encap-with-vlan ip-version ipv4 vlan-tci 34
4680          eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4681  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
4682         mplsoudp_decap / l2_encap / end
4683
4684 Sample L2 decapsulation rule
4685 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4686
4687 L2 decapsulation has default value pre-configured in testpmd
4688 source code, those can be changed by using the following commands
4689
4690 L2 header::
4691
4692  testpmd> set l2_decap
4693  testpmd> flow create 0 egress pattern eth / end actions l2_decap / mplsoudp_encap /
4694         queue index 0 / end
4695
4696 L2 with VXLAN header::
4697
4698  testpmd> set l2_encap-with-vlan
4699  testpmd> flow create 0 egress pattern eth / end actions l2_encap / mplsoudp_encap /
4700          queue index 0 / end
4701
4702 Sample MPLSoGRE encapsulation rule
4703 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4704
4705 MPLSoGRE encapsulation outer layer has default value pre-configured in testpmd
4706 source code, those can be changed by using the following commands
4707
4708 IPv4 MPLSoGRE outer header::
4709
4710  testpmd> set mplsogre_encap ip-version ipv4 label 4
4711         ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
4712         eth-dst 22:22:22:22:22:22
4713  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4714         mplsogre_encap / end
4715
4716 IPv4 MPLSoGRE with VLAN outer header::
4717
4718  testpmd> set mplsogre_encap-with-vlan ip-version ipv4 label 4
4719         ip-src 127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34
4720         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4721  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4722         mplsogre_encap / end
4723
4724 IPv6 MPLSoGRE outer header::
4725
4726  testpmd> set mplsogre_encap ip-version ipv6 mask 4
4727         ip-src ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
4728         eth-dst 22:22:22:22:22:22
4729  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4730         mplsogre_encap / end
4731
4732 IPv6 MPLSoGRE with VLAN outer header::
4733
4734  testpmd> set mplsogre_encap-with-vlan ip-version ipv6 mask 4
4735         ip-src ::1 ip-dst ::2222 vlan-tci 34
4736         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4737  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4738         mplsogre_encap / end
4739
4740 Sample MPLSoGRE decapsulation rule
4741 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4742
4743 MPLSoGRE decapsulation outer layer has default value pre-configured in testpmd
4744 source code, those can be changed by using the following commands
4745
4746 IPv4 MPLSoGRE outer header::
4747
4748  testpmd> set mplsogre_decap ip-version ipv4
4749  testpmd> flow create 0 ingress pattern eth / ipv4 / gre / mpls / end actions
4750         mplsogre_decap / l2_encap / end
4751
4752 IPv4 MPLSoGRE with VLAN outer header::
4753
4754  testpmd> set mplsogre_decap-with-vlan ip-version ipv4
4755  testpmd> flow create 0 ingress pattern eth / vlan / ipv4 / gre / mpls / end
4756         actions mplsogre_decap / l2_encap / end
4757
4758 IPv6 MPLSoGRE outer header::
4759
4760  testpmd> set mplsogre_decap ip-version ipv6
4761  testpmd> flow create 0 ingress pattern eth / ipv6 / gre / mpls / end
4762         actions mplsogre_decap / l2_encap / end
4763
4764 IPv6 MPLSoGRE with VLAN outer header::
4765
4766  testpmd> set mplsogre_decap-with-vlan ip-version ipv6
4767  testpmd> flow create 0 ingress pattern eth / vlan / ipv6 / gre / mpls / end
4768         actions mplsogre_decap / l2_encap / end
4769
4770 Sample MPLSoUDP encapsulation rule
4771 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4772
4773 MPLSoUDP encapsulation outer layer has default value pre-configured in testpmd
4774 source code, those can be changed by using the following commands
4775
4776 IPv4 MPLSoUDP outer header::
4777
4778  testpmd> set mplsoudp_encap ip-version ipv4 label 4 udp-src 5 udp-dst 10
4779         ip-src 127.0.0.1 ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11
4780         eth-dst 22:22:22:22:22:22
4781  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4782         mplsoudp_encap / end
4783
4784 IPv4 MPLSoUDP with VLAN outer header::
4785
4786  testpmd> set mplsoudp_encap-with-vlan ip-version ipv4 label 4 udp-src 5
4787         udp-dst 10 ip-src 127.0.0.1 ip-dst 128.0.0.1 vlan-tci 34
4788         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4789  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4790         mplsoudp_encap / end
4791
4792 IPv6 MPLSoUDP outer header::
4793
4794  testpmd> set mplsoudp_encap ip-version ipv6 mask 4 udp-src 5 udp-dst 10
4795         ip-src ::1 ip-dst ::2222 eth-src 11:11:11:11:11:11
4796         eth-dst 22:22:22:22:22:22
4797  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4798         mplsoudp_encap / end
4799
4800 IPv6 MPLSoUDP with VLAN outer header::
4801
4802  testpmd> set mplsoudp_encap-with-vlan ip-version ipv6 mask 4 udp-src 5
4803         udp-dst 10 ip-src ::1 ip-dst ::2222 vlan-tci 34
4804         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4805  testpmd> flow create 0 egress pattern eth / end actions l2_decap /
4806         mplsoudp_encap / end
4807
4808 Sample MPLSoUDP decapsulation rule
4809 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4810
4811 MPLSoUDP decapsulation outer layer has default value pre-configured in testpmd
4812 source code, those can be changed by using the following commands
4813
4814 IPv4 MPLSoUDP outer header::
4815
4816  testpmd> set mplsoudp_decap ip-version ipv4
4817  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / mpls / end actions
4818         mplsoudp_decap / l2_encap / end
4819
4820 IPv4 MPLSoUDP with VLAN outer header::
4821
4822  testpmd> set mplsoudp_decap-with-vlan ip-version ipv4
4823  testpmd> flow create 0 ingress pattern eth / vlan / ipv4 / udp / mpls / end
4824         actions mplsoudp_decap / l2_encap / end
4825
4826 IPv6 MPLSoUDP outer header::
4827
4828  testpmd> set mplsoudp_decap ip-version ipv6
4829  testpmd> flow create 0 ingress pattern eth / ipv6 / udp / mpls / end
4830         actions mplsoudp_decap / l2_encap / end
4831
4832 IPv6 MPLSoUDP with VLAN outer header::
4833
4834  testpmd> set mplsoudp_decap-with-vlan ip-version ipv6
4835  testpmd> flow create 0 ingress pattern eth / vlan / ipv6 / udp / mpls / end
4836         actions mplsoudp_decap / l2_encap / end
4837
4838 Sample Raw encapsulation rule
4839 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4840
4841 Raw encapsulation configuration can be set by the following commands
4842
4843 Eecapsulating VxLAN::
4844
4845  testpmd> set raw_encap 4 eth src is 10:11:22:33:44:55 / vlan tci is 1
4846         inner_type is 0x0800 / ipv4 / udp dst is 4789 / vxlan vni
4847         is 2 / end_set
4848  testpmd> flow create 0 egress pattern eth / ipv4 / end actions
4849         raw_encap index 4 / end
4850
4851 Sample Raw decapsulation rule
4852 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4853
4854 Raw decapsulation configuration can be set by the following commands
4855
4856 Decapsulating VxLAN::
4857
4858  testpmd> set raw_decap eth / ipv4 / udp / vxlan / end_set
4859  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / vxlan / eth / ipv4 /
4860         end actions raw_decap / queue index 0 / end
4861
4862 Sample ESP rules
4863 ~~~~~~~~~~~~~~~~
4864
4865 ESP rules can be created by the following commands::
4866
4867  testpmd> flow create 0 ingress pattern eth / ipv4 / esp spi is 1 / end actions
4868         queue index 3 / end
4869  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / esp spi is 1 / end
4870         actions queue index 3 / end
4871  testpmd> flow create 0 ingress pattern eth / ipv6 / esp spi is 1 / end actions
4872         queue index 3 / end
4873  testpmd> flow create 0 ingress pattern eth / ipv6 / udp / esp spi is 1 / end
4874         actions queue index 3 / end
4875
4876 Sample AH rules
4877 ~~~~~~~~~~~~~~~~
4878
4879 AH rules can be created by the following commands::
4880
4881  testpmd> flow create 0 ingress pattern eth / ipv4 / ah spi is 1 / end actions
4882         queue index 3 / end
4883  testpmd> flow create 0 ingress pattern eth / ipv4 / udp / ah spi is 1 / end
4884         actions queue index 3 / end
4885  testpmd> flow create 0 ingress pattern eth / ipv6 / ah spi is 1 / end actions
4886         queue index 3 / end
4887  testpmd> flow create 0 ingress pattern eth / ipv6 / udp / ah spi is 1 / end
4888         actions queue index 3 / end
4889
4890 Sample PFCP rules
4891 ~~~~~~~~~~~~~~~~~
4892
4893 PFCP rules can be created by the following commands(s_field need to be 1
4894 if seid is set)::
4895
4896  testpmd> flow create 0 ingress pattern eth / ipv4 / pfcp s_field is 0 / end
4897         actions queue index 3 / end
4898  testpmd> flow create 0 ingress pattern eth / ipv4 / pfcp s_field is 1
4899         seid is 1 / end actions queue index 3 / end
4900  testpmd> flow create 0 ingress pattern eth / ipv6 / pfcp s_field is 0 / end
4901         actions queue index 3 / end
4902  testpmd> flow create 0 ingress pattern eth / ipv6 / pfcp s_field is 1
4903         seid is 1 / end actions queue index 3 / end
4904
4905 Sample Sampling/Mirroring rules
4906 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4907
4908 Sample/Mirroring rules can be set by the following commands
4909
4910 NIC-RX Sampling rule, the matched ingress packets and sent to the queue 1,
4911 and 50% packets are duplicated and marked with 0x1234 and sent to queue 0.
4912
4913 ::
4914
4915  testpmd> set sample_actions 0 mark id  0x1234 / queue index 0 / end
4916  testpmd> flow create 0 ingress group 1 pattern eth / end actions
4917         sample ratio 2 index 0 / queue index 1 / end
4918
4919 Mirroring rule with port representors (with "transfer" attribute), the matched
4920 ingress packets with encapsulation header are sent to port id 0, and also
4921 mirrored the packets and sent to port id 2.
4922
4923 ::
4924
4925  testpmd> set sample_actions 0 port_id id 2 / end
4926  testpmd> flow create 1 ingress transfer pattern eth / end actions
4927         sample ratio 1 index 0  / raw_encap / port_id id 0 / end
4928
4929 Mirroring rule with port representors (with "transfer" attribute), the matched
4930 ingress packets are sent to port id 2, and also mirrored the packets with
4931 encapsulation header and sent to port id 0.
4932
4933 ::
4934
4935  testpmd> set sample_actions 0 raw_encap / port_id id 0 / end
4936  testpmd> flow create 0 ingress transfer pattern eth / end actions
4937         sample ratio 1 index 0  / port_id id 2 / end
4938
4939 Mirroring rule with port representors (with "transfer" attribute), the matched
4940 ingress packets are sent to port id 2, and also mirrored the packets with
4941 VXLAN encapsulation header and sent to port id 0.
4942
4943 ::
4944
4945  testpmd> set vxlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src 127.0.0.1
4946         ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4947  testpmd> set sample_actions 0 vxlan_encap / port_id id 0 / end
4948  testpmd> flow create 0 ingress transfer pattern eth / end actions
4949         sample ratio 1 index 0  / port_id id 2 / end
4950
4951 Mirroring rule with port representors (with "transfer" attribute), the matched
4952 ingress packets are sent to port id 2, and also mirrored the packets with
4953 NVGRE encapsulation header and sent to port id 0.
4954
4955 ::
4956
4957  testpmd> set nvgre ip-version ipv4 tni 4 ip-src 127.0.0.1 ip-dst 128.0.0.1
4958         eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22
4959  testpmd> set sample_actions 0 nvgre_encap / port_id id 0 / end
4960  testpmd> flow create 0 ingress transfer pattern eth / end actions
4961         sample ratio 1 index 0  / port_id id 2 / end
4962
4963 Sample integrity rules
4964 ~~~~~~~~~~~~~~~~~~~~~~
4965
4966 Integrity rules can be created by the following commands:
4967
4968 Integrity rule that forwards valid TCP packets to group 1.
4969 TCP packet integrity is matched with the ``l4_ok`` bit 3.
4970
4971 ::
4972
4973  testpmd> flow create 0 ingress
4974             pattern eth / ipv4 / tcp / integrity value mask 8 value spec 8 / end
4975             actions jump group 1 / end
4976
4977 Integrity rule that forwards invalid packets to application.
4978 General packet integrity is matched with the ``packet_ok`` bit 0.
4979
4980 ::
4981
4982  testpmd> flow create 0 ingress pattern integrity value mask 1 value spec 0 / end actions queue index 0 / end
4983
4984 Sample conntrack rules
4985 ~~~~~~~~~~~~~~~~~~~~~~
4986
4987 Conntrack rules can be set by the following commands
4988
4989 Need to construct the connection context with provided information.
4990 In the first table, create a flow rule by using conntrack action and jump to
4991 the next table. In the next table, create a rule to check the state.
4992
4993 ::
4994
4995  testpmd> set conntrack com peer 1 is_orig 1 enable 1 live 1 sack 1 cack 0
4996         last_dir 0 liberal 0 state 1 max_ack_win 7 r_lim 5 last_win 510
4997         last_seq 2632987379 last_ack 2532480967 last_end 2632987379
4998         last_index 0x8
4999  testpmd> set conntrack orig scale 7 fin 0 acked 1 unack_data 0
5000         sent_end 2632987379 reply_end 2633016339 max_win 28960
5001         max_ack 2632987379
5002  testpmd> set conntrack rply scale 7 fin 0 acked 1 unack_data 0
5003         sent_end 2532480967 reply_end 2532546247 max_win 65280
5004         max_ack 2532480967
5005  testpmd> flow indirect_action 0 create ingress action conntrack / end
5006  testpmd> flow create 0 group 3 ingress pattern eth / ipv4 / tcp / end actions indirect 0 / jump group 5 / end
5007  testpmd> flow create 0 group 5 ingress pattern eth / ipv4 / tcp / conntrack is 1 / end actions queue index 5 / end
5008
5009 Construct the conntrack again with only "is_orig" set to 0 (other fields are
5010 ignored), then use "update" interface to update the direction. Create flow
5011 rules like above for the peer port.
5012
5013 ::
5014
5015  testpmd> flow indirect_action 0 update 0 action conntrack_update dir / end
5016
5017 Sample meter with policy rules
5018 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5019
5020 Meter with policy rules can be created by the following commands:
5021
5022 Need to create policy first and actions are set for green/yellow/red colors.
5023 Create meter with policy id. Create flow with meter id.
5024
5025 Example for policy with meter color action. The purpose is to color the packet
5026 to reflect the meter color result.
5027 The meter policy action list: ``green -> green, yellow -> yellow, red -> red``.
5028
5029 ::
5030
5031    testpmd> add port meter profile srtcm_rfc2697 0 13 21504 2688 0 0
5032    testpmd> add port meter policy 0 1 g_actions color type green / end y_actions color type yellow / end
5033             r_actions color type red / end
5034    testpmd> create port meter 0 1 13 1 yes 0xffff 0 0
5035    testpmd> flow create 0 priority 0 ingress group 1 pattern eth / end actions meter mtr_id 1 / end
5036
5037 BPF Functions
5038 --------------
5039
5040 The following sections show functions to load/unload eBPF based filters.
5041
5042 bpf-load
5043 ~~~~~~~~
5044
5045 Load an eBPF program as a callback for particular RX/TX queue::
5046
5047    testpmd> bpf-load rx|tx (portid) (queueid) (load-flags) (bpf-prog-filename)
5048
5049 The available load-flags are:
5050
5051 * ``J``: use JIT generated native code, otherwise BPF interpreter will be used.
5052
5053 * ``M``: assume input parameter is a pointer to rte_mbuf, otherwise assume it is a pointer to first segment's data.
5054
5055 * ``-``: none.
5056
5057 .. note::
5058
5059    You'll need clang v3.7 or above to build bpf program you'd like to load
5060
5061 For example:
5062
5063 .. code-block:: console
5064
5065    cd examples/bpf
5066    clang -O2 -target bpf -c t1.c
5067
5068 Then to load (and JIT compile) t1.o at RX queue 0, port 1:
5069
5070 .. code-block:: console
5071
5072    testpmd> bpf-load rx 1 0 J ./dpdk.org/examples/bpf/t1.o
5073
5074 To load (not JITed) t1.o at TX queue 0, port 0:
5075
5076 .. code-block:: console
5077
5078    testpmd> bpf-load tx 0 0 - ./dpdk.org/examples/bpf/t1.o
5079
5080 bpf-unload
5081 ~~~~~~~~~~
5082
5083 Unload previously loaded eBPF program for particular RX/TX queue::
5084
5085    testpmd> bpf-unload rx|tx (portid) (queueid)
5086
5087 For example to unload BPF filter from TX queue 0, port 0:
5088
5089 .. code-block:: console
5090
5091    testpmd> bpf-unload tx 0 0