include/openflow/nicira-ext.h

   1 /*
   2  * Copyright (c) 2008, 2009, 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 OPENFLOW_NICIRA_EXT_H
  18 #define OPENFLOW_NICIRA_EXT_H 1
  19
  20 #include "openflow/openflow.h"
  21
  22 /* The following vendor extensions, proposed by Nicira Networks, are not yet
  23  * standardized, so they are not included in openflow.h.  Some of them may be
  24  * suitable for standardization; others we never expect to standardize. */
  25
  26 #define NX_VENDOR_ID 0x00002320
  27 \f
  28 /* Nicira vendor-specific error messages extension.
  29  *
  30  * OpenFlow 1.0 has a set of predefined error types (OFPET_*) and codes (which
  31  * are specific to each type).  It does not have any provision for
  32  * vendor-specific error codes, and it does not even provide "generic" error
  33  * codes that can apply to problems not anticipated by the OpenFlow
  34  * specification authors.
  35  *
  36  * This extension attempts to address the problem by adding a generic "error
  37  * vendor extension".  The extension works as follows: use NXET_VENDOR as type
  38  * and NXVC_VENDOR_CODE as code, followed by struct nx_vendor_error with
  39  * vendor-specific details, followed by at least 64 bytes of the failed
  40  * request.
  41  *
  42  * It would be better to have type-specific vendor extension, e.g. so that
  43  * OFPET_BAD_ACTION could be used with vendor-specific code values.  But
  44  * OFPET_BAD_ACTION and most other standardized types already specify that
  45  * their 'data' values are (the start of) the OpenFlow message being replied
  46  * to, so there is no room to insert a vendor ID.
  47  *
  48  * Currently this extension is only implemented by Open vSwitch, but it seems
  49  * like a reasonable candidate for future standardization.
  50  */
  51
  52 /* This is a random number to avoid accidental collision with any other
  53  * vendor's extension. */
  54 #define NXET_VENDOR 0xb0c2
  55
  56 /* ofp_error msg 'code' values for NXET_VENDOR. */
  57 enum nx_vendor_code {
  58     NXVC_VENDOR_ERROR           /* 'data' contains struct nx_vendor_error. */
  59 };
  60
  61 /* 'data' for 'type' == NXET_VENDOR, 'code' == NXVC_VENDOR_ERROR. */
  62 struct nx_vendor_error {
  63     uint32_t vendor;            /* Vendor ID as in struct ofp_vendor_header. */
  64     uint16_t type;              /* Vendor-defined type. */
  65     uint16_t code;              /* Vendor-defined subtype. */
  66     /* Followed by at least the first 64 bytes of the failed request. */
  67 };
  68 \f
  69 /* Specific Nicira extension error numbers.
  70  *
  71  * These are the "code" values used in nx_vendor_error.  So far, the "type"
  72  * values in nx_vendor_error are the same as those in ofp_error_msg.  That is,
  73  * at Nicira so far we've only needed additional vendor-specific 'code' values,
  74  * so we're using the existing 'type' values to avoid having to invent new ones
  75  * that duplicate the current ones' meanings. */
  76
  77 /* Additional "code" values for OFPET_FLOW_MOD_FAILED. */
  78 enum {
  79     /* Generic hardware error. */
  80     NXFMFC_HARDWARE = 0x100,
  81
  82     /* A nonexistent table ID was specified in the "command" field of struct
  83      * ofp_flow_mod, when the nxt_flow_mod_table_id extension is enabled. */
  84     NXFMFC_BAD_TABLE_ID
  85 };
  86 \f
  87 /* Nicira vendor requests and replies. */
  88
  89 enum nicira_type {
  90     /* Switch status request.  The request body is an ASCII string that
  91      * specifies a prefix of the key names to include in the output; if it is
  92      * the null string, then all key-value pairs are included. */
  93     NXT_STATUS_REQUEST,
  94
  95     /* Switch status reply.  The reply body is an ASCII string of key-value
  96      * pairs in the form "key=value\n". */
  97     NXT_STATUS_REPLY,
  98
  99     /* No longer used. */
 100     NXT_ACT_SET_CONFIG__OBSOLETE,
 101     NXT_ACT_GET_CONFIG__OBSOLETE,
 102     NXT_COMMAND_REQUEST__OBSOLETE,
 103     NXT_COMMAND_REPLY__OBSOLETE,
 104     NXT_FLOW_END_CONFIG__OBSOLETE,
 105     NXT_FLOW_END__OBSOLETE,
 106     NXT_MGMT__OBSOLETE,
 107
 108     /* Use the high 32 bits of the cookie field as the tunnel ID in the flow
 109      * match. */
 110     NXT_TUN_ID_FROM_COOKIE,
 111
 112     /* Controller role support.  The request body is struct nx_role_request.
 113      * The reply echos the request. */
 114     NXT_ROLE_REQUEST,
 115     NXT_ROLE_REPLY,
 116
 117     /* Use the upper 8 bits of the 'command' member in struct ofp_flow_mod to
 118      * designate the table to which a flow is to be added?  See the big comment
 119      * on struct nxt_flow_mod_table_id for more information. */
 120     NXT_FLOW_MOD_TABLE_ID
 121 };
 122
 123 struct nicira_header {
 124     struct ofp_header header;
 125     uint32_t vendor;            /* NX_VENDOR_ID. */
 126     uint32_t subtype;           /* One of NXT_* above. */
 127 };
 128 OFP_ASSERT(sizeof(struct nicira_header) == 16);
 129
 130 struct nxt_tun_id_cookie {
 131     struct ofp_header header;
 132     uint32_t vendor;            /* NX_VENDOR_ID. */
 133     uint32_t subtype;           /* NXT_TUN_ID_FROM_COOKIE */
 134     uint8_t set;                /* Nonzero to enable, zero to disable. */
 135     uint8_t pad[7];
 136 };
 137 OFP_ASSERT(sizeof(struct nxt_tun_id_cookie) == 24);
 138
 139 /* This command enables or disables an Open vSwitch extension that allows a
 140  * controller to specify the OpenFlow table to which a flow should be added,
 141  * instead of having the switch decide which table is most appropriate as
 142  * required by OpenFlow 1.0.  By default, the extension is disabled.
 143  *
 144  * When this feature is enabled, Open vSwitch treats struct ofp_flow_mod's
 145  * 16-bit 'command' member as two separate fields.  The upper 8 bits are used
 146  * as the table ID, the lower 8 bits specify the command as usual.  A table ID
 147  * of 0xff is treated like a wildcarded table ID.
 148  *
 149  * The specific treatment of the table ID depends on the type of flow mod:
 150  *
 151  *    - OFPFC_ADD: Given a specific table ID, the flow is always placed in that
 152  *      table.  If an identical flow already exists in that table only, then it
 153  *      is replaced.  If the flow cannot be placed in the specified table,
 154  *      either because the table is full or because the table cannot support
 155  *      flows of the given type, the switch replies with an
 156  *      OFPFMFC_ALL_TABLES_FULL error.  (A controller can distinguish these
 157  *      cases by comparing the current and maximum number of entries reported
 158  *      in ofp_table_stats.)
 159  *
 160  *      If the table ID is wildcarded, the switch picks an appropriate table
 161  *      itself.  If an identical flow or flows already exist in some flow
 162  *      table, then one of them is replaced.  The choice of table might depend
 163  *      on the flows that are already in the switch; for example, if one table
 164  *      fills up then the switch might fall back to another one.
 165  *
 166  *    - OFPFC_MODIFY, OFPFC_DELETE: Given a specific table ID, only flows
 167  *      within that table are matched and modified or deleted.  If the table ID
 168  *      is wildcarded, flows within any table may be matched and modified or
 169  *      deleted.
 170  *
 171  *    - OFPFC_MODIFY_STRICT, OFPFC_DELETE_STRICT: Given a specific table ID,
 172  *      only a flow within that table may be matched and modified or deleted.
 173  *      If the table ID is wildcarded and exactly one flow within any table
 174  *      matches, then it is modified or deleted; if flows in more than one
 175  *      table match, then none is modified or deleted.
 176  */
 177 struct nxt_flow_mod_table_id {
 178     struct ofp_header header;
 179     uint32_t vendor;            /* NX_VENDOR_ID. */
 180     uint32_t subtype;           /* NXT_FLOW_MOD_TABLE_ID. */
 181     uint8_t set;                /* Nonzero to enable, zero to disable. */
 182     uint8_t pad[7];
 183 };
 184 OFP_ASSERT(sizeof(struct nxt_flow_mod_table_id) == 24);
 185
 186 /* Configures the "role" of the sending controller.  The default role is:
 187  *
 188  *    - Other (NX_ROLE_OTHER), which allows the controller access to all
 189  *      OpenFlow features.
 190  *
 191  * The other possible roles are a related pair:
 192  *
 193  *    - Master (NX_ROLE_MASTER) is equivalent to Other, except that there may
 194  *      be at most one Master controller at a time: when a controller
 195  *      configures itself as Master, any existing Master is demoted to the
 196  *      Slave role.
 197  *
 198  *    - Slave (NX_ROLE_SLAVE) allows the controller read-only access to
 199  *      OpenFlow features.  In particular attempts to modify the flow table
 200  *      will be rejected with an OFPBRC_EPERM error.
 201  *
 202  *      Slave controllers also do not receive asynchronous messages
 203  *      (OFPT_PACKET_IN, OFPT_FLOW_REMOVED, OFPT_PORT_STATUS).
 204  */
 205 struct nx_role_request {
 206     struct nicira_header nxh;
 207     uint32_t role;              /* One of NX_ROLE_*. */
 208 };
 209
 210 enum nx_role {
 211     NX_ROLE_OTHER,              /* Default role, full access. */
 212     NX_ROLE_MASTER,             /* Full access, at most one. */
 213     NX_ROLE_SLAVE               /* Read-only access. */
 214 };
 215 \f
 216 /* Nicira vendor flow actions. */
 217
 218 enum nx_action_subtype {
 219     NXAST_SNAT__OBSOLETE,           /* No longer used. */
 220
 221     /* Searches the flow table again, using a flow that is slightly modified
 222      * from the original lookup:
 223      *
 224      *    - The 'in_port' member of struct nx_action_resubmit is used as the
 225      *      flow's in_port.
 226      *
 227      *    - If NXAST_RESUBMIT is preceded by actions that affect the flow
 228      *      (e.g. OFPAT_SET_VLAN_VID), then the flow is updated with the new
 229      *      values.
 230      *
 231      * Following the lookup, the original in_port is restored.
 232      *
 233      * If the modified flow matched in the flow table, then the corresponding
 234      * actions are executed.  Afterward, actions following NXAST_RESUBMIT in
 235      * the original set of actions, if any, are executed; any changes made to
 236      * the packet (e.g. changes to VLAN) by secondary actions persist when
 237      * those actions are executed, although the original in_port is restored.
 238      *
 239      * NXAST_RESUBMIT may be used any number of times within a set of actions.
 240      *
 241      * NXAST_RESUBMIT may nest to an implementation-defined depth.  Beyond this
 242      * implementation-defined depth, further NXAST_RESUBMIT actions are simply
 243      * ignored.  (Open vSwitch 1.0.1 and earlier did not support recursion.)
 244      */
 245     NXAST_RESUBMIT,
 246
 247     /* Set encapsulating tunnel ID. */
 248     NXAST_SET_TUNNEL,
 249
 250     /* Stops processing further actions, if the packet being processed is an
 251      * Ethernet+IPv4 ARP packet for which the source Ethernet address inside
 252      * the ARP packet differs from the source Ethernet address in the Ethernet
 253      * header.
 254      *
 255      * This is useful because OpenFlow does not provide a way to match on the
 256      * Ethernet addresses inside ARP packets, so there is no other way to drop
 257      * spoofed ARPs other than sending every ARP packet to a controller. */
 258     NXAST_DROP_SPOOFED_ARP,
 259
 260     /* Set the queue that should be used when packets are output.  This
 261      * is similar to the OpenFlow OFPAT_ENQUEUE action, but does not
 262      * take the output port as an argument.  This allows the queue
 263      * to be defined before the port is known. */
 264     NXAST_SET_QUEUE,
 265
 266     /* Restore the queue to the value it was before any NXAST_SET_QUEUE
 267      * actions were used. */
 268     NXAST_POP_QUEUE
 269 };
 270
 271 /* Action structure for NXAST_RESUBMIT. */
 272 struct nx_action_resubmit {
 273     uint16_t type;                  /* OFPAT_VENDOR. */
 274     uint16_t len;                   /* Length is 16. */
 275     uint32_t vendor;                /* NX_VENDOR_ID. */
 276     uint16_t subtype;               /* NXAST_RESUBMIT. */
 277     uint16_t in_port;               /* New in_port for checking flow table. */
 278     uint8_t pad[4];
 279 };
 280 OFP_ASSERT(sizeof(struct nx_action_resubmit) == 16);
 281
 282 /* Action structure for NXAST_SET_TUNNEL. */
 283 struct nx_action_set_tunnel {
 284     uint16_t type;                  /* OFPAT_VENDOR. */
 285     uint16_t len;                   /* Length is 16. */
 286     uint32_t vendor;                /* NX_VENDOR_ID. */
 287     uint16_t subtype;               /* NXAST_SET_TUNNEL. */
 288     uint8_t pad[2];
 289     uint32_t tun_id;                /* Tunnel ID. */
 290 };
 291 OFP_ASSERT(sizeof(struct nx_action_set_tunnel) == 16);
 292
 293 /* Action structure for NXAST_SET_QUEUE. */
 294 struct nx_action_set_queue {
 295     uint16_t type;                  /* OFPAT_VENDOR. */
 296     uint16_t len;                   /* Length is 16. */
 297     uint32_t vendor;                /* NX_VENDOR_ID. */
 298     uint16_t subtype;               /* NXAST_SET_QUEUE. */
 299     uint8_t pad[2];
 300     uint32_t queue_id;              /* Where to enqueue packets. */
 301 };
 302 OFP_ASSERT(sizeof(struct nx_action_set_queue) == 16);
 303
 304 /* Header for Nicira-defined actions. */
 305 struct nx_action_header {
 306     uint16_t type;                  /* OFPAT_VENDOR. */
 307     uint16_t len;                   /* Length is 16. */
 308     uint32_t vendor;                /* NX_VENDOR_ID. */
 309     uint16_t subtype;               /* NXAST_*. */
 310     uint8_t pad[6];
 311 };
 312 OFP_ASSERT(sizeof(struct nx_action_header) == 16);
 313
 314 /* Wildcard for tunnel ID. */
 315 #define NXFW_TUN_ID  (1 << 25)
 316
 317 #define NXFW_ALL NXFW_TUN_ID
 318 #define OVSFW_ALL (OFPFW_ALL | NXFW_ALL)
 319
 320 #endif /* openflow/nicira-ext.h */