net/ixgbe: fix flow control mode setting
[dpdk.git] / doc / guides / nics / cxgbe.rst
1 .. SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2014-2018 Chelsio Communications.
3    All rights reserved.
4
5 CXGBE Poll Mode Driver
6 ======================
7
8 The CXGBE PMD (**librte_pmd_cxgbe**) provides poll mode driver support
9 for **Chelsio Terminator** 10/25/40/100 Gbps family of adapters. CXGBE PMD
10 has support for the latest Linux and FreeBSD operating systems.
11
12 CXGBEVF PMD provides poll mode driver support for SR-IOV Virtual functions
13 and has support for the latest Linux operating systems.
14
15 More information can be found at `Chelsio Communications Official Website
16 <http://www.chelsio.com>`_.
17
18 Features
19 --------
20
21 CXGBE and CXGBEVF PMD has support for:
22
23 - Multiple queues for TX and RX
24 - Receiver Side Steering (RSS)
25   Receiver Side Steering (RSS) on IPv4, IPv6, IPv4-TCP/UDP, IPv6-TCP/UDP.
26   For 4-tuple, enabling 'RSS on TCP' and 'RSS on TCP + UDP' is supported.
27 - VLAN filtering
28 - Checksum offload
29 - Promiscuous mode
30 - All multicast mode
31 - Port hardware statistics
32 - Jumbo frames
33 - Flow API - Support for both Wildcard (LE-TCAM) and Exact (HASH) match filters.
34
35 Limitations
36 -----------
37
38 The Chelsio Terminator series of devices provide two/four ports but
39 expose a single PCI bus address, thus, librte_pmd_cxgbe registers
40 itself as a PCI driver that allocates one Ethernet device per detected
41 port.
42
43 For this reason, one cannot whitelist/blacklist a single port without
44 whitelisting/blacklisting the other ports on the same device.
45
46 .. _t5-nics:
47
48 Supported Chelsio T5 NICs
49 -------------------------
50
51 - 1G NICs: T502-BT
52 - 10G NICs: T520-BT, T520-CR, T520-LL-CR, T520-SO-CR, T540-CR
53 - 40G NICs: T580-CR, T580-LP-CR, T580-SO-CR
54 - Other T5 NICs: T522-CR
55
56 .. _t6-nics:
57
58 Supported Chelsio T6 NICs
59 -------------------------
60
61 - 25G NICs: T6425-CR, T6225-CR, T6225-LL-CR, T6225-SO-CR
62 - 100G NICs: T62100-CR, T62100-LP-CR, T62100-SO-CR
63
64 Supported SR-IOV Chelsio NICs
65 -----------------------------
66
67 SR-IOV virtual functions are supported on all the Chelsio NICs listed
68 in :ref:`t5-nics` and :ref:`t6-nics`.
69
70 Prerequisites
71 -------------
72
73 - Requires firmware version **1.23.4.0** and higher. Visit
74   `Chelsio Download Center <http://service.chelsio.com>`_ to get latest firmware
75   bundled with the latest Chelsio Unified Wire package.
76
77   For Linux, installing and loading the latest cxgb4 kernel driver from the
78   Chelsio Unified Wire package should get you the latest firmware. More
79   information can be obtained from the User Guide that is bundled with the
80   Chelsio Unified Wire package.
81
82   For FreeBSD, the latest firmware obtained from the Chelsio Unified Wire
83   package must be manually flashed via cxgbetool available in FreeBSD source
84   repository.
85
86   Instructions on how to manually flash the firmware are given in section
87   :ref:`linux-installation` for Linux and section :ref:`freebsd-installation`
88   for FreeBSD.
89
90 Pre-Installation Configuration
91 ------------------------------
92
93 Config File Options
94 ~~~~~~~~~~~~~~~~~~~
95
96 The following options can be modified in the ``.config`` file. Please note that
97 enabling debugging options may affect system performance.
98
99 - ``CONFIG_RTE_LIBRTE_CXGBE_PMD`` (default **y**)
100
101   Toggle compilation of librte_pmd_cxgbe driver.
102
103   .. note::
104
105      This controls compilation of both CXGBE and CXGBEVF PMD.
106
107 Runtime Options
108 ~~~~~~~~~~~~~~~
109
110 The following ``devargs`` options can be enabled at runtime. They must
111 be passed as part of EAL arguments. For example,
112
113 .. code-block:: console
114
115    testpmd -w 02:00.4,keep_ovlan=1 -- -i
116
117 Common Runtime Options
118 ^^^^^^^^^^^^^^^^^^^^^^
119
120 - ``keep_ovlan`` (default **0**)
121
122   Toggle behavior to keep/strip outer VLAN in Q-in-Q packets. If
123   enabled, the outer VLAN tag is preserved in Q-in-Q packets. Otherwise,
124   the outer VLAN tag is stripped in Q-in-Q packets.
125
126 - ``tx_mode_latency`` (default **0**)
127
128   When set to 1, Tx doesn't wait for max number of packets to get
129   coalesced and sends the packets immediately at the end of the
130   current Tx burst. When set to 0, Tx waits across multiple Tx bursts
131   until the max number of packets have been coalesced. In this case,
132   Tx only sends the coalesced packets to hardware once the max
133   coalesce limit has been reached.
134
135 CXGBE VF Only Runtime Options
136 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
137
138 - ``force_link_up`` (default **0**)
139
140   When set to 1, CXGBEVF PMD always forces link as up for all VFs on
141   underlying Chelsio NICs. This enables multiple VFs on the same NIC
142   to send traffic to each other even when the physical link is down.
143
144 .. _driver-compilation:
145
146 Driver compilation and testing
147 ------------------------------
148
149 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
150 for details.
151
152 Linux
153 -----
154
155 .. _linux-installation:
156
157 Linux Installation
158 ~~~~~~~~~~~~~~~~~~
159
160 Steps to manually install the latest firmware from the downloaded Chelsio
161 Unified Wire package for Linux operating system are as follows:
162
163 #. Load the kernel module:
164
165    .. code-block:: console
166
167       modprobe cxgb4
168
169 #. Use ifconfig to get the interface name assigned to Chelsio card:
170
171    .. code-block:: console
172
173       ifconfig -a | grep "00:07:43"
174
175    Example output:
176
177    .. code-block:: console
178
179       p1p1      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C0
180       p1p2      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C8
181
182 #. Install cxgbtool:
183
184    .. code-block:: console
185
186       cd <path_to_uwire>/tools/cxgbtool
187       make install
188
189 #. Use cxgbtool to load the firmware config file onto the card:
190
191    .. code-block:: console
192
193       cxgbtool p1p1 loadcfg <path_to_uwire>/src/network/firmware/t5-config.txt
194
195 #. Use cxgbtool to load the firmware image onto the card:
196
197    .. code-block:: console
198
199       cxgbtool p1p1 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
200
201 #. Unload and reload the kernel module:
202
203    .. code-block:: console
204
205       modprobe -r cxgb4
206       modprobe cxgb4
207
208 #. Verify with ethtool:
209
210    .. code-block:: console
211
212       ethtool -i p1p1 | grep "firmware"
213
214    Example output:
215
216    .. code-block:: console
217
218       firmware-version: 1.23.4.0, TP 0.1.23.2
219
220 Running testpmd
221 ~~~~~~~~~~~~~~~
222
223 This section demonstrates how to launch **testpmd** with Chelsio
224 devices managed by librte_pmd_cxgbe in Linux operating system.
225
226 #. Load the kernel module:
227
228    .. code-block:: console
229
230       modprobe cxgb4
231
232 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
233
234    .. code-block:: console
235
236       dmesg | tail -2
237
238    Example output:
239
240    .. code-block:: console
241
242       cxgb4 0000:02:00.4 p1p1: renamed from eth0
243       cxgb4 0000:02:00.4 p1p2: renamed from eth1
244
245    .. note::
246
247       Both the interfaces of a Chelsio 2-port adapter are bound to the
248       same PCI bus address.
249
250 #. Unload the kernel module:
251
252    .. code-block:: console
253
254       modprobe -ar cxgb4 csiostor
255
256 #. Running testpmd
257
258    Follow instructions available in the document
259    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
260    to run testpmd.
261
262    .. note::
263
264       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio NICs.
265
266    Example output:
267
268    .. code-block:: console
269
270       [...]
271       EAL: PCI device 0000:02:00.4 on NUMA socket -1
272       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
273       EAL:   PCI memory mapped at 0x7fd7c0200000
274       EAL:   PCI memory mapped at 0x7fd77cdfd000
275       EAL:   PCI memory mapped at 0x7fd7c10b7000
276       PMD: rte_cxgbe_pmd: fw: 1.23.4.0, TP: 0.1.23.2
277       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
278       Interactive-mode selected
279       Configuring Port 0 (socket 0)
280       Port 0: 00:07:43:2D:EA:C0
281       Configuring Port 1 (socket 0)
282       Port 1: 00:07:43:2D:EA:C8
283       Checking link statuses...
284       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
285       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
286       Port 0 Link Up - speed 10000 Mbps - full-duplex
287       Port 1 Link Up - speed 10000 Mbps - full-duplex
288       Done
289       testpmd>
290
291    .. note::
292
293       Flow control pause TX/RX is disabled by default and can be enabled via
294       testpmd. Refer section :ref:`flow-control` for more details.
295
296 Configuring SR-IOV Virtual Functions
297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
298
299 This section demonstrates how to enable SR-IOV virtual functions
300 on Chelsio NICs and demonstrates how to run testpmd with SR-IOV
301 virtual functions.
302
303 #. Load the kernel module:
304
305    .. code-block:: console
306
307       modprobe cxgb4
308
309 #. Get the PCI bus addresses of the interfaces bound to cxgb4 driver:
310
311    .. code-block:: console
312
313       dmesg | tail -2
314
315    Example output:
316
317    .. code-block:: console
318
319       cxgb4 0000:02:00.4 p1p1: renamed from eth0
320       cxgb4 0000:02:00.4 p1p2: renamed from eth1
321
322    .. note::
323
324       Both the interfaces of a Chelsio 2-port adapter are bound to the
325       same PCI bus address.
326
327 #. Use ifconfig to get the interface name assigned to Chelsio card:
328
329    .. code-block:: console
330
331       ifconfig -a | grep "00:07:43"
332
333    Example output:
334
335    .. code-block:: console
336
337       p1p1      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C0
338       p1p2      Link encap:Ethernet  HWaddr 00:07:43:2D:EA:C8
339
340 #. Bring up the interfaces:
341
342    .. code-block:: console
343
344       ifconfig p1p1 up
345       ifconfig p1p2 up
346
347 #. Instantiate SR-IOV Virtual Functions. PF0..3 can be used for
348    SR-IOV VFs. Multiple VFs can be instantiated on each of PF0..3.
349    To instantiate one SR-IOV VF on each PF0 and PF1:
350
351    .. code-block:: console
352
353       echo 1 > /sys/bus/pci/devices/0000\:02\:00.0/sriov_numvfs
354       echo 1 > /sys/bus/pci/devices/0000\:02\:00.1/sriov_numvfs
355
356 #. Get the PCI bus addresses of the virtual functions:
357
358    .. code-block:: console
359
360       lspci | grep -i "Chelsio" | grep -i "VF"
361
362    Example output:
363
364    .. code-block:: console
365
366       02:01.0 Ethernet controller: Chelsio Communications Inc T540-CR Unified Wire Ethernet Controller [VF]
367       02:01.1 Ethernet controller: Chelsio Communications Inc T540-CR Unified Wire Ethernet Controller [VF]
368
369 #. Running testpmd
370
371    Follow instructions available in the document
372    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
373    to bind virtual functions and run testpmd.
374
375    Example output:
376
377    .. code-block:: console
378
379       [...]
380       EAL: PCI device 0000:02:01.0 on NUMA socket 0
381       EAL:   probe driver: 1425:5803 net_cxgbevf
382       PMD: rte_cxgbe_pmd: Firmware version: 1.23.4.0
383       PMD: rte_cxgbe_pmd: TP Microcode version: 0.1.23.2
384       PMD: rte_cxgbe_pmd: Chelsio rev 0
385       PMD: rte_cxgbe_pmd: No bootstrap loaded
386       PMD: rte_cxgbe_pmd: No Expansion ROM loaded
387       PMD: rte_cxgbe_pmd:  0000:02:01.0 Chelsio rev 0 1G/10GBASE-SFP
388       EAL: PCI device 0000:02:01.1 on NUMA socket 0
389       EAL:   probe driver: 1425:5803 net_cxgbevf
390       PMD: rte_cxgbe_pmd: Firmware version: 1.23.4.0
391       PMD: rte_cxgbe_pmd: TP Microcode version: 0.1.23.2
392       PMD: rte_cxgbe_pmd: Chelsio rev 0
393       PMD: rte_cxgbe_pmd: No bootstrap loaded
394       PMD: rte_cxgbe_pmd: No Expansion ROM loaded
395       PMD: rte_cxgbe_pmd:  0000:02:01.1 Chelsio rev 0 1G/10GBASE-SFP
396       Configuring Port 0 (socket 0)
397       Port 0: 06:44:29:44:40:00
398       Configuring Port 1 (socket 0)
399       Port 1: 06:44:29:44:40:10
400       Checking link statuses...
401       Done
402       testpmd>
403
404 FreeBSD
405 -------
406
407 .. _freebsd-installation:
408
409 FreeBSD Installation
410 ~~~~~~~~~~~~~~~~~~~~
411
412 Steps to manually install the latest firmware from the downloaded Chelsio
413 Unified Wire package for FreeBSD operating system are as follows:
414
415 #. Load the kernel module:
416
417    .. code-block:: console
418
419       kldload if_cxgbe
420
421 #. Use dmesg to get the t5nex instance assigned to the Chelsio card:
422
423    .. code-block:: console
424
425       dmesg | grep "t5nex"
426
427    Example output:
428
429    .. code-block:: console
430
431       t5nex0: <Chelsio T520-CR> irq 16 at device 0.4 on pci2
432       cxl0: <port 0> on t5nex0
433       cxl1: <port 1> on t5nex0
434       t5nex0: PCIe x8, 2 ports, 14 MSI-X interrupts, 31 eq, 13 iq
435
436    In the example above, a Chelsio T520-CR card is bound to a t5nex0 instance.
437
438 #. Install cxgbetool from FreeBSD source repository:
439
440    .. code-block:: console
441
442       cd <path_to_FreeBSD_source>/tools/tools/cxgbetool/
443       make && make install
444
445 #. Use cxgbetool to load the firmware image onto the card:
446
447    .. code-block:: console
448
449       cxgbetool t5nex0 loadfw <path_to_uwire>/src/network/firmware/t5fw-*.bin
450
451 #. Unload and reload the kernel module:
452
453    .. code-block:: console
454
455       kldunload if_cxgbe
456       kldload if_cxgbe
457
458 #. Verify with sysctl:
459
460    .. code-block:: console
461
462       sysctl -a | grep "t5nex" | grep "firmware"
463
464    Example output:
465
466    .. code-block:: console
467
468       dev.t5nex.0.firmware_version: 1.23.4.0
469
470 Running testpmd
471 ~~~~~~~~~~~~~~~
472
473 This section demonstrates how to launch **testpmd** with Chelsio
474 devices managed by librte_pmd_cxgbe in FreeBSD operating system.
475
476 #. Change to DPDK source directory where the target has been compiled in
477    section :ref:`driver-compilation`:
478
479    .. code-block:: console
480
481       cd <DPDK-source-directory>
482
483 #. Copy the contigmem kernel module to /boot/kernel directory:
484
485    .. code-block:: console
486
487       cp x86_64-native-freebsd-clang/kmod/contigmem.ko /boot/kernel/
488
489 #. Add the following lines to /boot/loader.conf:
490
491    .. code-block:: console
492
493       # reserve 2 x 1G blocks of contiguous memory using contigmem driver
494       hw.contigmem.num_buffers=2
495       hw.contigmem.buffer_size=1073741824
496       # load contigmem module during boot process
497       contigmem_load="YES"
498
499    The above lines load the contigmem kernel module during boot process and
500    allocate 2 x 1G blocks of contiguous memory to be used for DPDK later on.
501    This is to avoid issues with potential memory fragmentation during later
502    system up time, which may result in failure of allocating the contiguous
503    memory required for the contigmem kernel module.
504
505 #. Restart the system and ensure the contigmem module is loaded successfully:
506
507    .. code-block:: console
508
509       reboot
510       kldstat | grep "contigmem"
511
512    Example output:
513
514    .. code-block:: console
515
516       2    1 0xffffffff817f1000 3118     contigmem.ko
517
518 #. Repeat step 1 to ensure that you are in the DPDK source directory.
519
520 #. Load the cxgbe kernel module:
521
522    .. code-block:: console
523
524       kldload if_cxgbe
525
526 #. Get the PCI bus addresses of the interfaces bound to t5nex driver:
527
528    .. code-block:: console
529
530       pciconf -l | grep "t5nex"
531
532    Example output:
533
534    .. code-block:: console
535
536       t5nex0@pci0:2:0:4: class=0x020000 card=0x00001425 chip=0x54011425 rev=0x00
537
538    In the above example, the t5nex0 is bound to 2:0:4 bus address.
539
540    .. note::
541
542       Both the interfaces of a Chelsio 2-port adapter are bound to the
543       same PCI bus address.
544
545 #. Unload the kernel module:
546
547    .. code-block:: console
548
549       kldunload if_cxgbe
550
551 #. Set the PCI bus addresses to hw.nic_uio.bdfs kernel environment parameter:
552
553    .. code-block:: console
554
555       kenv hw.nic_uio.bdfs="2:0:4"
556
557    This automatically binds 2:0:4 to nic_uio kernel driver when it is loaded in
558    the next step.
559
560    .. note::
561
562       Currently, CXGBE PMD only supports the binding of PF4 for Chelsio NICs.
563
564 #. Load nic_uio kernel driver:
565
566    .. code-block:: console
567
568       kldload ./x86_64-native-freebsd-clang/kmod/nic_uio.ko
569
570 #. Start testpmd with basic parameters:
571
572    .. code-block:: console
573
574       ./x86_64-native-freebsd-clang/app/testpmd -l 0-3 -n 4 -w 0000:02:00.4 -- -i
575
576    Example output:
577
578    .. code-block:: console
579
580       [...]
581       EAL: PCI device 0000:02:00.4 on NUMA socket 0
582       EAL:   probe driver: 1425:5401 rte_cxgbe_pmd
583       EAL:   PCI memory mapped at 0x8007ec000
584       EAL:   PCI memory mapped at 0x842800000
585       EAL:   PCI memory mapped at 0x80086c000
586       PMD: rte_cxgbe_pmd: fw: 1.23.4.0, TP: 0.1.23.2
587       PMD: rte_cxgbe_pmd: Coming up as MASTER: Initializing adapter
588       Interactive-mode selected
589       Configuring Port 0 (socket 0)
590       Port 0: 00:07:43:2D:EA:C0
591       Configuring Port 1 (socket 0)
592       Port 1: 00:07:43:2D:EA:C8
593       Checking link statuses...
594       PMD: rte_cxgbe_pmd: Port0: passive DA port module inserted
595       PMD: rte_cxgbe_pmd: Port1: passive DA port module inserted
596       Port 0 Link Up - speed 10000 Mbps - full-duplex
597       Port 1 Link Up - speed 10000 Mbps - full-duplex
598       Done
599       testpmd>
600
601 .. note::
602
603    Flow control pause TX/RX is disabled by default and can be enabled via
604    testpmd. Refer section :ref:`flow-control` for more details.
605
606 Sample Application Notes
607 ------------------------
608
609 .. _flow-control:
610
611 Enable/Disable Flow Control
612 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
613
614 Flow control pause TX/RX is disabled by default and can be enabled via
615 testpmd as follows:
616
617 .. code-block:: console
618
619    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 0
620    testpmd> set flow_ctrl rx on tx on 0 0 0 0 mac_ctrl_frame_fwd off autoneg on 1
621
622 To disable again, run:
623
624 .. code-block:: console
625
626    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 0
627    testpmd> set flow_ctrl rx off tx off 0 0 0 0 mac_ctrl_frame_fwd off autoneg off 1
628
629 Jumbo Mode
630 ~~~~~~~~~~
631
632 There are two ways to enable sending and receiving of jumbo frames via testpmd.
633 One method involves using the **mtu** command, which changes the mtu of an
634 individual port without having to stop the selected port. Another method
635 involves stopping all the ports first and then running **max-pkt-len** command
636 to configure the mtu of all the ports with a single command.
637
638 - To configure each port individually, run the mtu command as follows:
639
640   .. code-block:: console
641
642      testpmd> port config mtu 0 9000
643      testpmd> port config mtu 1 9000
644
645 - To configure all the ports at once, stop all the ports first and run the
646   max-pkt-len command as follows:
647
648   .. code-block:: console
649
650      testpmd> port stop all
651      testpmd> port config all max-pkt-len 9000