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

Kevin Traynor ktraynor at redhat.com
Mon May 29 15:17:21 UTC 2017


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



More information about the dev mailing list