2 Copyright(c) 2017 Cavium, Inc.. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
15 * Neither the name of Cavium, Inc. 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.
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(S) 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.
31 LiquidIO VF Poll Mode Driver
32 ============================
34 The LiquidIO VF PMD library (librte_pmd_lio) provides poll mode driver support for
35 Cavium LiquidIO® II server adapter VFs. PF management and VF creation can be
36 done using kernel driver.
38 More information can be found at `Cavium Official Website
39 <http://cavium.com/LiquidIO_Adapters.html>`_.
41 Supported LiquidIO Adapters
42 -----------------------------
44 - LiquidIO II CN2350 210SV/225SV
45 - LiquidIO II CN2350 210SVPT
46 - LiquidIO II CN2360 210SV/225SV
47 - LiquidIO II CN2360 210SVPT
50 Pre-Installation Configuration
51 ------------------------------
53 The following options can be modified in the ``config`` file.
54 Please note that enabling debugging options may affect system performance.
56 - ``CONFIG_RTE_LIBRTE_LIO_PMD`` (default ``y``)
58 Toggle compilation of LiquidIO PMD.
60 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_DRIVER`` (default ``n``)
62 Toggle display of generic debugging messages.
64 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_INIT`` (default ``n``)
66 Toggle display of initialization related messages.
68 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_RX`` (default ``n``)
70 Toggle display of receive fast path run-time messages.
72 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_TX`` (default ``n``)
74 Toggle display of transmit fast path run-time messages.
76 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_MBOX`` (default ``n``)
78 Toggle display of mailbox messages.
80 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_REGS`` (default ``n``)
82 Toggle display of register reads and writes.
85 SR-IOV: Prerequisites and Sample Application Notes
86 --------------------------------------------------
88 This section provides instructions to configure SR-IOV with Linux OS.
90 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
92 .. code-block:: console
98 .. code-block:: console
101 Capabilities: [148 v1] Alternative Routing-ID Interpretation (ARI)
103 Capabilities: [178 v1] Single Root I/O Virtualization (SR-IOV)
105 Kernel driver in use: LiquidIO
107 #. Load the kernel module:
109 .. code-block:: console
113 #. Bring up the PF ports:
115 .. code-block:: console
120 #. Change PF MTU if required:
122 .. code-block:: console
124 ifconfig p4p1 mtu 9000
125 ifconfig p4p2 mtu 9000
127 #. Create VF device(s):
129 Echo number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
132 .. code-block:: console
134 echo 1 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
135 echo 1 > /sys/bus/pci/devices/0000:03:00.1/sriov_numvfs
137 #. Assign VF MAC address:
139 Assign MAC address to the VF using iproute2 utility. The syntax is::
141 ip link set <PF iface> vf <VF id> mac <macaddr>
145 .. code-block:: console
147 ip link set p4p1 vf 0 mac F2:A8:1B:5E:B4:66
149 #. Assign VF(s) to VM.
151 The VF devices may be passed through to the guest VM using qemu or
152 virt-manager or virsh etc.
154 Example qemu guest launch command:
156 .. code-block:: console
158 ./qemu-system-x86_64 -name lio-vm -machine accel=kvm \
159 -cpu host -m 4096 -smp 4 \
160 -drive file=<disk_file>,if=none,id=disk1,format=<type> \
161 -device virtio-blk-pci,scsi=off,drive=disk1,id=virtio-disk1,bootindex=1 \
162 -device vfio-pci,host=03:00.3 -device vfio-pci,host=03:08.3
166 Refer to the document
167 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
168 ``testpmd`` application.
172 Use ``igb_uio`` instead of ``vfio-pci`` in VM.
176 .. code-block:: console
179 EAL: PCI device 0000:03:00.3 on NUMA socket 0
180 EAL: probe driver: 177d:9712 net_liovf
181 EAL: using IOMMU type 1 (Type 1)
182 PMD: net_liovf[03:00.3]INFO: DEVICE : CN23XX VF
183 EAL: PCI device 0000:03:08.3 on NUMA socket 0
184 EAL: probe driver: 177d:9712 net_liovf
185 PMD: net_liovf[03:08.3]INFO: DEVICE : CN23XX VF
186 Interactive-mode selected
187 USER1: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
188 Configuring Port 0 (socket 0)
189 PMD: net_liovf[03:00.3]INFO: Starting port 0
190 Port 0: F2:A8:1B:5E:B4:66
191 Configuring Port 1 (socket 0)
192 PMD: net_liovf[03:08.3]INFO: Starting port 1
193 Port 1: 32:76:CC:EE:56:D7
194 Checking link statuses...
195 Port 0 Link Up - speed 10000 Mbps - full-duplex
196 Port 1 Link Up - speed 10000 Mbps - full-duplex
200 #. Enabling VF promiscuous mode
202 One VF per PF can be marked as trusted for promiscuous mode.
204 .. code-block:: console
206 ip link set dev <PF iface> vf <VF id> trust on
215 VF MTU is limited by PF MTU. Raise PF value before configuring VF for larger packet size.
220 Tx VLAN insertion is not supported and consequently VLAN offload feature is
226 Number of descriptors for Rx/Tx ring should be in the range 128 to 512.
231 LiquidIO adapters strip ethernet FCS of every packet coming to the host
232 interface. So, CRC will be stripped even when the ``rxmode.hw_strip_crc``
233 member is set to 0 in ``struct rte_eth_conf``.