New upstream version 17.11.4
[deb_dpdk.git] / doc / guides / nics / qede.rst
1 ..  BSD LICENSE
2     Copyright (c) 2016 QLogic Corporation
3     Copyright (c) 2017 Cavium Inc.
4     All rights reserved.
5
6     Redistribution and use in source and binary forms, with or without
7     modification, are permitted provided that the following conditions
8     are met:
9
10     * Redistributions of source code must retain the above copyright
11     notice, this list of conditions and the following disclaimer.
12     * Redistributions in binary form must reproduce the above copyright
13     notice, this list of conditions and the following disclaimer in
14     the documentation and/or other materials provided with the
15     distribution.
16     * Neither the name of QLogic Corporation nor the names of its
17     contributors may be used to endorse or promote products derived
18     from this software without specific prior written permission.
19
20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31
32 QEDE Poll Mode Driver
33 ======================
34
35 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
36 for **QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)** family of adapters as well as SR-IOV virtual functions (VF). It is supported on
37 several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu.
38 It is compile-tested under FreeBSD OS.
39
40 More information can be found at `QLogic Corporation's Website
41 <http://www.qlogic.com>`_.
42
43 Supported Features
44 ------------------
45
46 - Unicast/Multicast filtering
47 - Promiscuous mode
48 - Allmulti mode
49 - Port hardware statistics
50 - Jumbo frames
51 - Multiple MAC address
52 - MTU change
53 - Default pause flow control
54 - Multiprocess aware
55 - Scatter-Gather
56 - Multiple Rx/Tx queues
57 - RSS (with RETA/hash table/key)
58 - TSS
59 - Stateless checksum offloads (IPv4/IPv6/TCP/UDP)
60 - LRO/TSO
61 - VLAN offload - Filtering and stripping
62 - N-tuple filter and flow director (limited support)
63 - NPAR (NIC Partitioning)
64 - SR-IOV VF
65 - VXLAN tunneling offload
66 - MPLSoUDP Tx tunnel offload
67
68 Non-supported Features
69 ----------------------
70
71 - SR-IOV PF
72 - GENEVE and NVGRE Tunneling offloads
73
74 Supported QLogic Adapters
75 -------------------------
76
77 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)
78
79 Prerequisites
80 -------------
81
82 - Requires storm firmware version **8.30.12.0**. Firmware may be available
83   inbox in certain newer Linux distros under the standard directory
84   ``E.g. /lib/firmware/qed/qed_init_values-8.30.12.0.bin``
85   If the required firmware files are not available then download it from
86   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
87   For downloading firmware file, select adapter category, model and DPDK Poll Mode Driver.
88
89 - Requires the NIC be updated minimally with **8.30.x.x** Management firmware(MFW) version supported for that NIC.
90   It is highly recommended that the NIC be updated with the latest available management firmware version to get latest feature  set.
91   Management Firmware and Firmware Upgrade Utility for Cavium FastLinQ(r) branded adapters can be downloaded from
92   `Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
93   For downloading Firmware Upgrade Utility, select NIC category, model and Linux distro.
94   To update the management firmware, refer to the instructions in the Firmware Upgrade Utility Readme document.
95   For OEM branded adapters please follow the instruction provided by the OEM to update the Management Firmware on the NIC.
96
97 - SR-IOV requires Linux PF driver version **8.20.x.x** or higher.
98   If the required PF driver is not available then download it from
99   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
100   For downloading PF driver, select adapter category, model and Linux distro.
101
102
103 Performance note
104 ~~~~~~~~~~~~~~~~
105
106 - For better performance, it is recommended to use 4K or higher RX/TX rings.
107
108 Config File Options
109 ~~~~~~~~~~~~~~~~~~~
110
111 The following options can be modified in the ``.config`` file. Please note that
112 enabling debugging options may affect system performance.
113
114 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
115
116   Toggle compilation of QEDE PMD driver.
117
118 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_INFO`` (default **n**)
119
120   Toggle display of generic debugging messages.
121
122 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_DRIVER`` (default **n**)
123
124   Toggle display of ecore related messages.
125
126 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
127
128   Toggle display of transmit fast path run-time messages.
129
130 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
131
132   Toggle display of receive fast path run-time messages.
133
134 - ``CONFIG_RTE_LIBRTE_QEDE_VF_TX_SWITCH`` (default **"y"**)
135
136   A knob to control per-VF Tx switching feature.
137
138 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
139
140   Gives absolute path of firmware file.
141   ``Eg: "/lib/firmware/qed/qed_init_values-8.30.12.0.bin"``
142   Empty string indicates driver will pick up the firmware file
143   from the default location /lib/firmware/qed.
144   CAUTION this option is more for custom firmware, it is not
145   recommended for use under normal condition.
146
147 Driver compilation and testing
148 ------------------------------
149
150 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
151 for details.
152
153 SR-IOV: Prerequisites and Sample Application Notes
154 --------------------------------------------------
155
156 This section provides instructions to configure SR-IOV with Linux OS.
157
158 **Note**: librte_pmd_qede will be used to bind to SR-IOV VF device and Linux native kernel driver (qede) will function as SR-IOV PF driver. Requires PF driver to be 8.10.x.x or higher.
159
160 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
161
162    .. code-block:: console
163
164       lspci -s <slot> -vvv
165
166    Example output:
167
168    .. code-block:: console
169
170       [...]
171       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
172       [...]
173       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
174       [...]
175       Kernel driver in use: igb_uio
176
177 #. Load the kernel module:
178
179    .. code-block:: console
180
181       modprobe qede
182
183    Example output:
184
185    .. code-block:: console
186
187       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
188       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
189
190 #. Bring up the PF ports:
191
192    .. code-block:: console
193
194       ifconfig ens5f0 up
195       ifconfig ens5f1 up
196
197 #. Create VF device(s):
198
199    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
200    of the parent PF.
201
202    Example output:
203
204    .. code-block:: console
205
206       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
207
208
209 #. Assign VF MAC address:
210
211    Assign MAC address to the VF using iproute2 utility. The syntax is::
212
213       ip link set <PF iface> vf <VF id> mac <macaddr>
214
215    Example output:
216
217    .. code-block:: console
218
219       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
220
221
222 #. PCI Passthrough:
223
224    The VF devices may be passed through to the guest VM using ``virt-manager`` or
225    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
226    using the instructions from Driver compilation and testing section above.
227
228
229 #. Running testpmd
230    (Enable QEDE_DEBUG_INFO=y to view informational messages):
231
232    Refer to the document
233    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
234    ``testpmd`` application.
235
236    Example output:
237
238    .. code-block:: console
239
240       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
241       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
242       --rss-ip --rss-udp
243
244       [...]
245
246     EAL: PCI device 0000:84:00.0 on NUMA socket 1
247     EAL:   probe driver: 1077:1634 rte_qede_pmd
248     EAL:   Not managed by a supported kernel driver, skipped
249     EAL: PCI device 0000:84:00.1 on NUMA socket 1
250     EAL:   probe driver: 1077:1634 rte_qede_pmd
251     EAL:   Not managed by a supported kernel driver, skipped
252     EAL: PCI device 0000:88:00.0 on NUMA socket 1
253     EAL:   probe driver: 1077:1656 rte_qede_pmd
254     EAL:   PCI memory mapped at 0x7f738b200000
255     EAL:   PCI memory mapped at 0x7f738b280000
256     EAL:   PCI memory mapped at 0x7f738b300000
257     PMD: Chip details : BB1
258     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
259     PMD: Firmware version : 8.7.7.0
260     PMD: Management firmware version : 8.7.8.0
261     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
262     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
263                                                         00:0e:1e:d2:09:9c
264       [...]
265     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
266                                                 tx_free_thresh 4068 socket 0
267     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
268                                                 tx_free_thresh 4068 socket 0
269     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
270                                                  tx_free_thresh 4068 socket 0
271     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
272                                                  tx_free_thresh 4068 socket 0
273     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
274                                                 rx_buf_size=2148 socket 0
275     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
276                                                 rx_buf_size=2148 socket 0
277     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
278                                                 rx_buf_size=2148 socket 0
279     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
280                                                 rx_buf_size=2148 socket 0
281     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
282     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
283       [...]
284     Checking link statuses...
285     Port 0 Link Up - speed 25000 Mbps - full-duplex
286     Port 1 Link Up - speed 25000 Mbps - full-duplex
287     Port 2 Link Up - speed 25000 Mbps - full-duplex
288     Port 3 Link Up - speed 25000 Mbps - full-duplex
289     Done
290     testpmd>