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