[PATCH v12 4/4] net/netvsc: add documentation

[Stephen Hemminger <stephen@networkplumber.org>]

From: Stephen Hemminger <sthemmin@microsoft.com>

Matching documentation for new netvsc device.
Includes a brief note about the restart issue.

Signed-off-by: Stephen Hemminger <sthemmin@microsoft.com>
---
 doc/guides/nics/features/netvsc.ini    |  23 ++++++
 doc/guides/nics/index.rst              |   1 +
 doc/guides/nics/netvsc.rst             | 101 +++++++++++++++++++++++++
 doc/guides/rel_notes/known_issues.rst  |  20 +++++
 doc/guides/rel_notes/release_18_08.rst |   6 ++
 5 files changed, 151 insertions(+)
 create mode 100644 doc/guides/nics/features/netvsc.ini
 create mode 100644 doc/guides/nics/netvsc.rst

diff --git a/doc/guides/nics/features/netvsc.ini b/doc/guides/nics/features/netvsc.ini
new file mode 100644
index 000000000000..2ff6042bf47b
--- /dev/null
+++ b/doc/guides/nics/features/netvsc.ini
@@ -0,0 +1,23 @@
+;
+; Supported features of the 'netvsc' network poll mode driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+Speed capabilities   = P
+Link status          = Y
+Queue start/stop     = Y
+Scattered Rx         = Y
+Promiscuous mode     = Y
+Allmulticast mode    = Y
+Basic stats          = Y
+Stats per queue      = Y
+Extended stats       = Y
+Multiprocess aware   = Y
+Other kdrv           = Y
+ARMv7                = Y
+ARMv8                = Y
+x86-32               = Y
+x86-64               = Y
+Usage doc            = Y
+MTU update           = Y
diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index d68c5ed5ea1a..e9e7f74ce7ff 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -33,6 +33,7 @@ Network Interface Controller Drivers
     mlx4
     mlx5
     mvpp2
+    netvsc
     nfp
     octeontx
     qede
diff --git a/doc/guides/nics/netvsc.rst b/doc/guides/nics/netvsc.rst
new file mode 100644
index 000000000000..0f033e3a3d63
--- /dev/null
+++ b/doc/guides/nics/netvsc.rst
@@ -0,0 +1,101 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) Microsoft Corporation.
+
+Netvsc poll mode driver
+=======================
+
+The Netvsc Poll Mode driver (PMD) provides support for the paravirtualized
+network device for Microsoft Hyper-V. It can be used with
+Window Server 2008/2012/2016, Windows 10 and Azure cloud.
+The device offers multi-queue support (if kernel and host support it),
+checksum and segmentation offloads.
+
+
+Features and Limitations of Hyper-V PMD
+---------------------------------------
+
+In this release, the hyper PMD driver provides the basic functionality of packet reception and transmission.
+
+*   It supports merge-able buffers per packet when receiving packets and scattered buffer per packet
+    when transmitting packets. The packet size supported is from 64 to 65536.
+
+*   The PMD supports multicast packets and promiscuous mode subject to restrictions on the host.
+    In order to this to work, the guest network configuration on Hyper-V must be configured to allow MAC address
+    spoofing. This option is not available on Azure.
+
+*   The device has only a single MAC address.
+    Hyper-V driver does not support MAC or VLAN filtering because the Hyper-V host does not support it.
+
+*   VLAN tags are always stripped and presented in mbuf tci field.
+
+*   The Hyper-V driver does not use or support Link State or Rx interrupt.
+
+*   The maximum number of queues is limited by the host (currently 64).
+    When used with 4.16 kernel only a single queue is available.
+
+*   This driver is intended for use with synthetic path only.
+    Accelerated Networking (SR-IOV) acceleration is not supported yet.
+    Use the VDEV_NETVSC device for accelerated networking instead.
+
+
+Installation
+------------
+
+The Netvsc PMD is a standalone driver, similar to virtio and vmxnet3.
+Using Netvsc PMD requires that the associated VMBUS device be bound to the userspace
+I/O device driver for Hyper-V (uio_hv_generic). By default, all netvsc devices
+will be bound to the Linux kernel driver; in order to use netvsc PMD the
+device must first be overridden.
+
+The first step is to identify the network device to override.
+VMBUS uses Universal Unique Identifiers
+(`UUID`_) to identify devices on the bus similar to how PCI uses Domain:Bus:Function.
+The UUID associated with a Linux kernel network device can be determined
+by looking at the sysfs information. To find the UUID for eth1 and
+store it in a shell variable:
+
+    .. code-block:: console
+
+	DEV_UUID=$(basename $(readlink /sys/class/net/eth1/device))
+
+
+.. _`UUID`: https://en.wikipedia.org/wiki/Universally_unique_identifier
+
+There are several possible ways to assign the uio device driver for a device.
+The easiest way (but only on 4.18 or later)
+is to use the `driverctl Device Driver control utility`_ to override
+the normal kernel device.
+
+    .. code-block:: console
+
+	driverctl -b vmbus set-override $DEV_UUID uio_hv_generic
+
+.. _`driverctl Device Driver control utility`: https://gitlab.com/driverctl/driverctl
+
+Any settings done with driverctl are by default persistent and will be reapplied
+on reboot.
+
+On older kernels, the same effect can be had by manual sysfs bind and unbind
+operations:
+
+    .. code-block:: console
+
+	NET_UUID="f8615163-df3e-46c5-913f-f2d2f965ed0e"
+	modprobe uio_hv_generic
+	echo $NET_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/new_id
+	echo $DEV_UUID > /sys/bus/vmbus/drivers/hv_netvsc/unbind
+	echo $DEV_UUID > /sys/bus/vmbus/drivers/uio_hv_generic/bind
+
+.. Note::
+
+   The dpkd-devbind.py script should not be used. It only handles PCI devices.
+
+
+Prerequisites
+-------------
+
+The following prerequisites apply:
+
+*   Linux kernel support for UIO on vmbus is done with the uio_hv_generic driver.
+    Full support of multiple queues requires the 4.17 kernel. It is possible
+    to use the netvsc PMD with 4.16 kernel but it is limited to a single queue.
diff --git a/doc/guides/rel_notes/known_issues.rst b/doc/guides/rel_notes/known_issues.rst
index 716bd7360949..95e4ce693e45 100644
--- a/doc/guides/rel_notes/known_issues.rst
+++ b/doc/guides/rel_notes/known_issues.rst
@@ -739,3 +739,23 @@ Linux kernel 4.10.0 iommu attribute read error
 
 **Driver/Module**:
    ``vfio-pci`` module.
+
+Netvsc driver and application restart
+-------------------------------------
+
+**Description**:
+   The Linux kernel uio_hv_generic driver does not completely shutdown and clean up
+   resources properly if application using Netvsc PMD exits.
+
+**Implication**:
+   When application using Netvsc PMD is restarted it can not complete initialization
+   handshake sequence with the host.
+
+**Resolution/Workaround**:
+   Either reboot the guest or remove and reinsert the hv_uio_generic module.
+
+**Affected Environment/Platform**:
+   Linux Hyper-V.
+
+**Driver/Module**:
+   ``uio_hv_generic`` module.
diff --git a/doc/guides/rel_notes/release_18_08.rst b/doc/guides/rel_notes/release_18_08.rst
index 1274c9210c0c..e4a041a46d2f 100644
--- a/doc/guides/rel_notes/release_18_08.rst
+++ b/doc/guides/rel_notes/release_18_08.rst
@@ -68,6 +68,12 @@ New Features
   * Add handlers to add/delete VxLAN port number.
   * Add devarg to specify ingress VLAN rewrite mode.
 
+* **Added support for Hyper-V netvsc PMD.**
+
+  The new ``netvsc`` poll mode driver provides native support for
+  networking on Hyper-V. See the :doc:`../nics/netvsc` NIC driver guide
+  for more details on this new driver.
+
 
 API Changes
 -----------
-- 
2.18.0