src/plugins/avf/README.rst

   1 Intel AVF device driver
   2 =======================
   3
   4 Overview
   5 --------
   6
   7 This plugins provides native device support for intel Adaptive Virtual
   8 Function (AVF). AVF is driver specification for current and future Intel
   9 Virtual Function devices. AVF defines communication channel between
  10 Physical Functions (PF) and VF. In essence, today this driver can be
  11 used only with Intel XL710 / X710 / XXV710 adapters.
  12
  13 Prerequisites
  14 -------------
  15
  16 -  Driver requires newer i40e PF linux driver to be installed on the
  17    system, which supports virtualchnl interface. This code is tested
  18    with i40e driver version 2.4.6.
  19
  20 -  Driver requires MSI-X interrupt support, which is not supported by
  21    uio_pci_generic driver, so vfio-pci needs to be used. On systems
  22    without IOMMU vfio driver can still be used with recent kernels which
  23    support no-iommu mode.
  24
  25 Known issues
  26 ------------
  27
  28 This driver is still in experimental phase, however it shows very good
  29 performance numbers.
  30
  31 Usage
  32 -----
  33
  34 System setup
  35 ~~~~~~~~~~~~
  36
  37 1. load VFIO driver
  38
  39 ::
  40
  41    sudo modprobe vfio-pci
  42
  43 2. (systems without IOMMU only) enable unsafe NOIOMMU mode
  44
  45 ::
  46
  47    echo Y | sudo tee /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
  48
  49 3. Create and bind SR-IOV virtual function(s)
  50
  51 Following script creates VF, assigns MAC address and binds VF to
  52 vfio-pci
  53
  54 .. code:: bash
  55
  56    #!/bin/bash
  57
  58    if [ $USER != "root" ] ; then
  59        echo "Restarting script with sudo..."
  60        sudo $0 ${*}
  61        exit
  62    fi
  63
  64    setup () {
  65      cd /sys/bus/pci/devices/${1}
  66      driver=$(basename $(readlink driver))
  67      if [ "${driver}" != "i40e" ]; then
  68        echo ${1} | tee driver/unbind
  69        echo ${1} | tee /sys/bus/pci/drivers/i40e/bind
  70      fi
  71      ifname=$(basename net/*)
  72      echo 0 | tee sriov_numvfs > /dev/null
  73      echo 1 | tee sriov_numvfs > /dev/null
  74      ip link set dev ${ifname} vf 0 mac ${2}
  75      ip link show dev ${ifname}
  76      vf=$(basename $(readlink virtfn0))
  77      echo ${vf} | tee virtfn0/driver/unbind
  78      echo vfio-pci | tee virtfn0/driver_override
  79      echo ${vf} | sudo tee /sys/bus/pci/drivers/vfio-pci/bind
  80      echo  | tee virtfn0/driver_override
  81    }
  82
  83    # Setup one VF on PF 0000:3b:00.0 and assign MAC address
  84    setup 0000:3b:00.0 00:11:22:33:44:00
  85    # Setup one VF on PF 0000:3b:00.1 and assign MAC address
  86    setup 0000:3b:00.1 00:11:22:33:44:01
  87
  88 Promisc mode
  89 ~~~~~~~~~~~~
  90
  91 In cases when interface is used in the L2 mode or promisc mode is needed
  92 for some other reason, trust needs to be set to “on” using the linux “ip
  93 link” utility.
  94
  95 ::
  96
  97    ip link set dev <PF inteface name> vf <VF id> trust on
  98
  99 L2 spoofing check
 100 ~~~~~~~~~~~~~~~~~
 101
 102 By default Virtual Function is not allowed to send ethernet frames which
 103 have source MAC address different than address assigned to the VF. In
 104 some cases it is expected that VPP will send such frames (e.g. L2
 105 bridging, bonding, l2 cross-connect) and in such cases spoof check needs
 106 to be turned off by issuing following command:
 107
 108 ::
 109
 110    ip link set dev <PF inteface name> vf <VF id> spoofchk off
 111
 112 Interface Creation
 113 ~~~~~~~~~~~~~~~~~~
 114
 115 Interfaces can be dynamically created by using following CLI:
 116
 117 ::
 118
 119    create interface avf 0000:3b:02.0
 120    set int state avf-0/3b/2/0 up
 121
 122 Interface Deletion
 123 ~~~~~~~~~~~~~~~~~~
 124
 125 Interface can be deleted with following CLI:
 126
 127 ::
 128
 129    delete interface avf <interface name>
 130
 131 Interface Statistics
 132 ~~~~~~~~~~~~~~~~~~~~
 133
 134 Interface statistics can be displayed with
 135 ``sh hardware-interface <if-name>`` command.