[ovs-dev] [PATCH 04/31] fixup: Improve documentation.
Ben Pfaff
blp at ovn.org
Mon Jun 12 22:28:29 UTC 2017
Signed-off-by: Ben Pfaff <blp at 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
More information about the dev
mailing list