Re: [ovs-dev] [PATCH 1/2] doc: Fix cropped what-is-ovs page.

[Stephen Finucane]

On Thu, 2019-05-16 at 16:40 +0300, Ilya Maximets wrote:
> Despite of comments in both files no-one ever adjusted start/end-line
> in 'what-is-ovs' document. As a result, current document contains
> truncated "tools" section.
> 
> Let's replace start/end-line with start-after/end-before which requires
> less attention. Additionally, 'make docs-check' will fail if specified
> lines will not be found, i.e it'll be harder to mess up the docs again.
> 
> "Fixes" tag points to commit that broke the lines first.
> 
> Fixes: 602e24ee189b ("doc: Remove experimental warning for DPDK.")
> Signed-off-by: Ilya Maximets 

Good call.

Acked-by: Stephen Finucane 

> ---
>  Documentation/intro/what-is-ovs.rst | 8 
>  README.rst  | 5 +++--
>  2 files changed, 7 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/intro/what-is-ovs.rst 
> b/Documentation/intro/what-is-ovs.rst
> index bf7071f7a..002e1b063 100644
> --- a/Documentation/intro/what-is-ovs.rst
> +++ b/Documentation/intro/what-is-ovs.rst
> @@ -33,9 +33,9 @@ What Is Open vSwitch?
>  Overview
>  
>  
> -.. NOTE(stephenfin): The below line numbers may need to be updated if the
> -   README is modified
> +.. NOTE(stephenfin): The below start-after/end-before may need to be updated
> +   if the README is modified.
>  
>  .. include:: ../../README.rst
> -   :start-line: 13
> -   :end-line: 71
> +   :start-after: What is Open vSwitch?
> +   :end-before: What other documentation is available?
> diff --git a/README.rst b/README.rst
> index 4c9d9eddd..54d06d04b 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -1,5 +1,6 @@
> -.. NOTE(stephenfin): If making changes to this file, ensure that the line
> -   numbers found in 'Documentation/intro/what-is-ovs' are kept up-to-date.
> +.. NOTE(stephenfin): If making changes to this file, ensure that the
> +   start-after/end-before lines found in 'Documentation/intro/what-is-ovs'
> +   are kept up-to-date.
>  
>  
>  Open vSwitch

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [ovs-dev, v1] datapath-windows: Do not send out nbls when cloned nbls are being accessed

[Stephen Finucane]

On Wed, 2019-04-10 at 13:53 -0400, Aaron Conole wrote:
> Aaron Conole  writes:
> 
> > 0-day Robot  writes:
> > 
> > > Bleep bloop.  Greetings Anand Kumar via dev, I am a robot and I have 
> > > tried out your patch.
> > > Thanks for your contribution.
> > > 
> > > I encountered some error that I wasn't expecting.  See the details below.
> > > 
> > > 
> > > checkpatch:
> > > ERROR: Author should not be mailing list.
> > > Lines checked: 31, Warnings: 0, Errors: 1
> > 
> > I looked into this - it seems that your patch doesn't have a Reply-To
> > field.
> 
> Clarification, when fetched from Patchwork it doesn't seem that the
> Reply-To field is included.  Perhaps this is something useful to address
> in Patchwork as well?

This was resolved in Patchwork 2.1 [1]. Unfortunately the ozlabs.org
instance hasn't been updated yet and I've no influence over that.
Hopefully they'll bump to 2.2 when that's released in the coming
months.

Stephen

[1] 
https://github.com/getpatchwork/patchwork/commit/01b9cbb9ce9f44387be22b5d036dde0fff4bb14b

> > I plan to catch cases like this and duplicate the 'Signed-off-by:' as a
> > 'From:'.
> > 
> > Sorry for the noise, again.
> > > Please check this out.  If you feel there has been an error, please email 
> > > acon...@bytheb.org
> > > 
> > > Thanks,
> > > 0-day Robot
> > > ___
> > > dev mailing list
> > > d...@openvswitch.org
> > > https://mail.openvswitch.org/mailman/listinfo/ovs-dev
> > ___
> > dev mailing list
> > d...@openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev


___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH] doc: Add missing ':doc:' role

[Stephen Finucane]

This was rendering in italics instead of cross-referencing as intended.

Signed-off-by: Stephen Finucane 
---
 Documentation/topics/dpdk/bridge.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/topics/dpdk/bridge.rst 
b/Documentation/topics/dpdk/bridge.rst
index df74c02ad..82bdad840 100644
--- a/Documentation/topics/dpdk/bridge.rst
+++ b/Documentation/topics/dpdk/bridge.rst
@@ -26,7 +26,7 @@ DPDK Bridges
 
 
 The DPDK datapath requires specially configured bridge(s) in order to utilize
-DPDK-backed :doc:`physical ` and `virtual ` ports.
+DPDK-backed :doc:`physical ` and :doc:`virtual ` ports.
 
 Quick Example
 -
-- 
2.20.1

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Fix table title for VM MQ config in dpdk howto.

[Stephen Finucane]

On Thu, 2018-08-30 at 17:36 +0100, Cian Ferriter wrote:
> Found this when searching "BIOS Settings" for use with DPDK.
> 
> CC: Stephen Finucane 
> Fixes: c50938a24031 ("doc: Convert INSTALL.DPDK-ADVANCED to rST")
> Signed-off-by: Cian Ferriter 

Oops.

Acked-by: Stephen Finucane 

> ---
>  Documentation/howto/dpdk.rst |2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index ab3d576..6397d25 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -284,7 +284,7 @@ devices to bridge ``br0``. Once complete, follow the 
> below steps:
> We must configure with appropriate software versions to ensure this 
> feature
> is supported.
>  
> -   .. list-table:: Recommended BIOS Settings
> +   .. list-table:: VM Configuration
>:header-rows: 1
>  
>* - Setting


___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] doc: Final cleanup of the DPDK documents

[Stephen Finucane]

On Thu, 2018-05-10 at 19:05 +, Stokes, Ian wrote:
> > This concludes the cleanup by fixing some nits and adding some additional
> > cross-references.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> > This was initially sent as part of a larger series but excluded from a
> > recent merge due to label issues. I wasn't able to reproduce these so I'm
> > resending verbatim.
> 
> Hi Stephen,
> 
> Thanks for this. Bit of a strange one. I'm still seeing the complaint 
> regarding the duplication of labels on my own system
> 
> Warning, treated as error:
> ovs/Documentation/topics/dpdk/index.rst:None: WARNING: duplicate label 
> bridges and ports, other instance in ovs/Documentation/howto/dpdk.rst
> 
> This could be specific to my board as you couldn't re-produce, however 
> running the patch through travis build throws up a separate error on 
> compilation regarding the use of caption in toctree.
> 
> Warning, treated as error:
> Documentation/topics/dpdk/index.rst:1: ERROR: Error in "toctree" directive:
> unknown option: "caption".
> .. toctree::
>:maxdepth: 2
>:caption: Bridges and Ports
>/topics/dpdk/bridge
>/topics/dpdk/phy
>/topics/dpdk/vhost-user
>/topics/dpdk/ring
>/topics/dpdk/vdev
> 
> For completeness the link to the travis build is included below.
> 
> https://travis-ci.org/istokes/ovs/jobs/377412427

Yeah, looks like this is using Sphinx 1.2.2 and the 'caption' directive
was added in Sphinx 1.3 [1]. I'm guessing there's a reason that we're
using such an old version?

> I wondering is this related to different sphinx versions across the test 
> systems.
> 
> I'll investigate the error that appears on my board if you can look at the 
> travis error above.

What versions of Sphinx are you using locally? I'll see if I can
reproduce said issue myself too (or at least make sense of it).

Stephen

[1] http://www.sphinx-doc.org/en/master/usage/restructuredtext/directiv
es.html#directive-toctree

> Thanks
> Ian
> > ---
> >  Documentation/howto/dpdk.rst| 51 
> > -
> >  Documentation/topics/dpdk/index.rst |  6 +
> >  2 files changed, 28 insertions(+), 29 deletions(-)
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 380181db0..6344f1cb0 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -25,23 +25,26 @@
> >  Using Open vSwitch with DPDK
> >  
> > 
> > -This document describes how to use Open vSwitch with DPDK datapath.
> > +This document describes how to use Open vSwitch with DPDK datapath. For
> > +more detailed information, refer to the various :doc:`DPDK topic guides
> > +`.
> > 
> >  .. important::
> > 
> > Using the DPDK datapath requires building OVS with DPDK support. Refer
> > to
> > :doc:`/intro/install/dpdk` for more information.
> > 
> > -Ports and Bridges
> > --
> > +Overview
> > +
> > 
> > -ovs-vsctl can be used to set up bridges and other Open vSwitch features.
> > -Bridges should be created with a ``datapath_type=netdev``::
> > +:program:`ovs-vsctl` can be used to set up bridges and other Open
> > +vSwitch features.  Bridges should be created with a
> > ``datapath_type=netdev``::
> > 
> >  $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
> > 
> > -ovs-vsctl can also be used to add DPDK devices. ovs-vswitchd should print
> > the -number of dpdk devices found in the log file::
> > +:program:`ovs-vsctl` can also be used to add DPDK devices.
> > +:program:`ovs-vswitchd` should print the number of ``dpdk`` devices
> > +found in the log file::
> > 
> >  $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> >  options:dpdk-devargs=:01:00.0 @@ -59,14 +62,13 @@ is
> > suggested::
> > 
> >  .. important::
> > 
> > -Hotplugging physical interfaces is not supported using the above
> > syntax.
> > -This is expected to change with the release of DPDK v18.05. For
> > information
> > -on hotplugging physical interfaces, you should instead refer to
> > -:ref:`port-hotplug`.
> > +Hotplugging physical interfaces is not supported for these devices.
> > This
> > +is expected to change with the release of DPDK v18.05. For
> > information on
> > +hotplugging physical interfaces, refer to :ref:`port-hotplug`.
> > 
> >  After the DPDK ports get added

[ovs-dev] [PATCH] doc: Final cleanup of the DPDK documents

[Stephen Finucane]

This concludes the cleanup by fixing some nits and adding some
additional cross-references.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
This was initially sent as part of a larger series but excluded from a
recent merge due to label issues. I wasn't able to reproduce these so
I'm resending verbatim.
---
 Documentation/howto/dpdk.rst| 51 -
 Documentation/topics/dpdk/index.rst |  6 +
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 380181db0..6344f1cb0 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -25,23 +25,26 @@
 Using Open vSwitch with DPDK
 
 
-This document describes how to use Open vSwitch with DPDK datapath.
+This document describes how to use Open vSwitch with DPDK datapath. For more
+detailed information, refer to the various :doc:`DPDK topic guides
+`.
 
 .. important::
 
Using the DPDK datapath requires building OVS with DPDK support. Refer to
:doc:`/intro/install/dpdk` for more information.
 
-Ports and Bridges
--
+Overview
+
 
-ovs-vsctl can be used to set up bridges and other Open vSwitch features.
-Bridges should be created with a ``datapath_type=netdev``::
+:program:`ovs-vsctl` can be used to set up bridges and other Open vSwitch
+features.  Bridges should be created with a ``datapath_type=netdev``::
 
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
 
-ovs-vsctl can also be used to add DPDK devices. ovs-vswitchd should print the
-number of dpdk devices found in the log file::
+:program:`ovs-vsctl` can also be used to add DPDK devices.
+:program:`ovs-vswitchd` should print the number of ``dpdk`` devices found in
+the log file::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs=:01:00.0
@@ -59,14 +62,13 @@ is suggested::
 
 .. important::
 
-Hotplugging physical interfaces is not supported using the above syntax.
-This is expected to change with the release of DPDK v18.05. For information
-on hotplugging physical interfaces, you should instead refer to
-:ref:`port-hotplug`.
+Hotplugging physical interfaces is not supported for these devices.  This
+is expected to change with the release of DPDK v18.05. For information on
+hotplugging physical interfaces, refer to :ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
-DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
-``ps`` commands::
+DPDK devices and consumes 100% of the core, as can be checked from
+:command:`top` and :command:`ps` commands::
 
 $ top -H
 $ ps -eLo pid,psr,comm | grep pmd
@@ -79,7 +81,7 @@ set. For example::
 -- set Interface p0 type=dpdk options:dpdk-devargs=:01:00.0 \
 -- set Interface p1 type=dpdk options:dpdk-devargs=:01:00.1
 
-To stop ovs-vswitchd & delete bridge, run::
+To stop :program:`ovs-vswitchd` and delete the bridge, run::
 
 $ ovs-appctl -t ovs-vswitchd exit
 $ ovs-appctl -t ovsdb-server exit
@@ -137,13 +139,16 @@ Add test flows to forward packets between DPDK port 0 and 
port 1::
 
 Transmit traffic into either port. You should see it returned via the other.
 
+More information on the ``dpdk`` ports can be found in :doc:`/topics/dpdk/phy`.
+
 .. _dpdk-vhost-loopback:
 
 PHY-VM-PHY (vHost Loopback)
 ---
 
 Add a userspace bridge, two ``dpdk`` (PHY) ports, and two ``dpdkvhostuser``
-ports::
+ports. It is assumed that the physical ports are already bound to DPDK, as
+described in :ref:`dpdk-binding-nics`::
 
 # Add userspace bridge
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
@@ -221,19 +226,7 @@ described in :ref:`dpdk-testpmd`. Once compiled, run the 
application::
 $ set fwd mac retry
 $ start
 
-When you finish testing, bind the vNICs back to kernel::
-
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:03.0
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:04.0
-
-.. note::
-
-  Valid PCI IDs must be passed in above example. The PCI IDs can be retrieved
-  like so::
-
-  $ $DPDK_DIR/usertools/dpdk-devbind.py --status
-
-More information on the dpdkvhostuser ports can be found in
+More information on the ``dpdkvhostuser`` ports can be found in
 :doc:`/topics/dpdk/vhost-user`.
 
 PHY-VM-PHY (vHost Loopback) (Kernel Forwarding)
@@ -277,7 +270,7 @@ devices to bridge ``br0``. Once complete, follow the below 
steps:
$ ovs-vsctl set Interface phy0 options:n_rxq=2
$ ovs-vsctl set Interface phy1 options:n_rxq=2
 
-2. Instantiate Guest VM using QEMU cmdline
+2. Instantiate Guest VM using QEMU command line
 
We must configure with appropriate software versions to ensure this feature
is supported.
diff --git a/Documentation/t

[ovs-dev] [PATCH v3 10/n] docs: Clarify changes in Rx queue allocation

[Stephen Finucane]

Two mistakes here:

- Automatic assignment of Rx queues to PMD threads has always existed -
  it was simply switched from round-robin allocation to
  utilization-based allocation
- The above, along with the 'pmd-rxq-rebalance' command, was added in
  OVS 2.9.0 - not OVS 2.8.0 - while the 'pmd-rxq-show' command was added
  in OVS 2.6.0 and modified in OVS 2.9.0

Correct both of these and modify the NEWS entry for this to clarify
things a little (it took a bit of git spelunking and bothering people on
IRC to figure out).

Signed-off-by: Stephen Finucane <step...@that.guru>
Cc: Kevin Traynor <ktray...@redhat.com>
Cc: Ian Stokes <ian.sto...@intel.com>
---
I'm not sure if it's OK to modify NEWS entries after a release. If not,
please simply drop that hunk when applying this.
---
 Documentation/topics/dpdk/pmd.rst | 17 ++---
 NEWS  |  2 ++
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/Documentation/topics/dpdk/pmd.rst 
b/Documentation/topics/dpdk/pmd.rst
index a652720e2..5f0671ecc 100644
--- a/Documentation/topics/dpdk/pmd.rst
+++ b/Documentation/topics/dpdk/pmd.rst
@@ -148,14 +148,17 @@ or can be triggered by using::
 
 $ ovs-appctl dpif-netdev/pmd-rxq-rebalance
 
-.. versionchanged:: 2.8.0
+.. versionchanged:: 2.6.0
 
-   Automatic assignment of Rx queues to PMDs and the two related commands,
-   ``pmd-rxq-show`` and ``pmd-rxq-rebalance``, were added in OVS 2.8.0. Prior
-   to this, behavior was round-robin and processing cycles were not taken into
-   consideration. Tracking for stats was not available.
+   The ``pmd-rxq-show`` command was added in OVS 2.6.0.
 
 .. versionchanged:: 2.9.0
 
-   The output of ``pmd-rxq-show`` was modified to include utilization as a
-   percentage.
+   Utilization-based allocation of Rx queues to PMDs and the
+   ``pmd-rxq-rebalance`` command were added in OVS 2.9.0. Prior to this,
+   allocation was round-robin and processing cycles were not taken into
+   consideration.
+
+   In addition, the output of ``pmd-rxq-show`` was modified to include
+   Rx queue utilization of the PMD as a percentage. Prior to this, tracking of
+   stats was not available.
diff --git a/NEWS b/NEWS
index cd4ffbbfb..3e3f55385 100644
--- a/NEWS
+++ b/NEWS
@@ -83,6 +83,8 @@ v2.9.0 - 19 Feb 2018
   "management" statistics.
 - ovs-ofctl dump-ports command now prints new of set custom statistics
   if available (for OpenFlow 1.4+).
+ * Switch from round-robin allocation of rxq to pmd assignments to a
+   utilization-based allocation.
  * New appctl command 'dpif-netdev/pmd-rxq-rebalance' to rebalance rxq to
pmd assignments.
  * Add rxq utilization of pmd to appctl 'dpif-netdev/pmd-rxq-show'.
-- 
2.14.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

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

[Stephen Finucane]

This details configuration steps that apply to the entire bridge, rather
than individual ports.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
v2:
- Cross-reference this document from all interface documents
---
 Documentation/automake.mk|   1 +
 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 ++
 8 files changed, 126 insertions(+), 60 deletions(-)
 create mode 100644 Documentation/topics/dpdk/bridge.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index e443e..2aacaa380 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -34,6 +34,7 @@ DOC_SOURCE = \
Documentation/topics/datapath.rst \
Documentation/topics/design.rst \
Documentation/topics/dpdk/index.rst \
+   Documentation/topics/dpdk/bridge.rst \
Documentation/topics/dpdk/phy.rst \
Documentation/topics/dpdk/pmd.rst \
Documentation/topics/dpdk/qos.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 0..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
+   

[ovs-dev] [PATCH v3 2/9] doc: Add "PMD" topic document

[Stephen Finucane]

This continues the breakup of the huge DPDK "howto" into smaller
components. There are a couple of related changes included, such as
using "Rx queue" instead of "rxq" and noting how Tx queues cannot be
configured.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
- Add additional 'versionchanged' information for 'pmd-rxq-show' command
v2:
- Add cross-references from 'pmd' doc to 'vhost-user' and 'phy' docs
- Add 'versionchanged' warning about automatic assignment of Rx queues
- Add a 'todo' to describe Tx queue behavior
---
 Documentation/automake.mk|   1 +
 Documentation/howto/dpdk.rst |  86 -
 Documentation/topics/dpdk/index.rst  |   1 +
 Documentation/topics/dpdk/phy.rst|  12 +++
 Documentation/topics/dpdk/pmd.rst| 161 +++
 Documentation/topics/dpdk/vhost-user.rst |  17 ++--
 6 files changed, 183 insertions(+), 95 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pmd.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index cd8f3dc0d..878de4349 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -35,6 +35,7 @@ DOC_SOURCE = \
Documentation/topics/design.rst \
Documentation/topics/dpdk/index.rst \
Documentation/topics/dpdk/phy.rst \
+   Documentation/topics/dpdk/pmd.rst \
Documentation/topics/dpdk/ring.rst \
Documentation/topics/dpdk/vhost-user.rst \
Documentation/topics/testing.rst \
diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 79b626c76..388728363 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -81,92 +81,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-PMD Thread Statistics
--
-
-To show current stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-show
-
-To clear previous stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-clear
-
-Port/RXQ Assigment to PMD Threads
--
-
-To show port/rxq assignment::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-To change default rxq assignment to pmd threads, rxqs may be manually pinned to
-desired cores using::
-
-$ ovs-vsctl set Interface  \
-other_config:pmd-rxq-affinity=
-
-where:
-
--  is a CSV list of ``:`` values
-
-For example::
-
-$ ovs-vsctl set interface dpdk-p0 options:n_rxq=4 \
-other_config:pmd-rxq-affinity="0:3,1:7,3:8"
-
-This will ensure:
-
-- Queue #0 pinned to core 3
-- Queue #1 pinned to core 7
-- Queue #2 not pinned
-- Queue #3 pinned to core 8
-
-After that PMD threads on cores where RX queues was pinned will become
-``isolated``. This means that this thread will poll only pinned RX queues.
-
-.. warning::
-  If there are no ``non-isolated`` PMD threads, ``non-pinned`` RX queues will
-  not be polled. Also, if provided ``core_id`` is not available (ex. this
-  ``core_id`` not in ``pmd-cpu-mask``), RX queue will not be polled by any PMD
-  thread.
-
-If pmd-rxq-affinity is not set for rxqs, they will be assigned to pmds (cores)
-automatically. The processing cycles that have been stored for each rxq
-will be used where known to assign rxqs to pmd based on a round robin of the
-sorted rxqs.
-
-For example, in the case where here there are 5 rxqs and 3 cores (e.g. 3,7,8)
-available, and the measured usage of core cycles per rxq over the last
-interval is seen to be:
-
-- Queue #0: 30%
-- Queue #1: 80%
-- Queue #3: 60%
-- Queue #4: 70%
-- Queue #5: 10%
-
-The rxqs will be assigned to cores 3,7,8 in the following order:
-
-Core 3: Q1 (80%) |
-Core 7: Q4 (70%) | Q5 (10%)
-core 8: Q3 (60%) | Q0 (30%)
-
-To see the current measured usage history of pmd core cycles for each rxq::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-.. note::
-
-  A history of one minute is recorded and shown for each rxq to allow for
-  traffic pattern spikes. An rxq's pmd core cycles usage changes due to traffic
-  pattern or reconfig changes will take one minute before they are fully
-  reflected in the stats.
-
-Rxq to pmds assignment takes place whenever there are configuration changes
-or can be triggered by using::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-rebalance
-
 QoS
 ---
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 5f836a6e9..dfde88377 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -31,3 +31,4 @@ The DPDK Datapath
phy
vhost-user
ring
+   pmd
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index a3f8b475c..ad191dad0 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -113,3 +113,15 @@ tool::
 For more information, refer to the `DPDK documentation `__.
 
 .. _dpdk-drivers: http://dpdk.org/doc/g

[ovs-dev] [PATCH v3 4/9] doc: Add "vdev" topic document

[Stephen Finucane]

These are separate things from physical, ring and vhost-user interfaces
and deserve their own documents. A couple of small typos are fixed along
the way.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
- Add 'versionchanged' directive to call out when this was added
---
 Documentation/automake.mk   |  1 +
 Documentation/howto/dpdk.rst| 29 --
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/vdev.rst  | 61 +
 4 files changed, 63 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/topics/dpdk/vdev.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 878de4349..3056e527a 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -37,6 +37,7 @@ DOC_SOURCE = \
Documentation/topics/dpdk/phy.rst \
Documentation/topics/dpdk/pmd.rst \
Documentation/topics/dpdk/ring.rst \
+   Documentation/topics/dpdk/vdev.rst \
Documentation/topics/dpdk/vhost-user.rst \
Documentation/topics/testing.rst \
Documentation/topics/high-availability.rst \
diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 531612880..9cb76b7e1 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -244,35 +244,6 @@ 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.
 
-.. _vdev-support:
-
-Vdev Support
-
-
-DPDK provides drivers for both physical and virtual devices. Physical DPDK
-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'.
-
-Typically, the format expected is 'eth_' where 'x' is a
-unique identifier of your choice for the given port.
-
-For example to add a dpdk port that uses the 'null' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
-   options:dpdk-devargs=eth_null0
-
-Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
-   options:dpdk-devargs=eth_af_packet0,iface=eth0
-
-More information on the different types of virtual DPDK PMDs can be found in
-the `DPDK documentation
-<http://dpdk.org/doc/guides/nics/overview.html>`__.
-
-Note: Not all DPDK virtual PMD drivers have been tested and verified to work.
-
 EMC Insertion Probability
 -
 By default 1 in every 100 flows are inserted into the Exact Match Cache (EMC).
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 4b4dc119a..c1e6ea78c 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -34,4 +34,5 @@ The DPDK Datapath
/topics/dpdk/phy
/topics/dpdk/vhost-user
/topics/dpdk/ring
+   /topics/dpdk/vdev
/topics/dpdk/pmd
diff --git a/Documentation/topics/dpdk/vdev.rst 
b/Documentation/topics/dpdk/vdev.rst
new file mode 100644
index 0..31894530b
--- /dev/null
+++ b/Documentation/topics/dpdk/vdev.rst
@@ -0,0 +1,61 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 Virtual Devices
+
+
+DPDK provides drivers for both physical and virtual devices. Physical DPDK
+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``.
+
+.. note::
+
+Not all DPDK virtual PMD drivers have been tested and verified to work.
+
+.. versionadded:: 2.7.0
+
+Quick Example
+-
+
+To add a virtual ``dpdk`` devices, the ``dpdk-devargs`` argument should be of
+the format ``eth_``, where ``x``' is a unique identifier of
+your choice for the given port. For example to add a ``dp

[ovs-dev] [PATCH v3 8/9] doc: Add "jumbo frames" topic document

[Stephen Finucane]

We include references from the physical and vhost-user interface guides.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
- Add 'versionchanged' directive to call out when this was added
v2:
- Don't split the document into multiple docs
---
 Documentation/automake.mk  |  1 +
 Documentation/howto/dpdk.rst   | 52 ++---
 Documentation/topics/dpdk/index.rst|  1 +
 Documentation/topics/dpdk/jumbo-frames.rst | 73 ++
 Documentation/topics/dpdk/phy.rst  |  6 +++
 Documentation/topics/dpdk/vhost-user.rst   |  6 +++
 6 files changed, 90 insertions(+), 49 deletions(-)
 create mode 100644 Documentation/topics/dpdk/jumbo-frames.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 003ccd27f..8b47d2276 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -35,6 +35,7 @@ DOC_SOURCE = \
Documentation/topics/design.rst \
Documentation/topics/dpdk/index.rst \
Documentation/topics/dpdk/bridge.rst \
+   Documentation/topics/dpdk/jumbo-frames.rst \
Documentation/topics/dpdk/pdump.rst \
Documentation/topics/dpdk/phy.rst \
Documentation/topics/dpdk/pmd.rst \
diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 1a0fb6df1..e65e7dfaa 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -48,9 +48,9 @@ number of dpdk devices found in the log file::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs=:01:00.1
 
-Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated
-with multiple ports. Using a PCI device like above won't work. Instead, below
-usage is suggested::
+Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated with
+multiple ports. Using a PCI device like above won't work. Instead, below usage
+is suggested::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:01"
@@ -85,52 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-Jumbo Frames
-
-
-By default, DPDK ports are configured with standard Ethernet MTU (1500B). To
-enable Jumbo Frames support for a DPDK port, change the Interface's
-``mtu_request`` attribute to a sufficiently large value. For example, to add a
-DPDK Phy port with MTU of 9000::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-  options:dpdk-devargs=:01:00.0 mtu_request=9000
-
-Similarly, to change the MTU of an existing port to 6200::
-
-$ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
-
-Some additional configuration is needed to take advantage of jumbo frames with
-vHost ports:
-
-1. *mergeable buffers* must be enabled for vHost ports, as demonstrated in the
-   QEMU command line snippet below::
-
-   -netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \
-   -device virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on
-
-2. Where virtio devices are bound to the Linux kernel driver in a guest
-   environment (i.e. interfaces are not bound to an in-guest DPDK driver), the
-   MTU of those logical network interfaces must also be increased to a
-   sufficiently large value. This avoids segmentation of Jumbo Frames received
-   in the guest. Note that 'MTU' refers to the length of the IP packet only,
-   and not that of the entire frame.
-
-   To calculate the exact MTU of a standard IPv4 frame, subtract the L2 header
-   and CRC lengths (i.e. 18B) from the max supported frame size.  So, to set
-   the MTU for a 9018B Jumbo Frame::
-
-   $ ip link set eth1 mtu 9000
-
-When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
-increased, such that a full Jumbo Frame of a specific size may be accommodated
-within a single mbuf segment.
-
-Jumbo frame support has been validated against 9728B frames, which is the
-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.
-
 .. _dpdk-ovs-in-guest:
 
 OVS with DPDK Inside VMs
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index d083d929e..181f61abb 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -39,3 +39,4 @@ The DPDK Datapath
/topics/dpdk/pmd
/topics/dpdk/qos
/topics/dpdk/pdump
+   /topics/dpdk/jumbo-frames
diff --git a/Documentation/topics/dpdk/jumbo-frames.rst 
b/Documentation/topics/dpdk/jumbo-frames.rst
new file mode 100644
index 0..00360b4e6
--- /dev/null
+++ b/Documentation/topics/dpdk/jumbo-frames.rst
@@ -0,0 +1,73 @@
+..
+  Copyrigh

[ovs-dev] [PATCH v3 3/9] doc: Move additional sections to "physical ports" doc

[Stephen Finucane]

The "hotplugging", "flow control", and "Rx checksum offload" sections
only apply to 'dpdk' ports and are too detailed to include in a
high-level howto. Move them, reworking some aspects of this in the
process.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Split out vdev into its own document (and patch)
- Add cross-references from DPDK howto guide to detailed topic guides
- Add flow control
---
 Documentation/howto/dpdk.rst| 103 ++--
 Documentation/topics/dpdk/index.rst |  11 ++--
 Documentation/topics/dpdk/phy.rst   |  86 ++
 3 files changed, 110 insertions(+), 90 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 388728363..531612880 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -57,8 +57,12 @@ usage is suggested::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
 
-Note: such syntax won't support hotplug. The hotplug is supposed to work with
-future DPDK release, v18.05.
+.. important::
+
+Hotplugging physical interfaces is not supported using the above syntax.
+This is expected to change with the release of DPDK v18.05. For information
+on hotplugging physical interfaces, you should instead refer to
+:ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
 DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
@@ -123,34 +127,6 @@ To clear the ingress policer configuration from the port::
 
 Refer to vswitch.xml for more details on ingress-policer.
 
-Flow Control
-
-
-Flow control can be enabled only on DPDK physical ports. To enable flow control
-support at tx side while adding a port, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:tx-flow-ctrl=true
-
-Similarly, to enable rx flow control, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:rx-flow-ctrl=true
-
-To enable flow control auto-negotiation, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:flow-ctrl-autoneg=true
-
-To turn ON the tx flow control at run time for an existing port, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
-
-The flow control parameters can be turned off by setting ``false`` to the
-respective parameter. To disable the flow control at tx side, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
-
 pdump
 -
 
@@ -236,16 +212,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.
 
-Rx Checksum Offload

-
-By default, DPDK physical ports are enabled with Rx checksum offload.
-
-Rx checksum offload can offer performance improvement only for tunneling
-traffic in OVS-DPDK because the checksum validation of tunnel packets is
-offloaded to the NIC. Also enabling Rx checksum may slightly reduce the
-performance of non-tunnel traffic, specifically for smaller size packet.
-
 .. _extended-statistics:
 
 Extended & Custom Statistics
@@ -278,52 +244,6 @@ 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.
 
-.. _port-hotplug:
-
-Port Hotplug
-
-
-OVS supports port hotplugging, allowing the use of ports that were not bound
-to DPDK when vswitchd was started.
-In order to attach a port, it has to be bound to DPDK using the
-``dpdk_nic_bind.py`` script::
-
-$ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio :01:00.0
-
-Then it can be attached to OVS::
-
-$ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
-options:dpdk-devargs=:01:00.0
-
-Detaching will be performed while processing del-port command::
-
-$ ovs-vsctl del-port dpdkx
-
-Sometimes, the del-port command may not detach the device.
-Detaching can be confirmed by the appearance of an INFO log.
-For example::
-
-INFO|Device ':04:00.1' has been detached
-
-If the log is not seen, then the port can be detached using::
-
-$ ovs-appctl netdev-dpdk/detach :01:00.0
-
-Detaching can be confirmed by console output::
-
-Device ':04:00.1' has been detached
-
-.. warning::
-Detaching should not be done if a device is known to be non-detachable, as
-this may cause the device to behave improperly when added back with
-add-port. The Chelsio Terminator adapters which use the cxgbe driver seem
-to be

[ovs-dev] [PATCH v3 1/9] doc: Add an overview of the 'dpdk' port

[Stephen Finucane]

These ports are used to allow ingress/egress from the host and are
therefore _reasonably_ important. However, there is no clear overview of
what these ports actually are or why things are done the way they are.
Start closing this gap by providing a standalone example of using these
ports along with a little more detailed overview of the binding process.

There is additional cleanup to be done for the DPDK howto, but that will
be done separately.

We enable the TODO directive so we can actually start calling out some
TODOs.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
v2:
- Add TODO for multiple ports sharing the same bus slot function
  (ian.stokes)
---
 Documentation/automake.mk   |   1 +
 Documentation/conf.py   |   2 +-
 Documentation/topics/dpdk/index.rst |   1 +
 Documentation/topics/dpdk/phy.rst   | 115 
 4 files changed, 118 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/topics/dpdk/phy.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index c05a2313a..cd8f3dc0d 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -34,6 +34,7 @@ DOC_SOURCE = \
Documentation/topics/datapath.rst \
Documentation/topics/design.rst \
Documentation/topics/dpdk/index.rst \
+   Documentation/topics/dpdk/phy.rst \
Documentation/topics/dpdk/ring.rst \
Documentation/topics/dpdk/vhost-user.rst \
Documentation/topics/testing.rst \
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6ab144c5d..babda21de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -32,7 +32,7 @@ needs_sphinx = '1.1'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index da148b323..5f836a6e9 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -28,5 +28,6 @@ The DPDK Datapath
 .. toctree::
:maxdepth: 2
 
+   phy
vhost-user
ring
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
new file mode 100644
index 0..a3f8b475c
--- /dev/null
+++ b/Documentation/topics/dpdk/phy.rst
@@ -0,0 +1,115 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 Physical Ports
+===
+
+The netdev datapath allows attaching of DPDK-backed physical interfaces in
+order to provide high-performance ingress/egress from the host.
+
+.. versionchanged:: 2.7.0
+
+   Before Open vSwitch 2.7.0, it was necessary to prefix port names with a
+   ``dpdk`` prefix. Starting with 2.7.0, this is no longer necessary.
+
+.. todo::
+
+   Add an example for multiple ports share the same bus slot function.
+
+Quick Example
+-
+
+This example demonstrates how to bind two ``dpdk`` ports, bound to physical
+interfaces identified by hardware IDs ``:01:00.0`` and ``:01:00.1``, to
+an existing bridge called ``br0``::
+
+$ ovs-vsctl add-port br0 dpdk-p0 \
+   -- set Interface dpdk-p0 type=dpdk options:dpdk-devargs=:01:00.0
+$ ovs-vsctl add-port br0 dpdk-p1 \
+   -- set Interface dpdk-p1 type=dpdk options:dpdk-devargs=:01:00.1
+
+For the above example to work, the two physical interfaces must be bound to
+the DPDK poll-mode drivers in userspace rather than the traditional kernel
+drivers. See the `binding NIC drivers ` section for details.
+
+.. _dpdk-binding-nics:
+
+Binding NIC Drivers
+---
+
+DPDK operates entirely in userspace and, as a result, requires use of its own
+poll-mode drivers in user space for physical interfaces and a passthrough-style
+driver for the devices in kernel space.
+
+There are two different tools for binding drivers: 

[ovs-dev] [PATCH v3 5/9] doc: Move "QoS" guide to its own document

[Stephen Finucane]

Again, this stuff is too detailed for a high-level howto.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v3:
- Add new files to automake.mk
- Add 'versionchanged' directive to call out when this was added
v2:
- Keep flow control section in 'phy' document
---
 Documentation/automake.mk   |  1 +
 Documentation/howto/dpdk.rst| 42 
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/phy.rst   |  2 +
 Documentation/topics/dpdk/qos.rst   | 78 +
 5 files changed, 82 insertions(+), 42 deletions(-)
 create mode 100644 Documentation/topics/dpdk/qos.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 3056e527a..e443e 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -36,6 +36,7 @@ DOC_SOURCE = \
Documentation/topics/dpdk/index.rst \
Documentation/topics/dpdk/phy.rst \
Documentation/topics/dpdk/pmd.rst \
+   Documentation/topics/dpdk/qos.rst \
Documentation/topics/dpdk/ring.rst \
Documentation/topics/dpdk/vdev.rst \
Documentation/topics/dpdk/vhost-user.rst \
diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 9cb76b7e1..3e04d8627 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,48 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-QoS

-
-Assuming you have a vhost-user port transmitting traffic consisting of packets
-of size 64 bytes, the following command would limit the egress transmission
-rate of the port to ~1,000,000 packets per second::
-
-$ ovs-vsctl set port vhost-user0 qos=@newqos -- \
---id=@newqos create qos type=egress-policer other-config:cir=4600 \
-other-config:cbs=2048`
-
-To examine the QoS configuration of the port, run::
-
-$ ovs-appctl -t ovs-vswitchd qos/show vhost-user0
-
-To clear the QoS configuration from the port and ovsdb, run::
-
-$ ovs-vsctl destroy QoS vhost-user0 -- clear Port vhost-user0 qos
-
-Refer to vswitch.xml for more details on egress-policer.
-
-Rate Limiting
---
-
-Here is an example on Ingress Policing usage. Assuming you have a vhost-user
-port receiving traffic consisting of packets of size 64 bytes, the following
-command would limit the reception rate of the port to ~1,000,000 packets per
-second::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=368000 \
-ingress_policing_burst=1000`
-
-To examine the ingress policer configuration of the port::
-
-$ ovs-vsctl list interface vhost-user0
-
-To clear the ingress policer configuration from the port::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=0
-
-Refer to vswitch.xml for more details on ingress-policer.
-
 pdump
 -
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index c1e6ea78c..d3c1e2099 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -36,3 +36,4 @@ The DPDK Datapath
/topics/dpdk/ring
/topics/dpdk/vdev
/topics/dpdk/pmd
+   /topics/dpdk/qos
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index 929f394ea..581984b63 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -126,6 +126,8 @@ DPDK acceleration. It is possible to configure multiple Rx 
queues for ``dpdk``
 ports, thus ensuring this is not a bottleneck for performance. For information
 on configuring PMD threads, refer to :doc:`pmd`.
 
+.. _dpdk-phy-flow-control:
+
 Flow Control
 
 
diff --git a/Documentation/topics/dpdk/qos.rst 
b/Documentation/topics/dpdk/qos.rst
new file mode 100644
index 0..c0aec5d88
--- /dev/null
+++ b/Documentation/topics/dpdk/qos.rst
@@ -0,0 +1,78 @@
+..
+  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.
+
+
+Quality of Service (QoS)
+
+
+It is possible to apply both ingress and egress limiting when using the DPDK

[ovs-dev] [PATCH v3 0/9] Split up the DPDK how-to

[Stephen Finucane]

The DPDK howto has slowly morphed into a catch all for everything DPDK,
which goes against the original design goal for 'howto' documents [*].
This series attempts to return some sanity to the universe by splitting
this document into many more 'topic' documents. Along the way, we add a
lot of semantic markup, rework some text, and add an overview on
'dpdk'-type ports (the original goal here).

There's a good chance I've made some mistakes in the process and I've
left TODOs for someone to resolve now or at a future date. I welcome
feedback on both of these.

[*] 'howto' documents are supposed to be brief, high-level overviews on
a particular group of features, with a focus on the user. They're
not as all-encompassing as a 'tutorial', but not as specific as a
'topic'.

Changes since v2:
- Addressed comments from Ian Stokes

Stephen Finucane (9):
  doc: Add an overview of the 'dpdk' port
  doc: Add "PMD" topic document
  doc: Move additional sections to "physical ports" doc
  doc: Add "vdev" topic document
  doc: Move "QoS" guide to its own document
  doc: Add "bridge" topic document
  doc: Move "pdump" guide to its own document
  doc: Add "jumbo frames" topic document
  doc: Final cleanup of the DPDK documents

 Documentation/automake.mk  |   7 +
 Documentation/conf.py  |   2 +-
 Documentation/howto/dpdk.rst   | 454 +++--
 Documentation/topics/dpdk/bridge.rst   | 104 +++
 Documentation/topics/dpdk/index.rst|  20 +-
 Documentation/topics/dpdk/jumbo-frames.rst |  73 +
 Documentation/topics/dpdk/pdump.rst|  67 +
 Documentation/topics/dpdk/phy.rst  | 226 ++
 Documentation/topics/dpdk/pmd.rst  | 161 ++
 Documentation/topics/dpdk/qos.rst  |  78 +
 Documentation/topics/dpdk/ring.rst |   5 +
 Documentation/topics/dpdk/vdev.rst |  66 +
 Documentation/topics/dpdk/vhost-user.rst   |  28 +-
 13 files changed, 863 insertions(+), 428 deletions(-)
 create mode 100644 Documentation/topics/dpdk/bridge.rst
 create mode 100644 Documentation/topics/dpdk/jumbo-frames.rst
 create mode 100644 Documentation/topics/dpdk/pdump.rst
 create mode 100644 Documentation/topics/dpdk/phy.rst
 create mode 100644 Documentation/topics/dpdk/pmd.rst
 create mode 100644 Documentation/topics/dpdk/qos.rst
 create mode 100644 Documentation/topics/dpdk/vdev.rst

-- 
2.14.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

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

[Stephen Finucane]

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

Done.

> > @@ -0,0 +1,104 @@
&g

Re: [ovs-dev] [PATCH v2 2/9] doc: Add "PMD" topic document

[Stephen Finucane]

On Wed, 2018-04-18 at 15:31 +, Stokes, Ian wrote:
> > This continues the breakup of the huge DPDK "howto" into smaller
> > components. There are a couple of related changes included, such as using
> > "Rx queue" instead of "rxq" and noting how Tx queues cannot be configured.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> > v2:
> > - Add cross-references from 'pmd' doc to 'vhost-user' and 'phy' docs
> > - Add 'versionchanged' warning about automatic assignment of Rx queues
> > - Add a 'todo' to describe Tx queue behavior
> > ---
> >  Documentation/howto/dpdk.rst |  86 -
> >  Documentation/topics/dpdk/index.rst  |   1 +
> >  Documentation/topics/dpdk/phy.rst|  12 +++
> >  Documentation/topics/dpdk/pmd.rst| 156
> > +++
> >  Documentation/topics/dpdk/vhost-user.rst |  17 ++--
> >  5 files changed, 177 insertions(+), 95 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/pmd.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 79b626c76..388728363 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -81,92 +81,6 @@ To stop ovs-vswitchd & delete bridge, run::
> >  $ ovs-appctl -t ovsdb-server exit
> >  $ ovs-vsctl del-br br0
> > 
> > -PMD Thread Statistics
> > --
> > -
> > -To show current stats::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-stats-show
> > -
> > -To clear previous stats::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-stats-clear
> > -
> > -Port/RXQ Assigment to PMD Threads
> > --
> > -
> > -To show port/rxq assignment::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-rxq-show
> > -
> > -To change default rxq assignment to pmd threads, rxqs may be manually
> > pinned to -desired cores using::
> > -
> > -$ ovs-vsctl set Interface  \
> > -other_config:pmd-rxq-affinity=
> > -
> > -where:
> > -
> > --  is a CSV list of ``:``
> > values
> > -
> > -For example::
> > -
> > -$ ovs-vsctl set interface dpdk-p0 options:n_rxq=4 \
> > -other_config:pmd-rxq-affinity="0:3,1:7,3:8"
> > -
> > -This will ensure:
> > -
> > -- Queue #0 pinned to core 3
> > -- Queue #1 pinned to core 7
> > -- Queue #2 not pinned
> > -- Queue #3 pinned to core 8
> > -
> > -After that PMD threads on cores where RX queues was pinned will become -
> > ``isolated``. This means that this thread will poll only pinned RX queues.
> > -
> > -.. warning::
> > -  If there are no ``non-isolated`` PMD threads, ``non-pinned`` RX queues
> > will
> > -  not be polled. Also, if provided ``core_id`` is not available (ex. this
> > -  ``core_id`` not in ``pmd-cpu-mask``), RX queue will not be polled by
> > any PMD
> > -  thread.
> > -
> > -If pmd-rxq-affinity is not set for rxqs, they will be assigned to pmds
> > (cores) -automatically. The processing cycles that have been stored for
> > each rxq -will be used where known to assign rxqs to pmd based on a round
> > robin of the -sorted rxqs.
> > -
> > -For example, in the case where here there are 5 rxqs and 3 cores (e.g.
> > 3,7,8) -available, and the measured usage of core cycles per rxq over the
> > last -interval is seen to be:
> > -
> > -- Queue #0: 30%
> > -- Queue #1: 80%
> > -- Queue #3: 60%
> > -- Queue #4: 70%
> > -- Queue #5: 10%
> > -
> > -The rxqs will be assigned to cores 3,7,8 in the following order:
> > -
> > -Core 3: Q1 (80%) |
> > -Core 7: Q4 (70%) | Q5 (10%)
> > -core 8: Q3 (60%) | Q0 (30%)
> > -
> > -To see the current measured usage history of pmd core cycles for each
> > rxq::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-rxq-show
> > -
> > -.. note::
> > -
> > -  A history of one minute is recorded and shown for each rxq to allow for
> > -  traffic pattern spikes. An rxq's pmd core cycles usage changes due to
> > traffic
> > -  pattern or reconfig changes will take one minute before they are fully
> > -  reflected in the stats.
> > -
> > -Rxq to pmds assignment takes place whenever there are configuration
> > changes -or can be triggered by using::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-rxq-rebalance
> > -
> >  QoS
> >  ---
> 

Re: [ovs-dev] [PATCH v2 4/9] doc: Add "vdev" topic document

[Stephen Finucane]

On Wed, 2018-04-18 at 15:32 +, Stokes, Ian wrote:
> > These are separate things from physical, ring and vhost-user interfaces
> > and deserve their own documents. A couple of small typos are fixed along
> > the way.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst| 29 --
> >  Documentation/topics/dpdk/index.rst |  1 +
> > Documentation/topics/dpdk/vdev.rst  | 59
> > +
> >  3 files changed, 60 insertions(+), 29 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/vdev.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 531612880..9cb76b7e1 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -244,35 +244,6 @@ 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.
> > 
> > -.. _vdev-support:
> > -
> > -Vdev Support
> > -
> > -
> > -DPDK provides drivers for both physical and virtual devices. Physical
> > DPDK -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'.
> > -
> > -Typically, the format expected is 'eth_' where 'x' is a -
> > unique identifier of your choice for the given port.
> > -
> > -For example to add a dpdk port that uses the 'null' DPDK PMD driver::
> > -
> > -   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
> > -   options:dpdk-devargs=eth_null0
> > -
> > -Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
> > -
> > -   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk
> > \
> > -   options:dpdk-devargs=eth_af_packet0,iface=eth0
> > -
> > -More information on the different types of virtual DPDK PMDs can be found
> > in -the `DPDK documentation -
> > <http://dpdk.org/doc/guides/nics/overview.html>`__.
> > -
> > -Note: Not all DPDK virtual PMD drivers have been tested and verified to
> > work.
> > -
> >  EMC Insertion Probability
> >  -
> >  By default 1 in every 100 flows are inserted into the Exact Match Cache
> > (EMC).
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index 4b4dc119a..c1e6ea78c 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -34,4 +34,5 @@ The DPDK Datapath
> > /topics/dpdk/phy
> > /topics/dpdk/vhost-user
> > /topics/dpdk/ring
> > +   /topics/dpdk/vdev
> > /topics/dpdk/pmd
> > diff --git a/Documentation/topics/dpdk/vdev.rst
> > b/Documentation/topics/dpdk/vdev.rst
> 
> Compilation error, vdev.rst not listed in Documentation/automake.mk
> 
> > new file mode 100644
> > index 0..1b00ac573
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/vdev.rst
> > @@ -0,0 +1,59 @@
> > +..
> > +  Copyright 2018, Red Hat, Inc.
> > +
> > +  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 Virtual Devices
> > +
> > +
> 
> Support for vdevs was added as part of OVS 2.7, vers

Re: [ovs-dev] [PATCH v2 1/9] doc: Add an overview of the 'dpdk' port

[Stephen Finucane]

On Wed, 2018-04-18 at 15:30 +, Stokes, Ian wrote:
> > These ports are used to allow ingress/egress from the host and are
> > therefore _reasonably_ important. However, there is no clear overview of
> > what these ports actually are or why things are done the way they are.
> > Start closing this gap by providing a standalone example of using these
> > ports along with a little more detailed overview of the binding process.
> > 
> > There is additional cleanup to be done for the DPDK howto, but that will
> > be done separately.
> 
> This patch breaks compilation with the following
> 
> The following files are in git but not the distribution:
> Documentation/topics/dpdk/phy.rst
> 
> Need to add it to Documentation/automake.at

Whoops. I was building this with 'sphinx-build' directly to avoid
installing all the other build dependencies. Fixed now.

> > 
> > We enable the TODO directive so we can actually start calling out some
> > TODOs.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> > v2:
> > - Add TODO for multiple ports sharing the same bus slot function
> >   (ian.stokes)
> > ---
> >  Documentation/conf.py   |   2 +-
> >  Documentation/topics/dpdk/index.rst |   1 +
> >  Documentation/topics/dpdk/phy.rst   | 115
> > 
> >  3 files changed, 117 insertions(+), 1 deletion(-)  create mode 100644
> > Documentation/topics/dpdk/phy.rst
> > 
> > diff --git a/Documentation/conf.py b/Documentation/conf.py index
> > 6ab144c5d..babda21de 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -32,7 +32,7 @@ needs_sphinx = '1.1'
> >  # Add any Sphinx extension module names here, as strings. They can be  #
> > extensions coming with Sphinx (named 'sphinx.ext.*') or your custom  #
> > ones.
> > -extensions = []
> > +extensions = ['sphinx.ext.todo']
> > 
> >  # Add any paths that contain templates here, relative to this directory.
> >  templates_path = ['_templates']
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index da148b323..5f836a6e9 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -28,5 +28,6 @@ The DPDK Datapath
> >  .. toctree::
> > :maxdepth: 2
> > 
> > +   phy
> > vhost-user
> > ring
> > diff --git a/Documentation/topics/dpdk/phy.rst
> > b/Documentation/topics/dpdk/phy.rst
> > new file mode 100644
> > index 0..a3f8b475c
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/phy.rst
> > @@ -0,0 +1,115 @@
> > +..
> > +  Copyright 2018, Red Hat, Inc.
> > +
> > +  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 Physical Ports
> > +===
> > +
> > +The netdev datapath allows attaching of DPDK-backed physical interfaces
> > +in order to provide high-performance ingress/egress from the host.
> > +
> > +.. versionchanged:: 2.7.0
> > +
> > +   Before Open vSwitch 2.7.0, it was necessary to prefix port names with
> > a
> > +   ``dpdk`` prefix. Starting with 2.7.0, this is no longer necessary.
> > +
> > +.. todo::
> > +
> > +   Add an example for multiple ports share the same bus slot function.
> > +
> > +Quick Example
> > +-
> > +
> > +This example demonstrates how to bind two ``dpdk`` ports, bound to
> > +p

Re: [ovs-dev] [PATCH v1 3/4] docs: Fix sphinx urls.

[Stephen Finucane]

On Thu, 2018-04-19 at 11:49 +0100, Ian Stokes wrote:
> Update dead url links for sphinx documentation to avoid
> make check-docs failing.
> 
> Cc: Stephen Finucane <step...@that.guru>
> Fixes: 26ea2d409 ("docs: Add writing guide")
> Fixes: 73c76b447 ("doc: Add info on building documentation")
> Signed-off-by: Ian Stokes <ian.sto...@intel.com>
> ---
>  Documentation/internals/contributing/documentation-style.rst | 3 ++-
>  Documentation/intro/install/documentation.rst| 4 ++--
>  2 files changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/internals/contributing/documentation-style.rst 
> b/Documentation/internals/contributing/documentation-style.rst
> index 047f195..4e77db4 100644
> --- a/Documentation/internals/contributing/documentation-style.rst
> +++ b/Documentation/internals/contributing/documentation-style.rst
> @@ -441,4 +441,5 @@ Useful Links
>  - `Quick reStructuredText
><http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__
>  
> -- `Sphinx Documentation <http://sphinx.readthedocs.io/en/latest/rest.html>`__
> +- `Sphinx Documentation
> +  <http://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html>`__

You're looking for this link:

  http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

I'd rather we stuck to the authoritative resource on this.

> diff --git a/Documentation/intro/install/documentation.rst 
> b/Documentation/intro/install/documentation.rst
> index 0eeeab1..d7eb25d 100644
> --- a/Documentation/intro/install/documentation.rst
> +++ b/Documentation/intro/install/documentation.rst
> @@ -58,7 +58,7 @@ wish to install using ``pip``::
>  $ source .venv/bin/activate
>  $ pip install -r Documentation/requirements.txt
>  
> -__ http://www.sphinx-doc.org/install.html
> +__ http://www.sphinx-doc.org/en/master/usage/installation.html
>  
>  Configuring
>  ---
> @@ -86,4 +86,4 @@ Makefile targets::
>  Once built, documentation is available in the ``/Documentation/_build`` 
> folder.
>  Open the root ``index.html`` to browse the documentation.
>  
> -__ http://www.sphinx-doc.org/config.html
> +__ http://www.sphinx-doc.org/en/master/config.html

Note that I'm planning to move this to 'usage/configuration.html'
shortly (I'm the one who's moving all those docs around). Not much we
can do until then though.

The one link aside, this LGTM.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v1 2/4] docs: Fix style guide url in DocumentationStyle.rst.

[Stephen Finucane]

On Thu, 2018-04-19 at 11:49 +0100, Ian Stokes wrote:
> The link used for IBM Style Guide is no longer valid. As there is no
> longer a valid link via redbooks remove the url to avoid make
> check-docs failing.
> 
> Cc: Stephen Finucane <step...@that.guru>
> Fixes: 26ea2d409 ("docs: Add writing guide")
> Signed-off-by: Ian Stokes <ian.sto...@intel.com>
> ---
>  Documentation/internals/contributing/documentation-style.rst | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/Documentation/internals/contributing/documentation-style.rst 
> b/Documentation/internals/contributing/documentation-style.rst
> index 9c47bd6..047f195 100644
> --- a/Documentation/internals/contributing/documentation-style.rst
> +++ b/Documentation/internals/contributing/documentation-style.rst
> @@ -358,8 +358,7 @@ Writing Style
>  -
>  
>  Follow these guidelines to ensure readability and consistency of the Open
> -vSwitch documentation. These guidelines are based on the `IBM Style Guide
> -<http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`__.
> +vSwitch documentation. These guidelines are based on the `IBM Style Guide`.

s/`IBM Style Guide`/*IBM Style Guide*/

(I recently learnt the former means default role, which defaults to
italics but could actually be anything depending on configuration.
You're better off explicitly requesting italics)

In addition, I did find the following links which could be used:

 * http://ptgmedia.pearsoncmg.com/images/9780132101301/samplepages/0132
   101300.pdf
 * https://www.ibm.com/developerworks/library/styleguidelines/ (for
   developerWorks, but the ideas are the same)
 * https://www.safaribooksonline.com/library/view/the-ibm-style/9780132
   118989/ (paywall)

We could use any of these, if we chose. However, italics aside, I'm
still happy with this as-is so...

Acked-by: Stephen Finucane <step...@that.guru>

>  - Use standard US English
>  

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v1 4/4] docs: Fix urls in index.rst.

[Stephen Finucane]

On Thu, 2018-04-19 at 11:49 +0100, Ian Stokes wrote:
> This patch prepends 'www.' to openvswitch urls in index.rst. Without this
> make check-docs fails when verifying url liveness. Also remove url
> referencing ovsdb-server(5) as these are no longer accessible.
> 
> Cc: Stephen Finucane <step...@that.guru>
> Fixes: 4f6ec357c ("doc: Populate 'ref' section")
> Signed-off-by: Ian Stokes <ian.sto...@intel.com>

Acked-by: Stephen Finucane <step...@that.guru>

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v1 1/4] Docs: Fix sflow documentation url and markup.

[Stephen Finucane]

On Thu, 2018-04-19 at 11:49 +0100, Ian Stokes wrote:
> The link url link for the blog in sflow documentation causes make
> check-docs to fail with a broken link warning. Fix this by correcting
> the url address. Also use correct markup for note regarding the
> configuration of sflow.
> 
> CC: Stephen Finucane <step...@that.guru>
> Fixes: 198c5d3d0 ("doc: Add sFlow cookbook from website")
> Signed-off-by: Ian Stokes <ian.sto...@intel.com>

femotonit: s/Docs/docs/ (for the summary). Other than that...

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 0/8] Split up the DPDK how-to

[Stephen Finucane]

On Mon, 2018-04-09 at 15:15 +, Stokes, Ian wrote:
> > The DPDK howto has slowly morphed into a catch all for everything DPDK,
> > which goes against the original design goal for 'howto' documents [*].
> > This series attempts to return some sanity to the universe by splitting
> > this document into many more 'topic' documents. Along the way, we add a
> > lot of semantic markup, rework some text, and add an overview on 'dpdk'-
> > type ports (the original goal here).
> 
> Thanks for working on this Stephen.
> 
> I'm in favor of improving the documentation but we need to be careful
> when splitting it further apart. I think we should do this only where
> it makes sense.
> 
> Since moving to the current documentation design layout a common
> complaint I've heard at the community call is that users don't know
> where to find specific info as there are multiple locations dealing
> with the same topic. It can be argued that this info exists in
> different locations due to the differences in the type of content
> expected i.e. the difference between what is put in an intro, how-to
> or tutorial. But this can be non-obvious to a user. It seems the
> technical details of these differences are hampering the ease of use
> from a user POV.
> 
> I'd agree the previous approach of having a single DPDK doc catch all
> is far from ideal but one aspect users liked was that it was a single
> clear location.

I both understand and agree with all the above: there's definitely room
for improvement here and it's quite likely that we've made things less
discoverable in how we approached this. That said, I'd be very wary of
any kind of knee jerk reaction, whereby we go from one extreme to
another. As anyone who's ever worked with internal wikis on crufty
codebases will realise, things become increasingly difficult to
understand and maintain when you stop enforcing strict organization
around where things should go. That's not something I want to embrace.

The original intention of splitting this stuff up was so that we could
focus on different kinds of users:

- tutorials: beginners wishing to get started with OVS
- howtos: more experience users wishing to attain a given configuration
- topics: advanced users wishing to deep dive on certain areas

Something like a document map would help, however, I think a better
plan would be to ensure we provide mechanisms to guide people from one
section to another. This could be achieved by adding additional cross-
references (For more information on this topic, refer to XYZ) along
with 'Further Reading' sections at the bottom of the document. I've
touched on this in v2 of this series.

I think the best thing you could do here is get specific examples of
where the docs fall down via proper usability testing. I've heard lots
of complaints about various aspects of the docs but have never
collected these to build up a clear picture (with the exception of the
tunnelling documentation, which has come up more times than I can
count). My work on OVS occurs almost entirely off the clock so this is
not something I would be able to tackle. However, I have asked about
this internally and will continue to do so. In addition, I do think
this may be something Intel could invest some of their considerable
resources in addressing, perhaps instead of writing yet more OVS blogs
(something Red Hat is also guilty of).

In any case, I am happy to help out here and would like to see the docs
be the best docs they can be (TM). I do think this series is a good one
that adds lots of useful information and I also think it's something we
can build upon going forward. Be sure to let me know if you have ideas
on the off chance that I could help you drive them forward.

Stephen

> Possibly a document map at a high level could help with this.
> 
> I be interested for others input on this series as well.
> 
> Thanks
> Ian
> > 
> > There's a good chance I've made some mistakes in the process and I've left
> > TODOs for someone to resolve now or at a future date. I welcome feedback
> > on both of these.
> > 
> > Now to go back to figure how exactly NUMA affinity works for and affects
> > PMD threads...
> > 
> > [*] 'howto' documents are supposed to be brief, high-level overviews on
> > a particular group of features, with a focus on the user. They're
> > not as all-encompassing as a 'tutorial', but not as specific as a
> > 'topic'.
> > 
> > Stephen Finucane (8):
> >   doc: Add an overview of the 'dpdk' port
> >   doc: Add "PMD" topic document
> >   doc: Move additional sections to "physical ports" doc
> >   doc: Move "QoS" guide to its own document
> >   doc: Add "bridge" topic document
> >   doc: Move "pdump" guide to its own 

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

[Stephen Finucane]

This details configuration steps that apply to the entire bridge, rather
than individual ports.

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

[ovs-dev] [PATCH v2 9/9] doc: Final cleanup of the DPDK documents

[Stephen Finucane]

This concludes the cleanup by fixing some nits and adding some
additional cross-references.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Add changes to DPDK topic index doc
---
 Documentation/howto/dpdk.rst| 51 -
 Documentation/topics/dpdk/index.rst |  6 +
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index e65e7dfaa..199b8be65 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -25,23 +25,26 @@
 Using Open vSwitch with DPDK
 
 
-This document describes how to use Open vSwitch with DPDK datapath.
+This document describes how to use Open vSwitch with DPDK datapath. For more
+detailed information, refer to the various :doc:`DPDK topic guides
+`.
 
 .. important::
 
Using the DPDK datapath requires building OVS with DPDK support. Refer to
:doc:`/intro/install/dpdk` for more information.
 
-Ports and Bridges
--
+Overview
+
 
-ovs-vsctl can be used to set up bridges and other Open vSwitch features.
-Bridges should be created with a ``datapath_type=netdev``::
+:program:`ovs-vsctl` can be used to set up bridges and other Open vSwitch
+features.  Bridges should be created with a ``datapath_type=netdev``::
 
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
 
-ovs-vsctl can also be used to add DPDK devices. ovs-vswitchd should print the
-number of dpdk devices found in the log file::
+:program:`ovs-vsctl` can also be used to add DPDK devices.
+:program:`ovs-vswitchd` should print the number of ``dpdk`` devices found in
+the log file::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs=:01:00.0
@@ -59,14 +62,13 @@ is suggested::
 
 .. important::
 
-Hotplugging physical interfaces is not supported using the above syntax.
-This is expected to change with the release of DPDK v18.05. For information
-on hotplugging physical interfaces, you should instead refer to
-:ref:`port-hotplug`.
+Hotplugging physical interfaces is not supported for these devices.  This
+is expected to change with the release of DPDK v18.05. For information on
+hotplugging physical interfaces, refer to :ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
-DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
-``ps`` commands::
+DPDK devices and consumes 100% of the core, as can be checked from
+:command:`top` and :command:`ps` commands::
 
 $ top -H
 $ ps -eLo pid,psr,comm | grep pmd
@@ -79,7 +81,7 @@ set. For example::
 -- set Interface p0 type=dpdk options:dpdk-devargs=:01:00.0 \
 -- set Interface p1 type=dpdk options:dpdk-devargs=:01:00.1
 
-To stop ovs-vswitchd & delete bridge, run::
+To stop :program:`ovs-vswitchd` and delete the bridge, run::
 
 $ ovs-appctl -t ovs-vswitchd exit
 $ ovs-appctl -t ovsdb-server exit
@@ -137,13 +139,16 @@ Add test flows to forward packets between DPDK port 0 and 
port 1::
 
 Transmit traffic into either port. You should see it returned via the other.
 
+More information on the ``dpdk`` ports can be found in :doc:`/topics/dpdk/phy`.
+
 .. _dpdk-vhost-loopback:
 
 PHY-VM-PHY (vHost Loopback)
 ---
 
 Add a userspace bridge, two ``dpdk`` (PHY) ports, and two ``dpdkvhostuser``
-ports::
+ports. It is assumed that the physical ports are already bound to DPDK, as
+described in :ref:`dpdk-binding-nics`::
 
 # Add userspace bridge
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
@@ -221,19 +226,7 @@ described in :ref:`dpdk-testpmd`. Once compiled, run the 
application::
 $ set fwd mac retry
 $ start
 
-When you finish testing, bind the vNICs back to kernel::
-
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:03.0
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:04.0
-
-.. note::
-
-  Valid PCI IDs must be passed in above example. The PCI IDs can be retrieved
-  like so::
-
-  $ $DPDK_DIR/usertools/dpdk-devbind.py --status
-
-More information on the dpdkvhostuser ports can be found in
+More information on the ``dpdkvhostuser`` ports can be found in
 :doc:`/topics/dpdk/vhost-user`.
 
 PHY-VM-PHY (vHost Loopback) (Kernel Forwarding)
@@ -277,7 +270,7 @@ devices to bridge ``br0``. Once complete, follow the below 
steps:
$ ovs-vsctl set Interface phy0 options:n_rxq=2
$ ovs-vsctl set Interface phy1 options:n_rxq=2
 
-2. Instantiate Guest VM using QEMU cmdline
+2. Instantiate Guest VM using QEMU command line
 
We must configure with appropriate software versions to ensure this feature
is supported.
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 181f61abb..79d3af379 100644
--- a/Documentation/topics/dpdk/index

[ovs-dev] [PATCH v2 8/9] doc: Add "jumbo frames" topic document

[Stephen Finucane]

We include refrences from the physical and vhost-user interface guides.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Don't split the document into multiple docs
---
 Documentation/howto/dpdk.rst   | 52 ++
 Documentation/topics/dpdk/index.rst|  1 +
 Documentation/topics/dpdk/jumbo-frames.rst | 71 ++
 Documentation/topics/dpdk/phy.rst  |  6 +++
 Documentation/topics/dpdk/vhost-user.rst   |  6 +++
 5 files changed, 87 insertions(+), 49 deletions(-)
 create mode 100644 Documentation/topics/dpdk/jumbo-frames.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 1a0fb6df1..e65e7dfaa 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -48,9 +48,9 @@ number of dpdk devices found in the log file::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs=:01:00.1
 
-Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated
-with multiple ports. Using a PCI device like above won't work. Instead, below
-usage is suggested::
+Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated with
+multiple ports. Using a PCI device like above won't work. Instead, below usage
+is suggested::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:01"
@@ -85,52 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-Jumbo Frames
-
-
-By default, DPDK ports are configured with standard Ethernet MTU (1500B). To
-enable Jumbo Frames support for a DPDK port, change the Interface's
-``mtu_request`` attribute to a sufficiently large value. For example, to add a
-DPDK Phy port with MTU of 9000::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-  options:dpdk-devargs=:01:00.0 mtu_request=9000
-
-Similarly, to change the MTU of an existing port to 6200::
-
-$ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
-
-Some additional configuration is needed to take advantage of jumbo frames with
-vHost ports:
-
-1. *mergeable buffers* must be enabled for vHost ports, as demonstrated in the
-   QEMU command line snippet below::
-
-   -netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \
-   -device virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on
-
-2. Where virtio devices are bound to the Linux kernel driver in a guest
-   environment (i.e. interfaces are not bound to an in-guest DPDK driver), the
-   MTU of those logical network interfaces must also be increased to a
-   sufficiently large value. This avoids segmentation of Jumbo Frames received
-   in the guest. Note that 'MTU' refers to the length of the IP packet only,
-   and not that of the entire frame.
-
-   To calculate the exact MTU of a standard IPv4 frame, subtract the L2 header
-   and CRC lengths (i.e. 18B) from the max supported frame size.  So, to set
-   the MTU for a 9018B Jumbo Frame::
-
-   $ ip link set eth1 mtu 9000
-
-When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
-increased, such that a full Jumbo Frame of a specific size may be accommodated
-within a single mbuf segment.
-
-Jumbo frame support has been validated against 9728B frames, which is the
-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.
-
 .. _dpdk-ovs-in-guest:
 
 OVS with DPDK Inside VMs
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index d083d929e..181f61abb 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -39,3 +39,4 @@ The DPDK Datapath
/topics/dpdk/pmd
/topics/dpdk/qos
/topics/dpdk/pdump
+   /topics/dpdk/jumbo-frames
diff --git a/Documentation/topics/dpdk/jumbo-frames.rst 
b/Documentation/topics/dpdk/jumbo-frames.rst
new file mode 100644
index 0..692b291ac
--- /dev/null
+++ b/Documentation/topics/dpdk/jumbo-frames.rst
@@ -0,0 +1,71 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 head

[ovs-dev] [PATCH v2 0/9] Split up the DPDK how-to

[Stephen Finucane]

The DPDK howto has slowly morphed into a catch all for everything DPDK,
which goes against the original design goal for 'howto' documents [*].
This series attempts to return some sanity to the universe by splitting
this document into many more 'topic' documents. Along the way, we add a
lot of semantic markup, rework some text, and add an overview on
'dpdk'-type ports (the original goal here).

There's a good chance I've made some mistakes in the process and I've
left TODOs for someone to resolve now or at a future date. I welcome
feedback on both of these.

[*] 'howto' documents are supposed to be brief, high-level overviews on
a particular group of features, with a focus on the user. They're
not as all-encompassing as a 'tutorial', but not as specific as a
'topic'.

Changes since v1:
- Addressed comments from Ian Stokes

Stephen Finucane (9):
  doc: Add an overview of the 'dpdk' port
  doc: Add "PMD" topic document
  doc: Move additional sections to "physical ports" doc
  doc: Add "vdev" topic document
  doc: Move "QoS" guide to its own document
  doc: Add "bridge" topic document
  doc: Move "pdump" guide to its own document
  doc: Add "jumbo frames" topic document
  doc: Final cleanup of the DPDK documents

 Documentation/conf.py  |   2 +-
 Documentation/howto/dpdk.rst   | 454 +++--
 Documentation/topics/dpdk/bridge.rst   | 104 +++
 Documentation/topics/dpdk/index.rst|  20 +-
 Documentation/topics/dpdk/jumbo-frames.rst |  71 +
 Documentation/topics/dpdk/pdump.rst|  65 +
 Documentation/topics/dpdk/phy.rst  | 226 ++
 Documentation/topics/dpdk/pmd.rst  | 156 ++
 Documentation/topics/dpdk/qos.rst  |  76 +
 Documentation/topics/dpdk/ring.rst |   5 +
 Documentation/topics/dpdk/vdev.rst |  64 
 Documentation/topics/dpdk/vhost-user.rst   |  28 +-
 12 files changed, 843 insertions(+), 428 deletions(-)
 create mode 100644 Documentation/topics/dpdk/bridge.rst
 create mode 100644 Documentation/topics/dpdk/jumbo-frames.rst
 create mode 100644 Documentation/topics/dpdk/pdump.rst
 create mode 100644 Documentation/topics/dpdk/phy.rst
 create mode 100644 Documentation/topics/dpdk/pmd.rst
 create mode 100644 Documentation/topics/dpdk/qos.rst
 create mode 100644 Documentation/topics/dpdk/vdev.rst

-- 
2.14.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH v2 1/9] doc: Add an overview of the 'dpdk' port

[Stephen Finucane]

These ports are used to allow ingress/egress from the host and are
therefore _reasonably_ important. However, there is no clear overview of
what these ports actually are or why things are done the way they are.
Start closing this gap by providing a standalone example of using these
ports along with a little more detailed overview of the binding process.

There is additional cleanup to be done for the DPDK howto, but that will
be done separately.

We enable the TODO directive so we can actually start calling out some
TODOs.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Add TODO for multiple ports sharing the same bus slot function
  (ian.stokes)
---
 Documentation/conf.py   |   2 +-
 Documentation/topics/dpdk/index.rst |   1 +
 Documentation/topics/dpdk/phy.rst   | 115 
 3 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/topics/dpdk/phy.rst

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6ab144c5d..babda21de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -32,7 +32,7 @@ needs_sphinx = '1.1'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index da148b323..5f836a6e9 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -28,5 +28,6 @@ The DPDK Datapath
 .. toctree::
:maxdepth: 2
 
+   phy
vhost-user
ring
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
new file mode 100644
index 0..a3f8b475c
--- /dev/null
+++ b/Documentation/topics/dpdk/phy.rst
@@ -0,0 +1,115 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 Physical Ports
+===
+
+The netdev datapath allows attaching of DPDK-backed physical interfaces in
+order to provide high-performance ingress/egress from the host.
+
+.. versionchanged:: 2.7.0
+
+   Before Open vSwitch 2.7.0, it was necessary to prefix port names with a
+   ``dpdk`` prefix. Starting with 2.7.0, this is no longer necessary.
+
+.. todo::
+
+   Add an example for multiple ports share the same bus slot function.
+
+Quick Example
+-
+
+This example demonstrates how to bind two ``dpdk`` ports, bound to physical
+interfaces identified by hardware IDs ``:01:00.0`` and ``:01:00.1``, to
+an existing bridge called ``br0``::
+
+$ ovs-vsctl add-port br0 dpdk-p0 \
+   -- set Interface dpdk-p0 type=dpdk options:dpdk-devargs=:01:00.0
+$ ovs-vsctl add-port br0 dpdk-p1 \
+   -- set Interface dpdk-p1 type=dpdk options:dpdk-devargs=:01:00.1
+
+For the above example to work, the two physical interfaces must be bound to
+the DPDK poll-mode drivers in userspace rather than the traditional kernel
+drivers. See the `binding NIC drivers ` section for details.
+
+.. _dpdk-binding-nics:
+
+Binding NIC Drivers
+---
+
+DPDK operates entirely in userspace and, as a result, requires use of its own
+poll-mode drivers in user space for physical interfaces and a passthrough-style
+driver for the devices in kernel space.
+
+There are two different tools for binding drivers: :command:`driverctl` which
+is a generic tool for persistently configuring alternative device drivers, and
+:command:`dpdk-devbind` which is a DPDK-specific tool and whose changes do not
+persist across reboots. In addition, there are two options available for this
+kernel space driver - VFIO (Virtual Function I/O) and UIO (Userspace I/O) -
+along with a number of drivers for each option. We will demonstrate examples of
+both tools and will use the ``vfio-pci`` driver, which is the more secure,
+robust driver of those available. More information can be found in the `DPDK
+documentati

[ovs-dev] [PATCH v2 2/9] doc: Add "PMD" topic document

[Stephen Finucane]

This continues the breakup of the huge DPDK "howto" into smaller
components. There are a couple of related changes included, such as
using "Rx queue" instead of "rxq" and noting how Tx queues cannot be
configured.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Add cross-references from 'pmd' doc to 'vhost-user' and 'phy' docs
- Add 'versionchanged' warning about automatic assignment of Rx queues
- Add a 'todo' to describe Tx queue behavior
---
 Documentation/howto/dpdk.rst |  86 -
 Documentation/topics/dpdk/index.rst  |   1 +
 Documentation/topics/dpdk/phy.rst|  12 +++
 Documentation/topics/dpdk/pmd.rst| 156 +++
 Documentation/topics/dpdk/vhost-user.rst |  17 ++--
 5 files changed, 177 insertions(+), 95 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pmd.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 79b626c76..388728363 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -81,92 +81,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-PMD Thread Statistics
--
-
-To show current stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-show
-
-To clear previous stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-clear
-
-Port/RXQ Assigment to PMD Threads
--
-
-To show port/rxq assignment::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-To change default rxq assignment to pmd threads, rxqs may be manually pinned to
-desired cores using::
-
-$ ovs-vsctl set Interface  \
-other_config:pmd-rxq-affinity=
-
-where:
-
--  is a CSV list of ``:`` values
-
-For example::
-
-$ ovs-vsctl set interface dpdk-p0 options:n_rxq=4 \
-other_config:pmd-rxq-affinity="0:3,1:7,3:8"
-
-This will ensure:
-
-- Queue #0 pinned to core 3
-- Queue #1 pinned to core 7
-- Queue #2 not pinned
-- Queue #3 pinned to core 8
-
-After that PMD threads on cores where RX queues was pinned will become
-``isolated``. This means that this thread will poll only pinned RX queues.
-
-.. warning::
-  If there are no ``non-isolated`` PMD threads, ``non-pinned`` RX queues will
-  not be polled. Also, if provided ``core_id`` is not available (ex. this
-  ``core_id`` not in ``pmd-cpu-mask``), RX queue will not be polled by any PMD
-  thread.
-
-If pmd-rxq-affinity is not set for rxqs, they will be assigned to pmds (cores)
-automatically. The processing cycles that have been stored for each rxq
-will be used where known to assign rxqs to pmd based on a round robin of the
-sorted rxqs.
-
-For example, in the case where here there are 5 rxqs and 3 cores (e.g. 3,7,8)
-available, and the measured usage of core cycles per rxq over the last
-interval is seen to be:
-
-- Queue #0: 30%
-- Queue #1: 80%
-- Queue #3: 60%
-- Queue #4: 70%
-- Queue #5: 10%
-
-The rxqs will be assigned to cores 3,7,8 in the following order:
-
-Core 3: Q1 (80%) |
-Core 7: Q4 (70%) | Q5 (10%)
-core 8: Q3 (60%) | Q0 (30%)
-
-To see the current measured usage history of pmd core cycles for each rxq::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-.. note::
-
-  A history of one minute is recorded and shown for each rxq to allow for
-  traffic pattern spikes. An rxq's pmd core cycles usage changes due to traffic
-  pattern or reconfig changes will take one minute before they are fully
-  reflected in the stats.
-
-Rxq to pmds assignment takes place whenever there are configuration changes
-or can be triggered by using::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-rebalance
-
 QoS
 ---
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 5f836a6e9..dfde88377 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -31,3 +31,4 @@ The DPDK Datapath
phy
vhost-user
ring
+   pmd
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index a3f8b475c..ad191dad0 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -113,3 +113,15 @@ tool::
 For more information, refer to the `DPDK documentation `__.
 
 .. _dpdk-drivers: http://dpdk.org/doc/guides/linux_gsg/linux_drivers.html
+
+.. _dpdk-phy-multiqueue:
+
+Multiqueue
+--
+
+Poll Mode Driver (PMD) threads are the threads that do the heavy lifting for
+the DPDK datapath. Correct configuration of PMD threads and the Rx queues they
+utilize is a requirement in order to deliver the high-performance possible with
+DPDK acceleration. It is possible to configure multiple Rx queues for ``dpdk``
+ports, thus ensuring this is not a bottleneck for performance. For information
+on configuring PMD threads, refer to :doc:`pmd`.
diff --git a/Documentation/topics/dpdk/pmd.rst 
b/Documentation/topics/dpdk/pmd.rst
new file mode 100644
index 0..1be25

[ovs-dev] [PATCH v2 7/9] doc: Move "pdump" guide to its own document

[Stephen Finucane]

Yet another section that's far too detailed for someone getting started
with DPDK in OVS. Split it out.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst| 39 --
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/pdump.rst | 65 +
 3 files changed, 66 insertions(+), 39 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pdump.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index b3cba19b2..1a0fb6df1 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,45 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-pdump
--
-
-pdump allows you to listen on DPDK ports and view the traffic that is passing
-on them. To use this utility, one must have libpcap installed on the system.
-Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
-``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
-
-.. warning::
-  A performance decrease is expected when using a monitoring application like
-  the DPDK pdump app.
-
-To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
-directory in DPDK, ``make`` the application and run like so::
-
-$ sudo ./build/app/dpdk-pdump -- \
---pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
---server-socket-path=/usr/local/var/run/openvswitch
-
-The above command captures traffic received on queue 0 of port 0 and stores it
-in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
-pcap locations are of course also available to use. For example, to capture all
-packets that traverse port 0 in a single pcap file::
-
-$ sudo ./build/app/dpdk-pdump -- \
---pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-dev=/tmp/pkts.pcap' \
---server-socket-path=/usr/local/var/run/openvswitch
-
-``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
-typically resolves to ``/usr/local/var/run/openvswitch``.
-
-Many tools are available to view the contents of the pcap file. Once example is
-tcpdump. Issue the following command to view the contents of ``pkts.pcap``::
-
-$ tcpdump -r pkts.pcap
-
-More information on the pdump app and its usage can be found in the `DPDK docs
-<http://dpdk.org/doc/guides/tools/pdump.html>`__.
-
 Jumbo Frames
 
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index fd7cf38b5..d083d929e 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -38,3 +38,4 @@ The DPDK Datapath
/topics/dpdk/vdev
/topics/dpdk/pmd
/topics/dpdk/qos
+   /topics/dpdk/pdump
diff --git a/Documentation/topics/dpdk/pdump.rst 
b/Documentation/topics/dpdk/pdump.rst
new file mode 100644
index 0..f1a408989
--- /dev/null
+++ b/Documentation/topics/dpdk/pdump.rst
@@ -0,0 +1,65 @@
+..
+  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.
+
+=
+pdump
+=
+
+pdump allows you to listen on DPDK ports and view the traffic that is passing
+on them. To use this utility, one must have libpcap installed on the system.
+Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
+``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
+
+.. warning::
+
+   A performance decrease is expected when using a monitoring application like
+   the DPDK pdump app.
+
+To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
+directory in DPDK, ``make`` the application and run like so::
+
+$ sudo ./build/app/dpdk-pdump -- \
+--pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
+--server-socket-path=/usr/local/var/run/openvswitch
+
+The above command captures traffic received on queue 0 of port 0 and stores it
+in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
+pcap locations are of course also available to use. For example, to capture all
+packets that traverse port 0 in a single pcap file::
+
+$ sudo ./build/app/dpdk-pdump -- \
+--pdump 'port=0,queue

[ovs-dev] [PATCH v2 3/9] doc: Move additional sections to "physical ports" doc

[Stephen Finucane]

The "hotplugging", "flow control", and "Rx checksum offload" sections
only apply to 'dpdk' ports and are too detailed to include in a
high-level howto. Move them, reworking some aspects of this in the
process.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Split out vdev into its own document (and patch)
- Add cross-references from DPDK howto guide to detailed topic guides
- Add flow control
---
 Documentation/howto/dpdk.rst| 103 ++--
 Documentation/topics/dpdk/index.rst |  11 ++--
 Documentation/topics/dpdk/phy.rst   |  86 ++
 3 files changed, 110 insertions(+), 90 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 388728363..531612880 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -57,8 +57,12 @@ usage is suggested::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
 
-Note: such syntax won't support hotplug. The hotplug is supposed to work with
-future DPDK release, v18.05.
+.. important::
+
+Hotplugging physical interfaces is not supported using the above syntax.
+This is expected to change with the release of DPDK v18.05. For information
+on hotplugging physical interfaces, you should instead refer to
+:ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
 DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
@@ -123,34 +127,6 @@ To clear the ingress policer configuration from the port::
 
 Refer to vswitch.xml for more details on ingress-policer.
 
-Flow Control
-
-
-Flow control can be enabled only on DPDK physical ports. To enable flow control
-support at tx side while adding a port, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:tx-flow-ctrl=true
-
-Similarly, to enable rx flow control, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:rx-flow-ctrl=true
-
-To enable flow control auto-negotiation, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:flow-ctrl-autoneg=true
-
-To turn ON the tx flow control at run time for an existing port, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
-
-The flow control parameters can be turned off by setting ``false`` to the
-respective parameter. To disable the flow control at tx side, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
-
 pdump
 -
 
@@ -236,16 +212,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.
 
-Rx Checksum Offload

-
-By default, DPDK physical ports are enabled with Rx checksum offload.
-
-Rx checksum offload can offer performance improvement only for tunneling
-traffic in OVS-DPDK because the checksum validation of tunnel packets is
-offloaded to the NIC. Also enabling Rx checksum may slightly reduce the
-performance of non-tunnel traffic, specifically for smaller size packet.
-
 .. _extended-statistics:
 
 Extended & Custom Statistics
@@ -278,52 +244,6 @@ 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.
 
-.. _port-hotplug:
-
-Port Hotplug
-
-
-OVS supports port hotplugging, allowing the use of ports that were not bound
-to DPDK when vswitchd was started.
-In order to attach a port, it has to be bound to DPDK using the
-``dpdk_nic_bind.py`` script::
-
-$ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio :01:00.0
-
-Then it can be attached to OVS::
-
-$ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
-options:dpdk-devargs=:01:00.0
-
-Detaching will be performed while processing del-port command::
-
-$ ovs-vsctl del-port dpdkx
-
-Sometimes, the del-port command may not detach the device.
-Detaching can be confirmed by the appearance of an INFO log.
-For example::
-
-INFO|Device ':04:00.1' has been detached
-
-If the log is not seen, then the port can be detached using::
-
-$ ovs-appctl netdev-dpdk/detach :01:00.0
-
-Detaching can be confirmed by console output::
-
-Device ':04:00.1' has been detached
-
-.. warning::
-Detaching should not be done if a device is known to be non-detachable, as
-this may cause the device to behave improperly when added back with
-add-port. The Chelsio Terminator adapters which use the cxgbe driver seem
-to be

[ovs-dev] [PATCH v2 5/9] doc: Move "QoS" guide to its own document

[Stephen Finucane]

Again, this stuff is too detailed for a high-level howto.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Keep flow control section in 'phy' document
---
 Documentation/howto/dpdk.rst| 42 
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/phy.rst   |  2 +
 Documentation/topics/dpdk/qos.rst   | 76 +
 4 files changed, 79 insertions(+), 42 deletions(-)
 create mode 100644 Documentation/topics/dpdk/qos.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 9cb76b7e1..3e04d8627 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,48 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-QoS

-
-Assuming you have a vhost-user port transmitting traffic consisting of packets
-of size 64 bytes, the following command would limit the egress transmission
-rate of the port to ~1,000,000 packets per second::
-
-$ ovs-vsctl set port vhost-user0 qos=@newqos -- \
---id=@newqos create qos type=egress-policer other-config:cir=4600 \
-other-config:cbs=2048`
-
-To examine the QoS configuration of the port, run::
-
-$ ovs-appctl -t ovs-vswitchd qos/show vhost-user0
-
-To clear the QoS configuration from the port and ovsdb, run::
-
-$ ovs-vsctl destroy QoS vhost-user0 -- clear Port vhost-user0 qos
-
-Refer to vswitch.xml for more details on egress-policer.
-
-Rate Limiting
---
-
-Here is an example on Ingress Policing usage. Assuming you have a vhost-user
-port receiving traffic consisting of packets of size 64 bytes, the following
-command would limit the reception rate of the port to ~1,000,000 packets per
-second::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=368000 \
-ingress_policing_burst=1000`
-
-To examine the ingress policer configuration of the port::
-
-$ ovs-vsctl list interface vhost-user0
-
-To clear the ingress policer configuration from the port::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=0
-
-Refer to vswitch.xml for more details on ingress-policer.
-
 pdump
 -
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index c1e6ea78c..d3c1e2099 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -36,3 +36,4 @@ The DPDK Datapath
/topics/dpdk/ring
/topics/dpdk/vdev
/topics/dpdk/pmd
+   /topics/dpdk/qos
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index 929f394ea..581984b63 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -126,6 +126,8 @@ DPDK acceleration. It is possible to configure multiple Rx 
queues for ``dpdk``
 ports, thus ensuring this is not a bottleneck for performance. For information
 on configuring PMD threads, refer to :doc:`pmd`.
 
+.. _dpdk-phy-flow-control:
+
 Flow Control
 
 
diff --git a/Documentation/topics/dpdk/qos.rst 
b/Documentation/topics/dpdk/qos.rst
new file mode 100644
index 0..b42140515
--- /dev/null
+++ b/Documentation/topics/dpdk/qos.rst
@@ -0,0 +1,76 @@
+..
+  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.
+
+
+Quality of Service (QoS)
+
+
+It is possible to apply both ingress and egress limiting when using the DPDK
+datapath. These are referred to as *QoS* and *Rate Limiting*, respectively.
+
+QoS (Egress Policing)
+-
+
+Assuming you have a :doc:`vhost-user port ` transmitting traffic
+consisting of packets of size 64 bytes, the following command would limit the
+egress transmission rate of the port to ~1,000,000 packets per second::
+
+$ ovs-vsctl set port vhost-user0 qos=@newqos -- \
+--id=@newqos create qos type=egress-policer other-config:cir=4600 \
+other-config:cbs=2048`
+
+To examine the QoS configuration of the port, run::
+
+$ ovs-appctl -t ovs-vswitchd qos/show vhost-user0
+
+To clear the QoS configuratio

[ovs-dev] [PATCH v2 4/9] doc: Add "vdev" topic document

[Stephen Finucane]

These are separate things from physical, ring and vhost-user interfaces
and deserve their own documents. A couple of small typos are fixed along
the way.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst| 29 --
 Documentation/topics/dpdk/index.rst |  1 +
 Documentation/topics/dpdk/vdev.rst  | 59 +
 3 files changed, 60 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/topics/dpdk/vdev.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 531612880..9cb76b7e1 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -244,35 +244,6 @@ 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.
 
-.. _vdev-support:
-
-Vdev Support
-
-
-DPDK provides drivers for both physical and virtual devices. Physical DPDK
-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'.
-
-Typically, the format expected is 'eth_' where 'x' is a
-unique identifier of your choice for the given port.
-
-For example to add a dpdk port that uses the 'null' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
-   options:dpdk-devargs=eth_null0
-
-Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
-   options:dpdk-devargs=eth_af_packet0,iface=eth0
-
-More information on the different types of virtual DPDK PMDs can be found in
-the `DPDK documentation
-<http://dpdk.org/doc/guides/nics/overview.html>`__.
-
-Note: Not all DPDK virtual PMD drivers have been tested and verified to work.
-
 EMC Insertion Probability
 -
 By default 1 in every 100 flows are inserted into the Exact Match Cache (EMC).
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 4b4dc119a..c1e6ea78c 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -34,4 +34,5 @@ The DPDK Datapath
/topics/dpdk/phy
/topics/dpdk/vhost-user
/topics/dpdk/ring
+   /topics/dpdk/vdev
/topics/dpdk/pmd
diff --git a/Documentation/topics/dpdk/vdev.rst 
b/Documentation/topics/dpdk/vdev.rst
new file mode 100644
index 0..1b00ac573
--- /dev/null
+++ b/Documentation/topics/dpdk/vdev.rst
@@ -0,0 +1,59 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 Virtual Devices
+
+
+DPDK provides drivers for both physical and virtual devices. Physical DPDK
+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``.
+
+.. note::
+
+Not all DPDK virtual PMD drivers have been tested and verified to work.
+
+Quick Example
+-
+
+To add a virtual ``dpdk`` devices, the ``dpdk-devargs`` argument should be of
+the format ``eth_``, where ``x``' is a unique identifier of
+your choice for the given port. For example to add a ``dpdk`` port that uses
+the ``null`` DPDK PMD driver, run::
+
+   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
+   options:dpdk-devargs=eth_null0
+
+Similarly, to add a ``dpdk`` port that uses the ``af_packet`` DPDK PMD driver,
+run::
+
+   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
+   options:dpdk-devargs=eth_af_packet0,iface=eth0
+
+More information on the different types of virtual DPDK PMDs can be found in
+the `DPDK documentation`__.
+
+__ http://dpdk.org/doc/guides/nics/overview.html
-- 
2.14.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 6/8] doc: Move "pdump" guide to its own document

[Stephen Finucane]

On Mon, 2018-04-09 at 15:17 +, Stokes, Ian wrote:
> Minor nit, would like to see a commit message here. I think you
> modify caption headers in the patch also, these could be kept in the
> final clean up patch of the series.

I've added the commit message and split the caption headers into a
separate patch.

Stephen

> Ian
> 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst| 39 --
> >  Documentation/topics/dpdk/index.rst |  7 
> > Documentation/topics/dpdk/pdump.rst | 65
> > +
> >  3 files changed, 72 insertions(+), 39 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/pdump.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index c01bf7a39..1a72e90bf 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -85,45 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
> >  $ ovs-appctl -t ovsdb-server exit
> >  $ ovs-vsctl del-br br0
> > 
> > -pdump
> > --
> > -
> > -pdump allows you to listen on DPDK ports and view the traffic that is
> > passing -on them. To use this utility, one must have libpcap installed on
> > the system.
> > -Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and -
> > ``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
> > -
> > -.. warning::
> > -  A performance decrease is expected when using a monitoring application
> > like
> > -  the DPDK pdump app.
> > -
> > -To use pdump, simply launch OVS as usual, then navigate to the
> > ``app/pdump`` -directory in DPDK, ``make`` the application and run like
> > so::
> > -
> > -$ sudo ./build/app/dpdk-pdump -- \
> > ---pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
> > ---server-socket-path=/usr/local/var/run/openvswitch
> > -
> > -The above command captures traffic received on queue 0 of port 0 and
> > stores it -in ``/tmp/pkts.pcap``. Other combinations of port numbers,
> > queues numbers and -pcap locations are of course also available to use.
> > For example, to capture all -packets that traverse port 0 in a single pcap
> > file::
> > -
> > -$ sudo ./build/app/dpdk-pdump -- \
> > ---pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-
> > dev=/tmp/pkts.pcap' \
> > ---server-socket-path=/usr/local/var/run/openvswitch
> > -
> > -``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
> > -typically resolves to ``/usr/local/var/run/openvswitch``.
> > -
> > -Many tools are available to view the contents of the pcap file. Once
> > example is -tcpdump. Issue the following command to view the contents of
> > ``pkts.pcap``::
> > -
> > -$ tcpdump -r pkts.pcap
> > -
> > -More information on the pdump app and its usage can be found in the `DPDK
> > docs -<http://dpdk.org/doc/guides/tools/pdump.html>`__.
> > -
> >  Jumbo Frames
> >  
> > 
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index 52cacaef6..c9b231f06 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -27,10 +27,17 @@ The DPDK Datapath
> > 
> >  .. toctree::
> > :maxdepth: 2
> > +   :caption: Bridges and Ports
> > 
> > bridge
> > phy
> > vhost-user
> > ring
> > +
> > +.. toctree::
> > +   :maxdepth: 2
> > +   :caption: Advanced Configuration
> > +
> > pmd
> > qos
> > +   pdump
> > diff --git a/Documentation/topics/dpdk/pdump.rst
> > b/Documentation/topics/dpdk/pdump.rst
> > new file mode 100644
> > index 0..f1a408989
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/pdump.rst
> > @@ -0,0 +1,65 @@
> > +..
> > +  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 speci

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

[Stephen Finucane]

On Mon, 2018-04-09 at 15:17 +, Stokes, Ian wrote:
> > This details configuration steps that apply to the entire bridge, rather
> > than individual ports.
> 
> Comments inline.
> 
> > 
> > Signed-off-by: Stephen Finucane <step...@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 0..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

Re: [ovs-dev] [PATCH 4/8] doc: Move "QoS" guide to its own document

[Stephen Finucane]

On Mon, 2018-04-09 at 15:16 +, Stokes, Ian wrote:
> > Again, this stuff is too detailed for a high-level howto.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst|  70 -
> >  Documentation/topics/dpdk/index.rst |   1 +
> >  Documentation/topics/dpdk/phy.rst   |   6 +++
> >  Documentation/topics/dpdk/qos.rst   | 100
> > 
> >  4 files changed, 107 insertions(+), 70 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/qos.rst
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index 4d993a0eb..608dde814 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -85,76 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
> >  $ ovs-appctl -t ovsdb-server exit
> >  $ ovs-vsctl del-br br0
> > 
> > -QoS
> > 
> > -
> > -Assuming you have a vhost-user port transmitting traffic consisting of
> > packets -of size 64 bytes, the following command would limit the egress
> > transmission -rate of the port to ~1,000,000 packets per second::
> > -
> > -$ ovs-vsctl set port vhost-user0 qos=@newqos -- \
> > ---id=@newqos create qos type=egress-policer other-
> > config:cir=4600 \
> > -other-config:cbs=2048`
> > -
> > -To examine the QoS configuration of the port, run::
> > -
> > -$ ovs-appctl -t ovs-vswitchd qos/show vhost-user0
> > -
> > -To clear the QoS configuration from the port and ovsdb, run::
> > -
> > -$ ovs-vsctl destroy QoS vhost-user0 -- clear Port vhost-user0 qos
> > -
> > -Refer to vswitch.xml for more details on egress-policer.
> > -
> > -Rate Limiting
> > ---
> > -
> > -Here is an example on Ingress Policing usage. Assuming you have a vhost-
> > user -port receiving traffic consisting of packets of size 64 bytes, the
> > following -command would limit the reception rate of the port to
> > ~1,000,000 packets per
> > -second::
> > -
> > -$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=368000 \
> > -ingress_policing_burst=1000`
> > -
> > -To examine the ingress policer configuration of the port::
> > -
> > -$ ovs-vsctl list interface vhost-user0
> > -
> > -To clear the ingress policer configuration from the port::
> > -
> > -$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=0
> > -
> > -Refer to vswitch.xml for more details on ingress-policer.
> > -
> > -Flow Control
> > -
> > -
> > -Flow control can be enabled only on DPDK physical ports. To enable flow
> > control -support at tx side while adding a port, run::
> > -
> > -$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> > -options:dpdk-devargs=:01:00.0 options:tx-flow-ctrl=true
> > -
> > -Similarly, to enable rx flow control, run::
> > -
> > -$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> > -options:dpdk-devargs=:01:00.0 options:rx-flow-ctrl=true
> > -
> > -To enable flow control auto-negotiation, run::
> > -
> > -$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
> > -options:dpdk-devargs=:01:00.0 options:flow-ctrl-autoneg=true
> > -
> > -To turn ON the tx flow control at run time for an existing port, run::
> > -
> > -$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
> > -
> > -The flow control parameters can be turned off by setting ``false`` to the
> > -respective parameter. To disable the flow control at tx side, run::
> > -
> > -$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
> > -
> >  pdump
> >  -
> > 
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index dfde88377..fe4d97b8b 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -32,3 +32,4 @@ The DPDK Datapath
> > vhost-user
> > ring
> > pmd
> > +   qos
> > diff --git a/Documentation/topics/dpdk/phy.rst
> > b/Documentation/topics/dpdk/phy.rst
> > index 507dac869..93aff628c 100644
> > --- a/Documentation/topics/dpdk/phy.rst
> > +++ b/Documentation/topics/dpdk/phy.rst
> > @@ -210,3 +210,9 @@ More information on the different types of virtual
> > DPDK PMDs can be found 

Re: [ovs-dev] [PATCH 3/8] doc: Move additional sections to "physical ports" doc

[Stephen Finucane]

On Mon, 2018-04-09 at 15:16 +, Stokes, Ian wrote:
> > The "vdev", "hotplugging", and "Rx checksum offload" sections only apply
> > to 'dpdk' ports and are too detailed to include in a high-level howto.
> 
> Should flow control be in here too? AFAIK it's phy port only.

Indeed it should. Done.

> > Move them, reworking some aspects of this in the process.
> 
> It may not be obvious to users that these are relevant to phy only
> and as such are found under Documentation/topics/dpdk/phy.rst.
> 
> We should be making it clear where these topics can be found to user
> at a higher level.
> 
> Have you considered a high level documentation map, possibly in
> Documentation/howto/dpdk.rst showing where feature docs can be found?

I've added a further reading section to the howto guide which should
address some of these issues. A more substantial follow up to come on
the cover letter.

> More comments below.
> 
> 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> >  Documentation/howto/dpdk.rst  | 93 +++---
> > -
> >  Documentation/topics/dpdk/phy.rst | 91
> > ++
> >  2 files changed, 97 insertions(+), 87 deletions(-)
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index c2324118d..4d993a0eb 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -57,8 +57,12 @@ usage is suggested::
> >  $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
> >  options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
> > 
> > -Note: such syntax won't support hotplug. The hotplug is supposed to work
> > with -future DPDK release, v18.05.
> > +.. important::
> > +
> > +Hotplugging physical interfaces is not supported using the above
> > syntax.
> > +This is expected to change with the release of DPDK v18.05. For
> > information
> > +on hotplugging physical interfaces, you should instead refer to
> > +:ref:`port-hotplug`.
> > 
> >  After the DPDK ports get added to switch, a polling thread continuously
> > polls  DPDK devices and consumes 100% of the core, as can be checked from
> > ``top`` and @@ -236,16 +240,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.
> > 
> > -Rx Checksum Offload
> > 
> > -
> > -By default, DPDK physical ports are enabled with Rx checksum offload.
> > -
> > -Rx checksum offload can offer performance improvement only for tunneling
> > -traffic in OVS-DPDK because the checksum validation of tunnel packets is
> > -offloaded to the NIC. Also enabling Rx checksum may slightly reduce the -
> > performance of non-tunnel traffic, specifically for smaller size packet.
> > -
> >  .. _extended-statistics:
> > 
> >  Extended & Custom Statistics
> > @@ -278,81 +272,6 @@ 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.
> > 
> > -.. _port-hotplug:
> > -
> > -Port Hotplug
> > -
> > -
> > -OVS supports port hotplugging, allowing the use of ports that were not
> > bound -to DPDK when vswitchd was started.
> > -In order to attach a port, it has to be bound to DPDK using the -
> > ``dpdk_nic_bind.py`` script::
> > -
> > -$ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio :01:00.0
> > -
> > -Then it can be attached to OVS::
> > -
> > -$ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
> > -options:dpdk-devargs=:01:00.0
> > -
> > -Detaching will be performed while processing del-port command::
> > -
> > -$ ovs-vsctl del-port dpdkx
> > -
> > -Sometimes, the del-port command may not detach the device.
> > -Detaching can be confirmed by the appearance of an INFO log.
> > -For example::
> > -
> > -INFO|Device ':04:00.1' has been detached
> > -
> > -If the log is not seen, then the port can be detached using::
> > -
> > -$ ovs-appctl netdev-dpdk/detach :01:00.0
> > -
> > -Detaching can be confirmed by console output::
> > -
> > -Device ':04:00.1' has been detached
> > -
> > -.. warning::

Re: [ovs-dev] [PATCH 2/8] doc: Add "PMD" topic document

[Stephen Finucane]

On Mon, 2018-04-09 at 15:16 +, Stokes, Ian wrote:
> > This continues the breakup of the huge DPDK "howto" into smaller
> > components. There are a couple of related changes included, such as using
> > "Rx queue" instead of "rxq" and noting how Tx queues cannot be configured.
> > 
> > We enable the TODO directive, so we can actually start calling out some
> > TODOs.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> >  Documentation/conf.py|   2 +-
> >  Documentation/howto/dpdk.rst |  86 ---
> >  Documentation/topics/dpdk/index.rst  |   1 +
> >  Documentation/topics/dpdk/phy.rst|  10 +++
> >  Documentation/topics/dpdk/pmd.rst| 139
> > +++
> >  Documentation/topics/dpdk/vhost-user.rst |  17 ++--
> >  6 files changed, 159 insertions(+), 96 deletions(-)  create mode 100644
> > Documentation/topics/dpdk/pmd.rst
> > 
> > diff --git a/Documentation/conf.py b/Documentation/conf.py index
> > 6ab144c5d..babda21de 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -32,7 +32,7 @@ needs_sphinx = '1.1'
> >  # Add any Sphinx extension module names here, as strings. They can be  #
> > extensions coming with Sphinx (named 'sphinx.ext.*') or your custom  #
> > ones.
> > -extensions = []
> > +extensions = ['sphinx.ext.todo']
> > 
> >  # Add any paths that contain templates here, relative to this directory.
> >  templates_path = ['_templates']
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index d717d2ebe..c2324118d 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -81,92 +81,6 @@ To stop ovs-vswitchd & delete bridge, run::
> >  $ ovs-appctl -t ovsdb-server exit
> >  $ ovs-vsctl del-br br0
> > 
> > -PMD Thread Statistics
> > --
> > -
> > -To show current stats::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-stats-show
> > -
> > -To clear previous stats::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-stats-clear
> > -
> > -Port/RXQ Assigment to PMD Threads
> > --
> > -
> > -To show port/rxq assignment::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-rxq-show
> > -
> > -To change default rxq assignment to pmd threads, rxqs may be manually
> > pinned to -desired cores using::
> > -
> > -$ ovs-vsctl set Interface  \
> > -other_config:pmd-rxq-affinity=
> > -
> > -where:
> > -
> > --  is a CSV list of ``:``
> > values
> > -
> > -For example::
> > -
> > -$ ovs-vsctl set interface dpdk-p0 options:n_rxq=4 \
> > -other_config:pmd-rxq-affinity="0:3,1:7,3:8"
> > -
> > -This will ensure:
> > -
> > -- Queue #0 pinned to core 3
> > -- Queue #1 pinned to core 7
> > -- Queue #2 not pinned
> > -- Queue #3 pinned to core 8
> > -
> > -After that PMD threads on cores where RX queues was pinned will become -
> > ``isolated``. This means that this thread will poll only pinned RX queues.
> > -
> > -.. warning::
> > -  If there are no ``non-isolated`` PMD threads, ``non-pinned`` RX queues
> > will
> > -  not be polled. Also, if provided ``core_id`` is not available (ex. this
> > -  ``core_id`` not in ``pmd-cpu-mask``), RX queue will not be polled by
> > any PMD
> > -  thread.
> > -
> > -If pmd-rxq-affinity is not set for rxqs, they will be assigned to pmds
> > (cores) -automatically. The processing cycles that have been stored for
> > each rxq -will be used where known to assign rxqs to pmd based on a round
> > robin of the -sorted rxqs.
> > -
> > -For example, in the case where here there are 5 rxqs and 3 cores (e.g.
> > 3,7,8) -available, and the measured usage of core cycles per rxq over the
> > last -interval is seen to be:
> > -
> > -- Queue #0: 30%
> > -- Queue #1: 80%
> > -- Queue #3: 60%
> > -- Queue #4: 70%
> > -- Queue #5: 10%
> > -
> > -The rxqs will be assigned to cores 3,7,8 in the following order:
> > -
> > -Core 3: Q1 (80%) |
> > -Core 7: Q4 (70%) | Q5 (10%)
> > -core 8: Q3 (60%) | Q0 (30%)
> > -
> > -To see the current measured usage history of pmd core cycles for each
> > rxq::
> > -
> > -$ ovs-appctl dpif-netdev/pmd-rxq-show
> > -
> > -.. note::
> > -
> > - 

Re: [ovs-dev] [PATCH 1/8] doc: Add an overview of the 'dpdk' port

[Stephen Finucane]

On Mon, 2018-04-09 at 15:15 +, Stokes, Ian wrote:
> > These ports are used to allow ingress/egress from the host and are
> > therefore _reasonably_ important. However, there is no clear overview of
> > what these ports actually are or why things are done the way they are.
> > Start closing this gap by providing a standalone example of using these
> > ports along with a little more detailed overview of the binding process.
> > 
> > There is additional cleanup to be done for the DPDK howto, but that will
> > be done separately.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > Cc: Ciara Loftus <ciara.lof...@intel.com>
> > Cc: Kevin Traynor <ktray...@redhat.com>
> > ---
> >  Documentation/topics/dpdk/index.rst |   1 +
> >  Documentation/topics/dpdk/phy.rst   | 111
> > 
> >  2 files changed, 112 insertions(+)
> >  create mode 100644 Documentation/topics/dpdk/phy.rst
> > 
> > diff --git a/Documentation/topics/dpdk/index.rst
> > b/Documentation/topics/dpdk/index.rst
> > index da148b323..5f836a6e9 100644
> > --- a/Documentation/topics/dpdk/index.rst
> > +++ b/Documentation/topics/dpdk/index.rst
> > @@ -28,5 +28,6 @@ The DPDK Datapath
> >  .. toctree::
> > :maxdepth: 2
> > 
> > +   phy
> > vhost-user
> > ring
> > diff --git a/Documentation/topics/dpdk/phy.rst
> > b/Documentation/topics/dpdk/phy.rst
> > new file mode 100644
> > index 0..1c18e4e3d
> > --- /dev/null
> > +++ b/Documentation/topics/dpdk/phy.rst
> > @@ -0,0 +1,111 @@
> > +..
> > +  Copyright 2018, Red Hat, Inc.
> > +
> > +  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 Physical Ports
> > +===
> > +
> > +The DPDK datapath provides a way to attach DPDK-backed physical
> > +interfaces to allow high-performance ingress/egress from the host.
> > +
> > +.. versionchanged:: 2.7.0
> > +
> > +   Before Open vSwitch 2.7.0, it was necessary to prefix port names with
> > a
> > +   ``dpdk`` prefix. Starting with 2.7.0, this is no longer necessary.
> > +
> > +Quick Example
> > +-
> > +
> > +This example demonstrates how to bind two ``dpdk`` ports, bound to
> > +physical interfaces identified by hardware IDs ``:01:00.0`` and
> > +``:01:00.1``, to an existing bridge called ``br0``::
> > +
> > +$ ovs-vsctl add-port br0 dpdk-p0 \
> > +   -- set Interface dpdk-p0 type=dpdk options:dpdk-
> > devargs=:01:00.0
> > +$ ovs-vsctl add-port br0 dpdk-p1 \
> > +   -- set Interface dpdk-p1 type=dpdk
> > + options:dpdk-devargs=:01:00.1
> > +
> > +For the above example to work, the two physical interfaces must be
> > +bound to the DPDK poll-mode drivers in userspace rather than the
> > +traditional kernel drivers. See the `binding NIC drivers  > nics>` section for details.
> 
> I think an example should be added here for when multiple ports share
> the same bus slot function.
> 
> Support for this was added in as part of OVS 2.9.
> 
> If not added here then we need to flag clearly that it's supported
> but that users need to consult the dpdk-binding-nic section for
> specifics.

This is only a quick intro so I don't think it would belong here.
However, we could definitely add this as another section. I'm not
familiar with this feature so would it be possible to submit this as a
follow-up? I'd be happy to review it from a docs persp

Re: [ovs-dev] [PATCH 2/2] dpdk docs: Drop file share in libvirt config.

[Stephen Finucane]

On Thu, 2018-04-12 at 08:24 +0100, Lam, Tiago wrote:
> On 11/04/2018 15:03, Stephen Finucane wrote:
> > On Wed, 2018-04-11 at 09:54 -0400, Aaron Conole wrote:
> > > Tiago Lam <tiago@intel.com> writes:
> > > 
> > > > When explaining on how to add vhost-user ports to a guest, using
> > > > libvirt, the following piece of configuration is used:
> > > >  
> > > >
> > > >
> > > >
> > > >
> > > >  
> > > > 
> > > > This is used to facilitate sharing of a DPDK directory between the host
> > > > and the guest. However, for this to work selinux also needs to be
> > > > configured (or disabled).  Furthermore, if one is using Ubuntu, libvirtd
> > > > would need to be added to complain only in AppArmor. Instead, in [1] it
> > > > is advised to use wget to get the DPDK sources over the internet, which
> > > > avoids this differentiation. Thus, we drop this piece of configuration
> > > > here as well and keep the example configuration as simple as possible.
> > > > 
> > > > This has been verified on both a Fedora 27 image and a Ubuntu 16.04 LTS
> > > > image.
> > > > 
> > > > [1] 
> > > > http://docs.openvswitch.org/en/latest/topics/dpdk/vhost-user/#dpdk-in-the-guest
> > > > 
> > > > Signed-off-by: Tiago Lam <tiago@intel.com>
> > > > ---
> > > > 
> > > > CC'ed Stephen,
> > > > 
> > > > I took the liberty of removing your TODO from here, as I read it to be 
> > > > related
> > > > to the (now removed) SELinux instruction below. If you think it should 
> > > > still be
> > > > there let me know and I'll gladly send a v2.
> > > 
> > > I think it should remain until the selinux issues have been addressed.
> > > 
> > > Is there a list somewhere of the AVC denials?  Maybe it makes sense to
> > > allow them.
> > 
> > If I'm reading this correctly, Tiago is saying these exceptions only
> > happen because we're sharing an arbitrary directory with the guest to
> > avoid downloading the DPDK sources twice. Given that there's a valid
> > workaround (just fetching sources twice), simply removing that section
> > of the XML removes the need to disable SELinux. If so, dropping the
> > warning does make sense in my mind.
> > 
> > Stephen
> > 
> 
> Thanks, Stephen. Yeah, that's what I was aiming at. In order to get the 
> file sharing working properly, one must fiddle around with either 
> SELinux or AppArmor, and that seems to be the sole reason why 
> `setenforce 0` is there. Losing the dependency on the file sharing means 
> we can lose any instructions that tell the user how to fiddle with 
> either of those systems.
> 
> Just a note though, in that the user won't have to download the DPDK 
> sources twice, only once. Following the guide, the user first sets up 
> the vhost-user ports using libvirt, and once inside the VM he should 
> follow up on running `testpmd` inside the guest [1], where he will be 
> instructed to download the DPDK sources. This makes this piece of the 
> docs a bit more consistent, I think.
> 
> [1] 
> http://docs.openvswitch.org/en/latest/topics/dpdk/vhost-user/#dpdk-in-the-guest

That all sounds fair to me.

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 2/2] dpdk docs: Drop file share in libvirt config.

[Stephen Finucane]

On Wed, 2018-04-11 at 09:54 -0400, Aaron Conole wrote:
> Tiago Lam  writes:
> 
> > When explaining on how to add vhost-user ports to a guest, using
> > libvirt, the following piece of configuration is used:
> > 
> >   
> >   
> >   
> >   
> > 
> > 
> > This is used to facilitate sharing of a DPDK directory between the host
> > and the guest. However, for this to work selinux also needs to be
> > configured (or disabled).  Furthermore, if one is using Ubuntu, libvirtd
> > would need to be added to complain only in AppArmor. Instead, in [1] it
> > is advised to use wget to get the DPDK sources over the internet, which
> > avoids this differentiation. Thus, we drop this piece of configuration
> > here as well and keep the example configuration as simple as possible.
> > 
> > This has been verified on both a Fedora 27 image and a Ubuntu 16.04 LTS
> > image.
> > 
> > [1] 
> > http://docs.openvswitch.org/en/latest/topics/dpdk/vhost-user/#dpdk-in-the-guest
> > 
> > Signed-off-by: Tiago Lam 
> > ---
> > 
> > CC'ed Stephen,
> > 
> > I took the liberty of removing your TODO from here, as I read it to be 
> > related
> > to the (now removed) SELinux instruction below. If you think it should 
> > still be
> > there let me know and I'll gladly send a v2.
> 
> I think it should remain until the selinux issues have been addressed.
> 
> Is there a list somewhere of the AVC denials?  Maybe it makes sense to
> allow them.

If I'm reading this correctly, Tiago is saying these exceptions only
happen because we're sharing an arbitrary directory with the guest to
avoid downloading the DPDK sources twice. Given that there's a valid
workaround (just fetching sources twice), simply removing that section
of the XML removes the need to disable SELinux. If so, dropping the
warning does make sense in my mind.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH 7/8] doc: Split Jumbo Frames guide between two docs

[Stephen Finucane]

While there is some duplication going on here, that's not necessarily a
bad thing. If nothing else, it lets us remove one more overly-detailed
step from the howto.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst | 52 ++--
 Documentation/topics/dpdk/phy.rst| 24 +++
 Documentation/topics/dpdk/vhost-user.rst | 36 ++
 3 files changed, 63 insertions(+), 49 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 1a72e90bf..ba01810f8 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -48,9 +48,9 @@ number of dpdk devices found in the log file::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs=:01:00.1
 
-Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated
-with multiple ports. Using a PCI device like above won't work. Instead, below
-usage is suggested::
+Some NICs (i.e. Mellanox ConnectX-3) have only one PCI address associated with
+multiple ports. Using a PCI device like above won't work. Instead, below usage
+is suggested::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:01"
@@ -85,52 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-Jumbo Frames
-
-
-By default, DPDK ports are configured with standard Ethernet MTU (1500B). To
-enable Jumbo Frames support for a DPDK port, change the Interface's
-``mtu_request`` attribute to a sufficiently large value. For example, to add a
-DPDK Phy port with MTU of 9000::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-  options:dpdk-devargs=:01:00.0 mtu_request=9000
-
-Similarly, to change the MTU of an existing port to 6200::
-
-$ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
-
-Some additional configuration is needed to take advantage of jumbo frames with
-vHost ports:
-
-1. *mergeable buffers* must be enabled for vHost ports, as demonstrated in the
-   QEMU command line snippet below::
-
-   -netdev type=vhost-user,id=mynet1,chardev=char0,vhostforce \
-   -device virtio-net-pci,mac=00:00:00:00:00:01,netdev=mynet1,mrg_rxbuf=on
-
-2. Where virtio devices are bound to the Linux kernel driver in a guest
-   environment (i.e. interfaces are not bound to an in-guest DPDK driver), the
-   MTU of those logical network interfaces must also be increased to a
-   sufficiently large value. This avoids segmentation of Jumbo Frames received
-   in the guest. Note that 'MTU' refers to the length of the IP packet only,
-   and not that of the entire frame.
-
-   To calculate the exact MTU of a standard IPv4 frame, subtract the L2 header
-   and CRC lengths (i.e. 18B) from the max supported frame size.  So, to set
-   the MTU for a 9018B Jumbo Frame::
-
-   $ ip link set eth1 mtu 9000
-
-When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
-increased, such that a full Jumbo Frame of a specific size may be accommodated
-within a single mbuf segment.
-
-Jumbo frame support has been validated against 9728B frames, which is the
-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.
-
 .. _dpdk-ovs-in-guest:
 
 OVS with DPDK Inside VMs
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index 93aff628c..d49269567 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -216,3 +216,27 @@ Flow Control
 
 Flow control is available for DPDK physical ports. For more information, refer
 to :ref:`dpdk-flow-control`.
+
+Jumbo Frames
+
+
+By default, ``dpdk`` ports are configured with standard Ethernet MTU (1500B).
+To enable Jumbo Frames support for such a port, change the interface's
+``mtu_request`` attribute to a sufficiently large value. For example, to add a
+``dpdk`` port with MTU of 9000, run::
+
+$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
+options:dpdk-devargs=:01:00.0 mtu_request=9000
+
+Similarly, to change the MTU of an existing port to 6200::
+
+$ ovs-vsctl set Interface dpdk-p0 mtu_request=6200
+
+When Jumbo Frames are enabled, the size of a DPDK port's mbuf segments are
+increased, such that a full Jumbo Frame of a specific size may be accommodated
+within a single mbuf segment.
+
+Jumbo frame support has been validated against 9728B frames, which is the
+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.
diff --git a/

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

[Stephen Finucane]

This details configuration steps that apply to the entire bridge, rather
than individual ports.

Signed-off-by: Stephen Finucane <step...@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 0..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 ` 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
+-

[ovs-dev] [PATCH 4/8] doc: Move "QoS" guide to its own document

[Stephen Finucane]

Again, this stuff is too detailed for a high-level howto.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst|  70 -
 Documentation/topics/dpdk/index.rst |   1 +
 Documentation/topics/dpdk/phy.rst   |   6 +++
 Documentation/topics/dpdk/qos.rst   | 100 
 4 files changed, 107 insertions(+), 70 deletions(-)
 create mode 100644 Documentation/topics/dpdk/qos.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index 4d993a0eb..608dde814 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,76 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-QoS

-
-Assuming you have a vhost-user port transmitting traffic consisting of packets
-of size 64 bytes, the following command would limit the egress transmission
-rate of the port to ~1,000,000 packets per second::
-
-$ ovs-vsctl set port vhost-user0 qos=@newqos -- \
---id=@newqos create qos type=egress-policer other-config:cir=4600 \
-other-config:cbs=2048`
-
-To examine the QoS configuration of the port, run::
-
-$ ovs-appctl -t ovs-vswitchd qos/show vhost-user0
-
-To clear the QoS configuration from the port and ovsdb, run::
-
-$ ovs-vsctl destroy QoS vhost-user0 -- clear Port vhost-user0 qos
-
-Refer to vswitch.xml for more details on egress-policer.
-
-Rate Limiting
---
-
-Here is an example on Ingress Policing usage. Assuming you have a vhost-user
-port receiving traffic consisting of packets of size 64 bytes, the following
-command would limit the reception rate of the port to ~1,000,000 packets per
-second::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=368000 \
-ingress_policing_burst=1000`
-
-To examine the ingress policer configuration of the port::
-
-$ ovs-vsctl list interface vhost-user0
-
-To clear the ingress policer configuration from the port::
-
-$ ovs-vsctl set interface vhost-user0 ingress_policing_rate=0
-
-Refer to vswitch.xml for more details on ingress-policer.
-
-Flow Control
-
-
-Flow control can be enabled only on DPDK physical ports. To enable flow control
-support at tx side while adding a port, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:tx-flow-ctrl=true
-
-Similarly, to enable rx flow control, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:rx-flow-ctrl=true
-
-To enable flow control auto-negotiation, run::
-
-$ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
-options:dpdk-devargs=:01:00.0 options:flow-ctrl-autoneg=true
-
-To turn ON the tx flow control at run time for an existing port, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=true
-
-The flow control parameters can be turned off by setting ``false`` to the
-respective parameter. To disable the flow control at tx side, run::
-
-$ ovs-vsctl set Interface dpdk-p0 options:tx-flow-ctrl=false
-
 pdump
 -
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index dfde88377..fe4d97b8b 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -32,3 +32,4 @@ The DPDK Datapath
vhost-user
ring
pmd
+   qos
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index 507dac869..93aff628c 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -210,3 +210,9 @@ More information on the different types of virtual DPDK 
PMDs can be found in
 the `DPDK documentation`__.
 
 __ http://dpdk.org/doc/guides/nics/overview.html
+
+Flow Control
+
+
+Flow control is available for DPDK physical ports. For more information, refer
+to :ref:`dpdk-flow-control`.
diff --git a/Documentation/topics/dpdk/qos.rst 
b/Documentation/topics/dpdk/qos.rst
new file mode 100644
index 0..c19e01db7
--- /dev/null
+++ b/Documentation/topics/dpdk/qos.rst
@@ -0,0 +1,100 @@
+..
+  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 (reserv

[ovs-dev] [PATCH 0/8] Split up the DPDK howto

[Stephen Finucane]

The DPDK howto has slowly morphed into a catch all for everything DPDK,
which goes against the original design goal for 'howto' documents [*].
This series attempts to return some sanity to the universe by splitting
this document into many more 'topic' documents. Along the way, we add a
lot of semantic markup, rework some text, and add an overview on
'dpdk'-type ports (the original goal here).

There's a good chance I've made some mistakes in the process and I've
left TODOs for someone to resolve now or at a future date. I welcome
feedback on both of these.

Now to go back to figure how exactly NUMA affinity works for and affects
PMD threads...

[*] 'howto' documents are supposed to be brief, high-level overviews on
a particular group of features, with a focus on the user. They're
not as all-encompassing as a 'tutorial', but not as specific as a
'topic'.

Stephen Finucane (8):
  doc: Add an overview of the 'dpdk' port
  doc: Add "PMD" topic document
  doc: Move additional sections to "physical ports" doc
  doc: Move "QoS" guide to its own document
  doc: Add "bridge" topic document
  doc: Move "pdump" guide to its own document
  doc: Split Jumbo Frames guide between two docs
  doc: Final cleanup of the DPDK howto

 Documentation/conf.py|   2 +-
 Documentation/howto/dpdk.rst | 453 +++
 Documentation/topics/dpdk/bridge.rst | 103 +++
 Documentation/topics/dpdk/index.rst  |  11 +
 Documentation/topics/dpdk/pdump.rst  |  65 +
 Documentation/topics/dpdk/phy.rst| 242 +
 Documentation/topics/dpdk/pmd.rst| 139 ++
 Documentation/topics/dpdk/qos.rst| 100 +++
 Documentation/topics/dpdk/vhost-user.rst |  53 +++-
 9 files changed, 740 insertions(+), 428 deletions(-)
 create mode 100644 Documentation/topics/dpdk/bridge.rst
 create mode 100644 Documentation/topics/dpdk/pdump.rst
 create mode 100644 Documentation/topics/dpdk/phy.rst
 create mode 100644 Documentation/topics/dpdk/pmd.rst
 create mode 100644 Documentation/topics/dpdk/qos.rst

-- 
2.14.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH 2/8] doc: Add "PMD" topic document

[Stephen Finucane]

This continues the breakup of the huge DPDK "howto" into smaller
components. There are a couple of related changes included, such as
using "Rx queue" instead of "rxq" and noting how Tx queues cannot be
configured.

We enable the TODO directive, so we can actually start calling out some
TODOs.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/conf.py|   2 +-
 Documentation/howto/dpdk.rst |  86 ---
 Documentation/topics/dpdk/index.rst  |   1 +
 Documentation/topics/dpdk/phy.rst|  10 +++
 Documentation/topics/dpdk/pmd.rst| 139 +++
 Documentation/topics/dpdk/vhost-user.rst |  17 ++--
 6 files changed, 159 insertions(+), 96 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pmd.rst

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6ab144c5d..babda21de 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -32,7 +32,7 @@ needs_sphinx = '1.1'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index d717d2ebe..c2324118d 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -81,92 +81,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-PMD Thread Statistics
--
-
-To show current stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-show
-
-To clear previous stats::
-
-$ ovs-appctl dpif-netdev/pmd-stats-clear
-
-Port/RXQ Assigment to PMD Threads
--
-
-To show port/rxq assignment::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-To change default rxq assignment to pmd threads, rxqs may be manually pinned to
-desired cores using::
-
-$ ovs-vsctl set Interface  \
-other_config:pmd-rxq-affinity=
-
-where:
-
--  is a CSV list of ``:`` values
-
-For example::
-
-$ ovs-vsctl set interface dpdk-p0 options:n_rxq=4 \
-other_config:pmd-rxq-affinity="0:3,1:7,3:8"
-
-This will ensure:
-
-- Queue #0 pinned to core 3
-- Queue #1 pinned to core 7
-- Queue #2 not pinned
-- Queue #3 pinned to core 8
-
-After that PMD threads on cores where RX queues was pinned will become
-``isolated``. This means that this thread will poll only pinned RX queues.
-
-.. warning::
-  If there are no ``non-isolated`` PMD threads, ``non-pinned`` RX queues will
-  not be polled. Also, if provided ``core_id`` is not available (ex. this
-  ``core_id`` not in ``pmd-cpu-mask``), RX queue will not be polled by any PMD
-  thread.
-
-If pmd-rxq-affinity is not set for rxqs, they will be assigned to pmds (cores)
-automatically. The processing cycles that have been stored for each rxq
-will be used where known to assign rxqs to pmd based on a round robin of the
-sorted rxqs.
-
-For example, in the case where here there are 5 rxqs and 3 cores (e.g. 3,7,8)
-available, and the measured usage of core cycles per rxq over the last
-interval is seen to be:
-
-- Queue #0: 30%
-- Queue #1: 80%
-- Queue #3: 60%
-- Queue #4: 70%
-- Queue #5: 10%
-
-The rxqs will be assigned to cores 3,7,8 in the following order:
-
-Core 3: Q1 (80%) |
-Core 7: Q4 (70%) | Q5 (10%)
-core 8: Q3 (60%) | Q0 (30%)
-
-To see the current measured usage history of pmd core cycles for each rxq::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-show
-
-.. note::
-
-  A history of one minute is recorded and shown for each rxq to allow for
-  traffic pattern spikes. An rxq's pmd core cycles usage changes due to traffic
-  pattern or reconfig changes will take one minute before they are fully
-  reflected in the stats.
-
-Rxq to pmds assignment takes place whenever there are configuration changes
-or can be triggered by using::
-
-$ ovs-appctl dpif-netdev/pmd-rxq-rebalance
-
 QoS
 ---
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 5f836a6e9..dfde88377 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -31,3 +31,4 @@ The DPDK Datapath
phy
vhost-user
ring
+   pmd
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
index 1c18e4e3d..222fa3e9f 100644
--- a/Documentation/topics/dpdk/phy.rst
+++ b/Documentation/topics/dpdk/phy.rst
@@ -109,3 +109,13 @@ tool::
 For more information, refer to the `DPDK documentation `__.
 
 .. _dpdk-drivers: http://dpdk.org/doc/guides/linux_gsg/linux_drivers.html
+
+Multiqueue
+--
+
+Poll Mode Driver (PMD) threads are the threads that do the heavy lifting for
+the DPDK datapath. Correct configuration of PMD threads and the Rx queues they
+uti

[ovs-dev] [PATCH 1/8] doc: Add an overview of the 'dpdk' port

[Stephen Finucane]

These ports are used to allow ingress/egress from the host and are
therefore _reasonably_ important. However, there is no clear overview of
what these ports actually are or why things are done the way they are.
Start closing this gap by providing a standalone example of using these
ports along with a little more detailed overview of the binding process.

There is additional cleanup to be done for the DPDK howto, but that will
be done separately.

Signed-off-by: Stephen Finucane <step...@that.guru>
Cc: Ciara Loftus <ciara.lof...@intel.com>
Cc: Kevin Traynor <ktray...@redhat.com>
---
 Documentation/topics/dpdk/index.rst |   1 +
 Documentation/topics/dpdk/phy.rst   | 111 
 2 files changed, 112 insertions(+)
 create mode 100644 Documentation/topics/dpdk/phy.rst

diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index da148b323..5f836a6e9 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -28,5 +28,6 @@ The DPDK Datapath
 .. toctree::
:maxdepth: 2
 
+   phy
vhost-user
ring
diff --git a/Documentation/topics/dpdk/phy.rst 
b/Documentation/topics/dpdk/phy.rst
new file mode 100644
index 0..1c18e4e3d
--- /dev/null
+++ b/Documentation/topics/dpdk/phy.rst
@@ -0,0 +1,111 @@
+..
+  Copyright 2018, Red Hat, Inc.
+
+  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 Physical Ports
+===
+
+The DPDK datapath provides a way to attach DPDK-backed physical interfaces to
+allow high-performance ingress/egress from the host.
+
+.. versionchanged:: 2.7.0
+
+   Before Open vSwitch 2.7.0, it was necessary to prefix port names with a
+   ``dpdk`` prefix. Starting with 2.7.0, this is no longer necessary.
+
+Quick Example
+-
+
+This example demonstrates how to bind two ``dpdk`` ports, bound to physical
+interfaces identified by hardware IDs ``:01:00.0`` and ``:01:00.1``, to
+an existing bridge called ``br0``::
+
+$ ovs-vsctl add-port br0 dpdk-p0 \
+   -- set Interface dpdk-p0 type=dpdk options:dpdk-devargs=:01:00.0
+$ ovs-vsctl add-port br0 dpdk-p1 \
+   -- set Interface dpdk-p1 type=dpdk options:dpdk-devargs=:01:00.1
+
+For the above example to work, the two physical interfaces must be bound to
+the DPDK poll-mode drivers in userspace rather than the traditional kernel
+drivers. See the `binding NIC drivers ` section for details.
+
+.. _dpdk-binding-nics:
+
+Binding NIC Drivers
+---
+
+DPDK operates entirely in userspace and, as a result, requires use of its own
+poll-mode drivers in user space for physical interfaces and a passthrough-style
+driver for the devices in kernel space.
+
+There are two different tools for binding drivers: :command:`driverctl` which
+is a generic tool for persistently configuring alternative device drivers, and
+:command:`dpdk-devbind` which is a DPDK-specific tool and whose changes do not
+persist across reboots. In addition, there are two options available for this
+kernel space driver - VFIO (Virtual Function I/O) and UIO (Userspace I/O) -
+along with a number of drivers for each option. We will demonstrate examples of
+both tools and will use the ``vfio-pci`` driver, which is the more secure,
+robust driver of those available. More information can be found in the `DPDK
+documentation `__.
+
+To list devices using :command:`driverctl`, run::
+
+$ driverctl -v list-devices | grep -i net
+:07:00.0 igb (I350 Gigabit Network Connection (Ethernet Server Adapter 
I350-T2))
+:07:00.1 igb (I350 Gigabit Network Connection (Ethernet Server Adapter 
I350-T2))
+
+You can then bind one or more of these devices using the same tool::
+
+$ driverctl set-override :07:00.0 vfio-pci
+
+Alternatively, to list devices using :command:`dpdk-devbind`, run::
+
+$ dpdk-devbind --status
+Network devices using DPDK-compatible driver
+
+
+
+Network devices using kernel driver
+===
+:07:00.0

[ovs-dev] [PATCH 6/8] doc: Move "pdump" guide to its own document

[Stephen Finucane]

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst| 39 --
 Documentation/topics/dpdk/index.rst |  7 
 Documentation/topics/dpdk/pdump.rst | 65 +
 3 files changed, 72 insertions(+), 39 deletions(-)
 create mode 100644 Documentation/topics/dpdk/pdump.rst

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index c01bf7a39..1a72e90bf 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -85,45 +85,6 @@ To stop ovs-vswitchd & delete bridge, run::
 $ ovs-appctl -t ovsdb-server exit
 $ ovs-vsctl del-br br0
 
-pdump
--
-
-pdump allows you to listen on DPDK ports and view the traffic that is passing
-on them. To use this utility, one must have libpcap installed on the system.
-Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
-``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
-
-.. warning::
-  A performance decrease is expected when using a monitoring application like
-  the DPDK pdump app.
-
-To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
-directory in DPDK, ``make`` the application and run like so::
-
-$ sudo ./build/app/dpdk-pdump -- \
---pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
---server-socket-path=/usr/local/var/run/openvswitch
-
-The above command captures traffic received on queue 0 of port 0 and stores it
-in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
-pcap locations are of course also available to use. For example, to capture all
-packets that traverse port 0 in a single pcap file::
-
-$ sudo ./build/app/dpdk-pdump -- \
---pdump 'port=0,queue=*,rx-dev=/tmp/pkts.pcap,tx-dev=/tmp/pkts.pcap' \
---server-socket-path=/usr/local/var/run/openvswitch
-
-``server-socket-path`` must be set to the value of ``ovs_rundir()`` which
-typically resolves to ``/usr/local/var/run/openvswitch``.
-
-Many tools are available to view the contents of the pcap file. Once example is
-tcpdump. Issue the following command to view the contents of ``pkts.pcap``::
-
-$ tcpdump -r pkts.pcap
-
-More information on the pdump app and its usage can be found in the `DPDK docs
-<http://dpdk.org/doc/guides/tools/pdump.html>`__.
-
 Jumbo Frames
 
 
diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 52cacaef6..c9b231f06 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -27,10 +27,17 @@ The DPDK Datapath
 
 .. toctree::
:maxdepth: 2
+   :caption: Bridges and Ports
 
bridge
phy
vhost-user
ring
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced Configuration
+
pmd
qos
+   pdump
diff --git a/Documentation/topics/dpdk/pdump.rst 
b/Documentation/topics/dpdk/pdump.rst
new file mode 100644
index 0..f1a408989
--- /dev/null
+++ b/Documentation/topics/dpdk/pdump.rst
@@ -0,0 +1,65 @@
+..
+  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.
+
+=
+pdump
+=
+
+pdump allows you to listen on DPDK ports and view the traffic that is passing
+on them. To use this utility, one must have libpcap installed on the system.
+Furthermore, DPDK must be built with ``CONFIG_RTE_LIBRTE_PDUMP=y`` and
+``CONFIG_RTE_LIBRTE_PMD_PCAP=y``.
+
+.. warning::
+
+   A performance decrease is expected when using a monitoring application like
+   the DPDK pdump app.
+
+To use pdump, simply launch OVS as usual, then navigate to the ``app/pdump``
+directory in DPDK, ``make`` the application and run like so::
+
+$ sudo ./build/app/dpdk-pdump -- \
+--pdump port=0,queue=0,rx-dev=/tmp/pkts.pcap \
+--server-socket-path=/usr/local/var/run/openvswitch
+
+The above command captures traffic received on queue 0 of port 0 and stores it
+in ``/tmp/pkts.pcap``. Other combinations of port numbers, queues numbers and
+pcap locations are of course also available to use. For example, to capture all
+packets that traverse port 0 in a single pcap file::
+
+$ sudo ./build/app/dpdk-pdump -- \
+   

[ovs-dev] [PATCH 3/8] doc: Move additional sections to "physical ports" doc

[Stephen Finucane]

The "vdev", "hotplugging", and "Rx checksum offload" sections only apply
to 'dpdk' ports and are too detailed to include in a high-level howto.
Move them, reworking some aspects of this in the process.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst  | 93 +++
 Documentation/topics/dpdk/phy.rst | 91 ++
 2 files changed, 97 insertions(+), 87 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index c2324118d..4d993a0eb 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -57,8 +57,12 @@ usage is suggested::
 $ ovs-vsctl add-port br0 dpdk-p1 -- set Interface dpdk-p1 type=dpdk \
 options:dpdk-devargs="class=eth,mac=00:11:22:33:44:55:02"
 
-Note: such syntax won't support hotplug. The hotplug is supposed to work with
-future DPDK release, v18.05.
+.. important::
+
+Hotplugging physical interfaces is not supported using the above syntax.
+This is expected to change with the release of DPDK v18.05. For information
+on hotplugging physical interfaces, you should instead refer to
+:ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
 DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
@@ -236,16 +240,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.
 
-Rx Checksum Offload

-
-By default, DPDK physical ports are enabled with Rx checksum offload.
-
-Rx checksum offload can offer performance improvement only for tunneling
-traffic in OVS-DPDK because the checksum validation of tunnel packets is
-offloaded to the NIC. Also enabling Rx checksum may slightly reduce the
-performance of non-tunnel traffic, specifically for smaller size packet.
-
 .. _extended-statistics:
 
 Extended & Custom Statistics
@@ -278,81 +272,6 @@ 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.
 
-.. _port-hotplug:
-
-Port Hotplug
-
-
-OVS supports port hotplugging, allowing the use of ports that were not bound
-to DPDK when vswitchd was started.
-In order to attach a port, it has to be bound to DPDK using the
-``dpdk_nic_bind.py`` script::
-
-$ $DPDK_DIR/tools/dpdk_nic_bind.py --bind=igb_uio :01:00.0
-
-Then it can be attached to OVS::
-
-$ ovs-vsctl add-port br0 dpdkx -- set Interface dpdkx type=dpdk \
-options:dpdk-devargs=:01:00.0
-
-Detaching will be performed while processing del-port command::
-
-$ ovs-vsctl del-port dpdkx
-
-Sometimes, the del-port command may not detach the device.
-Detaching can be confirmed by the appearance of an INFO log.
-For example::
-
-INFO|Device ':04:00.1' has been detached
-
-If the log is not seen, then the port can be detached using::
-
-$ ovs-appctl netdev-dpdk/detach :01:00.0
-
-Detaching can be confirmed by console output::
-
-Device ':04:00.1' has been detached
-
-.. warning::
-Detaching should not be done if a device is known to be non-detachable, as
-this may cause the device to behave improperly when added back with
-add-port. The Chelsio Terminator adapters which use the cxgbe driver seem
-to be an example of this behavior; check the driver documentation if this
-is suspected.
-
-This feature does not work with some NICs.
-For more information please refer to the `DPDK Port Hotplug Framework
-<http://dpdk.org/doc/guides/prog_guide/port_hotplug_framework.html#hotplug>`__.
-
-.. _vdev-support:
-
-Vdev Support
-
-
-DPDK provides drivers for both physical and virtual devices. Physical DPDK
-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'.
-
-Typically, the format expected is 'eth_' where 'x' is a
-unique identifier of your choice for the given port.
-
-For example to add a dpdk port that uses the 'null' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 null0 -- set Interface null0 type=dpdk \
-   options:dpdk-devargs=eth_null0
-
-Similarly, to add a dpdk port that uses the 'af_packet' DPDK PMD driver::
-
-   $ ovs-vsctl add-port br0 myeth0 -- set Interface myeth0 type=dpdk \
-   options:dpdk-devargs=eth_af_packet0,iface=eth0
-
-More information on the different types of virtual DPDK PMDs can be found in
-the `DPDK documentation
-<http://dpdk.org/doc/guides/nics/overview.html>`__.
-
-Note: Not all DPDK virtual PMD drivers have been tested and verified to work.
-
 EMC Insertion Probability

[ovs-dev] [PATCH 8/8] doc: Final cleanup of the DPDK howto

[Stephen Finucane]

This concludes the cleanup by fixing some grammar nits and adding some
additional cross-references.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/howto/dpdk.rst | 61 ++--
 1 file changed, 30 insertions(+), 31 deletions(-)

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index ba01810f8..89e068748 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -25,23 +25,26 @@
 Using Open vSwitch with DPDK
 
 
-This document describes how to use Open vSwitch with DPDK datapath.
+This document describes how to use Open vSwitch with DPDK datapath. For more
+detailed information, refer to the various :doc:`DPDK topic guides
+`.
 
 .. important::
 
Using the DPDK datapath requires building OVS with DPDK support. Refer to
:doc:`/intro/install/dpdk` for more information.
 
-Ports and Bridges
--
+Overview
+
 
-ovs-vsctl can be used to set up bridges and other Open vSwitch features.
-Bridges should be created with a ``datapath_type=netdev``::
+:program:`ovs-vsctl` can be used to set up bridges and other Open vSwitch
+features.  Bridges should be created with a ``datapath_type=netdev``::
 
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
 
-ovs-vsctl can also be used to add DPDK devices. ovs-vswitchd should print the
-number of dpdk devices found in the log file::
+:program:`ovs-vsctl` can also be used to add DPDK devices.
+:program:`ovs-vswitchd` should print the number of ``dpdk`` devices found in
+the log file::
 
 $ ovs-vsctl add-port br0 dpdk-p0 -- set Interface dpdk-p0 type=dpdk \
 options:dpdk-devargs=:01:00.0
@@ -59,14 +62,13 @@ is suggested::
 
 .. important::
 
-Hotplugging physical interfaces is not supported using the above syntax.
-This is expected to change with the release of DPDK v18.05. For information
-on hotplugging physical interfaces, you should instead refer to
-:ref:`port-hotplug`.
+Hotplugging physical interfaces is not supported for these devices.  This
+is expected to change with the release of DPDK v18.05. For information on
+hotplugging physical interfaces, refer to :ref:`port-hotplug`.
 
 After the DPDK ports get added to switch, a polling thread continuously polls
-DPDK devices and consumes 100% of the core, as can be checked from ``top`` and
-``ps`` commands::
+DPDK devices and consumes 100% of the core, as can be checked from
+:command:`top` and :command:`ps` commands::
 
 $ top -H
 $ ps -eLo pid,psr,comm | grep pmd
@@ -79,7 +81,7 @@ set. For example::
 -- set Interface p0 type=dpdk options:dpdk-devargs=:01:00.0 \
 -- set Interface p1 type=dpdk options:dpdk-devargs=:01:00.1
 
-To stop ovs-vswitchd & delete bridge, run::
+To stop :program:`ovs-vswitchd` and delete the bridge, run::
 
 $ ovs-appctl -t ovs-vswitchd exit
 $ ovs-appctl -t ovsdb-server exit
@@ -126,7 +128,7 @@ Add a userspace bridge and two ``dpdk`` (PHY) ports::
 $ ovs-vsctl add-port br0 phy1 -- set Interface phy1 type=dpdk
   options:dpdk-devargs=:01:00.1 ofport_request=2
 
-Add test flows to forward packets betwen DPDK port 0 and port 1::
+Add test flows to forward packets between DPDK port 0 and port 1::
 
 # Clear current flows
 $ ovs-ofctl del-flows br0
@@ -137,13 +139,16 @@ Add test flows to forward packets betwen DPDK port 0 and 
port 1::
 
 Transmit traffic into either port. You should see it returned via the other.
 
+More information on the ``dpdk`` ports can be found in :doc:`/topics/dpdk/phy`.
+
 .. _dpdk-vhost-loopback:
 
 PHY-VM-PHY (vHost Loopback)
 ---
 
 Add a userspace bridge, two ``dpdk`` (PHY) ports, and two ``dpdkvhostuser``
-ports::
+ports. It is assumed that the physical ports are already bound to DPDK, as
+described in :ref:`dpdk-binding-nics`::
 
 # Add userspace bridge
 $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
@@ -161,7 +166,7 @@ ports::
 $ ovs-vsctl add-port br0 dpdkvhostuser1 \
 -- set Interface dpdkvhostuser1 type=dpdkvhostuser ofport_request=4
 
-Add test flows to forward packets betwen DPDK devices and VM ports::
+Add test flows to forward packets between DPDK devices and VM ports::
 
 # Clear current flows
 $ ovs-ofctl del-flows br0
@@ -221,19 +226,7 @@ described in :ref:`dpdk-testpmd`. Once compiled, run the 
application::
 $ set fwd mac retry
 $ start
 
-When you finish testing, bind the vNICs back to kernel::
-
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:03.0
-$ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci :00:04.0
-
-.. note::
-
-  Valid PCI IDs must be passed in above example. The PCI IDs can be retrieved
-  like so::
-
-  $ $DPDK_DIR/usertools/dpdk-devbind.py --status
-
-More information on the dpdkvhostuser ports can be found in
+More information on the ``dpd

Re: [ovs-dev] [PATCH] MAINTAINERS: Fix links to other docs.

[Stephen Finucane]

On Fri, 2017-12-29 at 18:01 +0300, Ilya Maximets wrote:
> Hard links to .rst files are broken in compiled documentation.
> Fix that by changing to proper :doc: reference.
> 
> Signed-off-by: Ilya Maximets 

I hadn't done this because MAINTAINERS is a top-level document and
therefore likely to be viewed on GitHub. The 'doc' role won't render
here and GitHub uses the docutils-based 'rst2html' tool to render text
rather than Sphinx, and the 'doc' role is a Sphinx one.

As such, I don't think you should do this. What I would do instead is
move everything but the list of maintainers to whatever document is
including this file. You can keep a small note in MAINTAINERS (possibly
a reference to the other file) but this should be ignored in the other
file by way of 'start-line' option for the 'include' directive.

Stephen

> ---
>  MAINTAINERS.rst | 12 ++--
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst
> index fec215a..587a578 100644
> --- a/MAINTAINERS.rst
> +++ b/MAINTAINERS.rst
> @@ -28,11 +28,11 @@ Committers
>  Open vSwitch committers are the people who have been granted access
> to push
>  changes to to the Open vSwitch git repository.
>  
> -The responsibilities of an Open vSwitch committer are documented
> -`here `__.
> +The responsibilities of an Open vSwitch committer are documented in
> +:doc:`/internals/committer-responsibilities`.
>  
> -The process for adding or removing committers is documented
> -`here `__.
> +The process for adding or removing committers is documented in
> +:doc:`/internals/committer-grant-revocation`.
>  
>  This is the current list of active Open vSwitch committers:
>  
> @@ -77,8 +77,8 @@ This is the current list of active Open vSwitch
> committers:
>   - yamam...@midokura.com
>  
>  The project also maintains a list of Emeritus Committers (or
> Maintainers).
> -More information about Emeritus Committers can be found
> -`here `__.
> +More information about Emeritus Committers can be found in
> +:doc:`/internals/committer-emeritus-status`.
>  
>  .. list-table:: OVS Emeritus Maintainers
> :header-rows: 1

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Fix table view for VM config in dpdk howto.

[Stephen Finucane]

On Tue, 2017-12-12 at 16:19 +0300, Ilya Maximets wrote:
> In current version table contains only one row with all the values
> together. This is not readable. 'Simple table' format should work for
> this case.
> 
> CC: Stephen Finucane <step...@that.guru>
> Fixes: 167703d664fc ("doc: Convert INSTALL.DPDK to rST")
> Signed-off-by: Ilya Maximets <i.maxim...@samsung.com>

Some suggestion for other, not-totally-related improvements below, but
this looks good.

Acked-by: Stephen Finucane <step...@that.guru>

> ---
>  Documentation/howto/dpdk.rst | 22 --
>  1 file changed, 12 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/howto/dpdk.rst
> b/Documentation/howto/dpdk.rst
> index d123819..763b237 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -531,16 +531,18 @@ Add test flows to forward packets betwen DPDK
> devices and VM ports::
>  
>  Create a VM using the following configuration:
>  
> -+--++-+
> -| configuration| values | comments|
> -+--++-+
> -| qemu version | 2.2.0  | n/a |
> -| qemu thread affinity | core 5 | taskset 0x20|
> -| memory   | 4GB| n/a |
> -| cores| 2  | n/a |
> -| Qcow2 image  | CentOS7| n/a |
> -| mrg_rxbuf| off| n/a |
> -+--++-+
> +.. table::
> +
> +=  
> +configuration  valuescomments
> +=  
> +qemu version  2.2.0n/a
> +qemu thread affinity  core 5   taskset 0x20
> +memory4GB  n/a
> +cores 2n/a

We might want to capitalize these while we're at it.

  QEMU version
  Memory
  ...

> +Qcow2 image   CentOS7  n/a
> +mrg_rxbuf off  n/a
> +=  
>  
>  You can do this directly with QEMU via the ``qemu-system-x86_64``
> application::
>  

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v3 5/5] doc: ConnTracker cfg parameters.

[Stephen Finucane]

On Fri, 2017-10-13 at 09:25 +0100, antonio.fische...@intel.com wrote:
> Update documentation with the new commands to Read/Write
> ConnTracker configuration parameters.
> 
> CC: Kevin Traynor <ktray...@redhat.com>
> CC: Darrell Ball <dlu...@gmail.com>
> Signed-off-by: Antonio Fischetti <antonio.fische...@intel.com>

One nit below, but otherwise LGTM.

Acked-by: Stephen Finucane <step...@that.guru>

> ---
>  Documentation/intro/install/dpdk.rst | 25 +
>  lib/dpctl.man| 10 ++
>  2 files changed, 35 insertions(+)
> 
> diff --git a/Documentation/intro/install/dpdk.rst
> b/Documentation/intro/install/dpdk.rst
> index bb69ae5..a1f259c 100644
> --- a/Documentation/intro/install/dpdk.rst
> +++ b/Documentation/intro/install/dpdk.rst
> @@ -568,6 +568,31 @@ not needed i.e. jumbo frames are not needed, it can be
> forced off by adding
>  chains of descriptors it will make more individual virtio descriptors
> available
>  for rx to the guest using dpdkvhost ports and this can improve performance.
>  
> +Connection Tracker
> +~~
> +
> +When the Connection Tracker is enabled the overall performance can be deeply
> +affected, even with simple firewall rules and with stateless protocols like
> +UDP.  In order to find a better tuning, commands like
> +
> +::
> +
> +$ ovs-appctl dpctl/ct-get-glbl-cfg 
> +$ ovs-appctl dpctl/ct-set-glbl-cfg =
> +
> +allow respectively to read the current value, or set a new value to a
> +configuration parameter.
> +For example, to reduce the impact of the Connection Tracker load on the
> +system performance, the maximum number of tracked connections can be
> +reduced.
> +
> +The available configuration parameters are:
> +
> +- maxconn: Maximum number of connections managed by the Connection Tracker
> +  module. It's both readable and writeable.
> +- totconn: Total number of connections currently managed by the Connection
> +  Tracker module. Readable only.

nit: This section would probably read better as a definition list

  ``maxconn``
Maximum number of connections...

  ``totconn``
Total number of connections...

> +
>  Limitations
>  
>  
> diff --git a/lib/dpctl.man b/lib/dpctl.man
> index 675fe5a..64ad105 100644
> --- a/lib/dpctl.man
> +++ b/lib/dpctl.man
> @@ -235,3 +235,13 @@ For each ConnTracker bucket, displays the number of
> connections used
>  by \fIdp\fR.
>  If \fBgt=\fIThreshold\fR is specified, bucket numbers are displayed when
>  the number of connections in a bucket is greater than \fIThreshold\fR.
> +.
> +.TP
> +\*(DX\fBct\-get\-glbl\-cfg\fR [\fIdp\fR] \fBparam\fR
> +Read the current value of the specified ConnTracker parameter used
> +by \fIdp\fR.
> +.
> +.TP
> +\*(DX\fBct\-set\-glbl\-cfg\fR [\fIdp\fR] \fBparam=\fI..\fR
> +Set a value to the specified ConnTracker parameter used
> +by \fIdp\fR.

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] Documentation: Add Faucet tutorial.

[Stephen Finucane]

On Wed, 2017-10-18 at 14:05 -0700, Ben Pfaff wrote:
> This is for a talk at the Faucet conference on Oct. 19:
> http://conference.faucet.nz/schedule/
> 
> Signed-off-by: Ben Pfaff 

Spotted a few small issues while skimming this. Did this build correctly and
did the output HTML look OK?

Stephen

> ---
>  Documentation/automake.mk  |1 +
>  Documentation/tutorials/faucet.rst | 1462
> 
>  Documentation/tutorials/index.rst  |1 +
>  3 files changed, 1464 insertions(+)
>  create mode 100644 Documentation/tutorials/faucet.rst
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 6f38912f264b..da482b419887 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -23,6 +23,7 @@ DOC_SOURCE = \
>   Documentation/intro/install/windows.rst \
>   Documentation/intro/install/xenserver.rst \
>   Documentation/tutorials/index.rst \
> + Documentation/tutorials/faucet.rst \
>   Documentation/tutorials/ovs-advanced.rst \
>   Documentation/tutorials/ovn-openstack.rst \
>   Documentation/tutorials/ovn-sandbox.rst \
> diff --git a/Documentation/tutorials/faucet.rst
> b/Documentation/tutorials/faucet.rst
> new file mode 100644
> index ..67c663649f72
> --- /dev/null
> +++ b/Documentation/tutorials/faucet.rst
> @@ -0,0 +1,1462 @@
> +..
> +  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.
> +
> +===
> +OVS Faucet Tutorial
> +===
> +
> +This tutorial demonstrates how Open vSwitch works with a controller, using
> the
> +Faucet controller as a simple way to get started.  It was tested with the
> +"master" branch of Open vSwitch and version 1.6.7 of Faucet in October 2017.
> +It does not use advanced or recently added features in OVS or Faucet, so
> other
> +versions of both pieces of software are likely to work equally well.
> +
> +The goal of the tutorial is to demonstrate Open vSwitch and Faucet in an
> +end-to-end way, that is, to show how it works from the Faucet controller
> +configuration at the top, through the OpenFlow flow table, to the datapath
> +processing.  Along the way, in addition to helping to understand the
> +architecture at each level, we discuss performance and troubleshooting
> issues.
> +We hope that this demonstration makes it easier for users and potential
> users
> +to understand how Open vSwitch works and how to debug and troubleshoot it.
> +
> +We provide enough details in the tutorial that you should be able to fully
> +follow along by following the instructions.
> +
> +Setting Up OVS
> +--
> +
> +This section explains to how to set up Open vSwitch for the purpose of using
> it
> +with Faucet for the tutorial.
> +
> +You might already have Open vSwitch installed on one or more computers or
> VMs,
> +perhaps set up to control a set of VMs or a physical network.  This is
> +admirable, but we will be using Open vSwitch in a different way to set up a
> +simulation environment called the OVS "sandbox".  The sandbox does not use
> +virtual machines or containers, which makes it more limited than setups
> based
> +on those kinds of setups, but on the other hand it is also (in this writer's
> +opinion) easier to set up.
> +
> +There are two ways to start a sandbox: one that uses the Open vSwitch that
> is
> +already installed on a system, and another that uses a copy of Open vSwitch
> +that has been built but not yet installed.  The latter is more often used
> and
> +thus better tested, but both should work.  The instructions below explain
> both
> +approaches:
> +
> +1. Get a copy of the Open vSwitch source repository using Git, then ``cd``
> into
> +   the new directory::
> +
> + $ git clone https://github.com/openvswitch/ovs.git
> + $ cd ovs
> +
> +   The default checkout is the master branch.  You can check out a tag
> +   (such as v2.8.0) or a branch (such as origin/branch-2.8), if you
> +   prefer.
> +
> +2. If you do not already have an installed copy of Open vSwitch on your
> system,
> +   or if you do not want to use it for the 

Re: [ovs-dev] [RFC PATCH v1] docs: Add release feature roadmap.

[Stephen Finucane]

On Wed, 2017-09-13 at 22:04 +0100, Ian Stokes wrote:
> Add a document to outline the roadmap of features contributors are targeting
> for upcoming OVS releases.
> 
> Signed-off-by: Ian Stokes 
> ---
>  Documentation/automake.mk |1 +
>  Documentation/faq/index.rst   |1 +
>  Documentation/faq/release_feature_roadmap.rst |  350
> +
>  3 files changed, 352 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/faq/release_feature_roadmap.rst
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 24fe63d..3e16873 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -75,6 +75,7 @@ DOC_SOURCE = \
>   Documentation/faq/terminology.rst \
>   Documentation/faq/vlan.rst \
>   Documentation/faq/vxlan.rst \
> +Documentation/faq/release_feature_roadmap.rst \

Looks like you've some extra whitespace here than shouldn't be here.

>   Documentation/internals/index.rst \
>   Documentation/internals/authors.rst \
>   Documentation/internals/bugs.rst \
> diff --git a/Documentation/faq/index.rst b/Documentation/faq/index.rst
> index 334b828..e865f57 100644
> --- a/Documentation/faq/index.rst
> +++ b/Documentation/faq/index.rst
> @@ -41,3 +41,4 @@ Open vSwitch FAQ
> terminology
> vlan
> vxlan
> +   release_feature_roadmap
> diff --git a/Documentation/faq/release_feature_roadmap.rst
> b/Documentation/faq/release_feature_roadmap.rst
> new file mode 100644
> index 000..40388f6
> --- /dev/null
> +++ b/Documentation/faq/release_feature_roadmap.rst
> @@ -0,0 +1,350 @@
> +..
> +Licensed under the Apache License, Version 2.0 (the "License"); you
> may

Ditto (before "Licensed")

> +  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.
> +
> +===
> +Release Feature Roadmap
> +===
> +
> +This document provides a feature roadmap for upcoming OVS releases.
> +
> +A few issues to note:
> +
> +* The aim of the roadmap is to provide visibility across the community
> +  regarding which features contributors are targeting in the upcoming
> release.
> +* A feature listed on the roadmap is not guaranteed to be upstreamed in the
> +  targeted release and a release will not be delayed in order to accommodate
> +  features listed in the roadmap.
> +* It is not mandatory to include planned features in the roadmap although it
> +  is encouraged. Features not listed but that are submitted will still be
> +  reviewed as per usual for a release.
> +
> +--
> +Adding Features to the Roadmap
> +--

nit: overlines aren't necessary, and we don't use them for anything deeper than
the top-level header. Could you drop it here?

> +
> +When adding a feature to the roadmap a user should be aware of the required
> +fields and expected values as detailed below:
> +
> +* **Contributor**: The name of the person/company contributing the feature.
> +* **Feature Name**: The name of the feature being contributed.
> +* **Description**: A brief description of the feature being contributed.
> +
> +---
> +OVS 2.9 feature Roadmap
> +---
> +
> ++--+
> +| **OVS 2.9 Feature Roadmap**  +
> ++--+
> +|  |
> ++--+
> +| **Contributor**: *Intel* |
> ++--+
> +| **Feature Name**: Keepalive  |
> ++--+
> +| **Description**: Keepalive feature is aimed at achieving Fastpath Service|
> +| Assurance  in OVS-DPDK deployments. It adds support for monitoring the   |
> +| packet processing threads by dispatching 

Re: [ovs-dev] [PATCH v2] docs: Add references to git-pw

[Stephen Finucane]

On Thu, 2017-09-28 at 08:44 -0700, Ben Pfaff wrote:
> On Thu, Sep 28, 2017 at 04:36:04PM +0100, Stephen Finucane wrote:
> > On Mon, 2017-09-04 at 14:09 +0100, Stephen Finucane wrote:
> > > Now that Patchwork 2.0 is out, folks can start to take advantage of some
> > > of the new features that it offers. Chief among these is series support,
> > > which is only exposed via the web UI and new REST API and which, in
> > > turn, necessitates using git-pw rather than pwclient. As such, this tool
> > > is slightly documented.
> > > 
> > > Signed-off-by: Stephen Finucane <step...@that.guru>
> > 
> > Any chance of getting this merged? Seems trivial enough, IMO.
> 
> I've been off writing code lately.

That makes one of us :'(

> Applied, thanks!

Thanks, Ben!

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v2] docs: Add references to git-pw

[Stephen Finucane]

On Mon, 2017-09-04 at 14:09 +0100, Stephen Finucane wrote:
> Now that Patchwork 2.0 is out, folks can start to take advantage of some
> of the new features that it offers. Chief among these is series support,
> which is only exposed via the web UI and new REST API and which, in
> turn, necessitates using git-pw rather than pwclient. As such, this tool
> is slightly documented.
> 
> Signed-off-by: Stephen Finucane <step...@that.guru>

Any chance of getting this merged? Seems trivial enough, IMO.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] pwclient XML errors and form feeds

[Stephen Finucane]

On Fri, 2017-08-18 at 21:27 +, Mark Michelson wrote:
> On Fri, Aug 18, 2017 at 4:09 PM Ben Pfaff  wrote:
> 
> > On Mon, Aug 14, 2017 at 09:54:10PM +, Mark Michelson wrote:
> > > I debugged the problem further and I now have figured out that the
> > 
> > problem
> > > has to do with a form feed character being present in the patch. The
> > > Patchwork server places the patch text inside an XML 1.0 document;
> > 
> > however,
> > > form-feeds are illegal in XML 1.0 [2]. This makes the use of form feeds
> > 
> > and
> > > the use of pwclient incompatible.
> > 
> > Why not use XML 1.1?  It allows form feeds.
> > 
> 
> I don't know how viable that is. The XML version is hard-coded in Python's
> xmlrpclib code. As an experiment, I patched my local copy of xmlrpclib.py
> to use XML 1.1, but the server still responded with an XML 1.0 document, so
> the error still occurred. This would mean the server would need to be
> patched to send an XML 1.1 document, and you'd have to hope that the XML
> parser on the client side actually pays attention to the XML version.
> 
> For now, I'll just go with the crowd and use curl + web browser.
> Mark

In case you didn't see [1], patchwork.ozlabs.org is now bumped to 2.0 and the
'git-pw' tool should handle this with aplomb. There's a temporary issue with
'git-pw' whereby the project must be configured as 'open vswitch' rather than
'openvswitch' [2], but that should be fixed in the next day or two.

We don't plan to do any more with the XML-RPC API and will likely remove it in
3.0. pwclient should stick around, assuming we get to rework it to use the REST
API, but git-pw should provide a more pleasant interface and is to be
preferred.

Hope this helps,
Stephen

[1] https://patchwork.ozlabs.org/patch/809677/
[2] https://github.com/getpatchwork/patchwork/issues/117
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH v2] docs: Add references to git-pw

[Stephen Finucane]

Now that Patchwork 2.0 is out, folks can start to take advantage of some
of the new features that it offers. Chief among these is series support,
which is only exposed via the web UI and new REST API and which, in
turn, necessitates using git-pw rather than pwclient. As such, this tool
is slightly documented.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Add information on configuring git-pw for the OVS project
- Remove most documentation for pwclient, leaving only a footnote about
  its deprecated nature
---
 Documentation/internals/patchwork.rst | 51 +--
 1 file changed, 37 insertions(+), 14 deletions(-)

diff --git a/Documentation/internals/patchwork.rst 
b/Documentation/internals/patchwork.rst
index 3ae0d9503..bc5c89c96 100644
--- a/Documentation/internals/patchwork.rst
+++ b/Documentation/internals/patchwork.rst
@@ -29,33 +29,56 @@ Patchwork
 
 Open vSwitch uses `Patchwork`__ to track the status of patches sent to the
 :doc:`ovs-dev mailing list `. The Open vSwitch Patchwork
-instance can be found on `ozlabs.org`__. The ``pwclientrc`` file, required for
-*pwclient*, can be found on the `project page`__
+instance can be found on `ozlabs.org`__.
 
 Patchwork provides a number of useful features for developers working on Open
 vSwitch:
 
 - Tracking the lifecycle of patches (accepted, rejected, under-review, ...)
 - Assigning reviewers (delegates) to patches
-- Downloading/applying patches via the web UI or the XML-RPC API (see
-  :ref:`pwclient`)
+- Downloading/applying patches, series, and bundles via the web UI or the REST
+  API (see :ref:`git-pw`)
 - A usable UI for viewing patch discussions
 
 __ https://github.com/getpatchwork/patchwork
 __ https://patchwork.ozlabs.org/project/openvswitch/list/
-__ https://patchwork.ozlabs.org/project/openvswitch/
 
-.. _pwclient:
+.. _git-pw:
 
-pwclient
-
+git-pw
+--
+
+The *git-pw* tool provides a way to download and apply patches, series, and
+bundles. You can install *git-pw* from `PyPi`__ like so::
+
+$ pip install --user git-pw
+
+To actually use *git-pw*, you must configure it with the Patchwork instance
+URL, Patchwork project, and your Patchwork user authentication token. The URL
+and project are provided below, but you must obtain your authentication token
+from your `Patchwork User Profile`__ page. If you do not already have a
+Patchwork user account, you should create one now.
+
+Once your token is obtained, configure *git-pw* as below. Note that this must
+be run from within the Open vSwitch Git repository::
 
-The *pwclient* tool provides an way to download and apply patches, change the
-state of patches in Patchwork, and more. You can download *pwclient* from
-`here`__. Once downloaded, run::
+$ git config pw.server https://patchwork.ozlabs.org/
+$ git config pw.project openvswitch
+$ git config pw.token $PW_TOKEN  # using the token obtained earlier
 
-$ pwclient help
+Once configured, run the following to get information about available
+commands::
 
-to get more information about the functionality pwclient provides.
+$ git pw --help
+
+__ https://pypi.python.org/pypi/git-pw
+__ https://patchwork.ozlabs.org/user/
+
+.. _pwclient:
+
+pwclient
+
 
-__ https://patchwork.ozlabs.org/pwclient/
+The *pwclient* is a legacy tool that provides some of the functionality of
+*git-pw* but uses the legacy XML-RPC API. It is considered deprecated in its
+current form and *git-pw* should be used instead.
-- 
2.13.5

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Add references to git-pw

[Stephen Finucane]

On Wed, 2017-08-30 at 10:38 -0700, Joe Stringer wrote:
> On 29 August 2017 at 02:54, Stephen Finucane <step...@that.guru> wrote:
> > Now that Patchwork 2.0 is out, folks can start to take advantage of some
> > of the new features that it offers. Chief among these is series support,
> > which is only exposed via the web UI and new REST API and which, in
> > turn, necessitates using git-pw rather than pwclient. As such, this tool
> > is slightly documented.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> > PS: I still plan to get back to converting the man pages to rST, but
> > have been sidetracked by other projects/work. Eventually! :)
> > ---
> >  Documentation/internals/patchwork.rst | 34 ++-
> > ---
> >  1 file changed, 26 insertions(+), 8 deletions(-)
> > 
> > diff --git a/Documentation/internals/patchwork.rst
> > b/Documentation/internals/patchwork.rst
> > index 3ae0d9503..07b233bd3 100644
> > --- a/Documentation/internals/patchwork.rst
> > +++ b/Documentation/internals/patchwork.rst
> > @@ -29,33 +29,51 @@ Patchwork
> > 
> >  Open vSwitch uses `Patchwork`__ to track the status of patches sent to the
> >  :doc:`ovs-dev mailing list `. The Open vSwitch Patchwork
> > -instance can be found on `ozlabs.org`__. The ``pwclientrc`` file, required
> > for
> > -*pwclient*, can be found on the `project page`__
> > +instance can be found on `ozlabs.org`__.
> > 
> >  Patchwork provides a number of useful features for developers working on
> > Open
> >  vSwitch:
> > 
> >  - Tracking the lifecycle of patches (accepted, rejected, under-review,
> > ...)
> >  - Assigning reviewers (delegates) to patches
> > -- Downloading/applying patches via the web UI or the XML-RPC API (see
> > -  :ref:`pwclient`)
> > +- Downloading/applying patches, series, and bundles via the web UI, REST
> > API
> > +  (see :ref:`git-pw`), or the legacy XML-RPC API (see :ref:`pwclient`)
> >  - A usable UI for viewing patch discussions
> > 
> >  __ https://github.com/getpatchwork/patchwork
> >  __ https://patchwork.ozlabs.org/project/openvswitch/list/
> > -__ https://patchwork.ozlabs.org/project/openvswitch/
> > +
> > +.. _git-pw:
> > +
> > +git-pw
> > +--
> > +
> > +The *git-pw* tool provides a way to download and apply patches, series,
> > and
> > +bundles. You can install *git-pw* from `PyPi`__ like so::
> > +
> > +$ pip install --user git-pw
> > +
> > +Once installed, run::
> > +
> > +$ git pw --help
> > +
> > +to get more information about the functionality *git-pw* provides.
> > +
> > +__ https://pypi.python.org/pypi/git-pw
> 
> Perhaps we could document what config the user needs to set up for this to
> work?
> 
> Eg:
> 
> $ git config pw.server https://patchwork.ozlabs.org/

Good call. I'll add this now in a v2.

> I'd also like to filter to relevant patches:
> 
> $ git config pw.project openvswitch

Also good. I plan to make this a required option in v1.1, as displaying all
patches when using an instance as large as the ozlabs.org one is not all that
helpful.

> However, it seems like this is broken right now. (git-pw patch list
> returns empty list if I have project configured)

Eek. So that's a bug with Patchwork, not git-pw. I've posted the patch [1] and
it should be there before the end of the week. Good catch.

> > 
> >  .. _pwclient:
> > 
> >  pwclient
> >  
> 
> 
> 
> I was going to ask if we still need pwclient documentation, but I
> guess if git-pw is super new and working through some bugs then we
> should probably keep it around a while.

Actually, I'd be OK to drop it now. I've been using git-pw as my daily tool for
a few months now (though only against projects where name ~= linkname,
apparently) without issue. I'll drop it, with a note, in v2.

Thanks for the review, Joe :)
Stephen

[1] https://patchwork.ozlabs.org/patch/808139/
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH] docs: Add references to git-pw

[Stephen Finucane]

Now that Patchwork 2.0 is out, folks can start to take advantage of some
of the new features that it offers. Chief among these is series support,
which is only exposed via the web UI and new REST API and which, in
turn, necessitates using git-pw rather than pwclient. As such, this tool
is slightly documented.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
PS: I still plan to get back to converting the man pages to rST, but
have been sidetracked by other projects/work. Eventually! :)
---
 Documentation/internals/patchwork.rst | 34 ++
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/Documentation/internals/patchwork.rst 
b/Documentation/internals/patchwork.rst
index 3ae0d9503..07b233bd3 100644
--- a/Documentation/internals/patchwork.rst
+++ b/Documentation/internals/patchwork.rst
@@ -29,33 +29,51 @@ Patchwork
 
 Open vSwitch uses `Patchwork`__ to track the status of patches sent to the
 :doc:`ovs-dev mailing list `. The Open vSwitch Patchwork
-instance can be found on `ozlabs.org`__. The ``pwclientrc`` file, required for
-*pwclient*, can be found on the `project page`__
+instance can be found on `ozlabs.org`__.
 
 Patchwork provides a number of useful features for developers working on Open
 vSwitch:
 
 - Tracking the lifecycle of patches (accepted, rejected, under-review, ...)
 - Assigning reviewers (delegates) to patches
-- Downloading/applying patches via the web UI or the XML-RPC API (see
-  :ref:`pwclient`)
+- Downloading/applying patches, series, and bundles via the web UI, REST API
+  (see :ref:`git-pw`), or the legacy XML-RPC API (see :ref:`pwclient`)
 - A usable UI for viewing patch discussions
 
 __ https://github.com/getpatchwork/patchwork
 __ https://patchwork.ozlabs.org/project/openvswitch/list/
-__ https://patchwork.ozlabs.org/project/openvswitch/
+
+.. _git-pw:
+
+git-pw
+--
+
+The *git-pw* tool provides a way to download and apply patches, series, and
+bundles. You can install *git-pw* from `PyPi`__ like so::
+
+$ pip install --user git-pw
+
+Once installed, run::
+
+$ git pw --help
+
+to get more information about the functionality *git-pw* provides.
+
+__ https://pypi.python.org/pypi/git-pw
 
 .. _pwclient:
 
 pwclient
 
 
-The *pwclient* tool provides an way to download and apply patches, change the
+The *pwclient* tool provides a way to download and apply patches, change the
 state of patches in Patchwork, and more. You can download *pwclient* from
-`here`__. Once downloaded, run::
+`here`__. You will also need a ``pwclientrc`` file, which can be found on the
+`Open vSwitch project page`__. Once both files are downloaded, run::
 
 $ pwclient help
 
-to get more information about the functionality pwclient provides.
+to get more information about the functionality *pwclient* provides.
 
 __ https://patchwork.ozlabs.org/pwclient/
+__ https://patchwork.ozlabs.org/project/openvswitch/
-- 
2.13.5

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update dpdk vdev naming instructions

[Stephen Finucane]

On Wed, 2017-06-07 at 15:33 +0100, Stephen Finucane wrote:
> On Tue, 2017-06-06 at 16:26 +0100, Ciara Loftus wrote:
> > Signed-off-by: Ciara Loftus <ciara.lof...@intel.com>
> 
> I couldn't find where this changed (the only related commit was 69876ed, but 
> that references the
> previous naming format) but I trust you know what you're talking about. From 
> the docs side:
> 
> Acked-by: Stephen Finucane <step...@that.guru>

...though you should probably fix 'dpdk-devargs' in 'vswitchd/vswitch.xml', per 
the above commit.

Stephen

> 
> > ---
> >  Documentation/howto/dpdk.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> > index f3c7aff..93248b4 100644
> > --- a/Documentation/howto/dpdk.rst
> > +++ b/Documentation/howto/dpdk.rst
> > @@ -361,7 +361,7 @@ Virtual DPDK devices which do not have PCI addresses 
> > can be added using a
> >  different format for 'dpdk-devargs'.
> >  
> >  Typically, the format expected is 'eth_' where 'x' is a
> > -number between 0 and RTE_MAX_ETHPORTS -1 (31).
> > +unique identifier of your choice for the given port.
> >  
> >  For example to add a dpdk port that uses the 'null' DPDK PMD driver::
> >  
> 
> ___
> dev mailing list
> d...@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update dpdk vdev naming instructions

[Stephen Finucane]

On Tue, 2017-06-06 at 16:26 +0100, Ciara Loftus wrote:
> Signed-off-by: Ciara Loftus <ciara.lof...@intel.com>

I couldn't find where this changed (the only related commit was 69876ed, but 
that references the
previous naming format) but I trust you know what you're talking about. From 
the docs side:

Acked-by: Stephen Finucane <step...@that.guru>

> ---
>  Documentation/howto/dpdk.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index f3c7aff..93248b4 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -361,7 +361,7 @@ Virtual DPDK devices which do not have PCI addresses can 
> be added using a
>  different format for 'dpdk-devargs'.
>  
>  Typically, the format expected is 'eth_' where 'x' is a
> -number between 0 and RTE_MAX_ETHPORTS -1 (31).
> +unique identifier of your choice for the given port.
>  
>  For example to add a dpdk port that uses the 'null' DPDK PMD driver::
>  

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v6 2/5] userspace: L3 tunnel support for GRE and LISP

[Stephen Finucane]

On Thu, 2017-05-25 at 09:22 -0700, Ben Pfaff wrote:
> On Mon, May 22, 2017 at 01:43:25PM +, Jan Scheurich wrote:
> > > I think that parse_gre_header() should perhaps be pickier about
> > > the
> > > Ethertypes it accepts, since values below 0x600 are not valid
> > > Ethertypes and sometimes they are used for special purposes, for
> > > example
> > > OpenFlow uses 0x5ff to mean that the frame lacks an Ethertype.
> > 
> > I agree. OVS could just drop packets from GRE tunnels with GRE
> > protocols < 0x600.
> > 
> > > 
> > > I recommend adding an item to NEWS to mention this new user-
> > > visible
> > > feature.
> > 
> > What about:
> > 
> > diff --git a/NEWS b/NEWS
> > index 25eb477..bbed787 100644
> > --- a/NEWS
> > +++ b/NEWS
> > @@ -45,6 +45,12 @@ Post-v2.7.0
> > - Fedora Packaging:
> >   * OVN services are no longer restarted automatically after
> > upgrade.
> > - Add --cleanup option to command 'ovs-appctl exit' (see ovs-
> > vswitchd(8)).
> > +   - L3 tunneling:
> > + * Add "layer3" options for tunnel ports that support non-
> > Ethernet (L3)
> > +   payload (GRE, VXLAN-GPE).
> > + * New vxlan tunnel extension "gpe" to support VXLAN-GPE
> > tunnels.
> > + * Transparently pop and push Ethernet headers at
> > transmit/reception
> > +   of packets to/from L3 tunnels.
> 
> Sure, thanks!
> 
> > > Ideally, some new documentation would explain how layer 2 and 3
> > > packets
> > > interact.
> > 
> > I am planning for proper documentation along the lines of the
> > Google doc as part of the overall PTAP and generic Encap/Decap
> > patch complex.
> > 
> > Can you recommend a good authoring tool for the .rst format used in
> > OVS lately?
> 
> I use Emacs, which is only so-so at RST, so I don't have a good
> recommendation.  Stephen, what do you use?

There's a good section in the docs about this:

  http://docs.openvswitch.org/en/latest/internals/contributing/document
ation-style/#helpful-tools

Personally, I use vim with the 'scrooloose/syntastic' plugin and the
following autocmd snippet:

  if has("autocmd")
  au FileType rst setlocal textwidth=79 spell
  endif

...which will force wrapping and enable spell check. All the good stuff
is in my dotfiles repo:

  https://github.com/stephenfin/dotfiles

If you 'Cc' me in any patches you write, I'd be happy to review them (I
don't monitor the OVS ML actively otherwise).

Hope this helps,
Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH 1/2] docs: Clarify the superiority of dpdkvhostuserclient

[Stephen Finucane]

Apparently dpdkvhostuser interfaces are inferior to dpdkvhostuserclient.
Explain why.

Signed-off-by: Stephen Finucane <step...@that.guru>
Cc: Ciara Loftus <ciara.lof...@intel.com>
Cc: Kevin Traynor <ktray...@redhat.com>
---
I'd like to note what happens to traffic when OVS or a VM is restarted
for both port types. If someone knows the answer to this, please feel
free to take ownership of that patch/ask me for a v2.
---
 Documentation/topics/dpdk/vhost-user.rst | 8 ++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/topics/dpdk/vhost-user.rst 
b/Documentation/topics/dpdk/vhost-user.rst
index ba22684..2e2396b 100644
--- a/Documentation/topics/dpdk/vhost-user.rst
+++ b/Documentation/topics/dpdk/vhost-user.rst
@@ -54,8 +54,12 @@ vHost User sockets, and the client connects to the server. 
Depending on which
 port type you use, ``dpdkvhostuser`` or ``dpdkvhostuserclient``, a different
 configuration of the client-server model is used.
 
-For vhost-user ports, Open vSwitch acts as the server and QEMU the client.  For
-vhost-user-client ports, Open vSwitch acts as the client and QEMU the server.
+For vhost-user ports, Open vSwitch acts as the server and QEMU the client. This
+means if OVS dies, all VMs **must** be restarted. On the other hand, for
+vhost-user-client ports, OVS acts as the client and QEMU the server. This means
+OVS can die and be restarted without issue, and it is also possible to restart
+an instance itself. For this reason, vhost-user-client ports are the preferred
+type for most use cases.
 
 .. _dpdk-vhost-user:
 
-- 
2.9.4

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH 2/2] docs: Document dpdkr ports

[Stephen Finucane]

I has an idea what these were but that idea was somewhat incorrect and
out-of-date. Add a minimal guide to fill in these gaps, along with a
warning about how useless these things generally are now (yay,
vhost-user).

Signed-off-by: Stephen Finucane <step...@that.guru>
Cc: Ciara Loftus <ciara.lof...@intel.com>
Cc: Kevin Traynor <ktray...@redhat.com>
---
 Documentation/topics/dpdk/index.rst  |  1 +
 Documentation/topics/dpdk/ring.rst   | 80 
 Documentation/topics/dpdk/vhost-user.rst |  8 ++--
 3 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/topics/dpdk/ring.rst

diff --git a/Documentation/topics/dpdk/index.rst 
b/Documentation/topics/dpdk/index.rst
index 180ebbf..da148b3 100644
--- a/Documentation/topics/dpdk/index.rst
+++ b/Documentation/topics/dpdk/index.rst
@@ -29,3 +29,4 @@ The DPDK Datapath
:maxdepth: 2
 
vhost-user
+   ring
diff --git a/Documentation/topics/dpdk/ring.rst 
b/Documentation/topics/dpdk/ring.rst
new file mode 100644
index 000..347d095
--- /dev/null
+++ b/Documentation/topics/dpdk/ring.rst
@@ -0,0 +1,80 @@
+..
+  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 Ring Ports
+===
+
+.. warning::
+
+   DPDK ring interfaces cannot be used for guest communication and are retained
+   mainly for backwards compatibility purposes. In nearly all cases,
+   :doc:`vhost-user ports ` are a better choice and should be used
+   instead.
+
+The DPDK datapath provides DPDK-backed ring ports that are implemented using
+DPDK's ``librte_ring`` library. For more information of this library, refer to
+the `DPDK documentation`_.
+
+Quick Example
+-
+
+This example demonstrates how to add a ``dpdkr`` port to an existing bridge
+called ``br0``::
+
+$ ovs-vsctl add-port br0 dpdkr0 -- set Interface dpdkr0 type=dpdkr
+
+dpdkr
+-
+
+To use ring ports, you must first add said ports to the switch. Unlike
+:doc:`vhost-user interfaces `, ring port names must take a specific
+format, ``dpdkrNN``, where ``NN`` is the port ID. For example::
+
+$ ovs-vsctl add-port br0 dpdkr0 -- set Interface dpdkr0 type=dpdkr
+
+Once the port has been added to the switch, they can be used by host processes.
+A sample loopback application - ``test-dpdkr`` - is included with Open vSwitch.
+To use this, run the following::
+
+$ ./tests/test-dpdkr -c 1 -n 4 --proc-type=secondary -- -n 0
+
+Further functionality would require developing your own application. Refer to
+the `DPDK documentation`_ for more information on how to do this.
+
+Adding dpdkr ports to the guest
+~~~
+
+It is **not** possible to use ring ports from guests. Historically, this was
+possible using a patched version of QEMU and the IVSHMEM feature provided with
+DPDK. However, this functionality was removed because:
+
+- The IVSHMEM library was removed from DPDK in DPDK 16.11
+
+- Support for IVSHMEM was never upstreamed to QEMU and has been publicly
+  rejected by the QEMU community
+
+- :doc:`vhost-user interfaces ` are the defacto DPDK-based path to
+  guests
+
+.. _DPDK documentation: 
https://dpdk.readthedocs.io/en/v17.05/prog_guide/ring_lib.html
diff --git a/Documentation/topics/dpdk/vhost-user.rst 
b/Documentation/topics/dpdk/vhost-user.rst
index 2e2396b..a1c19fd 100644
--- a/Documentation/topics/dpdk/vhost-user.rst
+++ b/Documentation/topics/dpdk/vhost-user.rst
@@ -70,10 +70,10 @@ vhost-user
 
Use of vhost-user ports requires QEMU >= 2.2
 
-To use vhost-user ports, you must first add said ports to the switch. Unlike
-DPDK ring ports, DPDK vhost-user ports can have arbitrary names, except that
-forward and backward slashes are prohibited in the names. For vhost-user, the
-port type is ``dpdkvhostuser``::
+To use vhost-user ports, you must first add said ports to the switch. DPDK
+vhost-user ports can have arbitrary names with the exception of forward and
+backward slashes, which are prohibited. For vhost-user, the port type is
+``dpdkvhostuser``::
 
 $ ovs-vsctl add-port br0 vhost-user-1 -- set Interface vhost-user-

Re: [ovs-dev] [RFC 1/2] doc: Reduce duplication in 'man_pages'

[Stephen Finucane]

On Fri, 2017-05-19 at 09:11 +, Bodireddy, Bhanuprakash wrote:
> The make fails with below error on my fedora 22 Target. 
> 
> error.log--
> 
> Documentation/conf.py:126:9: F812 list comprehension redefines
> 'filename' from line 59
> Makefile:5848: recipe for target 'flake8-check' failed
> make[2]: *** [flake8-check] Error 1
> make[2]: Leaving directory '/workspace/master/ovs'
> Makefile:5182: recipe for target 'all-recursive' failed
> make[1]: *** [all-recursive] Error 1
> make[1]: Leaving directory '/workspace/master/ovs'
> Makefile:3014: recipe for target 'all' failed
> make: *** [all] Error 2
> 
> I don't see this issue when I replace the filename with 'file_name'
> as below.  
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index d70ee6b..77c4df5 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -121,6 +121,6 @@ _man_pages = [
> 
>  # Generate list of (path, name, description, [author, ...], section)
>  man_pages = [
> -('ref/%s' % filename, filename.split('.', 1)[0],
> - description, [author], filename.split('.', 1)[1])
> -for filename, description in _man_pages]
> +('ref/%s' % file_name, file_name.split('.', 1)[0],
> + description, [author], file_name.split('.', 1)[1])
> +for file_name, description in _man_pages]
> 
> Regards,
> Bhanuprakash. 

Damn - I missed that. Patch submitted to fix this now.

Stephen

> > -Original Message-
> > From: ovs-dev-boun...@openvswitch.org [mailto:ovs-dev-
> > boun...@openvswitch.org] On Behalf Of Ben Pfaff
> > Sent: Thursday, May 18, 2017 11:50 PM
> > To: Stephen Finucane <step...@that.guru>
> > Cc: d...@openvswitch.org
> > Subject: Re: [ovs-dev] [RFC 1/2] doc: Reduce duplication in
> > 'man_pages'
> > 
> > On Wed, May 10, 2017 at 09:32:18PM -0400, Stephen Finucane wrote:
> > > All these entries are going to be roughly the same, with only two
> > > key
> > > differences. Clarify things by focusing on those differences.
> > > 
> > > Signed-off-by: Stephen Finucane <step...@that.guru>
> > 
> > Fair enough!  Thanks, I applied this to master.
> > ___
> > dev mailing list
> > d...@openvswitch.org
> > https://mail.openvswitch.org/mailman/listinfo/ovs-dev

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH] doc: Resolve pep8 warnings in conf.py

[Stephen Finucane]

flake8 doesn't like us redefining variables in loops.

Signed-off-by: Stephen Finucane <step...@that.guru>
Reported-by: Bhanuprakash Bodireddy <bhanuprakash.bodire...@intel.com>
Fixes: f15010f ("doc: Reduce duplication in 'man_pages'")
Cc: Ben Pfaff <b...@ovn.org>
---
 Documentation/conf.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d70ee6b..77c4df5 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -121,6 +121,6 @@ _man_pages = [
 
 # Generate list of (path, name, description, [author, ...], section)
 man_pages = [
-('ref/%s' % filename, filename.split('.', 1)[0],
- description, [author], filename.split('.', 1)[1])
-for filename, description in _man_pages]
+('ref/%s' % file_name, file_name.split('.', 1)[0],
+ description, [author], file_name.split('.', 1)[1])
+for file_name, description in _man_pages]
-- 
2.9.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [RFC 2/2] doc: Convert ovs-vswitchd to rST

[Stephen Finucane]

This is the largest man page by some distance. There are a couple of
changes needed to make this work:

- Combining italics and bold without spaces (i.e. hello-world
  ) and nesting italics and bold (i.e. hello-world)
  is not supported by rST. Where present, this has been removed.

- Duplicated opts are not possible. Where before we would have had a
  list like so:

-vPATTERN:destination:pattern
  Description

-vFACILITY:facility
  Description

   We now have:

 -v 

   PATTERN::
 Description

   FACILITY:
 Description

  This is necessary if we want to make best use of the Sphinx indexing.

- TODO

Signed-off-by: Stephen Finucane <step...@that.guru>
---
This patch isn't complete, but I wanted to see what people thought of
the formatting for more complex commands. There are a couple of issues
with this that I still need to work through:

- There's a big loss of formatting for subcommands. While I don't think
  the bit of loss in the option descriptions is _that_ big a deal, the
  subcommands are longer and could benefit from the formatting more. I
  could probably fix it in Sphinx internally for Sphinx 1.6, but that'd
  take a year or two to propagate to distros.

- I'm not sure if there's a way to use this kind of macro:

\*(DX\fBadd\-dp \fIdp\fR [\fInetdev\fR[\fB,\fIoption\fR]...]

  which is called like so:

.ds DX \fBdpctl/\fR
.de DO
\\$2 \\$1 \\$3

  and yields:

dpctl/add-dp dp [netdev[,option]...]

  This will probably result in some duplication, else a _lot_ of 'inc'
  files

- I'm not sure how we should pass in autoconf (?) variables like
  @RUNDIR@. Could we do this in Python or something?

- Some other stuff that I've forgotten

In any case though, it should go folks a rough idea of what a larger man
page in rST/Sphinx will actually look like.
---
 Documentation/conf.py  |   2 +
 Documentation/ref/common.inc   |   7 +
 Documentation/ref/coverage-unixctl.inc |  16 ++
 Documentation/ref/daemon.inc   |  85 ++
 Documentation/ref/dpctl.inc| 199 ++
 Documentation/ref/index.rst|   1 +
 Documentation/ref/memory-unixctl.inc   |  10 +
 Documentation/ref/ofproto-dpif-unixctl.inc |  38 +++
 Documentation/ref/ofproto-tnl-unixctl.inc  |  40 +++
 Documentation/ref/ofproto-unixctl.inc  | 162 +++
 Documentation/ref/ovs-vswitchd.8.rst   | 414 +
 Documentation/ref/remote-active.inc|  22 ++
 Documentation/ref/remote-passive.inc   |  28 ++
 Documentation/ref/service.inc  |  14 +
 Documentation/ref/ssl-bootstrap.inc|  22 ++
 Documentation/ref/ssl.inc  |  33 +++
 Documentation/ref/unixctl.inc  |  16 ++
 Documentation/ref/vlog-unixctl.inc |  79 ++
 Documentation/ref/vlog.inc |  88 ++
 19 files changed, 1276 insertions(+)
 create mode 100644 Documentation/ref/common.inc
 create mode 100644 Documentation/ref/coverage-unixctl.inc
 create mode 100644 Documentation/ref/daemon.inc
 create mode 100644 Documentation/ref/dpctl.inc
 create mode 100644 Documentation/ref/memory-unixctl.inc
 create mode 100644 Documentation/ref/ofproto-dpif-unixctl.inc
 create mode 100644 Documentation/ref/ofproto-tnl-unixctl.inc
 create mode 100644 Documentation/ref/ofproto-unixctl.inc
 create mode 100644 Documentation/ref/ovs-vswitchd.8.rst
 create mode 100644 Documentation/ref/remote-active.inc
 create mode 100644 Documentation/ref/remote-passive.inc
 create mode 100644 Documentation/ref/service.inc
 create mode 100644 Documentation/ref/ssl-bootstrap.inc
 create mode 100644 Documentation/ref/ssl.inc
 create mode 100644 Documentation/ref/unixctl.inc
 create mode 100644 Documentation/ref/vlog-unixctl.inc
 create mode 100644 Documentation/ref/vlog.inc

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d70ee6b..174cc7e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -113,6 +113,8 @@ html_static_path = ['_static']
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 _man_pages = [
+('ovs-vswitchd.8',
+ u'Open vSwitch daemon'),
 ('ovs-test.8',
  u'Check Linux drivers for performance, vlan and L3 tunneling problems'),
 ('ovs-vlan-test.8',
diff --git a/Documentation/ref/common.inc b/Documentation/ref/common.inc
new file mode 100644
index 000..321b331
--- /dev/null
+++ b/Documentation/ref/common.inc
@@ -0,0 +1,7 @@
+.. option:: -h, --help
+
+Prints a brief help message to the console.
+
+.. option:: -V, --version
+
+Prints version information to the console.
diff --git a/Documentation/ref/coverage-unixctl.inc 
b/Documentation/ref/coverage-unixctl.inc
new file mode 100644
index 000..90563e9
--- /dev/null
+++ b/Documentation/ref/coverage-unixctl.inc
@@ -0,0 +1,16 @@
+Coverage Commands
+-
+
+These commands 

Re: [ovs-dev] Cover letters (was Re: [PATCH 0/7] Add OVS DPDK keep-alive functionality)

[Stephen Finucane]

On Tue, 2017-05-02 at 12:21 -0400, Aaron Conole wrote:
> Ben Pfaff  writes:
> 
> > On Mon, May 01, 2017 at 04:45:56PM -0400, Aaron Conole wrote:
> > > Ben Pfaff  writes:
> > > ...
> > > > I think it'd be even better to include measurements in one of
> > > > the commit messages, because those are available in the
> > > > repository after the patches are applied.  It's harder to find
> > > > cover letters because they're only on the mailing list.
> > > 
> > > One thing that other projects do to keep the cover letters is to
> > > create a branch, apply all the patches from the series, and then
> > > create a merge commit, with the commit message as the cover
> > > letter.  It can make the history a bit messier, but means that
> > > the cover letter is retained, and makes 'git bisect' work quite a
> > > bit better (because bisect knows how to skip merged trees
> > > appropriately).  It could be worth doing, because it can help to
> > > explain an overall motivation for a series when walking the tree
> > > with git annotations.
> > 
> > I wouldn't object to that, for well-organized series.
> > 
> > Is there a way to automate applying a branch like this from
> > email?  Or is it better to do them as pull requests (whether via
> > email or Github)?
> 
> I think patchwork provides access to the cover letter somehow.  I've
> CC'd Stephen because he has a bit of experience with PW, and may be
> able to comment on whether or not I'm just crazy.

Patchwork 2.0 will. We're finishing up the release at the moment (RC
this week. Final release some time later this month), but it'll allow
downloading of entire series and displaying of cover letters. One of
the Patchwork contributors has a sample instance up to browse [1].

You should also check out 'git-pw' [2] (which I think Aaron has
contributed patches to?). This relies on Patchwork 2.0, but it'll make
downloading and applying a series as easy as:

  git-pw series apply {seriesID}

for a whole series, or:

  git-pw patch apply {patchID}

for a patch with its dependencies.

I'll be sure to ping the list as soon as the 2.0 is released and the
ozlabs instance bumped, which should be (fingers crossed) any week now.

Stephen

[1] https://py3.patchwork.dja.id.au/project/lkml/list/
[2] https://github.com/stephenfin/git-pw
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH v2 6/6] Documentation: Update DPDK doc with Keepalive feature.

[Stephen Finucane]

ock can be read by external
> monitoring
> +framework (or) applications. `collectd <https://collectd.org/>`__
> has built-in
> +support for DPDK and provides a `dpdkevents` plugin that can be
> enabled to
> +relay the datapath core status to OpenStack service `Ceilometer
> +<https://docs.openstack.org/developer/ceilometer/>`__.
> +
> +To install and configure `collectd`, run::
> +
> +# Clone collectd from Git repository
> +$ git clone https://github.com/collectd/collectd.git
> +
> +# configure and install collectd
> +$ cd collectd
> +$ ./build.sh
> +$ ./configure --enable-syslog --enable-logfile --with-
> libdpdk=/usr
> +$ make
> +$ make install
> +

I should have called this out first time, but I'm not sure we want to
duplicate collectd's installation procedure as these things can change.
We might be better of linking to installation docs. _However_, we do
this already for DPDK so there is precedent. If you think we should
keep them (and you likely do), I'd be happy to simply include a link to
the installation docs like so:

For further information on installing and configuring collectd,
refer to the `collectd installation guide `__.

> +`collectd` is installed in ``/opt/collectd`` by default. Edit the
> configuration
> +file in ``/opt/collectd/etc/collectd.conf`` to enable logfile,
> dpdkevents
> +and csv plugin::

nit:

...to enable the `logfile`, `dpdkevents`, and `csv` plugins. To
enable the `logfile` plugin, add::

> +
> +   LoadPlugin logfile
> +   
> +   LogLevel debug
> +   File "/var/log/collectd/collectd.log"
> +   Timestamp true
> +   PrintSeverity false
> +   
> +
> +   
> +   LogLevel info
> +   
> +
> +Enable `dpdkevents` plugin and update the plugindetails as below::

Is 'plugindetails' a variable or file name, or simply a term you're
using to reference the below chunk of XML? If the latter, perhaps
something like:

To enable the `dpdkevents` plugin, add:

> +
> +   LoadPlugin dpdkevents
> +
> +   
> + 
> +   Coremask "0x2"
> +   MemoryChannels "4"
> +   ProcessType "secondary"
> +   FilePrefix "rte"
> + 
> + 
> +   SendEventsOnUpdate true
> +   LCoreMask "0xf"
> +   KeepAliveShmName "/dpdk_keepalive_shm_name"
> +   SendNotification True
> +  
> +   
> +
> +``LCoreMask`` should be set to the PMD cores that were earlier
> registered
> +for keepalive monitoring. ``KeepAliveShmName`` refers to shared
> memory block
> +region.
> +
+Enable ``csv`` plugin as below::
> +
> +   LoadPlugin csv
> +
> +   
> +   DataDir "/var/log/collectd/csv"
> +   StoreRates false
> +   
> +
> +With csv plugin enabled, *meter* or *gauge* file is created and
> timestamp

s/*meter*/a *meter*/

> +and core status gets updated which are sent to ceilometer service.
> For example
> +``../csv/localhost/dpdkevents-keepalive/gauge-lcore3-2017-04-01`` is
> the file
> +for pmd thread running on core 3.
> +
>  .. _dpdk-ovs-in-guest:
>  
>  OVS with DPDK Inside VMs

All the above could be fixed at merge time or after merge, and I'd be
happy to see this go in even as is. As such:

Acked-by: Stephen Finucane <step...@that.guru>

Thanks, Bhanuprakash, :)

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

[Stephen Finucane]

On Wed, 2017-04-26 at 10:55 -0400, Lance Richardson wrote:
> > From: "Ben Pfaff" 
> > To: "Lance Richardson" 
> > Cc: "Leif Madsen" , "ovs dev"  > org>
> > Sent: Wednesday, 26 April, 2017 10:33:09 AM
> > Subject: Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST
> > 
> > On Tue, Apr 25, 2017 at 04:03:55PM -0400, Lance Richardson wrote:
> > > I ran into this a little while ago. The problem in my case was
> > > that
> > > sphinx-build
> > > was not installed, so these man pages were not being built (seems
> > > odd that
> > > this
> > > would not cause a build failure...)
> > > 
> > > Doing "yum install python-sphinx" let me build the rpms
> > > successfully once
> > > again. Seems we should add "BuildRequires: python-sphinx" to the
> > > spec file.
> > 
> > Huh.  Somehow I thought that we'd made Sphinx an overall build
> > requirement.  Maybe that's the right thing to do.
> > 
> 
> The rules to build rst-formatted man pages in the top-level
> Makefile.in are predicated on HAVE_SPHINX_TRUE, which does give the
> impression that Sphinx is optional.
> 
>    Lance

Yup, it's optional since these were only used for HTML docs initially.
I didn't change that as HAVE_GROFF is also a thing, afaict, and I
wasn't sure if man pages were essential. Maybe they should be now.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [branch-2.7] Documentation: Remove external dependence on pygments.

[Stephen Finucane]

On Wed, 2017-04-19 at 08:12 -0700, Ben Pfaff wrote:
> On Wed, Apr 19, 2017 at 12:23:39PM +0100, Stephen Finucane wrote:
> > From: Ilya Maximets <i.maxim...@samsung.com>
> > 
> > Current documentation uses syntax highlighting in 'sphinx'
> > via 'pygments' library. This leads to build failures on the
> > systems with old version of this library.
> > 
> > In fact that only 'windows.rst' uses highlighting it's a
> > very simple change. This helps us to avoid build issues
> > on different systems and allows to remove painful external
> > dependency.
> > 
> > Signed-off-by: Ilya Maximets <i.maxim...@samsung.com>
> > Signed-off-by: Ben Pfaff <b...@ovn.org>
> > (cherry picked from commit
> > 23cb93ff917e2addfed497730a8e72f261e677ce)
> 
> Thanks.  I applied this to branch-2.7.
> 
> (For a straight cherry-pick like this, it's enough to just ask for a
> cherry-pick, no need to re-send the whole patch.)

Thanks, Ben. Different rules for OpenStack :)

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH ovs V2] Documentation: fix broken links in maintainers page

[Stephen Finucane]

On Wed, 2017-04-19 at 16:52 +0300, Roi Dayan wrote:
> Missing the internals sub folder.
> 
> Signed-off-by: Roi Dayan <r...@mellanox.com>

I wonder should these links be updated to point to the absolute URL on
docs.openvswitch.org, e.g.

  `here <http://docs.openvswitch.org/en/latest/internals/committer-
responsibilities.rst>`__

or, cleaner:

  `here`__

  __ http://docs.openvswitch.org/en/latest/internals/committer-responsi
bilities.rst

I should have mentioned this before but I didn't think of it . Thi
s can be fixed at merge time though, so for this as-is:

Acked-by: Stephen Finucane <step...@that.guru>

> ---
> 
> V2
> - fix links but keep GitHub style as it's a top-level document
> 
> 
>  MAINTAINERS.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst
> index 28831ab..60fa1f5 100644
> --- a/MAINTAINERS.rst
> +++ b/MAINTAINERS.rst
> @@ -29,10 +29,10 @@ Open vSwitch committers are the people who have
> been granted access to push
>  changes to to the Open vSwitch git repository.
>  
>  The responsibilities of an Open vSwitch committer are documented
> -`here `__.
> +`here `__.
>  
>  The process for adding or removing committers is documented
> -`here `__.
> +`here `__.
>  
>  This is the current list of Open vSwitch committers:
>  

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] Documentation: Remove external dependence on pygments.

[Stephen Finucane]

On Wed, 2017-04-19 at 12:21 +0100, Stephen Finucane wrote:
> From: Ilya Maximets <i.maxim...@samsung.com>
> 
> Current documentation uses syntax highlighting in 'sphinx'
> via 'pygments' library. This leads to build failures on the
> systems with old version of this library.
> 
> In fact that only 'windows.rst' uses highlighting it's a
> very simple change. This helps us to avoid build issues
> on different systems and allows to remove painful external
> dependency.
> 
> Signed-off-by: Ilya Maximets <i.maxim...@samsung.com>
> Signed-off-by: Ben Pfaff <b...@ovn.org>
> (cherry picked from commit 23cb93ff917e2addfed497730a8e72f261e677ce)

I missed the fact that this needed a prefix. Re-submitted accordingly,
so you can ignore this now.

Stephen

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [branch-2.7] Documentation: Remove external dependence on pygments.

[Stephen Finucane]

From: Ilya Maximets 

Current documentation uses syntax highlighting in 'sphinx'
via 'pygments' library. This leads to build failures on the
systems with old version of this library.

In fact that only 'windows.rst' uses highlighting it's a
very simple change. This helps us to avoid build issues
on different systems and allows to remove painful external
dependency.

Signed-off-by: Ilya Maximets 
Signed-off-by: Ben Pfaff 
(cherry picked from commit 23cb93ff917e2addfed497730a8e72f261e677ce)
---
 Documentation/conf.py  |  3 -
 .../internals/contributing/documentation-style.rst | 10 ++-
 Documentation/intro/install/windows.rst| 88 +++---
 Documentation/topics/language-bindings.rst |  2 +-
 4 files changed, 51 insertions(+), 52 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 389ef70..ab439cf 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -107,9 +107,6 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 #
 # show_authors = False
 
-# The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = 'friendly'
-
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
diff --git a/Documentation/internals/contributing/documentation-style.rst 
b/Documentation/internals/contributing/documentation-style.rst
index ea41a07..99eec69 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -115,9 +115,11 @@ Titles
 Code
 
 
-- Use ``::``, the ``code`` role or the ``code-block:: `` role to prefix
-  code. The ``code-block:: `` format is preferred as this provides
-  syntax highlighting for non-Python languages, such as Bash or PowerShell.
+- Use ``::`` to prefix code.
+
+- Don't use syntax highlighting such as ``.. highlight:: `` or
+  ``code-block:: `` because it depends on external ``pygments``
+  library.
 
 - Prefix commands with ``$``.
 
@@ -259,7 +261,7 @@ Figures and Other Media
 - All images should be in PNG format and compressed where possible. For PNG
   files, use OptiPNG and AdvanceCOMP's ``advpng``:
 
-  .. code-block:: shell
+  ::
 
  $ optipng -o7 -zm1-9 -i0 -strip all 
  $ advpng -z4 
diff --git a/Documentation/intro/install/windows.rst 
b/Documentation/intro/install/windows.rst
index caa9f40..2be4eb5 100644
--- a/Documentation/intro/install/windows.rst
+++ b/Documentation/intro/install/windows.rst
@@ -63,7 +63,7 @@ The following explains the steps in some detail.
   We require that you have Python six and pypiwin32 libraries installed.
   The libraries can be installed via pip command:
 
-   .. code-block:: console
+   ::
 
   $ pip install six
   $ pip install pypiwin32
@@ -140,7 +140,7 @@ you pulled the sources directly from an Open vSwitch Git 
tree or got a
 Git tree snapshot, then run boot.sh in the top source directory to build
 the "configure" script:
 
-.. code-block:: console
+::
 
$ ./boot.sh
 
@@ -153,7 +153,7 @@ Configure the package by running the configure script.  You 
should provide some
 configure options to choose the right compiler, linker, libraries, Open vSwitch
 component installation directories, etc. For example:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="$(which link)" \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -169,7 +169,7 @@ component installation directories, etc. For example:
 
 To configure with SSL support, add the requisite additional options:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="`which link`"  \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -181,7 +181,7 @@ To configure with SSL support, add the requisite additional 
options:
 
 Finally, to the kernel module also:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="`which link`" \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -211,7 +211,7 @@ building on Linux, FreeBSD, or NetBSD.
 
 #. Run make for the ported executables in the top source directory, e.g.:
 
-   .. code-block:: console
+   ::
 
   $ make
 
@@ -225,25 +225,25 @@ building on Linux, FreeBSD, or NetBSD.
   all MinGW sessions and then run the below command from MSVC developers
   command prompt.:
 
-  .. code-block:: doscon
+  ::
 
  > mingw-get upgrade msys-core-bin=1.0.17-1
 
 #. To run all the unit tests in Open vSwitch, one at a time:
 
-   .. code-block:: console
+   ::
 
   $ make check
 
To run all the unit tests in Open vSwitch, up to 8 in parallel:
 
-   .. code-block:: console
+   ::
 
   $ make check TESTSUITEFLAGS="-j8"
 
 #. To install all the compiled executables on the local machine, run:
 
-   .. code-block:: console
+   ::
 
   $ make install
 
@@ -276,7 +276,7 @@ Now run ``./uninstall.cmd`` to 

[ovs-dev] [PATCH] Documentation: Remove external dependence on pygments.

[Stephen Finucane]

From: Ilya Maximets 

Current documentation uses syntax highlighting in 'sphinx'
via 'pygments' library. This leads to build failures on the
systems with old version of this library.

In fact that only 'windows.rst' uses highlighting it's a
very simple change. This helps us to avoid build issues
on different systems and allows to remove painful external
dependency.

Signed-off-by: Ilya Maximets 
Signed-off-by: Ben Pfaff 
(cherry picked from commit 23cb93ff917e2addfed497730a8e72f261e677ce)
---
 Documentation/conf.py  |  3 -
 .../internals/contributing/documentation-style.rst | 10 ++-
 Documentation/intro/install/windows.rst| 88 +++---
 Documentation/topics/language-bindings.rst |  2 +-
 4 files changed, 51 insertions(+), 52 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 389ef70..ab439cf 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -107,9 +107,6 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 #
 # show_authors = False
 
-# The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = 'friendly'
-
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
diff --git a/Documentation/internals/contributing/documentation-style.rst 
b/Documentation/internals/contributing/documentation-style.rst
index ea41a07..99eec69 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -115,9 +115,11 @@ Titles
 Code
 
 
-- Use ``::``, the ``code`` role or the ``code-block:: `` role to prefix
-  code. The ``code-block:: `` format is preferred as this provides
-  syntax highlighting for non-Python languages, such as Bash or PowerShell.
+- Use ``::`` to prefix code.
+
+- Don't use syntax highlighting such as ``.. highlight:: `` or
+  ``code-block:: `` because it depends on external ``pygments``
+  library.
 
 - Prefix commands with ``$``.
 
@@ -259,7 +261,7 @@ Figures and Other Media
 - All images should be in PNG format and compressed where possible. For PNG
   files, use OptiPNG and AdvanceCOMP's ``advpng``:
 
-  .. code-block:: shell
+  ::
 
  $ optipng -o7 -zm1-9 -i0 -strip all 
  $ advpng -z4 
diff --git a/Documentation/intro/install/windows.rst 
b/Documentation/intro/install/windows.rst
index caa9f40..2be4eb5 100644
--- a/Documentation/intro/install/windows.rst
+++ b/Documentation/intro/install/windows.rst
@@ -63,7 +63,7 @@ The following explains the steps in some detail.
   We require that you have Python six and pypiwin32 libraries installed.
   The libraries can be installed via pip command:
 
-   .. code-block:: console
+   ::
 
   $ pip install six
   $ pip install pypiwin32
@@ -140,7 +140,7 @@ you pulled the sources directly from an Open vSwitch Git 
tree or got a
 Git tree snapshot, then run boot.sh in the top source directory to build
 the "configure" script:
 
-.. code-block:: console
+::
 
$ ./boot.sh
 
@@ -153,7 +153,7 @@ Configure the package by running the configure script.  You 
should provide some
 configure options to choose the right compiler, linker, libraries, Open vSwitch
 component installation directories, etc. For example:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="$(which link)" \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -169,7 +169,7 @@ component installation directories, etc. For example:
 
 To configure with SSL support, add the requisite additional options:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="`which link`"  \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -181,7 +181,7 @@ To configure with SSL support, add the requisite additional 
options:
 
 Finally, to the kernel module also:
 
-.. code-block:: console
+::
 
$ ./configure CC=./build-aux/cccl LD="`which link`" \
LIBS="-lws2_32 -liphlpapi -lwbemuuid -lole32 -loleaut32" \
@@ -211,7 +211,7 @@ building on Linux, FreeBSD, or NetBSD.
 
 #. Run make for the ported executables in the top source directory, e.g.:
 
-   .. code-block:: console
+   ::
 
   $ make
 
@@ -225,25 +225,25 @@ building on Linux, FreeBSD, or NetBSD.
   all MinGW sessions and then run the below command from MSVC developers
   command prompt.:
 
-  .. code-block:: doscon
+  ::
 
  > mingw-get upgrade msys-core-bin=1.0.17-1
 
 #. To run all the unit tests in Open vSwitch, one at a time:
 
-   .. code-block:: console
+   ::
 
   $ make check
 
To run all the unit tests in Open vSwitch, up to 8 in parallel:
 
-   .. code-block:: console
+   ::
 
   $ make check TESTSUITEFLAGS="-j8"
 
 #. To install all the compiled executables on the local machine, run:
 
-   .. code-block:: console
+   ::
 
   $ make install
 
@@ -276,7 +276,7 @@ Now run ``./uninstall.cmd`` to 

Re: [ovs-dev] problem in "make" for openvswitch-2.7.0

[Stephen Finucane]

On Wed, 2017-04-19 at 12:16 +0100, rihab isims wrote:
> Hi,
> 
> I am following the installation guide to install openvswitch-2.7.0
> from
> this link http://docs.openvswitch.org/en/latest/intro/install/general
> /
> however i am blocked at "make" command execution with the following
> error:
> 
> rihab@Lenovo-G500:~/ovs$ make
> make  all-recursive
> make[1]: Entering directory `/home/rihab/ovs'
> Making all in datapath
> make[2]: Entering directory `/home/rihab/ovs/datapath'
> make[3]: Entering directory `/home/rihab/ovs/datapath'
> make[3]: Leaving directory `/home/rihab/ovs/datapath'
> make[2]: Leaving directory `/home/rihab/ovs/datapath'
> make[2]: Entering directory `/home/rihab/ovs'
> make[3]: Entering directory `/home/rihab/ovs/datapath'
> make[3]: `distfiles' is up to date.
> make[3]: Leaving directory `/home/rihab/ovs/datapath'
> sphinx-build  -b html -W -n -d ./Documentation/_build/doctrees
> ./Documentation ./Documentation/_build/html
> Running Sphinx v1.2.2
> Cannot find 'ovs_sphinx' package. Falling back to default theme.
> loading pickled environment... not yet created
> building [html]: targets for 78 source files that are out of date
> updating environment: 78 added, 0 changed, 0 removed
> reading sources... [100%]
> tutorials/ovs-advanced
> 
> looking for now-outdated files... none found
> pickling environment... done
> checking consistency... done
> preparing documents... done
> writing output... [ 46%]
> internals/contributing/documentation-style
> 
> Warning, treated as error:
> /home/rihab/ovs/Documentation/internals/contributing/documentation-
> style.rst:262:
> WARNING: Pygments lexer name u'shell' is not known
> 
> make[2]: *** [htmldocs] Error 1
> make[2]: Leaving directory `/home/rihab/ovs'
> make[1]: *** [all-recursive] Error 1
> make[1]: Leaving directory `/home/rihab/ovs'
> make: *** [all] Error 2

This is an issue caused by an out-of-date Pygments install. It's since
been fixed on master in commit 23cb93f [1].

You should cherry-pick that commit yourself or wait for the patch I
just submitted to fix this to land.

Cheers,
Stephen

[1] https://github.com/openvswitch/ovs/commit/23cb93f
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH ovs] Documentation: fix broken links in maintainers page

[Stephen Finucane]

On Tue, 2017-04-18 at 15:08 +0300, Roi Dayan wrote:
> The links were pointing to static non-existent location instead
> of internal doc link.
> 
> Signed-off-by: Roi Dayan 
> ---
>  MAINTAINERS.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/MAINTAINERS.rst b/MAINTAINERS.rst
> index 28831ab..36c8d58 100644
> --- a/MAINTAINERS.rst
> +++ b/MAINTAINERS.rst
> @@ -29,10 +29,10 @@ Open vSwitch committers are the people who have
> been granted access to push
>  changes to to the Open vSwitch git repository.
>  
>  The responsibilities of an Open vSwitch committer are documented
> -`here `__.
> +:doc:`here `.

I don't think we can do this: these files are in the top-level and as
such are liable to be rendered on GitHub, which doesn't support Sphinx
directives like this. This is mentioned in the documentation guide [1].

We can do this, but be aware it will render funnily on GitHub.
Personally, I think updating the link would be easier.

>  The process for adding or removing committers is documented
> -`here `__.
> +:doc:`here `.

Ditto.

>  This is the current list of Open vSwitch committers:

Cheers,
Stephen

[1] http://docs.openvswitch.org/en/latest/internals/contributing/docume
ntation-style/
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 5/6] doc: Convert ovs-test to rST

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane <step...@that.guru>
> 
> Signed-off-by: Stephen Finucane <step...@that.guru>
> Signed-off-by: Ben Pfaff <b...@ovn.org>

Same comment on the 'Synopsis' section. Other than that, LGTM.

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 6/6] doc: Remove latex output configuration

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane <step...@that.guru>
> 
> We don't care about building LaTeX documentation, so there's no need
> to
> keep this build cruft around.
> 
> Signed-off-by: Stephen Finucane <step...@that.guru>
> Signed-off-by: Ben Pfaff <b...@ovn.org>

Unchanged, but fwiw...

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 4/6] doc: Convert ovs-vlan-test to rST

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane <step...@that.guru>
> 
> Let's start with a simple one that lets us focus on setting up most
> of
> the required "infrastructure" for building man pages using Sphinx.
> 
> This changes the 'check-htmldocs' target to 'check-docs' as its now
> responsible for building man page docs too.
> 
> Other than that, hurrah for (mostly) legible syntaxes.
> 
> [1] http://www.tldp.org/HOWTO/Man-Page/q2.html

This mostly looks good to me. Some comments below but nothing I'd block
on.

Acked-by: Stephen Finucane <step...@that.guru>

> Signed-off-by: Stephen Finucane <step...@that.guru>
> Signed-off-by: Ben Pfaff <b...@ovn.org>
> ---
>  Documentation/automake.mk  |  84
> +--
>  Documentation/conf.py  |   5 +-
>  .../internals/contributing/documentation-style.rst |   3 +-
>  Documentation/intro/install/documentation.rst  |   4 +-
>  Documentation/ref/index.rst|  16 ++-
>  Documentation/ref/ovs-vlan-test.8.rst  | 115
> +
>  debian/openvswitch-switch.manpages |   1 -
>  manpages.mk|  10 --
>  utilities/automake.mk  |   3 -
>  utilities/ovs-vlan-test.8.in   |  96 -
> 
>  10 files changed, 211 insertions(+), 126 deletions(-)
>  create mode 100644 Documentation/ref/ovs-vlan-test.8.rst
>  delete mode 100644 utilities/ovs-vlan-test.8.in
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 9911668c1ca9..762255277102 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -90,7 +90,8 @@ DOC_SOURCE = \
>   Documentation/internals/contributing/documentation-style.rst 
> \
>   Documentation/internals/contributing/libopenvswitch-abi.rst
> \
>   Documentation/internals/contributing/submitting-patches.rst
> \
> - Documentation/requirements.txt
> + Documentation/requirements.txt \
> + $(addprefix Documentation/ref/,$(RST_MANPAGES))
>  
>  EXTRA_DIST += $(DOC_SOURCE)
>  
> @@ -110,20 +111,89 @@ sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_
> V@)
>  sphinx_verbose_0 = -q
>  
>  if HAVE_SPHINX
> -htmldocs-check: $(DOC_SOURCE)
> +docs-check: $(DOC_SOURCE)
>   $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html
> $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html && touch $@
> -ALL_LOCAL += htmldocs-check
> -CLEANFILES += htmldocs-check
> + $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b man
> $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man && touch $@
> +ALL_LOCAL += docs-check
> +CLEANFILES += docs-check
>  
>  check-docs:
>   $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS)
> $(SPHINXBUILDDIR)/linkcheck
>  
>  clean-docs:
> - rm -rf $(SPHINXBUILDDIR)/doctrees
> - rm -rf $(SPHINXBUILDDIR)/html
> - rm -rf $(SPHINXBUILDDIR)/linkcheck
> + rm -rf $(SPHINXBUILDDIR)
>   rm -f docs-check
>  CLEAN_LOCAL += clean-docs
>  endif
>  .PHONY: check-docs
>  .PHONY: clean-docs
> +

I might have done something funky applying this, but I can see a '^L'
character (linefeed?) on this line. Might be worth watching for.

> +# Installing manpages based on rST.
> +#
> +# The docs-check target converts the rST files listed in
> RST_MANPAGES
> +# into nroff manpages in Documentation/_build/man.  The easiest way
> to
> +# get these installed by "make install" is to write our own helper
> +# rules.
> +
> +# rST formatted manpages under Documentation/ref.
> +RST_MANPAGES = \
> + ovs-vlan-test.8.rst
> +
> +# The GNU standards say that these variables should control
> +# installation directories for manpages in each section.  Automake
> +# will define them for us only if it sees that a manpage in the
> +# appropriate section is to be installed through its built-in
> feature.
> +# Since we're working independently, for best safety, we need to
> +# define them ourselves.
> +man1dir = $(mandir)/man1
> +man2dir = $(mandir)/man2
> +man3dir = $(mandir)/man3
> +man4dir = $(mandir)/man4
> +man5dir = $(mandir)/man5
> +man6dir = $(mandir)/man6
> +man7dir = $(mandir)/man7
> +man8dir = $(mandir)/man8
> +man9dir = $(mandir)/man9
> +
> +# Set a shell variable for each manpage directory.
> +set_mandirs = \
> + man1dir='$(man1dir)' \
> + man2dir='$(man2dir)' \
> + man3dir='$(man3dir)' \
> + man4dir='$(man4dir)' \
> + man5dir='$(man5dir)' \
> + man6dir='$(man6dir)' \
> + man7dir='$(man7dir)' \
> + man8dir='$(man8dir)' \
> + man9dir='$

Re: [ovs-dev] [PATCH 3/6] doc: Add man page section to documentation guide

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane <step...@that.guru>
> 
> We also replace 'reST' with the far more common 'rST'.
> 
> Signed-off-by: Stephen Finucane <step...@that.guru>
> Signed-off-by: Ben Pfaff <b...@ovn.org>

This looks unchanged, thus:

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH] doc: Remove cruft from conf.py

[Stephen Finucane]

This file has enough going on as-is without keeping all this commented
out noise around.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 Documentation/conf.py | 248 --
 1 file changed, 248 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 49514ec..bfdce97 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -15,13 +15,6 @@
 import string
 import sys
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 try:
 import ovs_sphinx_theme
 use_ovs_theme = True
@@ -49,10 +42,6 @@ templates_path = ['_templates']
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
-# The encoding of source files.
-#
-# source_encoding = 'utf-8-sig'
-
 # The master toctree document.
 master_doc = 'contents'
 
@@ -86,55 +75,11 @@ if release is None:
 # closer to 2.8 than to 2.7), so check for that.
 version = release if '.90' in release else '.'.join(release.split('.')[0:2])
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#
-# today = ''
-#
-# Else, today_fmt is used as the format for a strftime call.
-#
-# today_fmt = '%B %d, %Y'
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#
-# show_authors = False
-
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
 # If true, check the validity of #anchors in links.
 linkcheck_anchors = False
 
@@ -148,183 +93,22 @@ if use_ovs_theme:
 else:
 html_theme = 'default'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
 # Add any paths that contain custom themes here, relative to this directory.
 if use_ovs_theme:
 html_theme_path = [ovs_sphinx_theme.get_theme_dir()]
 else:
 html_theme_path = []
 
-# The name for this set of Sphinx documents.
-# " v documentation" by default.
-#
-# html_title = u'Open vSwitch v2.6.0'
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#
-# html_short_title = None
-
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #
 html_logo = '_static/logo.png'
 
-# The name of an image file (relative to this directory) to use as a favicon of
-# the docs.  This file should be a Windows icon file (.ico) being 16x16 or
-# 32x32 pixels large.
-#
-# html_favicon = None
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#
-# html_extra_path = []
-
-# If not None, a 'Last updated on:' timestamp is inserted at every page
-# bottom, using the given strftime format.
-# The empty string is equivalent to '%b %d, %Y'.
-#
-# html_last_updated_fmt = None
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page

[ovs-dev] [PATCH] doc: Don't override default theme

[Stephen Finucane]

Sphinx 1.3 renamed the 'default' theme to 'classic' and configured the
'alabaster' theme as the new default. To prevent breaking existing
builds, the 'default' name was reserved as an alias for 'classic' [1].
However, initially this raised a warning [1] with a message to use
'classic' instead. This warning was removed in 1.3.2 [2], but it will
result in errors (due to the use of the '-W' flag) for Sphinx 1.3.0 and
1.3.1 users.

Mitigate the issue by not setting a theme if the 'ovs_sphinx_theme'
package is absent. This will result in Sphinx using its default theme,
be that 'classic' (Sphinx < 1.3) or 'alabaster'.

[1] https://github.com/sphinx-doc/sphinx/commit/68021b0bd
[2] https://github.com/sphinx-doc/sphinx/commit/034c4e942

Signed-off-by: Stephen Finucane <step...@that.guru>
Cc: Matthew Thode <mth...@mthode.org>
---
We might want to backport this if there are any releases with the Sphinx
docs present.
---
 Documentation/conf.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 49514ec..97f402e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -145,8 +145,6 @@ linkcheck_anchors = False
 #
 if use_ovs_theme:
 html_theme = 'ovs'
-else:
-html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
-- 
2.9.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] doc: fix doc build when not using ovs theme

[Stephen Finucane]

On Mon, 2017-04-17 at 10:21 -0700, Ben Pfaff wrote:
> On Mon, Apr 17, 2017 at 11:47:30AM -0500, Matthew Thode wrote:
> > On 04/17/2017 11:42 AM, Ben Pfaff wrote:
> > > On Mon, Apr 17, 2017 at 11:32:13AM -0500, Matthew Thode wrote:
> > > > On 04/17/2017 11:20 AM, Ben Pfaff wrote:
> > > > > On Mon, Apr 17, 2017 at 10:36:26AM -0500, Matthew Thode via
> > > > > dev wrote:
> > > > > > Fixes the following warning.
> > > > > > 
> > > > > > WARNING: 'default' html theme has been renamed to
> > > > > > 'classic'. Please change your
> > > > > > html_theme setting either to the new 'alabaster' default
> > > > > > theme, or to 'classic'
> > > > > > to keep using the old default.
> > > > > > 
> > > > > > As reported by https://bugs.gentoo.org/show_bug.cgi?id=6145
> > > > > > 20
> > > > > > 
> > > > > > Signed-off-by: Matthew Thode 
> > > > > 
> > > > > Thanks.  Do you know whether this is going to break the docs
> > > > > build for
> > > > > people with older sphinx?  That is, was "classic" introduced
> > > > > in sphinx
> > > > > sometime after 1.1 (since that's the current minimum version
> > > > > for OVS)?
> > > > > 
> > > > 
> > > > I'm not sure, the oldest version we have is 1.11.0, and the
> > > > oldest
> > > > stable version we support is 2.5.0.  This is the first I've
> > > > seen this
> > > > bug reported though.
> > > 
> > > I guess that you are talking about OVS versions, but I'm asking
> > > about
> > > Sphinx versions.  Does that make any difference?  I don't know
> > > Sphinx
> > > well at all.
> > > 
> > 
> > I was talking about OVS versions.  This code change only changes
> > anything if sphinx is not installed.
> > 
> > try:
> > import ovs_sphinx_theme
> > use_ovs_theme = True
> > except ImportError:
> > print("Cannot find 'ovs_sphinx' package. Falling back to
> > default
> > theme.")
> > use_ovs_theme = False
> > 
> > then
> > 
> > if use_ovs_theme:
> > html_theme = 'ovs'
> > else:
> > html_theme = 'default'
> 
> This code only runs at all if sphinx is installed, since it's
> sphinx-build that runs it.  The conditional is whether the OVS sphinx
> theme is installed.
> 
> My question is, what version of Sphinx (not OVS, not the OVS sphinx
> theme) introduced a theme named "classic"?  If it is newer than the
> oldest version of Sphinx that OVS requires, then this patch will
> break
> things and we will need to make a choice:
> 
> 1. Refine the patch to use "default" if "classic" is not
>    available.
> 
> 2. Live with the warning.
> 
> 3. Increase OVS's minimum required Sphinx version.

It would appear this was a feature introduced in Sphinx 1.3.0 [1][2],
but which was reverted in Sphinx 1.3.2 [3][4]. We should handle this
but if we simply rename 'default' to 'classic' then we will break
support for Sphinx 1.1 and 1.2 users.

My suggestion would be to simply remove the 'else' clause. This will
cause Sphinx to use it's own default (alabaster in recent releases,
default/classic before that) when the 'ovs_sphinx_theme' package is not
available. I didn't do this before because the 'alabaster' theme is a
little too sparse for my liking but if it fixes issues for some folks
then I'm sure I can live with it :) I'll submit a patch shortly that
will do just this.

Stephen

PS: If you're using a package then you might want to talk to the
maintainers of said package: 1.3.2 was released over 2 years ago and
should really be in use by now.

[1] https://github.com/sphinx-doc/sphinx/blob/1.3/sphinx/theming.py#L10
4-L108
[2] https://github.com/sphinx-doc/sphinx/commit/68021b0b
[3] https://github.com/sphinx-doc/sphinx/blob/1.3.2/sphinx/theming.py#L
104-L110
[3] https://github.com/sphinx-doc/sphinx/commit/034c4e94

> Thanks,
> 
> Ben.
> ___
> dev mailing list
> d...@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

[Stephen Finucane]

On Fri, 2017-04-14 at 12:49 -0700, Ben Pfaff wrote:
> On Fri, Apr 14, 2017 at 06:55:38PM +0100, Stephen Finucane wrote:
> > On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> > > Thank you!  rST is much more readable than nroff.  I have some
> > > comments
> > > below.
> > > 
> > > On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > > > Let's start with a simple one that lets us focus on setting up
> > > > most
> > > > of the required "infrastructure" for building man pages using
> > > > Sphinx.
> > > > 
> > > > There are a couple of things worth noting here:
> > > > 
> > > > - The 'check-htmldocs' target becomes 'check-docs' as its now
> > > >   responsible for building man page docs too.
> > > > 
> > > > - The outputted file will always have a '.1' suffix. This is 
> > > > Sphinx's
> > > >   decision, and likely stems from the man page guidelines [1]
> > > > which
> > > >   state that "the name of the man page's source file...is the
> > > > name
> > > > of
> > > >   the command, function or file name, followed by a dot,
> > > > followed
> > > > by the
> > > >   section character".
> > > 
> > > It looks to me like the last element of the tuples inside
> > > man_pages
> > > in conf.py controls the section.  When I changed 1 to 8 there, it
> > > switched the manpage to section 8.  So I made that change in
> > > conf.py
> > > and I removed the above paragraph from the commit message.
> > > 
> > > > Other than that, hurrah for (mostly) legible syntaxes.
> > > > 
> > > > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > > > 
> > > > Signed-off-by: Stephen Finucane <step...@that.guru>
> > > > ---
> > > > I don't know if this is correctly integrated into the docs
> > > > build
> > > > system or not. I need someone to double check this for me. In
> > > > particular, I think I need to integrate the 'dh_sphinxdoc'
> > > > package
> > > > [2] into the Debian build but I've no idea how to.
> > > > 
> > > > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc
> > > > .1.h
> > > > tml
> > > 
> > > I spent a couple of hours working on the build and install system
> > > here.
> > > 
> > > My first thought was to add rules to allow Automake to find and
> > > install the generated manpages.  This turned out to be a huge
> > > mess
> > > that required tons of nasty GNU Make specific crap in the
> > > makefiles,
> > > and I didn't like it.
> > > 
> > > My second approach was better.  I gave up on integrating with the
> > > builtin Automake rules for manpages.  All those really do anyway
> > > is
> > > handle install and uninstall, so I wrote some Make rules to do
> > > that.
> > > They're ugly because they're make+shell, but readable enough if
> > > you
> > > squint.
> > > 
> > > The main question for install and uninstall is how to choose the
> > > right section.  The easiest way seems to be to give the .rst
> > > files
> > > names that embed the section, like "ovs-vlan-test.8.rst".  This
> > > is
> > > also handy to distinguish manpages with the same name but in
> > > different sections, which is sometimes a reasonable thing to
> > > have, so
> > > that's what I did.
> > 
> > I still need to have a look into the patch (anything to do with
> > autotools is generally worth avoiding, heh), but I had a crazy idea
> > over the weekend: couldn't we just include the compiled man pages
> > in
> > the source? The only issue with this would be the '.TH' line, but
> > there
> > are solutions for avoiding this [1][2]. If we have man pages
> > included
> > in the source, would that be adequate to use the standard autotools
> > setup for manpages?
> 
> I might not understand this idea yet.  Do you mean, to include the
> nroff output of sphinx in the Git repository?  I don't know why this
> would help.

Correct.

> I'm not sure there are any serious disadvantages to writing Make
> rules to install and uninstall manpages.

The only significant advantage would be simplicity for use in other
build systems. Would the rules you've proposed work for the Debian and
RHEL packaging, for example?

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 3/3] doc: Remove some link targets that aren't used anywhere.

[Stephen Finucane]

On Fri, 2017-04-14 at 10:31 -0700, Ben Pfaff wrote:
> It seems that there's a style here that every title has a separate
> link
> target even if it's never used.  Maybe there is some reason for that
> (maybe
> it should be explained in the documentation style document?), but if
> not
> then it seems reasonable to leave out the unused ones since they look
> to
> me like just visual clutter.
> 
> Signed-off-by: Ben Pfaff <b...@ovn.org>

Acked-by: Stephen Finucane <step...@that.guru>

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

[Stephen Finucane]

On Thu, 2017-04-13 at 21:27 -0700, Ben Pfaff wrote:
> Thank you!  rST is much more readable than nroff.  I have some
> comments
> below.
> 
> On Mon, Apr 10, 2017 at 01:12:28PM +0100, Stephen Finucane wrote:
> > Let's start with a simple one that lets us focus on setting up most
> > of the required "infrastructure" for building man pages using
> > Sphinx.
> > 
> > There are a couple of things worth noting here:
> > 
> > - The 'check-htmldocs' target becomes 'check-docs' as its now
> >   responsible for building man page docs too.
> > 
> > - The outputted file will always have a '.1' suffix. This is 
> > Sphinx's
> >   decision, and likely stems from the man page guidelines [1] which
> >   state that "the name of the man page's source file...is the name
> > of
> >   the command, function or file name, followed by a dot, followed
> > by the
> >   section character".
> 
> It looks to me like the last element of the tuples inside man_pages
> in conf.py controls the section.  When I changed 1 to 8 there, it
> switched the manpage to section 8.  So I made that change in conf.py
> and I removed the above paragraph from the commit message.
> 
> > Other than that, hurrah for (mostly) legible syntaxes.
> > 
> > [1] http://www.tldp.org/HOWTO/Man-Page/q2.html
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > ---
> > I don't know if this is correctly integrated into the docs build
> > system or not. I need someone to double check this for me. In
> > particular, I think I need to integrate the 'dh_sphinxdoc' package
> > [2] into the Debian build but I've no idea how to.
> > 
> > [2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.h
> > tml
> 
> I spent a couple of hours working on the build and install system
> here.
> 
> My first thought was to add rules to allow Automake to find and
> install the generated manpages.  This turned out to be a huge mess
> that required tons of nasty GNU Make specific crap in the makefiles,
> and I didn't like it.
> 
> My second approach was better.  I gave up on integrating with the
> builtin Automake rules for manpages.  All those really do anyway is
> handle install and uninstall, so I wrote some Make rules to do that.
> They're ugly because they're make+shell, but readable enough if you
> squint.
> 
> The main question for install and uninstall is how to choose the
> right section.  The easiest way seems to be to give the .rst files
> names that embed the section, like "ovs-vlan-test.8.rst".  This is
> also handy to distinguish manpages with the same name but in
> different sections, which is sometimes a reasonable thing to have, so
> that's what I did.

I still need to have a look into the patch (anything to do with
autotools is generally worth avoiding, heh), but I had a crazy idea
over the weekend: couldn't we just include the compiled man pages in
the source? The only issue with this would be the '.TH' line, but there
are solutions for avoiding this [1][2]. If we have man pages included
in the source, would that be adequate to use the standard autotools
setup for manpages?

> The patch didn't delete the old manpage, so I did that too.
> 
> I noticed that the "Synposis" section of the new ovs-vlan-test.rst
> did not use bold and italic in the canonical way for manpages, so I
> added * and ** in the right places.

++

Stephen

[1] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/Makefile.am#L
149-158
[2] https://gitlab.labs.nic.cz/labs/knot/blob/bab62de/doc/man/kdig.1in
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH 2/6] doc: Avoid need to generate conf.py.

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> It's awkward to have to at the same time generate conf.py from
> conf.py.in
> and to keep both versions in the repository.  This avoids the issue.
> 
> Signed-off-by: Ben Pfaff <b...@ovn.org>
> ---
>  Documentation/automake.mk |  10 --
>  Documentation/conf.py |  23 ++-
>  Documentation/conf.py.in  | 349 
> --
>  3 files changed, 19 insertions(+), 363 deletions(-)
>  delete mode 100644 Documentation/conf.py.in
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index ec60e0b1e831..9911668c1ca9 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -3,7 +3,6 @@ DOC_SOURCE = \
>   Documentation/_static/logo.png \
>   Documentation/_static/overview.png \
>   Documentation/conf.py \
> - Documentation/conf.py.in \
>   Documentation/index.rst \
>   Documentation/contents.rst \
>   Documentation/intro/index.rst \
> @@ -125,15 +124,6 @@ clean-docs:
>   rm -rf $(SPHINXBUILDDIR)/linkcheck
>   rm -f docs-check
>  CLEAN_LOCAL += clean-docs
> -
> -ALL_LOCAL += $(srcdir)/Documentation/conf.py
> -$(srcdir)/Documentation/conf.py: $(srcdir)/Documentation/conf.py.in
> - $(AM_V_GEN)($(ro_shell) && sed -e
> 's,[@]VERSION[@],$(VERSION),g' \
> - -e 's,[@]OVS_MAJOR[@],$(shell echo $(VERSION) | cut
> -f1 -d.),g' \
> - -e 's,[@]OVS_MINOR[@],$(shell echo $(VERSION) | cut
> -f2 -d.),g') \
> - < $(srcdir)/Documentation/$(@F).in > $(@F).tmp ||
> exit 1; \
> - if cmp -s $(@F).tmp $@; then touch $@; rm $(@F).tmp; else mv
> $(@F).tmp $@; fi
> -
>  endif
>  .PHONY: check-docs
>  .PHONY: clean-docs
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index ae672cbe7b0d..bfd7f33d88ba 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -1,4 +1,3 @@
> -# Generated automatically -- do not modify!-*- buffer-read-only: 
> t -*-
>  # -*- coding: utf-8 -*-
>  #
>  # Open vSwitch documentation build configuration file, created by
> @@ -63,10 +62,26 @@ author = u'The Open vSwitch Development
> Community'
>  # |version| and |release|, also used in various other places
> throughout the
>  # built documents.
>  #
> +import string
> +import sys
> +def get_release():
> +filename = "../configure.ac"
> +with open(filename, 'rU') as f:
> +for line in f:
> +if 'AC_INIT' in line:
> +# Parse "AC_INIT(openvswitch, 2.7.90, bugs@openvswit
> ch.org)":
> +return line.split(',')[1].strip(string.whitespace +
> '[]')
> +sys.stderr.write('%s: failed to determine Open vSwitch
> version\n'
> + % filename)
> +sys.exit(1)
> +release = get_release() # The full version, including alpha/beta/rc
> tags 
> +
>  # The short X.Y version.
> -version = u'2.7'
> -# The full version, including alpha/beta/rc tags.
> -release = u'2.7.90'
> +#
> +# However, it's important to know the difference between, e.g., 2.7
> +# and 2.7.90, which can be very different versions (2.7.90 may be
> much
> +# closer to 2.8 than to 2.7), so check for that.
> +version = release if '.90' in release else
> '.'.join(release.split('.')[0:2])

nit: You probably don't need to have this as a function. Might also
want to run it through pep8/flake8. Other than that though, lgtm.

Acked-by: Stephen Finucane <step...@that.guru>

>  # The language for content autogenerated by Sphinx. Refer to
> documentation
>  # for a list of supported languages.
> diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in
> deleted file mode 100644
> index 5ed7006228f2..
> --- a/Documentation/conf.py.in
> +++ /dev/null
> @@ -1,349 +0,0 @@
> -# -*- coding: utf-8 -*-
> -#
> -# Open vSwitch documentation build configuration file, created by
> -# sphinx-quickstart on Fri Sep 30 09:57:36 2016.
> -#
> -# This file is execfile()d with the current directory set to its
> -# containing dir.
> -#
> -# Note that not all possible configuration values are present in
> this
> -# autogenerated file.
> -#
> -# All configuration values have a default; values that are commented
> out
> -# serve to show the default.
> -
> -# If extensions (or modules to document with autodoc) are in another
> directory,
> -# add these directories to sys.path here. If the directory is
> relative to the
> -# documentation root, use os.path.abspath to make it absolute, like
> shown here.
> -#
> -# import os
> -# import sys
> -# sys.path.insert(0, os.path.abspath('.'))
> -try:
> -imp

Re: [ovs-dev] [PATCH 1/6] doc: Also delete stamp file in clean-docs target.

[Stephen Finucane]

On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> Otherwise "make docs-check" won't necessarily do anything since its
> apparent target is up to date.
> 
> Signed-off-by: Ben Pfaff <b...@ovn.org>

Acked-by: Stephen Finucane <step...@that.guru>
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Automatically extract version from NEWS

[Stephen Finucane]

On Thu, 2017-04-13 at 11:22 -0700, Ben Pfaff wrote:
> On Wed, Apr 12, 2017 at 12:32:24PM +0100, Stephen Finucane wrote:
> > Parse the version and release from the NEWS file. This looks a bit
> > hacky, but the NEWS file is generally well formatted and should be
> > reliable enough for our purposes.
> > 
> > Signed-off-by: Stephen Finucane <step...@that.guru>
> > Cc: Russell Bryant <russ...@ovn.org>
> > ---
> > I took a look through the 'git history' of NEWS and could spot no
> > other
> > formatting types for headers. Lemme know if I got this wrong
> > though.
> 
> The canonical place to get this is the AC_INIT line in configure.ac:
> AC_INIT(openvswitch, 2.7.90, b...@openvswitch.org)
> e.g. with:
> autom4te -l Autoconf -t 'AC_INIT:$2' configure.ac
> although that does assume that Autoconf is installed and so we can't
> use it unless we make that a (new) requirement.

Yeah, I think Russell's patch effectively covers this. You can ignore
this patch now.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Stephen Finucane]

On Wed, 2017-04-12 at 08:58 -0400, Russell Bryant wrote:
> On Wed, Apr 12, 2017 at 7:29 AM, Stephen Finucane <step...@that.guru>
> wrote:
> > On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
> > > Update the version numbers in the documentation config to reflect
> > > 2.7.90
> > > instead of 2.6.0.
> > > 
> > > This patch also updates the build system to automatically update
> > > this
> > > file.
> > > conf.py is now a generated file from conf.py.in.  We still
> > > include
> > > conf.py
> > > in the tree because it's needed for the docs to be automatically
> > > generated
> > > for docs.openvswitch.org.
> > > 
> > > Signed-off-by: Russell Bryant <russ...@ovn.org>
> > 
> > Looks OK, but how would we prevent this getting out of date? If
> > we're
> > going to include PATCH information, I imagine this would need to be
> > updated as part of every commit?
> 
> It doesn't change with every commit.  ".90" is fixed.  "2.7.90" is
> the
> version OVS uses for the master branch that will eventually become
> 2.8.

I realized that about 10 minutes ago after diving further into the git
history of NEWS :) Why '.90' , out of curiosity?

> In terms of keeping it up to date, conf.py is going to show a change
> as soon as the version changes, but it should only be when a new
> branch gets created, or after a point release is made from a release
> branch.

Gotcha.

> > Seeing as a more generic version of this information is already
> > available in 'NEWS', I imagine we could just parse that instead.
> > Lemme
> > draft something quickly and see what you think.
> 
> Cool, I'll take a look.

Given the above, what I've done works but it likely unnecessary. Unless
we want to update the version in real time (by parsing git logs using
dulwich or similar), this solution is probably more consistent with
OVS' build system. As such:

Acked-by: Stephen Finucane <step...@that.guru>

Cheers :)
Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] docs: Update version numbers in doc config.

[Stephen Finucane]

On Tue, 2017-04-11 at 13:15 -0400, Russell Bryant wrote:
> Update the version numbers in the documentation config to reflect
> 2.7.90
> instead of 2.6.0.
> 
> This patch also updates the build system to automatically update this
> file.
> conf.py is now a generated file from conf.py.in.  We still include
> conf.py
> in the tree because it's needed for the docs to be automatically
> generated
> for docs.openvswitch.org.
> 
> Signed-off-by: Russell Bryant 

Looks OK, but how would we prevent this getting out of date? If we're
going to include PATCH information, I imagine this would need to be
updated as part of every commit?

Seeing as a more generic version of this information is already
available in 'NEWS', I imagine we could just parse that instead. Lemme
draft something quickly and see what you think.

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [PATCH v2] doc: Link to release FAQ from DPDK install guide

[Stephen Finucane]

I wanted to find the mappings of DPDK versions to OVS versions. This was
a little more difficult than expected. Resolve the issue by linking to
it from the DPDK install guide.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
v2:
- Add a link to the releases FAQ from the installation section of the
  index page
---
 Documentation/index.rst  | 3 ++-
 Documentation/intro/install/dpdk.rst | 5 +
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index d81e9ba..5210a56 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -58,7 +58,8 @@ vSwitch? Start here.
   :doc:`intro/install/netbsd` |
   :doc:`intro/install/windows` |
   :doc:`intro/install/xenserver` |
-  :doc:`intro/install/dpdk`
+  :doc:`intro/install/dpdk` |
+  :doc:`Installation FAQs `
 
 - **Tutorials:** :doc:`tutorials/ovs-advanced` |
   :doc:`tutorials/ovn-sandbox`
diff --git a/Documentation/intro/install/dpdk.rst 
b/Documentation/intro/install/dpdk.rst
index b947bd5..f29ac05 100644
--- a/Documentation/intro/install/dpdk.rst
+++ b/Documentation/intro/install/dpdk.rst
@@ -29,6 +29,11 @@ This document describes how to build and install Open 
vSwitch using a DPDK
 datapath. Open vSwitch can use the DPDK library to operate entirely in
 userspace.
 
+.. seealso::
+
+The :doc:`releases FAQ ` lists support for the required
+versions of DPDK for each version of Open vSwitch.
+
 Build requirements
 --
 
-- 
2.9.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH] doc: Link to release FAQ from DPDK install guide

[Stephen Finucane]

On Fri, 2017-04-07 at 15:28 +, Darrell Ball wrote:
> 
> On 4/7/17, 6:58 AM, "ovs-dev-boun...@openvswitch.org on behalf of
> Stephen Finucane" <ovs-dev-boun...@openvswitch.org on behalf of steph
> e...@that.guru> wrote:
> 
> I wanted to find the mappings of DPDK versions to OVS versions.
> This was
> a little more difficult than expected. Resolve the issue by
> linking to
> it from the DPDK install guide.
> 
> Signed-off-by: Stephen Finucane <step...@that.guru>
> ---
>  Documentation/intro/install/dpdk.rst | 5 +
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/intro/install/dpdk.rst
> b/Documentation/intro/install/dpdk.rst
> index b947bd5..f29ac05 100644
> --- a/Documentation/intro/install/dpdk.rst
> +++ b/Documentation/intro/install/dpdk.rst
> @@ -29,6 +29,11 @@ This document describes how to build and
> install Open vSwitch using a DPDK
>  datapath. Open vSwitch can use the DPDK library to operate
> entirely in
>  userspace.
>  
> +.. seealso::
> +
> +The :doc:`releases FAQ ` lists support for
> the required
> +versions of DPDK for each version of Open vSwitch.
> +
> 
> If it is not intuitive to follow the path 
> Open vswitch Documentation -> FAQ -> Releases, 
> then perhaps it means
> “Releases” should also be linked at the same level as Installation
> Guides, Tutorials etc
> Releases is really one of first high topics people are interested in.

That would apply if you're navigating the docs from '/' and I see merit
in doing that. I'll reroll a v2 shortly. However, this wouldn't help
users navigating to the page from Google (like I was) and I think we
should keep this change itself.

> 
>  Build requirements
>  --
>  
> -- 
> 2.9.3
> 

Stephen
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [RFC 1/4] doc: Add man page section to documentation guide

[Stephen Finucane]

We also replace 'reST' with the far more common 'rST'.

Signed-off-by: Stephen Finucane <step...@that.guru>
---
 .../internals/contributing/documentation-style.rst | 84 +++---
 1 file changed, 76 insertions(+), 8 deletions(-)

diff --git a/Documentation/internals/contributing/documentation-style.rst 
b/Documentation/internals/contributing/documentation-style.rst
index 9fe473c..0ba5e54 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -41,17 +41,17 @@ documents found in the project tree.
 reStructuredText vs. Sphinx
 ---
 
-`reStructuredText (reST)`__ is the syntax, while `Sphinx`__ is a documentation
-generator.  Sphinx introduces a number of extensions to reST, like the
-``:ref:`` role, which can and should be used in documentation, but these will
-not work correctly on GitHub. As such, these extensions should not be used in
-any documentation in the root level, such as the ``README``.
+`reStructuredText (rST)`__ is the syntax, while `Sphinx`__ is a documentation
+generator.  Sphinx introduces a number of extensions to rST, like the ``:ref:``
+role, which can and should be used in documentation, but these will not work
+correctly on GitHub. As such, these extensions should not be used in any
+documentation in the root level, such as the ``README``.
 
 __ http://docutils.sourceforge.net/rst.html
 __ http://www.sphinx-doc.org/
 
-reST Conventions
-
+rST Conventions
+---
 
 Basics
 ~~
@@ -59,7 +59,7 @@ Basics
 Many of the basic documentation guidelines match those of the
 :doc:`coding-style`.
 
-- Use reStructuredText (reST) for all documentation.
+- Use reStructuredText (rST) for all documentation.
 
   Sphinx extensions can be used, but only for documentation in the
   ``Documentation`` folder.
@@ -90,6 +90,12 @@ File Names
 
 - Use hyphens as space delimiters. For example: ``my-readme-document.rst``
 
+  .. note::
+
+ An exception to this rule is any man pages, which take an trailing number
+ corresponding to the number of arguments required. This number is preceded
+ by an underscore.
+
 - Use lowercase filenames.
 
   .. note::
@@ -285,6 +291,68 @@ Comments
   .. TODO(stephenfin) This section needs some work. This TODO will not
  appear in the final generated document, however.
 
+Man Pages
+-
+
+In addition to the above, man pages have some specific requirements:
+
+- You **must** define the following sections:
+
+  - Synopsis
+
+  - Description
+
+  - Options
+
+  Note that `NAME` is not included - this is automatically generated by Sphinx
+  and should not be manually defined. Also note that these do not need to be
+  uppercase - Sphinx will do this automatically.
+
+  Additional sections are allowed. Refer to `man-pages(8)` for information on
+  the sections generally allowed.
+
+- You **must not** define a `NAME` section.
+
+  See above.
+
+- The `OPTIONS` section must describe arguments and options using the
+  `program`__ and `option`__ directives.
+
+  This ensures the output is formatted correctly and that you can
+  cross-reference various programs and commands from the documentation. For
+  example::
+
+  .. program:: ovs-do-something
+
+  .. option:: -f, --force
+
+  Force the operation
+
+  .. option:: -b , --bridge 
+
+  Name or ID of bridge
+
+  .. important::
+
+ Option argument names should be enclosed in angle brackets, as above.
+
+- Any references to the application or any other Open vSwitch application must
+  be marked up using the `program` role.
+
+  This allows for easy linking in the HTML output and correct formatting in the
+  man page output. For example::
+
+  To do something, run :program:`ovs-do-something`.
+
+- The man page must be included in the list of man page documents found in
+  `conf.py`__
+
+Refer to existing man pages for worked examples.
+
+__ http://www.sphinx-doc.org/en/stable/domains.html#directive-program
+__ http://www.sphinx-doc.org/en/stable/domains.html#directive-option
+__ http://www.sphinx-doc.org/en/stable/config.html#confval-man_pages
+
 Writing Style
 -
 
-- 
2.9.3

___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

[ovs-dev] [RFC 3/4] doc: Convert ovs-test to rST

[Stephen Finucane]

Signed-off-by: Stephen Finucane <step...@that.guru>
---
See comment on the previous change
---
 Documentation/automake.mk   |   2 +
 Documentation/conf.py   |   3 +
 Documentation/ref/index.rst |   1 +
 Documentation/ref/ovs-test.rst  | 165 
 Documentation/ref/ovs-vlan-test.rst |  11 +--
 debian/openvswitch-test.manpages|   1 -
 manpages.mk |  10 ---
 utilities/automake.mk   |   3 -
 8 files changed, 175 insertions(+), 21 deletions(-)
 create mode 100644 Documentation/ref/ovs-test.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 2d62a6a..7b6de65 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -90,6 +90,7 @@ DOC_SOURCE = \
Documentation/internals/contributing/libopenvswitch-abi.rst \
Documentation/internals/contributing/submitting-patches.rst \
Documentation/ref/index.rst \
+   Documentation/ref/ovs-test.rst \
Documentation/ref/ovs-vlan-test.rst \
Documentation/requirements.txt
 
@@ -118,6 +119,7 @@ ALL_LOCAL += docs-check
 CLEANFILES += docs-check
 
 man_MANS += \
+   $(SPHINXBUILDDIR)/man/ovs-test.1 \
$(SPHINXBUILDDIR)/man/ovs-vlan-test.1
 
 check-docs:
diff --git a/Documentation/conf.py b/Documentation/conf.py
index e40302c..28008ed 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -312,6 +312,9 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
+('ref/ovs-test', 'ovs-test',
+ u'Check Linux drivers for performance, vlan and L3 tunneling problems',
+ [author], 1),
 ('ref/ovs-vlan-test', 'ovs-vlan-test',
  u'Check Linux drivers for problems with vlan traffic',
  [author], 1)
diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst
index 1e0d413..635f4df 100644
--- a/Documentation/ref/index.rst
+++ b/Documentation/ref/index.rst
@@ -39,6 +39,7 @@ time:
 .. toctree::
:maxdepth: 3
 
+   ovs-test
ovs-vlan-test
 
 The remainder are still in roff format can be found below:
diff --git a/Documentation/ref/ovs-test.rst b/Documentation/ref/ovs-test.rst
new file mode 100644
index 000..164068d
--- /dev/null
+++ b/Documentation/ref/ovs-test.rst
@@ -0,0 +1,165 @@
+
+ovs-test
+
+
+Synopsis
+
+
+::
+
+ovs-test -s port
+
+ovs-test -c server1 server2 [-b targetbandwidth] [-i testinterval] [-d]
+  [-l vlantag] [-t tunnelmodes]
+
+Description
+===
+
+The :program:`ovs-test` program may be used to check for problems sending
+802.1Q or GRE traffic that Open vSwitch may uncover. These problems, for
+example, can occur when Open vSwitch is used to send 802.1Q traffic through
+physical interfaces running certain drivers of certain Linux kernel versions.
+To run a test, configure IP addresses on `server1` and `server2` for interfaces
+you intended to test. These interfaces could also be already configured OVS
+bridges that have a physical interface attached to them. Then, on one of the
+nodes, run :program:`ovs-test` in server mode and on the other node run it in
+client mode. The client will connect to :program:`ovs-test` server and schedule
+tests between both of them. The :program:`ovs-test` client will perform UDP and
+TCP tests.
+
+UDP tests can report packet loss and achieved bandwidth for various datagram
+sizes. By default target bandwidth for UDP tests is 1Mbit/s.
+
+TCP tests report only achieved bandwidth, because kernel TCP stack takes care
+of flow control and packet loss. TCP tests are essential to detect potential
+TSO related issues.
+
+To determine whether Open vSwitch is encountering any problems, the user must
+compare packet loss and achieved bandwidth in a setup where traffic is being
+directly sent and in one where it is not. If in the 802.1Q or L3 tunneled tests
+both :program:`ovs-test` processes are unable to communicate or the achieved
+bandwidth is much lower compared to direct setup, then, most likely, Open
+vSwitch has encountered a pre-existing kernel or driver bug.
+
+Some examples of the types of problems that may be encountered are:
+
+- When NICs use VLAN stripping on receive they must pass a pointer to a
+  `vlan_group` when reporting the stripped tag to the networking core. If no
+  `vlan_group` is in use then some drivers just drop the extracted tag.
+  Drivers are supposed to only enable stripping if a `vlan_group` is registered
+  but not all of them do that.
+
+- On receive, some drivers handle priority tagged packets specially and don't
+  pass the tag onto the network stack at all, so Open vSwitch never has a
+  chance to see it.
+
+- Some drivers size their receive buffers based on whether a `vlan_group` is
+  enabled, meaning that a maximum size packet with a VLAN tag will not fit if
+  no `vlan_group` is configured.
+
+- On transmit, some drivers expect tha

[ovs-dev] [RFC 2/4] doc: Convert ovs-vlan-test to rST

[Stephen Finucane]

Let's start with a simple one that lets us focus on setting up most of
the required "infrastructure" for building man pages using Sphinx.

There are a couple of things worth noting here:

- The 'check-htmldocs' target becomes 'check-docs' as its now
  responsible for building man page docs too.

- The outputted file will always have a '.1' suffix. This is Sphinx's
  decision, and likely stems from the man page guidelines [1] which
  state that "the name of the man page's source file...is the name of
  the command, function or file name, followed by a dot, followed by the
  section character".

Other than that, hurrah for (mostly) legible syntaxes.

[1] http://www.tldp.org/HOWTO/Man-Page/q2.html

Signed-off-by: Stephen Finucane <step...@that.guru>
---
I don't know if this is correctly integrated into the docs build system
or not. I need someone to double check this for me. In particular, I
think I need to integrate the 'dh_sphinxdoc' package [2] into the Debian
build but I've no idea how to.

[2] http://manpages.ubuntu.com/manpages/zesty/man1/dh_sphinxdoc.1.html
---
 Documentation/automake.mk  |  17 +--
 Documentation/conf.py  |   3 +-
 .../internals/contributing/documentation-style.rst |   3 +-
 Documentation/intro/install/documentation.rst  |   4 +-
 Documentation/ref/index.rst|  16 ++-
 Documentation/ref/ovs-vlan-test.rst| 117 +
 debian/openvswitch-switch.manpages |   1 -
 manpages.mk|  10 --
 utilities/automake.mk  |   3 -
 9 files changed, 145 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/ref/ovs-vlan-test.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 1fd452b..2d62a6a 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -59,7 +59,6 @@ DOC_SOURCE = \
Documentation/howto/vlan.png \
Documentation/howto/vlan.rst \
Documentation/howto/vtep.rst \
-   Documentation/ref/index.rst \
Documentation/faq/index.rst \
Documentation/faq/configuration.rst \
Documentation/faq/contributing.rst \
@@ -90,6 +89,8 @@ DOC_SOURCE = \
Documentation/internals/contributing/documentation-style.rst \
Documentation/internals/contributing/libopenvswitch-abi.rst \
Documentation/internals/contributing/submitting-patches.rst \
+   Documentation/ref/index.rst \
+   Documentation/ref/ovs-vlan-test.rst \
Documentation/requirements.txt
 
 EXTRA_DIST += $(DOC_SOURCE)
@@ -110,18 +111,20 @@ sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@)
 sphinx_verbose_0 = -q
 
 if HAVE_SPHINX
-htmldocs-check: $(DOC_SOURCE)
+docs-check: $(DOC_SOURCE)
$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) 
$(SPHINXBUILDDIR)/html && touch $@
-ALL_LOCAL += htmldocs-check
-CLEANFILES += htmldocs-check
+   $(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b man $(ALLSPHINXOPTS) 
$(SPHINXBUILDDIR)/man && touch $@
+ALL_LOCAL += docs-check
+CLEANFILES += docs-check
+
+man_MANS += \
+   $(SPHINXBUILDDIR)/man/ovs-vlan-test.1
 
 check-docs:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck
 
 clean-docs:
-   rm -rf $(SPHINXBUILDDIR)/doctrees
-   rm -rf $(SPHINXBUILDDIR)/html
-   rm -rf $(SPHINXBUILDDIR)/linkcheck
+   rm -rf $(SPHINXBUILDDIR)
 CLEAN_LOCAL += clean-docs
 endif
 .PHONY: check-docs
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6a924b3..e40302c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -312,7 +312,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-(master_doc, 'openvswitch', u'Open vSwitch Documentation',
+('ref/ovs-vlan-test', 'ovs-vlan-test',
+ u'Check Linux drivers for problems with vlan traffic',
  [author], 1)
 ]
 
diff --git a/Documentation/internals/contributing/documentation-style.rst 
b/Documentation/internals/contributing/documentation-style.rst
index 0ba5e54..fcf3b9e 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -347,7 +347,8 @@ In addition to the above, man pages have some specific 
requirements:
 - The man page must be included in the list of man page documents found in
   `conf.py`__
 
-Refer to existing man pages for worked examples.
+Refer to existing man pages, such as :doc:`/ref/ovs-vlan-test` for a worked
+example.
 
 __ http://www.sphinx-doc.org/en/stable/domains.html#directive-program
 __ http://www.sphinx-doc.org/en/stable/domains.html#directive-option
diff --git a/Documentation/intro/install/documentation.rst 
b/Documentation/intro/install/documentation.rst
index 94af950..0eeeab1 100644
--- a/Documenta