New action NXAST_RESUBMIT_TABLE.
[openvswitch] / ofproto / ofproto-provider.h
1 /*
2  * Copyright (c) 2009, 2010, 2011 Nicira Networks.
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 "classifier.h"
24 #include "list.h"
25 #include "shash.h"
26 #include "timeval.h"
27
28 /* An OpenFlow switch.
29  *
30  * With few exceptions, ofproto implementations may look at these fields but
31  * should not modify them. */
32 struct ofproto {
33     const struct ofproto_class *ofproto_class;
34     char *type;                 /* Datapath type. */
35     char *name;                 /* Datapath name. */
36     struct hmap_node hmap_node; /* In global 'all_ofprotos' hmap. */
37
38     /* Settings. */
39     uint64_t fallback_dpid;     /* Datapath ID if no better choice found. */
40     uint64_t datapath_id;       /* Datapath ID. */
41     unsigned flow_eviction_threshold; /* Threshold at which to begin flow
42                                        * table eviction. Only affects the
43                                        * ofproto-dpif implementation */
44     char *mfr_desc;             /* Manufacturer. */
45     char *hw_desc;              /* Hardware. */
46     char *sw_desc;              /* Software version. */
47     char *serial_desc;          /* Serial number. */
48     char *dp_desc;              /* Datapath description. */
49
50     /* Datapath. */
51     struct hmap ports;          /* Contains "struct ofport"s. */
52     struct shash port_by_name;
53
54     /* Flow tables. */
55     struct classifier *tables;  /* Each classifier contains "struct rule"s. */
56     int n_tables;
57
58     /* OpenFlow connections. */
59     struct connmgr *connmgr;
60
61     /* Flow table operation tracking. */
62     int state;                  /* Internal state. */
63     struct list pending;        /* List of "struct ofopgroup"s. */
64     struct hmap deletions;      /* All OFOPERATION_DELETE "ofoperation"s. */
65 };
66
67 struct ofproto *ofproto_lookup(const char *name);
68 struct ofport *ofproto_get_port(const struct ofproto *, uint16_t ofp_port);
69
70 /* Assigns CLS to each classifier table, in turn, in OFPROTO.
71  *
72  * All parameters are evaluated multiple times. */
73 #define OFPROTO_FOR_EACH_TABLE(CLS, OFPROTO)                \
74     for ((CLS) = (OFPROTO)->tables;                         \
75          (CLS) < &(OFPROTO)->tables[(OFPROTO)->n_tables];   \
76          (CLS)++)
77
78
79 /* An OpenFlow port within a "struct ofproto".
80  *
81  * With few exceptions, ofproto implementations may look at these fields but
82  * should not modify them. */
83 struct ofport {
84     struct ofproto *ofproto;    /* The ofproto that contains this port. */
85     struct hmap_node hmap_node; /* In struct ofproto's "ports" hmap. */
86     struct netdev *netdev;
87     struct ofp_phy_port opp;
88     uint16_t ofp_port;          /* OpenFlow port number. */
89     unsigned int change_seq;
90 };
91
92 /* An OpenFlow flow within a "struct ofproto".
93  *
94  * With few exceptions, ofproto implementations may look at these fields but
95  * should not modify them. */
96 struct rule {
97     struct ofproto *ofproto;     /* The ofproto that contains this rule. */
98     struct list ofproto_node;    /* Owned by ofproto base code. */
99     struct cls_rule cr;          /* In owning ofproto's classifier. */
100
101     struct ofoperation *pending; /* Operation now in progress, if nonnull. */
102
103     ovs_be64 flow_cookie;        /* Controller-issued identifier. */
104
105     long long int created;       /* Creation time. */
106     uint16_t idle_timeout;       /* In seconds from time of last use. */
107     uint16_t hard_timeout;       /* In seconds from time of creation. */
108     uint8_t table_id;            /* Index in ofproto's 'tables' array. */
109     bool send_flow_removed;      /* Send a flow removed message? */
110
111     union ofp_action *actions;   /* OpenFlow actions. */
112     int n_actions;               /* Number of elements in actions[]. */
113 };
114
115 static inline struct rule *
116 rule_from_cls_rule(const struct cls_rule *cls_rule)
117 {
118     return cls_rule ? CONTAINER_OF(cls_rule, struct rule, cr) : NULL;
119 }
120
121 void ofproto_rule_expire(struct rule *, uint8_t reason);
122 void ofproto_rule_destroy(struct rule *);
123
124 void ofoperation_complete(struct ofoperation *, int status);
125 struct rule *ofoperation_get_victim(struct ofoperation *);
126
127 /* ofproto class structure, to be defined by each ofproto implementation.
128  *
129  *
130  * Data Structures
131  * ===============
132  *
133  * These functions work primarily with three different kinds of data
134  * structures:
135  *
136  *   - "struct ofproto", which represents an OpenFlow switch.
137  *
138  *   - "struct ofport", which represents a port within an ofproto.
139  *
140  *   - "struct rule", which represents an OpenFlow flow within an ofproto.
141  *
142  * Each of these data structures contains all of the implementation-independent
143  * generic state for the respective concept, called the "base" state.  None of
144  * them contains any extra space for ofproto implementations to use.  Instead,
145  * each implementation is expected to declare its own data structure that
146  * contains an instance of the generic data structure plus additional
147  * implementation-specific members, called the "derived" state.  The
148  * implementation can use casts or (preferably) the CONTAINER_OF macro to
149  * obtain access to derived state given only a pointer to the embedded generic
150  * data structure.
151  *
152  *
153  * Life Cycle
154  * ==========
155  *
156  * Four stylized functions accompany each of these data structures:
157  *
158  *            "alloc"       "construct"       "destruct"       "dealloc"
159  *            ------------  ----------------  ---------------  --------------
160  *   ofproto  ->alloc       ->construct       ->destruct       ->dealloc
161  *   ofport   ->port_alloc  ->port_construct  ->port_destruct  ->port_dealloc
162  *   rule     ->rule_alloc  ->rule_construct  ->rule_destruct  ->rule_dealloc
163  *
164  * Any instance of a given data structure goes through the following life
165  * cycle:
166  *
167  *   1. The client calls the "alloc" function to obtain raw memory.  If "alloc"
168  *      fails, skip all the other steps.
169  *
170  *   2. The client initializes all of the data structure's base state.  If this
171  *      fails, skip to step 7.
172  *
173  *   3. The client calls the "construct" function.  The implementation
174  *      initializes derived state.  It may refer to the already-initialized
175  *      base state.  If "construct" fails, skip to step 6.
176  *
177  *   4. The data structure is now initialized and in use.
178  *
179  *   5. When the data structure is no longer needed, the client calls the
180  *      "destruct" function.  The implementation uninitializes derived state.
181  *      The base state has not been uninitialized yet, so the implementation
182  *      may still refer to it.
183  *
184  *   6. The client uninitializes all of the data structure's base state.
185  *
186  *   7. The client calls the "dealloc" to free the raw memory.  The
187  *      implementation must not refer to base or derived state in the data
188  *      structure, because it has already been uninitialized.
189  *
190  * Each "alloc" function allocates and returns a new instance of the respective
191  * data structure.  The "alloc" function is not given any information about the
192  * use of the new data structure, so it cannot perform much initialization.
193  * Its purpose is just to ensure that the new data structure has enough room
194  * for base and derived state.  It may return a null pointer if memory is not
195  * available, in which case none of the other functions is called.
196  *
197  * Each "construct" function initializes derived state in its respective data
198  * structure.  When "construct" is called, all of the base state has already
199  * been initialized, so the "construct" function may refer to it.  The
200  * "construct" function is allowed to fail, in which case the client calls the
201  * "dealloc" function (but not the "destruct" function).
202  *
203  * Each "destruct" function uninitializes and frees derived state in its
204  * respective data structure.  When "destruct" is called, the base state has
205  * not yet been uninitialized, so the "destruct" function may refer to it.  The
206  * "destruct" function is not allowed to fail.
207  *
208  * Each "dealloc" function frees raw memory that was allocated by the the
209  * "alloc" function.  The memory's base and derived members might not have ever
210  * been initialized (but if "construct" returned successfully, then it has been
211  * "destruct"ed already).  The "dealloc" function is not allowed to fail.
212  *
213  *
214  * Conventions
215  * ===========
216  *
217  * Most of these functions return 0 if they are successful or a positive error
218  * code on failure.  Depending on the function, valid error codes are either
219  * errno values or OpenFlow error codes constructed with ofp_mkerr().
220  *
221  * Most of these functions are expected to execute synchronously, that is, to
222  * block as necessary to obtain a result.  Thus, these functions may return
223  * EAGAIN (or EWOULDBLOCK or EINPROGRESS) only where the function descriptions
224  * explicitly say those errors are a possibility.  We may relax this
225  * requirement in the future if and when we encounter performance problems. */
226 struct ofproto_class {
227 /* ## ----------------- ## */
228 /* ## Factory Functions ## */
229 /* ## ----------------- ## */
230
231     /* Enumerates the types of all support ofproto types into 'types'.  The
232      * caller has already initialized 'types' and other ofproto classes might
233      * already have added names to it. */
234     void (*enumerate_types)(struct sset *types);
235
236     /* Enumerates the names of all existing datapath of the specified 'type'
237      * into 'names' 'all_dps'.  The caller has already initialized 'names' as
238      * an empty sset.
239      *
240      * 'type' is one of the types enumerated by ->enumerate_types().
241      *
242      * Returns 0 if successful, otherwise a positive errno value.
243      */
244     int (*enumerate_names)(const char *type, struct sset *names);
245
246     /* Deletes the datapath with the specified 'type' and 'name'.  The caller
247      * should have closed any open ofproto with this 'type' and 'name'; this
248      * function is allowed to fail if that is not the case.
249      *
250      * 'type' is one of the types enumerated by ->enumerate_types().
251      * 'name' is one of the names enumerated by ->enumerate_names() for 'type'.
252      *
253      * Returns 0 if successful, otherwise a positive errno value.
254      */
255     int (*del)(const char *type, const char *name);
256
257 /* ## --------------------------- ## */
258 /* ## Top-Level ofproto Functions ## */
259 /* ## --------------------------- ## */
260
261     /* Life-cycle functions for an "ofproto" (see "Life Cycle" above).
262      *
263      *
264      * Construction
265      * ============
266      *
267      * ->construct() should not modify any base members of the ofproto.  The
268      * client will initialize the ofproto's 'ports' and 'tables' members after
269      * construction is complete.
270      *
271      * When ->construct() is called, the client does not yet know how many flow
272      * tables the datapath supports, so ofproto->n_tables will be 0 and
273      * ofproto->tables will be NULL.  ->construct() should store the number of
274      * flow tables supported by the datapath (between 1 and 255, inclusive)
275      * into '*n_tables'.  After a successful return, the client will initialize
276      * the base 'n_tables' member to '*n_tables' and allocate and initialize
277      * the base 'tables' member as the specified number of empty flow tables.
278      * Each flow table will be initially empty, so ->construct() should delete
279      * flows from the underlying datapath, if necessary, rather than populating
280      * the tables.
281      *
282      * Only one ofproto instance needs to be supported for any given datapath.
283      * If a datapath is already open as part of one "ofproto", then another
284      * attempt to "construct" the same datapath as part of another ofproto is
285      * allowed to fail with an error.
286      *
287      * ->construct() returns 0 if successful, otherwise a positive errno
288      * value.
289      *
290      *
291      * Destruction
292      * ===========
293      *
294      * If 'ofproto' has any pending asynchronous operations, ->destruct()
295      * must complete all of them by calling ofoperation_complete().
296      *
297      * ->destruct() must also destroy all remaining rules in the ofproto's
298      * tables, by passing each remaining rule to ofproto_rule_destroy().  The
299      * client will destroy the flow tables themselves after ->destruct()
300      * returns.
301      */
302     struct ofproto *(*alloc)(void);
303     int (*construct)(struct ofproto *ofproto, int *n_tables);
304     void (*destruct)(struct ofproto *ofproto);
305     void (*dealloc)(struct ofproto *ofproto);
306
307     /* Performs any periodic activity required by 'ofproto'.  It should:
308      *
309      *   - Call connmgr_send_packet_in() for each received packet that missed
310      *     in the OpenFlow flow table or that had a OFPP_CONTROLLER output
311      *     action.
312      *
313      *   - Call ofproto_rule_expire() for each OpenFlow flow that has reached
314      *     its hard_timeout or idle_timeout, to expire the flow.
315      *
316      * Returns 0 if successful, otherwise a positive errno value.  The ENODEV
317      * return value specifically means that the datapath underlying 'ofproto'
318      * has been destroyed (externally, e.g. by an admin running ovs-dpctl).
319      */
320     int (*run)(struct ofproto *ofproto);
321
322     /* Causes the poll loop to wake up when 'ofproto''s 'run' function needs to
323      * be called, e.g. by calling the timer or fd waiting functions in
324      * poll-loop.h.  */
325     void (*wait)(struct ofproto *ofproto);
326
327     /* Every "struct rule" in 'ofproto' is about to be deleted, one by one.
328      * This function may prepare for that, for example by clearing state in
329      * advance.  It should *not* actually delete any "struct rule"s from
330      * 'ofproto', only prepare for it.
331      *
332      * This function is optional; it's really just for optimization in case
333      * it's cheaper to delete all the flows from your hardware in a single pass
334      * than to do it one by one. */
335     void (*flush)(struct ofproto *ofproto);
336
337     /* Helper for the OpenFlow OFPT_FEATURES_REQUEST request.
338      *
339      * The implementation should store true in '*arp_match_ip' if the switch
340      * supports matching IP addresses inside ARP requests and replies, false
341      * otherwise.
342      *
343      * The implementation should store in '*actions' a bitmap of the supported
344      * OpenFlow actions: the bit with value (1 << n) should be set to 1 if the
345      * implementation supports the action with value 'n', and to 0 otherwise.
346      * For example, if the implementation supports the OFPAT_OUTPUT and
347      * OFPAT_ENQUEUE actions, but no others, it would set '*actions' to (1 <<
348      * OFPAT_OUTPUT) | (1 << OFPAT_ENQUEUE).  Vendor actions are not included
349      * in '*actions'. */
350     void (*get_features)(struct ofproto *ofproto,
351                          bool *arp_match_ip, uint32_t *actions);
352
353     /* Helper for the OpenFlow OFPST_TABLE statistics request.
354      *
355      * The 'ots' array contains 'ofproto->n_tables' elements.  Each element is
356      * initialized as:
357      *
358      *   - 'table_id' to the array index.
359      *
360      *   - 'name' to "table#" where # is the table ID.
361      *
362      *   - 'wildcards' to OFPFW_ALL.
363      *
364      *   - 'max_entries' to 1,000,000.
365      *
366      *   - 'active_count' to the classifier_count() for the table.
367      *
368      *   - 'lookup_count' and 'matched_count' to 0.
369      *
370      * The implementation should update any members in each element for which
371      * it has better values:
372      *
373      *   - 'name' to a more meaningful name.
374      *
375      *   - 'wildcards' to the set of wildcards actually supported by the table
376      *     (if it doesn't support all OpenFlow wildcards).
377      *
378      *   - 'max_entries' to the maximum number of flows actually supported by
379      *     the hardware.
380      *
381      *   - 'lookup_count' to the number of packets looked up in this flow table
382      *     so far.
383      *
384      *   - 'matched_count' to the number of packets looked up in this flow
385      *     table so far that matched one of the flow entries.
386      *
387      * Keep in mind that all of the members of struct ofp_table_stats are in
388      * network byte order.
389      */
390     void (*get_tables)(struct ofproto *ofproto, struct ofp_table_stats *ots);
391
392 /* ## ---------------- ## */
393 /* ## ofport Functions ## */
394 /* ## ---------------- ## */
395
396     /* Life-cycle functions for a "struct ofport" (see "Life Cycle" above).
397      *
398      * ->port_construct() should not modify any base members of the ofport.
399      *
400      * ofports are managed by the base ofproto code.  The ofproto
401      * implementation should only create and destroy them in response to calls
402      * to these functions.  The base ofproto code will create and destroy
403      * ofports in the following situations:
404      *
405      *   - Just after the ->construct() function is called, the base ofproto
406      *     iterates over all of the implementation's ports, using
407      *     ->port_dump_start() and related functions, and constructs an ofport
408      *     for each dumped port.
409      *
410      *   - If ->port_poll() reports that a specific port has changed, then the
411      *     base ofproto will query that port with ->port_query_by_name() and
412      *     construct or destruct ofports as necessary to reflect the updated
413      *     set of ports.
414      *
415      *   - If ->port_poll() returns ENOBUFS to report an unspecified port set
416      *     change, then the base ofproto will iterate over all of the
417      *     implementation's ports, in the same way as at ofproto
418      *     initialization, and construct and destruct ofports to reflect all of
419      *     the changes.
420      *
421      * ->port_construct() returns 0 if successful, otherwise a positive errno
422      * value.
423      */
424     struct ofport *(*port_alloc)(void);
425     int (*port_construct)(struct ofport *ofport);
426     void (*port_destruct)(struct ofport *ofport);
427     void (*port_dealloc)(struct ofport *ofport);
428
429     /* Called after 'ofport->netdev' is replaced by a new netdev object.  If
430      * the ofproto implementation uses the ofport's netdev internally, then it
431      * should switch to using the new one.  The old one has been closed.
432      *
433      * An ofproto implementation that doesn't need to do anything in this
434      * function may use a null pointer. */
435     void (*port_modified)(struct ofport *ofport);
436
437     /* Called after an OpenFlow OFPT_PORT_MOD request changes a port's
438      * configuration.  'ofport->opp.config' contains the new configuration.
439      * 'old_config' contains the previous configuration.
440      *
441      * The caller implements OFPPC_PORT_DOWN using netdev functions to turn
442      * NETDEV_UP on and off, so this function doesn't have to do anything for
443      * that bit (and it won't be called if that is the only bit that
444      * changes). */
445     void (*port_reconfigured)(struct ofport *ofport, ovs_be32 old_config);
446
447     /* Looks up a port named 'devname' in 'ofproto'.  On success, initializes
448      * '*port' appropriately.
449      *
450      * The caller owns the data in 'port' and must free it with
451      * ofproto_port_destroy() when it is no longer needed. */
452     int (*port_query_by_name)(const struct ofproto *ofproto,
453                               const char *devname, struct ofproto_port *port);
454
455     /* Attempts to add 'netdev' as a port on 'ofproto'.  Returns 0 if
456      * successful, otherwise a positive errno value.  If successful, sets
457      * '*ofp_portp' to the new port's port number.
458      *
459      * It doesn't matter whether the new port will be returned by a later call
460      * to ->port_poll(); the implementation may do whatever is more
461      * convenient. */
462     int (*port_add)(struct ofproto *ofproto, struct netdev *netdev,
463                     uint16_t *ofp_portp);
464
465     /* Deletes port number 'ofp_port' from the datapath for 'ofproto'.  Returns
466      * 0 if successful, otherwise a positive errno value.
467      *
468      * It doesn't matter whether the new port will be returned by a later call
469      * to ->port_poll(); the implementation may do whatever is more
470      * convenient. */
471     int (*port_del)(struct ofproto *ofproto, uint16_t ofp_port);
472
473     /* Port iteration functions.
474      *
475      * The client might not be entirely in control of the ports within an
476      * ofproto.  Some hardware implementations, for example, might have a fixed
477      * set of ports in a datapath, and the Linux datapath allows the system
478      * administrator to externally add and remove ports with ovs-dpctl.  For
479      * this reason, the client needs a way to iterate through all the ports
480      * that are actually in a datapath.  These functions provide that
481      * functionality.
482      *
483      * The 'state' pointer provides the implementation a place to
484      * keep track of its position.  Its format is opaque to the caller.
485      *
486      * The ofproto provider retains ownership of the data that it stores into
487      * ->port_dump_next()'s 'port' argument.  The data must remain valid until
488      * at least the next call to ->port_dump_next() or ->port_dump_done() for
489      * 'state'.  The caller will not modify or free it.
490      *
491      * Details
492      * =======
493      *
494      * ->port_dump_start() attempts to begin dumping the ports in 'ofproto'.
495      * On success, it should return 0 and initialize '*statep' with any data
496      * needed for iteration.  On failure, returns a positive errno value, and
497      * the client will not call ->port_dump_next() or ->port_dump_done().
498      *
499      * ->port_dump_next() attempts to retrieve another port from 'ofproto' for
500      * 'state'.  If there is another port, it should store the port's
501      * information into 'port' and return 0.  It should return EOF if all ports
502      * have already been iterated.  Otherwise, on error, it should return a
503      * positive errno value.  This function will not be called again once it
504      * returns nonzero once for a given iteration (but the 'port_dump_done'
505      * function will be called afterward).
506      *
507      * ->port_dump_done() allows the implementation to release resources used
508      * for iteration.  The caller might decide to stop iteration in the middle
509      * by calling this function before ->port_dump_next() returns nonzero.
510      *
511      * Usage Example
512      * =============
513      *
514      * int error;
515      * void *state;
516      *
517      * error = ofproto->ofproto_class->port_dump_start(ofproto, &state);
518      * if (!error) {
519      *     for (;;) {
520      *         struct ofproto_port port;
521      *
522      *         error = ofproto->ofproto_class->port_dump_next(
523      *                     ofproto, state, &port);
524      *         if (error) {
525      *             break;
526      *         }
527      *         // Do something with 'port' here (without modifying or freeing
528      *         // any of its data).
529      *     }
530      *     ofproto->ofproto_class->port_dump_done(ofproto, state);
531      * }
532      * // 'error' is now EOF (success) or a positive errno value (failure).
533      */
534     int (*port_dump_start)(const struct ofproto *ofproto, void **statep);
535     int (*port_dump_next)(const struct ofproto *ofproto, void *state,
536                           struct ofproto_port *port);
537     int (*port_dump_done)(const struct ofproto *ofproto, void *state);
538
539     /* Polls for changes in the set of ports in 'ofproto'.  If the set of ports
540      * in 'ofproto' has changed, then this function should do one of the
541      * following:
542      *
543      * - Preferably: store the name of the device that was added to or deleted
544      *   from 'ofproto' in '*devnamep' and return 0.  The caller is responsible
545      *   for freeing '*devnamep' (with free()) when it no longer needs it.
546      *
547      * - Alternatively: return ENOBUFS, without indicating the device that was
548      *   added or deleted.
549      *
550      * Occasional 'false positives', in which the function returns 0 while
551      * indicating a device that was not actually added or deleted or returns
552      * ENOBUFS without any change, are acceptable.
553      *
554      * The purpose of 'port_poll' is to let 'ofproto' know about changes made
555      * externally to the 'ofproto' object, e.g. by a system administrator via
556      * ovs-dpctl.  Therefore, it's OK, and even preferable, for port_poll() to
557      * not report changes made through calls to 'port_add' or 'port_del' on the
558      * same 'ofproto' object.  (But it's OK for it to report them too, just
559      * slightly less efficient.)
560      *
561      * If the set of ports in 'ofproto' has not changed, returns EAGAIN.  May
562      * also return other positive errno values to indicate that something has
563      * gone wrong.
564      *
565      * If the set of ports in a datapath is fixed, or if the only way that the
566      * set of ports in a datapath can change is through ->port_add() and
567      * ->port_del(), then this function may be a null pointer.
568      */
569     int (*port_poll)(const struct ofproto *ofproto, char **devnamep);
570
571     /* Arranges for the poll loop to wake up when ->port_poll() will return a
572      * value other than EAGAIN.
573      *
574      * If the set of ports in a datapath is fixed, or if the only way that the
575      * set of ports in a datapath can change is through ->port_add() and
576      * ->port_del(), or if the poll loop will always wake up anyway when
577      * ->port_poll() will return a value other than EAGAIN, then this function
578      * may be a null pointer.
579      */
580     void (*port_poll_wait)(const struct ofproto *ofproto);
581
582     /* Checks the status of LACP negotiation for 'port'.  Returns 1 if LACP
583      * partner information for 'port' is up-to-date, 0 if LACP partner
584      * information is not current (generally indicating a connectivity
585      * problem), or -1 if LACP is not enabled on 'port'.
586      *
587      * This function may be a null pointer if the ofproto implementation does
588      * not support LACP. */
589     int (*port_is_lacp_current)(const struct ofport *port);
590
591 /* ## ----------------------- ## */
592 /* ## OpenFlow Rule Functions ## */
593 /* ## ----------------------- ## */
594
595
596
597     /* Chooses an appropriate table for 'cls_rule' within 'ofproto'.  On
598      * success, stores the table ID into '*table_idp' and returns 0.  On
599      * failure, returns an OpenFlow error code (as returned by ofp_mkerr()).
600      *
601      * The choice of table should be a function of 'cls_rule' and 'ofproto''s
602      * datapath capabilities.  It should not depend on the flows already in
603      * 'ofproto''s flow tables.  Failure implies that an OpenFlow rule with
604      * 'cls_rule' as its matching condition can never be inserted into
605      * 'ofproto', even starting from an empty flow table.
606      *
607      * If multiple tables are candidates for inserting the flow, the function
608      * should choose one arbitrarily (but deterministically).
609      *
610      * If this function is NULL then table 0 is always chosen. */
611     int (*rule_choose_table)(const struct ofproto *ofproto,
612                              const struct cls_rule *cls_rule,
613                              uint8_t *table_idp);
614
615     /* Life-cycle functions for a "struct rule" (see "Life Cycle" above).
616      *
617      *
618      * Asynchronous Operation Support
619      * ==============================
620      *
621      * The life-cycle operations on rules can operate asynchronously, meaning
622      * that ->rule_construct() and ->rule_destruct() only need to initiate
623      * their respective operations and do not need to wait for them to complete
624      * before they return.  ->rule_modify_actions() also operates
625      * asynchronously.
626      *
627      * An ofproto implementation reports the success or failure of an
628      * asynchronous operation on a rule using the rule's 'pending' member,
629      * which points to a opaque "struct ofoperation" that represents the
630      * ongoing opreation.  When the operation completes, the ofproto
631      * implementation calls ofoperation_complete(), passing the ofoperation and
632      * an error indication.
633      *
634      * Only the following contexts may call ofoperation_complete():
635      *
636      *   - The function called to initiate the operation,
637      *     e.g. ->rule_construct() or ->rule_destruct().  This is the best
638      *     choice if the operation completes quickly.
639      *
640      *   - The implementation's ->run() function.
641      *
642      *   - The implementation's ->destruct() function.
643      *
644      * The ofproto base code updates the flow table optimistically, assuming
645      * that the operation will probably succeed:
646      *
647      *   - ofproto adds or replaces the rule in the flow table before calling
648      *     ->rule_construct().
649      *
650      *   - ofproto updates the rule's actions before calling
651      *     ->rule_modify_actions().
652      *
653      *   - ofproto removes the rule before calling ->rule_destruct().
654      *
655      * With one exception, when an asynchronous operation completes with an
656      * error, ofoperation_complete() backs out the already applied changes:
657      *
658      *   - If adding or replacing a rule in the flow table fails, ofproto
659      *     removes the new rule or restores the original rule.
660      *
661      *   - If modifying a rule's actions fails, ofproto restores the original
662      *     actions.
663      *
664      *   - Removing a rule is not allowed to fail.  It must always succeed.
665      *
666      * The ofproto base code serializes operations: if any operation is in
667      * progress on a given rule, ofproto postpones initiating any new operation
668      * on that rule until the pending operation completes.  Therefore, every
669      * operation must eventually complete through a call to
670      * ofoperation_complete() to avoid delaying new operations indefinitely
671      * (including any OpenFlow request that affects the rule in question, even
672      * just to query its statistics).
673      *
674      *
675      * Construction
676      * ============
677      *
678      * When ->rule_construct() is called, the caller has already inserted
679      * 'rule' into 'rule->ofproto''s flow table numbered 'rule->table_id'.
680      * There are two cases:
681      *
682      *   - 'rule' is a new rule in its flow table.  In this case,
683      *     ofoperation_get_victim(rule) returns NULL.
684      *
685      *   - 'rule' is replacing an existing rule in its flow table that had the
686      *     same matching criteria and priority.  In this case,
687      *     ofoperation_get_victim(rule) returns the rule being replaced.
688      *
689      * ->rule_construct() should set the following in motion:
690      *
691      *   - Validate that the matching rule in 'rule->cr' is supported by the
692      *     datapath.  For example, if the rule's table does not support
693      *     registers, then it is an error if 'rule->cr' does not wildcard all
694      *     registers.
695      *
696      *   - Validate that 'rule->actions' and 'rule->n_actions' are well-formed
697      *     OpenFlow actions that the datapath can correctly implement.  The
698      *     validate_actions() function (in ofp-util.c) can be useful as a model
699      *     for action validation, but it accepts all of the OpenFlow actions
700      *     that OVS understands.  If your ofproto implementation only
701      *     implements a subset of those, then you should implement your own
702      *     action validation.
703      *
704      *   - If the rule is valid, update the datapath flow table, adding the new
705      *     rule or replacing the existing one.
706      *
707      * (On failure, the ofproto code will roll back the insertion from the flow
708      * table, either removing 'rule' or replacing it by the flow that was
709      * originally in its place.)
710      *
711      * ->rule_construct() must act in one of the following ways:
712      *
713      *   - If it succeeds, it must call ofoperation_complete() and return 0.
714      *
715      *   - If it fails, it must act in one of the following ways:
716      *
717      *       * Call ofoperation_complete() and return 0.
718      *
719      *       * Return an OpenFlow error code (as returned by ofp_mkerr()).  (Do
720      *         not call ofoperation_complete() in this case.)
721      *
722      *     In the former case, ->rule_destruct() will be called; in the latter
723      *     case, it will not.  ->rule_dealloc() will be called in either case.
724      *
725      *   - If the operation is only partially complete, then it must return 0.
726      *     Later, when the operation is complete, the ->run() or ->destruct()
727      *     function must call ofoperation_complete() to report success or
728      *     failure.
729      *
730      * ->rule_construct() should not modify any base members of struct rule.
731      *
732      *
733      * Destruction
734      * ===========
735      *
736      * When ->rule_destruct() is called, the caller has already removed 'rule'
737      * from 'rule->ofproto''s flow table.  ->rule_destruct() should set in
738      * motion removing 'rule' from the datapath flow table.  If removal
739      * completes synchronously, it should call ofoperation_complete().
740      * Otherwise, the ->run() or ->destruct() function must later call
741      * ofoperation_complete() after the operation completes.
742      *
743      * Rule destruction must not fail. */
744     struct rule *(*rule_alloc)(void);
745     int (*rule_construct)(struct rule *rule);
746     void (*rule_destruct)(struct rule *rule);
747     void (*rule_dealloc)(struct rule *rule);
748
749     /* Obtains statistics for 'rule', storing the number of packets that have
750      * matched it in '*packet_count' and the number of bytes in those packets
751      * in '*byte_count'.  UINT64_MAX indicates that the packet count or byte
752      * count is unknown. */
753     void (*rule_get_stats)(struct rule *rule, uint64_t *packet_count,
754                            uint64_t *byte_count);
755
756     /* Applies the actions in 'rule' to 'packet'.  (This implements sending
757      * buffered packets for OpenFlow OFPT_FLOW_MOD commands.)
758      *
759      * Takes ownership of 'packet' (so it should eventually free it, with
760      * ofpbuf_delete()).
761      *
762      * 'flow' reflects the flow information for 'packet'.  All of the
763      * information in 'flow' is extracted from 'packet', except for
764      * flow->tun_id and flow->in_port, which are assigned the correct values
765      * for the incoming packet.  The register values are zeroed.
766      *
767      * The statistics for 'packet' should be included in 'rule'.
768      *
769      * Returns 0 if successful, otherwise an OpenFlow error code (as returned
770      * by ofp_mkerr()). */
771     int (*rule_execute)(struct rule *rule, struct flow *flow,
772                         struct ofpbuf *packet);
773
774     /* When ->rule_modify_actions() is called, the caller has already replaced
775      * the OpenFlow actions in 'rule' by a new set.  (The original actions are
776      * in rule->pending->actions.)
777      *
778      * ->rule_modify_actions() should set the following in motion:
779      *
780      *   - Validate that the actions now in 'rule' are well-formed OpenFlow
781      *     actions that the datapath can correctly implement.
782      *
783      *   - Update the datapath flow table with the new actions.
784      *
785      * If the operation synchronously completes, ->rule_modify_actions() may
786      * call ofoperation_complete() before it returns.  Otherwise, ->run()
787      * should call ofoperation_complete() later, after the operation does
788      * complete.
789      *
790      * If the operation fails, then the base ofproto code will restore the
791      * original 'actions' and 'n_actions' of 'rule'.
792      *
793      * ->rule_modify_actions() should not modify any base members of struct
794      * rule. */
795     void (*rule_modify_actions)(struct rule *rule);
796
797     /* These functions implement the OpenFlow IP fragment handling policy.  By
798      * default ('drop_frags' == false), an OpenFlow switch should treat IP
799      * fragments the same way as other packets (although TCP and UDP port
800      * numbers cannot be determined).  With 'drop_frags' == true, the switch
801      * should drop all IP fragments without passing them through the flow
802      * table. */
803     bool (*get_drop_frags)(struct ofproto *ofproto);
804     void (*set_drop_frags)(struct ofproto *ofproto, bool drop_frags);
805
806     /* Implements the OpenFlow OFPT_PACKET_OUT command.  The datapath should
807      * execute the 'n_actions' in the 'actions' array on 'packet'.
808      *
809      * The caller retains ownership of 'packet', so ->packet_out() should not
810      * modify or free it.
811      *
812      * This function must validate that the 'n_actions' elements in 'actions'
813      * are well-formed OpenFlow actions that can be correctly implemented by
814      * the datapath.  If not, then it should return an OpenFlow error code (as
815      * returned by ofp_mkerr()).
816      *
817      * 'flow' reflects the flow information for 'packet'.  All of the
818      * information in 'flow' is extracted from 'packet', except for
819      * flow->in_port, which is taken from the OFPT_PACKET_OUT message.
820      * flow->tun_id and its register values are zeroed.
821      *
822      * 'packet' is not matched against the OpenFlow flow table, so its
823      * statistics should not be included in OpenFlow flow statistics.
824      *
825      * Returns 0 if successful, otherwise an OpenFlow error code (as returned
826      * by ofp_mkerr()). */
827     int (*packet_out)(struct ofproto *ofproto, struct ofpbuf *packet,
828                       const struct flow *flow,
829                       const union ofp_action *actions,
830                       size_t n_actions);
831
832 /* ## ------------------------- ## */
833 /* ## OFPP_NORMAL configuration ## */
834 /* ## ------------------------- ## */
835
836     /* Configures NetFlow on 'ofproto' according to the options in
837      * 'netflow_options', or turns off NetFlow if 'netflow_options' is NULL.
838      *
839      * EOPNOTSUPP as a return value indicates that 'ofproto' does not support
840      * NetFlow, as does a null pointer. */
841     int (*set_netflow)(struct ofproto *ofproto,
842                        const struct netflow_options *netflow_options);
843
844     void (*get_netflow_ids)(const struct ofproto *ofproto,
845                             uint8_t *engine_type, uint8_t *engine_id);
846
847     /* Configures sFlow on 'ofproto' according to the options in
848      * 'sflow_options', or turns off sFlow if 'sflow_options' is NULL.
849      *
850      * EOPNOTSUPP as a return value indicates that 'ofproto' does not support
851      * sFlow, as does a null pointer. */
852     int (*set_sflow)(struct ofproto *ofproto,
853                      const struct ofproto_sflow_options *sflow_options);
854
855     /* Configures connectivity fault management on 'ofport'.
856      *
857      * If 'cfm_settings' is nonnull, configures CFM according to its members.
858      *
859      * If 'cfm_settings' is null, removes any connectivity fault management
860      * configuration from 'ofport'.
861      *
862      * EOPNOTSUPP as a return value indicates that this ofproto_class does not
863      * support CFM, as does a null pointer. */
864     int (*set_cfm)(struct ofport *ofport, const struct cfm_settings *s);
865
866     /* Checks the fault status of CFM configured on 'ofport'.  Returns 1 if CFM
867      * is faulted (generally indicating a connectivity problem), 0 if CFM is
868      * not faulted, or -1 if CFM is not enabled on 'port'
869      *
870      * This function may be a null pointer if the ofproto implementation does
871      * not support CFM. */
872     int (*get_cfm_fault)(const struct ofport *ofport);
873
874     /* If 's' is nonnull, this function registers a "bundle" associated with
875      * client data pointer 'aux' in 'ofproto'.  A bundle is the same concept as
876      * a Port in OVSDB, that is, it consists of one or more "slave" devices
877      * (Interfaces, in OVSDB) along with VLAN and LACP configuration and, if
878      * there is more than one slave, a bonding configuration.  If 'aux' is
879      * already registered then this function updates its configuration to 's'.
880      * Otherwise, this function registers a new bundle.
881      *
882      * If 's' is NULL, this function unregisters the bundle registered on
883      * 'ofproto' associated with client data pointer 'aux'.  If no such bundle
884      * has been registered, this has no effect.
885      *
886      * This function affects only the behavior of the NXAST_AUTOPATH action and
887      * output to the OFPP_NORMAL port.  An implementation that does not support
888      * it at all may set it to NULL or return EOPNOTSUPP.  An implementation
889      * that supports only a subset of the functionality should implement what
890      * it can and return 0. */
891     int (*bundle_set)(struct ofproto *ofproto, void *aux,
892                       const struct ofproto_bundle_settings *s);
893
894     /* If 'port' is part of any bundle, removes it from that bundle.  If the
895      * bundle now has no ports, deletes the bundle.  If the bundle now has only
896      * one port, deconfigures the bundle's bonding configuration. */
897     void (*bundle_remove)(struct ofport *ofport);
898
899     /* If 's' is nonnull, this function registers a mirror associated with
900      * client data pointer 'aux' in 'ofproto'.  A mirror is the same concept as
901      * a Mirror in OVSDB.  If 'aux' is already registered then this function
902      * updates its configuration to 's'.  Otherwise, this function registers a
903      * new mirror.
904      *
905      * If 's' is NULL, this function unregisters the mirror registered on
906      * 'ofproto' associated with client data pointer 'aux'.  If no such mirror
907      * has been registered, this has no effect.
908      *
909      * This function affects only the behavior of the OFPP_NORMAL action.  An
910      * implementation that does not support it at all may set it to NULL or
911      * return EOPNOTSUPP.  An implementation that supports only a subset of the
912      * functionality should implement what it can and return 0. */
913     int (*mirror_set)(struct ofproto *ofproto, void *aux,
914                       const struct ofproto_mirror_settings *s);
915
916     /* Configures the VLANs whose bits are set to 1 in 'flood_vlans' as VLANs
917      * on which all packets are flooded, instead of using MAC learning.  If
918      * 'flood_vlans' is NULL, then MAC learning applies to all VLANs.
919      *
920      * This function affects only the behavior of the OFPP_NORMAL action.  An
921      * implementation that does not support it may set it to NULL or return
922      * EOPNOTSUPP. */
923     int (*set_flood_vlans)(struct ofproto *ofproto,
924                            unsigned long *flood_vlans);
925
926     /* Returns true if 'aux' is a registered bundle that is currently in use as
927      * the output for a mirror. */
928     bool (*is_mirror_output_bundle)(struct ofproto *ofproto, void *aux);
929 };
930
931 extern const struct ofproto_class ofproto_dpif_class;
932
933 int ofproto_class_register(const struct ofproto_class *);
934 int ofproto_class_unregister(const struct ofproto_class *);
935
936 void ofproto_add_flow(struct ofproto *, const struct cls_rule *,
937                       const union ofp_action *, size_t n_actions);
938 bool ofproto_delete_flow(struct ofproto *, const struct cls_rule *);
939 void ofproto_flush_flows(struct ofproto *);
940
941 #endif /* ofproto/ofproto-provider.h */