src/plugins/avf/README.md

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