Setting tag sliver-openvswitch-2.2.90-1

[sliver-openvswitch.git] / PORTING

diff --git a/PORTING b/PORTING
index 3a6faa4..88694a4 100644 (file)
--- a/PORTING
+++ b/PORTING
@@ -18,7 +18,7 @@ is a concordance, indexed by the area of the source tree:
         datapath/       vport           ---
         vswitchd/       iface           port
         ofproto/        port            bundle
         datapath/       vport           ---
         vswitchd/       iface           port
         ofproto/        port            bundle

-        lib/bond.c      slave           bond
+        ofproto/bond.c  slave           bond

         lib/lacp.c      slave           lacp
         lib/netdev.c    netdev          ---
         database        Interface       Port
         lib/lacp.c      slave           lacp
         lib/netdev.c    netdev          ---
         database        Interface       Port


@@ -53,7 +53,7 @@ these components should not need to be modified as part of a port:
 
     - "ofproto" is the Open vSwitch library, in ofproto/, that
       implements an OpenFlow switch.  It talks to OpenFlow controllers
 
     - "ofproto" is the Open vSwitch library, in ofproto/, that
       implements an OpenFlow switch.  It talks to OpenFlow controllers

-      over the network and to switch hardware or software to an
+      over the network and to switch hardware or software through an

       "ofproto provider", explained further below.
 
     - "netdev" is the Open vSwitch library, in lib/netdev.c, that
       "ofproto provider", explained further below.
 
     - "netdev" is the Open vSwitch library, in lib/netdev.c, that


@@ -146,7 +146,11 @@ depends on a few different factors:
       other features.  An ofproto provider has to provide its own
       implementations, if the hardware can support them at all.
 
       other features.  An ofproto provider has to provide its own
       implementations, if the hardware can support them at all.
 

-    * A dpif provider is usually easier to implement.
+    * A dpif provider is usually easier to implement, but most
+      appropriate for software switching.  It "explodes" wildcard
+      rules into exact-match entries (with an optional wildcard mask).
+      This allows fast hash lookups in software, but makes
+      inefficient use of TCAMs in hardware that support wildcarding.

 
 The following sections describe how to implement each kind of port.
 
 
 The following sections describe how to implement each kind of port.
 


@@ -156,9 +160,9 @@ ofproto Providers
 
 An "ofproto provider" is what ofproto uses to directly monitor and
 control an OpenFlow-capable switch.  struct ofproto_class, in
 
 An "ofproto provider" is what ofproto uses to directly monitor and
 control an OpenFlow-capable switch.  struct ofproto_class, in

-ofproto/private.h, defines the interfaces to implement a ofproto
-provider for new hardware or software.  That structure contains many
-function pointers, each of which has a comment that is meant to
+ofproto/ofproto-provider.h, defines the interfaces to implement an
+ofproto provider for new hardware or software.  That structure contains
+many function pointers, each of which has a comment that is meant to

 describe its behavior in detail.  If the requirements are unclear,
 please report this as a bug.
 
 describe its behavior in detail.  If the requirements are unclear,
 please report this as a bug.
 


@@ -171,18 +175,26 @@ Writing a dpif Provider
 
 Open vSwitch has a built-in ofproto provider named "ofproto-dpif",
 which is built on top of a library for manipulating datapaths, called
 
 Open vSwitch has a built-in ofproto provider named "ofproto-dpif",
 which is built on top of a library for manipulating datapaths, called

-"dpif".  A "datapath" is a simple flow table, one that supports only
-exact-match flows, that is, flows without wildcards.  When a packet
-arrives on a network device, the datapath looks for it in this
-exact-match table.  If there is a match, then it performs the
-associated actions.  If there is no match, the datapath passes the
-packet up to ofproto-dpif, which maintains an OpenFlow flow table
-(that supports wildcards).  If the packet matches in this flow table,
-then ofproto-dpif executes its actions and inserts a new exact-match
-entry into the dpif flow table.  (Otherwise, ofproto-dpif passes the
+"dpif".  A "datapath" is a simple flow table, one that is only required
+to support exact-match flows, that is, flows without wildcards.  When a
+packet arrives on a network device, the datapath looks for it in this
+table.  If there is a match, then it performs the associated actions.
+If there is no match, the datapath passes the packet up to ofproto-dpif,
+which maintains the full OpenFlow flow table.  If the packet matches in
+this flow table, then ofproto-dpif executes its actions and inserts a
+new entry into the dpif flow table.  (Otherwise, ofproto-dpif passes the

 packet up to ofproto to send the packet to the OpenFlow controller, if
 one is configured.)
 
 packet up to ofproto to send the packet to the OpenFlow controller, if
 one is configured.)
 

+When calculating the dpif flow, ofproto-dpif generates an exact-match
+flow that describes the missed packet.  It makes an effort to figure out
+what fields can be wildcarded based on the switch's configuration and
+OpenFlow flow table.  The dpif is free to ignore the suggested wildcards
+and only support the exact-match entry.  However, if the dpif supports
+wildcarding, then it can use the masks to match multiple flows with
+fewer entries and potentially significantly reduce the number of flow
+misses handled by ofproto-dpif.
+

 The "dpif" library in turn delegates much of its functionality to a
 "dpif provider".  The following diagram shows how dpif providers fit
 into the Open vSwitch architecture:
 The "dpif" library in turn delegates much of its functionality to a
 "dpif provider".  The following diagram shows how dpif providers fit
 into the Open vSwitch architecture:


@@ -197,7 +209,7 @@ into the Open vSwitch architecture:
      userspace |   +--------+ |  dpif  |   |
                |   | netdev | +--------+   |
                |   |provider| |  dpif  |   |
      userspace |   +--------+ |  dpif  |   |
                |   | netdev | +--------+   |
                |   |provider| |  dpif  |   |

-               |   +---||---+ +--------+   | 
+               |   +---||---+ +--------+   |

                |       ||     |  dpif  |   | implementation of
                |       ||     |provider|   | ofproto provider
                |_      ||     +---||---+   |
                |       ||     |  dpif  |   | implementation of
                |       ||     |provider|   | ofproto provider
                |_      ||     +---||---+   |


@@ -241,10 +253,16 @@ ovs_be64 as fixed-width types in network byte order.  Each of the
 latter is equivalent to the one of the former, but the difference in
 name makes the intended use obvious.
 
 latter is equivalent to the one of the former, but the difference in
 name makes the intended use obvious.
 

-ovs-vswitchd is the most sophisticated of ofproto's clients, but
-ofproto can have other clients as well.  test-openflowd, in the
-tests directory, is much simpler than ovs-vswitchd.  It may be
-easier to initially bring up test-openflowd as part of a port.
+The default "fail-mode" for Open vSwitch bridges is "standalone",
+meaning that, when the OpenFlow controllers cannot be contacted, Open
+vSwitch acts as a regular MAC-learning switch.  This works well in
+virtualization environments where there is normally just one uplink
+(either a single physical interface or a bond).  In a more general
+environment, it can create loops.  So, if you are porting to a
+general-purpose switch platform, you should consider changing the
+default "fail-mode" to "secure", which does not behave this way.  See
+documentation for the "fail-mode" column in the Bridge table in
+ovs-vswitchd.conf.db(5) for more information.

 
 lib/entropy.c assumes that it can obtain high-quality random number
 seeds at startup by reading from /dev/urandom.  You will need to
 
 lib/entropy.c assumes that it can obtain high-quality random number
 seeds at startup by reading from /dev/urandom.  You will need to


@@ -254,6 +272,51 @@ vswitchd/system-stats.c only knows how to obtain some statistics on
 Linux.  Optionally you may implement them for your platform as well.
 
 
 Linux.  Optionally you may implement them for your platform as well.
 
 

+Why OVS Does Not Support Hybrid Providers
+-----------------------------------------
+
+The "Porting Strategies" section above describes the "ofproto
+provider" and "dpif provider" porting strategies.  Only an ofproto
+provider can take advantage of hardware TCAM support, and only a dpif
+provider can take advantage of the OVS built-in implementations of
+various features.  It is therefore tempting to suggest a hybrid
+approach that shares the advantages of both strategies.
+
+However, Open vSwitch does not support a hybrid approach.  Doing so
+may be possible, with a significant amount of extra development work,
+but it does not yet seem worthwhile, for the reasons explained below.
+
+First, user surprise is likely when a switch supports a feature only
+with a high performance penalty.  For example, one user questioned why
+adding a particular OpenFlow action to a flow caused a 1,058x slowdown
+on a hardware OpenFlow implementation [1].  The action required the
+flow to be implemented in software.
+
+Given that implementing a flow in software on the slow management CPU
+of a hardware switch causes a major slowdown, software-implemented
+flows would only make sense for very low-volume traffic.  But many of
+the features built into the OVS software switch implementation would
+need to apply to every flow to be useful.  There is no value, for
+example, in applying bonding or 802.1Q VLAN support only to low-volume
+traffic.
+
+Besides supporting features of OpenFlow actions, a hybrid approach
+could also support forms of matching not supported by particular
+switching hardware, by sending all packets that might match a rule to
+software.  But again this can cause an unacceptable slowdown by
+forcing bulk traffic through software in the hardware switch's slow
+management CPU.  Consider, for example, a hardware switch that can
+match on the IPv6 Ethernet type but not on fields in IPv6 headers.  An
+OpenFlow table that matched on the IPv6 Ethernet type would perform
+well, but adding a rule that matched only UDPv6 would force every IPv6
+packet to software, slowing down not just UDPv6 but all IPv6
+processing.
+
+[1] Aaron Rosen, "Modify packet fields extremely slow",
+    openflow-discuss mailing list, June 26, 2011, archived at
+    https://mailman.stanford.edu/pipermail/openflow-discuss/2011-June/002386.html.
+
+

 Questions
 ---------
 
 Questions
 ---------