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