3b3e150523db3b5fe200d01f23019b0a58a5f0fd
[openvswitch] / 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/uuid.c, used in OVSDB, assumes that it can obtain a high-quality
209 random number seed at startup by reading from /dev/urandom.  You may
210 need to modify it if this is not true on your platform.
211
212 Questions
213 ---------
214
215 Please direct porting questions to dev@openvswitch.org.  We will try
216 to use questions to improve this porting guide.