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

Stokes, Ian ian.stokes at intel.com
Fri May 11 13:58:24 UTC 2018 

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

Not sure tbh, is there a hard requirement in the docs related to sphinx versions? I didn’t spot any.

> 
> > I wondering is this related to different sphinx versions across the test
> systems.
> >
> > I'll investigate the error that appears on my board if you can look at
> the travis error above.
> 
> What versions of Sphinx are you using locally? I'll see if I can reproduce
> said issue myself too (or at least make sense of it).
> 

I'm using v1.4.8.

Ian

> Stephen
> 
> [1] http://www.sphinx-doc.org/en/master/usage/restructuredtext/directiv
> es.html#directive-toctree
> 
> > Thanks
> > Ian
> > > ---
> > >  Documentation/howto/dpdk.rst        | 51 ++++++++++++++++------------
> ----
> > > -----
> > >  Documentation/topics/dpdk/index.rst |  6 +++++
> > >  2 files changed, 28 insertions(+), 29 deletions(-)
> > >
> > > diff --git a/Documentation/howto/dpdk.rst
> > > b/Documentation/howto/dpdk.rst index 380181db0..6344f1cb0 100644
> > > --- a/Documentation/howto/dpdk.rst
> > > +++ b/Documentation/howto/dpdk.rst
> > > @@ -25,23 +25,26 @@
> > >  Using Open vSwitch with DPDK
> > >  ============================
> > >
> > > -This document describes how to use Open vSwitch with DPDK datapath.
> > > +This document describes how to use Open vSwitch with DPDK datapath.
> > > +For more detailed information, refer to the various :doc:`DPDK
> > > +topic guides </topics/dpdk/index>`.
> > >
> > >  .. 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=0000: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=0000:01:00.0 \
> > >          -- set Interface p1 type=dpdk
> > > options:dpdk-devargs=0000:01:00.1
> > >
> > > -To stop ovs-vswitchd & delete bridge, run::
> > > +To stop :program:`ovs-vswitchd` and delete the bridge, run::
> > >
> > >      $ ovs-appctl -t ovs-vswitchd exit
> > >      $ ovs-appctl -t ovsdb-server exit @@ -137,13 +139,16 @@ Add
> > > test flows to forward packets between DPDK port
> > > 0 and port 1::
> > >
> > >  Transmit traffic into either port. You should see it returned via
> > > the other.
> > >
> > > +More information on the ``dpdk`` ports can be found in
> > > :doc:`/topics/dpdk/phy`.
> > > +
> > >  .. _dpdk-vhost-loopback:
> > >
> > >  PHY-VM-PHY (vHost Loopback)
> > >  ---------------------------
> > >
> > >  Add a userspace bridge, two ``dpdk`` (PHY) ports, and two
> > > ``dpdkvhostuser``
> > > -ports::
> > > +ports. It is assumed that the physical ports are already bound to
> > > +DPDK, as described in :ref:`dpdk-binding-nics`::
> > >
> > >      # Add userspace bridge
> > >      $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=netdev
> > > @@ -
> > > 221,19 +226,7 @@ described in :ref:`dpdk-testpmd`. Once compiled,
> > > run the
> > > application::
> > >      $ set fwd mac retry
> > >      $ start
> > >
> > > -When you finish testing, bind the vNICs back to kernel::
> > > -
> > > -    $ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci
> 0000:00:03.0
> > > -    $ $DPDK_DIR/usertools/dpdk-devbind.py --bind=virtio-pci
> 0000:00:04.0
> > > -
> > > -.. note::
> > > -
> > > -  Valid PCI IDs must be passed in above example. The PCI IDs can be
> > > retrieved
> > > -  like so::
> > > -
> > > -      $ $DPDK_DIR/usertools/dpdk-devbind.py --status
> > > -
> > > -More information on the dpdkvhostuser ports can be found in
> > > +More information on the ``dpdkvhostuser`` ports can be found in
> > >  :doc:`/topics/dpdk/vhost-user`.
> > >
> > >  PHY-VM-PHY (vHost Loopback) (Kernel Forwarding) @@ -277,7 +270,7 @@
> > > devices to bridge ``br0``. Once complete, follow the below steps:
> > >         $ ovs-vsctl set Interface phy0 options:n_rxq=2
> > >         $ ovs-vsctl set Interface phy1 options:n_rxq=2
> > >
> > > -2. Instantiate Guest VM using QEMU cmdline
> > > +2. Instantiate Guest VM using QEMU command line
> > >
> > >     We must configure with appropriate software versions to ensure
> > > this feature
> > >     is supported.
> > > diff --git a/Documentation/topics/dpdk/index.rst
> > > b/Documentation/topics/dpdk/index.rst
> > > index 181f61abb..79d3af379 100644
> > > --- a/Documentation/topics/dpdk/index.rst
> > > +++ b/Documentation/topics/dpdk/index.rst
> > > @@ -30,12 +30,18 @@ The DPDK Datapath
> > >
> > >  .. toctree::
> > >     :maxdepth: 2
> > > +   :caption: Bridges and Ports
> > >
> > >     /topics/dpdk/bridge
> > >     /topics/dpdk/phy
> > >     /topics/dpdk/vhost-user
> > >     /topics/dpdk/ring
> > >     /topics/dpdk/vdev
> > > +
> > > +.. toctree::
> > > +   :maxdepth: 2
> > > +   :caption: Advanced Configuration
> > > +
> > >     /topics/dpdk/pmd
> > >     /topics/dpdk/qos
> > >     /topics/dpdk/pdump
> > > --
> > > 2.14.3
> > >
> > > _______________________________________________
> > > dev mailing list
> > > dev at openvswitch.org
> > > https://mail.openvswitch.org/mailman/listinfo/ovs-dev

More information about the dev mailing list