Message ID | 20170526141238.31246-2-stephen@that.guru |
---|---|
State | Accepted |
Headers | show |
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.
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 +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
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