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 ### Interface Creation
  79 Interfaces can be dynamically created by using following CLI:
  80 ```
  81 create interface avf 0000:3b:02.0
  82 set int state AVF0/3b/2/0 up
  83 ```
  84
  85 ### Interface Deletion
  86 Interface can be deleted with following CLI:
  87 ```
  88 delete interface avf <interface name>
  89 ```
  90
  91 ### Interface Statistics
  92 Interface statistics can be displayed with `sh hardware-interface <if-name>`
  93 command.
  94