doc/guides/nics/vdev_netvsc.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2017 6WIND S.A.
   3     Copyright 2017 Mellanox Technologies, Ltd
   4
   5 VDEV_NETVSC driver
   6 ==================
   7
   8 The VDEV_NETVSC driver (librte_pmd_vdev_netvsc) provides support for NetVSC
   9 interfaces and associated SR-IOV virtual function (VF) devices found in
  10 Linux virtual machines running on Microsoft Hyper-V_ (including Azure)
  11 platforms.
  12
  13 .. _Hyper-V: https://docs.microsoft.com/en-us/windows-hardware/drivers/network/overview-of-hyper-v
  14
  15 Implementation details
  16 ----------------------
  17
  18 Each instance of this driver effectively needs to drive two devices: the
  19 NetVSC interface proper and its SR-IOV VF (referred to as "physical" from
  20 this point on) counterpart sharing the same MAC address.
  21
  22 Physical devices are part of the host system and cannot be maintained during
  23 VM migration. From a VM standpoint they appear as hot-plug devices that come
  24 and go without prior notice.
  25
  26 When the physical device is present, egress and most of the ingress traffic
  27 flows through it; only multicasts and other hypervisor control still flow
  28 through NetVSC. Otherwise, NetVSC acts as a fallback for all traffic.
  29
  30 To avoid unnecessary code duplication and ensure maximum performance,
  31 handling of physical devices is left to their original PMDs; this virtual
  32 device driver (also known as *vdev*) manages other PMDs as summarized by the
  33 following block diagram::
  34
  35          .------------------.
  36          | DPDK application |
  37          `--------+---------'
  38                   |
  39            .------+------.
  40            | DPDK ethdev |
  41            `------+------'       Control
  42                   |                 |
  43      .------------+------------.    v    .--------------------.
  44      |       failsafe PMD      +---------+ vdev_netvsc driver |
  45      `--+-------------------+--'         `--------------------'
  46         |                   |
  47         |          .........|.........
  48         |          :        |        :
  49    .----+----.     :   .----+----.   :
  50    | tap PMD |     :   | any PMD |   :
  51    `----+----'     :   `----+----'   : <-- Hot-pluggable
  52         |          :        |        :
  53  .------+-------.  :  .-----+-----.  :
  54  | NetVSC-based |  :  | SR-IOV VF |  :
  55  |   netdevice  |  :  |   device  |  :
  56  `--------------'  :  `-----------'  :
  57                    :.................:
  58
  59
  60 This driver implementation may be temporary and should be improved or removed
  61 either when hot-plug will be fully supported in EAL and bus drivers or when
  62 a new NetVSC driver will be integrated.
  63
  64 Build options
  65 -------------
  66
  67 - ``CONFIG_RTE_LIBRTE_VDEV_NETVSC_PMD`` (default ``y``)
  68
  69    Toggle compilation of this driver.
  70
  71 Run-time parameters
  72 -------------------
  73
  74 This driver is invoked automatically in Hyper-V VM systems unless the user
  75 invoked it by command line using ``--vdev=net_vdev_netvsc`` EAL option.
  76
  77 The following device parameters are supported:
  78
  79 - ``iface`` [string]
  80
  81   Provide a specific NetVSC interface (netdevice) name to attach this driver
  82   to. Can be provided multiple times for additional instances.
  83
  84 - ``mac`` [string]
  85
  86   Same as ``iface`` except a suitable NetVSC interface is located using its
  87   MAC address.
  88
  89 - ``force`` [int]
  90
  91   If nonzero, forces the use of specified interfaces even if not detected as
  92   NetVSC.
  93
  94 - ``ignore`` [int]
  95
  96   If nonzero, ignores the driver running (actually used to disable the
  97   auto-detection in Hyper-V VM).
  98
  99 .. note::
 100
 101    Not specifying either ``iface`` or ``mac`` makes this driver attach itself to
 102    all unrouted NetVSC interfaces found on the system.
 103    Specifying the device makes this driver attach itself to the device
 104    regardless the device routes.