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