[ovs-dev] [PATCH v2] doc: Added OVS Extensions document

Ashish Varma ashishvarma.ovs at gmail.com
Wed Oct 2 17:23:05 UTC 2019

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 at gmail.com>
Fixed the indentation in the commit message.
Converted the document from FAQ format to regular document format.
Changed the multiple references to Nicira extension to Open vSwitch extensions.
Changed the file name from ovs-nicira-extension.rst to ovs-extensions.rst.
Removed references from 'objects' to 'extensions'.
Refer to ofp-msgs.h instead of ofp-msgs.inc.
NXM description now refers to ovs-fields(7).
The C structures are now being referred to respective files instead of copying
it in the document.

 Documentation/automake.mk               |   1 +
 Documentation/index.rst                 |   3 +-
 Documentation/topics/index.rst          |   1 +
 Documentation/topics/ovs-extensions.rst | 147 ++++++++++++++++++++++++++++++++
 4 files changed, 151 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/topics/ovs-extensions.rst

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 2a3214a..5aa494a 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -64,6 +64,7 @@ DOC_SOURCE = \
 	Documentation/topics/porting.rst \
 	Documentation/topics/role-based-access-control.rst \
 	Documentation/topics/tracing.rst \
+	Documentation/topics/ovs-extensions.rst \
 	Documentation/topics/windows.rst \
 	Documentation/howto/index.rst \
 	Documentation/howto/docker.rst \
diff --git a/Documentation/index.rst b/Documentation/index.rst
index bace34d..4e4bb61 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -77,7 +77,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` |
diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst
index 057649d..6b514a5 100644
--- a/Documentation/topics/index.rst
+++ b/Documentation/topics/index.rst
@@ -51,6 +51,7 @@ OVS
+   ovs-extensions
diff --git a/Documentation/topics/ovs-extensions.rst b/Documentation/topics/ovs-extensions.rst
new file mode 100644
index 0000000..babc603
--- /dev/null
+++ b/Documentation/topics/ovs-extensions.rst
@@ -0,0 +1,147 @@
+      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
+OpenFlow since version 1.0 allows vendor extensions to be added in the
+protocol and OVS has used these extensions in the implementation. (Initially
+also known as 'Nicira extensions'. This is the reason we see the prefix
+'NX' in the different vendor extension messages.)
+These extensions have been used to add additional functionality for the
+desired features not present in the standard OpenFlow protocol.
+OVS vendor extension messages in OpenFlow and OVS
+1. **OFPT_VENDOR (In OpenFlow 1.0) or
+   OFPT_EXPERIMENTER (In OpenFlow 1.1+)**
+This is a vendor message type with value the value of OFPT_VENDOR
+or OFPT_EXPERIMENTER (refer to respective OpenFlow specifications)
+in the OpenFlow header 'type' field. After the header of this message,
+there is a vendor id field which identifies the vendor. This is followed
+by a subtype field which defines the vendor specific message types.
+The vendor ids are defined in: ovs/include/openflow/openflow-common.h
+To see a list of all the vendor message subtypes, we
+can refer to 'ovs/lib/ofp-msgs.h' file. We can see the instances
+of 'ofpraw' enum which has a comment containing the keyword NXT.
+For e.g. in the below mentioned line containing OFPRAW_NXT_FLOW_MOD:
+   /* NXT 1.0+ (13): struct nx_flow_mod, uint8_t[8][]. */
+   NXT          - stands for Nicira extension message.
+   nx_flow_mod  - data that follow the OpenFlow header.
+   uint8_t[8][] - multiple of 8 data.
+   13           - is the subtype for the Flow Mod message when it is sent as a
+                 Open vSwitch extension message.
+   OFPRAW_NXT_FLOW_MOD - is 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)
+2. **OFPST_VENDOR (In OpenFlow 1.0) or
+   OFPST_EXPERIMENTER (In OpenFlow 1.1 and 1.2) or
+   OFPMP_EXPERIMENTER (In OpenFlow 1.3+):**
+EXPERIMENTER multipart type in the message.
+Again if we refer to 'ovs/lib/ofp-msgs.h', we see the following lines:
+    /* NXST 1.0 (2): uint8_t[8][]. */
+    NXST         - stands for Nicira extension statistics or multipart message.
+    uint8_t[8][] - multiple of 8 data.
+    2            - is 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 - is 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
+NXM (Nicira Extended Match) is used to extend the flow
+match structure. 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 which are a series of TLV (type-length-value) entries or
+For a detailed description of NXM, please see the OVS fields documentation
+at: http://openvswitch.org/support/dist-docs/ovs-fields.7.txt
+Error Message Extension
+In the 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.
+Later, OpenFlow version 1.2+ added a 'OFPET_EXPERIMENTER' error type to
+generate 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

More information about the dev mailing list