[ovs-dev] [PATCH 04/15] doc: Convert PORTING to rST

Stephen Finucane stephen at that.guru
Tue Oct 18 20:03:34 UTC 2016


Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 FAQ.md            |   4 +-
 INSTALL.NetBSD.md |   4 +-
 Makefile.am       |   2 +-
 PORTING.md        | 326 -----------------------------------------------------
 PORTING.rst       | 330 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 335 insertions(+), 331 deletions(-)
 delete mode 100644 PORTING.md
 create mode 100644 PORTING.rst

diff --git a/FAQ.md b/FAQ.md
index cfa5e70..9ab5210 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -75,7 +75,7 @@ A: No, Open vSwitch has been ported to a number of different operating
 
 ### Q: What's involved with porting Open vSwitch to a new platform or switching ASIC?
 
-A: The [PORTING.md] document describes how one would go about
+A: The [PORTING.rst] document describes how one would go about
    porting Open vSwitch to a new operating system or hardware platform.
 
 ### Q: Why would I use Open vSwitch instead of the Linux bridge?
@@ -2149,7 +2149,7 @@ Contact
 bugs at openvswitch.org
 http://openvswitch.org/
 
-[PORTING.md]:PORTING.md
+[PORTING.rst]:PORTING.rst
 [WHY-OVS.md]:WHY-OVS.md
 [INSTALL.rst]:INSTALL.rst
 [OPENFLOW-1.1+.md]:OPENFLOW-1.1+.md
diff --git a/INSTALL.NetBSD.md b/INSTALL.NetBSD.md
index 3002bad..b89201a 100644
--- a/INSTALL.NetBSD.md
+++ b/INSTALL.NetBSD.md
@@ -31,8 +31,8 @@ As all executables installed with pkgsrc are placed in `/usr/pkg/bin/`
 directory, it might be a good idea to add it to your PATH.
 
 Open vSwitch on NetBSD is currently "userspace switch" implementation
-in the sense described in [INSTALL.userspace.rst] and [PORTING.md].
+in the sense described in [INSTALL.userspace.rst] and [PORTING.rst].
 
 [INSTALL.rst]:INSTALL.rst
 [INSTALL.userspace.rst]:INSTALL.userspace.rst
-[PORTING.md]:PORTING.md
+[PORTING.rst]:PORTING.rst
diff --git a/Makefile.am b/Makefile.am
index 5e55650..73e94ba 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -88,7 +88,7 @@ docs = \
 	IntegrationGuide.rst \
 	MAINTAINERS.rst \
 	OPENFLOW-1.1+.md \
-	PORTING.md \
+	PORTING.rst \
 	README.md \
 	README-lisp.md \
 	README-native-tunneling.md \
diff --git a/PORTING.md b/PORTING.md
deleted file mode 100644
index b7a5073..0000000
--- a/PORTING.md
+++ /dev/null
@@ -1,326 +0,0 @@
-How to Port Open vSwitch to New Software or Hardware
-====================================================
-
-Open vSwitch (OVS) is intended to be easily ported to new software and
-hardware platforms.  This document describes the types of changes that
-are most likely to be necessary in porting OVS to Unix-like platforms.
-(Porting OVS to other kinds of platforms is likely to be more
-difficult.)
-
-
-Vocabulary
-----------
-
-For historical reasons, different words are used for essentially the
-same concept in different areas of the Open vSwitch source tree.  Here
-is a concordance, indexed by the area of the source tree:
-
-        datapath/       vport           ---
-        vswitchd/       iface           port
-        ofproto/        port            bundle
-        ofproto/bond.c  slave           bond
-        lib/lacp.c      slave           lacp
-        lib/netdev.c    netdev          ---
-        database        Interface       Port
-
-
-Open vSwitch Architectural Overview
------------------------------------
-
-The following diagram shows the very high-level architecture of Open
-vSwitch from a porter's perspective.
-
-                   +-------------------+
-                   |    ovs-vswitchd   |<-->ovsdb-server
-                   +-------------------+
-                   |      ofproto      |<-->OpenFlow controllers
-                   +--------+-+--------+
-                   | netdev | | ofproto|
-                   +--------+ |provider|
-                   | netdev | +--------+
-                   |provider|
-                   +--------+
-
-Some of the components are generic.  Modulo bugs or inadequacies,
-these components should not need to be modified as part of a port:
-
-  - "ovs-vswitchd" is the main Open vSwitch userspace program, in
-    vswitchd/.  It reads the desired Open vSwitch configuration from
-    the ovsdb-server program over an IPC channel and passes this
-    configuration down to the "ofproto" library.  It also passes
-    certain status and statistical information from ofproto back
-    into the database.
-
-  - "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 through an
-    "ofproto provider", explained further below.
-
-  - "netdev" is the Open vSwitch library, in lib/netdev.c, that
-    abstracts interacting with network devices, that is, Ethernet
-    interfaces.  The netdev library is a thin layer over "netdev
-    provider" code, explained further below.
-
-The other components may need attention during a port.  You will
-almost certainly have to implement a "netdev provider".  Depending on
-the type of port you are doing and the desired performance, you may
-also have to implement an "ofproto provider" or a lower-level
-component called a "dpif" provider.
-
-The following sections talk about these components in more detail.
-
-
-Writing a netdev Provider
--------------------------
-
-A "netdev provider" implements an operating system and hardware
-specific interface to "network devices", e.g. eth0 on Linux.  Open
-vSwitch must be able to open each port on a switch as a netdev, so you
-will need to implement a "netdev provider" that works with your switch
-hardware and software.
-
-struct netdev_class, in lib/netdev-provider.h, defines the interfaces
-required to implement a netdev.  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.
-
-The netdev interface can be divided into a few rough categories:
-
-  * Functions required to properly implement OpenFlow features.  For
-    example, OpenFlow requires the ability to report the Ethernet
-    hardware address of a port.  These functions must be implemented
-    for minimally correct operation.
-
-  * Functions required to implement optional Open vSwitch features.
-    For example, the Open vSwitch support for in-band control
-    requires netdev support for inspecting the TCP/IP stack's ARP
-    table.  These functions must be implemented if the corresponding
-    OVS features are to work, but may be omitted initially.
-
-  * Functions needed in some implementations but not in others.  For
-    example, most kinds of ports (see below) do not need
-    functionality to receive packets from a network device.
-
-The existing netdev implementations may serve as useful examples
-during a port:
-
-  * lib/netdev-linux.c implements netdev functionality for Linux
-    network devices, using Linux kernel calls.  It may be a good
-    place to start for full-featured netdev implementations.
-
-  * lib/netdev-vport.c provides support for "virtual ports"
-    implemented by the Open vSwitch datapath module for the Linux
-    kernel.  This may serve as a model for minimal netdev
-    implementations.
-
-  * lib/netdev-dummy.c is a fake netdev implementation useful only
-    for testing.
-
-
-Porting Strategies
-------------------
-
-After a netdev provider has been implemented for a system's network
-devices, you may choose among three basic porting strategies.
-
-The lowest-effort strategy is to use the "userspace switch"
-implementation built into Open vSwitch.  This ought to work, without
-writing any more code, as long as the netdev provider that you
-implemented supports receiving packets.  It yields poor performance,
-however, because every packet passes through the ovs-vswitchd process.
-See [INSTALL.userspace.rst] for instructions on how to configure a
-userspace switch.
-
-If the userspace switch is not the right choice for your port, then
-you will have to write more code.  You may implement either an
-"ofproto provider" or a "dpif provider".  Which you should choose
-depends on a few different factors:
-
-  * Only an ofproto provider can take full advantage of hardware
-    with built-in support for wildcards (e.g. an ACL table or a
-    TCAM).
-
-  * A dpif provider can take advantage of the Open vSwitch built-in
-    implementations of bonding, LACP, 802.1ag, 802.1Q VLANs, and
-    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, 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.
-
-
-ofproto Providers
------------------
-
-An "ofproto provider" is what ofproto uses to directly monitor and
-control an OpenFlow-capable switch.  struct ofproto_class, in
-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.
-
-The ofproto provider interface is preliminary.  Please let us know if
-it seems unsuitable for your purpose.  We will try to improve it.
-
-
-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
-"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.)
-
-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:
-
-                _
-               |   +-------------------+
-               |   |    ovs-vswitchd   |<-->ovsdb-server
-               |   +-------------------+
-               |   |      ofproto      |<-->OpenFlow controllers
-               |   +--------+-+--------+  _
-               |   | netdev | |ofproto-|   |
-     userspace |   +--------+ |  dpif  |   |
-               |   | netdev | +--------+   |
-               |   |provider| |  dpif  |   |
-               |   +---||---+ +--------+   |
-               |       ||     |  dpif  |   | implementation of
-               |       ||     |provider|   | ofproto provider
-               |_      ||     +---||---+   |
-                       ||         ||       |
-                _  +---||-----+---||---+   |
-               |   |          |datapath|   |
-        kernel |   |          +--------+  _|
-               |   |                   |
-               |_  +--------||---------+
-                            ||
-                         physical
-                           NIC
-
-struct dpif_class, in lib/dpif-provider.h, defines the interfaces
-required to implement a dpif 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.
-
-There are two existing dpif implementations that may serve as
-useful examples during a port:
-
-  * lib/dpif-netlink.c is a Linux-specific dpif implementation that
-    talks to an Open vSwitch-specific kernel module (whose sources
-    are in the "datapath" directory).  The kernel module performs
-    all of the switching work, passing packets that do not match any
-    flow table entry up to userspace.  This dpif implementation is
-    essentially a wrapper around calls into the kernel module.
-
-  * lib/dpif-netdev.c is a generic dpif implementation that performs
-    all switching internally.  This is how the Open vSwitch
-    userspace switch is implemented.
-
-
-Miscellaneous Notes
--------------------
-
-Open vSwitch source code uses uint16_t, uint32_t, and uint64_t as
-fixed-width types in host byte order, and ovs_be16, ovs_be32, and
-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.
-
-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
-modify it if this is not true on your platform.
-
-vswitchd/system-stats.c only knows how to obtain some statistics on
-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
----------
-
-Please direct porting questions to dev at openvswitch.org.  We will try
-to use questions to improve this porting guide.
-
-[INSTALL.userspace.rst]:INSTALL.userspace.rst
diff --git a/PORTING.rst b/PORTING.rst
new file mode 100644
index 0000000..05a2425
--- /dev/null
+++ b/PORTING.rst
@@ -0,0 +1,330 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+================================================
+Porting Open vSwitch to New Software or Hardware
+================================================
+
+Open vSwitch (OVS) is intended to be easily ported to new software and hardware
+platforms.  This document describes the types of changes that are most likely
+to be necessary in porting OVS to Unix-like platforms.  (Porting OVS to other
+kinds of platforms is likely to be more difficult.)
+
+Vocabulary
+----------
+
+For historical reasons, different words are used for essentially the same
+concept in different areas of the Open vSwitch source tree.  Here is a
+concordance, indexed by the area of the source tree:
+
+::
+
+    datapath/       vport           ---
+    vswitchd/       iface           port
+    ofproto/        port            bundle
+    ofproto/bond.c  slave           bond
+    lib/lacp.c      slave           lacp
+    lib/netdev.c    netdev          ---
+    database        Interface       Port
+
+Open vSwitch Architectural Overview
+-----------------------------------
+
+The following diagram shows the very high-level architecture of Open vSwitch
+from a porter's perspective.
+
+::
+
+    +-------------------+
+    |    ovs-vswitchd   |<-->ovsdb-server
+    +-------------------+
+    |      ofproto      |<-->OpenFlow controllers
+    +--------+-+--------+
+    | netdev | | ofproto|
+    +--------+ |provider|
+    | netdev | +--------+
+    |provider|
+    +--------+
+
+Some of the components are generic.  Modulo bugs or inadequacies, these
+components should not need to be modified as part of a port:
+
+ovs-vswitchd
+  The main Open vSwitch userspace program, in vswitchd/.  It reads the desired
+  Open vSwitch configuration from the ovsdb-server program over an IPC channel
+  and passes this configuration down to the "ofproto" library.  It also passes
+  certain status and statistical information from ofproto back into the
+  database.
+
+ofproto
+  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 through an "ofproto provider", explained further below.
+
+netdev
+  The Open vSwitch library, in lib/netdev.c, that abstracts interacting with
+  network devices, that is, Ethernet interfaces.  The netdev library is a thin
+  layer over "netdev provider" code, explained further below.
+
+The other components may need attention during a port.  You will almost
+certainly have to implement a "netdev provider".  Depending on the type of port
+you are doing and the desired performance, you may also have to implement an
+"ofproto provider" or a lower-level component called a "dpif" provider.
+
+The following sections talk about these components in more detail.
+
+Writing a netdev Provider
+-------------------------
+
+A "netdev provider" implements an operating system and hardware specific
+interface to "network devices", e.g. eth0 on Linux.  Open vSwitch must be able
+to open each port on a switch as a netdev, so you will need to implement a
+"netdev provider" that works with your switch hardware and software.
+
+``struct netdev_class``, in ``lib/netdev-provider.h``, defines the interfaces
+required to implement a netdev.  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, report this as a bug.
+
+The netdev interface can be divided into a few rough categories:
+
+- Functions required to properly implement OpenFlow features.  For example,
+  OpenFlow requires the ability to report the Ethernet hardware address of a
+  port.  These functions must be implemented for minimally correct operation.
+
+- Functions required to implement optional Open vSwitch features.  For example,
+  the Open vSwitch support for in-band control requires netdev support for
+  inspecting the TCP/IP stack's ARP table.  These functions must be implemented
+  if the corresponding OVS features are to work, but may be omitted initially.
+
+- Functions needed in some implementations but not in others.  For example,
+  most kinds of ports (see below) do not need functionality to receive packets
+  from a network device.
+
+The existing netdev implementations may serve as useful examples during a port:
+
+- lib/netdev-linux.c implements netdev functionality for Linux network devices,
+  using Linux kernel calls.  It may be a good place to start for full-featured
+  netdev implementations.
+
+- lib/netdev-vport.c provides support for "virtual ports" implemented by the
+  Open vSwitch datapath module for the Linux kernel.  This may serve as a model
+  for minimal netdev implementations.
+
+- lib/netdev-dummy.c is a fake netdev implementation useful only for testing.
+
+.. _porting strategies:
+
+Porting Strategies
+------------------
+
+After a netdev provider has been implemented for a system's network devices,
+you may choose among three basic porting strategies.
+
+The lowest-effort strategy is to use the "userspace switch" implementation
+built into Open vSwitch.  This ought to work, without writing any more code, as
+long as the netdev provider that you implemented supports receiving packets.
+It yields poor performance, however, because every packet passes through the
+ovs-vswitchd process.  See the `userspace installation guide
+<INSTALL.userspace.md>` for instructions on how to configure a userspace
+switch.
+
+If the userspace switch is not the right choice for your port, then you will
+have to write more code.  You may implement either an "ofproto provider" or a
+"dpif provider".  Which you should choose depends on a few different factors:
+
+* Only an ofproto provider can take full advantage of hardware with built-in
+  support for wildcards (e.g. an ACL table or a TCAM).
+
+* A dpif provider can take advantage of the Open vSwitch built-in
+  implementations of bonding, LACP, 802.1ag, 802.1Q VLANs, and 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, 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.
+
+ofproto Providers
+-----------------
+
+An "ofproto provider" is what ofproto uses to directly monitor and control an
+OpenFlow-capable switch.  ``struct ofproto_class``, in
+``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, report this as a bug.
+
+The ofproto provider interface is preliminary.  Let us know if it seems
+unsuitable for your purpose.  We will try to improve it.
+
+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 "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.)
+
+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:
+
+::
+
+
+    Architecure
+
+               _
+              |   +-------------------+
+              |   |    ovs-vswitchd   |<-->ovsdb-server
+              |   +-------------------+
+              |   |      ofproto      |<-->OpenFlow controllers
+              |   +--------+-+--------+  _
+              |   | netdev | |ofproto-|   |
+    userspace |   +--------+ |  dpif  |   |
+              |   | netdev | +--------+   |
+              |   |provider| |  dpif  |   |
+              |   +---||---+ +--------+   |
+              |       ||     |  dpif  |   | implementation of
+              |       ||     |provider|   | ofproto provider
+              |_      ||     +---||---+   |
+                      ||         ||       |
+               _  +---||-----+---||---+   |
+              |   |          |datapath|   |
+       kernel |   |          +--------+  _|
+              |   |                   |
+              |_  +--------||---------+
+                           ||
+                        physical
+                           NIC
+
+struct ``dpif_class``, in ``lib/dpif-provider.h``, defines the interfaces
+required to implement a dpif 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,
+report this as a bug.
+
+There are two existing dpif implementations that may serve as useful examples
+during a port:
+
+* lib/dpif-netlink.c is a Linux-specific dpif implementation that talks to an
+  Open vSwitch-specific kernel module (whose sources are in the "datapath"
+  directory).  The kernel module performs all of the switching work, passing
+  packets that do not match any flow table entry up to userspace.  This dpif
+  implementation is essentially a wrapper around calls into the kernel module.
+
+* lib/dpif-netdev.c is a generic dpif implementation that performs all
+  switching internally.  This is how the Open vSwitch userspace switch is
+  implemented.
+
+Miscellaneous Notes
+-------------------
+
+Open vSwitch source code uses ``uint16_t``, ``uint32_t``, and ``uint64_t`` as
+fixed-width types in host byte order, and ``ovs_be16``, ``ovs_be32``, and
+``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.
+
+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 modify it if this is
+not true on your platform.
+
+``vswitchd/system-stats.c`` only knows how to obtain some statistics on 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
+---------
+
+Direct porting questions to dev at openvswitch.org.  We will try to use questions
+to improve this porting guide.
-- 
2.7.4




More information about the dev mailing list