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 **n**)
100
101  Toggle compilation of bnx2x driver. To use bnx2x PMD set this config parameter
102  to 'y'. Also, in order for firmware binary to load user will need zlib devel
103  package installed.
104
105- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG`` (default **n**)
106
107  Toggle display of generic debugging messages.
108
109- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_INIT`` (default **n**)
110
111  Toggle display of initialization related messages.
112
113- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_TX`` (default **n**)
114
115  Toggle display of transmit fast path run-time messages.
116
117- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_RX`` (default **n**)
118
119  Toggle display of receive fast path run-time messages.
120
121- ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_PERIODIC`` (default **n**)
122
123  Toggle display of register reads and writes.
124
125
126.. _bnx2x_driver-compilation:
127
128Driver Compilation
129~~~~~~~~~~~~~~~~~~
130
131BNX2X PMD for Linux x86_64 gcc target, run the following "make"
132command::
133
134   cd <DPDK-source-directory>
135   make config T=x86_64-native-linuxapp-gcc install
136
137To compile BNX2X PMD for Linux x86_64 clang target, run the following "make"
138command::
139
140   cd <DPDK-source-directory>
141   make config T=x86_64-native-linuxapp-clang install
142
143To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
144command::
145
146   cd <DPDK-source-directory>
147   make config T=i686-native-linuxapp-gcc install
148
149To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
150command:
151
152.. code-block:: console
153
154   cd <DPDK-source-directory>
155   make config T=i686-native-linuxapp-gcc install
156
157To compile BNX2X PMD for FreeBSD x86_64 clang target, run the following "gmake"
158command::
159
160   cd <DPDK-source-directory>
161   gmake config T=x86_64-native-bsdapp-clang install
162
163To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
164command::
165
166   cd <DPDK-source-directory>
167   gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49
168
169To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
170command:
171
172.. code-block:: console
173
174   cd <DPDK-source-directory>
175   gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49
176
177Linux
178-----
179
180.. _bnx2x_Linux-installation:
181
182Linux Installation
183~~~~~~~~~~~~~~~~~~
184
185Sample Application Notes
186~~~~~~~~~~~~~~~~~~~~~~~~
187
188This section demonstrates how to launch ``testpmd`` with QLogic 578xx
189devices managed by ``librte_pmd_bnx2x`` in Linux operating system.
190
191#. Request huge pages:
192
193   .. code-block:: console
194
195      echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
196
197#. Load ``igb_uio`` or ``vfio-pci`` driver:
198
199   .. code-block:: console
200
201      insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
202
203   or
204
205   .. code-block:: console
206
207      modprobe vfio-pci
208
209#. Bind the QLogic adapters to ``igb_uio`` or ``vfio-pci`` loaded in the
210   previous step::
211
212      ./tools/dpdk-devbind.py --bind igb_uio 0000:84:00.0 0000:84:00.1
213
214   or
215
216   Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
217
218   .. code-block:: console
219
220      sudo chmod a+x /dev/vfio
221
222      sudo chmod 0666 /dev/vfio/*
223
224      ./tools/dpdk-devbind.py --bind vfio-pci 0000:84:00.0 0000:84:00.1
225
226#. Start ``testpmd`` with basic parameters:
227
228   .. code-block:: console
229
230      ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -- -i
231
232   Example output:
233
234   .. code-block:: console
235
236      [...]
237      EAL: PCI device 0000:84:00.0 on NUMA socket 1
238      EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
239      EAL:   PCI memory mapped at 0x7f14f6fe5000
240      EAL:   PCI memory mapped at 0x7f14f67e5000
241      EAL:   PCI memory mapped at 0x7f15fbd9b000
242      EAL: PCI device 0000:84:00.1 on NUMA socket 1
243      EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
244      EAL:   PCI memory mapped at 0x7f14f5fe5000
245      EAL:   PCI memory mapped at 0x7f14f57e5000
246      EAL:   PCI memory mapped at 0x7f15fbd4f000
247      Interactive-mode selected
248      Configuring Port 0 (socket 0)
249      PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
250                   usable_bd=1020, total_bd=1024,
251                                tx_pages=4
252      PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
253                   usable_bd=510, total_bd=512,
254                                rx_pages=1, cq_pages=8
255      PMD: bnx2x_print_adapter_info():
256      [...]
257      Checking link statuses...
258      Port 0 Link Up - speed 10000 Mbps - full-duplex
259      Port 1 Link Up - speed 10000 Mbps - full-duplex
260      Done
261      testpmd>
262
263SR-IOV: Prerequisites and sample Application Notes
264~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265
266This section provides instructions to configure SR-IOV with Linux OS.
267
268#. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
269
270   .. code-block:: console
271
272      lspci -s <slot> -vvv
273
274   Example output:
275
276   .. code-block:: console
277
278      [...]
279      Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
280      [...]
281      Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
282      [...]
283      Kernel driver in use: igb_uio
284
285#. Load the kernel module:
286
287   .. code-block:: console
288
289      modprobe bnx2x
290
291   Example output:
292
293   .. code-block:: console
294
295      systemd-udevd[4848]: renamed network interface eth0 to ens5f0
296      systemd-udevd[4848]: renamed network interface eth1 to ens5f1
297
298#. Bring up the PF ports:
299
300   .. code-block:: console
301
302      ifconfig ens5f0 up
303      ifconfig ens5f1 up
304
305#. Create VF device(s):
306
307   Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
308   of the parent PF.
309
310   Example output:
311
312   .. code-block:: console
313
314      echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
315
316
317#. Assign VF MAC address:
318
319   Assign MAC address to the VF using iproute2 utility. The syntax is:
320   ip link set <PF iface> vf <VF id> mac <macaddr>
321
322   Example output:
323
324   .. code-block:: console
325
326      ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
327
328
329#. PCI Passthrough:
330
331   The VF devices may be passed through to the guest VM using virt-manager or
332   virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
333   using the instructions outlined in the Application notes below.
334