net/ixgbe: fix flow control mode setting
[dpdk.git] / doc / guides / nics / qede.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2016 QLogic Corporation
3     Copyright(c) 2017 Cavium, Inc
4
5 QEDE Poll Mode Driver
6 ======================
7
8 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
9 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
10 several standard Linux distros like RHEL, SLES, Ubuntu etc.
11 It is compile-tested under FreeBSD OS.
12
13 More information can be found at `QLogic Corporation's Website
14 <http://www.qlogic.com>`_.
15
16 Supported Features
17 ------------------
18
19 - Unicast/Multicast filtering
20 - Promiscuous mode
21 - Allmulti mode
22 - Port hardware statistics
23 - Jumbo frames
24 - Multiple MAC address
25 - MTU change
26 - Default pause flow control
27 - Multiprocess aware
28 - Scatter-Gather
29 - Multiple Rx/Tx queues
30 - RSS (with RETA/hash table/key)
31 - TSS
32 - Stateless checksum offloads (IPv4/IPv6/TCP/UDP)
33 - LRO/TSO
34 - VLAN offload - Filtering and stripping
35 - N-tuple filter and flow director (limited support)
36 - NPAR (NIC Partitioning)
37 - SR-IOV VF
38 - GRE Tunneling offload
39 - GENEVE Tunneling offload
40 - VXLAN Tunneling offload
41 - MPLSoUDP Tx Tunneling offload
42 - Generic flow API
43
44 Non-supported Features
45 ----------------------
46
47 - SR-IOV PF
48
49 Co-existence considerations
50 ---------------------------
51
52 - QLogic FastLinQ QL4xxxx CNAs support Ethernet, RDMA, iSCSI and FCoE
53   functionalities. These functionalities are supported using
54   QLogic Linux kernel drivers qed, qede, qedr, qedi and qedf. DPDK is
55   supported on these adapters using qede PMD.
56
57 - When SR-IOV is not enabled on the adapter,
58   QLogic Linux kernel drivers (qed, qede, qedr, qedi and qedf) and qede
59   PMD can’t be attached to different PFs on a given QLogic FastLinQ
60   QL4xxx adapter.
61   A given adapter needs to be completely used by DPDK or Linux drivers
62   Before binding DPDK driver to one or more PFs on the adapter,
63   please make sure to unbind Linux drivers from all PFs of the adapter.
64   If there are multiple adapters on the system, one or more adapters
65   can be used by DPDK driver completely and other adapters can be used
66   by Linux drivers completely.
67
68 - When SR-IOV is enabled on the adapter,
69   Linux kernel drivers (qed, qede, qedr, qedi and qedf) can be bound
70   to the PFs of a given adapter and either qede PMD or Linux drivers
71   (qed and qede) can be bound to the VFs of the adapter.
72
73 - For sharing an adapter between DPDK and Linux drivers, SRIOV needs
74   to be enabled. Bind all the PFs to Linux Drivers(qed/qede). Create
75   a VF on PFs where DPDK is desired and bind these VFs to qede_pmd.
76   Binding of PFs simultaneously to DPDK and Linux drivers on a given
77   adapter is not supported.
78
79 Supported QLogic Adapters
80 -------------------------
81
82 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)
83
84 Prerequisites
85 -------------
86
87 - Requires storm firmware version **8.40.33.0**. Firmware may be available
88   inbox in certain newer Linux distros under the standard directory
89   ``E.g. /lib/firmware/qed/qed_init_values-8.40.33.0.bin``.
90   If the required firmware files are not available then download it from
91   `linux-firmware git repository <http://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/qed>`_.
92
93 - Requires the NIC be updated minimally with **8.30.x.x** Management firmware(MFW) version supported for that NIC.
94   It is highly recommended that the NIC be updated with the latest available management firmware version to get latest feature  set.
95   Management Firmware and Firmware Upgrade Utility for Cavium FastLinQ(r) branded adapters can be downloaded from
96   `Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
97   For downloading Firmware Upgrade Utility, select NIC category, model and Linux distro.
98   To update the management firmware, refer to the instructions in the Firmware Upgrade Utility Readme document.
99   For OEM branded adapters please follow the instruction provided by the OEM to update the Management Firmware on the NIC.
100
101 - SR-IOV requires Linux PF driver version **8.20.x.x** or higher.
102   If the required PF driver is not available then download it from
103   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
104   For downloading PF driver, select adapter category, model and Linux distro.
105
106 Performance note
107 ~~~~~~~~~~~~~~~~
108
109 - For better performance, it is recommended to use 4K or higher RX/TX rings.
110
111 Config File Options
112 ~~~~~~~~~~~~~~~~~~~
113
114 The following options can be modified in the ``.config`` file. Please note that
115 enabling debugging options may affect system performance.
116
117 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
118
119   Toggle compilation of QEDE PMD driver.
120
121 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
122
123   Toggle display of transmit fast path run-time messages.
124
125 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
126
127   Toggle display of receive fast path run-time messages.
128
129 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
130
131   Gives absolute path of firmware file.
132   ``Eg: "/lib/firmware/qed/qed_init_values-8.40.33.0.bin"``
133   Empty string indicates driver will pick up the firmware file
134   from the default location /lib/firmware/qed.
135   CAUTION this option is more for custom firmware, it is not
136   recommended for use under normal condition.
137
138 Config notes
139 ~~~~~~~~~~~~
140
141 When there are multiple adapters and/or large number of Rx/Tx queues
142 configured on the adapters, the default (2560) number of memzone
143 descriptors may not be enough. Please increase the number of memzone
144 descriptors to a higher number as needed. When sufficient number of
145 memzone descriptors are not configured, user can potentially run into
146 following error.
147
148    .. code-block:: console
149
150       EAL: memzone_reserve_aligned_thread_unsafe(): No more room in config
151
152 Driver compilation and testing
153 ------------------------------
154
155 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
156 for details.
157
158 RTE Flow Support
159 ----------------
160
161 QLogic FastLinQ QL4xxxx NICs has support for the following patterns and
162 actions.
163
164 Patterns:
165
166 .. _table_qede_supported_flow_item_types:
167
168 .. table:: Item types
169
170    +----+--------------------------------+
171    | #  | Pattern Type                   |
172    +====+================================+
173    | 1  | RTE_FLOW_ITEM_TYPE_IPV4        |
174    +----+--------------------------------+
175    | 2  | RTE_FLOW_ITEM_TYPE_IPV6        |
176    +----+--------------------------------+
177    | 3  | RTE_FLOW_ITEM_TYPE_UDP         |
178    +----+--------------------------------+
179    | 4  | RTE_FLOW_ITEM_TYPE_TCP         |
180    +----+--------------------------------+
181
182 Actions:
183
184 .. _table_qede_supported_ingress_action_types:
185
186 .. table:: Ingress action types
187
188    +----+--------------------------------+
189    | #  | Action Type                    |
190    +====+================================+
191    | 1  | RTE_FLOW_ACTION_TYPE_QUEUE     |
192    +----+--------------------------------+
193    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
194    +----+--------------------------------+
195
196 SR-IOV: Prerequisites and Sample Application Notes
197 --------------------------------------------------
198
199 This section provides instructions to configure SR-IOV with Linux OS.
200
201 **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.20.x.x or higher.
202
203 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
204
205    .. code-block:: console
206
207       lspci -s <slot> -vvv
208
209    Example output:
210
211    .. code-block:: console
212
213       [...]
214       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
215       [...]
216       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
217       [...]
218       Kernel driver in use: igb_uio
219
220 #. Load the kernel module:
221
222    .. code-block:: console
223
224       modprobe qede
225
226    Example output:
227
228    .. code-block:: console
229
230       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
231       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
232
233 #. Bring up the PF ports:
234
235    .. code-block:: console
236
237       ifconfig ens5f0 up
238       ifconfig ens5f1 up
239
240 #. Create VF device(s):
241
242    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
243    of the parent PF.
244
245    Example output:
246
247    .. code-block:: console
248
249       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
250
251
252 #. Assign VF MAC address:
253
254    Assign MAC address to the VF using iproute2 utility. The syntax is::
255
256       ip link set <PF iface> vf <VF id> mac <macaddr>
257
258    Example output:
259
260    .. code-block:: console
261
262       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
263
264
265 #. PCI Passthrough:
266
267    The VF devices may be passed through to the guest VM using ``virt-manager`` or
268    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
269    using the instructions from Driver compilation and testing section above.
270
271
272 #. Running testpmd
273    (Supply ``--log-level="pmd.net.qede.driver:info`` to view informational messages):
274
275    Refer to the document
276    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
277    ``testpmd`` application.
278
279    Example output:
280
281    .. code-block:: console
282
283       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
284       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
285       --rss-ip --rss-udp
286
287       [...]
288
289     EAL: PCI device 0000:84:00.0 on NUMA socket 1
290     EAL:   probe driver: 1077:1634 rte_qede_pmd
291     EAL:   Not managed by a supported kernel driver, skipped
292     EAL: PCI device 0000:84:00.1 on NUMA socket 1
293     EAL:   probe driver: 1077:1634 rte_qede_pmd
294     EAL:   Not managed by a supported kernel driver, skipped
295     EAL: PCI device 0000:88:00.0 on NUMA socket 1
296     EAL:   probe driver: 1077:1656 rte_qede_pmd
297     EAL:   PCI memory mapped at 0x7f738b200000
298     EAL:   PCI memory mapped at 0x7f738b280000
299     EAL:   PCI memory mapped at 0x7f738b300000
300     PMD: Chip details : BB1
301     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
302     PMD: Firmware version : 8.7.7.0
303     PMD: Management firmware version : 8.7.8.0
304     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
305     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
306                                                         00:0e:1e:d2:09:9c
307       [...]
308     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
309                                                 tx_free_thresh 4068 socket 0
310     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
311                                                 tx_free_thresh 4068 socket 0
312     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
313                                                  tx_free_thresh 4068 socket 0
314     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
315                                                  tx_free_thresh 4068 socket 0
316     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
317                                                 rx_buf_size=2148 socket 0
318     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
319                                                 rx_buf_size=2148 socket 0
320     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
321                                                 rx_buf_size=2148 socket 0
322     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
323                                                 rx_buf_size=2148 socket 0
324     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
325     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
326       [...]
327     Checking link statuses...
328     Port 0 Link Up - speed 25000 Mbps - full-duplex
329     Port 1 Link Up - speed 25000 Mbps - full-duplex
330     Port 2 Link Up - speed 25000 Mbps - full-duplex
331     Port 3 Link Up - speed 25000 Mbps - full-duplex
332     Done
333     testpmd>