diff mbox

[ovs-dev,04/31] fixup: Improve documentation.

Message ID 20170612222856.14108-5-blp@ovn.org
State Superseded
Headers show

Commit Message

Ben Pfaff June 12, 2017, 10:28 p.m. UTC
Signed-off-by: Ben Pfaff <blp@ovn.org>
---
 lib/meta-flow.xml | 131 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 90 insertions(+), 41 deletions(-)

Comments

Jan Scheurich June 14, 2017, 6:22 p.m. UTC | #1
These changes look good but need to be subject to major rewriting if property packet-type-aware is removed.

> -----Original Message-----
> From: ovs-dev-bounces@openvswitch.org [mailto:ovs-dev-bounces@openvswitch.org] On Behalf Of Ben Pfaff
> Sent: Tuesday, 13 June, 2017 00:28
> To: dev@openvswitch.org
> Cc: Ben Pfaff <blp@ovn.org>
> Subject: [ovs-dev] [PATCH 04/31] fixup: Improve documentation.
> 
> Signed-off-by: Ben Pfaff <blp@ovn.org>
> ---
>  lib/meta-flow.xml | 131 +++++++++++++++++++++++++++++++++++++-----------------
>  1 file changed, 90 insertions(+), 41 deletions(-)
> 
> diff --git a/lib/meta-flow.xml b/lib/meta-flow.xml
> index c94288e4c294..82daaaffcb44 100644
> --- a/lib/meta-flow.xml
> +++ b/lib/meta-flow.xml
> @@ -24,20 +24,21 @@
>    <p>
>      Data fields that are always present as a consequence of the basic
>      networking technology in use are called called <dfn>root fields</dfn>.
> -    In earlier versions of Open vSwitch, the Ethernet header was always
> -    present and, as a consequence, the Ethernet header fields were root fields.
> -    This remains the default mode of operation of Open vSwitch.  When packets
> -    are received from a "layer3" Tunnel which does not encapsulate an Ethernet
> -    header (such as LISP or GRE), Open vSwitch synthesizes one.
> +    Open vSwitch 2.7 and earlier considered Ethernet fields to be root fields,
> +    and this remains the default mode of operation for Open vSwitch bridges.
> +    In this mode, when a packet is received from a non-Ethernet interfaces,
> +    such as a layer-3 LISP or GRE tunnel, Open vSwitch force-fits it to this
> +    Ethernet-centric point of view by pretending that an Ethernet header is
> +    present whose Ethernet type that indicates the packet's actual type (and
> +    whose source and destination addresses are all-zero).
>    </p>
> 
>    <p>
> -    The present version of Open vSwitch supports the concept of packet type-
> -    aware pipeline introduced in OpenFlow 1.5.  A bridge configured as packet
> +    Open vSwitch 2.8 and later supports the ``packet type-aware pipeline''
> +    concept introduced in OpenFlow 1.5.  A bridge configured to be packet
>      type-aware can handle packets of multiple networking technologies, such as
> -    Ethernet, IP, ARP, MPLS, or NSH in parallel.
> -    The new packet type data metadata field <cite>packet_type</cite> becomes
> -    the single root field and determines the applicability of all data fields.
> +    Ethernet, IP, ARP, MPLS, or NSH in parallel.  Such a bridge does not have
> +    any root fields.
>    </p>
> 
>    <p>
> @@ -62,8 +63,8 @@
>      example, one may match (see <cite>Matching</cite>, below) a given
>      field only if the match includes the field's prerequisite,
>      e.g. matching an ARP field is only allowed if one also matches on
> -    Ethertype 0x0806 or the packet_type for ARP in a packet type-aware
> -    bridge.
> +    Ethertype 0x0806 or the <ref field="packet_type"/> for ARP in a packet
> +    type-aware bridge.
>    </p>
> 
>    <p>
> @@ -331,10 +332,10 @@ tcp,tp_src=0x07c0/0xfff0
> 
>    <p>
>      These shorthand notations continue to work in packet type-aware bridges.
> -    The absence of a packet_type match implies packet_type=ethernet, so that
> -    shorthands match on Ethernet packets with the implied eth_type. Please
> -    note that the shorthand <code>ip</code> does not match packets of packet_type
> -    (1,0x800) for IPv4.
> +    The absence of a packet_type match implies
> +    <code>packet_type=ethernet</code>, so that shorthands match on Ethernet
> +    packets with the implied eth_type. Please note that the shorthand
> +    <code>ip</code> does not match packets of packet_type (1,0x800) for IPv4.
>    </p>
> 
> 
> @@ -2289,11 +2290,22 @@ actions=clone(load:0->NXM_OF_IN_PORT[],output:123)
> 
>      <field id="MFF_PACKET_TYPE" title="Packet Type">
>        <p>
> -        Holds the current type of the packet in the format specified in
> -        OpenFlow 1.5. The 32-bit value consists of the name space <code>NS</code>
> -        in the upper 16 bits and a type <code>NS_TYPE</code> (within that name
> -        space) in the lower 16 bits.  For ease of use the packet type field is
> -        specified and displayed in the <code>(NS,NS_TYPE)</code> syntax.
> +        The type of the packet in the format specified in OpenFlow 1.5:
> +      </p>
> +
> +      <diagram>
> +	<header name="Packet type">
> +	  <bits name="ns" above="16" width=".75"/>
> +	  <bits name="ns_type" above="16" width=".75"/>
> +	</header>
> +	<dots/>
> +      </diagram>
> +
> +      <p>
> +        The upper 16 bits, <var>ns</var>, are a namespace.  The meaning of
> +        <var>ns_type</var> depends on the namespace.  The packet type field is
> +        specified and displayed in the format
> +        <code>(<var>ns</var>,<var>ns_type</var>)</code>.
>        </p>
> 
>        <p>
> @@ -2301,33 +2313,70 @@ actions=clone(load:0->NXM_OF_IN_PORT[],output:123)
>          for matching:
>          <dl>
>            <dt><code>(0,0)</code></dt>
> -            <dd>(NS=ONF and NS_TYPE=Ethernet)</dd>
> -          <dt><code>(1,xxxx)</code></dt>
> -            <dd>(NS=Ethertype and xxxx=Ethertype value)</dd>
> +            <dd>Ethernet.</dd>
> +          <dt><code>(1,<var>ethertype</var>)</code></dt>
> +          <dd>
> +            <p>
> +              The specified <var>ethertype</var>.  Open vSwitch can forward
> +              packets with any <var>ethertype</var>, but it can only match on
> +              and process data fields for the following supported packet types:
> +            </p>
> +            <dl>
> +              <dt><code>(1,0x800)</code></dt>  <dd>IPv4</dd>
> +              <dt><code>(1,0x806)</code></dt>  <dd>ARP</dd>
> +              <dt><code>(1,0x86dd)</code></dt> <dd>IPv6</dd>
> +              <dt><code>(1,0x8847)</code></dt> <dd>MPLS</dd>
> +              <dt><code>(1,0x8848)</code></dt> <dd>MPLS multicast</dd>
> +              <dt><code>(1,0x8035)</code></dt> <dd>RARP</dd>
> +              <dt><code>(1,0x894f)</code></dt> <dd>NSH</dd>
> +            </dl>
> +          </dd>
>          </dl>
>        </p>
> 
>        <p>
> -        Even though Open vSwitch can forward packets with any NS_TYPE value
> -        for NS=Ethertype, it can only match on and process data fields for
> -        the following list of supported packet types:
> -        <dl>
> -          <dt><code>(1,0x800)</code></dt>  <dd>IPv4</dd>
> -          <dt><code>(1,0x806)</code></dt>  <dd>ARP</dd>
> -          <dt><code>(1,0x86dd)</code></dt> <dd>IPv6</dd>
> -          <dt><code>(1,0x8847)</code></dt> <dd>MPLS</dd>
> -          <dt><code>(1,0x8848)</code></dt> <dd>MPLS multicast</dd>
> -          <dt><code>(1,0x8035)</code></dt> <dd>RARP</dd>
> -          <dt><code>(1,0x894f)</code></dt> <dd>NSH</dd>
> -        </dl>
> +        Consider the distinction between a packet with <code>packet_type=(0,0),
> +        dl_type=0x800</code> and one with <code>packet_type=(1,0x800)</code>.
> +        The former is an Ethernet frame that contains an IPv4 packet, like
> +        this:
> +      </p>
> +
> +      <diagram>
> +	<header name="Ethernet">
> +	  <bits name="dst" above="48" width="0.4"/>
> +	  <bits name="src" above="48" width="0.4"/>
> +	  <bits name="type" above="16" below="0x800" width="0.4"/>
> +	</header>
> +	<header name="IPv4">
> +	  <bits name="..." width="0.4"/>
> +	  <bits name="proto" above="8" width="0.4"/>
> +	  <bits name="src" above="32" width="0.4"/>
> +	  <bits name="dst" above="32" width="0.4"/>
> +	</header>
> +	<dots/>
> +      </diagram>
> +
> +      <p>
> +        The latter is an IPv4 packet not encapsulated inside any outer frame,
> +        like this:
>        </p>
> 
> +      <diagram>
> +	<header name="IPv4">
> +	  <bits name="..." width="0.4"/>
> +	  <bits name="proto" above="8" width="0.4"/>
> +	  <bits name="src" above="32" width="0.4"/>
> +	  <bits name="dst" above="32" width="0.4"/>
> +	</header>
> +	<dots/>
> +      </diagram>
> +
>        <p>
> -        The packet type field is mandatory if the OVS bridge is configured
> -        to be packet type-aware. In that case the packet type becomes a
> -        pre-requisite for all matches. If it is omitted from the match,
> -        it defaults to <code>(0,0)</code> (Ethernet) for backward
> -        compatibility.
> +        When the OVS bridge is configured to be packet type-aware, <ref
> +        field="packet_type"/> is a pre-requisite for all data field matches.
> +        As a special case to simplify the common case, and for backward
> +        compatibility, when no such match is supplied, Open vSwitch acts as
> +        though a match on <code>(0,0)</code> (Ethernet) had been supplied.
>        </p>
> 
>        <p>
> --
> 2.10.2
> 
> _______________________________________________
> dev mailing list
> dev@openvswitch.org
> https://mail.openvswitch.org/mailman/listinfo/ovs-dev
diff mbox

Patch

diff --git a/lib/meta-flow.xml b/lib/meta-flow.xml
index c94288e4c294..82daaaffcb44 100644
--- a/lib/meta-flow.xml
+++ b/lib/meta-flow.xml
@@ -24,20 +24,21 @@ 
   <p>
     Data fields that are always present as a consequence of the basic
     networking technology in use are called called <dfn>root fields</dfn>.
-    In earlier versions of Open vSwitch, the Ethernet header was always
-    present and, as a consequence, the Ethernet header fields were root fields.
-    This remains the default mode of operation of Open vSwitch.  When packets
-    are received from a "layer3" Tunnel which does not encapsulate an Ethernet
-    header (such as LISP or GRE), Open vSwitch synthesizes one.
+    Open vSwitch 2.7 and earlier considered Ethernet fields to be root fields,
+    and this remains the default mode of operation for Open vSwitch bridges.
+    In this mode, when a packet is received from a non-Ethernet interfaces,
+    such as a layer-3 LISP or GRE tunnel, Open vSwitch force-fits it to this
+    Ethernet-centric point of view by pretending that an Ethernet header is
+    present whose Ethernet type that indicates the packet's actual type (and
+    whose source and destination addresses are all-zero).
   </p>
 
   <p>
-    The present version of Open vSwitch supports the concept of packet type-
-    aware pipeline introduced in OpenFlow 1.5.  A bridge configured as packet
+    Open vSwitch 2.8 and later supports the ``packet type-aware pipeline''
+    concept introduced in OpenFlow 1.5.  A bridge configured to be packet
     type-aware can handle packets of multiple networking technologies, such as
-    Ethernet, IP, ARP, MPLS, or NSH in parallel.
-    The new packet type data metadata field <cite>packet_type</cite> becomes
-    the single root field and determines the applicability of all data fields.
+    Ethernet, IP, ARP, MPLS, or NSH in parallel.  Such a bridge does not have
+    any root fields.
   </p>
 
   <p>
@@ -62,8 +63,8 @@ 
     example, one may match (see <cite>Matching</cite>, below) a given
     field only if the match includes the field's prerequisite,
     e.g. matching an ARP field is only allowed if one also matches on
-    Ethertype 0x0806 or the packet_type for ARP in a packet type-aware
-    bridge.
+    Ethertype 0x0806 or the <ref field="packet_type"/> for ARP in a packet
+    type-aware bridge.
   </p>
 
   <p>
@@ -331,10 +332,10 @@  tcp,tp_src=0x07c0/0xfff0
 
   <p>
     These shorthand notations continue to work in packet type-aware bridges.
-    The absence of a packet_type match implies packet_type=ethernet, so that
-    shorthands match on Ethernet packets with the implied eth_type. Please
-    note that the shorthand <code>ip</code> does not match packets of packet_type
-    (1,0x800) for IPv4.
+    The absence of a packet_type match implies
+    <code>packet_type=ethernet</code>, so that shorthands match on Ethernet
+    packets with the implied eth_type. Please note that the shorthand
+    <code>ip</code> does not match packets of packet_type (1,0x800) for IPv4.
   </p>
 
 
@@ -2289,11 +2290,22 @@  actions=clone(load:0->NXM_OF_IN_PORT[],output:123)
 
     <field id="MFF_PACKET_TYPE" title="Packet Type">
       <p>
-        Holds the current type of the packet in the format specified in
-        OpenFlow 1.5. The 32-bit value consists of the name space <code>NS</code>
-        in the upper 16 bits and a type <code>NS_TYPE</code> (within that name
-        space) in the lower 16 bits.  For ease of use the packet type field is
-        specified and displayed in the <code>(NS,NS_TYPE)</code> syntax.
+        The type of the packet in the format specified in OpenFlow 1.5:
+      </p>
+
+      <diagram>
+	<header name="Packet type">
+	  <bits name="ns" above="16" width=".75"/>
+	  <bits name="ns_type" above="16" width=".75"/>
+	</header>
+	<dots/>
+      </diagram>
+
+      <p>
+        The upper 16 bits, <var>ns</var>, are a namespace.  The meaning of
+        <var>ns_type</var> depends on the namespace.  The packet type field is
+        specified and displayed in the format
+        <code>(<var>ns</var>,<var>ns_type</var>)</code>.
       </p>
 
       <p>
@@ -2301,33 +2313,70 @@  actions=clone(load:0->NXM_OF_IN_PORT[],output:123)
         for matching:
         <dl>
           <dt><code>(0,0)</code></dt>
-            <dd>(NS=ONF and NS_TYPE=Ethernet)</dd>
-          <dt><code>(1,xxxx)</code></dt>
-            <dd>(NS=Ethertype and xxxx=Ethertype value)</dd>
+            <dd>Ethernet.</dd>
+          <dt><code>(1,<var>ethertype</var>)</code></dt>
+          <dd>
+            <p>
+              The specified <var>ethertype</var>.  Open vSwitch can forward
+              packets with any <var>ethertype</var>, but it can only match on
+              and process data fields for the following supported packet types:
+            </p>
+            <dl>
+              <dt><code>(1,0x800)</code></dt>  <dd>IPv4</dd>
+              <dt><code>(1,0x806)</code></dt>  <dd>ARP</dd>
+              <dt><code>(1,0x86dd)</code></dt> <dd>IPv6</dd>
+              <dt><code>(1,0x8847)</code></dt> <dd>MPLS</dd>
+              <dt><code>(1,0x8848)</code></dt> <dd>MPLS multicast</dd>
+              <dt><code>(1,0x8035)</code></dt> <dd>RARP</dd>
+              <dt><code>(1,0x894f)</code></dt> <dd>NSH</dd>
+            </dl>
+          </dd>
         </dl>
       </p>
 
       <p>
-        Even though Open vSwitch can forward packets with any NS_TYPE value
-        for NS=Ethertype, it can only match on and process data fields for
-        the following list of supported packet types:
-        <dl>
-          <dt><code>(1,0x800)</code></dt>  <dd>IPv4</dd>
-          <dt><code>(1,0x806)</code></dt>  <dd>ARP</dd>
-          <dt><code>(1,0x86dd)</code></dt> <dd>IPv6</dd>
-          <dt><code>(1,0x8847)</code></dt> <dd>MPLS</dd>
-          <dt><code>(1,0x8848)</code></dt> <dd>MPLS multicast</dd>
-          <dt><code>(1,0x8035)</code></dt> <dd>RARP</dd>
-          <dt><code>(1,0x894f)</code></dt> <dd>NSH</dd>
-        </dl>
+        Consider the distinction between a packet with <code>packet_type=(0,0),
+        dl_type=0x800</code> and one with <code>packet_type=(1,0x800)</code>.
+        The former is an Ethernet frame that contains an IPv4 packet, like
+        this:
+      </p>
+
+      <diagram>
+	<header name="Ethernet">
+	  <bits name="dst" above="48" width="0.4"/>
+	  <bits name="src" above="48" width="0.4"/>
+	  <bits name="type" above="16" below="0x800" width="0.4"/>
+	</header>
+	<header name="IPv4">
+	  <bits name="..." width="0.4"/>
+	  <bits name="proto" above="8" width="0.4"/>
+	  <bits name="src" above="32" width="0.4"/>
+	  <bits name="dst" above="32" width="0.4"/>
+	</header>
+	<dots/>
+      </diagram>
+
+      <p>
+        The latter is an IPv4 packet not encapsulated inside any outer frame,
+        like this:
       </p>
 
+      <diagram>
+	<header name="IPv4">
+	  <bits name="..." width="0.4"/>
+	  <bits name="proto" above="8" width="0.4"/>
+	  <bits name="src" above="32" width="0.4"/>
+	  <bits name="dst" above="32" width="0.4"/>
+	</header>
+	<dots/>
+      </diagram>
+
       <p>
-        The packet type field is mandatory if the OVS bridge is configured
-        to be packet type-aware. In that case the packet type becomes a
-        pre-requisite for all matches. If it is omitted from the match,
-        it defaults to <code>(0,0)</code> (Ethernet) for backward
-        compatibility.
+        When the OVS bridge is configured to be packet type-aware, <ref
+        field="packet_type"/> is a pre-requisite for all data field matches.
+        As a special case to simplify the common case, and for backward
+        compatibility, when no such match is supplied, Open vSwitch acts as
+        though a match on <code>(0,0)</code> (Ethernet) had been supplied.
       </p>
 
       <p>