doc: Added OVS Extensions document

OVS supports OVS Extensions as various vendor messages or as vendor
types in stats or multipart messages. Added a document to describe the
extensions as currently supported by OVS.

Signed-off-by: Ashish Varma <ashishvarma.ovs@gmail.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>

4 files changed, 172 insertions, 2 deletions

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index e1384851d..5f7c3e07b 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -53,6 +53,7 @@ DOC_SOURCE = \
 	Documentation/topics/language-bindings.rst \
 	Documentation/topics/networking-namespaces.rst \
 	Documentation/topics/openflow.rst \
+	Documentation/topics/ovs-extensions.rst \
 	Documentation/topics/ovsdb-replication.rst \
 	Documentation/topics/porting.rst \
 	Documentation/topics/tracing.rst \
diff --git a/Documentation/index.rst b/Documentation/index.rst
index f18f8df1c..1f1da2916 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -71,7 +71,8 @@ Deeper Dive
 - **Architecture** :doc:`topics/design` |
   :doc:`topics/openflow` |
   :doc:`topics/integration` |
-  :doc:`topics/porting`
+  :doc:`topics/porting` |
+  :doc:`topics/ovs-extensions`
 
 - **DPDK** :doc:`howto/dpdk` |
   :doc:`topics/dpdk/vhost-user`
diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst
index fcb741637..34c4b10e0 100644
--- a/Documentation/topics/index.rst
+++ b/Documentation/topics/index.rst
@@ -51,4 +51,4 @@ OVS
    testing
    tracing
    idl-compound-indexes
-
+   ovs-extensions
diff --git a/Documentation/topics/ovs-extensions.rst b/Documentation/topics/ovs-extensions.rst
new file mode 100644
index 000000000..50eacce3e
--- /dev/null
+++ b/Documentation/topics/ovs-extensions.rst
@@ -0,0 +1,168 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+=======================
+Open vSwitch Extensions
+=======================
+
+Introduction
+------------
+
+OpenFlow allows vendor extensions to the protocol.  OVS implements
+many of its own extensions.  These days, we typically refer to these
+as "Open vSwitch extensions" to OpenFlow.  You might also see them
+called "Nicira extensions" after the company that initiated the Open
+vSwitch project.  These extensions have been used to add additional
+functionality for the desired features not present in the standard
+OpenFlow protocol.
+
+OpenFlow 1.0 refers to extensions as "vendor extensions", whereas
+OpenFlow 1.1 and later call them "experimenter extensions".  These are
+different names for the same concept and we use them interchangeably.
+
+OVS vendor extension messages in OpenFlow and OVS
+-------------------------------------------------
+
+Vendor/experimenter request and replies
++++++++++++++++++++++++++++++++++++++++
+
+OpenFlow supports vendor extensions for basic requests and replies.
+In OpenFlow 1.0, such messages carry ``OFPT_VENDOR`` in the ``struct
+ofp_header`` message type field, and in later versions
+``OFPT_EXPERIMENTER``.  After the header of this message, there is a
+vendor id field which identifies the vendor.  Everything after the
+vendor ID is vendor specific, but it would typically include a subtype
+field to identify a particular kind of vendor-specific message.
+Vendor ids are defined in ``ovs/include/openflow/openflow-common.h``.
+
+To see a list of all the vendor message subtypes that OVS understands,
+we can refer to ``ovs/lib/ofp-msgs.h``.  We can see the instances of
+``enum ofpraw`` which has a comment containing the keyword ``NXT``,
+e.g.  ``OFPRAW_NXT_FLOW_MOD`` below:
+
+::
+
+   /* NXT 1.0+ (13): struct nx_flow_mod, uint8_t[8][]. */
+   OFPRAW_NXT_FLOW_MOD,
+
+which may be interpreted as follows:
+
+``NXT``
+    stands for Nicira extension message.
+``nx_flow_mod``
+    data that follow the OpenFlow header.
+``uint8_t[8][]``
+    multiple of 8 data.
+``13``
+    the subtype for the Flow Mod message when it is sent as a Open
+    vSwitch extension message
+``OFPRAW_NXT_FLOW_MOD``
+    the Open vSwitch Flow Mod extension message.
+
+For reference, the vendor message header is defined as
+``struct ofp_vendor_header`` in ``ovs/lib/ofp-msgs.c``.
+
+The general structure of a message with a vendor message type is:
+
+ofp_header(msg_type=VENDOR/EXPERIMENTER) / vendor id / vendor subtype /
+vendor defined additional data
+(e.g. nx_flow_mod structure for OFPRAW_NXT_FLOW_MOD message)
+
+Multipart vendor requests and replies
++++++++++++++++++++++++++++++++++++++
+
+OpenFlow supports "statistics" or "multipart" messages that consist of
+a sequence of shorter messages with associated content.  In OpenFlow
+1.0 through 1.2, these are ``OFPT_STATS_REQUEST`` requests and
+``OFPT_STATS_REPLY`` replies, and in OpenFlow 1.3 and later, they are
+``OFPT_MULTIPART_REQUEST``and ``OFPT_MULTIPART_REPLY``.
+
+A multipart message carries its own embedded type that denotes the
+kind of multipart data.  Multipart vendor requests and replies use
+type ``OFPT_VENDOR`` in OpenFlow 1.0, ``OFPST_EXPERIMENTER`` in
+OpenFlow 1.1 and 1.2, and ``OFPMP_EXPERIMENTER`` in OpenFlow 1.3 and
+later.
+
+Again if we refer to ``ovs/lib/ofp-msgs.h``, we see the following lines:
+
+::
+
+    /* NXST 1.0 (2): uint8_t[8][]. */
+    OFPRAW_NXST_FLOW_MONITOR_REQUEST,
+
+``NXST``
+    stands for Nicira extension statistics or multipart message.
+``uint8_t[8][]``
+    multiple of 8 data.
+``2``
+    the subtype for the Flow Monitor Request message when it is sent
+    as a Flow Monitor Request message with extension vendor id.
+``OFPRAW_NXST_FLOW_MONITOR_REQUEST``
+    the OpenFlow Flow Monitor extension message.
+
+For reference, the vendor extension stats message header is defined as
+``struct ofp11_vendor_stats_msg`` in ``ovs/lib/ofp-msgs.c``.
+
+The general structure of a multipart/stats message with vendor type is:
+
+ofp_header(msg_type=STATS/MULTIPART) / stats_msg(type=VENDOR/EXPERIMENTER) /
+ vendor-id / subtype / vendor defined additional data
+
+Extended Match
+--------------
+
+OpenFlow 1.0 uses a fixed size flow match structure (struct
+ofp_match) to define the fields to match in a packet.  This is
+limiting and not extensible.  To make the match structure extensible,
+OVS added as an extension ``nx_match`` structure, called NXM, as a
+series of TLV (type-length-value) entries or ``nxm_entry``.  OpenFlow
+1.2 standardized NXM as OXM, with extensions of its own.  OVS supports
+standard and extension OXM and NXM TLVs.
+
+For a detailed description of NXM and OXM, please see the OVS fields
+documentation at
+https://www.openvswitch.org/support/dist-docs/ovs-fields.7.pdf.
+
+Error Message Extension
+-----------------------
+
+In OpenFlow version 1.0 and 1.1, there is no provision to generate
+vendor specific error codes and does not even provide ``generic``
+error codes that can apply to problems not anticipated by the OpenFlow
+specification authors.  OVS added a generic "error vendor extension"
+which uses ``NXET_VENDOR`` as type and ``NXVC_VENDOR_ERROR`` as code,
+followed by ``struct nx_vendor_error`` with vendor-specific details,
+followed by at least 64 bytes of the failed request.
+
+OpenFlow version 1.2+ added a ``OFPET_EXPERIMENTER`` error type to
+support vendor specific error codes.
+
+Source files related to Open vSwitch extensions
+-----------------------------------------------
+
+::
+
+   ovs/include/openflow/nicira-ext.h
+   ovs/lib/ofp-msgs.inc
+   ovs/include/openvswitch/ofp-msgs.h
+   ovs/lib/ofp-msgs.c