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