bnx2x.rst revision 97f17497
1..  BSD LICENSE
2    Copyright (c) 2015 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
31BNX2X Poll Mode Driver
32======================
33
34The BNX2X poll mode driver library (**librte_pmd_bnx2x**) implements support
35for **QLogic 578xx** 10/20 Gbps family of adapters as well as their virtual
36functions (VF) in SR-IOV context. It is supported on several standard Linux
37distros like Red Hat 7.x and SLES12 OS. It is compile-tested under FreeBSD OS.
38
39More information can be found at `QLogic Corporation's Official Website
40<http://www.qlogic.com>`_.
41
42Supported Features
43------------------
44
45BNX2X PMD has support for:
46
47- Base L2 features
48- Unicast/multicast filtering
49- Promiscuous mode
50- Port hardware statistics
51- SR-IOV VF
52
53Non-supported Features
54----------------------
55
56The features not yet supported include:
57
58- TSS (Transmit Side Scaling)
59- RSS (Receive Side Scaling)
60- LRO/TSO offload
61- Checksum offload
62- SR-IOV PF
63- Rx TX scatter gather
64
65Co-existence considerations
66---------------------------
67
68- BCM578xx being a CNA can have both NIC and Storage personalities.
69  However, coexistence with storage protocol drivers (cnic, bnx2fc and
70  bnx2fi) is not supported on the same adapter. So storage personality
71  has to be disabled on that adapter when used in DPDK applications.
72
73- For SR-IOV case, bnx2x PMD will be used to bind to SR-IOV VF device and
74  Linux native kernel driver (bnx2x) will be attached to SR-IOV PF.
75
76
77Supported QLogic NICs
78---------------------
79
80- 578xx
81
82Prerequisites
83-------------
84
85- Requires firmware version **7.2.51.0**. It is included in most of the
86  standard Linux distros. If it is not available visit
87  `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_
88  to get the required firmware.
89
90Pre-Installation Configuration
91------------------------------
92
93Config File Options
94~~~~~~~~~~~~~~~~~~~
95
96The following options can be modified in the ``.config`` file. Please note that
97enabling debugging options may affect system performance.
98
99- ``CONFIG_RTE_LIBRTE_BNX2X_PMD`` (default **y**)
100
101  Toggle compilation of bnx2x driver.
102
103- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG`` (default **n**)
104
105  Toggle display of generic debugging messages.
106
107- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_INIT`` (default **n**)
108
109  Toggle display of initialization related messages.
110
111- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_TX`` (default **n**)
112
113  Toggle display of transmit fast path run-time messages.
114
115- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_RX`` (default **n**)
116
117  Toggle display of receive fast path run-time messages.
118
119- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_PERIODIC`` (default **n**)
120
121  Toggle display of register reads and writes.
122
123
124.. _bnx2x_driver-compilation:
125
126Driver Compilation
127~~~~~~~~~~~~~~~~~~
128
129BNX2X PMD for Linux x86_64 gcc target, run the following "make"
130command::
131
132   cd <DPDK-source-directory>
133   make config T=x86_64-native-linuxapp-gcc install
134
135To compile BNX2X PMD for Linux x86_64 clang target, run the following "make"
136command::
137
138   cd <DPDK-source-directory>
139   make config T=x86_64-native-linuxapp-clang install
140
141To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
142command::
143
144   cd <DPDK-source-directory>
145   make config T=i686-native-linuxapp-gcc install
146
147To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
148command:
149
150.. code-block:: console
151
152   cd <DPDK-source-directory>
153   make config T=i686-native-linuxapp-gcc install
154
155To compile BNX2X PMD for FreeBSD x86_64 clang target, run the following "gmake"
156command::
157
158   cd <DPDK-source-directory>
159   gmake config T=x86_64-native-bsdapp-clang install
160
161To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
162command::
163
164   cd <DPDK-source-directory>
165   gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc48 CC=gcc48
166
167To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
168command:
169
170.. code-block:: console
171
172   cd <DPDK-source-directory>
173   gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc48 CC=gcc48
174
175Linux
176-----
177
178.. _bnx2x_Linux-installation:
179
180Linux Installation
181~~~~~~~~~~~~~~~~~~
182
183Sample Application Notes
184~~~~~~~~~~~~~~~~~~~~~~~~
185
186This section demonstrates how to launch ``testpmd`` with QLogic 578xx
187devices managed by ``librte_pmd_bnx2x`` in Linux operating system.
188
189#. Request huge pages:
190
191   .. code-block:: console
192
193      echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
194
195#. Load ``igb_uio`` or ``vfio-pci`` driver:
196
197   .. code-block:: console
198
199      insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
200
201   or
202
203   .. code-block:: console
204
205      modprobe vfio-pci
206
207#. Bind the QLogic adapters to ``igb_uio`` or ``vfio-pci`` loaded in the
208   previous step::
209
210      ./tools/dpdk_nic_bind.py --bind igb_uio 0000:84:00.0 0000:84:00.1
211
212   or
213
214   Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
215
216   .. code-block:: console
217
218      sudo chmod a+x /dev/vfio
219
220      sudo chmod 0666 /dev/vfio/*
221
222      ./tools/dpdk_nic_bind.py --bind vfio-pci 0000:84:00.0 0000:84:00.1
223
224#. Start ``testpmd`` with basic parameters:
225
226   .. code-block:: console
227
228      ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -- -i
229
230   Example output:
231
232   .. code-block:: console
233
234      [...]
235      EAL: PCI device 0000:84:00.0 on NUMA socket 1
236      EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
237      EAL:   PCI memory mapped at 0x7f14f6fe5000
238      EAL:   PCI memory mapped at 0x7f14f67e5000
239      EAL:   PCI memory mapped at 0x7f15fbd9b000
240      EAL: PCI device 0000:84:00.1 on NUMA socket 1
241      EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
242      EAL:   PCI memory mapped at 0x7f14f5fe5000
243      EAL:   PCI memory mapped at 0x7f14f57e5000
244      EAL:   PCI memory mapped at 0x7f15fbd4f000
245      Interactive-mode selected
246      Configuring Port 0 (socket 0)
247      PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
248                   usable_bd=1020, total_bd=1024,
249                                tx_pages=4
250      PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
251                   usable_bd=510, total_bd=512,
252                                rx_pages=1, cq_pages=8
253      PMD: bnx2x_print_adapter_info():
254      [...]
255      Checking link statuses...
256      Port 0 Link Up - speed 10000 Mbps - full-duplex
257      Port 1 Link Up - speed 10000 Mbps - full-duplex
258      Done
259      testpmd>
260
261SR-IOV: Prerequisites and sample Application Notes
262~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263
264This section provides instructions to configure SR-IOV with Linux OS.
265
266#. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
267
268   .. code-block:: console
269
270      lspci -s <slot> -vvv
271
272   Example output:
273
274   .. code-block:: console
275
276      [...]
277      Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
278      [...]
279      Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
280      [...]
281      Kernel driver in use: igb_uio
282
283#. Load the kernel module:
284
285   .. code-block:: console
286
287      modprobe bnx2x
288
289   Example output:
290
291   .. code-block:: console
292
293      systemd-udevd[4848]: renamed network interface eth0 to ens5f0
294      systemd-udevd[4848]: renamed network interface eth1 to ens5f1
295
296#. Bring up the PF ports:
297
298   .. code-block:: console
299
300      ifconfig ens5f0 up
301      ifconfig ens5f1 up
302
303#. Create VF device(s):
304
305   Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
306   of the parent PF.
307
308   Example output:
309
310   .. code-block:: console
311
312      echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
313
314
315#. Assign VF MAC address:
316
317   Assign MAC address to the VF using iproute2 utility. The syntax is:
318   ip link set <PF iface> vf <VF id> mac <macaddr>
319
320   Example output:
321
322   .. code-block:: console
323
324      ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
325
326
327#. PCI Passthrough:
328
329   The VF devices may be passed through to the guest VM using virt-manager or
330   virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
331   using the instructions outlined in the Application notes below.
332