[ovs-dev,18/23] ovn-nb.xml: Reorganize documentation for Logical_Port table.
diff mbox

Message ID 1444450838-12150-7-git-send-email-blp@nicira.com
State Accepted
Headers show

Commit Message

Ben Pfaff Oct. 10, 2015, 4:20 a.m. UTC
This uses the column grouping feature and the ability to document an
individual key within a column to better, in my opinion, organize the
documentation for the Logical_Port table.

This will make it easier to document a new port type that a future commit
will add.

Signed-off-by: Ben Pfaff <blp@nicira.com>
---
 ovn/ovn-nb.xml | 382 ++++++++++++++++++++++++++++++---------------------------
 1 file changed, 202 insertions(+), 180 deletions(-)

Comments

Justin Pettit Oct. 16, 2015, 1:21 a.m. UTC | #1
> On Oct 9, 2015, at 9:20 PM, Ben Pfaff <blp@nicira.com> wrote:
> 
> This uses the column grouping feature and the ability to document an
> individual key within a column to better, in my opinion, organize the
> documentation for the Logical_Port table.
> 
> This will make it easier to document a new port type that a future commit
> will add.
> 
> Signed-off-by: Ben Pfaff <blp@nicira.com>

Agreed it looks better.

Acked-by: Justin Pettit <jpettit@nicira.com>

--Justin

Patch
diff mbox

diff --git a/ovn/ovn-nb.xml b/ovn/ovn-nb.xml
index 78b146e..37556cf 100644
--- a/ovn/ovn-nb.xml
+++ b/ovn/ovn-nb.xml
@@ -86,207 +86,229 @@ 
       A port within an L2 logical switch.
     </p>
 
-    <column name="name">
-      <p>
-      The logical port name.
-      </p>
+    <group title="Core Features">
+      <column name="name">
+        <p>
+          The logical port name.
+        </p>
 
-      <p>
-      For entities (VMs or containers) that are spawned in the hypervisor,
-      the name used here must match those used in the <ref key="iface-id"
-      table="Interface" column="external_ids" db="Open_vSwitch"/> in the
-      <ref db="Open_vSwitch"/> database's <ref table="Interface"
-      db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
-      table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
-      key to identify the network interface of that entity.
-      </p>
+        <p>
+          For entities (VMs or containers) that are spawned in the hypervisor,
+          the name used here must match those used in the <ref key="iface-id"
+          table="Interface" column="external_ids" db="Open_vSwitch"/> in the
+          <ref db="Open_vSwitch"/> database's <ref table="Interface"
+          db="Open_vSwitch"/> table, because hypervisors use <ref key="iface-id"
+          table="Interface" column="external_ids" db="Open_vSwitch"/> as a lookup
+          key to identify the network interface of that entity.
+        </p>
 
-      <p>
-      For containers that are spawned inside a VM, the name can be
-      any unique identifier.  In such a case, <ref column="parent_name"/>
-      must be populated.
-      </p>
-    </column>
+        <p>
+          For containers that share a VIF within a VM, the name can be any
+          unique identifier.  See <code>Containers</code>, below, for more
+          information.
+        </p>
+      </column>
 
-    <column name="type">
-      <p>
-      Specify 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>
+      <column name="type">
+        <p>
+          Specify 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><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.  In order
-        to get this port correctly recognized by the OVN controller, the
-        <ref column="options" table="Logical_Port"/>:<code>vtep-physical-switch</code>
-        and <ref column="options" table="Logical_Port"/>:<code>vtep-logical-switch</code>
-        must also be defined.</dd>
-      </dl>
-    </column>
+        <dl>
+          <dt>(empty string)</dt>
+          <dd>
+            A 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.
+          </dd>
+        </dl>
+      </column>
+    </group>
 
-    <column name="options">
-      <p>
+    <group title="Options">
+      <column name="options">
         This column provides key/value settings specific to the logical port
-        <ref column="type"/>.  The following options are defined:
-      </p>
+        <ref column="type"/>.  The type-specific options are described
+        individually below.
+      </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 local configuration to determine
-          exactly how to connect to this locally accessible network.
-        </dd>
-      </dl>
-
-      <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>
-
-      <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>
+      <group title="Options for localnet ports">
+        <p>
+          These options apply when <ref column="type"/> is
+          <code>localnet</code>.
+        </p>
 
-    <column name="parent_name">
-      When <ref column="name"/> identifies the interface of a container
-      spawned inside a tenant VM, this column represents the VM interface
-      through which the container interface sends its network traffic.
-      The name used here must match those used in the <ref key="iface-id"
-      table="Interface" column="external_ids" db="Open_vSwitch"/> in the
-      <ref db="Open_vSwitch"/> table, because hypervisors in this case use
-      <ref key="iface-id" table="Interface" column="external_ids"
-      db="Open_vSwitch"/> as a lookup key to identify the network interface
-      of the tenant VM.
-    </column>
+        <column name="options" key="network_name">
+          Required.  The name of the network to which the <code>localnet</code>
+          port is connected.  Each hypervisor, via <code>ovn-controller</code>,
+          uses its local configuration to determine exactly how to connect to
+          this locally accessible network.
+        </column>
+      </group>
 
-    <column name="tag">
-     <p>
-      When <ref column="type"/> is empty and <ref column="name"/> identifies
-      the interface of a container spawned inside a tenant VM, this column
-      identifies the VLAN tag in the network traffic associated with that
-      container's network interface. When there are multiple container
-      interfaces inside a VM, all of them send their network traffic through a
-      single VM network interface and this value helps OVN identify the correct
-      container interface.
-     </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 title="Options for vtep ports">
+        <p>
+          These options apply when <ref column="type"/> is <code>vtep</code>.
+        </p>
 
-    <column name="up">
-      This column is populated by <code>ovn-northd</code>, rather than by
-      the CMS plugin as is most of this database.  When a logical port is bound
-      to a physical location in the OVN Southbound database <ref
-      db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
-      sets this column to <code>true</code>; otherwise, or if the port
-      becomes unbound later, it sets it to <code>false</code>.  This
-      allows the CMS to wait for a VM's (or container's) networking to
-      become active before it allows the VM (or container) to start.
-    </column>
+        <column name="options" key="vtep-physical-switch">
+          Required.  The name of the VTEP gateway.
+        </column>
 
-    <column name="enabled">
-      This column is used to administratively set port state.  If this column is
-      empty or is set to <code>true</code>, the port is enabled.  If this column
-      is set to <code>false</code>, the port is disabled.  A disabled port has all
-      ingress and egress traffic dropped.
-    </column>
+        <column name="options" key="vtep-logical-switch">
+          Required.  A logical switch name connected by the VTEP gateway.
+        </column>
+      </group>
+    </group>
 
-    <column name="addresses">
+    <group title="Containers">
       <p>
-        Addresses owned by the logical port.
+        When a large number of containers are nested within a VM, it may be too
+        expensive to dedicate a VIF to each container.  OVN can use VLAN tags
+        to support such cases.  Each container is assigned a VLAN ID and each
+        packet that passes between the hypervisor and the VM is tagged with the
+        appropriate ID for the container.  Such VLAN IDs never appear on a
+        physical wire, even inside a tunnel, so they need not be unique except
+        relative to a single VM on a hypervisor.
       </p>
 
       <p>
-        Each element in the set must take one of the following forms:
+        These columns are used for VIFs that represent nested containers using
+        shared VIFs.  For VMs and for containers that have dedicated VIFs, they
+        are empty.
       </p>
 
-      <dl>
-        <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
-        <dd>
-          <p>
-            An Ethernet address owned by the logical port.  Like a physical
-            Ethernet NIC, a logical port ordinarily has a single fixed Ethernet
-            address.
-          </p>
-
-          <p>
-            When a OVN logical switch processes a unicast Ethernet frame whose
-            destination MAC address is in a logical port's <ref
-            column="addresses"/> column, it delivers it only to that port, as
-            if a MAC learning process had learned that MAC address on the port.
-          </p>
-        </dd>
-
-        <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
-        <dd>
-          <p>
-            This form has all the effects of the previous form.  It also
-            indicates that the logical port owns the given IPv4 address.
-          </p>
-
-          <p>
-            The OVN logical switch uses this information to synthesize
-            responses to ARP requests without traversing the physical network.
-            The OVN logical router connected to the logical switch, if any,
-            uses this information to avoid issuing ARP requests for logical
-            switch ports.
-          </p>
-        </dd>
-
-        <dt><code>unknown</code></dt>
-        <dd>
-          This indicates that the logical port has an unknown set of Ethernet
-          addresses.  When an OVN logical switch processes a unicast Ethernet
-          frame whose destination MAC address is not in any logical port's <ref
-          column="addresses"/> column, it delivers it to the port (or ports)
-          whose <ref column="addresses"/> columns include <code>unknown</code>.
-        </dd>
-      </dl>
-    </column>
+      <column name="parent_name">
+        The VM interface through which the nested container sends its network
+        traffic.  This must match the <ref column="name"/> column for some
+        other <ref table="Logical_Port"/>.
+      </column>
 
-    <column name="port_security">
-      <p>
-        A set of L2 (Ethernet) addresses
-        from which the logical port is allowed to send packets and to which it
-        is allowed to receive packets.  If this column is empty, all addresses
-        are permitted.  Logical ports are always allowed to receive packets
-        addressed to multicast and broadcast addresses.
-      </p>
+      <column name="tag">
+        <p>
+          The VLAN tag in the network traffic associated with a container's
+          network interface.
+        </p>
 
-      <p>
-        Each member of the set is an Ethernet address in the form
-        <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
-      </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>
 
-      <p>
-	This specification will be extended to support L3 port security.
-      </p>
-    </column>
+    <group title="Port State">
+      <column name="up">
+        This column is populated by <code>ovn-northd</code>, rather than by the
+        CMS plugin as is most of this database.  When a logical port is bound
+        to a physical location in the OVN Southbound database <ref
+        db="OVN_Southbound" table="Binding"/> table, <code>ovn-northd</code>
+        sets this column to <code>true</code>; otherwise, or if the port
+        becomes unbound later, it sets it to <code>false</code>.  This allows
+        the CMS to wait for a VM's (or container's) networking to become active
+        before it allows the VM (or container) to start.
+      </column>
+
+      <column name="enabled">
+        This column is used to administratively set port state.  If this column
+        is empty or is set to <code>true</code>, the port is enabled.  If this
+        column is set to <code>false</code>, the port is disabled.  A disabled
+        port has all ingress and egress traffic dropped.
+      </column>
+
+    </group>
+
+    <group title="Addressing">
+      <column name="addresses">
+        <p>
+          Addresses owned by the logical port.
+        </p>
+
+        <p>
+          Each element in the set must take one of the following forms:
+        </p>
+
+        <dl>
+          <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code></dt>
+          <dd>
+            <p>
+              An Ethernet address owned by the logical port.  Like a physical
+              Ethernet NIC, a logical port ordinarily has a single fixed
+              Ethernet address.
+            </p>
+
+            <p>
+              When a OVN logical switch processes a unicast Ethernet frame
+              whose destination MAC address is in a logical port's <ref
+              column="addresses"/> column, it delivers it only to that port, as
+              if a MAC learning process had learned that MAC address on the
+              port.
+            </p>
+          </dd>
+
+          <dt><code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var> <var>a</var>.<var>b</var>.<var>c</var>.<var>d</var></code></dt>
+          <dd>
+            <p>
+              This form has all the effects of the previous form.  It also
+              indicates that the logical port owns the given IPv4 address.
+            </p>
+
+            <p>
+              The OVN logical switch uses this information to synthesize
+              responses to ARP requests without traversing the physical
+              network.  The OVN logical router connected to the logical switch,
+              if any, uses this information to avoid issuing ARP requests for
+              logical switch ports.
+            </p>
+          </dd>
+
+          <dt><code>unknown</code></dt>
+          <dd>
+            This indicates that the logical port has an unknown set of Ethernet
+            addresses.  When an OVN logical switch processes a unicast Ethernet
+            frame whose destination MAC address is not in any logical port's
+            <ref column="addresses"/> column, it delivers it to the port (or
+            ports) whose <ref column="addresses"/> columns include
+            <code>unknown</code>.
+          </dd>
+        </dl>
+      </column>
+
+      <column name="port_security">
+        <p>
+          A set of L2 (Ethernet) addresses from which the logical port is
+          allowed to send packets and to which it is allowed to receive
+          packets.  If this column is empty, all addresses are permitted.
+          Logical ports are always allowed to receive packets addressed to
+          multicast and broadcast addresses.
+        </p>
+
+        <p>
+          Each member of the set is an Ethernet address in the form
+          <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+        </p>
+
+        <p>
+	  This specification will be extended to support L3 port security.
+        </p>
+      </column>
+    </group>
 
     <group title="Common Columns">
       <column name="external_ids">