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 "tag.h"
  25 #include "util.h"
  26 #include "wdp.h"
  27
  28 #ifdef  __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 static inline struct wdp_rule *
  33 wdp_rule_cast(const struct cls_rule *cls_rule)
  34 {
  35     return cls_rule ? CONTAINER_OF(cls_rule, struct wdp_rule, cr) : NULL;
  36 }
  37
  38 /* Open vSwitch datapath interface.
  39  *
  40  * This structure should be treated as opaque by wdp implementations. */
  41 struct wdp {
  42     const struct wdp_class *wdp_class;
  43     char *base_name;
  44     char *full_name;
  45     uint8_t netflow_engine_type;
  46     uint8_t netflow_engine_id;
  47 };
  48
  49 void wdp_init(struct wdp *, const struct wdp_class *, const char *name,
  50               uint8_t netflow_engine_type, uint8_t netflow_engine_id);
  51 void wdp_uninit(struct wdp *wdp, bool close);
  52
  53 static inline void wdp_assert_class(const struct wdp *wdp,
  54                                     const struct wdp_class *wdp_class)
  55 {
  56     assert(wdp->wdp_class == wdp_class);
  57 }
  58
  59 /* Datapath interface class structure, to be defined by each implementation of
  60  * a datapath interface.
  61  *
  62  * These functions return 0 if successful or a positive errno value on failure,
  63  * except where otherwise noted.
  64  *
  65  * Most of these functions are expected to execute synchronously, that is, to
  66  * block as necessary to obtain a result.  Thus, these functions may return
  67  * EAGAIN (or EWOULDBLOCK or EINPROGRESS) only where the function descriptions
  68  * explicitly say those errors are a possibility.  We may relax this
  69  * requirement in the future if and when we encounter performance problems. */
  70 struct wdp_class {
  71     /* Type of wdp in this class, e.g. "system", "netdev", etc.
  72      *
  73      * One of the providers should supply a "system" type, since this is
  74      * the type assumed if no type is specified when opening a wdp. */
  75     const char *type;
  76
  77     /* Performs periodic work needed by wdps of this class, if any is
  78      * necessary. */
  79     void (*run)(void);
  80
  81     /* Arranges for poll_block() to wake up if the "run" member function needs
  82      * to be called. */
  83     void (*wait)(void);
  84
  85     /* Enumerates the names of all known created datapaths for 'wdp_class',
  86      * if possible, into 'all_wdps'.  The caller has already initialized
  87      * 'all_wdps' and other wdp classes might already have added names to it.
  88      *
  89      * This is used by the vswitch at startup, so that it can delete any
  90      * datapaths that are not configured.
  91      *
  92      * Some kinds of datapaths might not be practically enumerable, in which
  93      * case this function may be a null pointer. */
  94     int (*enumerate)(const struct wdp_class *wdp_class,
  95                      struct svec *all_wdps);
  96
  97     /* Attempts to open an existing wdp of class 'wdp_class' called 'name',
  98      * if 'create' is false, or to open an existing wdp or create a new one,
  99      * if 'create' is true.
 100      *
 101      * If successful, stores a pointer to the new wdp in '*wdpp'.  On
 102      * failure there are no requirements on what is stored in '*wdpp'. */
 103     int (*open)(const struct wdp_class *wdp_class, const char *name,
 104                 bool create, struct wdp **wdpp);
 105
 106     /* Closes 'wdp' and frees associated memory. */
 107     void (*close)(struct wdp *wdp);
 108
 109     /* Enumerates all names that may be used to open 'wdp' into 'all_names'.
 110      * The Linux datapath, for example, supports opening a datapath both by
 111      * number, e.g. "wdp0", and by the name of the datapath's local port.  For
 112      * some datapaths, this might be an infinite set (e.g. in a file name,
 113      * slashes may be duplicated any number of times), in which case only the
 114      * names most likely to be used should be enumerated.
 115      *
 116      * The caller has already initialized 'all_names' and might already have
 117      * added some names to it.  This function should not disturb any existing
 118      * names in 'all_names'.
 119      *
 120      * If a datapath class does not support multiple names for a datapath, this
 121      * function may be a null pointer.
 122      *
 123      * This is used by the vswitch at startup, */
 124     int (*get_all_names)(const struct wdp *wdp, struct svec *all_names);
 125
 126     /* Attempts to destroy the wdp underlying 'wdp'.
 127      *
 128      * If successful, 'wdp' will not be used again except as an argument for
 129      * the 'close' member function. */
 130     int (*destroy)(struct wdp *wdp);
 131
 132     /* Creates a "struct ofp_switch_features" for 'wdp' and stores it in
 133      * '*featuresp'.  The caller is responsible for freeing '*featuresp' (with
 134      * ofpbuf_delete()) when it is no longer needed. */
 135     int (*get_features)(const struct wdp *wdp, struct ofpbuf **featuresp);
 136
 137     /* Retrieves statistics for 'wdp' into 'stats'. */
 138     int (*get_stats)(const struct wdp *wdp, struct wdp_stats *stats);
 139
 140     /* Appends to 'stats' one or more 'struct ofp_table_stats' structures that
 141      * represent the tables maintained by 'wdp'.  Returns 0 if successful,
 142      * otherwise an OpenFlow error code constructed with ofp_mkerr(). */
 143     int (*get_table_stats)(const struct wdp *wdp, struct ofpbuf *stats);
 144
 145     /* Retrieves 'wdp''s current treatment of IP fragments into '*drop_frags':
 146      * true indicates that fragments are dropped, false indicates that
 147      * fragments are treated in the same way as other IP packets (except that
 148      * the L4 header cannot be read). */
 149     int (*get_drop_frags)(const struct wdp *wdp, bool *drop_frags);
 150
 151     /* Changes 'wdp''s treatment of IP fragments to 'drop_frags', whose meaning
 152      * is the same as for the get_drop_frags member function.  EOPNOTSUPP
 153      * indicates that the datapath does not support changing the fragment
 154      * dropping policy, as does a null pointer. */
 155     int (*set_drop_frags)(struct wdp *wdp, bool drop_frags);
 156
 157     /* Creates a new port in 'wdp' connected to network device 'devname'.  If
 158      * 'internal' is true, creates the port as an internal port.  If
 159      * successful, sets '*port_nop' to the new port's port number.
 160      *
 161      * Possible error return values include:
 162      *
 163      *   - ENODEV: No device named 'devname' exists (if 'internal' is false).
 164      *
 165      *   - EEXIST: A device named 'devname' already exists (if 'internal' is
 166      *     true).
 167      *
 168      *   - EINVAL: Device 'devname' is not supported as part of a datapath
 169      *     (e.g. it is not an Ethernet device), or 'devname' is too long for a
 170      *     network device name (if 'internal' is true)
 171      *
 172      *   - EFBIG: The datapath already has as many ports as it can support.
 173      *
 174      *   - EOPNOTSUPP: 'wdp' has a fixed set of ports.
 175      *
 176      * A null pointer is equivalent to returning EOPNOTSUPP.
 177      */
 178     int (*port_add)(struct wdp *wdp, const char *devname,
 179                     bool internal, uint16_t *port_nop);
 180
 181     /* Removes port numbered 'port_no' from 'wdp'.
 182      *
 183      * Possible error return values include:
 184      *
 185      *   - EINVAL: 'port_no' is outside the valid range, or this particular
 186      *     port is not removable (e.g. it is the local port).
 187      *
 188      *   - ENOENT: 'wdp' currently has no port numbered 'port_no'.
 189      *
 190      *   - EOPNOTSUPP: 'wdp' has a fixed set of ports.
 191      *
 192      * A null pointer is equivalent to returning EOPNOTSUPP.
 193      */
 194     int (*port_del)(struct wdp *wdp, uint16_t port_no);
 195
 196     /* Looks up a port in 'wdp' by name or number.  On success, returns 0 and
 197      * initializes '*portp'.  On failure, returns a positive errno value.
 198      *
 199      * The caller takes ownership of everything in '*portp' and will eventually
 200      * free it with, e.g., wdp_port_free(). */
 201     int (*port_query_by_number)(const struct wdp *wdp, uint16_t port_no,
 202                                 struct wdp_port *portp);
 203     int (*port_query_by_name)(const struct wdp *wdp, const char *devname,
 204                               struct wdp_port *portp);
 205
 206     /* Obtains a list of all the ports in 'wdp'.  Sets '*portsp' to point to an
 207      * array of port structures and '*n_portsp' to the number of ports in the
 208      * array.
 209      *
 210      * The caller takes ownership of '*portsp' and all of the ports in it and
 211      * is responsible for freeing the ports and the array with, e.g.,
 212      * wdp_port_array_free(). */
 213     int (*port_list)(const struct wdp *wdp, struct wdp_port **portsp,
 214                      size_t *n_portsp);
 215
 216     /* Updates the configuration for the port number 'port_no' within 'wdp' to
 217      * 'config', which is a set of OpenFlow OFPPC_* constants in host byte
 218      * order.  Returns 0 if successful, otherwise an OpenFlow error code
 219      * constructed with ofp_mkerr().  */
 220     int (*port_set_config)(struct wdp *wdp, uint16_t port_no,
 221                            uint32_t config);
 222
 223     /* Polls for changes in the set of ports in 'wdp' since the last call to
 224      * this function or, if this is the first call, since this wdp was opened.
 225      * For each change, calls 'cb' passing 'aux' and:
 226      *
 227      *   - For a port that has been added, OFPPR_ADD as 'reason' and the new
 228      *     port's "struct ofp_phy_port" as 'opp'.
 229      *
 230      *   - For a port that has been removed, OFPPR_DELETE as 'reason' and the
 231      *     deleted port's former "struct ofp_phy_port" as 'opp'.
 232      *
 233      *   - For a port whose configuration has changed, OFPPR_MODIFY as 'reason'
 234      *     and the modified port's new "struct ofp_phy_port" as 'opp'.
 235      *
 236      * If 'wdp' has a fixed set of ports, this function must still be present
 237      * (to report changes to port configurations) but it will never report
 238      * OFPPR_ADD or OFPPR_DELETE as a reason.
 239      *
 240      * 'opp' is in *host* byte order.
 241      *
 242      * Normally returns 0.  May also return a positive errno value to indicate
 243      * that something has gone wrong.
 244      */
 245     int (*port_poll)(struct wdp *wdp,
 246                      void (*cb)(const struct ofp_phy_port *opp,
 247                                 uint8_t reason, void *aux),
 248                      void *aux);
 249
 250     /* Arranges for the poll loop to wake up when 'port_poll' will call its
 251      * callback. */
 252     int (*port_poll_wait)(const struct wdp *wdp);
 253
 254     /* If 'wdp' contains exactly one flow exactly equal to 'flow' in one of the
 255      * tables in the bit-mask in 'include', returns that flow.  Otherwise (if
 256      * there is no match or more than one match), returns null.
 257      *
 258      * A flow in table 'table_id' is a candidate for matching if 'include & (1u
 259      * << table_id)' is nonzero. */
 260     struct wdp_rule *(*flow_get)(const struct wdp *wdp,
 261                                  const flow_t *flow, unsigned int include);
 262
 263     /* If 'wdp' contains one or more flows that match 'flow', returns the
 264      * highest-priority matching flow.  If there is more than one
 265      * highest-priority match, picks one of them in an arbitrary fashion.
 266      * Otherwise returns null.
 267      *
 268      * Ignores 'flow->priority' and 'flow->wildcards'. */
 269     struct wdp_rule *(*flow_match)(const struct wdp *wdp,
 270                                    const flow_t *flow);
 271
 272     /* Iterates through all of the flows in 'wdp''s flow table, passing each
 273      * flow that matches the specified search criteria to 'callback' along with
 274      * 'aux'.
 275      *
 276      * If 'callback' returns nonzero, then this must stop the iteration and the
 277      * return value must be propagated to the caller.  Otherwise, this function
 278      * must return zero after all matching flows (if any) have been visited.
 279      *
 280      * Flows are filtered out in two ways.  First, based on the bit-mask in
 281      * 'include': wdp_rule 'wr' is included only if 'include & (1u <<
 282      * wr->ofp_table_id)' is nonzero.
 283      *
 284      * Flows are also filtered out based on 'target': on a field-by-field
 285      * basis, a flow is included if 'target' wildcards that field or if the
 286      * flow and 'target' both have the same exact value for the field.  A flow
 287      * is excluded if any field does not match based on these criteria.
 288      *
 289      * Ignores 'target->priority'.
 290      *
 291      * 'callback' is allowed to delete the rule that is passed as its argument.
 292      * It may modify any flow in 'wdp', e.g. changing their actions.
 293      * 'callback' must not delete flows from 'wdp' other than its argument
 294      * flow, nor may it insert new flows into 'wdp'. */
 295     int (*flow_for_each_match)(const struct wdp *wdp, const flow_t *flow,
 296                                unsigned int include,
 297                                wdp_flow_cb_func *callback, void *aux);
 298
 299     /* Retrieves flow statistics for 'rule', which must be in 'wdp''s flow
 300      * table, and stores them into '*stats'.  Returns 0 if successful,
 301      * otherwise a positive errno value. */
 302     int (*flow_get_stats)(const struct wdp *wdp,
 303                           const struct wdp_rule *rule,
 304                           struct wdp_flow_stats *stats);
 305
 306     /* Searches 'wdp''s flow table for a flow that overlaps 'flow'.  Two flow
 307      * entries overlap if they have the same priority and a single packet may
 308      * match both.
 309      *
 310      * This is intended for implementing OpenFlow's OFPFF_CHECK_OVERLAP
 311      * feature. */
 312     bool (*flow_overlaps)(const struct wdp *wdp, const flow_t *flow);
 313
 314     /* Adds or modifies a flow in 'wdp' as specified in 'put'.
 315      *
 316      * As the first step, this function determines the table of 'wdp' in which
 317      * the flow should be inserted or modified:
 318      *
 319      *   - If 'put->ofp_table_id' is 0xff, then 'wdp' chooses the flow table
 320      *     itself.  It may do so based on, for example, the flow's wildcards
 321      *     and how full the various tables in 'wdp' already are.
 322      *
 323      *     If a flow identical to 'put->flow' already exists in one of 'wdp''s
 324      *     tables, this does not necessarily mean that that table must be
 325      *     chosen.  That is, 'wdp' may allow duplicate flows, as long as they
 326      *     are in different tables.  Conversely, 'wdp' may refuse to add
 327      *     duplicate flows.  (Whether to allow duplicate flows ordinarily
 328      *     depends on the structure of the hardware.)
 329      *
 330      *   - If 'put->ofp_table_id' is not 0xff, then that table must be used.
 331      *     If 'wdp' cannot support 'put->flow' in the specified table, or if no
 332      *     such table exists, then the function must return an error.  Reasons
 333      *     that 'wdp' might not support a flow in a given table include: the
 334      *     table is full, the flow has wildcards not supported by that table or
 335      *     otherwise is not in a form supported by the table, or (if 'wdp' does
 336      *     not support duplicate flows) putting the flow in that table would
 337      *     cause a duplicate flow.
 338      *
 339      * Afterward, it performs the action:
 340      *
 341      *   - If a rule with the same priority, wildcards, values specified in
 342      *     'put->flow' (for fields that are not wildcarded) does not already
 343      *     exist in 'wdp' in the selected table, then behavior depends on
 344      *     whether WDP_PUT_CREATE is specified in 'put->flags': if it is, the
 345      *     flow will be added, otherwise the operation will fail with ENOENT.
 346      *
 347      *     The new flow's actions and timeouts are set from the values in
 348      *     'put'.
 349      *
 350      *   - Otherwise, the flow specified in 'put->flow' does exist in 'wdp' in
 351      *     the selected table.  Behavior in this case depends on whether
 352      *     WDP_PUT_MODIFY is specified in 'put->flags': if it is, the flow will
 353      *     be updated, otherwise the operation will fail with EEXIST.  The
 354      *     exact updates depend on the remaining flags in 'put->flags':
 355      *
 356      *       . If WDP_PUT_COUNTERS is set, packet counters, byte counters, TCP
 357      *         flags, and IP TOS values are set to 0.
 358      *
 359      *       . If WDP_PUT_ACTIONS is set, the actions are replaced by the
 360      *         'put->n_actions' actions in 'put->actions'.
 361      *
 362      *       . If WDP_PUT_INSERTED is set, the flow's insertion time is updated
 363      *         to the current time.  (Timeouts are relative to a flow's
 364      *         insertion time so this affects their interpretation.)
 365      *
 366      *       . If WDP_PUT_TIMEOUTS is set, the flow's idle and hard timeouts
 367      *         are updated from 'put->idle_timeout' and 'put->hard_timeout',
 368      *         respectively.
 369      *
 370      * Returns 0 if successful, otherwise a positive errno value.  If
 371      * successful:
 372      *
 373      *   - If 'old_stats' is nonnull, then 'old_stats' is filled with the
 374      *     flow's stats as they existed just before the update, or it is zeroed
 375      *     if the flow is newly created.
 376      *
 377      *   - If 'rulep' is nonnull, then it is set to the newly created rule.
 378      *
 379      * Some error return values have specific meanings:
 380      *
 381      *   - ENOENT: Flow does not exist and WDP_PUT_CREATE not specified.
 382      *
 383      *   - EEXIST: Flow exists and WDP_PUT_MODIFY not specified.
 384      *
 385      *   - ENOBUFS: Flow table full.
 386      *
 387      *   - EINVAL: Flow table cannot accept flow of this form.
 388      */
 389     int (*flow_put)(struct wdp *wdp, const struct wdp_flow_put *put,
 390                     struct wdp_flow_stats *old_stats,
 391                     struct wdp_rule **rulep);
 392
 393     /* Deletes 'rule' from 'wdp'.  Returns 0 if successful, otherwise a
 394      * positive errno value.
 395      *
 396      * If successful and 'final_stats' is non-null, stores the flow's
 397      * statistics just before it is deleted into '*final_stats'. */
 398     int (*flow_delete)(struct wdp *wdp, struct wdp_rule *rule,
 399                        struct wdp_flow_stats *final_stats);
 400
 401     /* Deletes all flows from 'wdp' and clears all of its queues of received
 402      * packets. */
 403     int (*flow_flush)(struct wdp *wdp);
 404
 405     /* Performs the actions for 'rule' on the Ethernet frame specified in
 406      * 'packet'.  Pretends that the frame was originally received on the port
 407      * numbered 'in_port'.  Packets and bytes sent should be credited to
 408      * 'rule'. */
 409     int (*flow_inject)(struct wdp *wdp, struct wdp_rule *rule,
 410                        uint16_t in_port, const struct ofpbuf *packet);
 411
 412     /* Performs the 'n_actions' actions in 'actions' on the Ethernet frame
 413      * specified in 'packet'.  Pretends that the frame was originally received
 414      * on the port numbered 'in_port'. */
 415     int (*execute)(struct wdp *wdp, uint16_t in_port,
 416                    const union ofp_action actions[], int n_actions,
 417                    const struct ofpbuf *packet);
 418
 419     /* Retrieves 'wdp''s "listen mask" into '*listen_mask'.  Each bit set in
 420      * '*listen_mask' indicates the 'wdp' will receive messages of the
 421      * corresponding WDP_CHAN_* when it calls the recv member function. */
 422     int (*recv_get_mask)(const struct wdp *wdp, int *listen_mask);
 423
 424     /* Sets 'wdp''s "listen mask" to 'listen_mask'.  Each bit set in
 425      * 'listen_mask' indicates the 'wdp' will receive messages of the
 426      * corresponding WDP_CHAN_* type when it calls the recv member function. */
 427     int (*recv_set_mask)(struct wdp *wdp, int listen_mask);
 428
 429     /* Retrieves 'wdp''s sFlow sampling probability into '*probability'.
 430      * Return value is 0 or a positive errno value.  EOPNOTSUPP indicates that
 431      * the datapath does not support sFlow, as does a null pointer.
 432      *
 433      * '*probability' is expressed as the number of packets out of UINT_MAX to
 434      * sample, e.g. probability/UINT_MAX is the probability of sampling a given
 435      * packet. */
 436     int (*get_sflow_probability)(const struct wdp *wdp,
 437                                  uint32_t *probability);
 438
 439     /* Sets 'wdp''s sFlow sampling probability to 'probability'.  Return value
 440      * is 0 or a positive errno value.  EOPNOTSUPP indicates that the datapath
 441      * does not support sFlow, as does a null pointer.
 442      *
 443      * 'probability' is expressed as the number of packets out of UINT_MAX to
 444      * sample, e.g. probability/UINT_MAX is the probability of sampling a given
 445      * packet. */
 446     int (*set_sflow_probability)(struct wdp *wdp, uint32_t probability);
 447
 448     /* Attempts to receive a message from 'wdp'.  If successful, stores the
 449      * message into '*packet'.  Only messages of the types selected with the
 450      * recv_set_mask member function should be received.
 451      *
 452      * This function must not block.  If no message is ready to be received
 453      * when it is called, it should return EAGAIN without blocking. */
 454     int (*recv)(struct wdp *wdp, struct wdp_packet *packet);
 455
 456     /* Discards any queued messages that otherwise would be received by the
 457      * 'recv' member function for 'wdp'. */
 458     int (*recv_purge)(struct wdp *wdp);
 459
 460     /* Arranges for the poll loop to wake up when 'wdp' has a message queued
 461      * to be received with the recv member function. */
 462     void (*recv_wait)(struct wdp *wdp);
 463 \f
 464     /* ovs-vswitchd interface.
 465      *
 466      * This needs to be redesigned, because it only makes sense for wdp-xflow.
 467      * Other implementations cannot practically use these interfaces and should
 468      * just set these pointers to NULL.
 469      *
 470      * The ofhooks are currently the key to implementing the OFPP_NORMAL
 471      * feature of ovs-vswitchd.  This design is not adequate for the long
 472      * term; it needs to be redone. */
 473
 474     /* Sets the ofhooks for 'wdp' to 'ofhooks' with the accompanying 'aux'
 475      * value.
 476      *
 477      * This needs to be redesigned, because it only makes sense for wdp-xflow.
 478      * Other implementations cannot practically use this interface and should
 479      * just set this to NULL. */
 480     int (*set_ofhooks)(struct wdp *wdp,
 481                        const struct ofhooks *ofhooks, void *aux);
 482
 483     /* Tell 'wdp' to revalidate all the flows that match 'tag'.
 484      *
 485      * This needs to be redesigned, because it only makes sense for wdp-xflow.
 486      * Other implementations cannot practically use this interface and should
 487      * just set this to NULL. */
 488     void (*revalidate)(struct wdp *wdp, tag_type tag);
 489
 490     /* Tell 'wdp' to revalidate every flow.  (This is not the same as calling
 491      * 'revalidate' with all-1-bits for 'tag' because it also revalidates flows
 492      * that do not have any tag at all.)
 493      *
 494      * This needs to be redesigned, because it only makes sense for wdp-xflow.
 495      * Other implementations cannot practically use this interface and should
 496      * just set this to NULL. */
 497     void (*revalidate_all)(struct wdp *wdp);
 498 };
 499
 500 extern const struct wdp_class wdp_linux_class;
 501 extern const struct wdp_class wdp_netdev_class;
 502
 503 #ifdef  __cplusplus
 504 }
 505 #endif
 506
 507 #endif /* wdp-provider.h */