qede.rst revision 8b25d1ad
1..  BSD LICENSE
2    Copyright (c) 2016 QLogic Corporation
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 QLogic 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
31QEDE Poll Mode Driver
32======================
33
34The QEDE poll mode driver library (**librte_pmd_qede**) implements support
35for **QLogic FastLinQ QL4xxxx 25G/40G CNA** family of adapters as well
36as their virtual functions (VF) in SR-IOV context. It is supported on
37several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu.
38It is compile-tested under FreeBSD OS.
39
40More information can be found at `QLogic Corporation's Website
41<http://www.qlogic.com>`_.
42
43Supported Features
44------------------
45
46- Unicast/Multicast filtering
47- Promiscuous mode
48- Allmulti mode
49- Port hardware statistics
50- Jumbo frames (using single buffer)
51- VLAN offload - Filtering and stripping
52- Stateless checksum offloads (IPv4/TCP/UDP)
53- Multiple Rx/Tx queues (queue-pairs)
54- RSS (with user configurable table/key)
55- TSS
56- Multiple MAC address
57- Default pause flow control
58- SR-IOV VF for 25G/40G modes
59
60Non-supported Features
61----------------------
62
63- Scatter-Gather Rx/Tx frames
64- Unequal number of Rx/Tx queues
65- MTU change (dynamic)
66- SR-IOV PF
67- Tunneling offloads
68- Reload of the PMD after a non-graceful termination
69
70Supported QLogic Adapters
71-------------------------
72
73- QLogic FastLinQ QL4xxxx 25G/40G/100G CNAs.
74
75Prerequisites
76-------------
77
78- Requires firmware version **8.7.x.** and management firmware
79  version **8.7.x or higher**. Firmware may be available
80  inbox in certain newer Linux distros under the standard directory
81  ``E.g. /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin``
82
83- If the required firmware files are not available then visit
84  `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_.
85
86- This driver relies on external zlib library (-lz) for uncompressing
87  the firmware file.
88
89Performance note
90~~~~~~~~~~~~~~~~
91
92- For better performance, it is recommended to use 4K or higher RX/TX rings.
93
94Config File Options
95~~~~~~~~~~~~~~~~~~~
96
97The following options can be modified in the ``.config`` file. Please note that
98enabling debugging options may affect system performance.
99
100- ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
101
102  Toggle compilation of QEDE PMD driver.
103
104- ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_INFO`` (default **n**)
105
106  Toggle display of generic debugging messages.
107
108- ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_DRIVER`` (default **n**)
109
110  Toggle display of ecore related messages.
111
112- ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
113
114  Toggle display of transmit fast path run-time messages.
115
116- ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
117
118  Toggle display of receive fast path run-time messages.
119
120- ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
121
122  Gives absolute path of firmware file.
123  ``Eg: "/lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin"``
124  Empty string indicates driver will pick up the firmware file
125  from the default location.
126
127Driver Compilation
128~~~~~~~~~~~~~~~~~~
129
130To compile QEDE PMD for Linux x86_64 gcc target, run the following ``make``
131command::
132
133   cd <DPDK-source-directory>
134   make config T=x86_64-native-linuxapp-gcc install
135
136To compile QEDE PMD for Linux x86_64 clang target, run the following ``make``
137command::
138
139   cd <DPDK-source-directory>
140   make config T=x86_64-native-linuxapp-clang install
141
142To compile QEDE PMD for FreeBSD x86_64 clang target, run the following ``gmake``
143command::
144
145   cd <DPDK-source-directory>
146   gmake config T=x86_64-native-bsdapp-clang install
147
148To compile QEDE PMD for FreeBSD x86_64 gcc target, run the following ``gmake``
149command::
150
151   cd <DPDK-source-directory>
152   gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=\
153                                        /usr/local/lib/gcc48 CC=gcc48
154
155
156Sample Application Notes
157~~~~~~~~~~~~~~~~~~~~~~~~
158
159This section demonstrates how to launch ``testpmd`` with QLogic 4xxxx
160devices managed by ``librte_pmd_qede`` in Linux operating system.
161
162#. Request huge pages:
163
164   .. code-block:: console
165
166      echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/ \
167                                                                nr_hugepages
168
169#. Load ``igb_uio`` driver:
170
171   .. code-block:: console
172
173      insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
174
175#. Bind the QLogic 4xxxx adapters to ``igb_uio`` loaded in the
176   previous step:
177
178   .. code-block:: console
179
180      ./tools/dpdk_nic_bind.py --bind igb_uio 0000:84:00.0 0000:84:00.1 \
181                                              0000:84:00.2 0000:84:00.3
182
183#. Start ``testpmd`` with basic parameters:
184   (Enable QEDE_DEBUG_INFO=y to view informational messages)
185
186   .. code-block:: console
187
188      testpmd -c 0xff1 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
189      --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
190      --rss-ip --rss-udp
191
192      [...]
193
194    EAL: PCI device 0000:84:00.0 on NUMA socket 1
195    EAL:   probe driver: 1077:1634 rte_qede_pmd
196    EAL:   Not managed by a supported kernel driver, skipped
197    EAL: PCI device 0000:84:00.1 on NUMA socket 1
198    EAL:   probe driver: 1077:1634 rte_qede_pmd
199    EAL:   Not managed by a supported kernel driver, skipped
200    EAL: PCI device 0000:88:00.0 on NUMA socket 1
201    EAL:   probe driver: 1077:1656 rte_qede_pmd
202    EAL:   PCI memory mapped at 0x7f738b200000
203    EAL:   PCI memory mapped at 0x7f738b280000
204    EAL:   PCI memory mapped at 0x7f738b300000
205    PMD: Chip details : BB1
206    PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
207    PMD: Firmware version : 8.7.7.0
208    PMD: Management firmware version : 8.7.8.0
209    PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
210    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
211                                                        00:0e:1e:d2:09:9c
212      [...]
213    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
214                                                tx_free_thresh 4068 socket 0
215    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
216                                                tx_free_thresh 4068 socket 0
217    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
218                                                 tx_free_thresh 4068 socket 0
219    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
220                                                 tx_free_thresh 4068 socket 0
221    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
222                                                rx_buf_size=2148 socket 0
223    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
224                                                rx_buf_size=2148 socket 0
225    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
226                                                rx_buf_size=2148 socket 0
227    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
228                                                rx_buf_size=2148 socket 0
229    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
230    [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
231      [...]
232    Checking link statuses...
233    Port 0 Link Up - speed 25000 Mbps - full-duplex
234    Port 1 Link Up - speed 25000 Mbps - full-duplex
235    Port 2 Link Up - speed 25000 Mbps - full-duplex
236    Port 3 Link Up - speed 25000 Mbps - full-duplex
237    Done
238    testpmd>
239
240
241SR-IOV: Prerequisites and Sample Application Notes
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243
244This section provides instructions to configure SR-IOV with Linux OS.
245
246**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.
247
248#. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
249
250   .. code-block:: console
251
252      lspci -s <slot> -vvv
253
254   Example output:
255
256   .. code-block:: console
257
258      [...]
259      Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
260      [...]
261      Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
262      [...]
263      Kernel driver in use: igb_uio
264
265#. Load the kernel module:
266
267   .. code-block:: console
268
269      modprobe qede
270
271   Example output:
272
273   .. code-block:: console
274
275      systemd-udevd[4848]: renamed network interface eth0 to ens5f0
276      systemd-udevd[4848]: renamed network interface eth1 to ens5f1
277
278#. Bring up the PF ports:
279
280   .. code-block:: console
281
282      ifconfig ens5f0 up
283      ifconfig ens5f1 up
284
285#. Create VF device(s):
286
287   Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
288   of the parent PF.
289
290   Example output:
291
292   .. code-block:: console
293
294      echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
295
296
297#. Assign VF MAC address:
298
299   Assign MAC address to the VF using iproute2 utility. The syntax is::
300
301      ip link set <PF iface> vf <VF id> mac <macaddr>
302
303   Example output:
304
305   .. code-block:: console
306
307      ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
308
309
310#. PCI Passthrough:
311
312   The VF devices may be passed through to the guest VM using ``virt-manager`` or
313   ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
314   using the instructions outlined in the Application notes above.
315