doc/guides/nics/netvsc.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) Microsoft Corporation.
   3
   4 Netvsc poll mode driver
   5 =======================
   6
   7 The Netvsc Poll Mode driver (PMD) provides support for the paravirtualized
   8 network device for Microsoft Hyper-V. It can be used with
   9 Window Server 2008/2012/2016, Windows 10.
  10 The device offers multi-queue support (if kernel and host support it),
  11 checksum and segmentation offloads.
  12
  13
  14 Features and Limitations of Hyper-V PMD
  15 ---------------------------------------
  16
  17 In this release, the hyper PMD driver provides the basic functionality of packet reception and transmission.
  18
  19 *   It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
  20     when transmitting packets. The packet size supported is from 64 to 65536.
  21
  22 *   The PMD supports multicast packets and promiscuous mode subject to restrictions on the host.
  23     In order to this to work, the guest network configuration on Hyper-V must be configured to allow MAC address
  24     spoofing.
  25
  26 *   The device has only a single MAC address.
  27     Hyper-V driver does not support MAC or VLAN filtering because the Hyper-V host does not support it.
  28
  29 *   VLAN tags are always stripped and presented in mbuf tci field.
  30
  31 *   The Hyper-V driver does not use or support interrupts. Link state change
  32     callback is done via change events in the packet ring.
  33
  34 *   The maximum number of queues is limited by the host (currently 64).
  35     When used with 4.16 kernel only a single queue is available.
  36
  37 .. note::
  38    This driver is intended for use with **Hyper-V only** and is
  39    not recommended for use on Azure because accelerated Networking
  40    (SR-IOV) is not supported.
  41
  42    On Azure, use the :doc:`vdev_netvsc` which
  43    automatically configures the necessary TAP and failsave drivers.
  44
  45
  46 Installation
  47 ------------
  48
  49 The Netvsc PMD is a standalone driver, similar to virtio and vmxnet3.
  50 Using Netvsc PMD requires that the associated VMBUS device be bound to the userspace
  51 I/O device driver for Hyper-V (uio_hv_generic). By default, all netvsc devices
  52 will be bound to the Linux kernel driver; in order to use netvsc PMD the
  53 device must first be overridden.
  54
  55 The first step is to identify the network device to override.
  56 VMBUS uses Universal Unique Identifiers
  57 (`UUID`_) to identify devices on the bus similar to how PCI uses Domain:Bus:Function.
  58 The UUID associated with a Linux kernel network device can be determined
  59 by looking at the sysfs information. To find the UUID for eth1 and
  60 store it in a shell variable:
  61
  62     .. code-block:: console
  63
  64         DEV_UUID=$(basename $(readlink /sys/class/net/eth1/device))
  65
  66
  67 .. _`UUID`: https://en.wikipedia.org/wiki/Universally_unique_identifier
  68
  69 There are several possible ways to assign the uio device driver for a device.
  70 The easiest way (but only on 4.18 or later)
  71 is to use the `driverctl Device Driver control utility`_ to override
  72 the normal kernel device.
  73
  74     .. code-block:: console
  75
  76         driverctl -b vmbus set-override $DEV_UUID uio_hv_generic
  77
  78 .. _`driverctl Device Driver control utility`: https://gitlab.com/driverctl/driverctl
  79
  80 Any settings done with driverctl are by default persistent and will be reapplied
  81 on reboot.
  82
  83 On older kernels, the same effect can be had by manual sysfs bind and unbind
  84 operations:
  85
  86     .. code-block:: console
  87
  88         NET_UUID="f8615163-df3e-46c5-913f-f2d2f965ed0e"
  89         modprobe uio_hv_generic
  90         echo $NET_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/new_id
  91         echo $DEV_UUID > /sys/bus/vmbus/drivers/hv_netvsc/unbind
  92         echo $DEV_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/bind
  93
  94 .. Note::
  95
  96    The dpkd-devbind.py script can not be used since it only handles PCI devices.
  97
  98
  99 Prerequisites
 100 -------------
 101
 102 The following prerequisites apply:
 103
 104 *   Linux kernel support for UIO on vmbus is done with the uio_hv_generic driver.
 105     Full support of multiple queues requires the 4.17 kernel. It is possible
 106     to use the netvsc PMD with 4.16 kernel but it is limited to a single queue.
 107
 108
 109 Netvsc PMD arguments
 110 --------------------
 111
 112 The user can specify below argument in devargs.
 113
 114 #.  ``latency``:
 115
 116     A netvsc device uses a mailbox page to indicate to the host that there
 117     is something in the transmit queue. The host scans this page at a
 118     periodic interval. This parameter allows adjusting the value that
 119     is used by the host. Smaller values improve transmit latency, and larger
 120     values save CPU cycles. This parameter is in microseconds.
 121     If the value is too large or too small it will be
 122     ignored by the host. (Default: 50)