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
+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
--
2.9.4
_______________________________________________
dev mailing list
d...@openvswitch.org
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
