DPDK patches and discussions
 help / color / mirror / Atom feed
From: Stephen Hemminger <stephen@networkplumber.org>
To: dev@dpdk.org
Cc: Stephen Hemminger <sthemmin@microsoft.com>
Subject: [dpdk-dev] [PATCH v3 3/4] net/netvsc: add documentation
Date: Tue, 17 Apr 2018 14:53:23 -0700	[thread overview]
Message-ID: <20180417215324.8576-4-sthemmin@microsoft.com> (raw)
In-Reply-To: <20180417215324.8576-1-sthemmin@microsoft.com>

Matching documentation for new netvsc device.

Signed-off-by: Stephen Hemminger <sthemmin@microsoft.com>
---
 doc/guides/nics/index.rst              |  1 +
 doc/guides/nics/netvsc.rst             | 97 ++++++++++++++++++++++++++
 doc/guides/rel_notes/release_18_05.rst |  6 ++
 3 files changed, 104 insertions(+)
 create mode 100644 doc/guides/nics/netvsc.rst

diff --git a/doc/guides/nics/index.rst b/doc/guides/nics/index.rst
index ea9110c81159..c5d19476bf68 100644
--- a/doc/guides/nics/index.rst
+++ b/doc/guides/nics/index.rst
@@ -32,6 +32,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..1b7f0333fd52
--- /dev/null
+++ b/doc/guides/nics/netvsc.rst
@@ -0,0 +1,97 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) Microsoft Corporation.
+
+Netvsc (Hyper-V) poll mode driver.
+================================================
+
+Hyper-V is a hypervisor integrated into Window Server 2008, Windows 10
+and later versions.  It supports a para-virtualized network interface
+called netvsc that is visible on the virtual machine bus (VMBUS).  In
+the Data Plane Development Kit (DPDK), we provide a Network Virtual
+Service Client (NetVSC) Poll Mode Driver (PMD). The NetVSC PMD
+supports Windows Server 2016 and Microsoft Azure cloud.
+
+NetVSC Implementation in DPDK
+-----------------------------
+
+The Netvsc PMD is a standalone driver. VMBus network devices that are
+being used by DPDK must be unbound from the Linux kernel driver
+(hv_netvsc) and bound to the Userspace IO driver for Hyper-V
+(uio_hv_generic).
+
+This is most conveniently done with the
+.. _`driverctl`: https://gitlab.com/driverctl/driverctl
+script.
+
+To list all VMBusus network devices:
+
+    .. code-block:: console
+
+	driverctl -b vmbus -v list-devices | grep netvsc
+
+
+To override default kernel device with DPDK uio it is necessary to first determine the GUID associated with a particular existing Ethernet device then pass that to ``driverctl``.
+
+    .. code-block:: console
+
+	GUID=$(basename $(readlink /sys/class/net/eth1/device))
+	driverctl -b vmbus set-override $GUID uio_hv_generic
+
+
+The kernel must be version 5.0 or later to allow driver_override to work. With older kernels ethernet must be rebound manually using sysfs bind and unbind.
+
+    .. code-block:: console
+
+	NET_GUID="f8615163-df3e-46c5-913f-f2d2f965ed0e"
+	DEV_GUID=$(basename $(readlink /sys/class/net/eth1/device))
+	modprobe uio_hv_generic
+	echo $NET_GUID > /sys/bus/vmbus/drivers/uio_hv_generic/new_id
+	echo $DEV_GUID > /sys/bus/vmbus/drivers/hv_netvsc/unbind
+	echo $DEV_GUID > /sys/bus/vmbus/drivers/uio_hv_generic/bind
+
+.. Note::
+
+   The dpkd-devbind.py script should not be used. It only handles PCI devices.
+
+
+
+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.
+
+*   It supports multicast packets and promiscuous mode. In order to this to work, the guest network
+    configuration on Hyper-V must be configured to allow this as well.
+
+*   Hyper-V driver does not support MAC or VLAN filtering because the host does not support it.
+    The device has only a single MAC address.
+
+*   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 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.
+
+
+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 were added in 5.0.
+
+*   VMBus uses Universal Unique Identifiers (UUID) to identify devices.
+    Therefore the netvsc and vmbus drivers require the libuuid library
+    to be installed.
diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst
index bc9cdda6af7a..0a7b65d49293 100644
--- a/doc/guides/rel_notes/release_18_05.rst
+++ b/doc/guides/rel_notes/release_18_05.rst
@@ -115,6 +115,12 @@ New Features
 
   Linux uevent is supported as backend of this device event notification framework.
 
+* **Added experimental support for Hyper-V netvsc PMD.**
+
+  The new experimntal ``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.17.0

  parent reply	other threads:[~2018-04-17 21:53 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-04-17 21:53 [dpdk-dev] [PATCH v3 0/4] Hyper-V Netvsc PMD Stephen Hemminger
2018-04-17 21:53 ` [dpdk-dev] [PATCH v3 1/4] bus/vmbus: add hyper-v virtual bus support Stephen Hemminger
2018-04-18 13:16   ` Ferruh Yigit
2018-04-18 16:01     ` Stephen Hemminger
2018-04-17 21:53 ` [dpdk-dev] [PATCH v3 2/4] net/netvsc: add hyper-v netvsc network device Stephen Hemminger
2018-04-18 13:19   ` Ferruh Yigit
2018-04-18 16:04     ` Stephen Hemminger
2018-04-18 17:36     ` Stephen Hemminger
2018-04-17 21:53 ` Stephen Hemminger [this message]
2018-04-18 13:25   ` [dpdk-dev] [PATCH v3 3/4] net/netvsc: add documentation Ferruh Yigit
2018-04-18 16:03     ` Stephen Hemminger
2018-04-18 16:16       ` Ferruh Yigit
2018-04-19 12:37         ` Hemant Agrawal
2018-04-17 21:53 ` [dpdk-dev] [PATCH v3 4/4] bus/vmbus and net/netvsc: add meson build support Stephen Hemminger
2018-04-18 13:25 ` [dpdk-dev] [PATCH v3 0/4] Hyper-V Netvsc PMD Ferruh Yigit

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20180417215324.8576-4-sthemmin@microsoft.com \
    --to=stephen@networkplumber.org \
    --cc=dev@dpdk.org \
    --cc=sthemmin@microsoft.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).