Signed-off-by: Stephen Finucane <step...@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
b...@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@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@openvswitch.org. We will try to use questions
+to improve this porting guide.
--
2.7.4
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
