[ovs-dev] [PATCH 5/8] doc: Add "bridge" topic document

Stephen Finucane stephen at that.guru
Mon Apr 16 13:59:06 UTC 2018


On Mon, 2018-04-09 at 15:17 +0000, Stokes, Ian wrote:
> > This details configuration steps that apply to the entire bridge, rather
> > than individual ports.
> 
> Comments inline.
> 
> > 
> > Signed-off-by: Stephen Finucane <stephen at that.guru>
> > ---
> >  Documentation/howto/dpdk.rst         |  60 --------------------
> >  Documentation/topics/dpdk/bridge.rst | 103
> > +++++++++++++++++++++++++++++++++++
> >  Documentation/topics/dpdk/index.rst  |   1 +
> >  3 files changed, 104 insertions(+), 60 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/bridge.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 608dde814..c01bf7a39 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 unique set of
> > statistics.
> > -The Extended statistics are implemented and supported only for DPDK
> > physical -and vHost ports. Custom statistics are dynamic set of counters
> > which can -vary depenend on a 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:
> > -<https://wiki.opnfv.org/display/fastpath/Collectd+Metrics+and+Events>`__.
> > -
> > -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..307005f3b
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/bridge.rst
> > @@ -0,0 +1,103 @@
> > +..
> > +      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 <phy>` and `virtual <vhost-user>`
> > 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
> > +
> 
> I would suggest adding a link to this section in the
> Documentation/topics/dpdk/phy.rst and
> Documentation/topics/dpdk/vhost.rst before the examples of adding
> ports.
>
> As these are split out it's important to keep in mind a user may not
> know they require this particular bridge type before adding the dpdk
> ports.

Good idea. I've done this for all interface docs.

> I'm also not so sure that EMC and extended statistics belong here or
> warrant their own section. Again is it obvious to a user this is
> where to find them.

I'm not sure what the ask is here: is there a "not" missing (it is not
obvious)? Extended statistics could probably be moved to the PMD guide
but I'm not so sure on EMC. We could add a "fine-tuning" section but
I'm concerned that that would once again become a catch-all and allow
people to not think about structure. I've left this as-is for now.

Stephen

> Would be interested to hear peoples thoughts on this. 
> 
> Ian
> 
> > +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 unique set of
> > statistics.
> > +The Extended statistics are implemented and supported only for DPDK
> > +physical and vHost ports. Custom statistics are 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 fe4d97b8b..52cacaef6 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -28,6 +28,7 @@ The DPDK Datapath
> >  .. toctree::
> >     :maxdepth: 2
> > 
> > +   bridge
> >     phy
> >     vhost-user
> >     ring
> > --
> > 2.14.3
> > 
> > _______________________________________________
> > dev mailing list
> > dev at openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev



More information about the dev mailing list