1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) Microsoft Corporation. 3 4Netvsc poll mode driver 5======================= 6 7The Netvsc Poll Mode driver (PMD) provides support for the paravirtualized 8network device for Microsoft Hyper-V. It can be used with 9Window Server 2008/2012/2016, Windows 10. 10The device offers multi-queue support (if kernel and host support it), 11checksum and segmentation offloads. 12 13 14Features and Limitations of Hyper-V PMD 15--------------------------------------- 16 17In this release, the hyper PMD 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* This driver supports SR-IOV network acceleration. 38 If SR-IOV is enabled then the driver will transparently manage the interface, 39 and send and receive packets using the VF path. 40 The VDEV_NETVSC and FAILSAFE drivers are *not* used when using netvsc PMD. 41 42Installation 43------------ 44 45The Netvsc PMD is a standalone driver, similar to virtio and vmxnet3. 46Using Netvsc PMD requires that the associated VMBUS device be bound to the userspace 47I/O device driver for Hyper-V (uio_hv_generic). By default, all netvsc devices 48will be bound to the Linux kernel driver; in order to use netvsc PMD the 49device must first be overridden. 50 51The first step is to identify the network device to override. 52VMBUS uses Universal Unique Identifiers 53(`UUID`_) to identify devices on the bus similar to how PCI uses Domain:Bus:Function. 54The UUID associated with a Linux kernel network device can be determined 55by looking at the sysfs information. To find the UUID for eth1 and 56store it in a shell variable: 57 58 .. code-block:: console 59 60 DEV_UUID=$(basename $(readlink /sys/class/net/eth1/device)) 61 62 63.. _`UUID`: https://en.wikipedia.org/wiki/Universally_unique_identifier 64 65There are several possible ways to assign the UIO device driver for a device. 66The easiest way (but only on 4.18 or later) 67is to use the `driverctl Device Driver control utility`_ to override 68the normal kernel device. 69 70 .. code-block:: console 71 72 driverctl -b vmbus set-override $DEV_UUID uio_hv_generic 73 74.. _`driverctl Device Driver control utility`: https://gitlab.com/driverctl/driverctl 75 76Any settings done with driverctl are by default persistent and will be reapplied 77on reboot. 78 79On older kernels, the same effect can be had by manual sysfs bind and unbind 80operations: 81 82 .. code-block:: console 83 84 NET_UUID="f8615163-df3e-46c5-913f-f2d2f965ed0e" 85 modprobe uio_hv_generic 86 echo $NET_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/new_id 87 echo $DEV_UUID > /sys/bus/vmbus/drivers/hv_netvsc/unbind 88 echo $DEV_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/bind 89 90.. Note:: 91 92 The dpdk-devbind.py script can not be used since it only handles PCI devices. 93 94 95Prerequisites 96------------- 97 98The following prerequisites apply: 99 100* Linux kernel support for UIO on vmbus is done with the uio_hv_generic driver. 101 Full support of multiple queues requires the 4.17 kernel. It is possible 102 to use the netvsc PMD with 4.16 kernel but it is limited to a single queue. 103 104 105Runtime Configuration 106--------------------- 107 108The user can specify below argument in devargs. 109 110#. ``latency``: 111 112 A netvsc device uses a mailbox page to indicate to the host that there 113 is something in the transmit queue. The host scans this page at a 114 periodic interval. This parameter allows adjusting the value that 115 is used by the host. Smaller values improve transmit latency, and larger 116 values save CPU cycles. This parameter is in microseconds. 117 If the value is too large or too small it will be 118 ignored by the host. (Default: 50) 119 120#. ``rx_copybreak``: 121 122 The rx_copybreak sets the threshold where the driver uses an external 123 mbuf to avoid having to copy data. Setting 0 for copybreak will cause 124 driver to always create an external mbuf. Setting a value greater than 125 the MTU would prevent it from ever making an external mbuf and always 126 copy. The default value is 256 (bytes). 127 128#. ``tx_copybreak``: 129 130 The tx_copybreak sets the threshold where the driver aggregates 131 multiple small packets into one request. If tx_copybreak is 0 then 132 each packet goes as a VMBus request (no copying). If tx_copybreak is 133 set larger than the MTU, then all packets smaller than the chunk size 134 of the VMBus send buffer will be copied; larger packets always have to 135 go as a single direct request. The default value is 512 (bytes). 136 137#. ``rx_extmbuf_enable``: 138 The rx_extmbuf_enable is used to control if netvsc should use external 139 mbuf for receiving packets. The default value is 0. (netvsc doesn't use 140 external mbuf, it always allocates mbuf and copy received data to mbuf) 141 A non-zero value tells netvsc to attach external buffers to mbuf on 142 receiving packets, thus avoid copying memory. Use of external buffers 143 requires the application is able to read data from external mbuf. 144