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