From patchwork Fri Jun 8 16:59:19 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Hemminger X-Patchwork-Id: 40881 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 9AA0A695D; Fri, 8 Jun 2018 18:59:34 +0200 (CEST) Received: from mail-pf0-f193.google.com (mail-pf0-f193.google.com [209.85.192.193]) by dpdk.org (Postfix) with ESMTP id 1A8B25B1C for ; Fri, 8 Jun 2018 18:59:31 +0200 (CEST) Received: by mail-pf0-f193.google.com with SMTP id j20-v6so6922171pff.10 for ; Fri, 08 Jun 2018 09:59:31 -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=qh5YbDOOVsOaAnZFWU33XaxhANR5NZ8fjWKoE9a+aKY=; b=GgOqxTZG6Uf/TOL1SzKMYFDg9R/AzDX1cfty0sbve6oGKBj1xgkRvlsb6Dp8itzKJY 0VT8SRYgW9ES0xotVZxs21SiM0jiyQBPALhKPsCKbZfU5MIc2QRoNAnEWG2pmYGlLVU7 qB/rSmH2svg+j6Gg3aGC6hOLBzaIKj1PhTSWbBrR5jTSwTgu9EU/oggbqlFGYOV+xLwO okebAF3jlwG5T4MQkyyxIzPm6a+Tf2pZz+DNCxwNw9kGHOpI+def7JYn9tUSJhBlQneB YSLg4VYj3x5C40XK/CnRM+fEdmOUKLxoV4dx3Ju/kq8VVozqmZ7PukHFnmgIvUF1BAl3 LPLQ== 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=qh5YbDOOVsOaAnZFWU33XaxhANR5NZ8fjWKoE9a+aKY=; b=L2HOvv7MaQlnLbU+uh5SB2uR7qo1ORpellu7iphOz/MzDBDlWPdGINbjJYY4OvwnMW lplANx2rwoLLrdjpJm1/Kf1Yzbk+SnHaI3fgo2btjGI86VE5XvJzM02KK6w12pwqHyqf xToyWjb8TMolIrRSirWm0B56hf22K+MCWJuOwrUoLnt8mHs4PmvwzoePnCgdrXoZquN8 ZSm7jhuiKt1qhjmvnUbfK27FoevAQx9/O8FfQQm9jTBUvpzX/sFFXG9rEwVuzgft9LIE M+xHnEfRBPMhWaQCMAk3VhPhF8zUnWYeimt4lMZS+uKtVZ2uoBzy9lSVc8zdjcrEKahU OZSw== X-Gm-Message-State: APt69E2p4UA9BXiv6EQxaaH6hfHFHvtwqwUh29nFjb7Y/rG6aqXUGce6 7Zwv8aLiTySlLtaQDVfXNUejxtFbuOw= X-Google-Smtp-Source: ADUXVKKAvoBh9OMdnGuKTCZdgxvmZZmlei+Pkfk13GSt6rUwL8O6gcoYyWBlEMxjqePB9migdBr9wQ== X-Received: by 2002:a62:4c04:: with SMTP id z4-v6mr6839108pfa.205.1528477169698; Fri, 08 Jun 2018 09:59:29 -0700 (PDT) Received: from xeon-e3.lan (204-195-35-107.wavecable.com. [204.195.35.107]) by smtp.gmail.com with ESMTPSA id k9-v6sm21921750pgs.49.2018.06.08.09.59.28 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 08 Jun 2018 09:59:28 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger Date: Fri, 8 Jun 2018 09:59:19 -0700 Message-Id: <20180608165920.12228-5-stephen@networkplumber.org> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20180608165920.12228-1-stephen@networkplumber.org> References: <20180608165920.12228-1-stephen@networkplumber.org> Subject: [dpdk-dev] [PATCH v10 4/5] 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" From: Stephen Hemminger Matching documentation for new netvsc device. Includes a brief note about the restart issue. Signed-off-by: Stephen Hemminger --- 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 | 22 ++++++ doc/guides/rel_notes/release_18_08.rst | 6 ++ 5 files changed, 153 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 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..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..17bb713e05c6 100644 --- a/doc/guides/rel_notes/known_issues.rst +++ b/doc/guides/rel_notes/known_issues.rst @@ -739,3 +739,25 @@ 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 5bc23c537371..49d56194e9c0 100644 --- a/doc/guides/rel_notes/release_18_08.rst +++ b/doc/guides/rel_notes/release_18_08.rst @@ -41,7 +41,13 @@ New Features 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. + + API Changes -----------