From patchwork Wed Apr 18 17:56:40 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Hemminger X-Patchwork-Id: 38432 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 295207D01; Wed, 18 Apr 2018 20:05:23 +0200 (CEST) Received: from mail-pl0-f41.google.com (mail-pl0-f41.google.com [209.85.160.41]) by dpdk.org (Postfix) with ESMTP id B2DCB7CEF for ; Wed, 18 Apr 2018 20:05:19 +0200 (CEST) Received: by mail-pl0-f41.google.com with SMTP id e7-v6so1579316plt.6 for ; Wed, 18 Apr 2018 11:05:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=2dAdX4FKhpFW67kwJ9Scobk0STa/7p/6p8PX6fRP+Y4=; b=qtZvbD9LMDHDAbd2TTOZRbxZ6qrXoG4bwNczIcKmmj9xQS6sApjmd5iX9sJkg0UDcd KXeKbisPsf/Y3UGUTjaZDy8Dk9tJReYG/TkEHNDI5P22ALkx9q9I9ZBGXCEizisAjwWz H08aO0ZdgZiHyiZkiPJryk6rvwy/UBUr6osCFWfH+EVatMI30JWZOJDav4uUqXyZ7ZSj l1xNNgCJaF46NyKmPs+r1gCPcWVFa8npBrHdofIva2xX9UgNjxbUN3sozyfXaY1tv/iT z2AbcZ7dPj9zgZFuPZlxpKix+o1dIr9sPCILwh3VQDjwTrGj1UXgTjfow2ZsL1yruHHK cAkw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=2dAdX4FKhpFW67kwJ9Scobk0STa/7p/6p8PX6fRP+Y4=; b=LQm7RXm0iCxMxVRCqzM/r2VEuylsigfp9bMyFW7XXIaHdWrzp+ybQEQrOL98/Ngxhe 5jyJ69e4rLAgyy5MvzNDP9vRBrVkvEbaMENRUyiAPwpA2AFBqd7seO/57DYJrvpnygcM qaEGRl6uCgCyIxMVj8oHZ5XAOFCtxiR3PMdMuU1zSRYOmt3SAR6legYdQI3eqdnO89zN uszR+8r/VHeiqQg1jefHHDWF0nJ2w8c3H64ZT29XmGMRGNUZR8IP+bTWDxZb46x4lbtO tXJ5KTI3q8gZrEw+X4K0Hk/RoJjTprB06AwtvOsn4VBodvc/4X1TyY3Y+SK1yPvLEgmn vPDA== X-Gm-Message-State: ALQs6tC83JffouorN97oquKXJzKQXsQFh/cb8MQC1UA4iUuy8509Bfa1 QgjN3GurqI+JMgpG4o6Qfa+VYBnmkdY= X-Google-Smtp-Source: AIpwx49NimoS2oUugEWRrubnBRIHYs7tWZ6LrsD+wLHdUiASDQqg0iZ3jMKB8wTlYLuXZg2GUxPwoQ== X-Received: by 2002:a17:902:a506:: with SMTP id s6-v6mr2997605plq.191.1524074718098; Wed, 18 Apr 2018 11:05:18 -0700 (PDT) Received: from xeon-e3.lan (204-195-71-95.wavecable.com. [204.195.71.95]) by smtp.gmail.com with ESMTPSA id w10sm5259507pfk.26.2018.04.18.11.05.16 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 18 Apr 2018 11:05:17 -0700 (PDT) From: Stephen Hemminger X-Google-Original-From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger Date: Wed, 18 Apr 2018 10:56:40 -0700 Message-Id: <20180418175641.24051-4-sthemmin@microsoft.com> X-Mailer: git-send-email 2.17.0 In-Reply-To: <20180418175641.24051-1-sthemmin@microsoft.com> References: <20180418175641.24051-1-sthemmin@microsoft.com> Subject: [dpdk-dev] [PATCH v4 3/4] net/netvsc: add documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Matching documentation for new netvsc device. Signed-off-by: Stephen Hemminger --- doc/guides/nics/features/netvsc.ini | 23 ++++++ doc/guides/nics/index.rst | 1 + doc/guides/nics/netvsc.rst | 97 ++++++++++++++++++++++++++ doc/guides/rel_notes/release_18_05.rst | 6 ++ 4 files changed, 127 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 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 290fa0940933..47708ab47df3 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 -----------