1 How to Port Open vSwitch to New Software or Hardware
2 ====================================================
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
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:
22 lib/netdev.c netdev ---
23 database Interface Port
26 Open vSwitch Architectural Overview
27 -----------------------------------
29 The following diagram shows the conceptual architecture of Open
30 vSwitch from a porter's perspective.
32 | +-------------------+ |
33 | | ovs-vswitchd | |Generic
34 | +-------------------+ |code
35 userspace | | ofproto | _|
36 | +---------+---------+ _
37 | | netdev |dpif/wdp | |
38 |_ +---||----+----||---+ |Code that
40 | +---||-----+---||---+ |porting
44 |_ +-------||----------+
49 Some of the components are generic. Modulo bugs, these components
50 should not need to be modified as part of a port:
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"
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
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.
68 The other components require attention during a port:
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
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().
80 The following sections talk about these components in more detail.
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:
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.
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
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".
104 In porting OVS, the major difference between the two branches is the
105 form of the flow table in the datapath:
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.)
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.
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
129 The following sections describe the two datapath interfaces in a
132 dpif: The "master" Branch Datapath
133 ----------------------------------
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.
142 There are two existing dpif implementations that may serve as
143 useful examples during a port:
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".
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.
159 "wdp": The "wdp" Branch Datapath
160 --------------------------------
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
169 The wdp interface is preliminary. Please let us know if it seems
170 unsuitable for your purpose. We will try to improve it.
172 There is currently only one wdp implementation:
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.
182 "netdev": Interface to network devices
183 --------------------------------------
185 The netdev interface can be roughly divided into functionality for the
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.
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.
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.
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.
209 The existing netdev implementations may serve as useful examples
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.
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
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.
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.
234 Please direct porting questions to dev@openvswitch.org. We will try
235 to use questions to improve this porting guide.