testpmd_funcs.rst revision f7a9461e
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
33Testpmd Runtime Functions
34=========================
35
36Where the testpmd application is started in interactive mode, (``-i|--interactive``),
37it displays a prompt that can be used to start and stop forwarding,
38configure the application, display statistics (including the extended NIC
39statistics aka xstats) , set the Flow Director and other tasks::
40
41   testpmd>
42
43The testpmd prompt has some, limited, readline support.
44Common bash command-line functions such as ``Ctrl+a`` and ``Ctrl+e`` to go to the start and end of the prompt line are supported
45as well as access to the command history via the up-arrow.
46
47There is also support for tab completion.
48If 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 X
55       info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all
56       stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc X
57       stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc all
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
68In the real ``testpmd>`` prompt these commands should be on a single line.
69
70Help Functions
71--------------
72
73The testpmd has on-line help for the functions that are available at runtime.
74These 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
89Control Functions
90-----------------
91
92start
93~~~~~
94
95Start packet forwarding with current configuration::
96
97   testpmd> start
98
99start tx_first
100~~~~~~~~~~~~~~
101
102Start packet forwarding with current configuration after sending specified number of bursts of packets::
103
104   testpmd> start tx_first (""|burst_num)
105
106The default burst number is 1 when ``burst_num`` not presented.
107
108stop
109~~~~
110
111Stop packet forwarding, and display accumulated statistics::
112
113   testpmd> stop
114
115quit
116~~~~
117
118Quit to prompt::
119
120   testpmd> quit
121
122
123Display Functions
124-----------------
125
126The functions in the following sections are used to display information about the
127testpmd configuration or the NIC status.
128
129show port
130~~~~~~~~~
131
132Display information for a given port or all ports::
133
134   testpmd> show port (info|stats|xstats|fdir|stat_qmap|dcb_tc) (port_id|all)
135
136The available information categories are:
137
138* ``info``: General port information such as MAC address.
139
140* ``stats``: RX/TX statistics.
141
142* ``xstats``: RX/TX extended NIC statistics.
143
144* ``fdir``: Flow Director information and statistics.
145
146* ``stat_qmap``: Queue statistics mapping.
147
148* ``dcb_tc``: DCB information such as TC mapping.
149
150For example:
151
152.. code-block:: console
153
154   testpmd> show port info 0
155
156   ********************* Infos for port 0 *********************
157
158   MAC address: XX:XX:XX:XX:XX:XX
159   Connect to socket: 0
160   memory allocation on the socket: 0
161   Link status: up
162   Link speed: 40000 Mbps
163   Link duplex: full-duplex
164   Promiscuous mode: enabled
165   Allmulticast mode: disabled
166   Maximum number of MAC addresses: 64
167   Maximum number of MAC addresses of hash filtering: 0
168   VLAN offload:
169       strip on
170       filter on
171       qinq(extend) off
172   Redirection table size: 512
173   Supported flow types:
174     ipv4-frag
175     ipv4-tcp
176     ipv4-udp
177     ipv4-sctp
178     ipv4-other
179     ipv6-frag
180     ipv6-tcp
181     ipv6-udp
182     ipv6-sctp
183     ipv6-other
184     l2_payload
185     port
186     vxlan
187     geneve
188     nvgre
189
190show port rss reta
191~~~~~~~~~~~~~~~~~~
192
193Display the rss redirection table entry indicated by masks on port X::
194
195   testpmd> show port (port_id) rss reta (size) (mask0, mask1...)
196
197size is used to indicate the hardware supported reta size
198
199show port rss-hash
200~~~~~~~~~~~~~~~~~~
201
202Display the RSS hash functions and RSS hash key of a port::
203
204   testpmd> show port (port_id) rss-hash [key]
205
206clear port
207~~~~~~~~~~
208
209Clear the port statistics for a given port or for all ports::
210
211   testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all)
212
213For example::
214
215   testpmd> clear port stats all
216
217show (rxq|txq)
218~~~~~~~~~~~~~~
219
220Display information for a given port's RX/TX queue::
221
222   testpmd> show (rxq|txq) info (port_id) (queue_id)
223
224show config
225~~~~~~~~~~~
226
227Displays the configuration of the application.
228The configuration comes from the command-line, the runtime or the application defaults::
229
230   testpmd> show config (rxtx|cores|fwd|txpkts)
231
232The available information categories are:
233
234* ``rxtx``: RX/TX configuration items.
235
236* ``cores``: List of forwarding cores.
237
238* ``fwd``: Packet forwarding configuration.
239
240* ``txpkts``: Packets to TX configuration.
241
242For example:
243
244.. code-block:: console
245
246   testpmd> show config rxtx
247
248   io packet forwarding - CRC stripping disabled - packets/burst=16
249   nb forwarding cores=2 - nb forwarding ports=1
250   RX queues=1 - RX desc=128 - RX free threshold=0
251   RX threshold registers: pthresh=8 hthresh=8 wthresh=4
252   TX queues=1 - TX desc=512 - TX free threshold=0
253   TX threshold registers: pthresh=36 hthresh=0 wthresh=0
254   TX RS bit threshold=0 - TXQ flags=0x0
255
256set fwd
257~~~~~~~
258
259Set the packet forwarding mode::
260
261   testpmd> set fwd (io|mac|macswap|flowgen| \
262                     rxonly|txonly|csum|icmpecho) (""|retry)
263
264``retry`` can be specified for forwarding engines except ``rx_only``.
265
266The available information categories are:
267
268* ``io``: Forwards packets "as-is" in I/O mode.
269  This is the fastest possible forwarding operation as it does not access packets data.
270  This is the default mode.
271
272* ``mac``: Changes the source and the destination Ethernet addresses of packets before forwarding them.
273  Default application behaviour is to set source Ethernet address to that of the transmitting interface, and destination
274  address to a dummy value (set during init). The user may specify a target destination Ethernet address via the 'eth-peer' or
275  'eth-peer-configfile' command-line options. It is not currently possible to specify a specific source Ethernet address.
276
277* ``macswap``: MAC swap forwarding mode.
278  Swaps the source and the destination Ethernet addresses of packets before forwarding them.
279
280* ``flowgen``: Multi-flow generation mode.
281  Originates a number of flows (with varying destination IP addresses), and terminate receive traffic.
282
283* ``rxonly``: Receives packets but doesn't transmit them.
284
285* ``txonly``: Generates and transmits packets without receiving any.
286
287* ``csum``: Changes the checksum field with hardware or software methods depending on the offload flags on the packet.
288
289* ``icmpecho``: Receives a burst of packets, lookup for IMCP echo requests and, if any, send back ICMP echo replies.
290
291* ``ieee1588``: Demonstrate L2 IEEE1588 V2 PTP timestamping for RX and TX. Requires ``CONFIG_RTE_LIBRTE_IEEE1588=y``.
292
293Note: TX timestamping is only available in the "Full Featured" TX path. To force ``testpmd`` into this mode set ``--txqflags=0``.
294
295Example::
296
297   testpmd> set fwd rxonly
298
299   Set rxonly packet forwarding mode
300
301
302read rxd
303~~~~~~~~
304
305Display an RX descriptor for a port RX queue::
306
307   testpmd> read rxd (port_id) (queue_id) (rxd_id)
308
309For example::
310
311   testpmd> read rxd 0 0 4
312        0x0000000B - 0x001D0180 / 0x0000000B - 0x001D0180
313
314read txd
315~~~~~~~~
316
317Display a TX descriptor for a port TX queue::
318
319   testpmd> read txd (port_id) (queue_id) (txd_id)
320
321For example::
322
323   testpmd> read txd 0 0 4
324        0x00000001 - 0x24C3C440 / 0x000F0000 - 0x2330003C
325
326
327Configuration Functions
328-----------------------
329
330The testpmd application can be configured from the runtime as well as from the command-line.
331
332This section details the available configuration functions that are available.
333
334.. note::
335
336   Configuration changes only become active when forwarding is started/restarted.
337
338set default
339~~~~~~~~~~~
340
341Reset forwarding to the default configuration::
342
343   testpmd> set default
344
345set verbose
346~~~~~~~~~~~
347
348Set the debug verbosity level::
349
350   testpmd> set verbose (level)
351
352Currently the only available levels are 0 (silent except for error) and 1 (fully verbose).
353
354set nbport
355~~~~~~~~~~
356
357Set the number of ports used by the application:
358
359set nbport (num)
360
361This is equivalent to the ``--nb-ports`` command-line option.
362
363set nbcore
364~~~~~~~~~~
365
366Set the number of cores used by the application::
367
368   testpmd> set nbcore (num)
369
370This is equivalent to the ``--nb-cores`` command-line option.
371
372.. note::
373
374   The number of cores used must not be greater than number of ports used multiplied by the number of queues per port.
375
376set coremask
377~~~~~~~~~~~~
378
379Set the forwarding cores hexadecimal mask::
380
381   testpmd> set coremask (mask)
382
383This is equivalent to the ``--coremask`` command-line option.
384
385.. note::
386
387   The master lcore is reserved for command line parsing only and cannot be masked on for packet forwarding.
388
389set portmask
390~~~~~~~~~~~~
391
392Set the forwarding ports hexadecimal mask::
393
394   testpmd> set portmask (mask)
395
396This is equivalent to the ``--portmask`` command-line option.
397
398set burst
399~~~~~~~~~
400
401Set number of packets per burst::
402
403   testpmd> set burst (num)
404
405This is equivalent to the ``--burst command-line`` option.
406
407When retry is enabled, the transmit delay time and number of retries can also be set::
408
409   testpmd> set burst tx delay (microseconds) retry (num)
410
411set txpkts
412~~~~~~~~~~
413
414Set the length of each segment of the TX-ONLY packets or length of packet for FLOWGEN mode::
415
416   testpmd> set txpkts (x[,y]*)
417
418Where x[,y]* represents a CSV list of values, without white space.
419
420set txsplit
421~~~~~~~~~~~
422
423Set the split policy for the TX packets, applicable for TX-ONLY and CSUM forwarding modes::
424
425   testpmd> set txsplit (off|on|rand)
426
427Where:
428
429* ``off`` disable packet copy & split for CSUM mode.
430
431* ``on`` split outgoing packet into multiple segments. Size of each segment
432  and number of segments per packet is determined by ``set txpkts`` command
433  (see above).
434
435* ``rand`` same as 'on', but number of segments per each packet is a random value between 1 and total number of segments.
436
437set corelist
438~~~~~~~~~~~~
439
440Set the list of forwarding cores::
441
442   testpmd> set corelist (x[,y]*)
443
444For example, to change the forwarding cores:
445
446.. code-block:: console
447
448   testpmd> set corelist 3,1
449   testpmd> show config fwd
450
451   io packet forwarding - ports=2 - cores=2 - streams=2 - NUMA support disabled
452   Logical Core 3 (socket 0) forwards packets on 1 streams:
453   RX P=0/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:01
454   Logical Core 1 (socket 0) forwards packets on 1 streams:
455   RX P=1/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
456
457.. note::
458
459   The cores are used in the same order as specified on the command line.
460
461set portlist
462~~~~~~~~~~~~
463
464Set the list of forwarding ports::
465
466   testpmd> set portlist (x[,y]*)
467
468For example, to change the port forwarding:
469
470.. code-block:: console
471
472   testpmd> set portlist 0,2,1,3
473   testpmd> show config fwd
474
475   io packet forwarding - ports=4 - cores=1 - streams=4
476   Logical Core 3 (socket 0) forwards packets on 4 streams:
477   RX P=0/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:01
478   RX P=2/Q=0 (socket 0) -> TX P=0/Q=0 (socket 0) peer=02:00:00:00:00:00
479   RX P=1/Q=0 (socket 0) -> TX P=3/Q=0 (socket 0) peer=02:00:00:00:00:03
480   RX P=3/Q=0 (socket 0) -> TX P=1/Q=0 (socket 0) peer=02:00:00:00:00:02
481
482set tx loopback
483~~~~~~~~~~~~~~~
484
485Enable/disable tx loopback::
486
487   testpmd> set tx loopback (port_id) (on|off)
488
489set drop enable
490~~~~~~~~~~~~~~~
491
492set drop enable bit for all queues::
493
494   testpmd> set all queues drop (port_id) (on|off)
495
496set split drop enable (for VF)
497~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498
499set split drop enable bit for VF from PF::
500
501   testpmd> set vf split drop (port_id) (vf_id) (on|off)
502
503set mac antispoof (for VF)
504~~~~~~~~~~~~~~~~~~~~~~~~~~
505
506Set mac antispoof for a VF from the PF::
507
508   testpmd> set vf mac antispoof  (port_id) (vf_id) (on|off)
509
510vlan set strip
511~~~~~~~~~~~~~~
512
513Set the VLAN strip on a port::
514
515   testpmd> vlan set strip (on|off) (port_id)
516
517vlan set stripq
518~~~~~~~~~~~~~~~
519
520Set the VLAN strip for a queue on a port::
521
522   testpmd> vlan set stripq (on|off) (port_id,queue_id)
523
524vlan set stripq (for VF)
525~~~~~~~~~~~~~~~~~~~~~~~~
526
527Set VLAN strip for all queues in a pool for a VF from the PF::
528
529   testpmd> set vf vlan stripq (port_id) (vf_id) (on|off)
530
531vlan set insert (for VF)
532~~~~~~~~~~~~~~~~~~~~~~~~
533
534Set VLAN insert for a VF from the PF::
535
536   testpmd> set vf vlan insert (port_id) (vf_id) (vlan_id)
537
538vlan set antispoof (for VF)
539~~~~~~~~~~~~~~~~~~~~~~~~~~~
540
541Set VLAN antispoof for a VF from the PF::
542
543   testpmd> set vf vlan antispoof (port_id) (vf_id) (on|off)
544
545vlan set filter
546~~~~~~~~~~~~~~~
547
548Set the VLAN filter on a port::
549
550   testpmd> vlan set filter (on|off) (port_id)
551
552vlan set qinq
553~~~~~~~~~~~~~
554
555Set the VLAN QinQ (extended queue in queue) on for a port::
556
557   testpmd> vlan set qinq (on|off) (port_id)
558
559vlan set tpid
560~~~~~~~~~~~~~
561
562Set the inner or outer VLAN TPID for packet filtering on a port::
563
564   testpmd> vlan set (inner|outer) tpid (value) (port_id)
565
566.. note::
567
568   TPID value must be a 16-bit number (value <= 65536).
569
570rx_vlan add
571~~~~~~~~~~~
572
573Add a VLAN ID, or all identifiers, to the set of VLAN identifiers filtered by port ID::
574
575   testpmd> rx_vlan add (vlan_id|all) (port_id)
576
577.. note::
578
579   VLAN filter must be set on that port. VLAN ID < 4096.
580   Depending on the NIC used, number of vlan_ids may be limited to the maximum entries
581   in VFTA table. This is important if enabling all vlan_ids.
582
583rx_vlan rm
584~~~~~~~~~~
585
586Remove a VLAN ID, or all identifiers, from the set of VLAN identifiers filtered by port ID::
587
588   testpmd> rx_vlan rm (vlan_id|all) (port_id)
589
590rx_vlan add (for VF)
591~~~~~~~~~~~~~~~~~~~~
592
593Add a VLAN ID, to the set of VLAN identifiers filtered for VF(s) for port ID::
594
595   testpmd> rx_vlan add (vlan_id) port (port_id) vf (vf_mask)
596
597rx_vlan rm (for VF)
598~~~~~~~~~~~~~~~~~~~
599
600Remove a VLAN ID, from the set of VLAN identifiers filtered for VF(s) for port ID::
601
602   testpmd> rx_vlan rm (vlan_id) port (port_id) vf (vf_mask)
603
604tunnel_filter add
605~~~~~~~~~~~~~~~~~
606
607Add a tunnel filter on a port::
608
609   testpmd> tunnel_filter add (port_id) (outer_mac) (inner_mac) (ip_addr) \
610            (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
611            imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
612
613The available information categories are:
614
615* ``vxlan``: Set tunnel type as VXLAN.
616
617* ``nvgre``: Set tunnel type as NVGRE.
618
619* ``ipingre``: Set tunnel type as IP-in-GRE.
620
621* ``imac-ivlan``: Set filter type as Inner MAC and VLAN.
622
623* ``imac-ivlan-tenid``: Set filter type as Inner MAC, VLAN and tenant ID.
624
625* ``imac-tenid``: Set filter type as Inner MAC and tenant ID.
626
627* ``imac``: Set filter type as Inner MAC.
628
629* ``omac-imac-tenid``: Set filter type as Outer MAC, Inner MAC and tenant ID.
630
631* ``oip``: Set filter type as Outer IP.
632
633* ``iip``: Set filter type as Inner IP.
634
635Example::
636
637   testpmd> tunnel_filter add 0 68:05:CA:28:09:82 00:00:00:00:00:00 \
638            192.168.2.2 0 ipingre oip 1 1
639
640   Set an IP-in-GRE tunnel on port 0, and the filter type is Outer IP.
641
642tunnel_filter remove
643~~~~~~~~~~~~~~~~~~~~
644
645Remove a tunnel filter on a port::
646
647   testpmd> tunnel_filter rm (port_id) (outer_mac) (inner_mac) (ip_addr) \
648            (inner_vlan) (vxlan|nvgre|ipingre) (imac-ivlan|imac-ivlan-tenid|\
649            imac-tenid|imac|omac-imac-tenid|oip|iip) (tenant_id) (queue_id)
650
651rx_vxlan_port add
652~~~~~~~~~~~~~~~~~
653
654Add an UDP port for VXLAN packet filter on a port::
655
656   testpmd> rx_vxlan_port add (udp_port) (port_id)
657
658rx_vxlan_port remove
659~~~~~~~~~~~~~~~~~~~~
660
661Remove an UDP port for VXLAN packet filter on a port::
662
663   testpmd> rx_vxlan_port rm (udp_port) (port_id)
664
665tx_vlan set
666~~~~~~~~~~~
667
668Set hardware insertion of VLAN IDs in packets sent on a port::
669
670   testpmd> tx_vlan set (port_id) vlan_id[, vlan_id_outer]
671
672For example, set a single VLAN ID (5) insertion on port 0::
673
674   tx_vlan set 0 5
675
676Or, set double VLAN ID (inner: 2, outer: 3) insertion on port 1::
677
678   tx_vlan set 1 2 3
679
680
681tx_vlan set pvid
682~~~~~~~~~~~~~~~~
683
684Set port based hardware insertion of VLAN ID in packets sent on a port::
685
686   testpmd> tx_vlan set pvid (port_id) (vlan_id) (on|off)
687
688tx_vlan reset
689~~~~~~~~~~~~~
690
691Disable hardware insertion of a VLAN header in packets sent on a port::
692
693   testpmd> tx_vlan reset (port_id)
694
695csum set
696~~~~~~~~
697
698Select hardware or software calculation of the checksum when
699transmitting a packet using the ``csum`` forwarding engine::
700
701   testpmd> csum set (ip|udp|tcp|sctp|outer-ip) (hw|sw) (port_id)
702
703Where:
704
705* ``ip|udp|tcp|sctp`` always relate to  the inner layer.
706
707* ``outer-ip`` relates to the outer IP layer (only for IPv4) in the case where the packet is recognized
708  as a tunnel packet by the forwarding engine (vxlan, gre and ipip are
709  supported). See also the ``csum parse-tunnel`` command.
710
711.. note::
712
713   Check the NIC Datasheet for hardware limits.
714
715csum parse-tunnel
716~~~~~~~~~~~~~~~~~
717
718Define how tunneled packets should be handled by the csum forward
719engine::
720
721   testpmd> csum parse-tunnel (on|off) (tx_port_id)
722
723If enabled, the csum forward engine will try to recognize supported
724tunnel headers (vxlan, gre, ipip).
725
726If disabled, treat tunnel packets as non-tunneled packets (a inner
727header is handled as a packet payload).
728
729.. note::
730
731   The port argument is the TX port like in the ``csum set`` command.
732
733Example:
734
735Consider a packet in packet like the following::
736
737   eth_out/ipv4_out/udp_out/vxlan/eth_in/ipv4_in/tcp_in
738
739* If parse-tunnel is enabled, the ``ip|udp|tcp|sctp`` parameters of ``csum set``
740  command relate to the inner headers (here ``ipv4_in`` and ``tcp_in``), and the
741  ``outer-ip parameter`` relates to the outer headers (here ``ipv4_out``).
742
743* If parse-tunnel is disabled, the ``ip|udp|tcp|sctp`` parameters of ``csum  set``
744   command relate to the outer headers, here ``ipv4_out`` and ``udp_out``.
745
746csum show
747~~~~~~~~~
748
749Display tx checksum offload configuration::
750
751   testpmd> csum show (port_id)
752
753tso set
754~~~~~~~
755
756Enable TCP Segmentation Offload (TSO) in the ``csum`` forwarding engine::
757
758   testpmd> tso set (segsize) (port_id)
759
760.. note::
761
762   Check the NIC datasheet for hardware limits.
763
764tso show
765~~~~~~~~
766
767Display the status of TCP Segmentation Offload::
768
769   testpmd> tso show (port_id)
770
771mac_addr add
772~~~~~~~~~~~~
773
774Add an alternative MAC address to a port::
775
776   testpmd> mac_addr add (port_id) (XX:XX:XX:XX:XX:XX)
777
778mac_addr remove
779~~~~~~~~~~~~~~~
780
781Remove a MAC address from a port::
782
783   testpmd> mac_addr remove (port_id) (XX:XX:XX:XX:XX:XX)
784
785mac_addr add (for VF)
786~~~~~~~~~~~~~~~~~~~~~
787
788Add an alternative MAC address for a VF to a port::
789
790   testpmd> mac_add add port (port_id) vf (vf_id) (XX:XX:XX:XX:XX:XX)
791
792mac_addr set (for VF)
793~~~~~~~~~~~~~~~~~~~~~
794
795Set the MAC address for a VF from the PF::
796
797   testpmd> set vf mac addr (port_id) (vf_id) (XX:XX:XX:XX:XX:XX)
798
799set port-uta
800~~~~~~~~~~~~
801
802Set the unicast hash filter(s) on/off for a port::
803
804   testpmd> set port (port_id) uta (XX:XX:XX:XX:XX:XX|all) (on|off)
805
806set promisc
807~~~~~~~~~~~
808
809Set the promiscuous mode on for a port or for all ports.
810In promiscuous mode packets are not dropped if they aren't for the specified MAC address::
811
812   testpmd> set promisc (port_id|all) (on|off)
813
814set allmulti
815~~~~~~~~~~~~
816
817Set the allmulti mode for a port or for all ports::
818
819   testpmd> set allmulti (port_id|all) (on|off)
820
821Same as the ifconfig (8) option. Controls how multicast packets are handled.
822
823set flow_ctrl rx
824~~~~~~~~~~~~~~~~
825
826Set the link flow control parameter on a port::
827
828   testpmd> set flow_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
829            (pause_time) (send_xon) mac_ctrl_frame_fwd (on|off) \
830	    autoneg (on|off) (port_id)
831
832Where:
833
834* ``high_water`` (integer): High threshold value to trigger XOFF.
835
836* ``low_water`` (integer): Low threshold value to trigger XON.
837
838* ``pause_time`` (integer): Pause quota in the Pause frame.
839
840* ``send_xon`` (0/1): Send XON frame.
841
842* ``mac_ctrl_frame_fwd``: Enable receiving MAC control frames.
843
844* ``autoneg``: Change the auto-negotiation para mete.
845
846set pfc_ctrl rx
847~~~~~~~~~~~~~~~
848
849Set the priority flow control parameter on a port::
850
851   testpmd> set pfc_ctrl rx (on|off) tx (on|off) (high_water) (low_water) \
852            (pause_time) (priority) (port_id)
853
854Where:
855
856* ``high_water`` (integer): High threshold value.
857
858* ``low_water`` (integer): Low threshold value.
859
860* ``pause_time`` (integer): Pause quota in the Pause frame.
861
862* ``priority`` (0-7): VLAN User Priority.
863
864set stat_qmap
865~~~~~~~~~~~~~
866
867Set statistics mapping (qmapping 0..15) for RX/TX queue on port::
868
869   testpmd> set stat_qmap (tx|rx) (port_id) (queue_id) (qmapping)
870
871For example, to set rx queue 2 on port 0 to mapping 5::
872
873   testpmd>set stat_qmap rx 0 2 5
874
875set port - rx/tx (for VF)
876~~~~~~~~~~~~~~~~~~~~~~~~~
877
878Set VF receive/transmit from a port::
879
880   testpmd> set port (port_id) vf (vf_id) (rx|tx) (on|off)
881
882set port - mac address filter (for VF)
883~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
884
885Add/Remove unicast or multicast MAC addr filter for a VF::
886
887   testpmd> set port (port_id) vf (vf_id) (mac_addr) \
888            (exact-mac|exact-mac-vlan|hashmac|hashmac-vlan) (on|off)
889
890set port - rx mode(for VF)
891~~~~~~~~~~~~~~~~~~~~~~~~~~
892
893Set the VF receive mode of a port::
894
895   testpmd> set port (port_id) vf (vf_id) \
896            rxmode (AUPE|ROPE|BAM|MPE) (on|off)
897
898The available receive modes are:
899
900* ``AUPE``: Accepts untagged VLAN.
901
902* ``ROPE``: Accepts unicast hash.
903
904* ``BAM``: Accepts broadcast packets.
905
906* ``MPE``: Accepts all multicast packets.
907
908set port - tx_rate (for Queue)
909~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
910
911Set TX rate limitation for a queue on a port::
912
913   testpmd> set port (port_id) queue (queue_id) rate (rate_value)
914
915set port - tx_rate (for VF)
916~~~~~~~~~~~~~~~~~~~~~~~~~~~
917
918Set TX rate limitation for queues in VF on a port::
919
920   testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask)
921
922set port - mirror rule
923~~~~~~~~~~~~~~~~~~~~~~
924
925Set pool or vlan type mirror rule for a port::
926
927   testpmd> set port (port_id) mirror-rule (rule_id) \
928            (pool-mirror-up|pool-mirror-down|vlan-mirror) \
929            (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off)
930
931Set link mirror rule for a port::
932
933   testpmd> set port (port_id) mirror-rule (rule_id) \
934           (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off)
935
936For example to enable mirror traffic with vlan 0,1 to pool 0::
937
938   set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on
939
940reset port - mirror rule
941~~~~~~~~~~~~~~~~~~~~~~~~
942
943Reset a mirror rule for a port::
944
945   testpmd> reset port (port_id) mirror-rule (rule_id)
946
947set flush_rx
948~~~~~~~~~~~~
949
950Set the flush on RX streams before forwarding.
951The default is flush ``on``.
952Mainly used with PCAP drivers to turn off the default behavior of flushing the first 512 packets on RX streams::
953
954   testpmd> set flush_rx off
955
956set bypass mode
957~~~~~~~~~~~~~~~
958
959Set the bypass mode for the lowest port on bypass enabled NIC::
960
961   testpmd> set bypass mode (normal|bypass|isolate) (port_id)
962
963set bypass event
964~~~~~~~~~~~~~~~~
965
966Set the event required to initiate specified bypass mode for the lowest port on a bypass enabled::
967
968   testpmd> set bypass event (timeout|os_on|os_off|power_on|power_off) \
969            mode (normal|bypass|isolate) (port_id)
970
971Where:
972
973* ``timeout``: Enable bypass after watchdog timeout.
974
975* ``os_on``: Enable bypass when OS/board is powered on.
976
977* ``os_off``: Enable bypass when OS/board is powered off.
978
979* ``power_on``: Enable bypass when power supply is turned on.
980
981* ``power_off``: Enable bypass when power supply is turned off.
982
983
984set bypass timeout
985~~~~~~~~~~~~~~~~~~
986
987Set the bypass watchdog timeout to ``n`` seconds where 0 = instant::
988
989   testpmd> set bypass timeout (0|1.5|2|3|4|8|16|32)
990
991show bypass config
992~~~~~~~~~~~~~~~~~~
993
994Show the bypass configuration for a bypass enabled NIC using the lowest port on the NIC::
995
996   testpmd> show bypass config (port_id)
997
998set link up
999~~~~~~~~~~~
1000
1001Set link up for a port::
1002
1003   testpmd> set link-up port (port id)
1004
1005set link down
1006~~~~~~~~~~~~~
1007
1008Set link down for a port::
1009
1010   testpmd> set link-down port (port id)
1011
1012E-tag set
1013~~~~~~~~~
1014
1015Enable E-tag insertion for a VF on a port::
1016
1017   testpmd> E-tag set insertion on port-tag-id (value) port (port_id) vf (vf_id)
1018
1019Disable E-tag insertion for a VF on a port::
1020
1021   testpmd> E-tag set insertion off port (port_id) vf (vf_id)
1022
1023Enable/disable E-tag stripping on a port::
1024
1025   testpmd> E-tag set stripping (on|off) port (port_id)
1026
1027Enable/disable E-tag based forwarding on a port::
1028
1029   testpmd> E-tag set forwarding (on|off) port (port_id)
1030
1031Add an E-tag forwarding filter on a port::
1032
1033   testpmd> E-tag set filter add e-tag-id (value) dst-pool (pool_id) port (port_id)
1034
1035Delete an E-tag forwarding filter on a port::
1036   testpmd> E-tag set filter del e-tag-id (value) port (port_id)
1037
1038
1039Port Functions
1040--------------
1041
1042The following sections show functions for configuring ports.
1043
1044.. note::
1045
1046   Port configuration changes only become active when forwarding is started/restarted.
1047
1048port attach
1049~~~~~~~~~~~
1050
1051Attach a port specified by pci address or virtual device args::
1052
1053   testpmd> port attach (identifier)
1054
1055To attach a new pci device, the device should be recognized by kernel first.
1056Then it should be moved under DPDK management.
1057Finally the port can be attached to testpmd.
1058
1059For example, to move a pci device using ixgbe under DPDK management:
1060
1061.. code-block:: console
1062
1063   # Check the status of the available devices.
1064   ./tools/dpdk-devbind.py --status
1065
1066   Network devices using DPDK-compatible driver
1067   ============================================
1068   <none>
1069
1070   Network devices using kernel driver
1071   ===================================
1072   0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=
1073
1074
1075   # Bind the device to igb_uio.
1076   sudo ./tools/dpdk-devbind.py -b igb_uio 0000:0a:00.0
1077
1078
1079   # Recheck the status of the devices.
1080   ./tools/dpdk-devbind.py --status
1081   Network devices using DPDK-compatible driver
1082   ============================================
1083   0000:0a:00.0 '82599ES 10-Gigabit' drv=igb_uio unused=
1084
1085To attach a port created by virtual device, above steps are not needed.
1086
1087For example, to attach a port whose pci address is 0000:0a:00.0.
1088
1089.. code-block:: console
1090
1091   testpmd> port attach 0000:0a:00.0
1092   Attaching a new port...
1093   EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1094   EAL:   probe driver: 8086:10fb rte_ixgbe_pmd
1095   EAL:   PCI memory mapped at 0x7f83bfa00000
1096   EAL:   PCI memory mapped at 0x7f83bfa80000
1097   PMD: eth_ixgbe_dev_init(): MAC: 2, PHY: 18, SFP+: 5
1098   PMD: eth_ixgbe_dev_init(): port 0 vendorID=0x8086 deviceID=0x10fb
1099   Port 0 is attached. Now total ports is 1
1100   Done
1101
1102For example, to attach a port created by pcap PMD.
1103
1104.. code-block:: console
1105
1106   testpmd> port attach net_pcap0
1107   Attaching a new port...
1108   PMD: Initializing pmd_pcap for net_pcap0
1109   PMD: Creating pcap-backed ethdev on numa socket 0
1110   Port 0 is attached. Now total ports is 1
1111   Done
1112
1113In this case, identifier is ``net_pcap0``.
1114This identifier format is the same as ``--vdev`` format of DPDK applications.
1115
1116For example, to re-attach a bonded port which has been previously detached,
1117the mode and slave parameters must be given.
1118
1119.. code-block:: console
1120
1121   testpmd> port attach net_bond_0,mode=0,slave=1
1122   Attaching a new port...
1123   EAL: Initializing pmd_bond for net_bond_0
1124   EAL: Create bonded device net_bond_0 on port 0 in mode 0 on socket 0.
1125   Port 0 is attached. Now total ports is 1
1126   Done
1127
1128
1129port detach
1130~~~~~~~~~~~
1131
1132Detach a specific port::
1133
1134   testpmd> port detach (port_id)
1135
1136Before detaching a port, the port should be stopped and closed.
1137
1138For example, to detach a pci device port 0.
1139
1140.. code-block:: console
1141
1142   testpmd> port stop 0
1143   Stopping ports...
1144   Done
1145   testpmd> port close 0
1146   Closing ports...
1147   Done
1148
1149   testpmd> port detach 0
1150   Detaching a port...
1151   EAL: PCI device 0000:0a:00.0 on NUMA socket -1
1152   EAL:   remove driver: 8086:10fb rte_ixgbe_pmd
1153   EAL:   PCI memory unmapped at 0x7f83bfa00000
1154   EAL:   PCI memory unmapped at 0x7f83bfa80000
1155   Done
1156
1157
1158For example, to detach a virtual device port 0.
1159
1160.. code-block:: console
1161
1162   testpmd> port stop 0
1163   Stopping ports...
1164   Done
1165   testpmd> port close 0
1166   Closing ports...
1167   Done
1168
1169   testpmd> port detach 0
1170   Detaching a port...
1171   PMD: Closing pcap ethdev on numa socket 0
1172   Port 'net_pcap0' is detached. Now total ports is 0
1173   Done
1174
1175To remove a pci device completely from the system, first detach the port from testpmd.
1176Then the device should be moved under kernel management.
1177Finally the device can be removed using kernel pci hotplug functionality.
1178
1179For example, to move a pci device under kernel management:
1180
1181.. code-block:: console
1182
1183   sudo ./tools/dpdk-devbind.py -b ixgbe 0000:0a:00.0
1184
1185   ./tools/dpdk-devbind.py --status
1186
1187   Network devices using DPDK-compatible driver
1188   ============================================
1189   <none>
1190
1191   Network devices using kernel driver
1192   ===================================
1193   0000:0a:00.0 '82599ES 10-Gigabit' if=eth2 drv=ixgbe unused=igb_uio
1194
1195To remove a port created by a virtual device, above steps are not needed.
1196
1197port start
1198~~~~~~~~~~
1199
1200Start all ports or a specific port::
1201
1202   testpmd> port start (port_id|all)
1203
1204port stop
1205~~~~~~~~~
1206
1207Stop all ports or a specific port::
1208
1209   testpmd> port stop (port_id|all)
1210
1211port close
1212~~~~~~~~~~
1213
1214Close all ports or a specific port::
1215
1216   testpmd> port close (port_id|all)
1217
1218port start/stop queue
1219~~~~~~~~~~~~~~~~~~~~~
1220
1221Start/stop a rx/tx queue on a specific port::
1222
1223   testpmd> port (port_id) (rxq|txq) (queue_id) (start|stop)
1224
1225Only take effect when port is started.
1226
1227port config - speed
1228~~~~~~~~~~~~~~~~~~~
1229
1230Set the speed and duplex mode for all ports or a specific port::
1231
1232   testpmd> port config (port_id|all) speed (10|100|1000|10000|25000|40000|50000|100000|auto) \
1233            duplex (half|full|auto)
1234
1235port config - queues/descriptors
1236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1237
1238Set number of queues/descriptors for rxq, txq, rxd and txd::
1239
1240   testpmd> port config all (rxq|txq|rxd|txd) (value)
1241
1242This is equivalent to the ``--rxq``, ``--txq``, ``--rxd`` and ``--txd`` command-line options.
1243
1244port config - max-pkt-len
1245~~~~~~~~~~~~~~~~~~~~~~~~~
1246
1247Set the maximum packet length::
1248
1249   testpmd> port config all max-pkt-len (value)
1250
1251This is equivalent to the ``--max-pkt-len`` command-line option.
1252
1253port config - CRC Strip
1254~~~~~~~~~~~~~~~~~~~~~~~
1255
1256Set hardware CRC stripping on or off for all ports::
1257
1258   testpmd> port config all crc-strip (on|off)
1259
1260CRC stripping is on by default.
1261
1262The ``off`` option is equivalent to the ``--disable-crc-strip`` command-line option.
1263
1264port config - scatter
1265~~~~~~~~~~~~~~~~~~~~~~~
1266
1267Set RX scatter mode on or off for all ports::
1268
1269   testpmd> port config all scatter (on|off)
1270
1271RX scatter mode is off by default.
1272
1273The ``on`` option is equivalent to the ``--enable-scatter`` command-line option.
1274
1275port config - TX queue flags
1276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1277
1278Set a hexadecimal bitmap of TX queue flags for all ports::
1279
1280   testpmd> port config all txqflags value
1281
1282This command is equivalent to the ``--txqflags`` command-line option.
1283
1284port config - RX Checksum
1285~~~~~~~~~~~~~~~~~~~~~~~~~
1286
1287Set hardware RX checksum offload to on or off for all ports::
1288
1289   testpmd> port config all rx-cksum (on|off)
1290
1291Checksum offload is off by default.
1292
1293The ``on`` option is equivalent to the ``--enable-rx-cksum`` command-line option.
1294
1295port config - VLAN
1296~~~~~~~~~~~~~~~~~~
1297
1298Set hardware VLAN on or off for all ports::
1299
1300   testpmd> port config all hw-vlan (on|off)
1301
1302Hardware VLAN is on by default.
1303
1304The ``off`` option is equivalent to the ``--disable-hw-vlan`` command-line option.
1305
1306port config - VLAN filter
1307~~~~~~~~~~~~~~~~~~~~~~~~~
1308
1309Set hardware VLAN filter on or off for all ports::
1310
1311   testpmd> port config all hw-vlan-filter (on|off)
1312
1313Hardware VLAN filter is on by default.
1314
1315The ``off`` option is equivalent to the ``--disable-hw-vlan-filter`` command-line option.
1316
1317port config - VLAN strip
1318~~~~~~~~~~~~~~~~~~~~~~~~
1319
1320Set hardware VLAN strip on or off for all ports::
1321
1322   testpmd> port config all hw-vlan-strip (on|off)
1323
1324Hardware VLAN strip is on by default.
1325
1326The ``off`` option is equivalent to the ``--disable-hw-vlan-strip`` command-line option.
1327
1328port config - VLAN extend
1329~~~~~~~~~~~~~~~~~~~~~~~~~
1330
1331Set hardware VLAN extend on or off for all ports::
1332
1333   testpmd> port config all hw-vlan-extend (on|off)
1334
1335Hardware VLAN extend is off by default.
1336
1337The ``off`` option is equivalent to the ``--disable-hw-vlan-extend`` command-line option.
1338
1339port config - Drop Packets
1340~~~~~~~~~~~~~~~~~~~~~~~~~~
1341
1342Set packet drop for packets with no descriptors on or off for all ports::
1343
1344   testpmd> port config all drop-en (on|off)
1345
1346Packet dropping for packets with no descriptors is off by default.
1347
1348The ``on`` option is equivalent to the ``--enable-drop-en`` command-line option.
1349
1350port config - RSS
1351~~~~~~~~~~~~~~~~~
1352
1353Set the RSS (Receive Side Scaling) mode on or off::
1354
1355   testpmd> port config all rss (all|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|none)
1356
1357RSS is on by default.
1358
1359The ``none`` option is equivalent to the ``--disable-rss`` command-line option.
1360
1361port config - RSS Reta
1362~~~~~~~~~~~~~~~~~~~~~~
1363
1364Set the RSS (Receive Side Scaling) redirection table::
1365
1366   testpmd> port config all rss reta (hash,queue)[,(hash,queue)]
1367
1368port config - DCB
1369~~~~~~~~~~~~~~~~~
1370
1371Set the DCB mode for an individual port::
1372
1373   testpmd> port config (port_id) dcb vt (on|off) (traffic_class) pfc (on|off)
1374
1375The traffic class should be 4 or 8.
1376
1377port config - Burst
1378~~~~~~~~~~~~~~~~~~~
1379
1380Set the number of packets per burst::
1381
1382   testpmd> port config all burst (value)
1383
1384This is equivalent to the ``--burst`` command-line option.
1385
1386port config - Threshold
1387~~~~~~~~~~~~~~~~~~~~~~~
1388
1389Set thresholds for TX/RX queues::
1390
1391   testpmd> port config all (threshold) (value)
1392
1393Where the threshold type can be:
1394
1395* ``txpt:`` Set the prefetch threshold register of the TX rings, 0 <= value <= 255.
1396
1397* ``txht:`` Set the host threshold register of the TX rings, 0 <= value <= 255.
1398
1399* ``txwt:`` Set the write-back threshold register of the TX rings, 0 <= value <= 255.
1400
1401* ``rxpt:`` Set the prefetch threshold register of the RX rings, 0 <= value <= 255.
1402
1403* ``rxht:`` Set the host threshold register of the RX rings, 0 <= value <= 255.
1404
1405* ``rxwt:`` Set the write-back threshold register of the RX rings, 0 <= value <= 255.
1406
1407* ``txfreet:`` Set the transmit free threshold of the TX rings, 0 <= value <= txd.
1408
1409* ``rxfreet:`` Set the transmit free threshold of the RX rings, 0 <= value <= rxd.
1410
1411* ``txrst:`` Set the transmit RS bit threshold of TX rings, 0 <= value <= txd.
1412
1413These threshold options are also available from the command-line.
1414
1415port config - E-tag
1416~~~~~~~~~~~~~~~~~~~
1417
1418Set the value of ether-type for E-tag::
1419
1420   testpmd> port config (port_id|all) l2-tunnel E-tag ether-type (value)
1421
1422Enable/disable the E-tag support::
1423
1424   testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable)
1425
1426
1427Link Bonding Functions
1428----------------------
1429
1430The Link Bonding functions make it possible to dynamically create and
1431manage link bonding devices from within testpmd interactive prompt.
1432
1433create bonded device
1434~~~~~~~~~~~~~~~~~~~~
1435
1436Create a new bonding device::
1437
1438   testpmd> create bonded device (mode) (socket)
1439
1440For example, to create a bonded device in mode 1 on socket 0::
1441
1442   testpmd> create bonded device 1 0
1443   created new bonded device (port X)
1444
1445add bonding slave
1446~~~~~~~~~~~~~~~~~
1447
1448Adds Ethernet device to a Link Bonding device::
1449
1450   testpmd> add bonding slave (slave id) (port id)
1451
1452For example, to add Ethernet device (port 6) to a Link Bonding device (port 10)::
1453
1454   testpmd> add bonding slave 6 10
1455
1456
1457remove bonding slave
1458~~~~~~~~~~~~~~~~~~~~
1459
1460Removes an Ethernet slave device from a Link Bonding device::
1461
1462   testpmd> remove bonding slave (slave id) (port id)
1463
1464For example, to remove Ethernet slave device (port 6) to a Link Bonding device (port 10)::
1465
1466   testpmd> remove bonding slave 6 10
1467
1468set bonding mode
1469~~~~~~~~~~~~~~~~
1470
1471Set the Link Bonding mode of a Link Bonding device::
1472
1473   testpmd> set bonding mode (value) (port id)
1474
1475For example, to set the bonding mode of a Link Bonding device (port 10) to broadcast (mode 3)::
1476
1477   testpmd> set bonding mode 3 10
1478
1479set bonding primary
1480~~~~~~~~~~~~~~~~~~~
1481
1482Set an Ethernet slave device as the primary device on a Link Bonding device::
1483
1484   testpmd> set bonding primary (slave id) (port id)
1485
1486For example, to set the Ethernet slave device (port 6) as the primary port of a Link Bonding device (port 10)::
1487
1488   testpmd> set bonding primary 6 10
1489
1490set bonding mac
1491~~~~~~~~~~~~~~~
1492
1493Set the MAC address of a Link Bonding device::
1494
1495   testpmd> set bonding mac (port id) (mac)
1496
1497For example, to set the MAC address of a Link Bonding device (port 10) to 00:00:00:00:00:01::
1498
1499   testpmd> set bonding mac 10 00:00:00:00:00:01
1500
1501set bonding xmit_balance_policy
1502~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1503
1504Set the transmission policy for a Link Bonding device when it is in Balance XOR mode::
1505
1506   testpmd> set bonding xmit_balance_policy (port_id) (l2|l23|l34)
1507
1508For example, set a Link Bonding device (port 10) to use a balance policy of layer 3+4 (IP addresses & UDP ports)::
1509
1510   testpmd> set bonding xmit_balance_policy 10 l34
1511
1512
1513set bonding mon_period
1514~~~~~~~~~~~~~~~~~~~~~~
1515
1516Set the link status monitoring polling period in milliseconds for a bonding device.
1517
1518This adds support for PMD slave devices which do not support link status interrupts.
1519When the mon_period is set to a value greater than 0 then all PMD's which do not support
1520link status ISR will be queried every polling interval to check if their link status has changed::
1521
1522   testpmd> set bonding mon_period (port_id) (value)
1523
1524For example, to set the link status monitoring polling period of bonded device (port 5) to 150ms::
1525
1526   testpmd> set bonding mon_period 5 150
1527
1528
1529show bonding config
1530~~~~~~~~~~~~~~~~~~~
1531
1532Show the current configuration of a Link Bonding device::
1533
1534   testpmd> show bonding config (port id)
1535
1536For example,
1537to show the configuration a Link Bonding device (port 9) with 3 slave devices (1, 3, 4)
1538in balance mode with a transmission policy of layer 2+3::
1539
1540   testpmd> show bonding config 9
1541        Bonding mode: 2
1542        Balance Xmit Policy: BALANCE_XMIT_POLICY_LAYER23
1543        Slaves (3): [1 3 4]
1544        Active Slaves (3): [1 3 4]
1545        Primary: [3]
1546
1547
1548Register Functions
1549------------------
1550
1551The Register Functions can be used to read from and write to registers on the network card referenced by a port number.
1552This is mainly useful for debugging purposes.
1553Reference should be made to the appropriate datasheet for the network card for details on the register addresses
1554and fields that can be accessed.
1555
1556read reg
1557~~~~~~~~
1558
1559Display the value of a port register::
1560
1561   testpmd> read reg (port_id) (address)
1562
1563For example, to examine the Flow Director control register (FDIRCTL, 0x0000EE000) on an Intel 82599 10 GbE Controller::
1564
1565   testpmd> read reg 0 0xEE00
1566   port 0 PCI register at offset 0xEE00: 0x4A060029 (1241907241)
1567
1568read regfield
1569~~~~~~~~~~~~~
1570
1571Display a port register bit field::
1572
1573   testpmd> read regfield (port_id) (address) (bit_x) (bit_y)
1574
1575For example, reading the lowest two bits from the register in the example above::
1576
1577   testpmd> read regfield 0 0xEE00 0 1
1578   port 0 PCI register at offset 0xEE00: bits[0, 1]=0x1 (1)
1579
1580read regbit
1581~~~~~~~~~~~
1582
1583Display a single port register bit::
1584
1585   testpmd> read regbit (port_id) (address) (bit_x)
1586
1587For example, reading the lowest bit from the register in the example above::
1588
1589   testpmd> read regbit 0 0xEE00 0
1590   port 0 PCI register at offset 0xEE00: bit 0=1
1591
1592write reg
1593~~~~~~~~~
1594
1595Set the value of a port register::
1596
1597   testpmd> write reg (port_id) (address) (value)
1598
1599For example, to clear a register::
1600
1601   testpmd> write reg 0 0xEE00 0x0
1602   port 0 PCI register at offset 0xEE00: 0x00000000 (0)
1603
1604write regfield
1605~~~~~~~~~~~~~~
1606
1607Set bit field of a port register::
1608
1609   testpmd> write regfield (port_id) (address) (bit_x) (bit_y) (value)
1610
1611For example, writing to the register cleared in the example above::
1612
1613   testpmd> write regfield 0 0xEE00 0 1 2
1614   port 0 PCI register at offset 0xEE00: 0x00000002 (2)
1615
1616write regbit
1617~~~~~~~~~~~~
1618
1619Set single bit value of a port register::
1620
1621   testpmd> write regbit (port_id) (address) (bit_x) (value)
1622
1623For example, to set the high bit in the register from the example above::
1624
1625   testpmd> write regbit 0 0xEE00 31 1
1626   port 0 PCI register at offset 0xEE00: 0x8000000A (2147483658)
1627
1628
1629Filter Functions
1630----------------
1631
1632This section details the available filter functions that are available.
1633
1634ethertype_filter
1635~~~~~~~~~~~~~~~~~~~~
1636
1637Add or delete a L2 Ethertype filter, which identify packets by their L2 Ethertype mainly assign them to a receive queue::
1638
1639   ethertype_filter (port_id) (add|del) (mac_addr|mac_ignr) (mac_address) \
1640                    ethertype (ether_type) (drop|fwd) queue (queue_id)
1641
1642The available information parameters are:
1643
1644* ``port_id``: The port which the Ethertype filter assigned on.
1645
1646* ``mac_addr``: Compare destination mac address.
1647
1648* ``mac_ignr``: Ignore destination mac address match.
1649
1650* ``mac_address``: Destination mac address to match.
1651
1652* ``ether_type``: The EtherType value want to match,
1653  for example 0x0806 for ARP packet. 0x0800 (IPv4) and 0x86DD (IPv6) are invalid.
1654
1655* ``queue_id``: The receive queue associated with this EtherType filter.
1656  It is meaningless when deleting or dropping.
1657
1658Example, to add/remove an ethertype filter rule::
1659
1660   testpmd> ethertype_filter 0 add mac_ignr 00:11:22:33:44:55 \
1661                             ethertype 0x0806 fwd queue 3
1662
1663   testpmd> ethertype_filter 0 del mac_ignr 00:11:22:33:44:55 \
1664                             ethertype 0x0806 fwd queue 3
1665
16662tuple_filter
1667~~~~~~~~~~~~~~~~~
1668
1669Add or delete a 2-tuple filter,
1670which identifies packets by specific protocol and destination TCP/UDP port
1671and forwards packets into one of the receive queues::
1672
1673   2tuple_filter (port_id) (add|del) dst_port (dst_port_value) \
1674                 protocol (protocol_value) mask (mask_value) \
1675                 tcp_flags (tcp_flags_value) priority (prio_value) \
1676                 queue (queue_id)
1677
1678The available information parameters are:
1679
1680* ``port_id``: The port which the 2-tuple filter assigned on.
1681
1682* ``dst_port_value``: Destination port in L4.
1683
1684* ``protocol_value``: IP L4 protocol.
1685
1686* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate.
1687
1688* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the pro_value is not set to 0x06 (TCP).
1689
1690* ``prio_value``: Priority of this filter.
1691
1692* ``queue_id``: The receive queue associated with this 2-tuple filter.
1693
1694Example, to add/remove an 2tuple filter rule::
1695
1696   testpmd> 2tuple_filter 0 add dst_port 32 protocol 0x06 mask 0x03 \
1697                          tcp_flags 0x02 priority 3 queue 3
1698
1699   testpmd> 2tuple_filter 0 del dst_port 32 protocol 0x06 mask 0x03 \
1700                          tcp_flags 0x02 priority 3 queue 3
1701
17025tuple_filter
1703~~~~~~~~~~~~~~~~~
1704
1705Add or delete a 5-tuple filter,
1706which consists of a 5-tuple (protocol, source and destination IP addresses, source and destination TCP/UDP/SCTP port)
1707and routes packets into one of the receive queues::
1708
1709   5tuple_filter (port_id) (add|del) dst_ip (dst_address) src_ip \
1710                 (src_address) dst_port (dst_port_value) \
1711                 src_port (src_port_value) protocol (protocol_value) \
1712                 mask (mask_value) tcp_flags (tcp_flags_value) \
1713                 priority (prio_value) queue (queue_id)
1714
1715The available information parameters are:
1716
1717* ``port_id``: The port which the 5-tuple filter assigned on.
1718
1719* ``dst_address``: Destination IP address.
1720
1721* ``src_address``: Source IP address.
1722
1723* ``dst_port_value``: TCP/UDP destination port.
1724
1725* ``src_port_value``: TCP/UDP source port.
1726
1727* ``protocol_value``: L4 protocol.
1728
1729* ``mask_value``: Participates in the match or not by bit for field above, 1b means participate
1730
1731* ``tcp_flags_value``: TCP control bits. The non-zero value is invalid, when the protocol_value is not set to 0x06 (TCP).
1732
1733* ``prio_value``: The priority of this filter.
1734
1735* ``queue_id``: The receive queue associated with this 5-tuple filter.
1736
1737Example, to add/remove an 5tuple filter rule::
1738
1739   testpmd> 5tuple_filter 0 add dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1740            dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1741            flags 0x0 priority 3 queue 3
1742
1743   testpmd> 5tuple_filter 0 del dst_ip 2.2.2.5 src_ip 2.2.2.4 \
1744            dst_port 64 src_port 32 protocol 0x06 mask 0x1F \
1745            flags 0x0 priority 3 queue 3
1746
1747syn_filter
1748~~~~~~~~~~
1749
1750Using the  SYN filter, TCP packets whose *SYN* flag is set can be forwarded to a separate queue::
1751
1752   syn_filter (port_id) (add|del) priority (high|low) queue (queue_id)
1753
1754The available information parameters are:
1755
1756* ``port_id``: The port which the SYN filter assigned on.
1757
1758* ``high``: This SYN filter has higher priority than other filters.
1759
1760* ``low``: This SYN filter has lower priority than other filters.
1761
1762* ``queue_id``: The receive queue associated with this SYN filter
1763
1764Example::
1765
1766   testpmd> syn_filter 0 add priority high queue 3
1767
1768flex_filter
1769~~~~~~~~~~~
1770
1771With flex filter, packets can be recognized by any arbitrary pattern within the first 128 bytes of the packet
1772and routed into one of the receive queues::
1773
1774   flex_filter (port_id) (add|del) len (len_value) bytes (bytes_value) \
1775               mask (mask_value) priority (prio_value) queue (queue_id)
1776
1777The available information parameters are:
1778
1779* ``port_id``: The port which the Flex filter is assigned on.
1780
1781* ``len_value``: Filter length in bytes, no greater than 128.
1782
1783* ``bytes_value``: A string in hexadecimal, means the value the flex filter needs to match.
1784
1785* ``mask_value``: A string in hexadecimal, bit 1 means corresponding byte participates in the match.
1786
1787* ``prio_value``: The priority of this filter.
1788
1789* ``queue_id``: The receive queue associated with this Flex filter.
1790
1791Example::
1792
1793   testpmd> flex_filter 0 add len 16 bytes 0x00000000000000000000000008060000 \
1794                          mask 000C priority 3 queue 3
1795
1796   testpmd> flex_filter 0 del len 16 bytes 0x00000000000000000000000008060000 \
1797                          mask 000C priority 3 queue 3
1798
1799
1800.. _testpmd_flow_director:
1801
1802flow_director_filter
1803~~~~~~~~~~~~~~~~~~~~
1804
1805The Flow Director works in receive mode to identify specific flows or sets of flows and route them to specific queues.
1806
1807Four types of filtering are supported which are referred to as Perfect Match, Signature, Perfect-mac-vlan and
1808Perfect-tunnel filters, the match mode is set by the ``--pkt-filter-mode`` command-line parameter:
1809
1810* Perfect match filters.
1811  The hardware checks a match between the masked fields of the received packets and the programmed filters.
1812  The masked fields are for IP flow.
1813
1814* Signature filters.
1815  The hardware checks a match between a hash-based signature of the masked fields of the received packet.
1816
1817* Perfect-mac-vlan match filters.
1818  The hardware checks a match between the masked fields of the received packets and the programmed filters.
1819  The masked fields are for MAC VLAN flow.
1820
1821* Perfect-tunnel match filters.
1822  The hardware checks a match between the masked fields of the received packets and the programmed filters.
1823  The masked fields are for tunnel flow.
1824
1825The Flow Director filters can match the different fields for different type of packet: flow type, specific input set
1826per flow type and the flexible payload.
1827
1828The Flow Director can also mask out parts of all of these fields so that filters
1829are only applied to certain fields or parts of the fields.
1830
1831Different NICs may have different capabilities, command show port fdir (port_id) can be used to acquire the information.
1832
1833# Commands to add flow director filters of different flow types::
1834
1835   flow_director_filter (port_id) mode IP (add|del|update) \
1836                        flow (ipv4-other|ipv4-frag|ipv6-other|ipv6-frag) \
1837                        src (src_ip_address) dst (dst_ip_address) \
1838                        tos (tos_value) proto (proto_value) ttl (ttl_value) \
1839                        vlan (vlan_value) flexbytes (flexbytes_value) \
1840                        (drop|fwd) pf|vf(vf_id) queue (queue_id) \
1841                        fd_id (fd_id_value)
1842
1843   flow_director_filter (port_id) mode IP (add|del|update) \
1844                        flow (ipv4-tcp|ipv4-udp|ipv6-tcp|ipv6-udp) \
1845                        src (src_ip_address) (src_port) \
1846                        dst (dst_ip_address) (dst_port) \
1847                        tos (tos_value) ttl (ttl_value) \
1848                        vlan (vlan_value) flexbytes (flexbytes_value) \
1849                        (drop|fwd) queue pf|vf(vf_id) (queue_id) \
1850                        fd_id (fd_id_value)
1851
1852   flow_director_filter (port_id) mode IP (add|del|update) \
1853                        flow (ipv4-sctp|ipv6-sctp) \
1854                        src (src_ip_address) (src_port) \
1855                        dst (dst_ip_address) (dst_port) \
1856                        tos (tos_value) ttl (ttl_value) \
1857                        tag (verification_tag) vlan (vlan_value) \
1858                        flexbytes (flexbytes_value) (drop|fwd) \
1859                        pf|vf(vf_id) queue (queue_id) fd_id (fd_id_value)
1860
1861   flow_director_filter (port_id) mode IP (add|del|update) flow l2_payload \
1862                        ether (ethertype) flexbytes (flexbytes_value) \
1863                        (drop|fwd) pf|vf(vf_id) queue (queue_id)
1864                        fd_id (fd_id_value)
1865
1866   flow_director_filter (port_id) mode MAC-VLAN (add|del|update) \
1867                        mac (mac_address) vlan (vlan_value) \
1868                        flexbytes (flexbytes_value) (drop|fwd) \
1869                        queue (queue_id) fd_id (fd_id_value)
1870
1871   flow_director_filter (port_id) mode Tunnel (add|del|update) \
1872                        mac (mac_address) vlan (vlan_value) \
1873                        tunnel (NVGRE|VxLAN) tunnel-id (tunnel_id_value) \
1874                        flexbytes (flexbytes_value) (drop|fwd) \
1875                        queue (queue_id) fd_id (fd_id_value)
1876
1877For example, to add an ipv4-udp flow type filter::
1878
1879   testpmd> flow_director_filter 0 mode IP add flow ipv4-udp src 2.2.2.3 32 \
1880            dst 2.2.2.5 33 tos 2 ttl 40 vlan 0x1 flexbytes (0x88,0x48) \
1881            fwd pf queue 1 fd_id 1
1882
1883For example, add an ipv4-other flow type filter::
1884
1885   testpmd> flow_director_filter 0 mode IP add flow ipv4-other src 2.2.2.3 \
1886             dst 2.2.2.5 tos 2 proto 20 ttl 40 vlan 0x1 \
1887             flexbytes (0x88,0x48) fwd pf queue 1 fd_id 1
1888
1889flush_flow_director
1890~~~~~~~~~~~~~~~~~~~
1891
1892Flush all flow director filters on a device::
1893
1894   testpmd> flush_flow_director (port_id)
1895
1896Example, to flush all flow director filter on port 0::
1897
1898   testpmd> flush_flow_director 0
1899
1900flow_director_mask
1901~~~~~~~~~~~~~~~~~~
1902
1903Set flow director's input masks::
1904
1905   flow_director_mask (port_id) mode IP vlan (vlan_value) \
1906                      src_mask (ipv4_src) (ipv6_src) (src_port) \
1907                      dst_mask (ipv4_dst) (ipv6_dst) (dst_port)
1908
1909   flow_director_mask (port_id) mode MAC-VLAN vlan (vlan_value)
1910
1911   flow_director_mask (port_id) mode Tunnel vlan (vlan_value) \
1912                      mac (mac_value) tunnel-type (tunnel_type_value) \
1913                      tunnel-id (tunnel_id_value)
1914
1915Example, to set flow director mask on port 0::
1916
1917   testpmd> flow_director_mask 0 mode IP vlan 0xefff \
1918            src_mask 255.255.255.255 \
1919                FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF \
1920            dst_mask 255.255.255.255 \
1921                FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF 0xFFFF
1922
1923flow_director_flex_mask
1924~~~~~~~~~~~~~~~~~~~~~~~
1925
1926set masks of flow director's flexible payload based on certain flow type::
1927
1928   testpmd> flow_director_flex_mask (port_id) \
1929            flow (none|ipv4-other|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
1930                  ipv6-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp| \
1931                  l2_payload|all) (mask)
1932
1933Example, to set flow director's flex mask for all flow type on port 0::
1934
1935   testpmd> flow_director_flex_mask 0 flow all \
1936            (0xff,0xff,0,0,0,0,0,0,0,0,0,0,0,0,0,0)
1937
1938
1939flow_director_flex_payload
1940~~~~~~~~~~~~~~~~~~~~~~~~~~
1941
1942Configure flexible payload selection::
1943
1944   flow_director_flex_payload (port_id) (raw|l2|l3|l4) (config)
1945
1946For example, to select the first 16 bytes from the offset 4 (bytes) of packet's payload as flexible payload::
1947
1948   testpmd> flow_director_flex_payload 0 l4 \
1949            (4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)
1950
1951get_sym_hash_ena_per_port
1952~~~~~~~~~~~~~~~~~~~~~~~~~
1953
1954Get symmetric hash enable configuration per port::
1955
1956   get_sym_hash_ena_per_port (port_id)
1957
1958For example, to get symmetric hash enable configuration of port 1::
1959
1960   testpmd> get_sym_hash_ena_per_port 1
1961
1962set_sym_hash_ena_per_port
1963~~~~~~~~~~~~~~~~~~~~~~~~~
1964
1965Set symmetric hash enable configuration per port to enable or disable::
1966
1967   set_sym_hash_ena_per_port (port_id) (enable|disable)
1968
1969For example, to set symmetric hash enable configuration of port 1 to enable::
1970
1971   testpmd> set_sym_hash_ena_per_port 1 enable
1972
1973get_hash_global_config
1974~~~~~~~~~~~~~~~~~~~~~~
1975
1976Get the global configurations of hash filters::
1977
1978   get_hash_global_config (port_id)
1979
1980For example, to get the global configurations of hash filters of port 1::
1981
1982   testpmd> get_hash_global_config 1
1983
1984set_hash_global_config
1985~~~~~~~~~~~~~~~~~~~~~~
1986
1987Set the global configurations of hash filters::
1988
1989   set_hash_global_config (port_id) (toeplitz|simple_xor|default) \
1990   (ipv4|ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp|ipv4-other|ipv6|ipv6-frag| \
1991   ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other|l2_payload) \
1992   (enable|disable)
1993
1994For example, to enable simple_xor for flow type of ipv6 on port 2::
1995
1996   testpmd> set_hash_global_config 2 simple_xor ipv6 enable
1997
1998set_hash_input_set
1999~~~~~~~~~~~~~~~~~~
2000
2001Set the input set for hash::
2002
2003   set_hash_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2004   ipv4-other|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2005   l2_payload) (ovlan|ivlan|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2006   ipv4-proto|ipv6-tc|ipv6-next-header|udp-src-port|udp-dst-port| \
2007   tcp-src-port|tcp-dst-port|sctp-src-port|sctp-dst-port|sctp-veri-tag| \
2008   udp-key|gre-key|fld-1st|fld-2nd|fld-3rd|fld-4th|fld-5th|fld-6th|fld-7th| \
2009   fld-8th|none) (select|add)
2010
2011For example, to add source IP to hash input set for flow type of ipv4-udp on port 0::
2012
2013   testpmd> set_hash_input_set 0 ipv4-udp src-ipv4 add
2014
2015set_fdir_input_set
2016~~~~~~~~~~~~~~~~~~
2017
2018The Flow Director filters can match the different fields for different type of packet, i.e. specific input set
2019on per flow type and the flexible payload. This command can be used to change input set for each flow type.
2020
2021Set the input set for flow director::
2022
2023   set_fdir_input_set (port_id) (ipv4-frag|ipv4-tcp|ipv4-udp|ipv4-sctp| \
2024   ipv4-other|ipv6|ipv6-frag|ipv6-tcp|ipv6-udp|ipv6-sctp|ipv6-other| \
2025   l2_payload) (ivlan|ethertype|src-ipv4|dst-ipv4|src-ipv6|dst-ipv6|ipv4-tos| \
2026   ipv4-proto|ipv4-ttl|ipv6-tc|ipv6-next-header|ipv6-hop-limits| \
2027   tudp-src-port|udp-dst-port|cp-src-port|tcp-dst-port|sctp-src-port| \
2028   sctp-dst-port|sctp-veri-tag|none) (select|add)
2029
2030For example to add source IP to FD input set for flow type of ipv4-udp on port 0::
2031
2032   testpmd> set_fdir_input_set 0 ipv4-udp src-ipv4 add
2033
2034global_config
2035~~~~~~~~~~~~~
2036
2037Set different GRE key length for input set::
2038
2039   global_config (port_id) gre-key-len (number in bytes)
2040
2041For example to set GRE key length for input set to 4 bytes on port 0::
2042
2043   testpmd> global_config 0 gre-key-len 4
2044