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
  45 - LiquidIO II CN2360 210SV
  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 .. _lio_driver-compilation:
  84
  85 Driver Compilation
  86 ------------------
  87
  88 To compile LiquidIO PMD for Linux x86_64 gcc target, run the following "make"
  89 command:
  90
  91 .. code-block:: console
  92
  93    cd <DPDK-source-directory>
  94    make install T=x86_64-native-linuxapp-gcc
  95
  96
  97 Sample Application Notes
  98 ------------------------
  99
 100 This section demonstrates how to launch ``testpmd`` with LiquidIO® CN23XX
 101 device managed by ``librte_pmd_lio`` in Linux operating system.
 102
 103 #. Mount huge pages:
 104
 105    .. code-block:: console
 106
 107       mkdir /mnt/huge
 108       mount -t hugetlbfs nodev /mnt/huge
 109
 110 #. Request huge pages:
 111
 112    .. code-block:: console
 113
 114       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 115
 116 #. Load ``vfio-pci`` driver:
 117
 118    .. code-block:: console
 119
 120       modprobe vfio-pci
 121
 122 #. Bind the LiquidIO VFs to ``vfio-pci`` loaded in previous step:
 123
 124    Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 125
 126    .. code-block:: console
 127
 128       sudo chmod a+x /dev/vfio
 129
 130       sudo chmod 0666 /dev/vfio/*
 131
 132       ./usertools/dpdk-devbind.py --bind vfio-pci 0000:03:00.3 0000:03:08.3
 133
 134 #. Start ``testpmd`` with basic parameters:
 135
 136    .. code-block:: console
 137
 138       ./build/app/testpmd -c 0xf -n 4 -- -i
 139
 140    Example output:
 141
 142    .. code-block:: console
 143
 144       [...]
 145       EAL: PCI device 0000:03:00.3 on NUMA socket 0
 146       EAL:   probe driver: 177d:9712 net_liovf
 147       EAL:   using IOMMU type 1 (Type 1)
 148       PMD: net_liovf[03:00.3]INFO: DEVICE : CN23XX VF
 149       EAL: PCI device 0000:03:08.3 on NUMA socket 0
 150       EAL:   probe driver: 177d:9712 net_liovf
 151       PMD: net_liovf[03:08.3]INFO: DEVICE : CN23XX VF
 152       Interactive-mode selected
 153       USER1: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
 154       Configuring Port 0 (socket 0)
 155       PMD: net_liovf[03:00.3]INFO: Starting port 0
 156       Port 0: F2:A8:1B:5E:B4:66
 157       Configuring Port 1 (socket 0)
 158       PMD: net_liovf[03:08.3]INFO: Starting port 1
 159       Port 1: 32:76:CC:EE:56:D7
 160       Checking link statuses...
 161       Port 0 Link Up - speed 10000 Mbps - full-duplex
 162       Port 1 Link Up - speed 10000 Mbps - full-duplex
 163       Done
 164       testpmd>
 165
 166
 167 SR-IOV: Prerequisites and Sample Application Notes
 168 --------------------------------------------------
 169
 170 This section provides instructions to configure SR-IOV with Linux OS.
 171
 172 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
 173
 174    .. code-block:: console
 175
 176       lspci -s <slot> -vvv
 177
 178    Example output:
 179
 180    .. code-block:: console
 181
 182       [...]
 183       Capabilities: [148 v1] Alternative Routing-ID Interpretation (ARI)
 184       [...]
 185       Capabilities: [178 v1] Single Root I/O Virtualization (SR-IOV)
 186       [...]
 187       Kernel driver in use: LiquidIO
 188
 189 #. Load the kernel module:
 190
 191    .. code-block:: console
 192
 193       modprobe liquidio
 194
 195 #. Bring up the PF ports:
 196
 197    .. code-block:: console
 198
 199       ifconfig p4p1 up
 200       ifconfig p4p2 up
 201
 202 #. Change PF MTU if required:
 203
 204    .. code-block:: console
 205
 206       ifconfig p4p1 mtu 9000
 207       ifconfig p4p2 mtu 9000
 208
 209 #. Create VF device(s):
 210
 211    Echo number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 212    of the parent PF.
 213
 214    .. code-block:: console
 215
 216       echo 1 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
 217       echo 1 > /sys/bus/pci/devices/0000:03:00.1/sriov_numvfs
 218
 219
 220 #. Assign VF MAC address:
 221
 222    Assign MAC address to the VF using iproute2 utility. The syntax is::
 223
 224       ip link set <PF iface> vf <VF id> mac <macaddr>
 225
 226    Example output:
 227
 228    .. code-block:: console
 229
 230       ip link set p4p1 vf 0 mac F2:A8:1B:5E:B4:66
 231
 232
 233 #. Assign VF(s) to VM.
 234
 235    The VF devices may be passed through to the guest VM using qemu or
 236    virt-manager or virsh etc.
 237
 238    Example qemu guest launch command:
 239
 240    .. code-block:: console
 241
 242       ./qemu-system-x86_64 -name lio-vm -machine accel=kvm \
 243       -cpu host -m 4096 -smp 4 \
 244       -drive file=<disk_file>,if=none,id=disk1,format=<type> \
 245       -device virtio-blk-pci,scsi=off,drive=disk1,id=virtio-disk1,bootindex=1 \
 246       -device vfio-pci,host=03:00.3 -device vfio-pci,host=03:08.3
 247
 248
 249 #. Running testpmd
 250
 251    Refer :ref:`notes above <lio_driver-compilation>`
 252    to compile and run ``testpmd`` application.
 253    Use ``igb_uio`` instead of ``vfio-pci`` in VM.
 254
 255
 256 Limitations
 257 -----------
 258
 259 VF MTU
 260 ~~~~~~
 261
 262 VF MTU is limited by PF MTU. Raise PF value before configuring VF for larger packet size.
 263
 264 VLAN offload
 265 ~~~~~~~~~~~~
 266
 267 Tx VLAN insertion is not supported and consequently VLAN offload feature is
 268 marked partial.
 269
 270 Ring size
 271 ~~~~~~~~~
 272
 273 Number of descriptors for Rx/Tx ring should be in the range 128 to 512.
 274
 275 CRC striping
 276 ~~~~~~~~~~~~
 277
 278 LiquidIO adapters strip ethernet FCS of every packet coming to the host
 279 interface. So, CRC will be stripped even when the ``rxmode.hw_strip_crc``
 280 member is set to 0 in ``struct rte_eth_conf``.