PORTING

   1          How to Port Open vSwitch to New Software or Hardware
   2          ====================================================
   3
   4 Open vSwitch (OVS) is intended to be easily ported to new software and
   5 hardware platforms.  This document describes the types of changes that
   6 are most likely to be necessary in porting OVS to Unix-like platforms.
   7 (Porting OVS to other kinds of platforms is likely to be more
   8 difficult.)
   9
  10 Vocabulary
  11 ----------
  12
  13 For historical reasons, different words are used for essentially the
  14 same concept in different areas of the Open vSwitch source tree.  Here
  15 is a concordance, indexed by the area of the source tree:
  16
  17         datapath/       vport           ---
  18         vswitchd/       iface           port
  19         ofproto/        port            bundle
  20         lib/bond.c      slave           bond
  21         lib/lacp.c      slave           lacp
  22         lib/netdev.c    netdev          ---
  23         database        Interface       Port
  24
  25
  26 Open vSwitch Architectural Overview
  27 -----------------------------------
  28
  29 The following diagram shows the conceptual architecture of Open
  30 vSwitch from a porter's perspective.
  31                 _                         _
  32                |   +-------------------+   |
  33                |   |   ovs-vswitchd    |   |Generic
  34                |   +-------------------+   |code
  35      userspace |   |      ofproto      |  _|
  36                |   +---------+---------+  _
  37                |   | netdev  |dpif/wdp |   |
  38                |_  +---||----+----||---+   |Code that
  39                 _      ||         ||       |may need
  40                |   +---||-----+---||---+   |porting
  41                |   |          |datapath|  _|
  42         kernel |   |          +--------+
  43                |   |                   |
  44                |_  +-------||----------+
  45                            ||
  46                         physical
  47                           NIC
  48
  49 Some of the components are generic.  Modulo bugs, these components
  50 should not need to be modified as part of a port:
  51
  52     - Near the top of the diagram, "ofproto" is the library in Open vSwitch
  53       that contains the core OpenFlow protocol implementation and switching
  54       functionality.  It is built from source files in the "ofproto"
  55       directory.
  56
  57     - Above ofproto, "ovs-vswitchd", the main Open vSwitch userspace
  58       program, is the primary client for ofproto.  It is built
  59       from source files in the "vswitchd" directory of the Open
  60       vSwitch distribution.
  61
  62       ovs-vswitchd is the most sophisticated of ofproto's clients, but
  63       ofproto can have other clients as well.  Notably, ovs-openflowd,
  64       in the utilities directory, is much simpler (though less
  65       capable) than ovs-vswitchd, and it may be easier to get up and
  66       running as part of a port.
  67
  68 The other components require attention during a port:
  69
  70     - "dpif" or "wdp" is what ofproto uses to directly monitor and
  71       control a "datapath", which is the term used in OVS for a
  72       collection of physical or virtual ports that are exposed over
  73       OpenFlow as a single switch.  A datapath implements a flow
  74       table.
  75
  76     - "netdev" is the interface to "network devices", e.g. eth0 on
  77       Linux.  ofproto expects that every port exposed by a datapath
  78       has a corresponding netdev that it can open with netdev_open().
  79
  80 The following sections talk about these components in more detail.
  81
  82 Which Branch?
  83 -------------
  84
  85 The architectural diagram shows "dpif" and "wdp" as alternatives.
  86 These alternatives correspond to the "master" and "wdp" branches,
  87 respectively, of the Open vSwitch Git repository at
  88 git://openvswitch.org/openvswitch.  Both of these branches currently
  89 represent reasonable porting targets for different purposes:
  90
  91     - The "master" branch is more mature and better tested.  Open
  92       vSwitch releases are made from this branch, and most OVS
  93       development and testing occurs on this branch.
  94
  95     - The "wdp" branch has a software architecture that can take
  96       advantage of hardware with support for wildcards (e.g. TCAMs or
  97       similar).  This branch has known important bugs, but is the basis
  98       of a few ongoing hardware projects, so we expect the quality to
  99       improve rapidly.
 100
 101 Since its architecture is better, in the medium to long term we will
 102 fix the problems in the "wdp" branch and merge it into "master".
 103
 104 In porting OVS, the major difference between the two branches is the
 105 form of the flow table in the datapath:
 106
 107     - On "master", the "dpif" datapath interface maintains a simple
 108       flow table, one that does not support any kind of wildcards.
 109       This flow table essentially acts as a cache.  When a packet
 110       arrives on an interface, the datapath looks for it in this
 111       exact-match table.  If there is a match, then it performs the
 112       associated actions.  If there is no match, the datapath passes
 113       the packet up to "ofproto", which maintains a flow table that
 114       supports wildcards.  If the packet matches in this flow table,
 115       then ofproto executes its actions and inserts a new exact-match
 116       entry into the dpif flow table.  (Otherwise, ofproto sends the
 117       packet to the OpenFlow controller, if one is configured.)
 118
 119       Thus, on the "master" branch, the datapath has little
 120       opportunity to take advantage of hardware support for wildcards,
 121       since it is only ever presented with exact-match flow entries.
 122
 123     - On "wdp", the "wdp" datapath interface maintains a flow table
 124       similar to that of OpenFlow, one that supports wildcards.  Thus,
 125       a wdp datapath can take advantage of hardware support for
 126       wildcards, since it is free to implement the flow table any way
 127       it likes.
 128
 129 The following sections describe the two datapath interfaces in a
 130 little more detail.
 131
 132 dpif: The "master" Branch Datapath
 133 ----------------------------------
 134
 135 struct dpif_class, in lib/dpif-provider.h, defines the
 136 interfaces required to implement a dpif for new hardware or
 137 software.  That structure contains many function pointers, each
 138 of which has a comment that is meant to describe its behavior in
 139 detail.  If the requirements are unclear, please report this as
 140 a bug and we will clarify.
 141
 142 There are two existing dpif implementations that may serve as
 143 useful examples during a port:
 144
 145     * lib/dpif-linux.c is a Linux-specific dpif implementation that
 146       talks to an Open vSwitch-specific kernel module (whose sources
 147       are in the "datapath" directory).  The kernel module performs
 148       all of the switching work, passing packets that do not match any
 149       flow table entry up to userspace.  This dpif implementation is
 150       essentially a wrapper around calls to "ioctl".
 151
 152     * lib/dpif-netdev.c is a generic dpif implementation that performs
 153       all switching internally.  It delegates most of its work to the
 154       "netdev" library (described below).  Using dpif-netdev, instead
 155       of writing a new dpif, can be a simple way to get OVS up and
 156       running on new platforms, but other solutions are likely to
 157       yield higher performance.
 158
 159 "wdp": The "wdp" Branch Datapath
 160 --------------------------------
 161
 162 struct wdp_class, in ofproto/wdp-provider.h, defines the interfaces
 163 required to implement a wdp ("wildcarded datapath") for new hardware
 164 or software.  That structure contains many function pointers, each of
 165 which has a comment that is meant to describe its behavior in detail.
 166 If the requirements are unclear, please report this as a bug and we
 167 will clarify.
 168
 169 The wdp interface is preliminary.  Please let us know if it seems
 170 unsuitable for your purpose.  We will try to improve it.
 171
 172 There is currently only one wdp implementation:
 173
 174     * ofproto/wdp-xflow.c is an adaptation of "master" branch code
 175       that breaks wildcarded flows up into exact-match flows in the
 176       same way that ofproto always does on the "master" branch.  It
 177       delegates its work to exact-match datapath implementations whose
 178       interfaces are identical to "master" branch datapaths, except
 179       that names have been changed from "dpif" to "xfif" ("exact-match
 180       flow interface") and similar.
 181
 182 "netdev": Interface to network devices
 183 --------------------------------------
 184
 185 The netdev interface can be roughly divided into functionality for the
 186 following purposes:
 187
 188     * Functions required to properly implement OpenFlow features.  For
 189       example, OpenFlow requires the ability to report the Ethernet
 190       hardware address of a port.  These functions must be implemented
 191       for minimally correct operation.
 192
 193     * Functions required to implement optional Open vSwitch features.
 194       For example, the Open vSwitch support for in-band control
 195       requires netdev support for inspecting the TCP/IP stack's ARP
 196       table.  These functions must be implemented if the corresponding
 197       OVS features are to work, but may be omitted initially.
 198
 199     * Functions that may be needed in some implementations but not
 200       others.  The dpif-netdev described above, for example, needs to
 201       be able to send and receive packets on a netdev.
 202
 203 struct netdev_class, in lib/netdev-provider.h, defines the interfaces
 204 required to implement a netdev.  That structure contains many function
 205 pointers, each of which has a comment that is meant to describe its
 206 behavior in detail.  If the requirements are unclear, please report
 207 this as a bug and we will clarify.
 208
 209 The existing netdev implementations may serve as useful examples
 210 during a port:
 211
 212     * lib/netdev-linux.c implements netdev functionality for Linux
 213       network devices, using Linux kernel calls.  It may be a good
 214       place to start for full-featured netdev implementations.
 215
 216     * lib/netdev-vport.c provides support for "virtual ports"
 217       implemented by the Open vSwitch datapath module for the Linux
 218       kernel.  This may serve as a model for minimal netdev
 219       implementations.
 220
 221 Miscellaneous Notes
 222 -------------------
 223
 224 lib/entropy.c assumes that it can obtain high-quality random number
 225 seeds at startup by reading from /dev/urandom.  You will need to
 226 modify it if this is not true on your platform.
 227
 228 vswitchd/system-stats.c only knows how to obtain some statistics on
 229 Linux.  Optionally you may implement them for your platform as well.
 230
 231 Questions
 232 ---------
 233
 234 Please direct porting questions to dev@openvswitch.org.  We will try
 235 to use questions to improve this porting guide.