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``.