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