doc/guides/vdpadevs/ifc.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 IFCVF vDPA driver
   5 =================
   6
   7 The IFCVF vDPA (vhost data path acceleration) driver provides support for the
   8 Intel FPGA 100G VF (IFCVF). IFCVF's datapath is virtio ring compatible, it
   9 works as a HW vhost backend which can send/receive packets to/from virtio
  10 directly by DMA. Besides, it supports dirty page logging and device state
  11 report/restore, this driver enables its vDPA functionality.
  12
  13
  14 Pre-Installation Configuration
  15 ------------------------------
  16
  17 Config File Options
  18 ~~~~~~~~~~~~~~~~~~~
  19
  20 The following option can be modified in the ``config`` file.
  21
  22 - ``CONFIG_RTE_LIBRTE_IFC_PMD`` (default ``y`` for linux)
  23
  24   Toggle compilation of the ``librte_pmd_ifc`` driver.
  25
  26
  27 IFCVF vDPA Implementation
  28 -------------------------
  29
  30 IFCVF's vendor ID and device ID are same as that of virtio net pci device,
  31 with its specific subsystem vendor ID and device ID. To let the device be
  32 probed by IFCVF driver, adding "vdpa=1" parameter helps to specify that this
  33 device is to be used in vDPA mode, rather than polling mode, virtio pmd will
  34 skip when it detects this message. If no this parameter specified, device
  35 will not be used as a vDPA device, and it will be driven by virtio pmd.
  36
  37 Different VF devices serve different virtio frontends which are in different
  38 VMs, so each VF needs to have its own DMA address translation service. During
  39 the driver probe a new container is created for this device, with this
  40 container vDPA driver can program DMA remapping table with the VM's memory
  41 region information.
  42
  43 The device argument "sw-live-migration=1" will configure the driver into SW
  44 assisted live migration mode. In this mode, the driver will set up a SW relay
  45 thread when LM happens, this thread will help device to log dirty pages. Thus
  46 this mode does not require HW to implement a dirty page logging function block,
  47 but will consume some percentage of CPU resource depending on the network
  48 throughput. If no this parameter specified, driver will rely on device's logging
  49 capability.
  50
  51 Key IFCVF vDPA driver ops
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 - ifcvf_dev_config:
  55   Enable VF data path with virtio information provided by vhost lib, including
  56   IOMMU programming to enable VF DMA to VM's memory, VFIO interrupt setup to
  57   route HW interrupt to virtio driver, create notify relay thread to translate
  58   virtio driver's kick to a MMIO write onto HW, HW queues configuration.
  59
  60   This function gets called to set up HW data path backend when virtio driver
  61   in VM gets ready.
  62
  63 - ifcvf_dev_close:
  64   Revoke all the setup in ifcvf_dev_config.
  65
  66   This function gets called when virtio driver stops device in VM.
  67
  68 To create a vhost port with IFC VF
  69 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  70
  71 - Create a vhost socket and assign a VF's device ID to this socket via
  72   vhost API. When QEMU vhost connection gets ready, the assigned VF will
  73   get configured automatically.
  74
  75
  76 Features
  77 --------
  78
  79 Features of the IFCVF driver are:
  80
  81 - Compatibility with virtio 0.95 and 1.0.
  82 - SW assisted vDPA live migration.
  83
  84
  85 Prerequisites
  86 -------------
  87
  88 - Platform with IOMMU feature. IFC VF needs address translation service to
  89   Rx/Tx directly with virtio driver in VM.
  90
  91
  92 Limitations
  93 -----------
  94
  95 Dependency on vfio-pci
  96 ~~~~~~~~~~~~~~~~~~~~~~
  97
  98 vDPA driver needs to setup VF MSIX interrupts, each queue's interrupt vector
  99 is mapped to a callfd associated with a virtio ring. Currently only vfio-pci
 100 allows multiple interrupts, so the IFCVF driver is dependent on vfio-pci.
 101
 102 Live Migration with VIRTIO_NET_F_GUEST_ANNOUNCE
 103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 104
 105 IFC VF doesn't support RARP packet generation, virtio frontend supporting
 106 VIRTIO_NET_F_GUEST_ANNOUNCE feature can help to do that.