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 <step...@that.guru> > Cc: Ciara Loftus <ciara.lof...@intel.com> > Cc: Kevin Traynor <ktray...@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 > _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev