[ovs-dev] [PATCH v2 6/9] doc: Add "bridge" topic document

Stephen Finucane stephen at that.guru
Thu Apr 19 12:50:52 UTC 2018


On Wed, 2018-04-18 at 15:33 +0000, Stokes, Ian wrote:
> > This details configuration steps that apply to the entire bridge, rather
> > than individual ports.
> > 
> > Signed-off-by: Stephen Finucane <stephen at that.guru>
> > ---
> > 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:
> > -<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..63f8a62de
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/bridge.rst
> 
> Compilation error, bridge.rst not listed in Documentation/automake.mk.

Done.

> > @@ -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 <phy>` and `virtual <vhost-user>`
> > ports.
> 
> As mentioned earlier, you could add a link to the vdev doc here also.

This appears to be done already? See below.

> Ian
> > +
> > +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`.
> > +

Here ^^^

Stephen

> >  .. 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
> >  -------------
> > 
> > --
> > 2.14.3
> 
> 



More information about the dev mailing list