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 CN2350 210SVPT
  46 - LiquidIO II CN2360 210SV/225SV
  47 - LiquidIO II CN2360 210SVPT
  48
  49
  50 Pre-Installation Configuration
  51 ------------------------------
  52
  53 The following options can be modified in the ``config`` file.
  54 Please note that enabling debugging options may affect system performance.
  55
  56 - ``CONFIG_RTE_LIBRTE_LIO_PMD`` (default ``y``)
  57
  58   Toggle compilation of LiquidIO PMD.
  59
  60 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_DRIVER`` (default ``n``)
  61
  62   Toggle display of generic debugging messages.
  63
  64 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_INIT`` (default ``n``)
  65
  66   Toggle display of initialization related messages.
  67
  68 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_RX`` (default ``n``)
  69
  70   Toggle display of receive fast path run-time messages.
  71
  72 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_TX`` (default ``n``)
  73
  74   Toggle display of transmit fast path run-time messages.
  75
  76 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_MBOX`` (default ``n``)
  77
  78   Toggle display of mailbox messages.
  79
  80 - ``CONFIG_RTE_LIBRTE_LIO_DEBUG_REGS`` (default ``n``)
  81
  82   Toggle display of register reads and writes.
  83
  84
  85 SR-IOV: Prerequisites and Sample Application Notes
  86 --------------------------------------------------
  87
  88 This section provides instructions to configure SR-IOV with Linux OS.
  89
  90 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
  91
  92    .. code-block:: console
  93
  94       lspci -s <slot> -vvv
  95
  96    Example output:
  97
  98    .. code-block:: console
  99
 100       [...]
 101       Capabilities: [148 v1] Alternative Routing-ID Interpretation (ARI)
 102       [...]
 103       Capabilities: [178 v1] Single Root I/O Virtualization (SR-IOV)
 104       [...]
 105       Kernel driver in use: LiquidIO
 106
 107 #. Load the kernel module:
 108
 109    .. code-block:: console
 110
 111       modprobe liquidio
 112
 113 #. Bring up the PF ports:
 114
 115    .. code-block:: console
 116
 117       ifconfig p4p1 up
 118       ifconfig p4p2 up
 119
 120 #. Change PF MTU if required:
 121
 122    .. code-block:: console
 123
 124       ifconfig p4p1 mtu 9000
 125       ifconfig p4p2 mtu 9000
 126
 127 #. Create VF device(s):
 128
 129    Echo number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 130    of the parent PF.
 131
 132    .. code-block:: console
 133
 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
 136
 137 #. Assign VF MAC address:
 138
 139    Assign MAC address to the VF using iproute2 utility. The syntax is::
 140
 141       ip link set <PF iface> vf <VF id> mac <macaddr>
 142
 143    Example output:
 144
 145    .. code-block:: console
 146
 147       ip link set p4p1 vf 0 mac F2:A8:1B:5E:B4:66
 148
 149 #. Assign VF(s) to VM.
 150
 151    The VF devices may be passed through to the guest VM using qemu or
 152    virt-manager or virsh etc.
 153
 154    Example qemu guest launch command:
 155
 156    .. code-block:: console
 157
 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
 163
 164 #. Running testpmd
 165
 166    Refer to the document
 167    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 168    ``testpmd`` application.
 169
 170    .. note::
 171
 172       Use ``igb_uio`` instead of ``vfio-pci`` in VM.
 173
 174    Example output:
 175
 176    .. code-block:: console
 177
 178       [...]
 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
 197       Done
 198       testpmd>
 199
 200 #. Enabling VF promiscuous mode
 201
 202    One VF per PF can be marked as trusted for promiscuous mode.
 203
 204    .. code-block:: console
 205
 206       ip link set dev <PF iface> vf <VF id> trust on
 207
 208
 209 Limitations
 210 -----------
 211
 212 VF MTU
 213 ~~~~~~
 214
 215 VF MTU is limited by PF MTU. Raise PF value before configuring VF for larger packet size.
 216
 217 VLAN offload
 218 ~~~~~~~~~~~~
 219
 220 Tx VLAN insertion is not supported and consequently VLAN offload feature is
 221 marked partial.
 222
 223 Ring size
 224 ~~~~~~~~~
 225
 226 Number of descriptors for Rx/Tx ring should be in the range 128 to 512.
 227
 228 CRC striping
 229 ~~~~~~~~~~~~
 230
 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``.