]>
Commit | Line | Data |
---|---|---|
bc34d060 BP |
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 | ||
fa066f01 BP |
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 | ||
bc34d060 BP |
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 | |
0acc0c98 JP |
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. | |
bc34d060 | 100 | |
0acc0c98 JP |
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". | |
bc34d060 BP |
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 | |
15c93f41 | 146 | talks to an Open vSwitch-specific kernel module (whose sources |
bc34d060 BP |
147 | are in the "datapath" directory). The kernel module performs |
148 | all of the switching work, passing packets that do not match any | |
15c93f41 | 149 | flow table entry up to userspace. This dpif implementation is |
bc34d060 BP |
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 | ||
59348dba JP |
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. | |
bc34d060 | 220 | |
6e8e271c BP |
221 | Miscellaneous Notes |
222 | ------------------- | |
223 | ||
e251c8d0 BP |
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. | |
6e8e271c | 227 | |
ce887677 BP |
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 | ||
bc34d060 BP |
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. |