]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
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 | ||
9f95a23c TL |
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. | |
11fdf7f2 TL |
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 | ||
9f95a23c TL |
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. | |
11fdf7f2 TL |
41 | |
42 | Installation | |
43 | ------------ | |
44 | ||
45 | The Netvsc PMD is a standalone driver, similar to virtio and vmxnet3. | |
46 | Using Netvsc PMD requires that the associated VMBUS device be bound to the userspace | |
47 | I/O device driver for Hyper-V (uio_hv_generic). By default, all netvsc devices | |
48 | will be bound to the Linux kernel driver; in order to use netvsc PMD the | |
49 | device must first be overridden. | |
50 | ||
51 | The first step is to identify the network device to override. | |
52 | VMBUS uses Universal Unique Identifiers | |
53 | (`UUID`_) to identify devices on the bus similar to how PCI uses Domain:Bus:Function. | |
54 | The UUID associated with a Linux kernel network device can be determined | |
55 | by looking at the sysfs information. To find the UUID for eth1 and | |
56 | store 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 | ||
65 | There are several possible ways to assign the uio device driver for a device. | |
66 | The easiest way (but only on 4.18 or later) | |
67 | is to use the `driverctl Device Driver control utility`_ to override | |
68 | the 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 | ||
76 | Any settings done with driverctl are by default persistent and will be reapplied | |
77 | on reboot. | |
78 | ||
79 | On older kernels, the same effect can be had by manual sysfs bind and unbind | |
80 | operations: | |
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 | ||
9f95a23c | 92 | The dpdk-devbind.py script can not be used since it only handles PCI devices. |
11fdf7f2 TL |
93 | |
94 | ||
95 | Prerequisites | |
96 | ------------- | |
97 | ||
98 | The 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. | |
9f95a23c TL |
103 | |
104 | ||
105 | Netvsc PMD arguments | |
106 | -------------------- | |
107 | ||
108 | The 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) |