doc/guides/nics/liquidio.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Cavium, Inc
   3
   4 LiquidIO VF Poll Mode Driver
   5 ============================
   6
   7 The LiquidIO VF PMD library (librte_pmd_lio) provides poll mode driver support for
   8 Cavium LiquidIO® II server adapter VFs. PF management and VF creation can be
   9 done using kernel driver.
  10
  11 More information can be found at `Cavium Official Website
  12 <http://cavium.com/LiquidIO_Adapters.html>`_.
  13
  14 Supported LiquidIO Adapters
  15 -----------------------------
  16
  17 - LiquidIO II CN2350 210SV/225SV
  18 - LiquidIO II CN2350 210SVPT
  19 - LiquidIO II CN2360 210SV/225SV
  20 - LiquidIO II CN2360 210SVPT
  21
  22
  23 SR-IOV: Prerequisites and Sample Application Notes
  24 --------------------------------------------------
  25
  26 This section provides instructions to configure SR-IOV with Linux OS.
  27
  28 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
  29
  30    .. code-block:: console
  31
  32       lspci -s <slot> -vvv
  33
  34    Example output:
  35
  36    .. code-block:: console
  37
  38       [...]
  39       Capabilities: [148 v1] Alternative Routing-ID Interpretation (ARI)
  40       [...]
  41       Capabilities: [178 v1] Single Root I/O Virtualization (SR-IOV)
  42       [...]
  43       Kernel driver in use: LiquidIO
  44
  45 #. Load the kernel module:
  46
  47    .. code-block:: console
  48
  49       modprobe liquidio
  50
  51 #. Bring up the PF ports:
  52
  53    .. code-block:: console
  54
  55       ifconfig p4p1 up
  56       ifconfig p4p2 up
  57
  58 #. Change PF MTU if required:
  59
  60    .. code-block:: console
  61
  62       ifconfig p4p1 mtu 9000
  63       ifconfig p4p2 mtu 9000
  64
  65 #. Create VF device(s):
  66
  67    Echo number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
  68    of the parent PF.
  69
  70    .. code-block:: console
  71
  72       echo 1 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
  73       echo 1 > /sys/bus/pci/devices/0000:03:00.1/sriov_numvfs
  74
  75 #. Assign VF MAC address:
  76
  77    Assign MAC address to the VF using iproute2 utility. The syntax is::
  78
  79       ip link set <PF iface> vf <VF id> mac <macaddr>
  80
  81    Example output:
  82
  83    .. code-block:: console
  84
  85       ip link set p4p1 vf 0 mac F2:A8:1B:5E:B4:66
  86
  87 #. Assign VF(s) to VM.
  88
  89    The VF devices may be passed through to the guest VM using qemu or
  90    virt-manager or virsh etc.
  91
  92    Example qemu guest launch command:
  93
  94    .. code-block:: console
  95
  96       ./qemu-system-x86_64 -name lio-vm -machine accel=kvm \
  97       -cpu host -m 4096 -smp 4 \
  98       -drive file=<disk_file>,if=none,id=disk1,format=<type> \
  99       -device virtio-blk-pci,scsi=off,drive=disk1,id=virtio-disk1,bootindex=1 \
 100       -device vfio-pci,host=03:00.3 -device vfio-pci,host=03:08.3
 101
 102 #. Running testpmd
 103
 104    Refer to the document
 105    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 106    ``testpmd`` application.
 107
 108    .. note::
 109
 110       Use ``igb_uio`` instead of ``vfio-pci`` in VM.
 111
 112    Example output:
 113
 114    .. code-block:: console
 115
 116       [...]
 117       EAL: PCI device 0000:03:00.3 on NUMA socket 0
 118       EAL:   probe driver: 177d:9712 net_liovf
 119       EAL:   using IOMMU type 1 (Type 1)
 120       PMD: net_liovf[03:00.3]INFO: DEVICE : CN23XX VF
 121       EAL: PCI device 0000:03:08.3 on NUMA socket 0
 122       EAL:   probe driver: 177d:9712 net_liovf
 123       PMD: net_liovf[03:08.3]INFO: DEVICE : CN23XX VF
 124       Interactive-mode selected
 125       USER1: create a new mbuf pool <mbuf_pool_socket_0>: n=171456, size=2176, socket=0
 126       Configuring Port 0 (socket 0)
 127       PMD: net_liovf[03:00.3]INFO: Starting port 0
 128       Port 0: F2:A8:1B:5E:B4:66
 129       Configuring Port 1 (socket 0)
 130       PMD: net_liovf[03:08.3]INFO: Starting port 1
 131       Port 1: 32:76:CC:EE:56:D7
 132       Checking link statuses...
 133       Port 0 Link Up - speed 10000 Mbps - full-duplex
 134       Port 1 Link Up - speed 10000 Mbps - full-duplex
 135       Done
 136       testpmd>
 137
 138 #. Enabling VF promiscuous mode
 139
 140    One VF per PF can be marked as trusted for promiscuous mode.
 141
 142    .. code-block:: console
 143
 144       ip link set dev <PF iface> vf <VF id> trust on
 145
 146
 147 Limitations
 148 -----------
 149
 150 VF MTU
 151 ~~~~~~
 152
 153 VF MTU is limited by PF MTU. Raise PF value before configuring VF for larger packet size.
 154
 155 VLAN offload
 156 ~~~~~~~~~~~~
 157
 158 Tx VLAN insertion is not supported and consequently VLAN offload feature is
 159 marked partial.
 160
 161 Ring size
 162 ~~~~~~~~~
 163
 164 Number of descriptors for Rx/Tx ring should be in the range 128 to 512.
 165
 166 CRC stripping
 167 ~~~~~~~~~~~~~
 168
 169 LiquidIO adapters strip ethernet FCS of every packet coming to the host interface.