From: Stephen Hemminger <sthem...@microsoft.com>
Matching documentation for new netvsc device.
Signed-off-by: Stephen Hemminger <sthem...@microsoft.com>
---
doc/guides/nics/features/netvsc.ini | 23 ++++++
doc/guides/nics/index.rst | 1 +
doc/guides/nics/netvsc.rst | 103 +++++++++++++++++++++++++
doc/guides/rel_notes/release_18_08.rst | 49 ++++++++++++
4 files changed, 176 insertions(+)
create mode 100644 doc/guides/nics/features/netvsc.ini
create mode 100644 doc/guides/nics/netvsc.rst
create mode 100644 doc/guides/rel_notes/release_18_08.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 ddb9eb7a922e..d4eae2b8f046 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..e81dc002f403
--- /dev/null
+++ b/doc/guides/nics/netvsc.rst
@@ -0,0 +1,103 @@
+.. 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.
+ This driver was originally added in 4.14 kernel, but that version lacks
necessary
+ features for networking. The 4.16 kernel will work but is limited to a
single queue.
+ Supporting multiple queues (subchannels) required additional changes
+ which will be added in 4.18.
diff --git a/doc/guides/rel_notes/release_18_08.rst
b/doc/guides/rel_notes/release_18_08.rst
new file mode 100644
index 000000000000..489b8fa276b9
--- /dev/null
+++ b/doc/guides/rel_notes/release_18_08.rst
@@ -0,0 +1,49 @@
+DPDK Release 18.08
+==================
+
+.. **Read this first.**
+
+ The text in the sections below explains how to update the release notes.
+
+ Use proper spelling, capitalization and punctuation in all sections.
+
+ Variable and config names should be quoted as fixed width text:
+ ``LIKE_THIS``.
+
+ Build the docs and view the output file to ensure the changes are correct::
+
+ make doc-guides-html
+
+ xdg-open build/doc/html/guides/rel_notes/release_18_05.html
+
+
+New Features
+------------
+
+.. This section should contain new features added in this release. Sample
+ format:
+
+ * **Add a title in the past tense with a full stop.**
+
+ Add a short 1-2 sentence description in the past tense. The description
+ should be enough to allow someone scanning the release notes to
+ understand the new feature.
+
+ If the feature adds a lot of sub-features you can use a bullet list like
+ this:
+
+ * Added feature foo to do something.
+ * Enhanced feature bar to do something else.
+
+ Refer to the previous release notes for examples.
+
+ This section is a comment. Do not overwrite or remove it.
+ Also, make sure to start the actual text at the margin.
+ =========================================================
+
+* **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.
+
--
2.17.0
