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.
  82
  83 Since its architecture is better, in the medium to long term we hope
  84 to fix the problems in the "wdp" branch and merge it into "master".
  85
  86 In porting OVS, the major difference between the two branches is the
  87 form of the flow table in the datapath:
  88
  89     - On "master", the "dpif" datapath interface maintains a simple
  90       flow table, one that does not support any kind of wildcards.
  91       This flow table essentially acts as a cache.  When a packet
  92       arrives on an interface, the datapath looks for it in this
  93       exact-match table.  If there is a match, then it performs the
  94       associated actions.  If there is no match, the datapath passes
  95       the packet up to "ofproto", which maintains a flow table that
  96       supports wildcards.  If the packet matches in this flow table,
  97       then ofproto executes its actions and inserts a new exact-match
  98       entry into the dpif flow table.  (Otherwise, ofproto sends the
  99       packet to the OpenFlow controller, if one is configured.)
 100
 101       Thus, on the "master" branch, the datapath has little
 102       opportunity to take advantage of hardware support for wildcards,
 103       since it is only ever presented with exact-match flow entries.
 104
 105     - On "wdp", the "wdp" datapath interface maintains a flow table
 106       similar to that of OpenFlow, one that supports wildcards.  Thus,
 107       a wdp datapath can take advantage of hardware support for
 108       wildcards, since it is free to implement the flow table any way
 109       it likes.
 110
 111 The following sections describe the two datapath interfaces in a
 112 little more detail.
 113
 114 dpif: The "master" Branch Datapath
 115 ----------------------------------
 116
 117 struct dpif_class, in lib/dpif-provider.h, defines the
 118 interfaces required to implement a dpif for new hardware or
 119 software.  That structure contains many function pointers, each
 120 of which has a comment that is meant to describe its behavior in
 121 detail.  If the requirements are unclear, please report this as
 122 a bug and we will clarify.
 123
 124 There are two existing dpif implementations that may serve as
 125 useful examples during a port:
 126
 127     * lib/dpif-linux.c is a Linux-specific dpif implementation that
 128       talks to a Open vSwitch-specific kernel module (whose sources
 129       are in the "datapath" directory).  The kernel module performs
 130       all of the switching work, passing packets that do not match any
 131       flow table entry down to userspace.  This dpif implementation is
 132       essentially a wrapper around calls to "ioctl".
 133
 134     * lib/dpif-netdev.c is a generic dpif implementation that performs
 135       all switching internally.  It delegates most of its work to the
 136       "netdev" library (described below).  Using dpif-netdev, instead
 137       of writing a new dpif, can be a simple way to get OVS up and
 138       running on new platforms, but other solutions are likely to
 139       yield higher performance.
 140
 141 "wdp": The "wdp" Branch Datapath
 142 --------------------------------
 143
 144 struct wdp_class, in ofproto/wdp-provider.h, defines the interfaces
 145 required to implement a wdp ("wildcarded datapath") for new hardware
 146 or software.  That structure contains many function pointers, each of
 147 which has a comment that is meant to describe its behavior in detail.
 148 If the requirements are unclear, please report this as a bug and we
 149 will clarify.
 150
 151 The wdp interface is preliminary.  Please let us know if it seems
 152 unsuitable for your purpose.  We will try to improve it.
 153
 154 There is currently only one wdp implementation:
 155
 156     * ofproto/wdp-xflow.c is an adaptation of "master" branch code
 157       that breaks wildcarded flows up into exact-match flows in the
 158       same way that ofproto always does on the "master" branch.  It
 159       delegates its work to exact-match datapath implementations whose
 160       interfaces are identical to "master" branch datapaths, except
 161       that names have been changed from "dpif" to "xfif" ("exact-match
 162       flow interface") and similar.
 163
 164 "netdev": Interface to network devices
 165 --------------------------------------
 166
 167 The netdev interface can be roughly divided into functionality for the
 168 following purposes:
 169
 170     * Functions required to properly implement OpenFlow features.  For
 171       example, OpenFlow requires the ability to report the Ethernet
 172       hardware address of a port.  These functions must be implemented
 173       for minimally correct operation.
 174
 175     * Functions required to implement optional Open vSwitch features.
 176       For example, the Open vSwitch support for in-band control
 177       requires netdev support for inspecting the TCP/IP stack's ARP
 178       table.  These functions must be implemented if the corresponding
 179       OVS features are to work, but may be omitted initially.
 180
 181     * Functions that may be needed in some implementations but not
 182       others.  The dpif-netdev described above, for example, needs to
 183       be able to send and receive packets on a netdev.
 184
 185 struct netdev_class, in lib/netdev-provider.h, defines the interfaces
 186 required to implement a netdev.  That structure contains many function
 187 pointers, each of which has a comment that is meant to describe its
 188 behavior in detail.  If the requirements are unclear, please report
 189 this as a bug and we will clarify.
 190
 191 The existing netdev implementations may serve as useful examples
 192 during a port:
 193
 194     * lib/netdev-linux.c implements netdev functionality for Linux
 195       network devices, using Linux kernel calls.  It may be a good
 196       place to start for full-featured netdev implementations.
 197
 198     * lib/netdev-gre.c and lib/netdev-patch.c are minimal
 199       implementations for "virtual ports" implemented by the Open
 200       vSwitch datapath module for the Linux kernel.  They may serve as
 201       a model for minimal netdev implementations.
 202
 203 Questions
 204 ---------
 205
 206 Please direct porting questions to dev@openvswitch.org.  We will try
 207 to use questions to improve this porting guide.