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

Message ID 20180212181306.6674-6-stephen@that.guru
State Changes Requested
Delegated to: Ian Stokes
Headers show
Series
  • Split up the DPDK howto
Related show

Commit Message

Stephen Finucane Feb. 12, 2018, 6:13 p.m.
This details configuration steps that apply to the entire bridge, rather
than individual ports.

Signed-off-by: Stephen Finucane <stephen@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

Comments

Ian Stokes April 9, 2018, 3:17 p.m. | #1
> This details configuration steps that apply to the entire bridge, rather
> than individual ports.

Comments inline.

> 
> Signed-off-by: Stephen Finucane <stephen@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.

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.

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@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
Stephen Finucane April 16, 2018, 1:59 p.m. | #2
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@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@openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev
Ian Stokes April 17, 2018, 11:36 a.m. | #3
> 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@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.

Getting tied up in 'nots' here :). I suppose it's a general question regarding emc and extended statistics warranting their own documents. I'd be interested to hear others input on this. It's probably ok to keep them here for the time being.

Ian

> 
> 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@openvswitch.org
> > > https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Patch

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