net/i40e: fix link down and negotiation
[dpdk.git] / doc / guides / nics / liquidio.rst
1 ..  BSD LICENSE
2     Copyright(c) 2017 Cavium, Inc.. All rights reserved.
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 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.
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(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.
30
31 LiquidIO VF Poll Mode Driver
32 ============================
33
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.
37
38 More information can be found at `Cavium Official Website
39 <http://cavium.com/LiquidIO_Adapters.html>`_.
40
41 Supported LiquidIO Adapters
42 -----------------------------
43
44 - LiquidIO II CN2350 210SV/225SV
45 - LiquidIO II CN2360 210SV/225SV
46
47
48 Pre-Installation Configuration
49 ------------------------------
50
51 The following options can be modified in the ``config`` file.
52 Please note that enabling debugging options may affect system performance.
53
54 - ``CONFIG_RTE_LIBRTE_LIO_PMD`` (default ``y``)
55
56   Toggle compilation of LiquidIO PMD.
57
58 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_DRIVER`` (default ``n``)
59
60   Toggle display of generic debugging messages.
61
62 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_INIT`` (default ``n``)
63
64   Toggle display of initialization related messages.
65
66 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_RX`` (default ``n``)
67
68   Toggle display of receive fast path run-time messages.
69
70 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_TX`` (default ``n``)
71
72   Toggle display of transmit fast path run-time messages.
73
74 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_MBOX`` (default ``n``)
75
76   Toggle display of mailbox messages.
77
78 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_REGS`` (default ``n``)
79
80   Toggle display of register reads and writes.
81
82
83 SR-IOV: Prerequisites and Sample Application Notes
84 --------------------------------------------------
85
86 This section provides instructions to configure SR-IOV with Linux OS.
87
88 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
89
90    .. code-block:: console
91
92       lspci -s <slot> -vvv
93
94    Example output:
95
96    .. code-block:: console
97
98       [...]
99       Capabilities: [148 v1] Alternative Routing-ID Interpretation (ARI)
100       [...]
101       Capabilities: [178 v1] Single Root I/O Virtualization (SR-IOV)
102       [...]
103       Kernel driver in use: LiquidIO
104
105 #. Load the kernel module:
106
107    .. code-block:: console
108
109       modprobe liquidio
110
111 #. Bring up the PF ports:
112
113    .. code-block:: console
114
115       ifconfig p4p1 up
116       ifconfig p4p2 up
117
118 #. Change PF MTU if required:
119
120    .. code-block:: console
121
122       ifconfig p4p1 mtu 9000
123       ifconfig p4p2 mtu 9000
124
125 #. Create VF device(s):
126
127    Echo number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
128    of the parent PF.
129
130    .. code-block:: console
131
132       echo 1 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
133       echo 1 > /sys/bus/pci/devices/0000:03:00.1/sriov_numvfs
134
135 #. Assign VF MAC address:
136
137    Assign MAC address to the VF using iproute2 utility. The syntax is::
138
139       ip link set <PF iface> vf <VF id> mac <macaddr>
140
141    Example output:
142
143    .. code-block:: console
144
145       ip link set p4p1 vf 0 mac F2:A8:1B:5E:B4:66
146
147 #. Assign VF(s) to VM.
148
149    The VF devices may be passed through to the guest VM using qemu or
150    virt-manager or virsh etc.
151
152    Example qemu guest launch command:
153
154    .. code-block:: console
155
156       ./qemu-system-x86_64 -name lio-vm -machine accel=kvm \
157       -cpu host -m 4096 -smp 4 \
158       -drive file=<disk_file>,if=none,id=disk1,format=<type> \
159       -device virtio-blk-pci,scsi=off,drive=disk1,id=virtio-disk1,bootindex=1 \
160       -device vfio-pci,host=03:00.3 -device vfio-pci,host=03:08.3
161
162 #. Running testpmd
163
164    Refer to the document
165    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
166    ``testpmd`` application.
167
168    .. note::
169
170       Use ``igb_uio`` instead of ``vfio-pci`` in VM.
171
172    Example output:
173
174    .. code-block:: console
175
176       [...]
177       EAL: PCI device 0000:03:00.3 on NUMA socket 0
178       EAL:   probe driver: 177d:9712 net_liovf
179       EAL:   using IOMMU type 1 (Type 1)
180       PMD: net_liovf[03:00.3]INFO: DEVICE : CN23XX VF
181       EAL: PCI device 0000:03:08.3 on NUMA socket 0
182       EAL:   probe driver: 177d:9712 net_liovf
183       PMD: net_liovf[03:08.3]INFO: DEVICE : CN23XX VF
184       Interactive-mode selected
185       USER1: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
186       Configuring Port 0 (socket 0)
187       PMD: net_liovf[03:00.3]INFO: Starting port 0
188       Port 0: F2:A8:1B:5E:B4:66
189       Configuring Port 1 (socket 0)
190       PMD: net_liovf[03:08.3]INFO: Starting port 1
191       Port 1: 32:76:CC:EE:56:D7
192       Checking link statuses...
193       Port 0 Link Up - speed 10000 Mbps - full-duplex
194       Port 1 Link Up - speed 10000 Mbps - full-duplex
195       Done
196       testpmd>
197
198
199 Limitations
200 -----------
201
202 VF MTU
203 ~~~~~~
204
205 VF MTU is limited by PF MTU. Raise PF value before configuring VF for larger packet size.
206
207 VLAN offload
208 ~~~~~~~~~~~~
209
210 Tx VLAN insertion is not supported and consequently VLAN offload feature is
211 marked partial.
212
213 Ring size
214 ~~~~~~~~~
215
216 Number of descriptors for Rx/Tx ring should be in the range 128 to 512.
217
218 CRC striping
219 ~~~~~~~~~~~~
220
221 LiquidIO adapters strip ethernet FCS of every packet coming to the host
222 interface. So, CRC will be stripped even when the ``rxmode.hw_strip_crc``
223 member is set to 0 in ``struct rte_eth_conf``.