26343cf0e126c8232d6f31e6fcd802c75fe94e8f
[openvswitch] / ofproto-provider.h
1 /*
2  * Copyright (c) 2009, 2010, 2011, 2012 Nicira, Inc.
3  *
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:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
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.
15  */
16
17 #ifndef OFPROTO_OFPROTO_PROVIDER_H
18 #define OFPROTO_OFPROTO_PROVIDER_H 1
19
20 /* Definitions for use within ofproto. */
21
22 #include "ofproto/ofproto.h"
23 #include "cfm.h"
24 #include "classifier.h"
25 #include "heap.h"
26 #include "list.h"
27 #include "ofp-errors.h"
28 #include "ofp-util.h"
29 #include "shash.h"
30 #include "simap.h"
31 #include "timeval.h"
32
33 struct match;
34 struct ofpact;
35 struct ofputil_flow_mod;
36
37 /* An OpenFlow switch.
38  *
39  * With few exceptions, ofproto implementations may look at these fields but
40  * should not modify them. */
41 struct ofproto {
42     struct hmap_node hmap_node; /* In global 'all_ofprotos' hmap. */
43     const struct ofproto_class *ofproto_class;
44     char *type;                 /* Datapath type. */
45     char *name;                 /* Datapath name. */
46
47     /* Settings. */
48     uint64_t fallback_dpid;     /* Datapath ID if no better choice found. */
49     uint64_t datapath_id;       /* Datapath ID. */
50     unsigned flow_eviction_threshold; /* Threshold at which to begin flow
51                                        * table eviction. Only affects the
52                                        * ofproto-dpif implementation */
53     bool forward_bpdu;          /* Option to allow forwarding of BPDU frames
54                                  * when NORMAL action is invoked. */
55     char *mfr_desc;             /* Manufacturer. */
56     char *hw_desc;              /* Hardware. */
57     char *sw_desc;              /* Software version. */
58     char *serial_desc;          /* Serial number. */
59     char *dp_desc;              /* Datapath description. */
60     enum ofp_config_flags frag_handling; /* One of OFPC_*.  */
61
62     /* Datapath. */
63     struct hmap ports;          /* Contains "struct ofport"s. */
64     struct shash port_by_name;
65     unsigned long *ofp_port_ids;/* Bitmap of used OpenFlow port numbers. */
66     struct simap ofp_requests;  /* OpenFlow port number requests. */
67     uint16_t alloc_port_no;     /* Last allocated OpenFlow port number. */
68     uint16_t max_ports;         /* Max possible OpenFlow port num, plus one. */
69
70     /* Flow tables. */
71     struct oftable *tables;
72     int n_tables;
73
74     /* OpenFlow connections. */
75     struct connmgr *connmgr;
76
77     /* Flow table operation tracking. */
78     int state;                  /* Internal state. */
79     struct list pending;        /* List of "struct ofopgroup"s. */
80     unsigned int n_pending;     /* list_size(&pending). */
81     struct hmap deletions;      /* All OFOPERATION_DELETE "ofoperation"s. */
82
83     /* Flow table operation logging. */
84     int n_add, n_delete, n_modify; /* Number of unreported ops of each kind. */
85     long long int first_op, last_op; /* Range of times for unreported ops. */
86     long long int next_op_report;    /* Time to report ops, or LLONG_MAX. */
87     long long int op_backoff;        /* Earliest time to report ops again. */
88
89     /* Linux VLAN device support (e.g. "eth0.10" for VLAN 10.)
90      *
91      * This is deprecated.  It is only for compatibility with broken device
92      * drivers in old versions of Linux that do not properly support VLANs when
93      * VLAN devices are not used.  When broken device drivers are no longer in
94      * widespread use, we will delete these interfaces. */
95     unsigned long int *vlan_bitmap; /* 4096-bit bitmap of in-use VLANs. */
96     bool vlans_changed;             /* True if new VLANs are in use. */
97     int min_mtu;                    /* Current MTU of non-internal ports. */
98 };
99
100 void ofproto_init_tables(struct ofproto *, int n_tables);
101 void ofproto_init_max_ports(struct ofproto *, uint16_t max_ports);
102
103 struct ofproto *ofproto_lookup(const char *name);
104 struct ofport *ofproto_get_port(const struct ofproto *, uint16_t ofp_port);
105
106 /* An OpenFlow port within a "struct ofproto".
107  *
108  * With few exceptions, ofproto implementations may look at these fields but
109  * should not modify them. */
110 struct ofport {
111     struct hmap_node hmap_node; /* In struct ofproto's "ports" hmap. */
112     struct ofproto *ofproto;    /* The ofproto that contains this port. */
113     struct netdev *netdev;
114     struct ofputil_phy_port pp;
115     uint16_t ofp_port;          /* OpenFlow port number. */
116     unsigned int change_seq;
117     int mtu;
118 };
119
120 void ofproto_port_set_state(struct ofport *, enum ofputil_port_state);
121
122 /* OpenFlow table flags:
123  *
124  *   - "Hidden" tables are not included in OpenFlow operations that operate on
125  *     "all tables".  For example, a request for flow stats on all tables will
126  *     omit flows in hidden tables, table stats requests will omit the table
127  *     entirely, and the switch features reply will not count the hidden table.
128  *
129  *     However, operations that specifically name the particular table still
130  *     operate on it.  For example, flow_mods and flow stats requests on a
131  *     hidden table work.
132  *
133  *     To avoid gaps in table IDs (which have unclear validity in OpenFlow),
134  *     hidden tables must be the highest-numbered tables that a provider
135  *     implements.
136  *
137  *   - "Read-only" tables can't be changed through OpenFlow operations.  (At
138  *     the moment all flow table operations go effectively through OpenFlow, so
139  *     this means that read-only tables can't be changed at all after the
140  *     read-only flag is set.)
141  *
142  * The generic ofproto layer never sets these flags.  An ofproto provider can
143  * set them if it is appropriate.
144  */
145 enum oftable_flags {
146     OFTABLE_HIDDEN = 1 << 0,   /* Hide from most OpenFlow operations. */
147     OFTABLE_READONLY = 1 << 1  /* Don't allow OpenFlow to change this table. */
148 };
149
150 /* A flow table within a "struct ofproto". */
151 struct oftable {
152     enum oftable_flags flags;
153     struct classifier cls;      /* Contains "struct rule"s. */
154     char *name;                 /* Table name exposed via OpenFlow, or NULL. */
155
156     /* Maximum number of flows or UINT_MAX if there is no limit besides any
157      * limit imposed by resource limitations. */
158     unsigned int max_flows;
159
160     /* These members determine the handling of an attempt to add a flow that
161      * would cause the table to have more than 'max_flows' flows.
162      *
163      * If 'eviction_fields' is NULL, overflows will be rejected with an error.
164      *
165      * If 'eviction_fields' is nonnull (regardless of whether n_eviction_fields
166      * is nonzero), an overflow will cause a flow to be removed.  The flow to
167      * be removed is chosen to give fairness among groups distinguished by
168      * different values for the subfields within 'groups'. */
169     struct mf_subfield *eviction_fields;
170     size_t n_eviction_fields;
171
172     /* Eviction groups.
173      *
174      * When a flow is added that would cause the table to have more than
175      * 'max_flows' flows, and 'eviction_fields' is nonnull, these groups are
176      * used to decide which rule to evict: the rule is chosen from the eviction
177      * group that contains the greatest number of rules.*/
178     uint32_t eviction_group_id_basis;
179     struct hmap eviction_groups_by_id;
180     struct heap eviction_groups_by_size;
181 };
182
183 /* Assigns TABLE to each oftable, in turn, in OFPROTO.
184  *
185  * All parameters are evaluated multiple times. */
186 #define OFPROTO_FOR_EACH_TABLE(TABLE, OFPROTO)              \
187     for ((TABLE) = (OFPROTO)->tables;                       \
188          (TABLE) < &(OFPROTO)->tables[(OFPROTO)->n_tables]; \
189          (TABLE)++)
190
191 /* An OpenFlow flow within a "struct ofproto".
192  *
193  * With few exceptions, ofproto implementations may look at these fields but
194  * should not modify them. */
195 struct rule {
196     struct list ofproto_node;    /* Owned by ofproto base code. */
197     struct ofproto *ofproto;     /* The ofproto that contains this rule. */
198     struct cls_rule cr;          /* In owning ofproto's classifier. */
199
200     struct ofoperation *pending; /* Operation now in progress, if nonnull. */
201
202     ovs_be64 flow_cookie;        /* Controller-issued identifier. */
203
204     long long int created;       /* Creation time. */
205     long long int modified;      /* Time of last modification. */
206     long long int used;          /* Last use; time created if never used. */
207     uint16_t hard_timeout;       /* In seconds from ->modified. */
208     uint16_t idle_timeout;       /* In seconds from ->used. */
209     uint8_t table_id;            /* Index in ofproto's 'tables' array. */
210     bool send_flow_removed;      /* Send a flow removed message? */
211
212     /* Eviction groups. */
213     bool evictable;              /* If false, prevents eviction. */
214     struct heap_node evg_node;   /* In eviction_group's "rules" heap. */
215     struct eviction_group *eviction_group; /* NULL if not in any group. */
216
217     struct ofpact *ofpacts;      /* Sequence of "struct ofpacts". */
218     unsigned int ofpacts_len;    /* Size of 'ofpacts', in bytes. */
219
220     /* Flow monitors. */
221     enum nx_flow_monitor_flags monitor_flags;
222     uint64_t add_seqno;         /* Sequence number when added. */
223     uint64_t modify_seqno;      /* Sequence number when changed. */
224 };
225
226 static inline struct rule *
227 rule_from_cls_rule(const struct cls_rule *cls_rule)
228 {
229     return cls_rule ? CONTAINER_OF(cls_rule, struct rule, cr) : NULL;
230 }
231
232 void ofproto_rule_update_used(struct rule *, long long int used);
233 void ofproto_rule_expire(struct rule *, uint8_t reason);
234 void ofproto_rule_destroy(struct rule *);
235
236 bool ofproto_rule_has_out_port(const struct rule *, uint16_t out_port);
237
238 void ofoperation_complete(struct ofoperation *, enum ofperr);
239 struct rule *ofoperation_get_victim(struct ofoperation *);
240
241 bool ofoperation_has_out_port(const struct ofoperation *, uint16_t out_port);
242
243 bool ofproto_rule_is_hidden(const struct rule *);
244
245 /* ofproto class structure, to be defined by each ofproto implementation.
246  *
247  *
248  * Data Structures
249  * ===============
250  *
251  * These functions work primarily with three different kinds of data
252  * structures:
253  *
254  *   - "struct ofproto", which represents an OpenFlow switch.
255  *
256  *   - "struct ofport", which represents a port within an ofproto.
257  *
258  *   - "struct rule", which represents an OpenFlow flow within an ofproto.
259  *
260  * Each of these data structures contains all of the implementation-independent
261  * generic state for the respective concept, called the "base" state.  None of
262  * them contains any extra space for ofproto implementations to use.  Instead,
263  * each implementation is expected to declare its own data structure that
264  * contains an instance of the generic data structure plus additional
265  * implementation-specific members, called the "derived" state.  The
266  * implementation can use casts or (preferably) the CONTAINER_OF macro to
267  * obtain access to derived state given only a pointer to the embedded generic
268  * data structure.
269  *
270  *
271  * Life Cycle
272  * ==========
273  *
274  * Four stylized functions accompany each of these data structures:
275  *
276  *            "alloc"       "construct"       "destruct"       "dealloc"
277  *            ------------  ----------------  ---------------  --------------
278  *   ofproto  ->alloc       ->construct       ->destruct       ->dealloc
279  *   ofport   ->port_alloc  ->port_construct  ->port_destruct  ->port_dealloc
280  *   rule     ->rule_alloc  ->rule_construct  ->rule_destruct  ->rule_dealloc
281  *
282  * Any instance of a given data structure goes through the following life
283  * cycle:
284  *
285  *   1. The client calls the "alloc" function to obtain raw memory.  If "alloc"
286  *      fails, skip all the other steps.
287  *
288  *   2. The client initializes all of the data structure's base state.  If this
289  *      fails, skip to step 7.
290  *
291  *   3. The client calls the "construct" function.  The implementation
292  *      initializes derived state.  It may refer to the already-initialized
293  *      base state.  If "construct" fails, skip to step 6.
294  *
295  *   4. The data structure is now initialized and in use.
296  *
297  *   5. When the data structure is no longer needed, the client calls the
298  *      "destruct" function.  The implementation uninitializes derived state.
299  *      The base state has not been uninitialized yet, so the implementation
300  *      may still refer to it.
301  *
302  *   6. The client uninitializes all of the data structure's base state.
303  *
304  *   7. The client calls the "dealloc" to free the raw memory.  The
305  *      implementation must not refer to base or derived state in the data
306  *      structure, because it has already been uninitialized.
307  *
308  * Each "alloc" function allocates and returns a new instance of the respective
309  * data structure.  The "alloc" function is not given any information about the
310  * use of the new data structure, so it cannot perform much initialization.
311  * Its purpose is just to ensure that the new data structure has enough room
312  * for base and derived state.  It may return a null pointer if memory is not
313  * available, in which case none of the other functions is called.
314  *
315  * Each "construct" function initializes derived state in its respective data
316  * structure.  When "construct" is called, all of the base state has already
317  * been initialized, so the "construct" function may refer to it.  The
318  * "construct" function is allowed to fail, in which case the client calls the
319  * "dealloc" function (but not the "destruct" function).
320  *
321  * Each "destruct" function uninitializes and frees derived state in its
322  * respective data structure.  When "destruct" is called, the base state has
323  * not yet been uninitialized, so the "destruct" function may refer to it.  The
324  * "destruct" function is not allowed to fail.
325  *
326  * Each "dealloc" function frees raw memory that was allocated by the the
327  * "alloc" function.  The memory's base and derived members might not have ever
328  * been initialized (but if "construct" returned successfully, then it has been
329  * "destruct"ed already).  The "dealloc" function is not allowed to fail.
330  *
331  *
332  * Conventions
333  * ===========
334  *
335  * Most of these functions return 0 if they are successful or a positive error
336  * code on failure.  Depending on the function, valid error codes are either
337  * errno values or OFPERR_* OpenFlow error codes.
338  *
339  * Most of these functions are expected to execute synchronously, that is, to
340  * block as necessary to obtain a result.  Thus, these functions may return
341  * EAGAIN (or EWOULDBLOCK or EINPROGRESS) only where the function descriptions
342  * explicitly say those errors are a possibility.  We may relax this
343  * requirement in the future if and when we encounter performance problems. */
344 struct ofproto_class {
345 /* ## ----------------- ## */
346 /* ## Factory Functions ## */
347 /* ## ----------------- ## */
348
349     /* Initializes provider.  The caller may pass in 'iface_hints',
350      * which contains an shash of "struct iface_hint" elements indexed
351      * by the interface's name.  The provider may use these hints to
352      * describe the startup configuration in order to reinitialize its
353      * state.  The caller owns the provided data, so a provider must
354      * make copies of anything required.  An ofproto provider must
355      * remove any existing state that is not described by the hint, and
356      * may choose to remove it all. */
357     void (*init)(const struct shash *iface_hints);
358
359     /* Enumerates the types of all support ofproto types into 'types'.  The
360      * caller has already initialized 'types' and other ofproto classes might
361      * already have added names to it. */
362     void (*enumerate_types)(struct sset *types);
363
364     /* Enumerates the names of all existing datapath of the specified 'type'
365      * into 'names' 'all_dps'.  The caller has already initialized 'names' as
366      * an empty sset.
367      *
368      * 'type' is one of the types enumerated by ->enumerate_types().
369      *
370      * Returns 0 if successful, otherwise a positive errno value.
371      */
372     int (*enumerate_names)(const char *type, struct sset *names);
373
374     /* Deletes the datapath with the specified 'type' and 'name'.  The caller
375      * should have closed any open ofproto with this 'type' and 'name'; this
376      * function is allowed to fail if that is not the case.
377      *
378      * 'type' is one of the types enumerated by ->enumerate_types().
379      * 'name' is one of the names enumerated by ->enumerate_names() for 'type'.
380      *
381      * Returns 0 if successful, otherwise a positive errno value.
382      */
383     int (*del)(const char *type, const char *name);
384
385 /* ## ------------------------ ## */
386 /* ## Top-Level type Functions ## */
387 /* ## ------------------------ ## */
388
389     /* Performs any periodic activity required on ofprotos of type
390      * 'type'.
391      *
392      * An ofproto provider may implement it or not, depending on whether
393      * it needs type-level maintenance.
394      *
395      * Returns 0 if successful, otherwise a positive errno value. */
396     int (*type_run)(const char *type);
397
398     /* Performs periodic activity required on ofprotos of type 'type'
399      * that needs to be done with the least possible latency.
400      *
401      * This is run multiple times per main loop.  An ofproto provider may
402      * implement it or not, according to whether it provides a performance
403      * boost for that ofproto implementation.
404      *
405      * Returns 0 if successful, otherwise a positive errno value. */
406     int (*type_run_fast)(const char *type);
407
408     /* Causes the poll loop to wake up when a type 'type''s 'run'
409      * function needs to be called, e.g. by calling the timer or fd
410      * waiting functions in poll-loop.h.
411      *
412      * An ofproto provider may implement it or not, depending on whether
413      * it needs type-level maintenance. */
414     void (*type_wait)(const char *type);
415
416 /* ## --------------------------- ## */
417 /* ## Top-Level ofproto Functions ## */
418 /* ## --------------------------- ## */
419
420     /* Life-cycle functions for an "ofproto" (see "Life Cycle" above).
421      *
422      *
423      * Construction
424      * ============
425      *
426      * ->construct() should not modify any base members of the ofproto.  The
427      * client will initialize the ofproto's 'ports' and 'tables' members after
428      * construction is complete.
429      *
430      * When ->construct() is called, the client does not yet know how many flow
431      * tables the datapath supports, so ofproto->n_tables will be 0 and
432      * ofproto->tables will be NULL.  ->construct() should call
433      * ofproto_init_tables() to allocate and initialize ofproto->n_tables and
434      * ofproto->tables.  Each flow table will be initially empty, so
435      * ->construct() should delete flows from the underlying datapath, if
436      * necessary, rather than populating the tables.
437      *
438      * If the ofproto knows the maximum port number that the datapath can have,
439      * then it can call ofproto_init_max_ports().  If it does so, then the
440      * client will ensure that the actions it allows to be used through
441      * OpenFlow do not refer to ports above that maximum number.
442      *
443      * Only one ofproto instance needs to be supported for any given datapath.
444      * If a datapath is already open as part of one "ofproto", then another
445      * attempt to "construct" the same datapath as part of another ofproto is
446      * allowed to fail with an error.
447      *
448      * ->construct() returns 0 if successful, otherwise a positive errno
449      * value.
450      *
451      *
452      * Destruction
453      * ===========
454      *
455      * If 'ofproto' has any pending asynchronous operations, ->destruct()
456      * must complete all of them by calling ofoperation_complete().
457      *
458      * ->destruct() must also destroy all remaining rules in the ofproto's
459      * tables, by passing each remaining rule to ofproto_rule_destroy().  The
460      * client will destroy the flow tables themselves after ->destruct()
461      * returns.
462      */
463     struct ofproto *(*alloc)(void);
464     int (*construct)(struct ofproto *ofproto);
465     void (*destruct)(struct ofproto *ofproto);
466     void (*dealloc)(struct ofproto *ofproto);
467
468     /* Performs any periodic activity required by 'ofproto'.  It should:
469      *
470      *   - Call connmgr_send_packet_in() for each received packet that missed
471      *     in the OpenFlow flow table or that had a OFPP_CONTROLLER output
472      *     action.
473      *
474      *   - Call ofproto_rule_expire() for each OpenFlow flow that has reached
475      *     its hard_timeout or idle_timeout, to expire the flow.
476      *
477      *     (But rules that are part of a pending operation, e.g. rules for
478      *     which ->pending is true, may not expire.)
479      *
480      * Returns 0 if successful, otherwise a positive errno value. */
481     int (*run)(struct ofproto *ofproto);
482
483     /* Performs periodic activity required by 'ofproto' that needs to be done
484      * with the least possible latency.
485      *
486      * This is run multiple times per main loop.  An ofproto provider may
487      * implement it or not, according to whether it provides a performance
488      * boost for that ofproto implementation. */
489     int (*run_fast)(struct ofproto *ofproto);
490
491     /* Causes the poll loop to wake up when 'ofproto''s 'run' function needs to
492      * be called, e.g. by calling the timer or fd waiting functions in
493      * poll-loop.h.  */
494     void (*wait)(struct ofproto *ofproto);
495
496     /* Adds some memory usage statistics for the implementation of 'ofproto'
497      * into 'usage', for use with memory_report().
498      *
499      * This function is optional. */
500     void (*get_memory_usage)(const struct ofproto *ofproto,
501                              struct simap *usage);
502
503     /* Every "struct rule" in 'ofproto' is about to be deleted, one by one.
504      * This function may prepare for that, for example by clearing state in
505      * advance.  It should *not* actually delete any "struct rule"s from
506      * 'ofproto', only prepare for it.
507      *
508      * This function is optional; it's really just for optimization in case
509      * it's cheaper to delete all the flows from your hardware in a single pass
510      * than to do it one by one. */
511     void (*flush)(struct ofproto *ofproto);
512
513     /* Helper for the OpenFlow OFPT_FEATURES_REQUEST request.
514      *
515      * The implementation should store true in '*arp_match_ip' if the switch
516      * supports matching IP addresses inside ARP requests and replies, false
517      * otherwise.
518      *
519      * The implementation should store in '*actions' a bitmap of the supported
520      * OpenFlow actions.  Vendor actions are not included in '*actions'. */
521     void (*get_features)(struct ofproto *ofproto,
522                          bool *arp_match_ip,
523                          enum ofputil_action_bitmap *actions);
524
525     /* Helper for the OpenFlow OFPST_TABLE statistics request.
526      *
527      * The 'ots' array contains 'ofproto->n_tables' elements.  Each element is
528      * initialized as:
529      *
530      *   - 'table_id' to the array index.
531      *
532      *   - 'name' to "table#" where # is the table ID.
533      *
534      *   - 'match' and 'wildcards' to OFPXMT12_MASK.
535      *
536      *   - 'write_actions' and 'apply_actions' to OFPAT12_OUTPUT.
537      *
538      *   - 'write_setfields' and 'apply_setfields' to OFPXMT12_MASK.
539      *
540      *   - 'metadata_match' and 'metadata_write' to UINT64_MAX.
541      *
542      *   - 'instructions' to OFPIT11_ALL.
543      *
544      *   - 'config' to OFPTC11_TABLE_MISS_MASK.
545      *
546      *   - 'max_entries' to 1,000,000.
547      *
548      *   - 'active_count' to the classifier_count() for the table.
549      *
550      *   - 'lookup_count' and 'matched_count' to 0.
551      *
552      * The implementation should update any members in each element for which
553      * it has better values:
554      *
555      *   - 'name' to a more meaningful name.
556      *
557      *   - 'wildcards' to the set of wildcards actually supported by the table
558      *     (if it doesn't support all OpenFlow wildcards).
559      *
560      *   - 'instructions' to set the instructions actually supported by
561      *     the table.
562      *
563      *   - 'write_actions' to set the write actions actually supported by
564      *     the table (if it doesn't support all OpenFlow actions).
565      *
566      *   - 'apply_actions' to set the apply actions actually supported by
567      *     the table (if it doesn't support all OpenFlow actions).
568      *
569      *   - 'write_setfields' to set the write setfields actually supported by
570      *     the table.
571      *
572      *   - 'apply_setfields' to set the apply setfields actually supported by
573      *     the table.
574      *
575      *   - 'max_entries' to the maximum number of flows actually supported by
576      *     the hardware.
577      *
578      *   - 'lookup_count' to the number of packets looked up in this flow table
579      *     so far.
580      *
581      *   - 'matched_count' to the number of packets looked up in this flow
582      *     table so far that matched one of the flow entries.
583      *
584      * All of the members of struct ofp12_table_stats are in network byte
585      * order.
586      */
587     void (*get_tables)(struct ofproto *ofproto, struct ofp12_table_stats *ots);
588
589 /* ## ---------------- ## */
590 /* ## ofport Functions ## */
591 /* ## ---------------- ## */
592
593     /* Life-cycle functions for a "struct ofport" (see "Life Cycle" above).
594      *
595      * ->port_construct() should not modify any base members of the ofport.
596      * An ofproto implementation should use the 'ofp_port' member of
597      * "struct ofport" as the OpenFlow port number.
598      *
599      * ofports are managed by the base ofproto code.  The ofproto
600      * implementation should only create and destroy them in response to calls
601      * to these functions.  The base ofproto code will create and destroy
602      * ofports in the following situations:
603      *
604      *   - Just after the ->construct() function is called, the base ofproto
605      *     iterates over all of the implementation's ports, using
606      *     ->port_dump_start() and related functions, and constructs an ofport
607      *     for each dumped port.
608      *
609      *   - If ->port_poll() reports that a specific port has changed, then the
610      *     base ofproto will query that port with ->port_query_by_name() and
611      *     construct or destruct ofports as necessary to reflect the updated
612      *     set of ports.
613      *
614      *   - If ->port_poll() returns ENOBUFS to report an unspecified port set
615      *     change, then the base ofproto will iterate over all of the
616      *     implementation's ports, in the same way as at ofproto
617      *     initialization, and construct and destruct ofports to reflect all of
618      *     the changes.
619      *
620      * ->port_construct() returns 0 if successful, otherwise a positive errno
621      * value.
622      */
623     struct ofport *(*port_alloc)(void);
624     int (*port_construct)(struct ofport *ofport);
625     void (*port_destruct)(struct ofport *ofport);
626     void (*port_dealloc)(struct ofport *ofport);
627
628     /* Called after 'ofport->netdev' is replaced by a new netdev object.  If
629      * the ofproto implementation uses the ofport's netdev internally, then it
630      * should switch to using the new one.  The old one has been closed.
631      *
632      * An ofproto implementation that doesn't need to do anything in this
633      * function may use a null pointer. */
634     void (*port_modified)(struct ofport *ofport);
635
636     /* Called after an OpenFlow request changes a port's configuration.
637      * 'ofport->pp.config' contains the new configuration.  'old_config'
638      * contains the previous configuration.
639      *
640      * The caller implements OFPUTIL_PC_PORT_DOWN using netdev functions to
641      * turn NETDEV_UP on and off, so this function doesn't have to do anything
642      * for that bit (and it won't be called if that is the only bit that
643      * changes). */
644     void (*port_reconfigured)(struct ofport *ofport,
645                               enum ofputil_port_config old_config);
646
647     /* Looks up a port named 'devname' in 'ofproto'.  On success, initializes
648      * '*port' appropriately.
649      *
650      * The caller owns the data in 'port' and must free it with
651      * ofproto_port_destroy() when it is no longer needed. */
652     int (*port_query_by_name)(const struct ofproto *ofproto,
653                               const char *devname, struct ofproto_port *port);
654
655     /* Attempts to add 'netdev' as a port on 'ofproto'.  Returns 0 if
656      * successful, otherwise a positive errno value.  The caller should
657      * inform the implementation of the OpenFlow port through the
658      * ->port_construct() method.
659      *
660      * It doesn't matter whether the new port will be returned by a later call
661      * to ->port_poll(); the implementation may do whatever is more
662      * convenient. */
663     int (*port_add)(struct ofproto *ofproto, struct netdev *netdev);
664
665     /* Deletes port number 'ofp_port' from the datapath for 'ofproto'.  Returns
666      * 0 if successful, otherwise a positive errno value.
667      *
668      * It doesn't matter whether the new port will be returned by a later call
669      * to ->port_poll(); the implementation may do whatever is more
670      * convenient. */
671     int (*port_del)(struct ofproto *ofproto, uint16_t ofp_port);
672
673     /* Get port stats */
674     int (*port_get_stats)(const struct ofport *port,
675                           struct netdev_stats *stats);
676
677     /* Port iteration functions.
678      *
679      * The client might not be entirely in control of the ports within an
680      * ofproto.  Some hardware implementations, for example, might have a fixed
681      * set of ports in a datapath.  For this reason, the client needs a way to
682      * iterate through all the ports that are actually in a datapath.  These
683      * functions provide that functionality.
684      *
685      * The 'state' pointer provides the implementation a place to
686      * keep track of its position.  Its format is opaque to the caller.
687      *
688      * The ofproto provider retains ownership of the data that it stores into
689      * ->port_dump_next()'s 'port' argument.  The data must remain valid until
690      * at least the next call to ->port_dump_next() or ->port_dump_done() for
691      * 'state'.  The caller will not modify or free it.
692      *
693      * Details
694      * =======
695      *
696      * ->port_dump_start() attempts to begin dumping the ports in 'ofproto'.
697      * On success, it should return 0 and initialize '*statep' with any data
698      * needed for iteration.  On failure, returns a positive errno value, and
699      * the client will not call ->port_dump_next() or ->port_dump_done().
700      *
701      * ->port_dump_next() attempts to retrieve another port from 'ofproto' for
702      * 'state'.  If there is another port, it should store the port's
703      * information into 'port' and return 0.  It should return EOF if all ports
704      * have already been iterated.  Otherwise, on error, it should return a
705      * positive errno value.  This function will not be called again once it
706      * returns nonzero once for a given iteration (but the 'port_dump_done'
707      * function will be called afterward).
708      *
709      * ->port_dump_done() allows the implementation to release resources used
710      * for iteration.  The caller might decide to stop iteration in the middle
711      * by calling this function before ->port_dump_next() returns nonzero.
712      *
713      * Usage Example
714      * =============
715      *
716      * int error;
717      * void *state;
718      *
719      * error = ofproto->ofproto_class->port_dump_start(ofproto, &state);
720      * if (!error) {
721      *     for (;;) {
722      *         struct ofproto_port port;
723      *
724      *         error = ofproto->ofproto_class->port_dump_next(
725      *                     ofproto, state, &port);
726      *         if (error) {
727      *             break;
728      *         }
729      *         // Do something with 'port' here (without modifying or freeing
730      *         // any of its data).
731      *     }
732      *     ofproto->ofproto_class->port_dump_done(ofproto, state);
733      * }
734      * // 'error' is now EOF (success) or a positive errno value (failure).
735      */
736     int (*port_dump_start)(const struct ofproto *ofproto, void **statep);
737     int (*port_dump_next)(const struct ofproto *ofproto, void *state,
738                           struct ofproto_port *port);
739     int (*port_dump_done)(const struct ofproto *ofproto, void *state);
740
741     /* Polls for changes in the set of ports in 'ofproto'.  If the set of ports
742      * in 'ofproto' has changed, then this function should do one of the
743      * following:
744      *
745      * - Preferably: store the name of the device that was added to or deleted
746      *   from 'ofproto' in '*devnamep' and return 0.  The caller is responsible
747      *   for freeing '*devnamep' (with free()) when it no longer needs it.
748      *
749      * - Alternatively: return ENOBUFS, without indicating the device that was
750      *   added or deleted.
751      *
752      * Occasional 'false positives', in which the function returns 0 while
753      * indicating a device that was not actually added or deleted or returns
754      * ENOBUFS without any change, are acceptable.
755      *
756      * The purpose of 'port_poll' is to let 'ofproto' know about changes made
757      * externally to the 'ofproto' object, e.g. by a system administrator via
758      * ovs-dpctl.  Therefore, it's OK, and even preferable, for port_poll() to
759      * not report changes made through calls to 'port_add' or 'port_del' on the
760      * same 'ofproto' object.  (But it's OK for it to report them too, just
761      * slightly less efficient.)
762      *
763      * If the set of ports in 'ofproto' has not changed, returns EAGAIN.  May
764      * also return other positive errno values to indicate that something has
765      * gone wrong.
766      *
767      * If the set of ports in a datapath is fixed, or if the only way that the
768      * set of ports in a datapath can change is through ->port_add() and
769      * ->port_del(), then this function may be a null pointer.
770      */
771     int (*port_poll)(const struct ofproto *ofproto, char **devnamep);
772
773     /* Arranges for the poll loop to wake up when ->port_poll() will return a
774      * value other than EAGAIN.
775      *
776      * If the set of ports in a datapath is fixed, or if the only way that the
777      * set of ports in a datapath can change is through ->port_add() and
778      * ->port_del(), or if the poll loop will always wake up anyway when
779      * ->port_poll() will return a value other than EAGAIN, then this function
780      * may be a null pointer.
781      */
782     void (*port_poll_wait)(const struct ofproto *ofproto);
783
784     /* Checks the status of LACP negotiation for 'port'.  Returns 1 if LACP
785      * partner information for 'port' is up-to-date, 0 if LACP partner
786      * information is not current (generally indicating a connectivity
787      * problem), or -1 if LACP is not enabled on 'port'.
788      *
789      * This function may be a null pointer if the ofproto implementation does
790      * not support LACP. */
791     int (*port_is_lacp_current)(const struct ofport *port);
792
793 /* ## ----------------------- ## */
794 /* ## OpenFlow Rule Functions ## */
795 /* ## ----------------------- ## */
796
797     /* Chooses an appropriate table for 'match' within 'ofproto'.  On
798      * success, stores the table ID into '*table_idp' and returns 0.  On
799      * failure, returns an OpenFlow error code.
800      *
801      * The choice of table should be a function of 'match' and 'ofproto''s
802      * datapath capabilities.  It should not depend on the flows already in
803      * 'ofproto''s flow tables.  Failure implies that an OpenFlow rule with
804      * 'match' as its matching condition can never be inserted into 'ofproto',
805      * even starting from an empty flow table.
806      *
807      * If multiple tables are candidates for inserting the flow, the function
808      * should choose one arbitrarily (but deterministically).
809      *
810      * If this function is NULL then table 0 is always chosen. */
811     enum ofperr (*rule_choose_table)(const struct ofproto *ofproto,
812                                      const struct match *match,
813                                      uint8_t *table_idp);
814
815     /* Life-cycle functions for a "struct rule" (see "Life Cycle" above).
816      *
817      *
818      * Asynchronous Operation Support
819      * ==============================
820      *
821      * The life-cycle operations on rules can operate asynchronously, meaning
822      * that ->rule_construct() and ->rule_destruct() only need to initiate
823      * their respective operations and do not need to wait for them to complete
824      * before they return.  ->rule_modify_actions() also operates
825      * asynchronously.
826      *
827      * An ofproto implementation reports the success or failure of an
828      * asynchronous operation on a rule using the rule's 'pending' member,
829      * which points to a opaque "struct ofoperation" that represents the
830      * ongoing opreation.  When the operation completes, the ofproto
831      * implementation calls ofoperation_complete(), passing the ofoperation and
832      * an error indication.
833      *
834      * Only the following contexts may call ofoperation_complete():
835      *
836      *   - The function called to initiate the operation,
837      *     e.g. ->rule_construct() or ->rule_destruct().  This is the best
838      *     choice if the operation completes quickly.
839      *
840      *   - The implementation's ->run() function.
841      *
842      *   - The implementation's ->destruct() function.
843      *
844      * The ofproto base code updates the flow table optimistically, assuming
845      * that the operation will probably succeed:
846      *
847      *   - ofproto adds or replaces the rule in the flow table before calling
848      *     ->rule_construct().
849      *
850      *   - ofproto updates the rule's actions before calling
851      *     ->rule_modify_actions().
852      *
853      *   - ofproto removes the rule before calling ->rule_destruct().
854      *
855      * With one exception, when an asynchronous operation completes with an
856      * error, ofoperation_complete() backs out the already applied changes:
857      *
858      *   - If adding or replacing a rule in the flow table fails, ofproto
859      *     removes the new rule or restores the original rule.
860      *
861      *   - If modifying a rule's actions fails, ofproto restores the original
862      *     actions.
863      *
864      *   - Removing a rule is not allowed to fail.  It must always succeed.
865      *
866      * The ofproto base code serializes operations: if any operation is in
867      * progress on a given rule, ofproto postpones initiating any new operation
868      * on that rule until the pending operation completes.  Therefore, every
869      * operation must eventually complete through a call to
870      * ofoperation_complete() to avoid delaying new operations indefinitely
871      * (including any OpenFlow request that affects the rule in question, even
872      * just to query its statistics).
873      *
874      *
875      * Construction
876      * ============
877      *
878      * When ->rule_construct() is called, the caller has already inserted
879      * 'rule' into 'rule->ofproto''s flow table numbered 'rule->table_id'.
880      * There are two cases:
881      *
882      *   - 'rule' is a new rule in its flow table.  In this case,
883      *     ofoperation_get_victim(rule) returns NULL.
884      *
885      *   - 'rule' is replacing an existing rule in its flow table that had the
886      *     same matching criteria and priority.  In this case,
887      *     ofoperation_get_victim(rule) returns the rule being replaced (the
888      *     "victim" rule).
889      *
890      * ->rule_construct() should set the following in motion:
891      *
892      *   - Validate that the matching rule in 'rule->cr' is supported by the
893      *     datapath.  For example, if the rule's table does not support
894      *     registers, then it is an error if 'rule->cr' does not wildcard all
895      *     registers.
896      *
897      *   - Validate that the datapath can correctly implement 'rule->ofpacts'.
898      *
899      *   - If the rule is valid, update the datapath flow table, adding the new
900      *     rule or replacing the existing one.
901      *
902      *   - If 'rule' is replacing an existing rule, uninitialize any derived
903      *     state for the victim rule, as in step 5 in the "Life Cycle"
904      *     described above.
905      *
906      * (On failure, the ofproto code will roll back the insertion from the flow
907      * table, either removing 'rule' or replacing it by the victim rule if
908      * there is one.)
909      *
910      * ->rule_construct() must act in one of the following ways:
911      *
912      *   - If it succeeds, it must call ofoperation_complete() and return 0.
913      *
914      *   - If it fails, it must act in one of the following ways:
915      *
916      *       * Call ofoperation_complete() and return 0.
917      *
918      *       * Return an OpenFlow error code.  (Do not call
919      *         ofoperation_complete() in this case.)
920      *
921      *     Either way, ->rule_destruct() will not be called for 'rule', but
922      *     ->rule_dealloc() will be.
923      *
924      *   - If the operation is only partially complete, then it must return 0.
925      *     Later, when the operation is complete, the ->run() or ->destruct()
926      *     function must call ofoperation_complete() to report success or
927      *     failure.
928      *
929      * ->rule_construct() should not modify any base members of struct rule.
930      *
931      *
932      * Destruction
933      * ===========
934      *
935      * When ->rule_destruct() is called, the caller has already removed 'rule'
936      * from 'rule->ofproto''s flow table.  ->rule_destruct() should set in
937      * motion removing 'rule' from the datapath flow table.  If removal
938      * completes synchronously, it should call ofoperation_complete().
939      * Otherwise, the ->run() or ->destruct() function must later call
940      * ofoperation_complete() after the operation completes.
941      *
942      * Rule destruction must not fail. */
943     struct rule *(*rule_alloc)(void);
944     enum ofperr (*rule_construct)(struct rule *rule);
945     void (*rule_destruct)(struct rule *rule);
946     void (*rule_dealloc)(struct rule *rule);
947
948     /* Obtains statistics for 'rule', storing the number of packets that have
949      * matched it in '*packet_count' and the number of bytes in those packets
950      * in '*byte_count'.  UINT64_MAX indicates that the packet count or byte
951      * count is unknown. */
952     void (*rule_get_stats)(struct rule *rule, uint64_t *packet_count,
953                            uint64_t *byte_count);
954
955     /* Applies the actions in 'rule' to 'packet'.  (This implements sending
956      * buffered packets for OpenFlow OFPT_FLOW_MOD commands.)
957      *
958      * Takes ownership of 'packet' (so it should eventually free it, with
959      * ofpbuf_delete()).
960      *
961      * 'flow' reflects the flow information for 'packet'.  All of the
962      * information in 'flow' is extracted from 'packet', except for
963      * flow->tunnel and flow->in_port, which are assigned the correct values
964      * for the incoming packet.  The register values are zeroed.  'packet''s
965      * header pointers (e.g. packet->l3) are appropriately initialized.
966      *
967      * The implementation should add the statistics for 'packet' into 'rule'.
968      *
969      * Returns 0 if successful, otherwise an OpenFlow error code. */
970     enum ofperr (*rule_execute)(struct rule *rule, const struct flow *flow,
971                                 struct ofpbuf *packet);
972
973     /* When ->rule_modify_actions() is called, the caller has already replaced
974      * the OpenFlow actions in 'rule' by a new set.  (The original actions are
975      * in rule->pending->actions.)
976      *
977      * ->rule_modify_actions() should set the following in motion:
978      *
979      *   - Validate that the datapath can correctly implement the actions now
980      *     in 'rule'.
981      *
982      *   - Update the datapath flow table with the new actions.
983      *
984      * If the operation synchronously completes, ->rule_modify_actions() may
985      * call ofoperation_complete() before it returns.  Otherwise, ->run()
986      * should call ofoperation_complete() later, after the operation does
987      * complete.
988      *
989      * If the operation fails, then the base ofproto code will restore the
990      * original 'actions' and 'n_actions' of 'rule'.
991      *
992      * ->rule_modify_actions() should not modify any base members of struct
993      * rule. */
994     void (*rule_modify_actions)(struct rule *rule);
995
996     /* Changes the OpenFlow IP fragment handling policy to 'frag_handling',
997      * which takes one of the following values, with the corresponding
998      * meanings:
999      *
1000      *  - OFPC_FRAG_NORMAL: The switch should treat IP fragments the same way
1001      *    as other packets, omitting TCP and UDP port numbers (always setting
1002      *    them to 0).
1003      *
1004      *  - OFPC_FRAG_DROP: The switch should drop all IP fragments without
1005      *    passing them through the flow table.
1006      *
1007      *  - OFPC_FRAG_REASM: The switch should reassemble IP fragments before
1008      *    passing packets through the flow table.
1009      *
1010      *  - OFPC_FRAG_NX_MATCH (a Nicira extension): Similar to OFPC_FRAG_NORMAL,
1011      *    except that TCP and UDP port numbers should be included in fragments
1012      *    with offset 0.
1013      *
1014      * Implementations are not required to support every mode.
1015      * OFPC_FRAG_NORMAL is the default mode when an ofproto is created.
1016      *
1017      * At the time of the call to ->set_frag_handling(), the current mode is
1018      * available in 'ofproto->frag_handling'.  ->set_frag_handling() returns
1019      * true if the requested mode was set, false if it is not supported.
1020      *
1021      * Upon successful return, the caller changes 'ofproto->frag_handling' to
1022      * reflect the new mode.
1023      */
1024     bool (*set_frag_handling)(struct ofproto *ofproto,
1025                               enum ofp_config_flags frag_handling);
1026
1027     /* Implements the OpenFlow OFPT_PACKET_OUT command.  The datapath should
1028      * execute the 'ofpacts_len' bytes of "struct ofpacts" in 'ofpacts'.
1029      *
1030      * The caller retains ownership of 'packet' and of 'ofpacts', so
1031      * ->packet_out() should not modify or free them.
1032      *
1033      * This function must validate that it can correctly implement 'ofpacts'.
1034      * If not, then it should return an OpenFlow error code.
1035      *
1036      * 'flow' reflects the flow information for 'packet'.  All of the
1037      * information in 'flow' is extracted from 'packet', except for
1038      * flow->in_port (see below).  flow->tunnel and its register values are
1039      * zeroed.
1040      *
1041      * flow->in_port comes from the OpenFlow OFPT_PACKET_OUT message.  The
1042      * implementation should reject invalid flow->in_port values by returning
1043      * OFPERR_OFPBRC_BAD_PORT.  (If the implementation called
1044      * ofproto_init_max_ports(), then the client will reject these ports
1045      * itself.)  For consistency, the implementation should consider valid for
1046      * flow->in_port any value that could possibly be seen in a packet that it
1047      * passes to connmgr_send_packet_in().  Ideally, even an implementation
1048      * that never generates packet-ins (e.g. due to hardware limitations)
1049      * should still allow flow->in_port values for every possible physical port
1050      * and OFPP_LOCAL.  The only virtual ports (those above OFPP_MAX) that the
1051      * caller will ever pass in as flow->in_port, other than OFPP_LOCAL, are
1052      * OFPP_NONE and OFPP_CONTROLLER.  The implementation should allow both of
1053      * these, treating each of them as packets generated by the controller as
1054      * opposed to packets originating from some switch port.
1055      *
1056      * (Ordinarily the only effect of flow->in_port is on output actions that
1057      * involve the input port, such as actions that output to OFPP_IN_PORT,
1058      * OFPP_FLOOD, or OFPP_ALL.  flow->in_port can also affect Nicira extension
1059      * "resubmit" actions.)
1060      *
1061      * 'packet' is not matched against the OpenFlow flow table, so its
1062      * statistics should not be included in OpenFlow flow statistics.
1063      *
1064      * Returns 0 if successful, otherwise an OpenFlow error code. */
1065     enum ofperr (*packet_out)(struct ofproto *ofproto, struct ofpbuf *packet,
1066                               const struct flow *flow,
1067                               const struct ofpact *ofpacts,
1068                               size_t ofpacts_len);
1069
1070 /* ## ------------------------- ## */
1071 /* ## OFPP_NORMAL configuration ## */
1072 /* ## ------------------------- ## */
1073
1074     /* Configures NetFlow on 'ofproto' according to the options in
1075      * 'netflow_options', or turns off NetFlow if 'netflow_options' is NULL.
1076      *
1077      * EOPNOTSUPP as a return value indicates that 'ofproto' does not support
1078      * NetFlow, as does a null pointer. */
1079     int (*set_netflow)(struct ofproto *ofproto,
1080                        const struct netflow_options *netflow_options);
1081
1082     void (*get_netflow_ids)(const struct ofproto *ofproto,
1083                             uint8_t *engine_type, uint8_t *engine_id);
1084
1085     /* Configures sFlow on 'ofproto' according to the options in
1086      * 'sflow_options', or turns off sFlow if 'sflow_options' is NULL.
1087      *
1088      * EOPNOTSUPP as a return value indicates that 'ofproto' does not support
1089      * sFlow, as does a null pointer. */
1090     int (*set_sflow)(struct ofproto *ofproto,
1091                      const struct ofproto_sflow_options *sflow_options);
1092
1093     /* Configures connectivity fault management on 'ofport'.
1094      *
1095      * If 'cfm_settings' is nonnull, configures CFM according to its members.
1096      *
1097      * If 'cfm_settings' is null, removes any connectivity fault management
1098      * configuration from 'ofport'.
1099      *
1100      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1101      * support CFM, as does a null pointer. */
1102     int (*set_cfm)(struct ofport *ofport, const struct cfm_settings *s);
1103
1104     /* Checks the fault status of CFM configured on 'ofport'.  Returns a
1105      * bitmask of 'cfm_fault_reason's to indicate a CFM fault (generally
1106      * indicating a connectivity problem).  Returns zero if CFM is not faulted,
1107      * and -1 if CFM is not enabled on 'port'.
1108      *
1109      * This function may be a null pointer if the ofproto implementation does
1110      * not support CFM. */
1111     int (*get_cfm_fault)(const struct ofport *ofport);
1112
1113     /* Check the operational status reported by the remote CFM endpoint of
1114      * 'ofp_port'  Returns 1 if operationally up, 0 if operationally down, and
1115      * -1 if CFM is not enabled on 'ofp_port' or does not support operational
1116      * status.
1117      *
1118      * This function may be a null pointer if the ofproto implementation does
1119      * not support CFM. */
1120     int (*get_cfm_opup)(const struct ofport *ofport);
1121
1122     /* Gets the MPIDs of the remote maintenance points broadcasting to
1123      * 'ofport'.  Populates 'rmps' with a provider owned array of MPIDs, and
1124      * 'n_rmps' with the number of MPIDs in 'rmps'. Returns a number less than
1125      * 0 if CFM is not enabled of 'ofport'.
1126      *
1127      * This function may be a null pointer if the ofproto implementation does
1128      * not support CFM. */
1129     int (*get_cfm_remote_mpids)(const struct ofport *ofport,
1130                                 const uint64_t **rmps, size_t *n_rmps);
1131
1132     /* Checks the health of CFM configured on 'ofport'.  Returns an integer
1133      * to indicate the health percentage of the 'ofport' which is an average of
1134      * the health of all the remote_mps.  Returns an integer between 0 and 100
1135      * where 0 means that the 'ofport' is very unhealthy and 100 means the
1136      * 'ofport' is perfectly healthy.  Returns -1 if CFM is not enabled on
1137      * 'port' or if the number of remote_mpids is > 1.
1138      *
1139      * This function may be a null pointer if the ofproto implementation does
1140      * not support CFM. */
1141     int (*get_cfm_health)(const struct ofport *ofport);
1142
1143     /* Configures spanning tree protocol (STP) on 'ofproto' using the
1144      * settings defined in 's'.
1145      *
1146      * If 's' is nonnull, configures STP according to its members.
1147      *
1148      * If 's' is null, removes any STP configuration from 'ofproto'.
1149      *
1150      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1151      * support STP, as does a null pointer. */
1152     int (*set_stp)(struct ofproto *ofproto,
1153                    const struct ofproto_stp_settings *s);
1154
1155     /* Retrieves state of spanning tree protocol (STP) on 'ofproto'.
1156      *
1157      * Stores STP state for 'ofproto' in 's'.  If the 'enabled' member
1158      * is false, the other member values are not meaningful.
1159      *
1160      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1161      * support STP, as does a null pointer. */
1162     int (*get_stp_status)(struct ofproto *ofproto,
1163                           struct ofproto_stp_status *s);
1164
1165     /* Configures spanning tree protocol (STP) on 'ofport' using the
1166      * settings defined in 's'.
1167      *
1168      * If 's' is nonnull, configures STP according to its members.  The
1169      * caller is responsible for assigning STP port numbers (using the
1170      * 'port_num' member in the range of 1 through 255, inclusive) and
1171      * ensuring there are no duplicates.
1172      *
1173      * If 's' is null, removes any STP configuration from 'ofport'.
1174      *
1175      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1176      * support STP, as does a null pointer. */
1177     int (*set_stp_port)(struct ofport *ofport,
1178                         const struct ofproto_port_stp_settings *s);
1179
1180     /* Retrieves spanning tree protocol (STP) port status of 'ofport'.
1181      *
1182      * Stores STP state for 'ofport' in 's'.  If the 'enabled' member is
1183      * false, the other member values are not meaningful.
1184      *
1185      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1186      * support STP, as does a null pointer. */
1187     int (*get_stp_port_status)(struct ofport *ofport,
1188                                struct ofproto_port_stp_status *s);
1189
1190     /* Registers meta-data associated with the 'n_qdscp' Qualities of Service
1191      * 'queues' attached to 'ofport'.  This data is not intended to be
1192      * sufficient to implement QoS.  Instead, providers may use this
1193      * information to implement features which require knowledge of what queues
1194      * exist on a port, and some basic information about them.
1195      *
1196      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1197      * support QoS, as does a null pointer. */
1198     int (*set_queues)(struct ofport *ofport,
1199                       const struct ofproto_port_queue *queues, size_t n_qdscp);
1200
1201     /* If 's' is nonnull, this function registers a "bundle" associated with
1202      * client data pointer 'aux' in 'ofproto'.  A bundle is the same concept as
1203      * a Port in OVSDB, that is, it consists of one or more "slave" devices
1204      * (Interfaces, in OVSDB) along with VLAN and LACP configuration and, if
1205      * there is more than one slave, a bonding configuration.  If 'aux' is
1206      * already registered then this function updates its configuration to 's'.
1207      * Otherwise, this function registers a new bundle.
1208      *
1209      * If 's' is NULL, this function unregisters the bundle registered on
1210      * 'ofproto' associated with client data pointer 'aux'.  If no such bundle
1211      * has been registered, this has no effect.
1212      *
1213      * This function affects only the behavior of the NXAST_AUTOPATH action and
1214      * output to the OFPP_NORMAL port.  An implementation that does not support
1215      * it at all may set it to NULL or return EOPNOTSUPP.  An implementation
1216      * that supports only a subset of the functionality should implement what
1217      * it can and return 0. */
1218     int (*bundle_set)(struct ofproto *ofproto, void *aux,
1219                       const struct ofproto_bundle_settings *s);
1220
1221     /* If 'port' is part of any bundle, removes it from that bundle.  If the
1222      * bundle now has no ports, deletes the bundle.  If the bundle now has only
1223      * one port, deconfigures the bundle's bonding configuration. */
1224     void (*bundle_remove)(struct ofport *ofport);
1225
1226     /* If 's' is nonnull, this function registers a mirror associated with
1227      * client data pointer 'aux' in 'ofproto'.  A mirror is the same concept as
1228      * a Mirror in OVSDB.  If 'aux' is already registered then this function
1229      * updates its configuration to 's'.  Otherwise, this function registers a
1230      * new mirror.
1231      *
1232      * If 's' is NULL, this function unregisters the mirror registered on
1233      * 'ofproto' associated with client data pointer 'aux'.  If no such mirror
1234      * has been registered, this has no effect.
1235      *
1236      * An implementation that does not support mirroring at all may set
1237      * it to NULL or return EOPNOTSUPP.  An implementation that supports
1238      * only a subset of the functionality should implement what it can
1239      * and return 0. */
1240     int (*mirror_set)(struct ofproto *ofproto, void *aux,
1241                       const struct ofproto_mirror_settings *s);
1242
1243     /* Retrieves statistics from mirror associated with client data
1244      * pointer 'aux' in 'ofproto'.  Stores packet and byte counts in
1245      * 'packets' and 'bytes', respectively.  If a particular counter is
1246      * not supported, the appropriate argument is set to UINT64_MAX.
1247      *
1248      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
1249      * support retrieving mirror statistics. */
1250     int (*mirror_get_stats)(struct ofproto *ofproto, void *aux,
1251                             uint64_t *packets, uint64_t *bytes);
1252
1253     /* Configures the VLANs whose bits are set to 1 in 'flood_vlans' as VLANs
1254      * on which all packets are flooded, instead of using MAC learning.  If
1255      * 'flood_vlans' is NULL, then MAC learning applies to all VLANs.
1256      *
1257      * This function affects only the behavior of the OFPP_NORMAL action.  An
1258      * implementation that does not support it may set it to NULL or return
1259      * EOPNOTSUPP. */
1260     int (*set_flood_vlans)(struct ofproto *ofproto,
1261                            unsigned long *flood_vlans);
1262
1263     /* Returns true if 'aux' is a registered bundle that is currently in use as
1264      * the output for a mirror. */
1265     bool (*is_mirror_output_bundle)(const struct ofproto *ofproto, void *aux);
1266
1267     /* When the configuration option of forward_bpdu changes, this function
1268      * will be invoked. */
1269     void (*forward_bpdu_changed)(struct ofproto *ofproto);
1270
1271     /* Sets the MAC aging timeout for the OFPP_NORMAL action to 'idle_time',
1272      * in seconds. */
1273     void (*set_mac_idle_time)(struct ofproto *ofproto, unsigned int idle_time);
1274
1275 /* Linux VLAN device support (e.g. "eth0.10" for VLAN 10.)
1276  *
1277  * This is deprecated.  It is only for compatibility with broken device drivers
1278  * in old versions of Linux that do not properly support VLANs when VLAN
1279  * devices are not used.  When broken device drivers are no longer in
1280  * widespread use, we will delete these interfaces. */
1281
1282     /* If 'realdev_ofp_port' is nonzero, then this function configures 'ofport'
1283      * as a VLAN splinter port for VLAN 'vid', associated with the real device
1284      * that has OpenFlow port number 'realdev_ofp_port'.
1285      *
1286      * If 'realdev_ofp_port' is zero, then this function deconfigures 'ofport'
1287      * as a VLAN splinter port.
1288      *
1289      * This function should be NULL if a an implementation does not support
1290      * it. */
1291     int (*set_realdev)(struct ofport *ofport,
1292                        uint16_t realdev_ofp_port, int vid);
1293 };
1294
1295 extern const struct ofproto_class ofproto_dpif_class;
1296
1297 int ofproto_class_register(const struct ofproto_class *);
1298 int ofproto_class_unregister(const struct ofproto_class *);
1299
1300 /* ofproto_flow_mod() returns this value if the flow_mod could not be processed
1301  * because it overlaps with an ongoing flow table operation that has not yet
1302  * completed.  The caller should retry the operation later.
1303  *
1304  * ofproto.c also uses this value internally for additional (similar) purposes.
1305  *
1306  * This particular value is a good choice because it is large, so that it does
1307  * not collide with any errno value, but not large enough to collide with an
1308  * OFPERR_* value. */
1309 enum { OFPROTO_POSTPONE = 1 << 16 };
1310 BUILD_ASSERT_DECL(OFPROTO_POSTPONE < OFPERR_OFS);
1311
1312 int ofproto_flow_mod(struct ofproto *, const struct ofputil_flow_mod *);
1313 void ofproto_add_flow(struct ofproto *, const struct match *,
1314                       unsigned int priority,
1315                       const struct ofpact *ofpacts, size_t ofpacts_len);
1316 bool ofproto_delete_flow(struct ofproto *,
1317                          const struct match *, unsigned int priority);
1318 void ofproto_flush_flows(struct ofproto *);
1319
1320 #endif /* ofproto/ofproto-provider.h */