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