OPENFLOW.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 ================================
  25 OpenFlow Support in Open vSwitch
  26 ================================
  27
  28 Open vSwitch support for OpenFlow 1.1 and beyond is a work in progress.  This
  29 file describes the work still to be done.
  30
  31 The Plan
  32 --------
  33
  34 OpenFlow version support is not a build-time option.  A single build of Open
  35 vSwitch must be able to handle all supported versions of OpenFlow.  Ideally,
  36 even at runtime it should be able to support all protocol versions at the same
  37 time on different OpenFlow bridges (and perhaps even on the same bridge).
  38
  39 At the same time, it would be a shame to litter the core of the OVS code with
  40 lots of ugly code concerned with the details of various OpenFlow protocol
  41 versions.
  42
  43 The primary approach to compatibility is to abstract most of the details of the
  44 differences from the core code, by adding a protocol layer that translates
  45 between OF1.x and a slightly higher-level abstract representation.  The core of
  46 this approach is the many ``struct ofputil_*`` structures in
  47 ``include/openvswitch/ofp-util.h``.
  48
  49 As a consequence of this approach, OVS cannot use OpenFlow protocol definitions
  50 that closely resemble those in the OpenFlow specification, because
  51 ``openflow.h`` in different versions of the OpenFlow specification defines the
  52 same identifier with different values.  Instead, ``openflow-common.h`` contains
  53 definitions that are common to all the specifications and separate protocol
  54 version-specific headers contain protocol-specific definitions renamed so as
  55 not to conflict, e.g. ``OFPAT10_ENQUEUE`` and ``OFPAT11_ENQUEUE`` for the
  56 OpenFlow 1.0 and 1.1 values for ``OFPAT_ENQUEUE``.  Generally, in cases of
  57 conflict, the protocol layer will define a more abstract ``OFPUTIL_*`` or
  58 struct ``ofputil_*``.
  59
  60 Here are the current approaches in a few tricky areas:
  61
  62 * Port numbering.
  63
  64   OpenFlow 1.0 has 16-bit port numbers and later OpenFlow versions have 32-bit
  65   port numbers.  For now, OVS support for later protocol versions requires all
  66   port numbers to fall into the 16-bit range, translating the reserved
  67   ``OFPP_*`` port numbers.
  68
  69 * Actions.
  70
  71   OpenFlow 1.0 and later versions have very different ideas of actions.  OVS
  72   reconciles by translating all the versions' actions (and instructions) to and
  73   from a common internal representation.
  74
  75 OpenFlow 1.1
  76 ------------
  77
  78 The list of remaining work items for OpenFlow 1.1 is below.  It is probably
  79 incomplete.
  80
  81 * Match and set double-tagged VLANs (QinQ).
  82
  83   This requires kernel work for reasonable performance.
  84
  85   (optional for OF1.1+)
  86
  87 * VLANs tagged with 88a8 Ethertype.
  88
  89   This requires kernel work for reasonable performance.
  90
  91   (required for OF1.1+)
  92
  93 OpenFlow 1.2
  94 ------------
  95
  96 OpenFlow 1.2 support requires OpenFlow 1.1 as a prerequisite. All the
  97 additional work specific to Openflow 1.2 are complete.  (This is based on the
  98 change log at the end of the OF1.2 spec.  I didn't compare the specs carefully
  99 yet.)
 100
 101 OpenFlow 1.3
 102 ------------
 103
 104 OpenFlow 1.3 support requires OpenFlow 1.2 as a prerequisite, plus the
 105 following additional work.  (This is based on the change log at the end of the
 106 OF1.3 spec, reusing most of the section titles directly.  I didn't compare the
 107 specs carefully yet.)
 108
 109 * Add support for multipart requests.
 110
 111   Currently we always report ``OFPBRC_MULTIPART_BUFFER_OVERFLOW``.
 112
 113   (optional for OF1.3+)
 114
 115 * IPv6 extension header handling support.
 116
 117   Fully implementing this requires kernel support.  This likely will take some
 118   careful and probably time-consuming design work.  The actual coding, once
 119   that is all done, is probably 2 or 3 days work.
 120
 121   (optional for OF1.3+)
 122
 123 * Per-flow meters.
 124
 125   OpenFlow protocol support is now implemented.  Support for the special
 126   ``OFPM_SLOWPATH`` and ``OFPM_CONTROLLER`` meters is missing.  Support for
 127   the software switch is under review.
 128
 129   (optional for OF1.3+)
 130
 131 * Auxiliary connections.
 132
 133   An implementation in generic code might be a week's worth of work.  The value
 134   of an implementation in generic code is questionable, though, since much of
 135   the benefit of axuiliary connections is supposed to be to take advantage of
 136   hardware support.  (We could make the kernel module somehow send packets
 137   across the auxiliary connections directly, for some kind of "hardware"
 138   support, if we judged it useful enough.)
 139
 140   (optional for OF1.3+)
 141
 142 * Provider Backbone Bridge tagging.
 143
 144   I don't plan to implement this (but we'd accept an implementation).
 145
 146   (optional for OF1.3+)
 147
 148 * On-demand flow counters.
 149
 150   I think this might be a real optimization in some cases for the software
 151   switch.
 152
 153   (optional for OF1.3+)
 154
 155 OpenFlow 1.4 & ONF Extensions for 1.3.X Pack1
 156 ---------------------------------------------
 157
 158 The following features are both defined as a set of ONF Extensions for 1.3 and
 159 integrated in 1.4.
 160
 161 When defined as an ONF Extension for 1.3, the feature is using the Experimenter
 162 mechanism with the ONF Experimenter ID.
 163
 164 When defined integrated in 1.4, the feature use the standard OpenFlow
 165 structures (for example defined in openflow-1.4.h).
 166
 167 The two definitions for each feature are independant and can exist in parallel
 168 in OVS.
 169
 170
 171 * Flow entry notifications
 172
 173   This seems to be modelled after OVS's NXST_FLOW_MONITOR.  (Simon Horman is
 174   working on this.)
 175
 176   (EXT-187)
 177   (optional for OF1.4+)
 178
 179 * Role Status
 180
 181   Already implemented as a 1.4 feature.
 182
 183   (EXT-191)
 184
 185   (required for OF1.4+)
 186
 187 * Flow entry eviction
 188
 189   OVS has flow eviction functionality.  ``table_mod OFPTC_EVICTION``,
 190   ``flow_mod 'importance'``, and ``table_desc ofp_table_mod_prop_eviction``
 191   need to be implemented.
 192
 193   (EXT-192-e)
 194
 195   (optional for OF1.4+)
 196
 197 * Vacancy events
 198
 199   (EXT-192-v)
 200
 201   (optional for OF1.4+)
 202
 203 * Bundle
 204
 205   Transactional modification.  OpenFlow 1.4 requires to support
 206   ``flow_mods`` and ``port_mods`` in a bundle if bundle is supported.
 207   (Not related to OVS's 'ofbundle' stuff.)
 208
 209   Implemented as an OpenFlow 1.4 feature.  Only flow_mods and port_mods are
 210   supported in a bundle.  If the bundle includes port mods, it may not specify
 211   the ``OFPBF_ATOMIC`` flag.  Nevertheless, port mods and flow mods in a bundle
 212   are always applied in order and consecutive flow mods between port mods are
 213   made available to lookups atomically.
 214
 215   (EXT-230)
 216
 217   (optional for OF1.4+)
 218
 219 * Table synchronisation
 220
 221   Probably not so useful to the software switch.
 222
 223   (EXT-232)
 224
 225   (optional for OF1.4+)
 226
 227 * Group and Meter change notifications
 228
 229   (EXT-235)
 230
 231   (optional for OF1.4+)
 232
 233 * Bad flow entry priority error
 234
 235   Probably not so useful to the software switch.
 236
 237   (EXT-236)
 238
 239   (optional for OF1.4+)
 240
 241 * Set async config error
 242
 243   (EXT-237)
 244
 245   (optional for OF1.4+)
 246
 247 * PBB UCA header field
 248
 249   See comment on Provider Backbone Bridge in section about OpenFlow 1.3.
 250
 251   (EXT-256)
 252
 253   (optional for OF1.4+)
 254
 255 * Multipart timeout error
 256
 257   (EXT-264)
 258
 259   (required for OF1.4+)
 260
 261 OpenFlow 1.4 only
 262 -----------------
 263
 264 Those features are those only available in OpenFlow 1.4, other OpenFlow 1.4
 265 features are listed in the previous section.
 266
 267 * More extensible wire protocol
 268
 269   Many on-wire structures got TLVs.
 270
 271   All required features are now supported.
 272   Remaining optional: table desc, table-status
 273
 274   (EXT-262)
 275
 276   (required for OF1.4+)
 277
 278 * More descriptive reasons for packet-in
 279
 280   Distinguish ``OFPR_APPLY_ACTION``, ``OFPR_ACTION_SET``, ``OFPR_GROUP``,
 281   ``OFPR_PACKET_OUT``.  ``NO_MATCH`` was renamed to ``OFPR_TABLE_MISS``.
 282   (OFPR_ACTION_SET and OFPR_GROUP are now supported)
 283
 284   (EXT-136)
 285
 286   (required for OF1.4+)
 287
 288 * Optical port properties
 289
 290   (EXT-154)
 291
 292   (optional for OF1.4+)
 293
 294 OpenFlow 1.5 & ONF Extensions for 1.3.X Pack2
 295 ---------------------------------------------
 296
 297 The following features are both defined as a set of ONF Extensions for 1.3 and
 298 integrated in 1.5. Note that this list is not definitive as those are not yet
 299 published.
 300
 301 When defined as an ONF Extension for 1.3, the feature is using the Experimenter
 302 mechanism with the ONF Experimenter ID.  When defined integrated in 1.5, the
 303 feature use the standard OpenFlow structures (for example defined in
 304 openflow-1.5.h).
 305
 306 The two definitions for each feature are independant and can exist in parallel
 307 in OVS.
 308
 309 * Time scheduled bundles
 310
 311   (EXT-340)
 312
 313   (optional for OF1.5+)
 314
 315 OpenFlow 1.5 only
 316 -----------------
 317
 318 Those features are those only available in OpenFlow 1.5, other OpenFlow 1.5
 319 features are listed in the previous section.  Note that this list is not
 320 definitive as OpenFlow 1.5 is not yet published.
 321
 322 * Egress Tables
 323
 324   (EXT-306)
 325
 326   (optional for OF1.5+)
 327
 328 * Packet Type aware pipeline
 329
 330   Prototype for OVS was done during specification.
 331
 332   (EXT-112)
 333
 334   (optional for OF1.5+)
 335
 336 * Extensible Flow Entry Statistics
 337
 338   (EXT-334)
 339
 340   (required for OF1.5+)
 341
 342 * Flow Entry Statistics Trigger
 343
 344   (EXT-335)
 345
 346   (optional for OF1.5+)
 347
 348 * Controller connection status
 349
 350   Prototype for OVS was done during specification.
 351
 352   (EXT-454)
 353
 354   (optional for OF1.5+)
 355
 356 * Meter action
 357
 358   (EXT-379)
 359
 360   (required for OF1.5+ if metering is supported)
 361
 362 * Enable setting all pipeline fields in packet-out
 363
 364   Prototype for OVS was done during specification.
 365
 366   (EXT-427)
 367
 368   (required for OF1.5+)
 369
 370 * Port properties for pipeline fields
 371
 372   Prototype for OVS was done during specification.
 373
 374   (EXT-388)
 375
 376   (optional for OF1.5+)
 377
 378 * Port property for recirculation
 379
 380   Prototype for OVS was done during specification.
 381
 382   (EXT-399)
 383
 384   (optional for OF1.5+)
 385
 386 General
 387 -------
 388
 389 * ovs-ofctl(8) often lists as Nicira extensions features that later OpenFlow
 390   versions support in standard ways.
 391
 392 How to contribute
 393 -----------------
 394
 395 If you plan to contribute code for a feature, please let everyone know on
 396 ovs-dev before you start work.  This will help avoid duplicating work.
 397
 398 Please consider the following:
 399
 400 * Testing.  Please test your code.
 401
 402 * Unit tests.  Please consider writing some.  The tests directory has many
 403   examples that you can use as a starting point.
 404
 405 * ovs-ofctl.  If you add a feature that is useful for some ovs-ofctl command
 406   then you should add support for it there.
 407
 408 * Documentation.  If you add a user-visible feature, then you should document
 409   it in the appropriate manpage and mention it in NEWS as well.
 410
 411 * Coding style (see the `coding style guide <CodingStyle.rst>`__ file at the top
 412   of the source tree).
 413
 414 * The `patch submission guidelines <CONTRIBUTING.rst>`__.  I recommend using
 415   "git send-email", which automatically follows a lot of those guidelines.