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 <[email protected]> > Cc: Ciara Loftus <[email protected]> > Cc: Kevin Traynor <[email protected]>
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 _______________________________________________ dev mailing list [email protected] https://mail.openvswitch.org/mailman/listinfo/ovs-dev
