[ovs-dev] ovn-sb.xml: Reorganize Port_Binding documentation.
diff mbox

Message ID 1444163536-26626-1-git-send-email-blp@nicira.com
State Accepted
Headers show

Commit Message

Ben Pfaff Oct. 6, 2015, 8:32 p.m. UTC
This takes advantage of column grouping and the ability to document a key
within a column.

Signed-off-by: Ben Pfaff <blp@nicira.com>
---
 ovn/ovn-sb.xml | 263 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 134 insertions(+), 129 deletions(-)

Comments

Russell Bryant Oct. 6, 2015, 10:17 p.m. UTC | #1
On 10/06/2015 09:32 PM, Ben Pfaff wrote:
> This takes advantage of column grouping and the ability to document a key
> within a column.
> 
> Signed-off-by: Ben Pfaff <blp@nicira.com>

I like the grouping.  The only issue I saw is that "tag" is only
included under "Nested Containers".  It's now used for localnet ports,
as well.

Patch
diff mbox

diff --git a/ovn/ovn-sb.xml b/ovn/ovn-sb.xml
index 2664cd4..d1b37f0 100644
--- a/ovn/ovn-sb.xml
+++ b/ovn/ovn-sb.xml
@@ -957,152 +957,157 @@ 
       overwrite the <code>chassis</code> column with new information.
     </p>
 
-    <column name="datapath">
-      The logical datapath to which the logical port belongs.
-    </column>
-
-    <column name="logical_port">
-      A logical port, taken from <ref table="Logical_Port" column="name"
-      db="OVN_Northbound"/> in the OVN_Northbound database's
-      <ref table="Logical_Port" db="OVN_Northbound"/> table.  OVN does not
-      prescribe a particular format for the logical port ID.
-    </column>
-
-    <column name="type">
-      <p>
-      A type for this logical port.  Logical ports can be used to model
-      other types of connectivity into an OVN logical switch.  Leaving this
-      column blank maintains the default logical port behavior, which
-      is for a VM (or VIF) interface.  The following other types are defined:
-      </p>
-
-      <dl>
-        <dt><code>localnet</code></dt>
-        <dd>A connection to a locally accessible network from each
-        <code>ovn-controller</code> instance.  A logical switch can only
-        have a single <code>localnet</code> port attached and at most one
-        regular logical port.  This is used to model direct connectivity
-        to an existing network.</dd>
-      </dl>
-
-      <dl>
-        <dt><code>vtep</code></dt>
-        <dd>A port to a logical switch on a VTEP gateway chassis.  In order
-        to get this port correctly recognized by the OVN controller, the
-        <ref column="options" table="Port_Binding"/>:<code>vtep-physical-switch</code>
-        and <ref column="options" table="Port_Binding"/>:<code>vtep-logical-switch</code>
-        must also be defined.</dd>
-      </dl>
-    </column>
+    <group title="Core Features">
+      <column name="datapath">
+        The logical datapath to which the logical port belongs.
+      </column>
 
-    <column name="options">
-      <p>
-        This column provides key/value settings specific to the logical port
-        <ref column="type"/>.  The following options are defined:
-      </p>
+      <column name="logical_port">
+        A logical port, taken from <ref table="Logical_Port" column="name"
+        db="OVN_Northbound"/> in the OVN_Northbound database's <ref
+        table="Logical_Port" db="OVN_Northbound"/> table.  OVN does not
+        prescribe a particular format for the logical port ID.
+      </column>
 
-      <dl>
-        <dt><code>network_name</code></dt>
-        <dd>
-          Must be set when <ref column="type"/> is <code>localnet</code>.
-          <code>ovn-controller</code> uses the configuration entry
-          <code>ovn-bridge-mappings</code> to determine how to connect to
-          this network.  <code>ovn-bridge-mappings</code> is a list of
-          network names mapped to a local OVS bridge that provides access
-          to that network.  An example of configuring
-          <code>ovn-bridge-mappings</code> would be:
+      <column name="chassis">
+        The physical location of the logical port.  To successfully identify a
+        chassis, this column must be a <ref table="Chassis"/> record.  This is
+        populated by
+        <code>ovn-controller</code>/<code>ovn-controller-vtep</code>.
+      </column>
 
-          <p>
-            <code>$ ovs-vsctl set open
-            . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1</code>
-          </p>
+      <column name="tunnel_key">
+        <p>
+          A number that represents the logical port in the key (e.g. STT key or
+          Geneve TLV) field carried within tunnel protocol packets.
+        </p>
 
-          <p>
-            Also note that when a logical switch has a <code>localnet</code>
-            port attached, every chassis that may have a local vif attached
-            to that logical switch must have a bridge mapping configured to
-            reach that <code>localnet</code>.  Traffic that arrives on a
-            <code>localnet</code> port is never forwarded over a tunnel to
-            another chassis.
-          </p>
-        </dd>
-      </dl>
+        <p>
+          The tunnel ID must be unique within the scope of a logical datapath.
+        </p>
+      </column>
 
-      <dl>
-        <dt><code>vtep-physical-switch</code></dt>
-        <dd>
-          The name of the VTEP gateway.  Must be set when
-          <ref column="type"/> is <code>vtep</code>.
-        </dd>
-      </dl>
+      <column name="mac">
+        <p>
+          The Ethernet address or addresses used as a source address on the
+          logical port, each in the form
+          <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+          The string <code>unknown</code> is also allowed to indicate that the
+          logical port has an unknown set of (additional) source addresses.
+        </p>
+
+        <p>
+          A VM interface would ordinarily have a single Ethernet address.  A
+          gateway port might initially only have <code>unknown</code>, and then
+          add MAC addresses to the set as it learns new source addresses.
+        </p>
+      </column>
 
-      <dl>
-        <dt><code>vtep-logical-switch</code></dt>
-        <dd>
-          A logical switch name connected by the VTEP gateway.  Must be
-          set when <ref column="type"/> is <code>vtep</code>.
-        </dd>
-      </dl>
-    </column>
+      <column name="type">
+        <p>
+          A type for this logical port.  Logical ports can be used to model other
+          types of connectivity into an OVN logical switch.  The following types
+          are defined:
+        </p>
+
+        <dl>
+          <dt>(empty string)</dt>
+          <dd>VM (or VIF) interface.</dd>
+          <dt><code>localnet</code></dt>
+          <dd>
+            A connection to a locally accessible network from each
+            <code>ovn-controller</code> instance.  A logical switch can only
+            have a single <code>localnet</code> port attached and at most one
+            regular logical port.  This is used to model direct connectivity to
+            an existing network.
+          </dd>
+
+          <dt><code>vtep</code></dt>
+          <dd>
+            A port to a logical switch on a VTEP gateway chassis.  In order to
+            get this port correctly recognized by the OVN controller, the <ref
+            column="options"
+            table="Port_Binding"/>:<code>vtep-physical-switch</code> and <ref
+            column="options"
+            table="Port_Binding"/>:<code>vtep-logical-switch</code> must also
+            be defined.
+          </dd>
+        </dl>
+      </column>
+    </group>
 
-    <column name="tunnel_key">
+    <group title="Localnet Options">
       <p>
-        A number that represents the logical port in the key (e.g. STT key or
-        Geneve TLV) field carried within tunnel protocol packets.
+        These options apply to logical ports with <ref column="type"/> of
+        <code>localnet</code>.
       </p>
 
+      <column name="options" key="network_name">
+        Required.  <code>ovn-controller</code> uses the configuration entry
+        <code>ovn-bridge-mappings</code> to determine how to connect to this
+        network.  <code>ovn-bridge-mappings</code> is a list of network names
+        mapped to a local OVS bridge that provides access to that network.  An
+        example of configuring <code>ovn-bridge-mappings</code> would be:
+
+        <pre>$ ovs-vsctl set open . external-ids:ovn-bridge-mappings=physnet1:br-eth0,physnet2:br-eth1</pre>
+
+        <p>
+          When a logical switch has a <code>localnet</code> port attached,
+          every chassis that may have a local vif attached to that logical
+          switch must have a bridge mapping configured to reach that
+          <code>localnet</code>.  Traffic that arrives on a
+          <code>localnet</code> port is never forwarded over a tunnel to
+          another chassis.
+        </p>
+      </column>
+    </group>
+
+    <group title="VTEP Options">
       <p>
-        The tunnel ID must be unique within the scope of a logical datapath.
+        These options apply to logical ports with <ref column="type"/> of
+        <code>vtep</code>.
       </p>
-    </column>
-
-    <column name="parent_port">
-      For containers created inside a VM, this is taken from
-      <ref table="Logical_Port" column="parent_name" db="OVN_Northbound"/>
-      in the OVN_Northbound database's <ref table="Logical_Port"
-      db="OVN_Northbound"/> table.  It is left empty if
-      <ref column="logical_port"/> belongs to a VM or a container created
-      in the hypervisor.
-    </column>
 
-    <column name="tag">
-     <p>
-      When <ref column="type"/> is empty and <ref column="logical_port"/>
-      identifies the interface of a container spawned inside a VM, this column
-      identifies the VLAN tag in the network traffic associated with that
-      container's network interface. It is left empty if
-      <ref column="logical_port"/> belongs to a VM or a container created in the
-      hypervisor.
-     </p>
-
-     <p>
-      When <ref column="type"/> is set to <code>localnet</code>, this can be
-      set to indicate that the port represents a connection to a specific
-      VLAN on a locally accessible network. The VLAN ID is used to match
-      incoming traffic and is also added to outgoing traffic.
-     </p>
-    </column>
+      <column name="options" key="vtep-physical-switch">
+        Required. The name of the VTEP gateway.
+      </column>
 
-    <column name="chassis">
-      The physical location of the logical port.  To successfully identify a
-      chassis, this column must be a <ref table="Chassis"/> record.  This is
-      populated by <code>ovn-controller</code>/<code>ovn-controller-vtep</code>.
-    </column>
+      <column name="options" key="vtep-logical-switch">
+        Required.  A logical switch name connected by the VTEP gateway.  Must
+        be set when <ref column="type"/> is <code>vtep</code>.
+      </column>
+    </group>
 
-    <column name="mac">
+    <group title="Nested Containers">
       <p>
-        The Ethernet address or addresses used as a source address on the
-        logical port, each in the form
-        <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
-        The string <code>unknown</code> is also allowed to indicate that the
-        logical port has an unknown set of (additional) source addresses.
+        These columns support containers nested within a VM.  They are empty
+        for containers or VMs that run directly on a hypervisor.
       </p>
 
-      <p>
-        A VM interface would ordinarily have a single Ethernet address.  A
-        gateway port might initially only have <code>unknown</code>, and then
-        add MAC addresses to the set as it learns new source addresses.
-      </p>
-    </column>
+      <column name="parent_port">
+        This is taken from
+        <ref table="Logical_Port" column="parent_name" db="OVN_Northbound"/>
+        in the OVN_Northbound database's <ref table="Logical_Port"
+        db="OVN_Northbound"/> table.
+      </column>
+
+      <column name="tag">
+        <p>
+          When <ref column="type"/> is empty and <ref column="logical_port"/>
+          identifies the interface of a container spawned inside a VM, this
+          column identifies the VLAN tag in the network traffic associated with
+          that container's network interface. It is left empty if <ref
+          column="logical_port"/> belongs to a VM or a container created in the
+          hypervisor.
+        </p>
+
+        <p>
+          When <ref column="type"/> is set to <code>localnet</code>, this can
+          be set to indicate that the port represents a connection to a
+          specific VLAN on a locally accessible network. The VLAN ID is used to
+          match incoming traffic and is also added to outgoing traffic.
+        </p>
+      </column>
+    </group>
   </table>
 </database>