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

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 <stephen@that.guru>
Cc: Ciara Loftus <ciara.loftus@intel.com>
Cc: Kevin Traynor <ktraynor@redhat.com>
---
 Documentation/topics/dpdk/index.rst      |  1 +
 Documentation/topics/dpdk/ring.rst       | 80 ++++++++++++++++++++++++++++++++
 Documentation/topics/dpdk/vhost-user.rst |  8 ++--
 3 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/topics/dpdk/ring.rst

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 <stephen@that.guru>
> Cc: Ciara Loftus <ciara.loftus@intel.com>
> Cc: Kevin Traynor <ktraynor@redhat.com>

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 0000000..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 <vhost-user>` 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 <vhost-user>`, 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 <vhost-user>` 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
> 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

On 05/26/2017 03:12 PM, 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 <stephen@that.guru>
> Cc: Ciara Loftus <ciara.loftus@intel.com>
> Cc: Kevin Traynor <ktraynor@redhat.com>
> ---
>  Documentation/topics/dpdk/index.rst      |  1 +
>  Documentation/topics/dpdk/ring.rst       | 80 ++++++++++++++++++++++++++++++++
>  Documentation/topics/dpdk/vhost-user.rst |  8 ++--
>  3 files changed, 85 insertions(+), 4 deletions(-)
>  create mode 100644 Documentation/topics/dpdk/ring.rst
> 
> diff --git a/Documentation/topics/dpdk/index.rst b/Documentation/topics/dpdk/index.rst
> index 180ebbf..da148b3 100644
> --- a/Documentation/topics/dpdk/index.rst
> +++ b/Documentation/topics/dpdk/index.rst
> @@ -29,3 +29,4 @@ The DPDK Datapath
>     :maxdepth: 2
>  
>     vhost-user
> +   ring
> diff --git a/Documentation/topics/dpdk/ring.rst b/Documentation/topics/dpdk/ring.rst
> new file mode 100644
> index 0000000..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 <vhost-user>` 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 <vhost-user>`, 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

I'm not sure if "**not** possible" is the right language here and above.
I mean, it should be possible but there are external dependencies which
are gone stale and there is perhaps a better alternative now. Maybe "not
recommended" is strong enough

> +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 <vhost-user>` 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
>

On Fri, May 26, 2017 at 03:12:38PM +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 <stephen@that.guru>
> Cc: Ciara Loftus <ciara.loftus@intel.com>
> Cc: Kevin Traynor <ktraynor@redhat.com>

Thanks for adding to the documentation!  I applied this to master,
folding in your later corrections and Kevin's suggestion.