From patchwork Mon Apr 16 14:30:23 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 898659 X-Patchwork-Delegate: ian.stokes@intel.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="oy6D0ha5"; dkim-atps=neutral Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 40Prb04zyMz9s1l for ; Tue, 17 Apr 2018 00:38:04 +1000 (AEST) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id AA469EF7; Mon, 16 Apr 2018 14:30:55 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 7E460EA4 for ; Mon, 16 Apr 2018 14:30:52 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from anteater.ash.relay.mailchannels.net (anteater.ash.relay.mailchannels.net [23.83.222.3]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 5A28A477 for ; Mon, 16 Apr 2018 14:30:49 +0000 (UTC) X-Sender-Id: 5xi41l16bi|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 9C426280946; Mon, 16 Apr 2018 14:30:43 +0000 (UTC) Received: from one.mxroute.com (unknown [100.96.13.37]) (Authenticated sender: 5xi41l16bi) by relay.mailchannels.net (Postfix) with ESMTPA id 0CDCC280A05; Mon, 16 Apr 2018 14:30:42 +0000 (UTC) X-Sender-Id: 5xi41l16bi|x-authuser|stephen@that.guru Received: from one.mxroute.com (one-outgoing.mxroute.com [172.19.61.140]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.14.1); Mon, 16 Apr 2018 14:30:43 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: 5xi41l16bi|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: 5xi41l16bi X-Chief-Print: 4198c83575087578_1523889043536_398652349 X-MC-Loop-Signature: 1523889043536:2138522491 X-MC-Ingress-Time: 1523889043535 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=MDJfFCuXuGR1dW0k9p7o9GJnn8SGWwwtWjg6KMADC+E=; b=oy6D0ha58d5VwLJ9onRzINCAfw hIJHkeiSu8u5z4O0ATZL5vUwBuUqba5AwpY+L+sI//M9odInat/ec6VtVlH/IdpxbLrBORfiqeuGU uCrW562sEE8sY0SjrvvmdpOwBSz8r+RNH+F7WkjBdobMOQ9/J/G7b2gvwiV8n6PUMeSL3GydDWdnE cMHm3JloKf54HLm91QlUegSa6aZVG+o1iGjqpl2a9Ly+EncDoPNtWjLU0UfWRBp66y+o8I4+o7ytl 0ZMGQEAwaMAKGrHGU2yM3VVhI5Q6reVjBMmma0O1iObn5jIEDbiGUplr1tejLTJSmGV50E5XfeTR7 DefvCuOw==; From: Stephen Finucane To: dev@openvswitch.org Date: Mon, 16 Apr 2018 15:30:23 +0100 Message-Id: <20180416143026.24561-7-stephen@that.guru> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180416143026.24561-1-stephen@that.guru> References: <20180416143026.24561-1-stephen@that.guru> X-AuthUser: stephen@that.guru X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_NONE,T_DKIM_INVALID autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [PATCH v2 6/9] doc: Add "bridge" topic document X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org This details configuration steps that apply to the entire bridge, rather than individual ports. Signed-off-by: Stephen Finucane --- v2: - Cross-reference this document from all interface documents --- Documentation/howto/dpdk.rst | 60 ------------------ Documentation/topics/dpdk/bridge.rst | 104 +++++++++++++++++++++++++++++++ Documentation/topics/dpdk/index.rst | 1 + Documentation/topics/dpdk/phy.rst | 5 ++ Documentation/topics/dpdk/ring.rst | 5 ++ Documentation/topics/dpdk/vdev.rst | 5 ++ Documentation/topics/dpdk/vhost-user.rst | 5 ++ 7 files changed, 125 insertions(+), 60 deletions(-) create mode 100644 Documentation/topics/dpdk/bridge.rst diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst index 3e04d8627..b3cba19b2 100644 --- a/Documentation/howto/dpdk.rst +++ b/Documentation/howto/dpdk.rst @@ -170,66 +170,6 @@ largest frame size supported by Fortville NIC using the DPDK i40e driver, but larger frames and other DPDK NIC drivers may be supported. These cases are common for use cases involving East-West traffic only. -.. _extended-statistics: - -Extended & Custom Statistics ----------------------------- - -DPDK Extended Statistics API allows PMD to expose a unique set of statistics. -The Extended Statistics are implemented and supported only for DPDK physical -and vHost ports. Custom statistics are a dynamic set of counters which can -vary depending on the driver. Those statistics are implemented -for DPDK physical ports and contain all "dropped", "error" and "management" -counters from XSTATS. XSTATS counters list can be found here: -`__. - -To enable statistics, you have to enable OpenFlow 1.4 support for OVS. -Configure bridge br0 to support OpenFlow version 1.4:: - - $ ovs-vsctl set bridge br0 datapath_type=netdev \ - protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14 - -Check the OVSDB protocols column in the bridge table if OpenFlow 1.4 support -is enabled for OVS:: - - $ ovsdb-client dump Bridge protocols - -Query the port statistics by explicitly specifying -O OpenFlow14 option:: - - $ ovs-ofctl -O OpenFlow14 dump-ports br0 - -Note about "Extended Statistics": vHost ports supports only partial -statistics. RX packet size based counter are only supported and -doesn't include TX packet size counters. - -EMC Insertion Probability -------------------------- -By default 1 in every 100 flows are inserted into the Exact Match Cache (EMC). -It is possible to change this insertion probability by setting the -``emc-insert-inv-prob`` option:: - - $ ovs-vsctl --no-wait set Open_vSwitch . other_config:emc-insert-inv-prob=N - -where: - -``N`` - is a positive integer representing the inverse probability of insertion ie. - on average 1 in every N packets with a unique flow will generate an EMC - insertion. - -If ``N`` is set to 1, an insertion will be performed for every flow. If set to -0, no insertions will be performed and the EMC will effectively be disabled. - -With default ``N`` set to 100, higher megaflow hits will occur initially -as observed with pmd stats:: - - $ ovs-appctl dpif-netdev/pmd-stats-show - -For certain traffic profiles with many parallel flows, it's recommended to set -``N`` to '0' to achieve higher forwarding performance. - -For more information on the EMC refer to :doc:`/intro/install/dpdk` . - .. _dpdk-ovs-in-guest: OVS with DPDK Inside VMs diff --git a/Documentation/topics/dpdk/bridge.rst b/Documentation/topics/dpdk/bridge.rst new file mode 100644 index 000000000..63f8a62de --- /dev/null +++ b/Documentation/topics/dpdk/bridge.rst @@ -0,0 +1,104 @@ +.. + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +============ +DPDK Bridges +============ + +The DPDK datapath requires specially configured bridge(s) in order to utilize +DPDK-backed :doc:`physical ` and `virtual ` ports. + +Quick Example +------------- + +This example demonstrates how to add a bridge using the DPDK datapath:: + + $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev + +This assumes Open vSwitch has been built with DPDK support. Refer to +:doc:`/intro/install/dpdk` for more information. + +.. _extended-statistics: + +Extended & Custom Statistics +---------------------------- + +The DPDK Extended Statistics API allows PMDs to expose a unique set of +statistics. The Extended Statistics are implemented and supported only for +DPDK physical and vHost ports. Custom statistics are a dynamic set of counters +which can vary depending on the driver. Those statistics are implemented for +DPDK physical ports and contain all "dropped", "error" and "management" +counters from ``XSTATS``. A list of all ``XSTATS`` counters can be found +`here`__. + +__ https://wiki.opnfv.org/display/fastpath/Collectd+Metrics+and+Events + +.. note:: + + vHost ports only support RX packet size-based counters. TX packet size + counters are not available. + +To enable statistics, you have to enable OpenFlow 1.4 support for OVS. To +configure a bridge, ``br0``, to support OpenFlow version 1.4, run:: + + $ ovs-vsctl set bridge br0 datapath_type=netdev \ + protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14 + +Once configured, check the OVSDB protocols column in the bridge table to ensure +OpenFlow 1.4 support is enabled:: + + $ ovsdb-client dump Bridge protocols + +You can also query the port statistics by explicitly specifying the ``-O +OpenFlow14`` option:: + + $ ovs-ofctl -O OpenFlow14 dump-ports br0 + +EMC Insertion Probability +------------------------- + +By default 1 in every 100 flows is inserted into the Exact Match Cache (EMC). +It is possible to change this insertion probability by setting the +``emc-insert-inv-prob`` option:: + + $ ovs-vsctl --no-wait set Open_vSwitch . other_config:emc-insert-inv-prob=N + +where: + +``N`` + A positive integer representing the inverse probability of insertion, i.e. on + average 1 in every ``N`` packets with a unique flow will generate an EMC + insertion. + +If ``N`` is set to 1, an insertion will be performed for every flow. If set to +0, no insertions will be performed and the EMC will effectively be disabled. + +With default ``N`` set to 100, higher megaflow hits will occur initially as +observed with pmd stats:: + + $ ovs-appctl dpif-netdev/pmd-stats-show + +For certain traffic profiles with many parallel flows, it's recommended to set +``N`` to '0' to achieve higher forwarding performance. + +For more information on the EMC refer to :doc:`/intro/install/dpdk` . diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst index d3c1e2099..fd7cf38b5 100644 --- a/Documentation/topics/dpdk/index.rst +++ b/Documentation/topics/dpdk/index.rst @@ -31,6 +31,7 @@ The DPDK Datapath .. toctree:: :maxdepth: 2 + /topics/dpdk/bridge /topics/dpdk/phy /topics/dpdk/vhost-user /topics/dpdk/ring diff --git a/Documentation/topics/dpdk/phy.rst b/Documentation/topics/dpdk/phy.rst index 581984b63..c0931b2c4 100644 --- a/Documentation/topics/dpdk/phy.rst +++ b/Documentation/topics/dpdk/phy.rst @@ -30,6 +30,11 @@ DPDK Physical Ports The netdev datapath allows attaching of DPDK-backed physical interfaces in order to provide high-performance ingress/egress from the host. +.. important:: + + To use any DPDK-backed interface, you must ensure your bridge is configured + correctly. For more information, refer to :doc:`bridge`. + .. versionchanged:: 2.7.0 Before Open vSwitch 2.7.0, it was necessary to prefix port names with a diff --git a/Documentation/topics/dpdk/ring.rst b/Documentation/topics/dpdk/ring.rst index 8e8fb6088..9ef1dc3a5 100644 --- a/Documentation/topics/dpdk/ring.rst +++ b/Documentation/topics/dpdk/ring.rst @@ -36,6 +36,11 @@ The DPDK datapath provides DPDK-backed ring ports that are implemented using DPDK's ``librte_ring`` library. For more information on this library, refer to the `DPDK documentation`_. +.. important:: + + To use any DPDK-backed interface, you must ensure your bridge is configured + correctly. For more information, refer to :doc:`bridge`. + Quick Example ------------- diff --git a/Documentation/topics/dpdk/vdev.rst b/Documentation/topics/dpdk/vdev.rst index 1b00ac573..19b41a328 100644 --- a/Documentation/topics/dpdk/vdev.rst +++ b/Documentation/topics/dpdk/vdev.rst @@ -32,6 +32,11 @@ devices are added to OVS by specifying a valid PCI address in ``dpdk-devargs``. Virtual DPDK devices which do not have PCI addresses can be added using a different format for ``dpdk-devargs``. +.. important:: + + To use any DPDK-backed interface, you must ensure your bridge is configured + correctly. For more information, refer to :doc:`bridge`. + .. note:: Not all DPDK virtual PMD drivers have been tested and verified to work. diff --git a/Documentation/topics/dpdk/vhost-user.rst b/Documentation/topics/dpdk/vhost-user.rst index 6f794f296..168d5c5ce 100644 --- a/Documentation/topics/dpdk/vhost-user.rst +++ b/Documentation/topics/dpdk/vhost-user.rst @@ -29,6 +29,11 @@ The DPDK datapath provides DPDK-backed vHost user ports as a primary way to interact with guests. For more information on vHost User, refer to the `QEMU documentation`_ on same. +.. important:: + + To use any DPDK-backed interface, you must ensure your bridge is configured + correctly. For more information, refer to :doc:`bridge`. + Quick Example -------------