[ovs-dev] [patch_v4 2/2] ovn: Reformat some ovn design documentation.

Darrell Ball dlu998 at gmail.com
Thu Jul 7 05:09:28 UTC 2016


Some design micro-details (e.g.) register assignments) that may change
over time were moved from the ovn-architecture.7.xml document to the
OVN-DESIGN.md document.  A table is added to summarize and quantify
MFF logical metadata and register usage.  The OVN-DESIGN.md file was
tested using the following markdown parsers:

https://jbt.github.io/markdown-editor/
http://dillinger.io/

The new flags register usage is also documented in the new
OVN-DESIGN.md document.

Signed-off-by: Darrell Ball <dlu998 at gmail.com>
---
 ovn/OVN-DESIGN.md          | 185 ++++++++++++++++++++++++++++++++++++++++++++
 ovn/automake.mk            |   1 +
 ovn/ovn-architecture.7.xml | 188 ---------------------------------------------
 3 files changed, 186 insertions(+), 188 deletions(-)
 create mode 100644 ovn/OVN-DESIGN.md

diff --git a/ovn/OVN-DESIGN.md b/ovn/OVN-DESIGN.md
new file mode 100644
index 0000000..ec3f0c4
--- /dev/null
+++ b/ovn/OVN-DESIGN.md
@@ -0,0 +1,185 @@
+OVN register and metadata usage:
+-------------------------------
+
+logical datapath field:
+
+A field that denotes the logical datapath through which a packet is being
+processed.
+*Keep the following in sync with MFF_LOG_DATAPATH in*
+*ovn/lib/logical-fields.h.*
+OVN uses the field that OpenFlow 1.1+ simply (and confusingly) calls
+'metadata' to store the logical datapath.  (This field is passed across
+tunnels as part of the tunnel key.)
+
+
+logical input port field:
+
+A field that denotes the logical port from which the packet entered the
+logical datapath.
+*Keep the following in sync with MFF_LOG_INPORT in*
+*ovn/lib/logical-fields.h.*
+OVN stores this in Nicira extension register number 6.
+
+Geneve and STT tunnels pass this field as part of the tunnel key.
+Although VXLAN tunnels do not explicitly carry a logical input port,
+OVN only uses VXLAN to communicate with gateways that from OVN's
+perspective consist of only a single logical port, so that OVN can set
+the logical input port field to this one on ingress to the OVN logical
+pipeline.
+
+
+logical output port field:
+
+A field that denotes the logical port from which the packet will leave
+the logical datapath.  This is initialized to 0 at the beginning of the
+logical ingress pipeline.
+*Keep the following in sync with MFF_LOG_OUTPORT in*
+*ovn/lib/logical-fields.h.*
+OVN stores this in Nicira extension register number 7.
+
+Geneve and STT tunnels pass this field as part of the tunnel key.  VXLAN
+tunnels do not transmit the logical output port field.
+
+
+conntrack zone field for logical ports:
+
+A field that denotes the connection tracking zone for logical ports.
+The value only has local significance and is not meaningful between
+chassis.  This is initialized to 0 at the beginning of the logical
+ingress pipeline.  OVN stores this in Nicira extension register number 5.
+
+
+conntrack zone fields for Gateway router:
+
+Fields that denote the connection tracking zones for Gateway routers.
+These values only have local significance (only on chassis that have
+Gateway routers instantiated) and is not meaningful between
+chassis.  OVN stores the zone information for DNATting in Nicira
+extension register number 3 and zone information for SNATing in Nicira
+extension register number 4.
+
+
+flags field:
+
+Scratchpad flags that denote the pipeline state between tables.  The
+values only have local significance and are not meaningful between
+chassis.  This is initialized to 0 at the beginning of the logical
+ingress pipeline. 
+*Keep the following in sync with MFF_LOG_FLAGS in*
+*ovn/lib/logical-fields.h.*
+OVN stores this in Nicira extension register number 2.
+
+
+VLAN ID:
+
+The VLAN ID is used as an interface between OVN and containers nested
+inside a VM (see Life Cycle of a container interface inside a VM, in 
+ovn-architecture.7.xml, for more information).
+
+
+The following table summarizes the register and metadata usage for OVN.
+*Keep the following in sync with MFF_LOG_FLAGS in*
+*ovn/lib/logical-fields.h.*:
+
+```
+
+  Register/Metadata         Usage                      Bits (Used/Total)
+  ----------------        ---------                    --------------
+  MFF_METADATA         logical datapath                      24/64
+  MFF_REG0             generic scratch                       32/32
+  MFF_REG1             generic scratch                       32/32
+  MFF_REG2             flags                                  1/32
+  MFF_REG3             conntrack dnat zone gateway           16/32
+  MFF_REG4             conntrack snat zone gateway           16/32
+  MFF_REG5             conntrack zone logical ports          16/32
+  MFF_REG6             logical input port                    15/32
+  MFF_REG7             logical output port                   16/32
+
+```
+
+OVN Tunnel Encapsulations:
+-------------------------
+
+tunnel key:
+
+When OVN encapsulates a packet in Geneve or another tunnel, it attaches
+extra data to it to allow the receiving OVN instance to process it
+correctly.  This takes different forms depending on the particular
+encapsulation, but in each case we refer to it here as the 'tunnel key'.
+
+OVN supports three types of IP tunnel encapsulations used in the IP mesh
+connecting HVs, physical switches, appliances and/or servers.  OVN passes
+packet context information across tunnels.
+
+OVN annotates logical network packets that it sends from one hypervisor to
+another with the following three pieces of metadata, which are encoded in an
+encapsulation-specific fashion.
+
+
+24-bit logical datapath identifier:
+This is derived from the tunnel_key column in the OVN Southbound
+Datapath_Binding table.
+ 
+15-bit logical ingress port identifier:
+ID 0 is reserved for internal use within OVN.  IDs 1 through 32767, inclusive,
+may be assigned to logical ports (see the tunnel_key column in the OVN
+Southbound Port_Binding table).
+
+16-bit logical egress port identifier:
+IDs 0 through 32767 have the same meaning as for logical ingress ports. IDs
+32768 through 65535, inclusive, may be assigned to logical multicast groups
+(see the tunnel_key column in the OVN Southbound Multicast_Group table).
+
+For hypervisor-to-hypervisor traffic, OVN supports only Geneve and STT
+encapsulations, for the following reasons:
+
+Only STT and Geneve support the large amounts of metadata (over 32 bits per
+packet) that OVN uses (as described above).
+
+STT and Geneve use randomized UDP or TCP source ports that allows efficient
+distribution among multiple paths in environments that use ECMP in their
+underlay.
+
+NICs are available to offload STT and Geneve encapsulation and decapsulation.
+ 
+Due to its flexibility, the preferred encapsulation between hypervisors is
+Geneve.  For Geneve encapsulation, OVN transmits the logical datapath
+identifier in the Geneve VNI.
+
+*Keep the following in sync with ovn/controller/physical.h.*
+OVN transmits the logical ingress and logical egress ports in a TLV with
+class 0x0102, type 0, and a 32-bit value encoded as follows, from MSB to
+LSB:
+
+```
+
+      1          15             16
+  -----------------------------------------
+  |       |                |              |
+  |  resv |  ingress port  |  egress port |
+  |       |                |              |
+  -----------------------------------------
+ ``` 
+
+Environments whose NICs lack Geneve offload may prefer STT encapsulation
+for performance reasons.  For STT encapsulation, OVN encodes all three
+pieces of logical metadata in the STT 64-bit tunnel ID as follows, from MSB
+to LSB:
+
+```
+
+      9          15              16             24
+  ------------------------------------------------------
+  |       |                |              |            |
+  |  resv |  ingress port  |  egress port |  datapath  |
+  |       |                |              |            |
+  ------------------------------------------------------
+```
+
+For connecting to gateways, in addition to Geneve and STT, OVN supports
+VXLAN, because only VXLAN support is common on top-of-rack (ToR) switches.
+Currently, gateways have a feature set that matches the capabilities as
+defined by the VTEP schema, so fewer bits of metadata are necessary.  In
+the future, gateways that do not support encapsulations with large amounts
+of metadata may continue to have a reduced feature set.
+
diff --git a/ovn/automake.mk b/ovn/automake.mk
index f3f40e5..39277de 100644
--- a/ovn/automake.mk
+++ b/ovn/automake.mk
@@ -73,6 +73,7 @@ DISTCLEANFILES += ovn/ovn-architecture.7
 EXTRA_DIST += \
 	ovn/TODO \
 	ovn/CONTAINERS.OpenStack.md \
+        ovn/OVN-DESIGN.md \
 	ovn/OVN-GW-HA.md
 
 # Version checking for ovn-nb.ovsschema.
diff --git a/ovn/ovn-architecture.7.xml b/ovn/ovn-architecture.7.xml
index 72786bc..e023818 100644
--- a/ovn/ovn-architecture.7.xml
+++ b/ovn/ovn-architecture.7.xml
@@ -609,95 +609,6 @@
   </p>
 
   <p>
-    This section mentions several data and metadata fields, for clarity
-    summarized here:
-  </p>
-
-  <dl>
-    <dt>tunnel key</dt>
-    <dd>
-      When OVN encapsulates a packet in Geneve or another tunnel, it attaches
-      extra data to it to allow the receiving OVN instance to process it
-      correctly.  This takes different forms depending on the particular
-      encapsulation, but in each case we refer to it here as the ``tunnel
-      key.''  See <code>Tunnel Encapsulations</code>, below, for details.
-    </dd>
-
-    <dt>logical datapath field</dt>
-    <dd>
-      A field that denotes the logical datapath through which a packet is being
-      processed.
-      <!-- Keep the following in sync with MFF_LOG_DATAPATH in
-           ovn/lib/logical-fields.h. -->
-      OVN uses the field that OpenFlow 1.1+ simply (and confusingly) calls
-      ``metadata'' to store the logical datapath.  (This field is passed across
-      tunnels as part of the tunnel key.)
-    </dd>
-
-    <dt>logical input port field</dt>
-    <dd>
-      <p>
-        A field that denotes the logical port from which the packet
-        entered the logical datapath.
-        <!-- Keep the following in sync with MFF_LOG_INPORT in
-             ovn/lib/logical-fields.h. -->
-        OVN stores this in Nicira extension register number 6.
-      </p>
-
-      <p>
-        Geneve and STT tunnels pass this field as part of the tunnel key.
-        Although VXLAN tunnels do not explicitly carry a logical input port,
-        OVN only uses VXLAN to communicate with gateways that from OVN's
-        perspective consist of only a single logical port, so that OVN can set
-        the logical input port field to this one on ingress to the OVN logical
-        pipeline.
-      </p>
-    </dd>
-
-    <dt>logical output port field</dt>
-    <dd>
-      <p>
-        A field that denotes the logical port from which the packet will
-        leave the logical datapath.  This is initialized to 0 at the
-        beginning of the logical ingress pipeline.
-        <!-- Keep the following in sync with MFF_LOG_OUTPORT in
-             ovn/lib/logical-fields.h. -->
-        OVN stores this in Nicira extension register number 7.
-      </p>
-
-      <p>
-        Geneve and STT tunnels pass this field as part of the tunnel key.
-        VXLAN tunnels do not transmit the logical output port field.
-      </p>
-    </dd>
-
-    <dt>conntrack zone field for logical ports</dt>
-    <dd>
-      A field that denotes the connection tracking zone for logical ports.
-      The value only has local significance and is not meaningful between
-      chassis.  This is initialized to 0 at the beginning of the logical
-      ingress pipeline.  OVN stores this in Nicira extension register number 5.
-    </dd>
-
-    <dt>conntrack zone fields for Gateway router</dt>
-    <dd>
-      Fields that denote the connection tracking zones for Gateway routers.
-      These values only have local significance (only on chassis that have
-      Gateway routers instantiated) and is not meaningful between
-      chassis.  OVN stores the zone information for DNATting in Nicira
-      extension register number 3 and zone information for SNATing in Nicira
-      extension register number 4.
-    </dd>
-
-    <dt>VLAN ID</dt>
-    <dd>
-      The VLAN ID is used as an interface between OVN and containers nested
-      inside a VM (see <code>Life Cycle of a container interface inside a
-      VM</code>, above, for more information).
-    </dd>
-  </dl>
-
-  <p>
     Initially, a VM or container on the ingress hypervisor sends a packet on a
     port attached to the OVN integration bridge.  Then:
   </p>
@@ -998,103 +909,4 @@
       entries and the <code>Logical_Switch</code> tunnel keys.
     </li>
   </ol>
-
-  <h1>Design Decisions</h1>
-
-  <h2>Tunnel Encapsulations</h2>
-
-  <p>
-    OVN annotates logical network packets that it sends from one hypervisor to
-    another with the following three pieces of metadata, which are encoded in
-    an encapsulation-specific fashion:
-  </p>
-
-  <ul>
-    <li>
-      24-bit logical datapath identifier, from the <code>tunnel_key</code>
-      column in the OVN Southbound <code>Datapath_Binding</code> table.
-    </li>
-
-    <li>
-      15-bit logical ingress port identifier.  ID 0 is reserved for internal
-      use within OVN.  IDs 1 through 32767, inclusive, may be assigned to
-      logical ports (see the <code>tunnel_key</code> column in the OVN
-      Southbound <code>Port_Binding</code> table).
-    </li>
-
-    <li>
-      16-bit logical egress port identifier.  IDs 0 through 32767 have the same
-      meaning as for logical ingress ports.  IDs 32768 through 65535,
-      inclusive, may be assigned to logical multicast groups (see the
-      <code>tunnel_key</code> column in the OVN Southbound
-      <code>Multicast_Group</code> table).
-    </li>
-  </ul>
-
-  <p>
-    For hypervisor-to-hypervisor traffic, OVN supports only Geneve and STT
-    encapsulations, for the following reasons:
-  </p>
-
-  <ul>
-    <li>
-      Only STT and Geneve support the large amounts of metadata (over 32 bits
-      per packet) that OVN uses (as described above).
-    </li>
-
-    <li>
-      STT and Geneve use randomized UDP or TCP source ports that allows
-      efficient distribution among multiple paths in environments that use ECMP
-      in their underlay.
-    </li>
-
-    <li>
-      NICs are available to offload STT and Geneve encapsulation and
-      decapsulation.
-    </li>
-  </ul>
-
-  <p>
-    Due to its flexibility, the preferred encapsulation between hypervisors is
-    Geneve.  For Geneve encapsulation, OVN transmits the logical datapath
-    identifier in the Geneve VNI.
-
-    <!-- Keep the following in sync with ovn/controller/physical.h. -->
-    OVN transmits the logical ingress and logical egress ports in a TLV with
-    class 0x0102, type 0, and a 32-bit value encoded as follows, from MSB to
-    LSB:
-  </p>
-
-  <diagram>
-    <header name="">
-      <bits name="rsv" above="1" below="0" width=".25"/>
-      <bits name="ingress port" above="15" width=".75"/>
-      <bits name="egress port" above="16" width=".75"/>
-    </header>
-  </diagram>
-
-  <p>
-    Environments whose NICs lack Geneve offload may prefer STT encapsulation
-    for performance reasons.  For STT encapsulation, OVN encodes all three
-    pieces of logical metadata in the STT 64-bit tunnel ID as follows, from MSB
-    to LSB:
-  </p>
-
-  <diagram>
-    <header name="">
-      <bits name="reserved" above="9" below="0" width=".5"/>
-      <bits name="ingress port" above="15" width=".75"/>
-      <bits name="egress port" above="16" width=".75"/>
-      <bits name="datapath" above="24" width="1.25"/>
-    </header>
-  </diagram>
-
-  <p>
-    For connecting to gateways, in addition to Geneve and STT, OVN supports
-    VXLAN, because only VXLAN support is common on top-of-rack (ToR) switches.
-    Currently, gateways have a feature set that matches the capabilities as
-    defined by the VTEP schema, so fewer bits of metadata are necessary.  In
-    the future, gateways that do not support encapsulations with large amounts
-    of metadata may continue to have a reduced feature set.
-  </p>
 </manpage>
-- 
1.9.1




More information about the dev mailing list