]>
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 | ||
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 | |
0acc0c98 JP |
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. | |
bc34d060 | 84 | |
0acc0c98 JP |
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". | |
bc34d060 BP |
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 | |
15c93f41 | 130 | talks to an Open vSwitch-specific kernel module (whose sources |
bc34d060 BP |
131 | are in the "datapath" directory). The kernel module performs |
132 | all of the switching work, passing packets that do not match any | |
15c93f41 | 133 | flow table entry up to userspace. This dpif implementation is |
bc34d060 BP |
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 | ||
59348dba JP |
200 | * lib/netdev-vport.c provides support for "virtual ports" |
201 | implemented by the Open vSwitch datapath module for the Linux | |
202 | kernel. This may serve as a model for minimal netdev | |
203 | implementations. | |
bc34d060 | 204 | |
6e8e271c BP |
205 | Miscellaneous Notes |
206 | ------------------- | |
207 | ||
e251c8d0 BP |
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. | |
6e8e271c | 211 | |
ce887677 BP |
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 | ||
bc34d060 BP |
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. |