2 * Copyright (c) 2010 Nicira Networks.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at:
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef WDP_PROVIDER_H
18 #define WDP_PROVIDER_H 1
20 /* Provider interface to wdps, which provide an interface to an Open vSwitch
32 static inline struct wdp_rule *
33 wdp_rule_cast(const struct cls_rule *cls_rule)
35 return cls_rule ? CONTAINER_OF(cls_rule, struct wdp_rule, cr) : NULL;
38 /* Open vSwitch datapath interface.
40 * This structure should be treated as opaque by wdp implementations. */
42 const struct wdp_class *wdp_class;
45 uint8_t netflow_engine_type;
46 uint8_t netflow_engine_id;
49 void wdp_init(struct wdp *, const struct wdp_class *, const char *name,
50 uint8_t netflow_engine_type, uint8_t netflow_engine_id);
51 void wdp_uninit(struct wdp *wdp, bool close);
53 static inline void wdp_assert_class(const struct wdp *wdp,
54 const struct wdp_class *wdp_class)
56 assert(wdp->wdp_class == wdp_class);
59 /* Datapath interface class structure, to be defined by each implementation of
60 * a datapath interface.
62 * These functions return 0 if successful or a positive errno value on failure,
63 * except where otherwise noted.
65 * Most of these functions are expected to execute synchronously, that is, to
66 * block as necessary to obtain a result. Thus, these functions may return
67 * EAGAIN (or EWOULDBLOCK or EINPROGRESS) only where the function descriptions
68 * explicitly say those errors are a possibility. We may relax this
69 * requirement in the future if and when we encounter performance problems. */
71 /* Type of wdp in this class, e.g. "system", "netdev", etc.
73 * One of the providers should supply a "system" type, since this is
74 * the type assumed if no type is specified when opening a wdp. */
77 /* Performs periodic work needed by wdps of this class, if any is
81 /* Arranges for poll_block() to wake up if the "run" member function needs
85 /* Enumerates the names of all known created datapaths for 'wdp_class',
86 * if possible, into 'all_wdps'. The caller has already initialized
87 * 'all_wdps' and other wdp classes might already have added names to it.
89 * This is used by the vswitch at startup, so that it can delete any
90 * datapaths that are not configured.
92 * Some kinds of datapaths might not be practically enumerable, in which
93 * case this function may be a null pointer. */
94 int (*enumerate)(const struct wdp_class *wdp_class,
95 struct svec *all_wdps);
97 /* Attempts to open an existing wdp of class 'wdp_class' called 'name',
98 * if 'create' is false, or to open an existing wdp or create a new one,
99 * if 'create' is true.
101 * If successful, stores a pointer to the new wdp in '*wdpp'. On
102 * failure there are no requirements on what is stored in '*wdpp'. */
103 int (*open)(const struct wdp_class *wdp_class, const char *name,
104 bool create, struct wdp **wdpp);
106 /* Closes 'wdp' and frees associated memory. */
107 void (*close)(struct wdp *wdp);
109 /* Enumerates all names that may be used to open 'wdp' into 'all_names'.
110 * The Linux datapath, for example, supports opening a datapath both by
111 * number, e.g. "wdp0", and by the name of the datapath's local port. For
112 * some datapaths, this might be an infinite set (e.g. in a file name,
113 * slashes may be duplicated any number of times), in which case only the
114 * names most likely to be used should be enumerated.
116 * The caller has already initialized 'all_names' and might already have
117 * added some names to it. This function should not disturb any existing
118 * names in 'all_names'.
120 * If a datapath class does not support multiple names for a datapath, this
121 * function may be a null pointer.
123 * This is used by the vswitch at startup, */
124 int (*get_all_names)(const struct wdp *wdp, struct svec *all_names);
126 /* Attempts to destroy the wdp underlying 'wdp'.
128 * If successful, 'wdp' will not be used again except as an argument for
129 * the 'close' member function. */
130 int (*destroy)(struct wdp *wdp);
132 /* Creates a "struct ofp_switch_features" for 'wdp' and stores it in
133 * '*featuresp'. The caller is responsible for freeing '*featuresp' (with
134 * ofpbuf_delete()) when it is no longer needed. */
135 int (*get_features)(const struct wdp *wdp, struct ofpbuf **featuresp);
137 /* Retrieves statistics for 'wdp' into 'stats'. */
138 int (*get_stats)(const struct wdp *wdp, struct wdp_stats *stats);
140 /* Appends to 'stats' one or more 'struct ofp_table_stats' structures that
141 * represent the tables maintained by 'wdp'. Returns 0 if successful,
142 * otherwise an OpenFlow error code constructed with ofp_mkerr(). */
143 int (*get_table_stats)(const struct wdp *wdp, struct ofpbuf *stats);
145 /* Retrieves 'wdp''s current treatment of IP fragments into '*drop_frags':
146 * true indicates that fragments are dropped, false indicates that
147 * fragments are treated in the same way as other IP packets (except that
148 * the L4 header cannot be read). */
149 int (*get_drop_frags)(const struct wdp *wdp, bool *drop_frags);
151 /* Changes 'wdp''s treatment of IP fragments to 'drop_frags', whose meaning
152 * is the same as for the get_drop_frags member function. EOPNOTSUPP
153 * indicates that the datapath does not support changing the fragment
154 * dropping policy, as does a null pointer. */
155 int (*set_drop_frags)(struct wdp *wdp, bool drop_frags);
157 /* Creates a new port in 'wdp' connected to network device 'devname'. If
158 * 'internal' is true, creates the port as an internal port. If
159 * successful, sets '*port_nop' to the new port's port number.
161 * Possible error return values include:
163 * - ENODEV: No device named 'devname' exists (if 'internal' is false).
165 * - EEXIST: A device named 'devname' already exists (if 'internal' is
168 * - EINVAL: Device 'devname' is not supported as part of a datapath
169 * (e.g. it is not an Ethernet device), or 'devname' is too long for a
170 * network device name (if 'internal' is true)
172 * - EFBIG: The datapath already has as many ports as it can support.
174 * - EOPNOTSUPP: 'wdp' has a fixed set of ports.
176 * A null pointer is equivalent to returning EOPNOTSUPP.
178 int (*port_add)(struct wdp *wdp, const char *devname,
179 bool internal, uint16_t *port_nop);
181 /* Removes port numbered 'port_no' from 'wdp'.
183 * Possible error return values include:
185 * - EINVAL: 'port_no' is outside the valid range, or this particular
186 * port is not removable (e.g. it is the local port).
188 * - ENOENT: 'wdp' currently has no port numbered 'port_no'.
190 * - EOPNOTSUPP: 'wdp' has a fixed set of ports.
192 * A null pointer is equivalent to returning EOPNOTSUPP.
194 int (*port_del)(struct wdp *wdp, uint16_t port_no);
196 /* Looks up a port in 'wdp' by name or number. On success, returns 0 and
197 * initializes '*portp'. On failure, returns a positive errno value.
199 * The caller takes ownership of everything in '*portp' and will eventually
200 * free it with, e.g., wdp_port_free(). */
201 int (*port_query_by_number)(const struct wdp *wdp, uint16_t port_no,
202 struct wdp_port *portp);
203 int (*port_query_by_name)(const struct wdp *wdp, const char *devname,
204 struct wdp_port *portp);
206 /* Obtains a list of all the ports in 'wdp'. Sets '*portsp' to point to an
207 * array of port structures and '*n_portsp' to the number of ports in the
210 * The caller takes ownership of '*portsp' and all of the ports in it and
211 * is responsible for freeing the ports and the array with, e.g.,
212 * wdp_port_array_free(). */
213 int (*port_list)(const struct wdp *wdp, struct wdp_port **portsp,
216 /* Updates the configuration for the port number 'port_no' within 'wdp' to
217 * 'config', which is a set of OpenFlow OFPPC_* constants in host byte
218 * order. Returns 0 if successful, otherwise an OpenFlow error code
219 * constructed with ofp_mkerr(). */
220 int (*port_set_config)(struct wdp *wdp, uint16_t port_no,
223 /* Polls for changes in the set of ports in 'wdp' since the last call to
224 * this function or, if this is the first call, since this wdp was opened.
225 * For each change, calls 'cb' passing 'aux' and:
227 * - For a port that has been added, OFPPR_ADD as 'reason' and the new
228 * port's "struct ofp_phy_port" as 'opp'.
230 * - For a port that has been removed, OFPPR_DELETE as 'reason' and the
231 * deleted port's former "struct ofp_phy_port" as 'opp'.
233 * - For a port whose configuration has changed, OFPPR_MODIFY as 'reason'
234 * and the modified port's new "struct ofp_phy_port" as 'opp'.
236 * If 'wdp' has a fixed set of ports, this function must still be present
237 * (to report changes to port configurations) but it will never report
238 * OFPPR_ADD or OFPPR_DELETE as a reason.
240 * 'opp' is in *host* byte order.
242 * Normally returns 0. May also return a positive errno value to indicate
243 * that something has gone wrong.
245 int (*port_poll)(struct wdp *wdp,
246 void (*cb)(const struct ofp_phy_port *opp,
247 uint8_t reason, void *aux),
250 /* Arranges for the poll loop to wake up when 'port_poll' will call its
252 int (*port_poll_wait)(const struct wdp *wdp);
254 /* If 'wdp' contains exactly one flow exactly equal to 'flow' in one of the
255 * tables in the bit-mask in 'include', returns that flow. Otherwise (if
256 * there is no match or more than one match), returns null.
258 * A flow in table 'table_id' is a candidate for matching if 'include & (1u
259 * << table_id)' is nonzero. */
260 struct wdp_rule *(*flow_get)(const struct wdp *wdp,
261 const flow_t *flow, unsigned int include);
263 /* If 'wdp' contains one or more flows that match 'flow', returns the
264 * highest-priority matching flow. If there is more than one
265 * highest-priority match, picks one of them in an arbitrary fashion.
266 * Otherwise returns null.
268 * Ignores 'flow->priority' and 'flow->wildcards'. */
269 struct wdp_rule *(*flow_match)(const struct wdp *wdp,
272 /* Iterates through all of the flows in 'wdp''s flow table, passing each
273 * flow that matches the specified search criteria to 'callback' along with
276 * If 'callback' returns nonzero, then this must stop the iteration and the
277 * return value must be propagated to the caller. Otherwise, this function
278 * must return zero after all matching flows (if any) have been visited.
280 * Flows are filtered out in two ways. First, based on the bit-mask in
281 * 'include': wdp_rule 'wr' is included only if 'include & (1u <<
282 * wr->ofp_table_id)' is nonzero.
284 * Flows are also filtered out based on 'target': on a field-by-field
285 * basis, a flow is included if 'target' wildcards that field or if the
286 * flow and 'target' both have the same exact value for the field. A flow
287 * is excluded if any field does not match based on these criteria.
289 * Ignores 'target->priority'.
291 * 'callback' is allowed to delete the rule that is passed as its argument.
292 * It may modify any flow in 'wdp', e.g. changing their actions.
293 * 'callback' must not delete flows from 'wdp' other than its argument
294 * flow, nor may it insert new flows into 'wdp'. */
295 int (*flow_for_each_match)(const struct wdp *wdp, const flow_t *flow,
296 unsigned int include,
297 wdp_flow_cb_func *callback, void *aux);
299 /* Retrieves flow statistics for 'rule', which must be in 'wdp''s flow
300 * table, and stores them into '*stats'. Returns 0 if successful,
301 * otherwise a positive errno value. */
302 int (*flow_get_stats)(const struct wdp *wdp,
303 const struct wdp_rule *rule,
304 struct wdp_flow_stats *stats);
306 /* Searches 'wdp''s flow table for a flow that overlaps 'flow'. Two flow
307 * entries overlap if they have the same priority and a single packet may
310 * This is intended for implementing OpenFlow's OFPFF_CHECK_OVERLAP
312 bool (*flow_overlaps)(const struct wdp *wdp, const flow_t *flow);
314 /* Adds or modifies a flow in 'wdp' as specified in 'put'.
316 * As the first step, this function determines the table of 'wdp' in which
317 * the flow should be inserted or modified:
319 * - If 'put->ofp_table_id' is 0xff, then 'wdp' chooses the flow table
320 * itself. It may do so based on, for example, the flow's wildcards
321 * and how full the various tables in 'wdp' already are.
323 * If a flow identical to 'put->flow' already exists in one of 'wdp''s
324 * tables, this does not necessarily mean that that table must be
325 * chosen. That is, 'wdp' may allow duplicate flows, as long as they
326 * are in different tables. Conversely, 'wdp' may refuse to add
327 * duplicate flows. (Whether to allow duplicate flows ordinarily
328 * depends on the structure of the hardware.)
330 * - If 'put->ofp_table_id' is not 0xff, then that table must be used.
331 * If 'wdp' cannot support 'put->flow' in the specified table, or if no
332 * such table exists, then the function must return an error. Reasons
333 * that 'wdp' might not support a flow in a given table include: the
334 * table is full, the flow has wildcards not supported by that table or
335 * otherwise is not in a form supported by the table, or (if 'wdp' does
336 * not support duplicate flows) putting the flow in that table would
337 * cause a duplicate flow.
339 * Afterward, it performs the action:
341 * - If a rule with the same priority, wildcards, values specified in
342 * 'put->flow' (for fields that are not wildcarded) does not already
343 * exist in 'wdp' in the selected table, then behavior depends on
344 * whether WDP_PUT_CREATE is specified in 'put->flags': if it is, the
345 * flow will be added, otherwise the operation will fail with ENOENT.
347 * The new flow's actions and timeouts are set from the values in
350 * - Otherwise, the flow specified in 'put->flow' does exist in 'wdp' in
351 * the selected table. Behavior in this case depends on whether
352 * WDP_PUT_MODIFY is specified in 'put->flags': if it is, the flow will
353 * be updated, otherwise the operation will fail with EEXIST. The
354 * exact updates depend on the remaining flags in 'put->flags':
356 * . If WDP_PUT_COUNTERS is set, packet counters, byte counters, TCP
357 * flags, and IP TOS values are set to 0.
359 * . If WDP_PUT_ACTIONS is set, the actions are replaced by the
360 * 'put->n_actions' actions in 'put->actions'.
362 * . If WDP_PUT_INSERTED is set, the flow's insertion time is updated
363 * to the current time. (Timeouts are relative to a flow's
364 * insertion time so this affects their interpretation.)
366 * . If WDP_PUT_TIMEOUTS is set, the flow's idle and hard timeouts
367 * are updated from 'put->idle_timeout' and 'put->hard_timeout',
370 * If successful, returns 0 and:
372 * - If 'old_stats' is nonnull, then 'old_stats' is filled with the
373 * flow's stats as they existed just before the update, or it is zeroed
374 * if the flow is newly created.
376 * - If 'rulep' is nonnull, then it is set to the newly created rule.
378 * On failure, ordinarily returns an OpenFlow error code constructed with
379 * e.g. ofp_mkerr(), that will be reported to the controller. Some
382 * - ofp_mkerr(OFPET_FLOW_MOD_FAILED, OFPFMFC_ALL_TABLES_FULL): Flow
385 * - ofp_mkerr(OFPET_BAD_ACTION, OFPBAC_BAD_OUT_PORT): Output to
386 * unsupported output port.
388 * - ofp_mkerr(OFPET_FLOW_MOD_FAILED, OFPFMFC_UNSUPPORTED): The flow
389 * table supports the supplied actions but not in the supplied order or
392 * - OpenFlow lacks appropriate error types and codes for many
393 * situations. Feel free to add a new error vendor extension to
394 * nicira-ext.h to handle these situations with your own vendor ID. If
395 * it is a reasonably generic error and you want to use the Nicira
396 * vendor ID instead of your own, please coordinate with
397 * dev@openvswitch.org.
399 * The following specific kinds of failures should instead be reported as
400 * errno values, for the caller to interpret, instead of the controller:
402 * - ENOENT: Flow does not exist and WDP_PUT_CREATE not specified.
404 * - EEXIST: Flow exists and WDP_PUT_MODIFY not specified.
406 int (*flow_put)(struct wdp *wdp, const struct wdp_flow_put *put,
407 struct wdp_flow_stats *old_stats,
408 struct wdp_rule **rulep);
410 /* Deletes 'rule' from 'wdp'. Returns 0 if successful, otherwise an
411 * OpenFlow error code.
413 * If successful and 'final_stats' is non-null, stores the flow's
414 * statistics just before it is deleted into '*final_stats'. */
415 int (*flow_delete)(struct wdp *wdp, struct wdp_rule *rule,
416 struct wdp_flow_stats *final_stats);
418 /* Deletes all flows from 'wdp' and clears all of its queues of received
420 int (*flow_flush)(struct wdp *wdp);
422 /* Performs the actions for 'rule' on the Ethernet frame specified in
423 * 'packet'. Pretends that the frame was originally received on the port
424 * numbered 'in_port'. Packets and bytes sent should be credited to
427 * Returns 0 if successful, otherwise an OpenFlow error code. */
428 int (*flow_inject)(struct wdp *wdp, struct wdp_rule *rule,
429 uint16_t in_port, const struct ofpbuf *packet);
431 /* Performs the 'n_actions' actions in 'actions' on the Ethernet frame
432 * specified in 'packet'. Pretends that the frame was originally received
433 * on the port numbered 'in_port'. */
434 int (*execute)(struct wdp *wdp, uint16_t in_port,
435 const union ofp_action actions[], int n_actions,
436 const struct ofpbuf *packet);
438 /* Retrieves 'wdp''s "listen mask" into '*listen_mask'. Each bit set in
439 * '*listen_mask' indicates the 'wdp' will receive messages of the
440 * corresponding WDP_CHAN_* when it calls the recv member function. */
441 int (*recv_get_mask)(const struct wdp *wdp, int *listen_mask);
443 /* Sets 'wdp''s "listen mask" to 'listen_mask'. Each bit set in
444 * 'listen_mask' indicates the 'wdp' will receive messages of the
445 * corresponding WDP_CHAN_* type when it calls the recv member function. */
446 int (*recv_set_mask)(struct wdp *wdp, int listen_mask);
448 /* Retrieves 'wdp''s sFlow sampling probability into '*probability'.
449 * Return value is 0 or a positive errno value. EOPNOTSUPP indicates that
450 * the datapath does not support sFlow, as does a null pointer.
452 * '*probability' is expressed as the number of packets out of UINT_MAX to
453 * sample, e.g. probability/UINT_MAX is the probability of sampling a given
455 int (*get_sflow_probability)(const struct wdp *wdp,
456 uint32_t *probability);
458 /* Sets 'wdp''s sFlow sampling probability to 'probability'. Return value
459 * is 0 or a positive errno value. EOPNOTSUPP indicates that the datapath
460 * does not support sFlow, as does a null pointer.
462 * 'probability' is expressed as the number of packets out of UINT_MAX to
463 * sample, e.g. probability/UINT_MAX is the probability of sampling a given
465 int (*set_sflow_probability)(struct wdp *wdp, uint32_t probability);
467 /* Attempts to receive a message from 'wdp'. If successful, stores the
468 * message into '*packet'. Only messages of the types selected with the
469 * recv_set_mask member function should be received.
471 * This function must not block. If no message is ready to be received
472 * when it is called, it should return EAGAIN without blocking. */
473 int (*recv)(struct wdp *wdp, struct wdp_packet *packet);
475 /* Discards any queued messages that otherwise would be received by the
476 * 'recv' member function for 'wdp'. */
477 int (*recv_purge)(struct wdp *wdp);
479 /* Arranges for the poll loop to wake up when 'wdp' has a message queued
480 * to be received with the recv member function. */
481 void (*recv_wait)(struct wdp *wdp);
483 /* ovs-vswitchd interface.
485 * This needs to be redesigned, because it only makes sense for wdp-xflow.
486 * Other implementations cannot practically use these interfaces and should
487 * just set these pointers to NULL.
489 * The ofhooks are currently the key to implementing the OFPP_NORMAL
490 * feature of ovs-vswitchd. This design is not adequate for the long
491 * term; it needs to be redone. */
493 /* Sets the ofhooks for 'wdp' to 'ofhooks' with the accompanying 'aux'
496 * This needs to be redesigned, because it only makes sense for wdp-xflow.
497 * Other implementations cannot practically use this interface and should
498 * just set this to NULL. */
499 int (*set_ofhooks)(struct wdp *wdp,
500 const struct ofhooks *ofhooks, void *aux);
502 /* Tell 'wdp' to revalidate all the flows that match 'tag'.
504 * This needs to be redesigned, because it only makes sense for wdp-xflow.
505 * Other implementations cannot practically use this interface and should
506 * just set this to NULL. */
507 void (*revalidate)(struct wdp *wdp, tag_type tag);
509 /* Tell 'wdp' to revalidate every flow. (This is not the same as calling
510 * 'revalidate' with all-1-bits for 'tag' because it also revalidates flows
511 * that do not have any tag at all.)
513 * This needs to be redesigned, because it only makes sense for wdp-xflow.
514 * Other implementations cannot practically use this interface and should
515 * just set this to NULL. */
516 void (*revalidate_all)(struct wdp *wdp);
519 extern const struct wdp_class wdp_linux_class;
520 extern const struct wdp_class wdp_netdev_class;
526 #endif /* wdp-provider.h */