refactor for new netdev_rx class

[sliver-openvswitch.git] / PORTING

diff --git a/PORTING b/PORTING
index 09458ee..ffde296 100644 (file)
--- a/PORTING
+++ b/PORTING
@@ -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.  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.
 


@@ -192,19 +196,19 @@ into the Open vSwitch architecture:
                |   |    ovs-vswitchd   |<-->ovsdb-server
                |   +-------------------+
                |   |      ofproto      |<-->OpenFlow controllers
                |   |    ovs-vswitchd   |<-->ovsdb-server
                |   +-------------------+
                |   |      ofproto      |<-->OpenFlow controllers

-               |   +--------+-+--------+
-               |   | netdev | |ofproto-|
-     userspace |   +--------+ |  dpif  |
-               |   | netdev | +--------+
-               |   |provider| |  dpif  |
-               |   +---||---+ +--------+
-               |       ||     |  dpif  |
-               |       ||     |provider|
-               |_      ||     +---||---+
-                       ||         ||
-                _  +---||-----+---||---+
-               |   |          |datapath|
-        kernel |   |          +--------+
+               |   +--------+-+--------+  _
+               |   | netdev | |ofproto-|   |
+     userspace |   +--------+ |  dpif  |   |
+               |   | netdev | +--------+   |
+               |   |provider| |  dpif  |   |
+               |   +---||---+ +--------+   |
+               |       ||     |  dpif  |   | implementation of
+               |       ||     |provider|   | ofproto provider
+               |_      ||     +---||---+   |
+                       ||         ||       |
+                _  +---||-----+---||---+   |
+               |   |          |datapath|   |
+        kernel |   |          +--------+  _|

                |   |                   |
                |_  +--------||---------+
                             ||
                |   |                   |
                |_  +--------||---------+
                             ||


@@ -241,10 +245,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.  ovs-openflowd, in the
-utilities directory, is much simpler than ovs-vswitchd.  It may be
-easier to initially bring up ovs-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 +264,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
 ---------