ofproto/wdp-provider.h

   1 /*
   2  * Copyright (c) 2010 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 WDP_PROVIDER_H
  18 #define WDP_PROVIDER_H 1
  19
  20 /* Provider interface to wdps, which provide an interface to an Open vSwitch
  21  * datapath. */
  22
  23 #include <assert.h>
  24 #include "util.h"
  25 #include "wdp.h"
  26
  27 #ifdef  __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 static inline struct wdp_rule *
  32 wdp_rule_cast(const struct cls_rule *cls_rule)
  33 {
  34     return cls_rule ? CONTAINER_OF(cls_rule, struct wdp_rule, cr) : NULL;
  35 }
  36
  37 /* Open vSwitch datapath interface.
  38  *
  39  * This structure should be treated as opaque by wdp implementations. */
  40 struct wdp {
  41     const struct wdp_class *wdp_class;
  42     char *base_name;
  43     char *full_name;
  44     uint8_t netflow_engine_type;
  45     uint8_t netflow_engine_id;
  46 };
  47
  48 void wdp_init(struct wdp *, const struct wdp_class *, const char *name,
  49               uint8_t netflow_engine_type, uint8_t netflow_engine_id);
  50 void wdp_uninit(struct wdp *wdp, bool close);
  51
  52 static inline void wdp_assert_class(const struct wdp *wdp,
  53                                     const struct wdp_class *wdp_class)
  54 {
  55     assert(wdp->wdp_class == wdp_class);
  56 }
  57
  58 /* Datapath interface class structure, to be defined by each implementation of
  59  * a datapath interface.
  60  *
  61  * These functions return 0 if successful or a positive errno value on failure,
  62  * except where otherwise noted.
  63  *
  64  * These functions are expected to execute synchronously, that is, to block as
  65  * necessary to obtain a result.  Thus, they may not return EAGAIN or
  66  * EWOULDBLOCK or EINPROGRESS.  We may relax this requirement in the future if
  67  * and when we encounter performance problems. */
  68 struct wdp_class {
  69     /* Type of wdp in this class, e.g. "system", "netdev", etc.
  70      *
  71      * One of the providers should supply a "system" type, since this is
  72      * the type assumed if no type is specified when opening a wdp. */
  73     const char *type;
  74
  75     /* Performs periodic work needed by wdps of this class, if any is
  76      * necessary. */
  77     void (*run)(void);
  78
  79     /* Arranges for poll_block() to wake up if the "run" member function needs
  80      * to be called. */
  81     void (*wait)(void);
  82
  83     /* Enumerates the names of all known created datapaths for 'wdp_class',
  84      * if possible, into 'all_wdps'.  The caller has already initialized
  85      * 'all_wdps' and other wdp classes might already have added names to it.
  86      *
  87      * This is used by the vswitch at startup, so that it can delete any
  88      * datapaths that are not configured.
  89      *
  90      * Some kinds of datapaths might not be practically enumerable, in which
  91      * case this function may be a null pointer. */
  92     int (*enumerate)(const struct wdp_class *wdp_class,
  93                      struct svec *all_wdps);
  94
  95     /* Attempts to open an existing wdp of class 'wdp_class' called 'name',
  96      * if 'create' is false, or to open an existing wdp or create a new one,
  97      * if 'create' is true.
  98      *
  99      * If successful, stores a pointer to the new wdp in '*wdpp'.  On
 100      * failure there are no requirements on what is stored in '*wdpp'. */
 101     int (*open)(const struct wdp_class *wdp_class, const char *name,
 102                 bool create, struct wdp **wdpp);
 103
 104     /* Closes 'wdp' and frees associated memory. */
 105     void (*close)(struct wdp *wdp);
 106
 107     /* Enumerates all names that may be used to open 'wdp' into 'all_names'.
 108      * The Linux datapath, for example, supports opening a datapath both by
 109      * number, e.g. "wdp0", and by the name of the datapath's local port.  For
 110      * some datapaths, this might be an infinite set (e.g. in a file name,
 111      * slashes may be duplicated any number of times), in which case only the
 112      * names most likely to be used should be enumerated.
 113      *
 114      * The caller has already initialized 'all_names' and might already have
 115      * added some names to it.  This function should not disturb any existing
 116      * names in 'all_names'.
 117      *
 118      * If a datapath class does not support multiple names for a datapath, this
 119      * function may be a null pointer.
 120      *
 121      * This is used by the vswitch at startup, */
 122     int (*get_all_names)(const struct wdp *wdp, struct svec *all_names);
 123
 124     /* Attempts to destroy the wdp underlying 'wdp'.
 125      *
 126      * If successful, 'wdp' will not be used again except as an argument for
 127      * the 'close' member function. */
 128     int (*destroy)(struct wdp *wdp);
 129
 130     /* Creates a "struct ofp_switch_features" for 'wdp' and stores it in
 131      * '*featuresp'.  The caller is responsible for freeing '*featuresp' (with
 132      * ofpbuf_delete()) when it is no longer needed. */
 133     int (*get_features)(const struct wdp *wdp, struct ofpbuf **featuresp);
 134
 135     /* Retrieves statistics for 'wdp' into 'stats'. */
 136     int (*get_stats)(const struct wdp *wdp, struct wdp_stats *stats);
 137
 138     /* Retrieves 'wdp''s current treatment of IP fragments into '*drop_frags':
 139      * true indicates that fragments are dropped, false indicates that
 140      * fragments are treated in the same way as other IP packets (except that
 141      * the L4 header cannot be read). */
 142     int (*get_drop_frags)(const struct wdp *wdp, bool *drop_frags);
 143
 144     /* Changes 'wdp''s treatment of IP fragments to 'drop_frags', whose
 145      * meaning is the same as for the get_drop_frags member function. */
 146     int (*set_drop_frags)(struct wdp *wdp, bool drop_frags);
 147
 148     /* Creates a new port in 'wdp' connected to network device 'devname'.  If
 149      * 'internal' is true, creates the port as an internal port.  If
 150      * successful, sets '*port_no' to the new port's port number. */
 151     int (*port_add)(struct wdp *wdp, const char *devname,
 152                     bool internal, uint16_t *port_no);
 153
 154     /* Removes port numbered 'port_no' from 'wdp'. */
 155     int (*port_del)(struct wdp *wdp, uint16_t port_no);
 156
 157     /* Looks up a port in 'wdp' by name or number.  On success, returns 0 and
 158      * points '*portp' to a wdp_port representing the specified port.  On
 159      * failure, returns a positive errno value and sets '*portp' to NULL.
 160      *
 161      * The caller is not allowed to modify or free the returned wdp_port.  The
 162      * wdp_port must remain accessible until the next call to the 'run' member
 163      * function for this class or or wdp_port_poll() for 'wdp'. */
 164     int (*port_query_by_number)(const struct wdp *wdp, uint16_t port_no,
 165                                 struct wdp_port **portp);
 166     int (*port_query_by_name)(const struct wdp *wdp, const char *devname,
 167                               struct wdp_port **portp);
 168
 169     /* Obtains a list of all the ports in 'wdp'.  Sets '*portsp' to point to
 170      * an array of pointers to port structures and '*n_portsp' to the number of
 171      * pointers in the array.
 172      *
 173      * The caller is responsible for freeing '*portsp' by calling free().  The
 174      * calleris not allowed to modify or free the individual wdp_port
 175      * structures.  The wdp_ports must remain accessible until the next call to
 176      * the 'run' member function for this class or or wdp_port_poll() for
 177      * 'wdp'. */
 178     int (*port_list)(const struct wdp *wdp, struct wdp_port ***portsp,
 179                      size_t *n_portsp);
 180
 181     int (*port_set_config)(struct wdp *sdpif, uint16_t port_no,
 182                            uint32_t config);
 183
 184     /* Polls for changes in the set of ports in 'wdp'.  If the set of ports
 185      * in 'wdp' has changed, then this function should do one of the
 186      * following:
 187      *
 188      * - Preferably: store the name of the device that was added to or deleted
 189      *   from 'wdp' in '*devnamep' and return 0.  The caller is responsible
 190      *   for freeing '*devnamep' (with free()) when it no longer needs it.
 191      *
 192      * - Alternatively: return ENOBUFS, without indicating the device that was
 193      *   added or deleted.
 194      *
 195      * Occasional 'false positives', in which the function returns 0 while
 196      * indicating a device that was not actually added or deleted or returns
 197      * ENOBUFS without any change, are acceptable.
 198      *
 199      * If the set of ports in 'wdp' has not changed, returns EAGAIN.  May
 200      * also return other positive errno values to indicate that something has
 201      * gone wrong. */
 202     int (*port_poll)(const struct wdp *wdp, char **devnamep);
 203
 204     /* Arranges for the poll loop to wake up when 'port_poll' will return a
 205      * value other than EAGAIN. */
 206     void (*port_poll_wait)(const struct wdp *wdp);
 207
 208     /* If 'wdp' contains a flow exactly equal to 'flow', returns that flow.
 209      * Otherwise returns null. */
 210     struct wdp_rule *(*flow_get)(const struct wdp *wdp,
 211                                  const flow_t *flow);
 212
 213     /* If 'wdp' contains one or more flows that match 'flow', returns the
 214      * highest-priority matching flow.  If there is more than one
 215      * highest-priority match, picks one of them in an arbitrary fashion.
 216      * Otherwise returns null.
 217      *
 218      * Ignores 'flow->priority' and 'flow->wildcards'. */
 219     struct wdp_rule *(*flow_match)(const struct wdp *wdp,
 220                                    const flow_t *flow);
 221
 222     /* Iterates through all of the flows in 'wdp''s flow table, passing each
 223      * flow that matches the specified search criteria to 'callback' along with
 224      * 'aux'.
 225      *
 226      * Flows are filtered out in two ways.  First, based on 'include':
 227      * Exact-match flows are excluded unless CLS_INC_EXACT is in 'include'.
 228      * Wildcarded flows are excluded unless CLS_INC_WILD is in 'include'.
 229      *
 230      * Flows are also filtered out based on 'target': on a field-by-field
 231      * basis, a flow is included if 'target' wildcards that field or if the
 232      * flow and 'target' both have the same exact value for the field.  A flow
 233      * is excluded if any field does not match based on these criteria.
 234      *
 235      * Ignores 'target->priority'.
 236      *
 237      * 'callback' is allowed to delete the rule that is passed as its argument.
 238      * It may modify any flow in 'wdp', e.g. changing their actions.
 239      * 'callback' must not delete flows from 'wdp' other than its argument
 240      * flow, nor may it insert new flows into 'wdp'. */
 241     void (*flow_for_each_match)(const struct wdp *wdp, const flow_t *flow,
 242                                 int include,
 243                                 wdp_flow_cb_func *callback, void *aux);
 244
 245     /* Retrieves flow statistics for 'rule', which must be in 'wdp''s flow
 246      * table, and stores them into '*stats'.  Returns 0 if successful,
 247      * otherwise a positive errno value. */
 248     int (*flow_get_stats)(const struct wdp *wdp,
 249                           const struct wdp_rule *rule,
 250                           struct wdp_flow_stats *stats);
 251
 252     /* Searches 'wdp''s flow table for a flow that overlaps 'flow'.  Two flow
 253      * entries overlap if they have the same priority and a single packet may
 254      * match both.
 255      *
 256      * This is intended for implementing OpenFlow's OFPFF_CHECK_OVERLAP
 257      * feature. */
 258     bool (*flow_overlaps)(const struct wdp *wdp, const flow_t *flow);
 259
 260     /* Adds or modifies a flow in 'wdp' as specified in 'put':
 261      *
 262      *   - If a rule with the same priority, wildcards, and values for fields
 263      *     that are not wildcarded specified in 'put->flow' does not already
 264      *     exist in 'wdp', then behavior depends on whether WDP_PUT_CREATE is
 265      *     specified in 'put->flags': if it is, the flow will be added,
 266      *     otherwise the operation will fail with ENOENT.
 267      *
 268      *     The new flow's actions and timeouts are set from the values in
 269      *     'put'.
 270      *
 271      *   - Otherwise, the flow specified in 'put->flow' does exist in 'wdp'.
 272      *     Behavior in this case depends on whether WDP_PUT_MODIFY is specified
 273      *     in 'put->flags': if it is, the flow will be updated, otherwise the
 274      *     operation will fail with EEXIST.  The exact updates depend on the
 275      *     remaining flags in 'put->flags':
 276      *
 277      *       . If WDP_PUT_COUNTERS is set, packet counters, byte counters, TCP
 278      *         flags, and IP TOS values are set to 0.
 279      *
 280      *       . If WDP_PUT_ACTIONS is set, the actions are replaced by the
 281      *         'put->n_actions' actions in 'put->actions'.
 282      *
 283      *       . If WDP_PUT_INSERTED is set, the flow's insertion time is updated
 284      *         to the current time.  (Timeouts are relative to a flow's
 285      *         insertion time so this affects their interpretation.)
 286      *
 287      *       . If WDP_PUT_TIMEOUTS is set, the flow's idle and hard timeouts
 288      *         are updated from 'put->idle_timeout' and 'put->hard_timeout',
 289      *         respectively.
 290      *
 291      * Returns 0 if successful, otherwise a positive errno value.  If
 292      * successful:
 293      *
 294      *   - If 'old_stats' is nonnull, then 'old_stats' is filled with the
 295      *     flow's stats as they existed just before the update, or it is zeroed
 296      *     if the flow is newly created.
 297      *
 298      *   - If 'rulep' is nonnull, then it is set to the newly created rule.
 299      *
 300      * Some error return values have specific meanings:
 301      *
 302      *   - ENOENT: Flow does not exist and WDP_PUT_CREATE not specified.
 303      *
 304      *   - EEXIST: Flow exists and WDP_PUT_MODIFY not specified.
 305      *
 306      *   - ENOBUFS: Flow table full.
 307      *
 308      *   - EINVAL: Flow table cannot accept flow of this form.
 309      */
 310     int (*flow_put)(struct wdp *wdp, const struct wdp_flow_put *put,
 311                     struct wdp_flow_stats *old_stats,
 312                     struct wdp_rule **rulep);
 313
 314     /* Deletes 'rule' from 'wdp'.  Returns 0 if successful, otherwise a
 315      * positive errno value.
 316      *
 317      * If successful and 'final_stats' is non-null, stores the flow's
 318      * statistics just before it is deleted into '*final_stats'. */
 319     int (*flow_delete)(struct wdp *wdp, struct wdp_rule *rule,
 320                        struct wdp_flow_stats *final_stats);
 321
 322     /* Deletes all flows from 'wdp' and clears all of its queues of received
 323      * packets. */
 324     int (*flow_flush)(struct wdp *wdp);
 325
 326     /* Performs the actions for 'rule' on the Ethernet frame specified in
 327      * 'packet'.  Pretends that the frame was originally received on the port
 328      * numbered 'in_port'.  Packets and bytes sent should be credited to
 329      * 'rule'. */
 330     int (*flow_inject)(struct wdp *wdp, struct wdp_rule *rule,
 331                        uint16_t in_port, const struct ofpbuf *packet);
 332
 333     /* Performs the 'n_actions' actions in 'actions' on the Ethernet frame
 334      * specified in 'packet'.  Pretends that the frame was originally received
 335      * on the port numbered 'in_port'. */
 336     int (*execute)(struct wdp *wdp, uint16_t in_port,
 337                    const union ofp_action actions[], int n_actions,
 338                    const struct ofpbuf *packet);
 339
 340     /* Retrieves 'wdp''s "listen mask" into '*listen_mask'.  Each bit set in
 341      * '*listen_mask' indicates the 'wdp' will receive messages of the
 342      * corresponding WDP_CHAN_* when it calls the recv member function. */
 343     int (*recv_get_mask)(const struct wdp *wdp, int *listen_mask);
 344
 345     /* Sets 'wdp''s "listen mask" to 'listen_mask'.  Each bit set in
 346      * 'listen_mask' indicates the 'wdp' will receive messages of the
 347      * corresponding WDP_CHAN_* type when it calls the recv member function. */
 348     int (*recv_set_mask)(struct wdp *wdp, int listen_mask);
 349
 350     /* Retrieves 'wdp''s sFlow sampling probability into '*probability'.
 351      * Return value is 0 or a positive errno value.  EOPNOTSUPP indicates that
 352      * the datapath does not support sFlow, as does a null pointer.
 353      *
 354      * '*probability' is expressed as the number of packets out of UINT_MAX to
 355      * sample, e.g. probability/UINT_MAX is the probability of sampling a given
 356      * packet. */
 357     int (*get_sflow_probability)(const struct wdp *wdp,
 358                                  uint32_t *probability);
 359
 360     /* Sets 'wdp''s sFlow sampling probability to 'probability'.  Return value
 361      * is 0 or a positive errno value.  EOPNOTSUPP indicates that the datapath
 362      * does not support sFlow, as does a null pointer.
 363      *
 364      * 'probability' is expressed as the number of packets out of UINT_MAX to
 365      * sample, e.g. probability/UINT_MAX is the probability of sampling a given
 366      * packet. */
 367     int (*set_sflow_probability)(struct wdp *wdp, uint32_t probability);
 368
 369     /* Attempts to receive a message from 'wdp'.  If successful, stores the
 370      * message into '*packet'.  Only messages of the types selected with the
 371      * recv_set_mask member function should be received.
 372      *
 373      * This function must not block.  If no message is ready to be received
 374      * when it is called, it should return EAGAIN without blocking. */
 375     int (*recv)(struct wdp *wdp, struct wdp_packet *packet);
 376
 377     /* Arranges for the poll loop to wake up when 'wdp' has a message queued
 378      * to be received with the recv member function. */
 379     void (*recv_wait)(struct wdp *wdp);
 380 };
 381
 382 extern const struct wdp_class wdp_linux_class;
 383 extern const struct wdp_class wdp_netdev_class;
 384
 385 #ifdef  __cplusplus
 386 }
 387 #endif
 388
 389 #endif /* wdp-provider.h */