[ovs-dev] [PATCH] vswitch.xml: Better document patch ports.

[Ben Pfaff]

Reported-by: Hui Xiang <xianghuir at gmail.com>
Signed-off-by: Ben Pfaff <blp at ovn.org>
---
 AUTHORS.rst          |  1 +
 vswitchd/vswitch.xml | 30 +++++++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index 3a845fdd424b..4a80802dd625 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -444,6 +444,7 @@ Henrik Amren                    henrik at nicira.com
 Hiroshi Tanaka                  htanaka at nicira.com
 Hiroshi Miyata                  miyahiro.dazu at gmail.com
 Hsin-Yi Shen                    shenh at vmware.com
+Hui Xiang                       xianghuir at gmail.com
 Hyojoon Kim                     joonk at gatech.edu
 Igor Ganichev                   iganichev at nicira.com
 Igor Sever                      igor at xorops.com
diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index 074535b588ef..04c771f3fa0f 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -2548,9 +2548,37 @@
 
     <group title="Patch Options">
       <p>
-        Only <code>patch</code> interfaces support these options.
+        These options apply only to <dfn>patch ports</dfn>, that is, interfaces
+        whose <ref column="type"/> column is <code>patch</code>.  Patch ports
+        are mainly a way to connect otherwise independent bridges to one
+        another, similar to how one might plug an Ethernet cable (a ``patch
+        cable'') into two physical switches to connect those switches.  The
+        effect of plugging a patch port into two switches is conceptually
+        similar to that of plugging the two ends of a Linux <code>veth</code>
+        device into those switches, but the implementation of patch ports makes
+        them much more efficient.
       </p>
 
+      <p>
+        Patch ports may connect two different bridges (the usual case) or the
+        same bridge.  In the latter case, take special care to avoid loops,
+        e.g. by programming appropriate flows with OpenFlow.  Patch ports do
+        not work if its ends are attached to bridges on different datapaths,
+        e.g. to connect bridges in <code>system</code> and <code>netdev</code>
+        datapaths.
+      </p>
+
+      <p>
+        The following command creates and connects patch ports <code>p0</code>
+        and <code>p1</code> and adds them to bridges <code>br0</code> and
+        <code>br1</code>, respectively:
+      </p>
+
+      <pre>
+ovs-vsctl add-port br0 p0 -- set Interface p0 type=patch options:peer=p1 \
+       -- add-port br1 p1 -- set Interface p1 type=patch options:peer=p0
+      </pre>
+
       <column name="options" key="peer">
         The <ref column="name"/> of the <ref table="Interface"/> for the other
         side of the patch.  The named <ref table="Interface"/>'s own
-- 
2.10.2