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

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

Commit Message

Stephen Finucane April 16, 2018, 2:30 p.m.
This concludes the cleanup by fixing some nits and adding some
additional cross-references.

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

Comments

Stokes, Ian April 18, 2018, 3:32 p.m. | #1
> This concludes the cleanup by fixing some nits and adding some additional
> cross-references.
> 

LGTM.

Ian
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
> v2:
> - Add changes to DPDK topic index doc
> ---
>  Documentation/howto/dpdk.rst        | 51 ++++++++++++++++----------------
> -----
>  Documentation/topics/dpdk/index.rst |  6 +++++
>  2 files changed, 28 insertions(+), 29 deletions(-)
> 
> diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
> index e65e7dfaa..199b8be65 100644
> --- a/Documentation/howto/dpdk.rst
> +++ b/Documentation/howto/dpdk.rst
> @@ -25,23 +25,26 @@
>  Using Open vSwitch with DPDK
>  ============================
> 
> -This document describes how to use Open vSwitch with DPDK datapath.
> +This document describes how to use Open vSwitch with DPDK datapath. For
> +more detailed information, refer to the various :doc:`DPDK topic guides
> +</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

Patch

diff --git a/Documentation/howto/dpdk.rst b/Documentation/howto/dpdk.rst
index e65e7dfaa..199b8be65 100644
--- a/Documentation/howto/dpdk.rst
+++ b/Documentation/howto/dpdk.rst
@@ -25,23 +25,26 @@ 
 Using Open vSwitch with DPDK
 ============================
 
-This document describes how to use Open vSwitch with DPDK datapath.
+This document describes how to use Open vSwitch with DPDK datapath. For more
+detailed information, refer to the various :doc:`DPDK topic guides
+</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