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 

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] [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 
> > 
> > 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] [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 heartbeats at regular i

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 sandbox (the s

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 
> CC: Darrell Ball 
> Signed-off-by: Antonio Fischetti 

One nit below, but otherwise LGTM.

Acked-by: Stephen Finucane 

> ---
>  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] 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 
> Fixes: 167703d664fc ("doc: Convert INSTALL.DPDK to rST")
> Signed-off-by: Ilya Maximets 

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

Acked-by: Stephen Finucane 

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

[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 
---
 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 ``dpdkvhostuser`` ports can be f

[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 
---
 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 h

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

[Stephen Finucane]

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

[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 
Cc: Ciara Loftus 
Cc: Kevin Traynor 
---
 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 'I350 Gigabit Network Connection 1521' if

[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 
---
 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 que

[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 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 
---
 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 (reserved for the title in a document)
+

[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 
---
 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 & Cu

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

Re: [ovs-dev] [PATCH] INSTALL.rst: New file.

[Stephen Finucane]

On Wed, 2017-03-29 at 12:42 -0700, Ben Pfaff wrote:
> One or two people have expressed surprise to me that there are no
> installation instructions at the top level.  This should help.  (The
> content is copied from README.rst.)
> 
> Signed-off-by: Ben Pfaff 

How odd. GitHub has taught me to always seek out the README as the
starting point for any project. I figured everyone else would do the
same now, though I do realize there are a lot of older (GNU)
"standards" around these things...

> ---
>  INSTALL.rst | 12 
>  Makefile.am |  1 +
>  2 files changed, 13 insertions(+)
>  create mode 100644 INSTALL.rst
> 
> diff --git a/INSTALL.rst b/INSTALL.rst
> new file mode 100644
> index ..07268033188a
> --- /dev/null
> +++ b/INSTALL.rst
> @@ -0,0 +1,12 @@
> +Installing Open vSwitch
> +---
> +
> +To install Open vSwitch on a regular Linux or FreeBSD host, please
> read the
> +`installation guide `__. 
>
> For specifics
> +around installation on a specific platform, refer to one of the
> `other
> +installation guides `__

Should we should link to the docs website instead? Depends on whether
we expect people to browse this from the web or locally, I guess. If we
go with the web, you could simplify this to:

  To install Open vSwitch, refer to the `documentation
  <http://docs.openvswitch.org>`

> +---
> +
> +b...@openvswitch.org
> diff --git a/Makefile.am b/Makefile.am
> index c853085b9ca9..6ad50b6af391 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -67,6 +67,7 @@ EXTRA_DIST = \
>   AUTHORS.rst \
>   CONTRIBUTING.rst \
>   MAINTAINERS.rst \
> +     INSTALL.rst \
>   README.rst \
>   NOTICE \
>   .travis.yml \

I'm OK with local links also though, so:

Acked-by: Stephen Finucane 

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

Re: [ovs-dev] [PATCH] Makefile: Fix name of coding style guide.

[Stephen Finucane]

On Wed, 2017-03-29 at 12:43 -0700, Ben Pfaff wrote:
> Signed-off-by: Ben Pfaff 

I wish Patchwork would let me show changes to individual files and/or
terms that I cared about. It's tough to keep an eye out for doc changes
in the deluge that is ovs-dev :) In any case:

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

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

[Stephen Finucane]

On Sat, 2017-04-01 at 20:02 +0100, Bhanuprakash Bodireddy wrote:
> Signed-off-by: Bhanuprakash Bodireddy
> 

Couple of changes suggested below if there's a future v2.

Stephen


> ---
>  Documentation/howto/dpdk.rst | 95
> 
>  1 file changed, 95 insertions(+)
> 
> diff --git a/Documentation/howto/dpdk.rst
> b/Documentation/howto/dpdk.rst
> index dc63f7d..26f702c 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -400,6 +400,101 @@ If ``N`` is set to 1, an insertion will be
> performed for every flow. If set to
>  
>  For more information on the EMC refer to :doc:`/intro/install/dpdk`
> .
>  
> +.. _keepalive:

This should probably read '_dpdk_keepalive' per the rest of the
references in this file.

> +
> +KeepAlive
> +-
> +
> +OvS KeepAlive(KA) feature is disabled by default. To enable KA
> feature::
> +
> +'ovs-vsctl --no-wait set Open_vSwitch .
> other_config:keepalive=true'

Remove the quotes are prefix with a '$'. Ditto for the rest of the
commands in this file.

> +
> +Default timer interval for monitoring packet processing cores is
> 100ms.

*The default timer...

> +To set a different timer value::

To set a different timer value, run.

> +
> +'ovs-vsctl --no-wait set Open_vSwitch . \
> +other_config:keepalive-interval="50"'
> +
> +The events comprise of core states and the last seen timestamps.The
> events

Missing space after full stop.

> +are written in to shared memory region
> ``/dev/shm/dpdk_keepalive_shm_name``.
> +To write in to a different shared memory region::

...region, run::

> +
> +'ovs-vsctl --no-wait set Open_vSwitch . \
> +other_config:keepalive-shm-name="/"'
> +
> +The events in the shared memory block can be read by external
> monitoring
> +framework (or) applications. `collectd `__
> has builtin

s/builtin/built-in/

> +support for DPDK and implements dpdkevents plugin that can be
> enabled to

...and provides a `dpdkevents` plugin...

> +relay the datapath core status to OpenStack service `Ceilometer
> +`__.
> +
> +To install and configure ``collectd``::

To install and and configure `collectd`, run::

Note that collectd can probably take a single backtick as it's not
something you're running from the command line

> +
> +# Clone collectd from Git repository
> +$ git clone https://github.com/collectd/collectd.git
> +
> +# configure and install collectd

Perhaps

  $ cd collectd

first?

> +$ ./build.sh
> +$ ./configure --enable-syslog --enable-logfile --with-
> libdpdk=/usr
> +$ make
> +$ make install
> +
> +collectd is defacto installed in /opt/collectd directory. Edit
> configuration

`collectd` is installed in ``/opt/collectd`` by default. Edit the
configuration file...

> +file in ``/opt/collectd/etc/collectd.conf`` to enable logfile,
> dpdkevents
> +and csv plugin.
> +
> +Enable ``logfile`` and ``syslog`` plugins and make sure the logs get
> +redirected appropriately::

This seems unnecessary as you've said you'd do this already in the
previous paragraph?

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

nit: Single backticks would be fine

> +
> +   LoadPlugin dpdkevents
> +
> +   
> + 
> +   Coremask "0x2"
> +   MemoryChannels "4"
> +   ProcessType "secondary"
> +   FilePrefix "rte"
> + 
> + 
> +   SendEventsOnUpdate true
> +   LCoreMask "0xf"
> +   KeepAliveShmName "/dpdk_keepalive_shm_name"
> +   SendNotification false
> +  
> +   
> +
> +``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(gauge) file is created and timestamp
> and core

With the `csv` plugin enabled, a *meter* or *gauge* file...

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

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

[ovs-dev] [PATCH 1/2] doc: Describe how docs.openvswitch.org works

[Stephen Finucane]

Signed-off-by: Stephen Finucane 
---
 Documentation/index.rst|  3 +-
 .../internals/contributing/documentation-style.rst |  6 ++
 Documentation/internals/documentation.rst  | 78 ++
 Documentation/internals/index.rst  |  1 +
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/internals/documentation.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6970dce..d81e9ba 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -108,7 +108,8 @@ Learn more about the Open vSwitch project and about how you 
can contribute:
   :doc:`internals/committer-grant-revocation`
 
 - **Documentation:** :doc:`internals/contributing/documentation-style` |
-  :doc:`Building Open vSwitch Documentation `
+  :doc:`Building Open vSwitch Documentation ` |
+  :doc:`internals/documentation`
 
 Getting Help
 -
diff --git a/Documentation/internals/contributing/documentation-style.rst 
b/Documentation/internals/contributing/documentation-style.rst
index f9da44c..9fe473c 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -32,6 +32,12 @@ Open vSwitch. Documentation includes any documents found in 
``Documentation``
 along with any ``README``, ``MAINTAINERS``, or generally ``rst`` suffixed
 documents found in the project tree.
 
+.. note::
+
+   This guide only applies to documentation for Open vSwitch v2.7. or greater.
+   Previous versions of Open vSwitch used a combination of Markdown and raw
+   plain text, and guidelines for these are not detailed here.
+
 reStructuredText vs. Sphinx
 ---
 
diff --git a/Documentation/internals/documentation.rst 
b/Documentation/internals/documentation.rst
new file mode 100644
index 000..eed98b4
--- /dev/null
+++ b/Documentation/internals/documentation.rst
@@ -0,0 +1,78 @@
+..
+  Copyright (c) 2017 Stephen Finucane 
+
+  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.
+
+==
+How Open vSwitch's Documentation Works
+==
+
+This document provides a brief overview on how the documentation build system
+within Open vSwitch works. This is intended to maximize the "bus factor" and
+share best practices with other projects.
+
+reStructuredText and Sphinx
+---
+
+Nearly all of Open vSwitch's documentation is written in `reStructuredText`__,
+with man pages being the sole exception. Of this documentation, most of it is
+fed into `Sphinx`__, which provides not only the ability to convert rST to a
+variety of other output formats but also allows for things like
+cross-referencing and indexing. for more information on the two, refer to the
+:doc:`contributing/documentation-style`.
+
+ovs-sphinx-theme
+
+
+The documentation uses its own theme, `ovs-sphinx-theme`, which can be found on
+GitHub__ and is published on pypi__. This is packaged separately from Open
+vSwitch itself to ensure all documentation gets the latest version of the theme
+(assuming there are no major version bumps in that package). If building
+locally and the package is installed, it will be used. If the package is not
+installed, Sphinx will fallback to the default theme.
+
+The package is currently maintained by Stephen Finucane and Russell Bryant.
+
+Read the Docs
+-
+
+The documentation is hosted on readthedocs.org and a CNAME redirect is in place
+to allow access from docs.openvswitch.org. *Read the Docs* provides a couple of
+nifty features for us, such as automatic building of docs whenever there are
+changes and versioning of documentation.
+
+The *Read the Docs* project is currently maintained by Stephen Finucane,
+Russell Bryant and Ben Pfaff.
+
+openvswitch.org
+---
+
+The sources for openvswitch.org are maintained separately from
+docs.openvswitch.org. For modifications to this site, refer to the `GitHub
+project`__.
+
+__ http:/

[ovs-dev] [PATCH 2/2] doc: Update makefile target for docs

[Stephen Finucane]

Signed-off-by: Stephen Finucane 
---
 Documentation/intro/install/documentation.rst | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/intro/install/documentation.rst 
b/Documentation/intro/install/documentation.rst
index 1160e94..94af950 100644
--- a/Documentation/intro/install/documentation.rst
+++ b/Documentation/intro/install/documentation.rst
@@ -74,14 +74,14 @@ Building
 Once Sphinx installed, the documentation can be built using the provided
 Makefile targets::
 
-$ make htmldocs
+$ make htmldocs-check
 
 .. important::
 
-   The ``htmldocs`` target will fail if there are any syntax errors. However,
-   it won't catch more succint issues such as style or grammar issues. As a
-   result, you should always inspect changes visually to ensure the result is
-   as intended.
+   The ``htmldocs-check`` target will fail if there are any syntax errors.
+   However, it won't catch more succint issues such as style or grammar issues.
+   As a result, you should always inspect changes visually to ensure the result
+   is as intended.
 
 Once built, documentation is available in the ``/Documentation/_build`` folder.
 Open the root ``index.html`` to browse the documentation.
-- 
2.9.3

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

[ovs-dev] [PATCH] doc: Fix broken formatting in releases FAQ

[Stephen Finucane]

---
 Documentation/faq/releases.rst | 10 +-
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/faq/releases.rst b/Documentation/faq/releases.rst
index 98f5636..c85eff8 100644
--- a/Documentation/faq/releases.rst
+++ b/Documentation/faq/releases.rst
@@ -163,13 +163,13 @@ Q: What DPDK version does each Open vSwitch release work 
with?
 2.7.x16.11.1
  ===
 
-Q: I get an error like this when I configure Open vSwitch::
+Q: I get an error like this when I configure Open vSwitch:
 
-configure: error: Linux kernel in  is version , but
-version newer than  is not supported (please refer to the
-FAQ for advice)
+configure: error: Linux kernel in  is version , but
+version newer than  is not supported (please refer to the
+FAQ for advice)
 
-What should I do?
+What should I do?
 
 A: You have the following options:
 
-- 
2.9.3

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

[ovs-dev] [PATCH] 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 
---
 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.
+
 Build requirements
 --
 
-- 
2.9.3

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

[ovs-dev] [RFC 0/4] Introduce Sphinx for man pages

[Stephen Finucane]

This series introduces the use of Sphinx for building man pages. There are a
couple of reasons for doing this:

- roff is ruff to write

  Sorry. roff is an old markup format that's mostly used for man pages today.
  While certainly not impossible to parse, it isn't very pleasant to either
  read or write (as evidenced by the XML-roff toolchain used for the OVN
  sources). Sphinx/rST isn't perfect but it's certainly easier on the eyes.

- Sphinx/rST über alles

  We already use Sphinx for every other bit of documentation in the toolchain.
  Why force people to learn a second syntax for man pages?

- Integration with other documentation

  By building with Sphinx, we can do basic things like output the man pages as
  part of the documentation along with more advanced things like
  cross-referencing applications from elesewhere in the docs.

This series begins work on converting the docs, starting with two small
utilities: ovs-test and ovs-vlan-test. We can use these to tease out any issues
we might have with the idea before expanding this to more complex man pages
(ovs-vsctl, I'm looking at you). The eventual goal would be to move all man
pages to rST/Sphinx.
---
I meant to send this months ago, but I completely forgot about it. It's
unfinished, as evidenced by the commit footers. However, I think with a little
help from the maintainers of the packaging in OVS, it will be easy push this
over the line and move onto the bigger, more important man pages.

Stephen Finucane (4):
  doc: Add man page section to documentation guide
  doc: Convert ovs-vlan-test to rST
  doc: Convert ovs-test to rST
  doc: Remove latex output configuration

 Documentation/automake.mk  |  23 +--
 Documentation/conf.py  |   6 +-
 .../internals/contributing/documentation-style.rst |  85 ++-
 Documentation/intro/install/documentation.rst  |   4 +-
 Documentation/ref/index.rst|  17 ++-
 Documentation/ref/ovs-test.rst | 165 +
 Documentation/ref/ovs-vlan-test.rst| 114 ++
 debian/openvswitch-switch.manpages |   1 -
 debian/openvswitch-test.manpages   |   1 -
 manpages.mk|  20 ---
 utilities/automake.mk  |   6 -
 11 files changed, 389 insertions(+), 53 deletions(-)
 create mode 100644 Documentation/ref/ovs-test.rst
 create mode 100644 Documentation/ref/ovs-vlan-test.rst

-- 
2.9.3

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

[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 
---
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/Do

[ovs-dev] [RFC 4/4] doc: Remove latex output configuration

[Stephen Finucane]

We don't care about building LaTeX documentation, so there's no need to
keep this build cruft around.

Signed-off-by: Stephen Finucane 
---
 Documentation/automake.mk | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 7b6de65..7a3c078 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -103,9 +103,7 @@ SPHINXSRCDIR = $(srcdir)/Documentation
 SPHINXBUILDDIR = $(builddir)/Documentation/_build
 
 # Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -W -n -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) 
$(SPHINXOPTS) $(SPHINXSRCDIR)
+ALLSPHINXOPTS = -W -n -d $(SPHINXBUILDDIR)/doctrees $(SPHINXOPTS) 
$(SPHINXSRCDIR)
 
 sphinx_verbose = $(sphinx_verbose_@AM_V@)
 sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@)
-- 
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 
---
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.
+
+

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

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"  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 
> ---
>  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] [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 
---
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] 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] docs: Automatically extract version from NEWS

[Stephen Finucane]

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 
Cc: Russell Bryant 
---
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.
---
 Documentation/conf.py| 20 +++-
 Documentation/ovs_version.py | 38 ++
 2 files changed, 49 insertions(+), 9 deletions(-)
 create mode 100644 Documentation/ovs_version.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6a924b3..42ebdac 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -15,10 +15,13 @@
 # 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('.'))
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+import ovs_version
+
 try:
 import ovs_sphinx_theme
 use_ovs_theme = True
@@ -61,11 +64,10 @@ author = u'The Open vSwitch Development Community'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = u'2.6'
-# The full version, including alpha/beta/rc tags.
-release = u'2.6.0'
+
+# version is the short X.Y version, while release is the full version,
+# including alpha/beta/rc tags.
+version, release = ovs_version.get_release_info()
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/Documentation/ovs_version.py b/Documentation/ovs_version.py
new file mode 100644
index 000..3d250e9
--- /dev/null
+++ b/Documentation/ovs_version.py
@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+
+import os
+import re
+
+ROOT_DIR = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+NEWS_FILE = os.path.join(ROOT_DIR, 'NEWS')
+RELEASE_VERSION_RE = r'(?:Post-)?v(?P(?P\d+.\d+).\d+)'
+
+
+def get_release_info():
+"""Parse the latest release version from NEWS.
+
+This relies on some assumptions about the format of the NEWS file - mainly
+that the first line will always contain the latest version and an optional
+date.
+
+Returns:
+A tuple of (version, release), where version corresponds to the short
+MAJOR.MINOR version and release corresponds to the MAJOR.MINOR.PATCH
+version.
+"""
+with open(NEWS_FILE, 'r') as news:
+version_header = news.readline()
+
+try:
+# we don't care about the date of the release
+release, _ = version_header.split(' - ')
+except ValueError:
+release = version_header
+
+release = re.search(RELEASE_VERSION_RE, release)
+
+return release.group('version'), release.group('release')
+
+
+if __name__ == '__main__':
+print(get_latest_release())
-- 
2.9.3

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

Cheers :)
Stephen
___
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 
> > Cc: Russell Bryant 
> > ---
> > 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 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 

Acked-by: Stephen Finucane 
___
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 
> ---
>  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 

>  # 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.
&g

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 
> > ---
> > 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 1/3] doc: Convert some bolded words into links.

[Stephen Finucane]

On Fri, 2017-04-14 at 10:31 -0700, Ben Pfaff wrote:
> Seems more user-friendly.
> 
> Signed-off-by: Ben Pfaff 

Acked-by: Stephen Finucane 

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

Re: [ovs-dev] [PATCH 2/3] doc: Convert a named link into a title link.

[Stephen Finucane]

On Fri, 2017-04-14 at 10:31 -0700, Ben Pfaff wrote:
> It seems like this is easier to read in the source form.  I don't
> understand what is typical style here, though.
> 
> Signed-off-by: Ben Pfaff 

Acked-by: Stephen Finucane 

___
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 

Acked-by: Stephen Finucane 

___
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 
> > > > ---
> > > > 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] doc: Apply flake8 to conf.py also.

[Stephen Finucane]

On Fri, 2017-04-14 at 14:18 -0700, Ben Pfaff wrote:
> Suggested-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 

Acked-by: Stephen Finucane 

> ---
>  Documentation/automake.mk | 2 +-
>  Documentation/conf.py | 4 ++--
>  2 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 9911668c1ca9..8d18bd9714a4 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -91,7 +91,7 @@ DOC_SOURCE = \
>   Documentation/internals/contributing/libopenvswitch-abi.rst
> \
>   Documentation/internals/contributing/submitting-patches.rst
> \
>   Documentation/requirements.txt
> -
> +FLAKE8_PYFILES += Documentation/conf.py
>  EXTRA_DIST += $(DOC_SOURCE)
>  
>  # You can set these variables from the command line.
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index e32436be5357..49514ec96571 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -175,8 +175,8 @@ else:
>  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.
> +# the docs.  This file should be a Windows icon file (.ico) being
> 16x16 or
> +# 32x32 pixels large.
>  #
>  # html_favicon = None
>  

___
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

[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 
Cc: Matthew Thode 
---
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

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

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 
> 
> We also replace 'reST' with the far more common 'rST'.
> 
> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 

This looks unchanged, thus:

Acked-by: Stephen Finucane 
___
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 
> 
> 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 

> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 
> ---
>  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=&#x

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 
> 
> We don't care about building LaTeX documentation, so there's no need
> to
> keep this build cruft around.
> 
> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 

Unchanged, but fwiw...

Acked-by: Stephen Finucane 
___
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 
> 
> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 

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

Acked-by: Stephen Finucane 
___
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] 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

[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 remove the old extension. 
Once complete, run
 turn on ``TESTSIGN

[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 remove the old extension. 
Once complete, run
 turn on ``TESTSIGN

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

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

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 

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 

> ---
> 
> 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] [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 
> > 
> > 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)
> 
> 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] gitignore: Ignore /docs-check instead of /htmldocs-check

[Stephen Finucane]

On Mon, 2017-04-24 at 11:17 +0200, Timothy Redaelli wrote:
> Fixes: fd0837a76f4c ("doc: Convert ovs-vlan-test to rST")
> CC: Stephen Finucane 
> Signed-off-by: Timothy Redaelli 

Oops - good spot.

Acked-by: Stephen Finucane 
___
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] [PATCH v2 6/6] Documentation: Update DPDK doc with Keepalive feature.

[Stephen Finucane]

hared memory block 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 

Thanks, Bhanuprakash, :)

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

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

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

[Stephen Finucane]

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 
---
 Documentation/conf.py | 18 +++---
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 6555747..d70ee6b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -112,11 +112,15 @@ html_static_path = ['_static']
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-('ref/ovs-test.8', 'ovs-test',
- u'Check Linux drivers for performance, vlan and L3 tunneling problems',
- [author], 8),
-('ref/ovs-vlan-test.8', 'ovs-vlan-test',
- u'Check Linux drivers for problems with vlan traffic',
- [author], 8)
+_man_pages = [
+('ovs-test.8',
+ u'Check Linux drivers for performance, vlan and L3 tunneling problems'),
+('ovs-vlan-test.8',
+ u'Check Linux drivers for problems with vlan traffic'),
 ]
+
+# 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]
-- 
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 
---
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/coverag

[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 
Reported-by: Bhanuprakash Bodireddy 
Fixes: f15010f ("doc: Reduce duplication in 'man_pages'")
Cc: Ben Pfaff 
---
 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

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

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

[Stephen Finucane]

On Thu, 2017-05-18 at 16:02 -0700, Ben Pfaff wrote:
> Bravo.  This must have been a lot of work.
> 
> More comments follow...
> 
> On Wed, May 10, 2017 at 09:32:19PM -0400, Stephen Finucane wrote:
> > 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.
> 
> I'm not too aware of Sphinx indexing.  When I type "Sphinx indexing"
> into Google, it tells me about a search engine named Sphinx, which I
> don't think is what you mean.  Can you point to something about it?

Sure - here's the example from our own docs:

http://docs.openvswitch.org/en/latest/genindex/

> If the indexing is just a matter of being able to jump to the
> definition of -v from somewhere else, I wonder whether it matters
> whether both definitions are indexed?  I think that both definitions
> would be right next to each other in this case.

In fairness, it probably doesn't. I'll change this to use 'object' for
all except the most basic, no-arg one. 'object' produces the same
formatting as 'option' but doesn't generate a reference/add things to
the index.

> There's a bigger problem with the above transformation, though: -v
> takes an optional argument, which means that only accepts an argument
> if the argument is mashed up against it.  If you write "-v ..." with
> a space, it's not an argument, it's "-v" followed by a non-option
> argument.

They didn't account for this when writing the Sphinx directive, clearly
:) We should resolve this particular case with the above change, but
I'll have to rely on you to look for any other cases I've missed.

> > - TODO
> > 
> > Signed-off-by: Stephen Finucane 
> >
> > - 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 don't understand the issue yet.  What happens if we just use RST
> that produces the desired formatting?  (Is this about indexing
> again?)

Two issues. First, take a look at the current ovs-vswitchd doc:

  http://openvswitch.org/support/dist-docs/ovs-vswitchd.8.html

If you look at the 'ssl:ip:port' description, you'll note that 'ssl' is
 in bold, 'ip' and 'port' are underlined, and the colons in between
have no formatting. We can't do this in Sphinx as you need spaces
between inline formatting markers.

Secondly, look at an example of the 'option' directive, e.g.:

   .. option:: -V, --version

   Prints version information to the console.

This can be viewed like so:

   .. :: 

  

While '' is parsed as reStructuredText, '' is not. This means if we include things like '*' (italics),
'**' (bold), or '``' (code/literal), they'll be rendered as they are.

IMO, the option directive provides enough usefulness to make this
worthwhile, but I called it out just in case.

> > - 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
> 
> We could always just document these commands in only one place, e.g.
> the ovs-dpctl manpage, and then refer to that manpage from ovs-
> vswitchd manpage with a little extra explanation, e.g. "You can use
> ovs-dpctl commands via ovs-appctl: instead of &

[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 
Cc: Ciara Loftus 
Cc: Kevin Traynor 
---
 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-1 \
 type=dpdkvhostuser
-- 
2.9.4

___

[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 
Cc: Ciara Loftus 
Cc: Kevin Traynor 
---
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

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

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

[Stephen Finucane]

On Fri, 2017-05-26 at 15:12 +0100, Stephen Finucane wrote:
> 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 
> Cc: Ciara Loftus 
> Cc: Kevin Traynor 

Two nits I spotted after posting below.

Stephen

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

s/of/on

> 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

s/interfaces/ports/ ?

> 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_g
> uide/ring_lib.html
> diff --git a/Documentation/topics/dpdk/vhost-user.rst
> b/Documentation/topics/dpdk/vhost-user.rst
> ind

[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 
---
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: 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  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 
> > ---
> > 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

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

[Stephen Finucane]

On Thu, 2017-08-31 at 09:59 +0100, Stephen Finucane wrote:
> On Wed, 2017-08-30 at 10:38 -0700, Joe Stringer wrote:
> > On 29 August 2017 at 02:54, Stephen Finucane  wrote:

[snip]

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

If you did want to play with this rn, using the project name (as opposed to the
linkname) will let you do so:

  git config pw.project 'open vswitch'

Stephen
___
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 
---
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] 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

Re: [ovs-dev] [PATCH] doc: Describe backporting process.

[Stephen Finucane]

On Wed, 2017-02-15 at 15:05 -0800, Joe Stringer wrote:
> This patch documents the backporting process, and provides a
> walkthrough
> for developers who would like to backport upstream Linux patches into
> the Open vSwitch tree. Nothing in this documentation should be
> surprising or new; it merely puts the existing process into words.
> 
> Signed-off-by: Joe Stringer 
> Acked-by: Ben Pfaff 

Excellent guide - I had no idea OVS and the net-next tree were as
closely related as they are. Couple of nits below but nothing I'd block
on.

Acked-by: Stephen Finucane 

> ---
>  Documentation/automake.mk  |   1 +
>  Documentation/index.rst|   1 +
>  Documentation/internals/contributing/backports.rst | 232
> +
>  Documentation/internals/contributing/index.rst |   1 +
>  4 files changed, 235 insertions(+)
>  create mode 100644
> Documentation/internals/contributing/backports.rst
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 42553f0b57ff..610d8ccc6f96 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -80,6 +80,7 @@ EXTRA_DIST += \
>   Documentation/internals/release-process.rst \
>   Documentation/internals/security.rst \
>   Documentation/internals/contributing/index.rst \
> + Documentation/internals/contributing/backports.rst \
>   Documentation/internals/contributing/coding-style.rst \
>   Documentation/internals/contributing/coding-style-
> windows.rst \
>   Documentation/internals/contributing/documentation-style.rst 
> \
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 02b376fc2a08..8cfb9f3f47a8 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -98,6 +98,7 @@ Learn more about the Open vSwitch project and about
> how you can contribute:
>    :doc:`internals/security`
>  
>  - **Contributing:** :doc:`internals/contributing/submitting-patches` 
> |
> +  :doc:`internals/contributing/backports` |

I guess 'backporting-patches' might be more in keeping with existing
files?

>    :doc:`internals/contributing/coding-style` |
>    :doc:`internals/contributing/coding-style-windows`
>  
> diff --git a/Documentation/internals/contributing/backports.rst
> b/Documentation/internals/contributing/backports.rst
> new file mode 100644
> index ..d1fa35007f01
> --- /dev/null
> +++ b/Documentation/internals/contributing/backports.rst
> @@ -0,0 +1,232 @@
> +..

Copyright (c) 2017 ???

> +  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.
> +
> +===
> +Backporting patches
> +===
> +
> +.. note::
> +
> +This is an advanced topic for developers and maintainers.
> Readers should
> +familiarize themselves with building and running Open vSwitch,
> with the git
> +tool, and with the Open vSwitch patch submission process.
> +
> +The backporting of patches from one git tree to another takes
> multiple forms
> +within Open vSwitch, but is broadly applied in the following
> fashion:
> +
> +- Contributors submit their proposed changes to the latest
> development branch
> +- Contributors and maintainers provide feedback on the patches
> +- When the change is satisfactory, maintainers apply the patch to
> the
> +  development branch.
> +- Maintainers backport changes from a development branch to release
> branches.
> +
> +With regards to Open vSwitch user space code and code that does not
> comprise
> +the Linux datapath and compat code, the development branch is
> `master` in the
> +Open vSwitch repository. Patches are applied first to this branch,
> then to the
> +most recent `branch-X.Y`

Re: [ovs-dev] manpages in rst?

[Stephen Finucane]

On Thu, 2017-02-16 at 09:24 -0800, Ben Pfaff wrote:
> Currently, we have some manpages written directly in nroff.  This is
> an
> awful format, that is difficult to read and difficult to
> write.  Other
> manpages are written in a custom XML format that, while it is easier
> to
> read and write, isn't any standard format and so we can't expect
> anyone
> else (person or program) to understand it.  This is not ideal.  It's
> difficult to include either format in the readthedocs documentation,
> too.

I started on a converter for that XML format but I haven't had a chance
to finish it. The biggest problem I encountered was that rST is
slightly lossy - it's not possible to nest elements the way you can
nest XML or HTML so you have to drop some stuff. For example,
converting '' is impossible, since rST doesn't have markup for
bold AND italic. Figuring out what to drop proved tougher than I
thought. I basically needed to build a parser rather than hacking
something together with regexes :(

> I'm thinking about starting to write manpages in REstructured Text
> (rst).  This would make it much easier to include them in the
> readthedocs pages, and ReST seems to convert pretty well to nroff for
> installing as real manpages.  For example, try fetching
> http://docutils.sourceforge.net/sandbox/manpage-writer/input/test.txt
> ,
> which is a rst file, and then running "rst2man test.txt > test.man"
> and
> viewing test.man with "man -l" or "groffer".  The output looks fine.
> 
> I think that all we'd need for this is a build dependency on
> python-docutils to ensure that rst2man is available at build time.

Pure rST would be my recommendation. Sphinx (python-sphinx) supports
man page output [2] and could be an even better option that rst2man. We
already have this (optional) dependency for the docs.

I do note that Django includes the generated man pages in the repo
itself [1]. While the general policy for version control is not to
include anything that's autogenerated, this could make packaging and
installation from source slightly easier by avoiding adding another
dependency. Then again, Sphinx is widely enough used that we could be
pretty certain it would be available. I'll leave this to you to decide.

I have a couple of the man pages already converted to rST so, if you're
happy to wait until after the OpenStack PTG, I could submit these. Also
happy to review if someone else would like to work on it.

Cheers,
Stephen

[1] https://github.com/django/django/tree/master/docs/man
[2] http://www.sphinx-doc.org/en/stable/builders.html#sphinx.builders.m
anpage.ManualPageBuilder
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] manpages in rst?

[Stephen Finucane]

On Fri, 2017-02-17 at 09:32 -0800, Ben Pfaff wrote:
> On Fri, Feb 17, 2017 at 07:34:10AM -0500, Stephen Finucane wrote:
> > On Thu, 2017-02-16 at 09:24 -0800, Ben Pfaff wrote:
> > > Currently, we have some manpages written directly in nroff.  This
> > > is
> > > an
> > > awful format, that is difficult to read and difficult to
> > > write.  Other
> > > manpages are written in a custom XML format that, while it is
> > > easier
> > > to
> > > read and write, isn't any standard format and so we can't expect
> > > anyone
> > > else (person or program) to understand it.  This is not
> > > ideal.  It's
> > > difficult to include either format in the readthedocs
> > > documentation,
> > > too.
> > 
> > I started on a converter for that XML format but I haven't had a
> > chance
> > to finish it. The biggest problem I encountered was that rST is
> > slightly lossy - it's not possible to nest elements the way you can
> > nest XML or HTML so you have to drop some stuff. For example,
> > converting '' is impossible, since rST doesn't have markup
> > for
> > bold AND italic. Figuring out what to drop proved tougher than I
> > thought. I basically needed to build a parser rather than hacking
> > something together with regexes :(
> 
> Hmm.  I think that the XML format, in nroff translation, effectively
> ends up with whatever is the innermost markup.  I don't think it does
> anything smarter than that.  (I don't even know how to produce
> bold-italic in nroff.)

Ah, so a tie in this aspect of the XML vs. rST "debate". I have seen a
couple of bold-italic 

> > > I'm thinking about starting to write manpages in REstructured
> > > Text
> > > (rst).  This would make it much easier to include them in the
> > > readthedocs pages, and ReST seems to convert pretty well to nroff
> > > for
> > > installing as real manpages.  For example, try fetching
> > > http://docutils.sourceforge.net/sandbox/manpage-writer/input/test
> > > .txt
> > > ,
> > > which is a rst file, and then running "rst2man test.txt >
> > > test.man"
> > > and
> > > viewing test.man with "man -l" or "groffer".  The output looks
> > > fine.
> > > 
> > > I think that all we'd need for this is a build dependency on
> > > python-docutils to ensure that rst2man is available at build
> > > time.
> > 
> > Pure rST would be my recommendation. Sphinx (python-sphinx)
> > supports
> > man page output [2] and could be an even better option that
> > rst2man. We
> > already have this (optional) dependency for the docs.
> 
> Can you help me understand the trade-off?  That is, how is one better
> than the other?

Some advantages that I can think of:

- We can use Sphinx directives, such as 'include' to avoid duplication
and 'doc' or 'ref' to cross-reference where required

- Our man pages will be integrated into the rest of the docs build
system

- Only one, widely available dependency needed for all documentation:
python-sphinx

- Sphinx supports multiple output formats - not just roff or HTML. PDF
versions of the man pages, for example, would be possible for whoever
wanted them

As far as downsides go, rST with Sphinx directives can't be rendered
without "compiling the docs", unlike pure rST docs. Also, introducing a
bug in the docs would now break the global build (maybe a good thing?)

> > I do note that Django includes the generated man pages in the repo
> > itself [1]. While the general policy for version control is not to
> > include anything that's autogenerated, this could make packaging
> > and
> > installation from source slightly easier by avoiding adding another
> > dependency. Then again, Sphinx is widely enough used that we could
> > be
> > pretty certain it would be available. I'll leave this to you to
> > decide.
> 
> We already have a build dependency on Python, so I don't think that
> depending on python-docutils would add much to that; it seems like
> it's
> close to being core Python in any case.  I don't know whether adding
> sphinx is a big deal.

Personally, given the widespread availability of Sphinx (it's been
packaged on all major distros for many moons now [*] and easily
installed on Windows), I think it's fair to make Sphinx a required
dependency for building OVS now. The only platforms I can't find
concrete info for are the two BSDs, but they do have Python and

Re: [ovs-dev] [patch_v1] doc: Support building ovs with Trusty.

[Stephen Finucane]

On Thu, 2017-03-02 at 20:01 -0800, Darrell Ball wrote:
> Some code-block directives are not understood using
> Trusty (I was using 14.04.1 when the issue was found)
> default package versions, which blocks the build.
> 
> An error example:
> writing output... [100%] topics/language-bindings
> Warning, treated as error:
> /home/dball/ovs/Documentation/topics/language-bindings.rst:39:
> WARNING: Pygments lexer name u'shell' is not known
> 
> 14.04.1 has Sphinx 1.2.2 and Pygments 1.6.
> 
> I expect Trusty to still be widely used, so we
> should be able to build ovs with it.
> 
> requirements.rst indicates only:
> sphinx>=1.2,<2.0
> ovs_sphinx_theme>=1.0,<1.1
> 
> Fixes: f150a8bafbf2 ("doc: Document various language bindings")
> Suggested-by: Daniele Di Proietto 
> Signed-off-by: Darrell Ball 
> CC: Stephen Finucane 

This all looks fine to me. I'm not sure if 14.04 is a valid
target still (for development at least), but these changes are small
enough and the requirements *do* state 1.2 as the minimum. As such:

Acked-by: Stephen Finucane 

Could you also submit a modification to the documentation style guide
as a follow up, noting the need to validate docs against the minimum
supported version?

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

Re: [ovs-dev] [patch_v1] doc: Support building ovs with Trusty.

[Stephen Finucane]

On Tue, 2017-03-07 at 08:21 -0500, Russell Bryant wrote:
> 
> 
> On Tue, Mar 7, 2017 at 5:31 AM, Stephen Finucane 
> wrote:
> > On Thu, 2017-03-02 at 20:01 -0800, Darrell Ball wrote:
> > > Some code-block directives are not understood using
> > > Trusty (I was using 14.04.1 when the issue was found)
> > > default package versions, which blocks the build.
> > >
> > > An error example:
> > > writing output... [100%] topics/language-bindings
> > > Warning, treated as error:
> > > /home/dball/ovs/Documentation/topics/language-bindings.rst:39:
> > > WARNING: Pygments lexer name u'shell' is not known
> > >
> > > 14.04.1 has Sphinx 1.2.2 and Pygments 1.6.
> > >
> > > I expect Trusty to still be widely used, so we
> > > should be able to build ovs with it.
> > >
> > > requirements.rst indicates only:
> > > sphinx>=1.2,<2.0
> > > ovs_sphinx_theme>=1.0,<1.1
> > >
> > > Fixes: f150a8bafbf2 ("doc: Document various language bindings")
> > > Suggested-by: Daniele Di Proietto 
> > > Signed-off-by: Darrell Ball 
> > > CC: Stephen Finucane 
> > 
> > This all looks fine to me. I'm not sure if 14.04 is a valid
> > target still (for development at least), but these changes are
> > small
> > enough and the requirements *do* state 1.2 as the minimum. As such:
> > 
> > Acked-by: Stephen Finucane 
> > 
> > Could you also submit a modification to the documentation style
> > guide
> > as a follow up, noting the need to validate docs against the
> > minimum
> > supported version?
> 
> Maybe we should set up a tox environment that builds the docs using
> the minimum supported version of sphinx.  That would make it easy on
> everyone to test.

This sounds good to me - I'd have it done already only I wasn't sure if
you'd want a tox file in a non-Python project :) I can draft that
shortly if you're OK with it.

I'd still like to update the documentation guide in any case, even if
only to reference the tox option.

Stephen

PS: This also sounds like something that could be automatically tested.
If only some folks were working on a tool to automatically test mailing
list patches...

  https://speakerdeck.com/stephenfin/mailing-list-meet-ci
___
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev

Re: [ovs-dev] [PATCH RFC] doc: Decrease build requirements to support RHEL7.

[Stephen Finucane]

On Tue, 2017-03-07 at 17:31 +0300, Ilya Maximets wrote:
> Sphynx 1.1.3 on RHEL7 is able to properly build the documentation.
> One last thing is that 'ps1con' and 'doscon' lexers are not
> supported by available python-pygments-2.0.2. Changing them
> to 'ps1' and 'console' accordingly doesn't make many differencies.
> 
> Sphinx discovering fixed because 'sphinx-build v1.1.3' doesn't
> support '--version' option.
> 
> Signed-off-by: Ilya Maximets 

I'm generally fine with this, but Darren Ball beat you to the punch [1]
and caught one that you seem to have missed (documentation-style.rst)?
As such, we only need the modifications to 'conf.py', 'openvswitch.m4'
and 'requirements.txt'. Assuming we keep just those changes:

Acked-by: Stephen Finucane 

Stephen

[1] https://patchwork.ozlabs.org/patch/734930/

> ---
> 
>  Note:
>   Marked as RFC because I don't know sphinx well.
> 
>  Documentation/conf.py   |  2 +-
>  Documentation/intro/install/windows.rst | 70 ---
> --
>  Documentation/requirements.txt  |  2 +-
>  m4/openvswitch.m4   |  2 +-
>  4 files changed, 38 insertions(+), 38 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 389ef70..5909669 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -30,7 +30,7 @@ except ImportError:
>  
>  # If your documentation needs a minimal Sphinx version, state it
> here.
>  #
> -needs_sphinx = '1.2'
> +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
> diff --git a/Documentation/intro/install/windows.rst
> b/Documentation/intro/install/windows.rst
> index caa9f40..d78a442 100644
> --- a/Documentation/intro/install/windows.rst
> +++ b/Documentation/intro/install/windows.rst
> @@ -225,7 +225,7 @@ building on Linux, FreeBSD, or NetBSD.
>    all MinGW sessions and then run the below command from MSVC
> developers
>    command prompt.:
>  
> -  .. code-block:: doscon
> +  .. code-block:: console
>  
>   > mingw-get upgrade msys-core-bin=1.0.17-1
>  
> @@ -276,7 +276,7 @@ Now run ``./uninstall.cmd`` to remove the old
> extension. Once complete, run
>  turn on ``TESTSIGNING`` boot option or 'Disable Driver Signature
>  Enforcement' during boot.  The following commands can be used:
>  
> -.. code-block:: doscon
> +.. code-block:: console
>  
> > bcdedit /set LOADOPTIONS DISABLE_INTEGRITY_CHECKS
> > bcdedit /set TESTSIGNING ON
> @@ -294,7 +294,7 @@ to work (covered later).
>  The command to create a new switch named 'OVS-Extended-Switch' using
> a physical
>  NIC named 'Ethernet 1' is:
>  
> -.. code-block:: ps1con
> +.. code-block:: ps1
>  
> PS > New-VMSwitch "OVS-Extended-Switch" -NetAdapterName "Ethernet
> 1"
>  
> @@ -307,7 +307,7 @@ In the properties of any switch, you should
> should now see "Open vSwitch
>  Extension" under 'Extensions'.  Click the check box to enable the
> extension.
>  An alternative way to do the same is to run the following command:
>  
> -.. code-block:: ps1con
> +.. code-block:: ps1
>  
> PS > Enable-VMSwitchExtension "Open vSwitch Extension" OVS-
> Extended-Switch
>  
> @@ -330,7 +330,7 @@ database, ovsdb-server. Each machine on which
> Open vSwitch is installed should
>  run its own copy of ovsdb-server. Before ovsdb-server itself can be
> started,
>  configure a database that it can use:
>  
> -.. code-block:: doscon
> +.. code-block:: console
>  
> > ovsdb-tool create C:\openvswitch\etc\openvswitch\conf.db \
> C:\openvswitch\usr\share\openvswitch\vswitch.ovsschema
> @@ -338,7 +338,7 @@ configure a database that it can use:
>  Configure ovsdb-server to use database created above and to listen
> on a Unix
>  domain socket:
>  
> -.. code-block:: doscon
> +.. code-block:: console
>  
> > ovsdb-server -vfile:info --remote=punix:db.sock --log-file \
> --pidfile --detach
> @@ -351,7 +351,7 @@ Initialize the database using ovs-vsctl. This is
> only necessary the first time
>  after you create the database with ovsdb-tool, though running it at
> any time is
>  harmless:
>  
> -.. code-block:: doscon
> +.. code-block:: console
>  
> > ovs-vsctl --no-wait init
>  
> @@ -359,14 +359,14 @@ harmless:
>  
> If you would later like to term

Re: [ovs-dev] [PATCH] Documentation: Report errors for use of features not in Sphinx 1.1.3.

[Stephen Finucane]

On Tue, 2017-03-07 at 10:54 -0800, Ben Pfaff wrote:
> Signed-off-by: Ben Pfaff 

I'm not sure if this is completely necessary, but I imagine it won't
slow the build down too much and looks about right so:

Acked-by: Stephen Finucane 

I'd also like to see a TODO describing the path to removing support for
Sphinx 1.1 (which is pretty old now) but what that path looks like, I
don't know.

Some other small points below.

> ---
>  Documentation/automake.mk  | 15 ++-
>  Documentation/sphinx-version-blacklist |  2 ++
>  2 files changed, 16 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/sphinx-version-blacklist
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index a74807fde532..f7f1fe61d1b7 100644
> --- a/Documentation/automake.mk
> +++ b/Documentation/automake.mk
> @@ -86,7 +86,8 @@ EXTRA_DIST += \
>   Documentation/internals/contributing/documentation-style.rst 
> \
>   Documentation/internals/contributing/libopenvswitch-abi.rst
> \
>   Documentation/internals/contributing/submitting-patches.rst
> \
> - Documentation/requirements.txt
> + Documentation/requirements.txt \
> + Documentation/sphinx-version-blacklist

This still won't build locally for me so I can't validate it. Could you
just make sure this doesn't cause a failed doc build due to a warning
about documents that are not included in any table of contents. I think
only 'rst' files are included in that check, but I can't be sure.

>  
>  # You can set these variables from the command line.
>  SPHINXOPTS =
> @@ -120,3 +121,15 @@ endif
>  .PHONY: htmldocs
>  .PHONY: check-docs
>  .PHONY: clean-docs
> +
> +ALL_LOCAL += sphinx-version-check
> +sphinx-version-check: $(EXTRA_DIST)
> + @if grep -n -f $(srcdir)/Documentation/sphinx-version-
> blacklist $?; \
> + then \
> +   echo "See above for list of uses of features that Sphinx
> 1.1.3"; \

Assuming Sphinx do semantic versioning correctly (they do), we can
simply say Sphinx 1.1 here.

> +   echo "does not support.  Please avoid using these
> features.."; \
> +   exit 1; \
> + else \
> +  : > $@; \
> + fi
> +CLEANFILES += sphinx-version-check
> diff --git a/Documentation/sphinx-version-blacklist
> b/Documentation/sphinx-version-blacklist
> new file mode 100644
> index ..a67339bf2758
> --- /dev/null
> +++ b/Documentation/sphinx-version-blacklist
> @@ -0,0 +1,2 @@
> +code-block:: *ps1con
> +code-block:: *doscon

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

Re: [ovs-dev] [PATCH 1/3] doc: Fix issues.rst formatting typo.

[Stephen Finucane]

On Thu, 2017-03-02 at 05:02 -0800, nickcooper-zhangtonghao wrote:
> The preformatted block is only finished when the text
> falls back to the same indentation level as a paragraph
> prior to the preformatted block.
> 
> Signed-off-by: nickcooper-zhangtonghao 

LGTM.

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

Re: [ovs-dev] [patch_v1] doc: Support building ovs with Trusty.

[Stephen Finucane]

On Tue, 2017-03-07 at 11:01 -0800, Ben Pfaff wrote:
> On Tue, Mar 07, 2017 at 05:01:06PM +0000, Stephen Finucane wrote:
> > PS: This also sounds like something that could be automatically
> > tested.
> > If only some folks were working on a tool to automatically test
> > mailing
> > list patches...
> > 
> >   https://speakerdeck.com/stephenfin/mailing-list-meet-ci
> 
> More automatic tests are (almost) always better.  Is this something
> that's ready for us to try out, or should we wait until it's more
> mature?

Not quite yet. I'll let you know when it is though.

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

Re: [ovs-dev] [RFC] Use tox to build docs.

[Stephen Finucane]

On Mon, 2017-03-13 at 17:41 -0400, Russell Bryant wrote:
> There have been a few patches lately tweaking docs to deal with
> different
> sphinx versions in different linux distributions.  This patch
> demonstrates
> an alternative approach to avoid those types of issues.  Instead of
> calling
> sphinx-build directly, it uses tox to build a Python virtual
> environment
> based on the requirements.txt file.  Everyone would have to install
> tox,
> but then everyone would automatically use the same versions of doc
> build
> dependencies.
> TODO:
>  - remove checking for sphinx from build system, add tox check
> instead
>  - update various documentations to reflect that you should install
> tox
> 
> Signed-off-by: Russell Bryant 

I'm on the fence with this. On one hand, I myself used a virtualenv to
develop the docs to make sure I had the latest and greatest Sphinx
version and to avoid cluttering my system PYTHONPATH. However,
something about calling tox from make seems...icky :) I like tox, but
it does seem like something that doesn't belong in a C-based project.

I'm pretty sure I noted the option of using virtualenv when building
docs, so we could just update the sphinx version check to check a given
pygments version too. Anyone that can't match that with system packages
(Ubuntu 14.04, for example) would be advised to use virtualenvs.

The above is entirely subjective though, and I've no strong technical
reason not to follow through with the tox approach. If Ben et al are
happy with this, then so am I.

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

Re: [ovs-dev] [RFC] Use tox to build docs.

[Stephen Finucane]

On Tue, 2017-03-14 at 10:50 -0400, Russell Bryant wrote:
> On Tue, Mar 14, 2017 at 8:21 AM, Stephen Finucane 
> wrote:
> > On Mon, 2017-03-13 at 17:41 -0400, Russell Bryant wrote:
> > > There have been a few patches lately tweaking docs to deal with
> > > different
> > > sphinx versions in different linux distributions.  This patch
> > > demonstrates
> > > an alternative approach to avoid those types of issues.  Instead
> > > of
> > > calling
> > > sphinx-build directly, it uses tox to build a Python virtual
> > > environment
> > > based on the requirements.txt file.  Everyone would have to
> > > install
> > > tox,
> > > but then everyone would automatically use the same versions of
> > > doc
> > > build
> > > dependencies.
> > > TODO:
> > >  - remove checking for sphinx from build system, add tox check
> > > instead
> > >  - update various documentations to reflect that you should
> > > install
> > > tox
> > > 
> > > Signed-off-by: Russell Bryant 
> > 
> > I'm on the fence with this. On one hand, I myself used a virtualenv
> > to
> > develop the docs to make sure I had the latest and greatest Sphinx
> > version and to avoid cluttering my system PYTHONPATH. However,
> > something about calling tox from make seems...icky :) I like tox,
> > but
> > it does seem like something that doesn't belong in a C-based
> > project.
> > 
> > I'm pretty sure I noted the option of using virtualenv when
> > building
> > docs, so we could just update the sphinx version check to check a
> > given
> > pygments version too. Anyone that can't match that with system
> > packages
> > (Ubuntu 14.04, for example) would be advised to use virtualenvs.
> > 
> > The above is entirely subjective though, and I've no strong
> > technical
> > reason not to follow through with the tox approach. If Ben et al
> > are
> > happy with this, then so am I.
> 
> I suppose another option would be to have this available, but not run
> by make.  We can document that if you have trouble with using sphinx
> directly, you can re-run configure --without-sphinx and then run tox
> manually to build the docs.

So keep make as-is and provide tox as an alternative? I would prefer
this, yes. We could still highlight the virtualenv instructions for
people that wish to use make too.

We could also do as someone suggested and just remove all 'code-block'
directives, removing any reliance on Pygments (which seems to be the
main culprit here). Syntax highlighting is nice, but a simpler build is
perhaps nicer.

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

Re: [ovs-dev] [PATCH] CONTRIBUTING.rst: Fix links.

[Stephen Finucane]

On Fri, 2017-03-17 at 11:27 -0700, Joe Stringer wrote:
> Signed-off-by: Joe Stringer 

Acked-by: Stephen Finucane 
___
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

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

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 
> > Cc: Ciara Loftus 
> > Cc: Kevin Traynor 
> > ---
> >  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 perspective.

Stephen 

> Ian

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

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

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

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

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

[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 
---
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 th

[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 
---
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 driv

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

[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 
---
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 100

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