Message ID | 20170612222856.14108-5-blp@ovn.org |
---|---|
State | Superseded |
Headers | show |
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 --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>
Signed-off-by: Ben Pfaff <blp@ovn.org> --- lib/meta-flow.xml | 131 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 90 insertions(+), 41 deletions(-)