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

Stokes, Ian ian.stokes at intel.com
Wed Apr 18 15:33:31 UTC 2018


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

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

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