These changes look good but need to be subject to major rewriting if property packet-type-aware is removed.
> -----Original Message----- > From: ovs-dev-boun...@openvswitch.org > [mailto:ovs-dev-boun...@openvswitch.org] On Behalf Of Ben Pfaff > Sent: Tuesday, 13 June, 2017 00:28 > To: d...@openvswitch.org > Cc: Ben Pfaff <b...@ovn.org> > Subject: [ovs-dev] [PATCH 04/31] fixup: Improve documentation. > > Signed-off-by: Ben Pfaff <b...@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 > d...@openvswitch.org > https://mail.openvswitch.org/mailman/listinfo/ovs-dev _______________________________________________ dev mailing list d...@openvswitch.org https://mail.openvswitch.org/mailman/listinfo/ovs-dev
