app/testpmd: update DDP add command parameters
[dpdk.git] / doc / guides / testpmd_app_ug / testpmd_funcs.rst
1 ..  BSD LICENSE
2     Copyright(c) 2010-2016 Intel Corporation. All rights reserved.
3     All rights reserved.
4
5     Redistribution and use in source and binary forms, with or without
6     modification, are permitted provided that the following conditions
7     are met:
8
9     * Redistributions of source code must retain the above copyright
10     notice, this list of conditions and the following disclaimer.
11     * Redistributions in binary form must reproduce the above copyright
12     notice, this list of conditions and the following disclaimer in
13     the documentation and/or other materials provided with the
14     distribution.
15     * Neither the name of Intel Corporation nor the names of its
16     contributors may be used to endorse or promote products derived
17     from this software without specific prior written permission.
18
19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31 .. _testpmd_runtime:
32
33 Testpmd Runtime Functions
34 =========================
35
36 Where the testpmd application is started in interactive mode, (``-i|--interactive``),
37 it displays a prompt that can be used to start and stop forwarding,
38 configure the application, display statistics (including the extended NIC
39 statistics aka xstats) , set the Flow Director and other tasks::
40
41    testpmd>
42
43 The testpmd prompt has some, limited, readline support.
44 Common bash command-line functions such as ``Ctrl+a`` and ``Ctrl+e`` to go to the start and end of the prompt line are supported
45 as well as access to the command history via the up-arrow.
46
47 There is also support for tab completion.
48 If you type a partial command and hit ``<TAB>`` you get a list of the available completions:
49
50 .. code-block:: console
51
52    testpmd> show port <TAB>
53
54        info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X
55        info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all
56        stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X
57        stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all
58        ...
59
60
61 .. note::
62
63    Some examples in this document are too long to fit on one line are are shown wrapped at `"\\"` for display purposes::
64
65       testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
66                (pause_time) (send_xon) (port_id)
67
68 In the real ``testpmd>`` prompt these commands should be on a single line.
69
70 Help Functions
71 --------------
72
73 The testpmd has on-line help for the functions that are available at runtime.
74 These are divided into sections and can be accessed using help, help section or help all:
75
76 .. code-block:: console
77
78    testpmd> help
79
80        help control    : Start and stop forwarding.
81        help display    : Displaying port, stats and config information.
82        help config     : Configuration information.
83        help ports      : Configuring ports.
84        help registers  : Reading and setting port registers.
85        help filters    : Filters configuration help.
86        help all        : All of the above sections.
87
88
89 Command File Functions
90 ----------------------
91
92 To facilitate loading large number of commands or to avoid cutting and pasting where not
93 practical or possible testpmd supports alternative methods for executing commands.
94
95 * If started with the ``--cmdline-file=FILENAME`` command line argument testpmd
96   will execute all CLI commands contained within the file immediately before
97   starting packet forwarding or entering interactive mode.
98
99 .. code-block:: console
100
101    ./testpmd -n4 -r2 ... -- -i --cmdline-file=/home/ubuntu/flow-create-commands.txt
102    Interactive-mode selected
103    CLI commands to be read from /home/ubuntu/flow-create-commands.txt
104    Configuring Port 0 (socket 0)
105    Port 0: 7C:FE:90:CB:74:CE
106    Configuring Port 1 (socket 0)
107    Port 1: 7C:FE:90:CB:74:CA
108    Checking link statuses...
109    Port 0 Link Up - speed 10000 Mbps - full-duplex
110    Port 1 Link Up - speed 10000 Mbps - full-duplex
111    Done
112    Flow rule #0 created
113    Flow rule #1 created
114    ...
115    ...
116    Flow rule #498 created
117    Flow rule #499 created
118    Read all CLI commands from /home/ubuntu/flow-create-commands.txt
119    testpmd>
120
121
122 * At run-time additional commands can be loaded in bulk by invoking the ``load FILENAME``
123   command.
124
125 .. code-block:: console
126
127    testpmd> load /home/ubuntu/flow-create-commands.txt
128    Flow rule #0 created
129    Flow rule #1 created
130    ...
131    ...
132    Flow rule #498 created
133    Flow rule #499 created
134    Read all CLI commands from /home/ubuntu/flow-create-commands.txt
135    testpmd>
136
137
138 In all cases output from any included command will be displayed as standard output.
139 Execution will continue until the end of the file is reached regardless of
140 whether any errors occur.  The end user must examine the output to determine if
141 any failures occurred.
142
143
144 Control Functions
145 -----------------
146
147 start
148 ~~~~~
149
150 Start packet forwarding with current configuration::
151
152    testpmd> start
153
154 start tx_first
155 ~~~~~~~~~~~~~~
156
157 Start packet forwarding with current configuration after sending specified number of bursts of packets::
158
159    testpmd> start tx_first (""|burst_num)
160
161 The default burst number is 1 when ``burst_num`` not presented.
162
163 stop
164 ~~~~
165
166 Stop packet forwarding, and display accumulated statistics::
167
168    testpmd> stop
169
170 quit
171 ~~~~
172
173 Quit to prompt::
174
175    testpmd> quit
176
177
178 Display Functions
179 -----------------
180
181 The functions in the following sections are used to display information about the
182 testpmd configuration or the NIC status.
183
184 show port
185 ~~~~~~~~~
186
187 Display information for a given port or all ports::
188
189    testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc|cap) (port_id|all)
190
191 The available information categories are:
192
193 * ``info``: General port information such as MAC address.
194
195 * ``stats``: RX/TX statistics.
196
197 * ``xstats``: RX/TX extended NIC statistics.
198
199 * ``fdir``: Flow Director information and statistics.
200
201 * ``stat_qmap``: Queue statistics mapping.
202
203 * ``dcb_tc``: DCB information such as TC mapping.
204
205 * ``cap``: Supported offload capabilities.
206
207 For example:
208
209 .. code-block:: console
210
211    testpmd> show port info 0
212
213    ********************* Infos for port 0 *********************
214
215    MAC address: XX:XX:XX:XX:XX:XX
216    Connect to socket: 0
217    memory allocation on the socket: 0
218    Link status: up
219    Link speed: 40000 Mbps
220    Link duplex: full-duplex
221    Promiscuous mode: enabled
222    Allmulticast mode: disabled
223    Maximum number of MAC addresses: 64
224    Maximum number of MAC addresses of hash filtering: 0
225    VLAN offload:
226        strip on
227        filter on
228        qinq(extend) off
229    Redirection table size: 512
230    Supported flow types:
231      ipv4-frag
232      ipv4-tcp
233      ipv4-udp
234      ipv4-sctp
235      ipv4-other
236      ipv6-frag
237      ipv6-tcp
238      ipv6-udp
239      ipv6-sctp
240      ipv6-other
241      l2_payload
242      port
243      vxlan
244      geneve
245      nvgre
246
247 show port rss reta
248 ~~~~~~~~~~~~~~~~~~
249
250 Display the rss redirection table entry indicated by masks on port X::
251
252    testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
253
254 size is used to indicate the hardware supported reta size
255
256 show port rss-hash
257 ~~~~~~~~~~~~~~~~~~
258
259 Display the RSS hash functions and RSS hash key of a port::
260
261    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]
262
263 clear port
264 ~~~~~~~~~~
265
266 Clear the port statistics for a given port or for all ports::
267
268    testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all)
269
270 For example::
271
272    testpmd> clear port stats all
273
274 show (rxq|txq)
275 ~~~~~~~~~~~~~~
276
277 Display information for a given port's RX/TX queue::
278
279    testpmd> show (rxq|txq) info (port_id) (queue_id)
280
281 show config
282 ~~~~~~~~~~~
283
284 Displays the configuration of the application.
285 The configuration comes from the command-line, the runtime or the application defaults::
286
287    testpmd> show config (rxtx|cores|fwd|txpkts)
288
289 The available information categories are:
290
291 * ``rxtx``: RX/TX configuration items.
292
293 * ``cores``: List of forwarding cores.
294
295 * ``fwd``: Packet forwarding configuration.
296
297 * ``txpkts``: Packets to TX configuration.
298
299 For example:
300
301 .. code-block:: console
302
303    testpmd> show config rxtx
304
305    io packet forwarding - CRC stripping disabled - packets/burst=16
306    nb forwarding cores=2 - nb forwarding ports=1
307    RX queues=1 - RX desc=128 - RX free threshold=0
308    RX threshold registers: pthresh=8 hthresh=8 wthresh=4
309    TX queues=1 - TX desc=512 - TX free threshold=0
310    TX threshold registers: pthresh=36 hthresh=0 wthresh=0
311    TX RS bit threshold=0 - TXQ flags=0x0
312
313 set fwd
314 ~~~~~~~
315
316 Set the packet forwarding mode::
317
318    testpmd> set fwd (io|mac|macswap|flowgen| \
319                      rxonly|txonly|csum|icmpecho) (""|retry)
320
321 ``retry`` can be specified for forwarding engines except ``rx_only``.
322
323 The available information categories are:
324
325 * ``io``: Forwards packets "as-is" in I/O mode.
326   This is the fastest possible forwarding operation as it does not access packets data.
327   This is the default mode.
328
329 * ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
330   Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination
331   address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
332   'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
333
334 * ``macswap``: MAC swap forwarding mode.
335   Swaps the source and the destination Ethernet addresses of packets before forwarding them.
336
337 * ``flowgen``: Multi-flow generation mode.
338   Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
339
340 * ``rxonly``: Receives packets but doesn't transmit them.
341
342 * ``txonly``: Generates and transmits packets without receiving any.
343
344 * ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
345
346 * ``icmpecho``: Receives a burst of packets, lookup for IMCP echo requests and, if any, send back ICMP echo replies.
347
348 * ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=y``.
349
350 Note: TX timestamping is only available in the "Full Featured" TX path. To force ``testpmd`` into this mode set ``--txqflags=0``.
351
352 Example::
353
354    testpmd> set fwd rxonly
355
356    Set rxonly packet forwarding mode
357
358
359 read rxd
360 ~~~~~~~~
361
362 Display an RX descriptor for a port RX queue::
363
364    testpmd> read rxd (port_id) (queue_id) (rxd_id)
365
366 For example::
367
368    testpmd> read rxd 0 0 4
369         0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
370
371 read txd
372 ~~~~~~~~
373
374 Display a TX descriptor for a port TX queue::
375
376    testpmd> read txd (port_id) (queue_id) (txd_id)
377
378 For example::
379
380    testpmd> read txd 0 0 4
381         0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
382
383 ddp get list
384 ~~~~~~~~~~~~
385
386 Get loaded dynamic device personalization (DDP) package info list::
387
388    testpmd> ddp get list (port_id)
389
390 ddp get info
391 ~~~~~~~~~~~~
392
393 Display information about dynamic device personalization (DDP) profile::
394
395    testpmd> ddp get info (profile_patch)
396
397 show vf stats
398 ~~~~~~~~~~~~~
399
400 Display VF statistics::
401
402    testpmd> show vf stats (port_id) (vf_id)
403
404 clear vf stats
405 ~~~~~~~~~~~~~~
406
407 Reset VF statistics::
408
409    testpmd> clear vf stats (port_id) (vf_id)
410
411 Configuration Functions
412 -----------------------
413
414 The testpmd application can be configured from the runtime as well as from the command-line.
415
416 This section details the available configuration functions that are available.
417
418 .. note::
419
420    Configuration changes only become active when forwarding is started/restarted.
421
422 set default
423 ~~~~~~~~~~~
424
425 Reset forwarding to the default configuration::
426
427    testpmd> set default
428
429 set verbose
430 ~~~~~~~~~~~
431
432 Set the debug verbosity level::
433
434    testpmd> set verbose (level)
435
436 Currently the only available levels are 0 (silent except for error) and 1 (fully verbose).
437
438 set nbport
439 ~~~~~~~~~~
440
441 Set the number of ports used by the application:
442
443 set nbport (num)
444
445 This is equivalent to the ``--nb-ports`` command-line option.
446
447 set nbcore
448 ~~~~~~~~~~
449
450 Set the number of cores used by the application::
451
452    testpmd> set nbcore (num)
453
454 This is equivalent to the ``--nb-cores`` command-line option.
455
456 .. note::
457
458    The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
459
460 set coremask
461 ~~~~~~~~~~~~
462
463 Set the forwarding cores hexadecimal mask::
464
465    testpmd> set coremask (mask)
466
467 This is equivalent to the ``--coremask`` command-line option.
468
469 .. note::
470
471    The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
472
473 set portmask
474 ~~~~~~~~~~~~
475
476 Set the forwarding ports hexadecimal mask::
477
478    testpmd> set portmask (mask)
479
480 This is equivalent to the ``--portmask`` command-line option.
481
482 set burst
483 ~~~~~~~~~
484
485 Set number of packets per burst::
486
487    testpmd> set burst (num)
488
489 This is equivalent to the ``--burst command-line`` option.
490
491 When retry is enabled, the transmit delay time and number of retries can also be set::
492
493    testpmd> set burst tx delay (microseconds) retry (num)
494
495 set txpkts
496 ~~~~~~~~~~
497
498 Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
499
500    testpmd> set txpkts (x[,y]*)
501
502 Where x[,y]* represents a CSV list of values, without white space.
503
504 set txsplit
505 ~~~~~~~~~~~
506
507 Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
508
509    testpmd> set txsplit (off|on|rand)
510
511 Where:
512
513 * ``off`` disable packet copy & split for CSUM mode.
514
515 * ``on`` split outgoing packet into multiple segments. Size of each segment
516   and number of segments per packet is determined by ``set txpkts`` command
517   (see above).
518
519 * ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
520
521 set corelist
522 ~~~~~~~~~~~~
523
524 Set the list of forwarding cores::
525
526    testpmd> set corelist (x[,y]*)
527
528 For example, to change the forwarding cores:
529
530 .. code-block:: console
531
532    testpmd> set corelist 3,1
533    testpmd> show config fwd
534
535    io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
536    Logical Core 3 (socket 0) forwards packets on 1 streams:
537    RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
538    Logical Core 1 (socket 0) forwards packets on 1 streams:
539    RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
540
541 .. note::
542
543    The cores are used in the same order as specified on the command line.
544
545 set portlist
546 ~~~~~~~~~~~~
547
548 Set the list of forwarding ports::
549
550    testpmd> set portlist (x[,y]*)
551
552 For example, to change the port forwarding:
553
554 .. code-block:: console
555
556    testpmd> set portlist 0,2,1,3
557    testpmd> show config fwd
558
559    io packet forwarding - ports=4 - cores=1 - streams=4
560    Logical Core 3 (socket 0) forwards packets on 4 streams:
561    RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
562    RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
563    RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
564    RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
565
566 set tx loopback
567 ~~~~~~~~~~~~~~~
568
569 Enable/disable tx loopback::
570
571    testpmd> set tx loopback (port_id) (on|off)
572
573 set drop enable
574 ~~~~~~~~~~~~~~~
575
576 set drop enable bit for all queues::
577
578    testpmd> set all queues drop (port_id) (on|off)
579
580 set split drop enable (for VF)
581 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
582
583 set split drop enable bit for VF from PF::
584
585    testpmd> set vf split drop (port_id) (vf_id) (on|off)
586
587 set mac antispoof (for VF)
588 ~~~~~~~~~~~~~~~~~~~~~~~~~~
589
590 Set mac antispoof for a VF from the PF::
591
592    testpmd> set vf mac antispoof  (port_id) (vf_id) (on|off)
593
594 set macsec offload
595 ~~~~~~~~~~~~~~~~~~
596
597 Enable/disable MACsec offload::
598
599    testpmd> set macsec offload (port_id) on encrypt (on|off) replay-protect (on|off)
600    testpmd> set macsec offload (port_id) off
601
602 set macsec sc
603 ~~~~~~~~~~~~~
604
605 Configure MACsec secure connection (SC)::
606
607    testpmd> set macsec sc (tx|rx) (port_id) (mac) (pi)
608
609 .. note::
610
611    The pi argument is ignored for tx.
612    Check the NIC Datasheet for hardware limits.
613
614 set macsec sa
615 ~~~~~~~~~~~~~
616
617 Configure MACsec secure association (SA)::
618
619    testpmd> set macsec sa (tx|rx) (port_id) (idx) (an) (pn) (key)
620
621 .. note::
622
623    The IDX value must be 0 or 1.
624    Check the NIC Datasheet for hardware limits.
625
626 set broadcast mode (for VF)
627 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
628
629 Set broadcast mode for a VF from the PF::
630
631    testpmd> set vf broadcast (port_id) (vf_id) (on|off)
632
633 vlan set strip
634 ~~~~~~~~~~~~~~
635
636 Set the VLAN strip on a port::
637
638    testpmd> vlan set strip (on|off) (port_id)
639
640 vlan set stripq
641 ~~~~~~~~~~~~~~~
642
643 Set the VLAN strip for a queue on a port::
644
645    testpmd> vlan set stripq (on|off) (port_id,queue_id)
646
647 vlan set stripq (for VF)
648 ~~~~~~~~~~~~~~~~~~~~~~~~
649
650 Set VLAN strip for all queues in a pool for a VF from the PF::
651
652    testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
653
654 vlan set insert (for VF)
655 ~~~~~~~~~~~~~~~~~~~~~~~~
656
657 Set VLAN insert for a VF from the PF::
658
659    testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
660
661 vlan set tag (for VF)
662 ~~~~~~~~~~~~~~~~~~~~~
663
664 Set VLAN tag for a VF from the PF::
665
666    testpmd> set vf vlan tag (port_id) (vf_id) (on|off)
667
668 vlan set antispoof (for VF)
669 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
670
671 Set VLAN antispoof for a VF from the PF::
672
673    testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
674
675 vlan set filter
676 ~~~~~~~~~~~~~~~
677
678 Set the VLAN filter on a port::
679
680    testpmd> vlan set filter (on|off) (port_id)
681
682 vlan set qinq
683 ~~~~~~~~~~~~~
684
685 Set the VLAN QinQ (extended queue in queue) on for a port::
686
687    testpmd> vlan set qinq (on|off) (port_id)
688
689 vlan set tpid
690 ~~~~~~~~~~~~~
691
692 Set the inner or outer VLAN TPID for packet filtering on a port::
693
694    testpmd> vlan set (inner|outer) tpid (value) (port_id)
695
696 .. note::
697
698    TPID value must be a 16-bit number (value <= 65536).
699
700 rx_vlan add
701 ~~~~~~~~~~~
702
703 Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
704
705    testpmd> rx_vlan add (vlan_id|all) (port_id)
706
707 .. note::
708
709    VLAN filter must be set on that port. VLAN ID < 4096.
710    Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
711    in VFTA table. This is important if enabling all vlan_ids.
712
713 rx_vlan rm
714 ~~~~~~~~~~
715
716 Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
717
718    testpmd> rx_vlan rm (vlan_id|all) (port_id)
719
720 rx_vlan add (for VF)
721 ~~~~~~~~~~~~~~~~~~~~
722
723 Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
724
725    testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
726
727 rx_vlan rm (for VF)
728 ~~~~~~~~~~~~~~~~~~~
729
730 Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
731
732    testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
733
734 tunnel_filter add
735 ~~~~~~~~~~~~~~~~~
736
737 Add a tunnel filter on a port::
738
739    testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \
740             (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
741             imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
742
743 The available information categories are:
744
745 * ``vxlan``: Set tunnel type as VXLAN.
746
747 * ``nvgre``: Set tunnel type as NVGRE.
748
749 * ``ipingre``: Set tunnel type as IP-in-GRE.
750
751 * ``imac-ivlan``: Set filter type as Inner MAC and VLAN.
752
753 * ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID.
754
755 * ``imac-tenid``: Set filter type as Inner MAC and tenant ID.
756
757 * ``imac``: Set filter type as Inner MAC.
758
759 * ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID.
760
761 * ``oip``: Set filter type as Outer IP.
762
763 * ``iip``: Set filter type as Inner IP.
764
765 Example::
766
767    testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \
768             192.168.2.2 0 ipingre oip 1 1
769
770    Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP.
771
772 tunnel_filter remove
773 ~~~~~~~~~~~~~~~~~~~~
774
775 Remove a tunnel filter on a port::
776
777    testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \
778             (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
779             imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
780
781 rx_vxlan_port add
782 ~~~~~~~~~~~~~~~~~
783
784 Add an UDP port for VXLAN packet filter on a port::
785
786    testpmd> rx_vxlan_port add (udp_port) (port_id)
787
788 rx_vxlan_port remove
789 ~~~~~~~~~~~~~~~~~~~~
790
791 Remove an UDP port for VXLAN packet filter on a port::
792
793    testpmd> rx_vxlan_port rm (udp_port) (port_id)
794
795 tx_vlan set
796 ~~~~~~~~~~~
797
798 Set hardware insertion of VLAN IDs in packets sent on a port::
799
800    testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
801
802 For example, set a single VLAN ID (5) insertion on port 0::
803
804    tx_vlan set 0 5
805
806 Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
807
808    tx_vlan set 1 2 3
809
810
811 tx_vlan set pvid
812 ~~~~~~~~~~~~~~~~
813
814 Set port based hardware insertion of VLAN ID in packets sent on a port::
815
816    testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
817
818 tx_vlan reset
819 ~~~~~~~~~~~~~
820
821 Disable hardware insertion of a VLAN header in packets sent on a port::
822
823    testpmd> tx_vlan reset (port_id)
824
825 csum set
826 ~~~~~~~~
827
828 Select hardware or software calculation of the checksum when
829 transmitting a packet using the ``csum`` forwarding engine::
830
831    testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)
832
833 Where:
834
835 * ``ip|udp|tcp|sctp`` always relate to  the inner layer.
836
837 * ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
838   as a tunnel packet by the forwarding engine (vxlan, gre and ipip are
839   supported). See also the ``csum parse-tunnel`` command.
840
841 .. note::
842
843    Check the NIC Datasheet for hardware limits.
844
845 csum parse-tunnel
846 ~~~~~~~~~~~~~~~~~
847
848 Define how tunneled packets should be handled by the csum forward
849 engine::
850
851    testpmd> csum parse-tunnel (on|off) (tx_port_id)
852
853 If enabled, the csum forward engine will try to recognize supported
854 tunnel headers (vxlan, gre, ipip).
855
856 If disabled, treat tunnel packets as non-tunneled packets (a inner
857 header is handled as a packet payload).
858
859 .. note::
860
861    The port argument is the TX port like in the ``csum set`` command.
862
863 Example:
864
865 Consider a packet in packet like the following::
866
867    eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
868
869 * If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
870   command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
871   ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``).
872
873 * If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum  set``
874    command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
875
876 csum show
877 ~~~~~~~~~
878
879 Display tx checksum offload configuration::
880
881    testpmd> csum show (port_id)
882
883 tso set
884 ~~~~~~~
885
886 Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
887
888    testpmd> tso set (segsize) (port_id)
889
890 .. note::
891
892    Check the NIC datasheet for hardware limits.
893
894 tso show
895 ~~~~~~~~
896
897 Display the status of TCP Segmentation Offload::
898
899    testpmd> tso show (port_id)
900
901 mac_addr add
902 ~~~~~~~~~~~~
903
904 Add an alternative MAC address to a port::
905
906    testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
907
908 mac_addr remove
909 ~~~~~~~~~~~~~~~
910
911 Remove a MAC address from a port::
912
913    testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
914
915 mac_addr add (for VF)
916 ~~~~~~~~~~~~~~~~~~~~~
917
918 Add an alternative MAC address for a VF to a port::
919
920    testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
921
922 mac_addr set
923 ~~~~~~~~~~~~
924
925 Set the default MAC address for a port::
926
927    testpmd> mac_addr set (port_id) (XX:XX:XX:XX:XX:XX)
928
929 mac_addr set (for VF)
930 ~~~~~~~~~~~~~~~~~~~~~
931
932 Set the MAC address for a VF from the PF::
933
934    testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
935
936 set port-uta
937 ~~~~~~~~~~~~
938
939 Set the unicast hash filter(s) on/off for a port::
940
941    testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
942
943 set promisc
944 ~~~~~~~~~~~
945
946 Set the promiscuous mode on for a port or for all ports.
947 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
948
949    testpmd> set promisc (port_id|all) (on|off)
950
951 set allmulti
952 ~~~~~~~~~~~~
953
954 Set the allmulti mode for a port or for all ports::
955
956    testpmd> set allmulti (port_id|all) (on|off)
957
958 Same as the ifconfig (8) option. Controls how multicast packets are handled.
959
960 set promisc (for VF)
961 ~~~~~~~~~~~~~~~~~~~~
962
963 Set the unicast promiscuous mode for a VF from PF.
964 It's supported by Intel i40e NICs now.
965 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
966
967    testpmd> set vf promisc (port_id) (vf_id) (on|off)
968
969 set allmulticast (for VF)
970 ~~~~~~~~~~~~~~~~~~~~~~~~~
971
972 Set the multicast promiscuous mode for a VF from PF.
973 It's supported by Intel i40e NICs now.
974 In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
975
976    testpmd> set vf allmulti (port_id) (vf_id) (on|off)
977
978 set tx max bandwidth (for VF)
979 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
980
981 Set TX max absolute bandwidth (Mbps) for a VF from PF::
982
983    testpmd> set vf tx max-bandwidth (port_id) (vf_id) (max_bandwidth)
984
985 set tc tx min bandwidth (for VF)
986 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
987
988 Set all TCs' TX min relative bandwidth (%) for a VF from PF::
989
990    testpmd> set vf tc tx min-bandwidth (port_id) (vf_id) (bw1, bw2, ...)
991
992 set tc tx max bandwidth (for VF)
993 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
994
995 Set a TC's TX max absolute bandwidth (Mbps) for a VF from PF::
996
997    testpmd> set vf tc tx max-bandwidth (port_id) (vf_id) (tc_no) (max_bandwidth)
998
999 set tc strict link priority mode
1000 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1001
1002 Set some TCs' strict link priority mode on a physical port::
1003
1004    testpmd> set tx strict-link-priority (port_id) (tc_bitmap)
1005
1006 set tc tx min bandwidth
1007 ~~~~~~~~~~~~~~~~~~~~~~~
1008
1009 Set all TCs' TX min relative bandwidth (%) globally for all PF and VFs::
1010
1011    testpmd> set tc tx min-bandwidth (port_id) (bw1, bw2, ...)
1012
1013 set flow_ctrl rx
1014 ~~~~~~~~~~~~~~~~
1015
1016 Set the link flow control parameter on a port::
1017
1018    testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1019             (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
1020             autoneg (on|off) (port_id)
1021
1022 Where:
1023
1024 * ``high_water`` (integer): High threshold value to trigger XOFF.
1025
1026 * ``low_water`` (integer): Low threshold value to trigger XON.
1027
1028 * ``pause_time`` (integer): Pause quota in the Pause frame.
1029
1030 * ``send_xon`` (0/1): Send XON frame.
1031
1032 * ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
1033
1034 * ``autoneg``: Change the auto-negotiation parameter.
1035
1036 set pfc_ctrl rx
1037 ~~~~~~~~~~~~~~~
1038
1039 Set the priority flow control parameter on a port::
1040
1041    testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
1042             (pause_time) (priority) (port_id)
1043
1044 Where:
1045
1046 * ``high_water`` (integer): High threshold value.
1047
1048 * ``low_water`` (integer): Low threshold value.
1049
1050 * ``pause_time`` (integer): Pause quota in the Pause frame.
1051
1052 * ``priority`` (0-7): VLAN User Priority.
1053
1054 set stat_qmap
1055 ~~~~~~~~~~~~~
1056
1057 Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
1058
1059    testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
1060
1061 For example, to set rx queue 2 on port 0 to mapping 5::
1062
1063    testpmd>set stat_qmap rx 0 2 5
1064
1065 set port - rx/tx (for VF)
1066 ~~~~~~~~~~~~~~~~~~~~~~~~~
1067
1068 Set VF receive/transmit from a port::
1069
1070    testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
1071
1072 set port - mac address filter (for VF)
1073 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1074
1075 Add/Remove unicast or multicast MAC addr filter for a VF::
1076
1077    testpmd> set port (port_id) vf (vf_id) (mac_addr) \
1078             (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off)
1079
1080 set port - rx mode(for VF)
1081 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1082
1083 Set the VF receive mode of a port::
1084
1085    testpmd> set port (port_id) vf (vf_id) \
1086             rxmode (AUPE|ROPE|BAM|MPE) (on|off)
1087
1088 The available receive modes are:
1089
1090 * ``AUPE``: Accepts untagged VLAN.
1091
1092 * ``ROPE``: Accepts unicast hash.
1093
1094 * ``BAM``: Accepts broadcast packets.
1095
1096 * ``MPE``: Accepts all multicast packets.
1097
1098 set port - tx_rate (for Queue)
1099 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1100
1101 Set TX rate limitation for a queue on a port::
1102
1103    testpmd> set port (port_id) queue (queue_id) rate (rate_value)
1104
1105 set port - tx_rate (for VF)
1106 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1107
1108 Set TX rate limitation for queues in VF on a port::
1109
1110    testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
1111
1112 set port - mirror rule
1113 ~~~~~~~~~~~~~~~~~~~~~~
1114
1115 Set pool or vlan type mirror rule for a port::
1116
1117    testpmd> set port (port_id) mirror-rule (rule_id) \
1118             (pool-mirror-up|pool-mirror-down|vlan-mirror) \
1119             (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off)
1120
1121 Set link mirror rule for a port::
1122
1123    testpmd> set port (port_id) mirror-rule (rule_id) \
1124            (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off)
1125
1126 For example to enable mirror traffic with vlan 0,1 to pool 0::
1127
1128    set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on
1129
1130 reset port - mirror rule
1131 ~~~~~~~~~~~~~~~~~~~~~~~~
1132
1133 Reset a mirror rule for a port::
1134
1135    testpmd> reset port (port_id) mirror-rule (rule_id)
1136
1137 set flush_rx
1138 ~~~~~~~~~~~~
1139
1140 Set the flush on RX streams before forwarding.
1141 The default is flush ``on``.
1142 Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
1143
1144    testpmd> set flush_rx off
1145
1146 set bypass mode
1147 ~~~~~~~~~~~~~~~
1148
1149 Set the bypass mode for the lowest port on bypass enabled NIC::
1150
1151    testpmd> set bypass mode (normal|bypass|isolate) (port_id)
1152
1153 set bypass event
1154 ~~~~~~~~~~~~~~~~
1155
1156 Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
1157
1158    testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
1159             mode (normal|bypass|isolate) (port_id)
1160
1161 Where:
1162
1163 * ``timeout``: Enable bypass after watchdog timeout.
1164
1165 * ``os_on``: Enable bypass when OS/board is powered on.
1166
1167 * ``os_off``: Enable bypass when OS/board is powered off.
1168
1169 * ``power_on``: Enable bypass when power supply is turned on.
1170
1171 * ``power_off``: Enable bypass when power supply is turned off.
1172
1173
1174 set bypass timeout
1175 ~~~~~~~~~~~~~~~~~~
1176
1177 Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
1178
1179    testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
1180
1181 show bypass config
1182 ~~~~~~~~~~~~~~~~~~
1183
1184 Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
1185
1186    testpmd> show bypass config (port_id)
1187
1188 set link up
1189 ~~~~~~~~~~~
1190
1191 Set link up for a port::
1192
1193    testpmd> set link-up port (port id)
1194
1195 set link down
1196 ~~~~~~~~~~~~~
1197
1198 Set link down for a port::
1199
1200    testpmd> set link-down port (port id)
1201
1202 E-tag set
1203 ~~~~~~~~~
1204
1205 Enable E-tag insertion for a VF on a port::
1206
1207    testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1208
1209 Disable E-tag insertion for a VF on a port::
1210
1211    testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1212
1213 Enable/disable E-tag stripping on a port::
1214
1215    testpmd> E-tag set stripping (on|off) port (port_id)
1216
1217 Enable/disable E-tag based forwarding on a port::
1218
1219    testpmd> E-tag set forwarding (on|off) port (port_id)
1220
1221 Add an E-tag forwarding filter on a port::
1222
1223    testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id)
1224
1225 Delete an E-tag forwarding filter on a port::
1226    testpmd> E-tag set filter del e-tag-id (value) port (port_id)
1227
1228 ddp add
1229 ~~~~~~~
1230
1231 Load a dynamic device personalization (DDP) package::
1232
1233    testpmd> ddp add (port_id) (package_path[,output_path])
1234
1235 ptype mapping
1236 ~~~~~~~~~~~~~
1237
1238 List all items from the ptype mapping table::
1239
1240    testpmd> ptype mapping get (port_id) (valid_only)
1241
1242 Where:
1243
1244 * ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0).
1245
1246 Replace a specific or a group of software defined ptype with a new one::
1247
1248    testpmd> ptype mapping replace  (port_id) (target) (mask) (pkt_type)
1249
1250 where:
1251
1252 * ``target``: A specific software ptype or a mask to represent a group of software ptypes.
1253
1254 * ``mask``: A flag indicate if "target" is a specific software ptype(=0) or a ptype mask(=1).
1255
1256 * ``pkt_type``: The new software ptype to replace the old ones.
1257
1258 Update hardware defined ptype to software defined packet type mapping table::
1259
1260    testpmd> ptype mapping update (port_id) (hw_ptype) (sw_ptype)
1261
1262 where:
1263
1264 * ``hw_ptype``: hardware ptype as the index of the ptype mapping table.
1265
1266 * ``sw_ptype``: software ptype as the value of the ptype mapping table.
1267
1268 Reset ptype mapping table::
1269
1270    testpmd> ptype mapping reset (port_id)
1271
1272 Port Functions
1273 --------------
1274
1275 The following sections show functions for configuring ports.
1276
1277 .. note::
1278
1279    Port configuration changes only become active when forwarding is started/restarted.
1280
1281 port attach
1282 ~~~~~~~~~~~
1283
1284 Attach a port specified by pci address or virtual device args::
1285
1286    testpmd> port attach (identifier)
1287
1288 To attach a new pci device, the device should be recognized by kernel first.
1289 Then it should be moved under DPDK management.
1290 Finally the port can be attached to testpmd.
1291
1292 For example, to move a pci device using ixgbe under DPDK management:
1293
1294 .. code-block:: console
1295
1296    # Check the status of the available devices.
1297    ./usertools/dpdk-devbind.py --status
1298
1299    Network devices using DPDK-compatible driver
1300    ============================================
1301    <none>
1302
1303    Network devices using kernel driver
1304    ===================================
1305    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
1306
1307
1308    # Bind the device to igb_uio.
1309    sudo ./usertools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
1310
1311
1312    # Recheck the status of the devices.
1313    ./usertools/dpdk-devbind.py --status
1314    Network devices using DPDK-compatible driver
1315    ============================================
1316    0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
1317
1318 To attach a port created by virtual device, above steps are not needed.
1319
1320 For example, to attach a port whose pci address is 0000:0a:00.0.
1321
1322 .. code-block:: console
1323
1324    testpmd> port attach 0000:0a:00.0
1325    Attaching a new port...
1326    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1327    EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
1328    EAL:   PCI memory mapped at 0x7f83bfa00000
1329    EAL:   PCI memory mapped at 0x7f83bfa80000
1330    PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
1331    PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
1332    Port 0 is attached. Now total ports is 1
1333    Done
1334
1335 For example, to attach a port created by pcap PMD.
1336
1337 .. code-block:: console
1338
1339    testpmd> port attach net_pcap0
1340    Attaching a new port...
1341    PMD: Initializing pmd_pcap for net_pcap0
1342    PMD: Creating pcap-backed ethdev on numa socket 0
1343    Port 0 is attached. Now total ports is 1
1344    Done
1345
1346 In this case, identifier is ``net_pcap0``.
1347 This identifier format is the same as ``--vdev`` format of DPDK applications.
1348
1349 For example, to re-attach a bonded port which has been previously detached,
1350 the mode and slave parameters must be given.
1351
1352 .. code-block:: console
1353
1354    testpmd> port attach net_bond_0,mode=0,slave=1
1355    Attaching a new port...
1356    EAL: Initializing pmd_bond for net_bond_0
1357    EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
1358    Port 0 is attached. Now total ports is 1
1359    Done
1360
1361
1362 port detach
1363 ~~~~~~~~~~~
1364
1365 Detach a specific port::
1366
1367    testpmd> port detach (port_id)
1368
1369 Before detaching a port, the port should be stopped and closed.
1370
1371 For example, to detach a pci device port 0.
1372
1373 .. code-block:: console
1374
1375    testpmd> port stop 0
1376    Stopping ports...
1377    Done
1378    testpmd> port close 0
1379    Closing ports...
1380    Done
1381
1382    testpmd> port detach 0
1383    Detaching a port...
1384    EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1385    EAL:   remove driver: 8086:10fb rte_ixgbe_pmd
1386    EAL:   PCI memory unmapped at 0x7f83bfa00000
1387    EAL:   PCI memory unmapped at 0x7f83bfa80000
1388    Done
1389
1390
1391 For example, to detach a virtual device port 0.
1392
1393 .. code-block:: console
1394
1395    testpmd> port stop 0
1396    Stopping ports...
1397    Done
1398    testpmd> port close 0
1399    Closing ports...
1400    Done
1401
1402    testpmd> port detach 0
1403    Detaching a port...
1404    PMD: Closing pcap ethdev on numa socket 0
1405    Port 'net_pcap0' is detached. Now total ports is 0
1406    Done
1407
1408 To remove a pci device completely from the system, first detach the port from testpmd.
1409 Then the device should be moved under kernel management.
1410 Finally the device can be removed using kernel pci hotplug functionality.
1411
1412 For example, to move a pci device under kernel management:
1413
1414 .. code-block:: console
1415
1416    sudo ./usertools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
1417
1418    ./usertools/dpdk-devbind.py --status
1419
1420    Network devices using DPDK-compatible driver
1421    ============================================
1422    <none>
1423
1424    Network devices using kernel driver
1425    ===================================
1426    0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
1427
1428 To remove a port created by a virtual device, above steps are not needed.
1429
1430 port start
1431 ~~~~~~~~~~
1432
1433 Start all ports or a specific port::
1434
1435    testpmd> port start (port_id|all)
1436
1437 port stop
1438 ~~~~~~~~~
1439
1440 Stop all ports or a specific port::
1441
1442    testpmd> port stop (port_id|all)
1443
1444 port close
1445 ~~~~~~~~~~
1446
1447 Close all ports or a specific port::
1448
1449    testpmd> port close (port_id|all)
1450
1451 port start/stop queue
1452 ~~~~~~~~~~~~~~~~~~~~~
1453
1454 Start/stop a rx/tx queue on a specific port::
1455
1456    testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
1457
1458 Only take effect when port is started.
1459
1460 port config - speed
1461 ~~~~~~~~~~~~~~~~~~~
1462
1463 Set the speed and duplex mode for all ports or a specific port::
1464
1465    testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \
1466             duplex (half|full|auto)
1467
1468 port config - queues/descriptors
1469 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1470
1471 Set number of queues/descriptors for rxq, txq, rxd and txd::
1472
1473    testpmd> port config all (rxq|txq|rxd|txd) (value)
1474
1475 This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
1476
1477 port config - max-pkt-len
1478 ~~~~~~~~~~~~~~~~~~~~~~~~~
1479
1480 Set the maximum packet length::
1481
1482    testpmd> port config all max-pkt-len (value)
1483
1484 This is equivalent to the ``--max-pkt-len`` command-line option.
1485
1486 port config - CRC Strip
1487 ~~~~~~~~~~~~~~~~~~~~~~~
1488
1489 Set hardware CRC stripping on or off for all ports::
1490
1491    testpmd> port config all crc-strip (on|off)
1492
1493 CRC stripping is on by default.
1494
1495 The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option.
1496
1497 port config - scatter
1498 ~~~~~~~~~~~~~~~~~~~~~~~
1499
1500 Set RX scatter mode on or off for all ports::
1501
1502    testpmd> port config all scatter (on|off)
1503
1504 RX scatter mode is off by default.
1505
1506 The ``on`` option is equivalent to the ``--enable-scatter`` command-line option.
1507
1508 port config - TX queue flags
1509 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1510
1511 Set a hexadecimal bitmap of TX queue flags for all ports::
1512
1513    testpmd> port config all txqflags value
1514
1515 This command is equivalent to the ``--txqflags`` command-line option.
1516
1517 port config - RX Checksum
1518 ~~~~~~~~~~~~~~~~~~~~~~~~~
1519
1520 Set hardware RX checksum offload to on or off for all ports::
1521
1522    testpmd> port config all rx-cksum (on|off)
1523
1524 Checksum offload is off by default.
1525
1526 The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option.
1527
1528 port config - VLAN
1529 ~~~~~~~~~~~~~~~~~~
1530
1531 Set hardware VLAN on or off for all ports::
1532
1533    testpmd> port config all hw-vlan (on|off)
1534
1535 Hardware VLAN is on by default.
1536
1537 The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option.
1538
1539 port config - VLAN filter
1540 ~~~~~~~~~~~~~~~~~~~~~~~~~
1541
1542 Set hardware VLAN filter on or off for all ports::
1543
1544    testpmd> port config all hw-vlan-filter (on|off)
1545
1546 Hardware VLAN filter is on by default.
1547
1548 The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option.
1549
1550 port config - VLAN strip
1551 ~~~~~~~~~~~~~~~~~~~~~~~~
1552
1553 Set hardware VLAN strip on or off for all ports::
1554
1555    testpmd> port config all hw-vlan-strip (on|off)
1556
1557 Hardware VLAN strip is on by default.
1558
1559 The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option.
1560
1561 port config - VLAN extend
1562 ~~~~~~~~~~~~~~~~~~~~~~~~~
1563
1564 Set hardware VLAN extend on or off for all ports::
1565
1566    testpmd> port config all hw-vlan-extend (on|off)
1567
1568 Hardware VLAN extend is off by default.
1569
1570 The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option.
1571
1572 port config - Drop Packets
1573 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1574
1575 Set packet drop for packets with no descriptors on or off for all ports::
1576
1577    testpmd> port config all drop-en (on|off)
1578
1579 Packet dropping for packets with no descriptors is off by default.
1580
1581 The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
1582
1583 port config - RSS
1584 ~~~~~~~~~~~~~~~~~
1585
1586 Set the RSS (Receive Side Scaling) mode on or off::
1587
1588    testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none)
1589
1590 RSS is on by default.
1591
1592 The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
1593
1594 port config - RSS Reta
1595 ~~~~~~~~~~~~~~~~~~~~~~
1596
1597 Set the RSS (Receive Side Scaling) redirection table::
1598
1599    testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
1600
1601 port config - DCB
1602 ~~~~~~~~~~~~~~~~~
1603
1604 Set the DCB mode for an individual port::
1605
1606    testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
1607
1608 The traffic class should be 4 or 8.
1609
1610 port config - Burst
1611 ~~~~~~~~~~~~~~~~~~~
1612
1613 Set the number of packets per burst::
1614
1615    testpmd> port config all burst (value)
1616
1617 This is equivalent to the ``--burst`` command-line option.
1618
1619 port config - Threshold
1620 ~~~~~~~~~~~~~~~~~~~~~~~
1621
1622 Set thresholds for TX/RX queues::
1623
1624    testpmd> port config all (threshold) (value)
1625
1626 Where the threshold type can be:
1627
1628 * ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
1629
1630 * ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
1631
1632 * ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
1633
1634 * ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
1635
1636 * ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
1637
1638 * ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
1639
1640 * ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
1641
1642 * ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
1643
1644 * ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
1645
1646 These threshold options are also available from the command-line.
1647
1648 port config - E-tag
1649 ~~~~~~~~~~~~~~~~~~~
1650
1651 Set the value of ether-type for E-tag::
1652
1653    testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value)
1654
1655 Enable/disable the E-tag support::
1656
1657    testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable)
1658
1659
1660 Link Bonding Functions
1661 ----------------------
1662
1663 The Link Bonding functions make it possible to dynamically create and
1664 manage link bonding devices from within testpmd interactive prompt.
1665
1666 create bonded device
1667 ~~~~~~~~~~~~~~~~~~~~
1668
1669 Create a new bonding device::
1670
1671    testpmd> create bonded device (mode) (socket)
1672
1673 For example, to create a bonded device in mode 1 on socket 0::
1674
1675    testpmd> create bonded 1 0
1676    created new bonded device (port X)
1677
1678 add bonding slave
1679 ~~~~~~~~~~~~~~~~~
1680
1681 Adds Ethernet device to a Link Bonding device::
1682
1683    testpmd> add bonding slave (slave id) (port id)
1684
1685 For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
1686
1687    testpmd> add bonding slave 6 10
1688
1689
1690 remove bonding slave
1691 ~~~~~~~~~~~~~~~~~~~~
1692
1693 Removes an Ethernet slave device from a Link Bonding device::
1694
1695    testpmd> remove bonding slave (slave id) (port id)
1696
1697 For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
1698
1699    testpmd> remove bonding slave 6 10
1700
1701 set bonding mode
1702 ~~~~~~~~~~~~~~~~
1703
1704 Set the Link Bonding mode of a Link Bonding device::
1705
1706    testpmd> set bonding mode (value) (port id)
1707
1708 For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
1709
1710    testpmd> set bonding mode 3 10
1711
1712 set bonding primary
1713 ~~~~~~~~~~~~~~~~~~~
1714
1715 Set an Ethernet slave device as the primary device on a Link Bonding device::
1716
1717    testpmd> set bonding primary (slave id) (port id)
1718
1719 For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
1720
1721    testpmd> set bonding primary 6 10
1722
1723 set bonding mac
1724 ~~~~~~~~~~~~~~~
1725
1726 Set the MAC address of a Link Bonding device::
1727
1728    testpmd> set bonding mac (port id) (mac)
1729
1730 For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
1731
1732    testpmd> set bonding mac 10 00:00:00:00:00:01
1733
1734 set bonding xmit_balance_policy
1735 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1736
1737 Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
1738
1739    testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34)
1740
1741 For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
1742
1743    testpmd> set bonding xmit_balance_policy 10 l34
1744
1745
1746 set bonding mon_period
1747 ~~~~~~~~~~~~~~~~~~~~~~
1748
1749 Set the link status monitoring polling period in milliseconds for a bonding device.
1750
1751 This adds support for PMD slave devices which do not support link status interrupts.
1752 When the mon_period is set to a value greater than 0 then all PMD's which do not support
1753 link status ISR will be queried every polling interval to check if their link status has changed::
1754
1755    testpmd> set bonding mon_period (port_id) (value)
1756
1757 For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
1758
1759    testpmd> set bonding mon_period 5 150
1760
1761
1762 show bonding config
1763 ~~~~~~~~~~~~~~~~~~~
1764
1765 Show the current configuration of a Link Bonding device::
1766
1767    testpmd> show bonding config (port id)
1768
1769 For example,
1770 to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
1771 in balance mode with a transmission policy of layer 2+3::
1772
1773    testpmd> show bonding config 9
1774         Bonding mode: 2
1775         Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
1776         Slaves (3): [1 3 4]
1777         Active Slaves (3): [1 3 4]
1778         Primary: [3]
1779
1780
1781 Register Functions
1782 ------------------
1783
1784 The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
1785 This is mainly useful for debugging purposes.
1786 Reference should be made to the appropriate datasheet for the network card for details on the register addresses
1787 and fields that can be accessed.
1788
1789 read reg
1790 ~~~~~~~~
1791
1792 Display the value of a port register::
1793
1794    testpmd> read reg (port_id) (address)
1795
1796 For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
1797
1798    testpmd> read reg 0 0xEE00
1799    port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
1800
1801 read regfield
1802 ~~~~~~~~~~~~~
1803
1804 Display a port register bit field::
1805
1806    testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
1807
1808 For example, reading the lowest two bits from the register in the example above::
1809
1810    testpmd> read regfield 0 0xEE00 0 1
1811    port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
1812
1813 read regbit
1814 ~~~~~~~~~~~
1815
1816 Display a single port register bit::
1817
1818    testpmd> read regbit (port_id) (address) (bit_x)
1819
1820 For example, reading the lowest bit from the register in the example above::
1821
1822    testpmd> read regbit 0 0xEE00 0
1823    port 0 PCI register at offset 0xEE00: bit 0=1
1824
1825 write reg
1826 ~~~~~~~~~
1827
1828 Set the value of a port register::
1829
1830    testpmd> write reg (port_id) (address) (value)
1831
1832 For example, to clear a register::
1833
1834    testpmd> write reg 0 0xEE00 0x0
1835    port 0 PCI register at offset 0xEE00: 0x00000000 (0)
1836
1837 write regfield
1838 ~~~~~~~~~~~~~~
1839
1840 Set bit field of a port register::
1841
1842    testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
1843
1844 For example, writing to the register cleared in the example above::
1845
1846    testpmd> write regfield 0 0xEE00 0 1 2
1847    port 0 PCI register at offset 0xEE00: 0x00000002 (2)
1848
1849 write regbit
1850 ~~~~~~~~~~~~
1851
1852 Set single bit value of a port register::
1853
1854    testpmd> write regbit (port_id) (address) (bit_x) (value)
1855
1856 For example, to set the high bit in the register from the example above::
1857
1858    testpmd> write regbit 0 0xEE00 31 1
1859    port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
1860
1861
1862 Filter Functions
1863 ----------------
1864
1865 This section details the available filter functions that are available.
1866
1867 Note these functions interface the deprecated legacy filtering framework,
1868 superseded by *rte_flow*. See `Flow rules management`_.
1869
1870 ethertype_filter
1871 ~~~~~~~~~~~~~~~~~~~~
1872
1873 Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue::
1874
1875    ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \
1876                     ethertype (ether_type) (drop|fwd) queue (queue_id)
1877
1878 The available information parameters are:
1879
1880 * ``port_id``: The port which the Ethertype filter assigned on.
1881
1882 * ``mac_addr``: Compare destination mac address.
1883
1884 * ``mac_ignr``: Ignore destination mac address match.
1885
1886 * ``mac_address``: Destination mac address to match.
1887
1888 * ``ether_type``: The EtherType value want to match,
1889   for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid.
1890
1891 * ``queue_id``: The receive queue associated with this EtherType filter.
1892   It is meaningless when deleting or dropping.
1893
1894 Example, to add/remove an ethertype filter rule::
1895
1896    testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \
1897                              ethertype 0x0806 fwd queue 3
1898
1899    testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \
1900                              ethertype 0x0806 fwd queue 3
1901
1902 2tuple_filter
1903 ~~~~~~~~~~~~~~~~~
1904
1905 Add or delete a 2-tuple filter,
1906 which identifies packets by specific protocol and destination TCP/UDP port
1907 and forwards packets into one of the receive queues::
1908
1909    2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \
1910                  protocol (protocol_value) mask (mask_value) \
1911                  tcp_flags (tcp_flags_value) priority (prio_value) \
1912                  queue (queue_id)
1913
1914 The available information parameters are:
1915
1916 * ``port_id``: The port which the 2-tuple filter assigned on.
1917
1918 * ``dst_port_value``: Destination port in L4.
1919
1920 * ``protocol_value``: IP L4 protocol.
1921
1922 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate.
1923
1924 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP).
1925
1926 * ``prio_value``: Priority of this filter.
1927
1928 * ``queue_id``: The receive queue associated with this 2-tuple filter.
1929
1930 Example, to add/remove an 2tuple filter rule::
1931
1932    testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \
1933                           tcp_flags 0x02 priority 3 queue 3
1934
1935    testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \
1936                           tcp_flags 0x02 priority 3 queue 3
1937
1938 5tuple_filter
1939 ~~~~~~~~~~~~~~~~~
1940
1941 Add or delete a 5-tuple filter,
1942 which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port)
1943 and routes packets into one of the receive queues::
1944
1945    5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \
1946                  (src_address) dst_port (dst_port_value) \
1947                  src_port (src_port_value) protocol (protocol_value) \
1948                  mask (mask_value) tcp_flags (tcp_flags_value) \
1949                  priority (prio_value) queue (queue_id)
1950
1951 The available information parameters are:
1952
1953 * ``port_id``: The port which the 5-tuple filter assigned on.
1954
1955 * ``dst_address``: Destination IP address.
1956
1957 * ``src_address``: Source IP address.
1958
1959 * ``dst_port_value``: TCP/UDP destination port.
1960
1961 * ``src_port_value``: TCP/UDP source port.
1962
1963 * ``protocol_value``: L4 protocol.
1964
1965 * ``mask_value``: Participates in the match or not by bit for field above, 1b means participate
1966
1967 * ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP).
1968
1969 * ``prio_value``: The priority of this filter.
1970
1971 * ``queue_id``: The receive queue associated with this 5-tuple filter.
1972
1973 Example, to add/remove an 5tuple filter rule::
1974
1975    testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1976             dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1977             flags 0x0 priority 3 queue 3
1978
1979    testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1980             dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1981             flags 0x0 priority 3 queue 3
1982
1983 syn_filter
1984 ~~~~~~~~~~
1985
1986 Using the  SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue::
1987
1988    syn_filter (port_id) (add|del) priority (high|low) queue (queue_id)
1989
1990 The available information parameters are:
1991
1992 * ``port_id``: The port which the SYN filter assigned on.
1993
1994 * ``high``: This SYN filter has higher priority than other filters.
1995
1996 * ``low``: This SYN filter has lower priority than other filters.
1997
1998 * ``queue_id``: The receive queue associated with this SYN filter
1999
2000 Example::
2001
2002    testpmd> syn_filter 0 add priority high queue 3
2003
2004 flex_filter
2005 ~~~~~~~~~~~
2006
2007 With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet
2008 and routed into one of the receive queues::
2009
2010    flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \
2011                mask (mask_value) priority (prio_value) queue (queue_id)
2012
2013 The available information parameters are:
2014
2015 * ``port_id``: The port which the Flex filter is assigned on.
2016
2017 * ``len_value``: Filter length in bytes, no greater than 128.
2018
2019 * ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match.
2020
2021 * ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match.
2022
2023 * ``prio_value``: The priority of this filter.
2024
2025 * ``queue_id``: The receive queue associated with this Flex filter.
2026
2027 Example::
2028
2029    testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \
2030                           mask 000C priority 3 queue 3
2031
2032    testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \
2033                           mask 000C priority 3 queue 3
2034
2035
2036 .. _testpmd_flow_director:
2037
2038 flow_director_filter
2039 ~~~~~~~~~~~~~~~~~~~~
2040
2041 The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues.
2042
2043 Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and
2044 Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter:
2045
2046 * Perfect match filters.
2047   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2048   The masked fields are for IP flow.
2049
2050 * Signature filters.
2051   The hardware checks a match between a hash-based signature of the masked fields of the received packet.
2052
2053 * Perfect-mac-vlan match filters.
2054   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2055   The masked fields are for MAC VLAN flow.
2056
2057 * Perfect-tunnel match filters.
2058   The hardware checks a match between the masked fields of the received packets and the programmed filters.
2059   The masked fields are for tunnel flow.
2060
2061 The Flow Director filters can match the different fields for different type of packet: flow type, specific input set
2062 per flow type and the flexible payload.
2063
2064 The Flow Director can also mask out parts of all of these fields so that filters
2065 are only applied to certain fields or parts of the fields.
2066
2067 Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information.
2068
2069 # Commands to add flow director filters of different flow types::
2070
2071    flow_director_filter (port_id) mode IP (add|del|update) \
2072                         flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \
2073                         src (src_ip_address) dst (dst_ip_address) \
2074                         tos (tos_value) proto (proto_value) ttl (ttl_value) \
2075                         vlan (vlan_value) flexbytes (flexbytes_value) \
2076                         (drop|fwd) pf|vf(vf_id) queue (queue_id) \
2077                         fd_id (fd_id_value)
2078
2079    flow_director_filter (port_id) mode IP (add|del|update) \
2080                         flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \
2081                         src (src_ip_address) (src_port) \
2082                         dst (dst_ip_address) (dst_port) \
2083                         tos (tos_value) ttl (ttl_value) \
2084                         vlan (vlan_value) flexbytes (flexbytes_value) \
2085                         (drop|fwd) queue pf|vf(vf_id) (queue_id) \
2086                         fd_id (fd_id_value)
2087
2088    flow_director_filter (port_id) mode IP (add|del|update) \
2089                         flow (ipv4-sctp|ipv6-sctp) \
2090                         src (src_ip_address) (src_port) \
2091                         dst (dst_ip_address) (dst_port) \
2092                         tos (tos_value) ttl (ttl_value) \
2093                         tag (verification_tag) vlan (vlan_value) \
2094                         flexbytes (flexbytes_value) (drop|fwd) \
2095                         pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value)
2096
2097    flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \
2098                         ether (ethertype) flexbytes (flexbytes_value) \
2099                         (drop|fwd) pf|vf(vf_id) queue (queue_id)
2100                         fd_id (fd_id_value)
2101
2102    flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \
2103                         mac (mac_address) vlan (vlan_value) \
2104                         flexbytes (flexbytes_value) (drop|fwd) \
2105                         queue (queue_id) fd_id (fd_id_value)
2106
2107    flow_director_filter (port_id) mode Tunnel (add|del|update) \
2108                         mac (mac_address) vlan (vlan_value) \
2109                         tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \
2110                         flexbytes (flexbytes_value) (drop|fwd) \
2111                         queue (queue_id) fd_id (fd_id_value)
2112
2113 For example, to add an ipv4-udp flow type filter::
2114
2115    testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \
2116             dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \
2117             fwd pf queue 1 fd_id 1
2118
2119 For example, add an ipv4-other flow type filter::
2120
2121    testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \
2122              dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \
2123              flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1
2124
2125 flush_flow_director
2126 ~~~~~~~~~~~~~~~~~~~
2127
2128 Flush all flow director filters on a device::
2129
2130    testpmd> flush_flow_director (port_id)
2131
2132 Example, to flush all flow director filter on port 0::
2133
2134    testpmd> flush_flow_director 0
2135
2136 flow_director_mask
2137 ~~~~~~~~~~~~~~~~~~
2138
2139 Set flow director's input masks::
2140
2141    flow_director_mask (port_id) mode IP vlan (vlan_value) \
2142                       src_mask (ipv4_src) (ipv6_src) (src_port) \
2143                       dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
2144
2145    flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
2146
2147    flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
2148                       mac (mac_value) tunnel-type (tunnel_type_value) \
2149                       tunnel-id (tunnel_id_value)
2150
2151 Example, to set flow director mask on port 0::
2152
2153    testpmd> flow_director_mask 0 mode IP vlan 0xefff \
2154             src_mask 255.255.255.255 \
2155                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
2156             dst_mask 255.255.255.255 \
2157                 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
2158
2159 flow_director_flex_mask
2160 ~~~~~~~~~~~~~~~~~~~~~~~
2161
2162 set masks of flow director's flexible payload based on certain flow type::
2163
2164    testpmd> flow_director_flex_mask (port_id) \
2165             flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2166                   ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \
2167                   l2_payload|all) (mask)
2168
2169 Example, to set flow director's flex mask for all flow type on port 0::
2170
2171    testpmd> flow_director_flex_mask 0 flow all \
2172             (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0)
2173
2174
2175 flow_director_flex_payload
2176 ~~~~~~~~~~~~~~~~~~~~~~~~~~
2177
2178 Configure flexible payload selection::
2179
2180    flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
2181
2182 For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
2183
2184    testpmd> flow_director_flex_payload 0 l4 \
2185             (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
2186
2187 get_sym_hash_ena_per_port
2188 ~~~~~~~~~~~~~~~~~~~~~~~~~
2189
2190 Get symmetric hash enable configuration per port::
2191
2192    get_sym_hash_ena_per_port (port_id)
2193
2194 For example, to get symmetric hash enable configuration of port 1::
2195
2196    testpmd> get_sym_hash_ena_per_port 1
2197
2198 set_sym_hash_ena_per_port
2199 ~~~~~~~~~~~~~~~~~~~~~~~~~
2200
2201 Set symmetric hash enable configuration per port to enable or disable::
2202
2203    set_sym_hash_ena_per_port (port_id) (enable|disable)
2204
2205 For example, to set symmetric hash enable configuration of port 1 to enable::
2206
2207    testpmd> set_sym_hash_ena_per_port 1 enable
2208
2209 get_hash_global_config
2210 ~~~~~~~~~~~~~~~~~~~~~~
2211
2212 Get the global configurations of hash filters::
2213
2214    get_hash_global_config (port_id)
2215
2216 For example, to get the global configurations of hash filters of port 1::
2217
2218    testpmd> get_hash_global_config 1
2219
2220 set_hash_global_config
2221 ~~~~~~~~~~~~~~~~~~~~~~
2222
2223 Set the global configurations of hash filters::
2224
2225    set_hash_global_config (port_id) (toeplitz|simple_xor|default) \
2226    (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \
2227    ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \
2228    (enable|disable)
2229
2230 For example, to enable simple_xor for flow type of ipv6 on port 2::
2231
2232    testpmd> set_hash_global_config 2 simple_xor ipv6 enable
2233
2234 set_hash_input_set
2235 ~~~~~~~~~~~~~~~~~~
2236
2237 Set the input set for hash::
2238
2239    set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2240    ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2241    l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2242    ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \
2243    tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \
2244    udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \
2245    fld-8th|none) (select|add)
2246
2247 For example, to add source IP to hash input set for flow type of ipv4-udp on port 0::
2248
2249    testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add
2250
2251 set_fdir_input_set
2252 ~~~~~~~~~~~~~~~~~~
2253
2254 The Flow Director filters can match the different fields for different type of packet, i.e. specific input set
2255 on per flow type and the flexible payload. This command can be used to change input set for each flow type.
2256
2257 Set the input set for flow director::
2258
2259    set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2260    ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2261    l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2262    ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \
2263    tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \
2264    sctp-dst-port|sctp-veri-tag|none) (select|add)
2265
2266 For example to add source IP to FD input set for flow type of ipv4-udp on port 0::
2267
2268    testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add
2269
2270 global_config
2271 ~~~~~~~~~~~~~
2272
2273 Set different GRE key length for input set::
2274
2275    global_config (port_id) gre-key-len (number in bytes)
2276
2277 For example to set GRE key length for input set to 4 bytes on port 0::
2278
2279    testpmd> global_config 0 gre-key-len 4
2280
2281
2282 .. _testpmd_rte_flow:
2283
2284 Flow rules management
2285 ---------------------
2286
2287 Control of the generic flow API (*rte_flow*) is fully exposed through the
2288 ``flow`` command (validation, creation, destruction, queries and operation
2289 modes).
2290
2291 Considering *rte_flow* overlaps with all `Filter Functions`_, using both
2292 features simultaneously may cause undefined side-effects and is therefore
2293 not recommended.
2294
2295 ``flow`` syntax
2296 ~~~~~~~~~~~~~~~
2297
2298 Because the ``flow`` command uses dynamic tokens to handle the large number
2299 of possible flow rules combinations, its behavior differs slightly from
2300 other commands, in particular:
2301
2302 - Pressing *?* or the *<tab>* key displays contextual help for the current
2303   token, not that of the entire command.
2304
2305 - Optional and repeated parameters are supported (provided they are listed
2306   in the contextual help).
2307
2308 The first parameter stands for the operation mode. Possible operations and
2309 their general syntax are described below. They are covered in detail in the
2310 following sections.
2311
2312 - Check whether a flow rule can be created::
2313
2314    flow validate {port_id}
2315        [group {group_id}] [priority {level}] [ingress] [egress]
2316        pattern {item} [/ {item} [...]] / end
2317        actions {action} [/ {action} [...]] / end
2318
2319 - Create a flow rule::
2320
2321    flow create {port_id}
2322        [group {group_id}] [priority {level}] [ingress] [egress]
2323        pattern {item} [/ {item} [...]] / end
2324        actions {action} [/ {action} [...]] / end
2325
2326 - Destroy specific flow rules::
2327
2328    flow destroy {port_id} rule {rule_id} [...]
2329
2330 - Destroy all flow rules::
2331
2332    flow flush {port_id}
2333
2334 - Query an existing flow rule::
2335
2336    flow query {port_id} {rule_id} {action}
2337
2338 - List existing flow rules sorted by priority, filtered by group
2339   identifiers::
2340
2341    flow list {port_id} [group {group_id}] [...]
2342
2343 - Restrict ingress traffic to the defined flow rules::
2344
2345    flow isolate {port_id} {boolean}
2346
2347 Validating flow rules
2348 ~~~~~~~~~~~~~~~~~~~~~
2349
2350 ``flow validate`` reports whether a flow rule would be accepted by the
2351 underlying device in its current state but stops short of creating it. It is
2352 bound to ``rte_flow_validate()``::
2353
2354    flow validate {port_id}
2355       [group {group_id}] [priority {level}] [ingress] [egress]
2356       pattern {item} [/ {item} [...]] / end
2357       actions {action} [/ {action} [...]] / end
2358
2359 If successful, it will show::
2360
2361    Flow rule validated
2362
2363 Otherwise it will show an error message of the form::
2364
2365    Caught error type [...] ([...]): [...]
2366
2367 This command uses the same parameters as ``flow create``, their format is
2368 described in `Creating flow rules`_.
2369
2370 Check whether redirecting any Ethernet packet received on port 0 to RX queue
2371 index 6 is supported::
2372
2373    testpmd> flow validate 0 ingress pattern eth / end
2374       actions queue index 6 / end
2375    Flow rule validated
2376    testpmd>
2377
2378 Port 0 does not support TCPv6 rules::
2379
2380    testpmd> flow validate 0 ingress pattern eth / ipv6 / tcp / end
2381       actions drop / end
2382    Caught error type 9 (specific pattern item): Invalid argument
2383    testpmd>
2384
2385 Creating flow rules
2386 ~~~~~~~~~~~~~~~~~~~
2387
2388 ``flow create`` validates and creates the specified flow rule. It is bound
2389 to ``rte_flow_create()``::
2390
2391    flow create {port_id}
2392       [group {group_id}] [priority {level}] [ingress] [egress]
2393       pattern {item} [/ {item} [...]] / end
2394       actions {action} [/ {action} [...]] / end
2395
2396 If successful, it will return a flow rule ID usable with other commands::
2397
2398    Flow rule #[...] created
2399
2400 Otherwise it will show an error message of the form::
2401
2402    Caught error type [...] ([...]): [...]
2403
2404 Parameters describe in the following order:
2405
2406 - Attributes (*group*, *priority*, *ingress*, *egress* tokens).
2407 - A matching pattern, starting with the *pattern* token and terminated by an
2408   *end* pattern item.
2409 - Actions, starting with the *actions* token and terminated by an *end*
2410   action.
2411
2412 These translate directly to *rte_flow* objects provided as-is to the
2413 underlying functions.
2414
2415 The shortest valid definition only comprises mandatory tokens::
2416
2417    testpmd> flow create 0 pattern end actions end
2418
2419 Note that PMDs may refuse rules that essentially do nothing such as this
2420 one.
2421
2422 **All unspecified object values are automatically initialized to 0.**
2423
2424 Attributes
2425 ^^^^^^^^^^
2426
2427 These tokens affect flow rule attributes (``struct rte_flow_attr``) and are
2428 specified before the ``pattern`` token.
2429
2430 - ``group {group id}``: priority group.
2431 - ``priority {level}``: priority level within group.
2432 - ``ingress``: rule applies to ingress traffic.
2433 - ``egress``: rule applies to egress traffic.
2434
2435 Each instance of an attribute specified several times overrides the previous
2436 value as shown below (group 4 is used)::
2437
2438    testpmd> flow create 0 group 42 group 24 group 4 [...]
2439
2440 Note that once enabled, ``ingress`` and ``egress`` cannot be disabled.
2441
2442 While not specifying a direction is an error, some rules may allow both
2443 simultaneously.
2444
2445 Most rules affect RX therefore contain the ``ingress`` token::
2446
2447    testpmd> flow create 0 ingress pattern [...]
2448
2449 Matching pattern
2450 ^^^^^^^^^^^^^^^^
2451
2452 A matching pattern starts after the ``pattern`` token. It is made of pattern
2453 items and is terminated by a mandatory ``end`` item.
2454
2455 Items are named after their type (*RTE_FLOW_ITEM_TYPE_* from ``enum
2456 rte_flow_item_type``).
2457
2458 The ``/`` token is used as a separator between pattern items as shown
2459 below::
2460
2461    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end [...]
2462
2463 Note that protocol items like these must be stacked from lowest to highest
2464 layer to make sense. For instance, the following rule is either invalid or
2465 unlikely to match any packet::
2466
2467    testpmd> flow create 0 ingress pattern eth / udp / ipv4 / end [...]
2468
2469 More information on these restrictions can be found in the *rte_flow*
2470 documentation.
2471
2472 Several items support additional specification structures, for example
2473 ``ipv4`` allows specifying source and destination addresses as follows::
2474
2475    testpmd> flow create 0 ingress pattern eth / ipv4 src is 10.1.1.1
2476       dst is 10.2.0.0 / end [...]
2477
2478 This rule matches all IPv4 traffic with the specified properties.
2479
2480 In this example, ``src`` and ``dst`` are field names of the underlying
2481 ``struct rte_flow_item_ipv4`` object. All item properties can be specified
2482 in a similar fashion.
2483
2484 The ``is`` token means that the subsequent value must be matched exactly,
2485 and assigns ``spec`` and ``mask`` fields in ``struct rte_flow_item``
2486 accordingly. Possible assignment tokens are:
2487
2488 - ``is``: match value perfectly (with full bit-mask).
2489 - ``spec``: match value according to configured bit-mask.
2490 - ``last``: specify upper bound to establish a range.
2491 - ``mask``: specify bit-mask with relevant bits set to one.
2492 - ``prefix``: generate bit-mask from a prefix length.
2493
2494 These yield identical results::
2495
2496    ipv4 src is 10.1.1.1
2497
2498 ::
2499
2500    ipv4 src spec 10.1.1.1 src mask 255.255.255.255
2501
2502 ::
2503
2504    ipv4 src spec 10.1.1.1 src prefix 32
2505
2506 ::
2507
2508    ipv4 src is 10.1.1.1 src last 10.1.1.1 # range with a single value
2509
2510 ::
2511
2512    ipv4 src is 10.1.1.1 src last 0 # 0 disables range
2513
2514 Inclusive ranges can be defined with ``last``::
2515
2516    ipv4 src is 10.1.1.1 src last 10.2.3.4 # 10.1.1.1 to 10.2.3.4
2517
2518 Note that ``mask`` affects both ``spec`` and ``last``::
2519
2520    ipv4 src is 10.1.1.1 src last 10.2.3.4 src mask 255.255.0.0
2521       # matches 10.1.0.0 to 10.2.255.255
2522
2523 Properties can be modified multiple times::
2524
2525    ipv4 src is 10.1.1.1 src is 10.1.2.3 src is 10.2.3.4 # matches 10.2.3.4
2526
2527 ::
2528
2529    ipv4 src is 10.1.1.1 src prefix 24 src prefix 16 # matches 10.1.0.0/16
2530
2531 Pattern items
2532 ^^^^^^^^^^^^^
2533
2534 This section lists supported pattern items and their attributes, if any.
2535
2536 - ``end``: end list of pattern items.
2537
2538 - ``void``: no-op pattern item.
2539
2540 - ``invert``: perform actions when pattern does not match.
2541
2542 - ``any``: match any protocol for the current layer.
2543
2544   - ``num {unsigned}``: number of layers covered.
2545
2546 - ``pf``: match packets addressed to the physical function.
2547
2548 - ``vf``: match packets addressed to a virtual function ID.
2549
2550   - ``id {unsigned}``: destination VF ID.
2551
2552 - ``port``: device-specific physical port index to use.
2553
2554   - ``index {unsigned}``: physical port index.
2555
2556 - ``raw``: match an arbitrary byte string.
2557
2558   - ``relative {boolean}``: look for pattern after the previous item.
2559   - ``search {boolean}``: search pattern from offset (see also limit).
2560   - ``offset {integer}``: absolute or relative offset for pattern.
2561   - ``limit {unsigned}``: search area limit for start of pattern.
2562   - ``pattern {string}``: byte string to look for.
2563
2564 - ``eth``: match Ethernet header.
2565
2566   - ``dst {MAC-48}``: destination MAC.
2567   - ``src {MAC-48}``: source MAC.
2568   - ``type {unsigned}``: EtherType.
2569
2570 - ``vlan``: match 802.1Q/ad VLAN tag.
2571
2572   - ``tpid {unsigned}``: tag protocol identifier.
2573   - ``tci {unsigned}``: tag control information.
2574   - ``pcp {unsigned}``: priority code point.
2575   - ``dei {unsigned}``: drop eligible indicator.
2576   - ``vid {unsigned}``: VLAN identifier.
2577
2578 - ``ipv4``: match IPv4 header.
2579
2580   - ``tos {unsigned}``: type of service.
2581   - ``ttl {unsigned}``: time to live.
2582   - ``proto {unsigned}``: next protocol ID.
2583   - ``src {ipv4 address}``: source address.
2584   - ``dst {ipv4 address}``: destination address.
2585
2586 - ``ipv6``: match IPv6 header.
2587
2588   - ``tc {unsigned}``: traffic class.
2589   - ``flow {unsigned}``: flow label.
2590   - ``proto {unsigned}``: protocol (next header).
2591   - ``hop {unsigned}``: hop limit.
2592   - ``src {ipv6 address}``: source address.
2593   - ``dst {ipv6 address}``: destination address.
2594
2595 - ``icmp``: match ICMP header.
2596
2597   - ``type {unsigned}``: ICMP packet type.
2598   - ``code {unsigned}``: ICMP packet code.
2599
2600 - ``udp``: match UDP header.
2601
2602   - ``src {unsigned}``: UDP source port.
2603   - ``dst {unsigned}``: UDP destination port.
2604
2605 - ``tcp``: match TCP header.
2606
2607   - ``src {unsigned}``: TCP source port.
2608   - ``dst {unsigned}``: TCP destination port.
2609
2610 - ``sctp``: match SCTP header.
2611
2612   - ``src {unsigned}``: SCTP source port.
2613   - ``dst {unsigned}``: SCTP destination port.
2614   - ``tag {unsigned}``: validation tag.
2615   - ``cksum {unsigned}``: checksum.
2616
2617 - ``vxlan``: match VXLAN header.
2618
2619   - ``vni {unsigned}``: VXLAN identifier.
2620
2621 - ``e_tag``: match IEEE 802.1BR E-Tag header.
2622
2623   - ``grp_ecid_b {unsigned}``: GRP and E-CID base.
2624
2625 - ``nvgre``: match NVGRE header.
2626
2627   - ``tni {unsigned}``: virtual subnet ID.
2628
2629 - ``mpls``: match MPLS header.
2630
2631   - ``label {unsigned}``: MPLS label.
2632
2633 - ``gre``: match GRE header.
2634
2635   - ``protocol {unsigned}``: protocol type.
2636
2637 - ``fuzzy``: fuzzy pattern match, expect faster than default.
2638
2639   - ``thresh {unsigned}``: accuracy threshold.
2640
2641 Actions list
2642 ^^^^^^^^^^^^
2643
2644 A list of actions starts after the ``actions`` token in the same fashion as
2645 `Matching pattern`_; actions are separated by ``/`` tokens and the list is
2646 terminated by a mandatory ``end`` action.
2647
2648 Actions are named after their type (*RTE_FLOW_ACTION_TYPE_* from ``enum
2649 rte_flow_action_type``).
2650
2651 Dropping all incoming UDPv4 packets can be expressed as follows::
2652
2653    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2654       actions drop / end
2655
2656 Several actions have configurable properties which must be specified when
2657 there is no valid default value. For example, ``queue`` requires a target
2658 queue index.
2659
2660 This rule redirects incoming UDPv4 traffic to queue index 6::
2661
2662    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2663       actions queue index 6 / end
2664
2665 While this one could be rejected by PMDs (unspecified queue index)::
2666
2667    testpmd> flow create 0 ingress pattern eth / ipv4 / udp / end
2668       actions queue / end
2669
2670 As defined by *rte_flow*, the list is not ordered, all actions of a given
2671 rule are performed simultaneously. These are equivalent::
2672
2673    queue index 6 / void / mark id 42 / end
2674
2675 ::
2676
2677    void / mark id 42 / queue index 6 / end
2678
2679 All actions in a list should have different types, otherwise only the last
2680 action of a given type is taken into account::
2681
2682    queue index 4 / queue index 5 / queue index 6 / end # will use queue 6
2683
2684 ::
2685
2686    drop / drop / drop / end # drop is performed only once
2687
2688 ::
2689
2690    mark id 42 / queue index 3 / mark id 24 / end # mark will be 24
2691
2692 Considering they are performed simultaneously, opposite and overlapping
2693 actions can sometimes be combined when the end result is unambiguous::
2694
2695    drop / queue index 6 / end # drop has no effect
2696
2697 ::
2698
2699    drop / dup index 6 / end # same as above
2700
2701 ::
2702
2703    queue index 6 / rss queues 6 7 8 / end # queue has no effect
2704
2705 ::
2706
2707    drop / passthru / end # drop has no effect
2708
2709 Note that PMDs may still refuse such combinations.
2710
2711 Actions
2712 ^^^^^^^
2713
2714 This section lists supported actions and their attributes, if any.
2715
2716 - ``end``: end list of actions.
2717
2718 - ``void``: no-op action.
2719
2720 - ``passthru``: let subsequent rule process matched packets.
2721
2722 - ``mark``: attach 32 bit value to packets.
2723
2724   - ``id {unsigned}``: 32 bit value to return with packets.
2725
2726 - ``flag``: flag packets.
2727
2728 - ``queue``: assign packets to a given queue index.
2729
2730   - ``index {unsigned}``: queue index to use.
2731
2732 - ``drop``: drop packets (note: passthru has priority).
2733
2734 - ``count``: enable counters for this rule.
2735
2736 - ``dup``: duplicate packets to a given queue index.
2737
2738   - ``index {unsigned}``: queue index to duplicate packets to.
2739
2740 - ``rss``: spread packets among several queues.
2741
2742   - ``queues [{unsigned} [...]] end``: queue indices to use.
2743
2744 - ``pf``: redirect packets to physical device function.
2745
2746 - ``vf``: redirect packets to virtual device function.
2747
2748   - ``original {boolean}``: use original VF ID if possible.
2749   - ``id {unsigned}``: VF ID to redirect packets to.
2750
2751 Destroying flow rules
2752 ~~~~~~~~~~~~~~~~~~~~~
2753
2754 ``flow destroy`` destroys one or more rules from their rule ID (as returned
2755 by ``flow create``), this command calls ``rte_flow_destroy()`` as many
2756 times as necessary::
2757
2758    flow destroy {port_id} rule {rule_id} [...]
2759
2760 If successful, it will show::
2761
2762    Flow rule #[...] destroyed
2763
2764 It does not report anything for rule IDs that do not exist. The usual error
2765 message is shown when a rule cannot be destroyed::
2766
2767    Caught error type [...] ([...]): [...]
2768
2769 ``flow flush`` destroys all rules on a device and does not take extra
2770 arguments. It is bound to ``rte_flow_flush()``::
2771
2772    flow flush {port_id}
2773
2774 Any errors are reported as above.
2775
2776 Creating several rules and destroying them::
2777
2778    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2779       actions queue index 2 / end
2780    Flow rule #0 created
2781    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2782       actions queue index 3 / end
2783    Flow rule #1 created
2784    testpmd> flow destroy 0 rule 0 rule 1
2785    Flow rule #1 destroyed
2786    Flow rule #0 destroyed
2787    testpmd>
2788
2789 The same result can be achieved using ``flow flush``::
2790
2791    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2792       actions queue index 2 / end
2793    Flow rule #0 created
2794    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2795       actions queue index 3 / end
2796    Flow rule #1 created
2797    testpmd> flow flush 0
2798    testpmd>
2799
2800 Non-existent rule IDs are ignored::
2801
2802    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2803       actions queue index 2 / end
2804    Flow rule #0 created
2805    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2806       actions queue index 3 / end
2807    Flow rule #1 created
2808    testpmd> flow destroy 0 rule 42 rule 10 rule 2
2809    testpmd>
2810    testpmd> flow destroy 0 rule 0
2811    Flow rule #0 destroyed
2812    testpmd>
2813
2814 Querying flow rules
2815 ~~~~~~~~~~~~~~~~~~~
2816
2817 ``flow query`` queries a specific action of a flow rule having that
2818 ability. Such actions collect information that can be reported using this
2819 command. It is bound to ``rte_flow_query()``::
2820
2821    flow query {port_id} {rule_id} {action}
2822
2823 If successful, it will display either the retrieved data for known actions
2824 or the following message::
2825
2826    Cannot display result for action type [...] ([...])
2827
2828 Otherwise, it will complain either that the rule does not exist or that some
2829 error occurred::
2830
2831    Flow rule #[...] not found
2832
2833 ::
2834
2835    Caught error type [...] ([...]): [...]
2836
2837 Currently only the ``count`` action is supported. This action reports the
2838 number of packets that hit the flow rule and the total number of bytes. Its
2839 output has the following format::
2840
2841    count:
2842     hits_set: [...] # whether "hits" contains a valid value
2843     bytes_set: [...] # whether "bytes" contains a valid value
2844     hits: [...] # number of packets
2845     bytes: [...] # number of bytes
2846
2847 Querying counters for TCPv6 packets redirected to queue 6::
2848
2849    testpmd> flow create 0 ingress pattern eth / ipv6 / tcp / end
2850       actions queue index 6 / count / end
2851    Flow rule #4 created
2852    testpmd> flow query 0 4 count
2853    count:
2854     hits_set: 1
2855     bytes_set: 0
2856     hits: 386446
2857     bytes: 0
2858    testpmd>
2859
2860 Listing flow rules
2861 ~~~~~~~~~~~~~~~~~~
2862
2863 ``flow list`` lists existing flow rules sorted by priority and optionally
2864 filtered by group identifiers::
2865
2866    flow list {port_id} [group {group_id}] [...]
2867
2868 This command only fails with the following message if the device does not
2869 exist::
2870
2871    Invalid port [...]
2872
2873 Output consists of a header line followed by a short description of each
2874 flow rule, one per line. There is no output at all when no flow rules are
2875 configured on the device::
2876
2877    ID      Group   Prio    Attr    Rule
2878    [...]   [...]   [...]   [...]   [...]
2879
2880 ``Attr`` column flags:
2881
2882 - ``i`` for ``ingress``.
2883 - ``e`` for ``egress``.
2884
2885 Creating several flow rules and listing them::
2886
2887    testpmd> flow create 0 ingress pattern eth / ipv4 / end
2888       actions queue index 6 / end
2889    Flow rule #0 created
2890    testpmd> flow create 0 ingress pattern eth / ipv6 / end
2891       actions queue index 2 / end
2892    Flow rule #1 created
2893    testpmd> flow create 0 priority 5 ingress pattern eth / ipv4 / udp / end
2894       actions rss queues 6 7 8 end / end
2895    Flow rule #2 created
2896    testpmd> flow list 0
2897    ID      Group   Prio    Attr    Rule
2898    0       0       0       i-      ETH IPV4 => QUEUE
2899    1       0       0       i-      ETH IPV6 => QUEUE
2900    2       0       5       i-      ETH IPV4 UDP => RSS
2901    testpmd>
2902
2903 Rules are sorted by priority (i.e. group ID first, then priority level)::
2904
2905    testpmd> flow list 1
2906    ID      Group   Prio    Attr    Rule
2907    0       0       0       i-      ETH => COUNT
2908    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2909    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2910    1       24      0       i-      ETH IPV4 UDP => QUEUE
2911    4       24      10      i-      ETH IPV4 TCP => DROP
2912    3       24      20      i-      ETH IPV4 => DROP
2913    2       24      42      i-      ETH IPV4 UDP => QUEUE
2914    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2915    testpmd>
2916
2917 Output can be limited to specific groups::
2918
2919    testpmd> flow list 1 group 0 group 63
2920    ID      Group   Prio    Attr    Rule
2921    0       0       0       i-      ETH => COUNT
2922    6       0       500     i-      ETH IPV6 TCP => DROP COUNT
2923    5       0       1000    i-      ETH IPV6 ICMP => QUEUE
2924    7       63      0       i-      ETH IPV6 UDP VXLAN => MARK QUEUE
2925    testpmd>
2926
2927 Toggling isolated mode
2928 ~~~~~~~~~~~~~~~~~~~~~~
2929
2930 ``flow isolate`` can be used to tell the underlying PMD that ingress traffic
2931 must only be injected from the defined flow rules; that no default traffic
2932 is expected outside those rules and the driver is free to assign more
2933 resources to handle them. It is bound to ``rte_flow_isolate()``::
2934
2935  flow isolate {port_id} {boolean}
2936
2937 If successful, enabling or disabling isolated mode shows either::
2938
2939  Ingress traffic on port [...]
2940     is now restricted to the defined flow rules
2941
2942 Or::
2943
2944  Ingress traffic on port [...]
2945     is not restricted anymore to the defined flow rules
2946
2947 Otherwise, in case of error::
2948
2949    Caught error type [...] ([...]): [...]
2950
2951 Mainly due to its side effects, PMDs supporting this mode may not have the
2952 ability to toggle it more than once without reinitializing affected ports
2953 first (e.g. by exiting testpmd).
2954
2955 Enabling isolated mode::
2956
2957  testpmd> flow isolate 0 true
2958  Ingress traffic on port 0 is now restricted to the defined flow rules
2959  testpmd>
2960
2961 Disabling isolated mode::
2962
2963  testpmd> flow isolate 0 false
2964  Ingress traffic on port 0 is not restricted anymore to the defined flow rules
2965  testpmd>
2966
2967 Sample QinQ flow rules
2968 ~~~~~~~~~~~~~~~~~~~~~~
2969
2970 Before creating QinQ rule(s) the following commands should be issued to enable QinQ::
2971
2972    testpmd> port stop 0
2973    testpmd> vlan set qinq on 0
2974
2975 The above command sets the inner and outer TPID's to 0x8100.
2976
2977 To change the TPID's the following commands should be used::
2978
2979    testpmd> vlan set outer tpid 0xa100 0
2980    testpmd> vlan set inner tpid 0x9100 0
2981    testpmd> port start 0
2982
2983 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM.
2984
2985 ::
2986
2987    testpmd> flow validate 0 ingress pattern eth / vlan tci is 123 /
2988        vlan tci is 456 / end actions vf id 1 / queue index 0 / end
2989    Flow rule #0 validated
2990
2991    testpmd> flow create 0 ingress pattern eth / vlan tci is 4 /
2992        vlan tci is 456 / end actions vf id 123 / queue index 0 / end
2993    Flow rule #0 created
2994
2995    testpmd> flow list 0
2996    ID      Group   Prio    Attr    Rule
2997    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
2998
2999 Validate and create a QinQ rule on port 0 to steer traffic to a queue on the host.
3000
3001 ::
3002
3003    testpmd> flow validate 0 ingress pattern eth / vlan tci is 321 /
3004         vlan tci is 654 / end actions pf / queue index 0 / end
3005    Flow rule #1 validated
3006
3007    testpmd> flow create 0 ingress pattern eth / vlan tci is 321 /
3008         vlan tci is 654 / end actions pf / queue index 1 / end
3009    Flow rule #1 created
3010
3011    testpmd> flow list 0
3012    ID      Group   Prio    Attr    Rule
3013    0       0       0       i-      ETH VLAN VLAN=>VF QUEUE
3014    1       0       0       i-      ETH VLAN VLAN=>PF QUEUE