doc: Convert datapath-windows/CodingStyle to rST

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

3 files changed, 184 insertions, 155 deletions

diff --git a/datapath-windows/CodingStyle b/datapath-windows/CodingStyle
deleted file mode 100644
index 40873e8c4..000000000
--- a/datapath-windows/CodingStyle
+++ /dev/null
@@ -1,154 +0,0 @@
-       Open vSwitch Windows Datapath Coding Style
-       ==========================================
-
-The coding style described in the Open vSwitch distribution gives the
-flexiblity for each platform to use its own coding style for the kernel
-datapath.  This file describes the specific coding style used in most
-of the C files in the Windows kernel datapath of the Open vSwitch distribution.
-
-Most of the coding conventions applicable for the Open vSwitch distribution are
-applicable to the Windows kernel datapath as well.  There are some exceptions
-and new guidlines owing to the commonly followed practices in Windows
-kernel/driver code.  They are noted as follows:
-
-
-BASICS
-
-  Limit lines to 79 characters.  Many times, this is not possible due to long
-names of functions and it is fine to go beyond the characters limit.  One
-common example is when calling into NDIS functions.
-
-
-TYPES
-  Use data types defined by Windows for most of the code.  This is a common
-practice in Windows driver code, and it makes integrating with the data
-structures and functions defined by Windows easier.  Example: DWORD and
-BOOLEAN.
-
-  Use caution in portions of the code that interface with the OVS userspace.
-OVS userspace does not use Windows specific data types, and when copying data
-back and forth between kernel and userspace, care should be exercised.
-
-
-NAMING
-
-  It is common practice to use camel casing for naming variables, functions
-and files in Windows.  For types, especially structures, unions and enums,
-using all upper case letters with words seprated by '_' is common. These
-practices can be used for OVS Windows datapath.  However, use the following
-guidelines:
-
-  Use lower case to begin the name of a variable.
-
-  Do not use '_' to begin the name of the variable. '_' is to be used to begin
-  the parameters of a pre-processor macro.
-
-  Use upper case to begin the name of a function, enum, file name etc.
-
-  Static functions whose scope is limited to the file they are defined in can
-  be prefixed with '_'. This is not mandatory though.
-
-  For types, use all upper case for all letters with words separated by '_'. If
-  camel casing is preferred, use  upper case for the first letter.
-
-  It is a common practice to define a pointer type by prefixing the letter
-'P' to a data type.  The same practice can be followed here as well.
-
-  Example:
-
-static __inline BOOLEAN
-OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx,
-                     POVS_FLOW_KEY flowKey)
-{
-    POVS_VPORT_ENTRY tunnelVport = NULL;
-
-    if (!flowKey->ipKey.nwFrag &&
-        flowKey->ipKey.nwProto == IPPROTO_UDP &&
-        flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) {
-        tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN);
-        ovsActionStats.rxVxlan++;
-    } else {
-        return FALSE;
-    }
-
-    if (tunnelVport) {
-        ASSERT(ovsFwdCtx->tunnelRxNic == NULL);
-        ovsFwdCtx->tunnelRxNic = tunnelVport;
-        return TRUE;
-    }
-
-    return FALSE;
-}
-
-  For declaring variables of pointer type, use of the pointer data type
-prefixed with 'P' is preferred over using '*'. This is not mandatory though,
-and is only prescribed since it is a common practice in Windows.
-
-  Example, #1 is preferred over #2 though #2 is also equally correct:
-  1. PNET_BUFFER_LIST curNbl;
-  2. NET_BUFFER_LIST *curNbl;
-
-COMMENTS
-
-  Comments should be written as full sentences that start with a
-capital letter and end with a period.  Putting two spaces between sentances is
-not necessary.
-
-  // can be used for comments as long as the comment is a single line comment.
-For block comments, use /* */ comments
-
-
-FUNCTIONS
-
-  Put the return type, function name, and the braces that surround the
-function's code on separate lines, all starting in column 0.
-
-  Before each function definition, write a comment that describes the
-function's purpose, including each parameter, the return value, and
-side effects.  References to argument names should be given in
-single-quotes, e.g. 'arg'.  The comment should not include the
-function name, nor need it follow any formal structure.  The comment
-does not need to describe how a function does its work, unless this
-information is needed to use the function correctly (this is often
-better done with comments *inside* the function).
-
-  Mention any side effects that the function has that are not obvious based on
-the name of the function or based on the workflow it is called from.
-
-  In the interest of keeping comments describing functions similar in
-structure, use the following template.
-
-/*
- *----------------------------------------------------------------------------
- * Any description of the function, arguments, return types, assumptions and
- * side effects.
- *----------------------------------------------------------------------------
- */
-
-SOURCE FILES
-
-  Each source file should state its license in a comment at the very
-top, followed by a comment explaining the purpose of the code that is
-in that file.  The comment should explain how the code in the file
-relates to code in other files.  The goal is to allow a programmer to
-quickly figure out where a given module fits into the larger system.
-
-  The first non-comment line in a .c source file should be:
-
-    #include <precomp.h>
-
-#include directives should appear in the following order:
-
-    1. #include <precomp.h>
-
-    2. The module's own headers, if any.  Including this before any
-       other header (besides <precomp.h>) ensures that the module's
-       header file is self-contained (see HEADER FILES) below.
-
-    3. Standard C library headers and other system headers, preferably
-       in alphabetical order.  (Occasionally one encounters a set of
-       system headers that must be included in a particular order, in
-       which case that order must take precedence.)
-
-    4. Open vSwitch headers, in alphabetical order.  Use "", not <>,
-       to specify Open vSwitch header names.
diff --git a/datapath-windows/CodingStyle.rst b/datapath-windows/CodingStyle.rst
new file mode 100644
index 000000000..1de748842
--- /dev/null
+++ b/datapath-windows/CodingStyle.rst
@@ -0,0 +1,183 @@
+..
+      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 Windows Datapath Coding Style
+==========================================
+
+The coding style described in the Open vSwitch distribution gives the
+flexiblity for each platform to use its own coding style for the kernel
+datapath.  This file describes the specific coding style used in most of the C
+files in the Windows kernel datapath of the Open vSwitch distribution.
+
+Most of the coding conventions applicable for the Open vSwitch distribution are
+applicable to the Windows kernel datapath as well.  There are some exceptions
+and new guidlines owing to the commonly followed practices in Windows
+kernel/driver code.  They are noted as follows:
+
+Basics
+------
+
+- Limit lines to 79 characters.
+
+  Many times, this is not possible due to long names of functions and it is
+  fine to go beyond the characters limit.  One common example is when calling
+  into NDIS functions.
+
+Types
+-----
+
+Use data types defined by Windows for most of the code.  This is a common
+practice in Windows driver code, and it makes integrating with the data
+structures and functions defined by Windows easier.  Example: ``DWORD`` and
+``BOOLEAN``.
+
+Use caution in portions of the code that interface with the OVS userspace.  OVS
+userspace does not use Windows specific data types, and when copying data back
+and forth between kernel and userspace, care should be exercised.
+
+Naming
+------
+
+It is common practice to use camel casing for naming variables, functions and
+files in Windows.  For types, especially structures, unions and enums, using
+all upper case letters with words seprated by '_' is common. These practices
+can be used for OVS Windows datapath.  However, use the following guidelines:
+
+- Use lower case to begin the name of a variable.
+
+- Do not use '_' to begin the name of the variable. '_' is to be used to begin
+  the parameters of a pre-processor macro.
+
+- Use upper case to begin the name of a function, enum, file name etc.
+
+- Static functions whose scope is limited to the file they are defined in can
+  be prefixed with '_'. This is not mandatory though.
+
+- For types, use all upper case for all letters with words separated by '_'. If
+  camel casing is preferred, use  upper case for the first letter.
+
+- It is a common practice to define a pointer type by prefixing the letter 'P'
+  to a data type.  The same practice can be followed here as well.
+
+For example::
+
+    static __inline BOOLEAN
+    OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx,
+                         POVS_FLOW_KEY flowKey)
+    {
+        POVS_VPORT_ENTRY tunnelVport = NULL;
+
+        if (!flowKey->ipKey.nwFrag &&
+            flowKey->ipKey.nwProto == IPPROTO_UDP &&
+            flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) {
+            tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN);
+            ovsActionStats.rxVxlan++;
+        } else {
+            return FALSE;
+        }
+
+        if (tunnelVport) {
+            ASSERT(ovsFwdCtx->tunnelRxNic == NULL);
+            ovsFwdCtx->tunnelRxNic = tunnelVport;
+            return TRUE;
+        }
+
+        return FALSE;
+    }
+
+For declaring variables of pointer type, use of the pointer data type prefixed
+with 'P' is preferred over using '*'. This is not mandatory though, and is only
+prescribed since it is a common practice in Windows.
+
+Example, #1 is preferred over #2 though #2 is also equally correct:
+
+1. ``PNET_BUFFER_LIST curNbl;``
+2. ``NET_BUFFER_LIST *curNbl;``
+
+Comments
+--------
+
+Comments should be written as full sentences that start with a capital letter
+and end with a period.  Putting two spaces between sentances is not necessary.
+
+``//`` can be used for comments as long as the comment is a single line
+comment.  For block comments, use ``/* */`` comments
+
+Functions
+---------
+
+Put the return type, function name, and the braces that surround the function's
+code on separate lines, all starting in column 0.
+
+Before each function definition, write a comment that describes the function's
+purpose, including each parameter, the return value, and side effects.
+References to argument names should be given in single-quotes, e.g. 'arg'.  The
+comment should not include the function name, nor need it follow any formal
+structure.  The comment does not need to describe how a function does its work,
+unless this information is needed to use the function correctly (this is often
+better done with comments *inside* the function).
+
+Mention any side effects that the function has that are not obvious based on
+the name of the function or based on the workflow it is called from.
+
+In the interest of keeping comments describing functions similar in structure,
+use the following template.
+
+::
+
+    /*
+     *----------------------------------------------------------------------------
+     * Any description of the function, arguments, return types, assumptions and
+     * side effects.
+     *----------------------------------------------------------------------------
+     */
+
+Source Files
+------------
+
+Each source file should state its license in a comment at the very top,
+followed by a comment explaining the purpose of the code that is in that file.
+The comment should explain how the code in the file relates to code in other
+files.  The goal is to allow a programmer to quickly figure out where a given
+module fits into the larger system.
+
+The first non-comment line in a .c source file should be::
+
+    #include <precomp.h>
+
+``#include`` directives should appear in the following order:
+
+1. ``#include <precomp.h>``
+
+2. The module's own headers, if any.  Including this before any other header
+   (besides ``<precomp.h>``) ensures that the module's header file is
+   self-contained (see *Header Files*) below.
+
+3. Standard C library headers and other system headers, preferably in
+   alphabetical order.  (Occasionally one encounters a set of system headers
+   that must be included in a particular order, in which case that order must
+   take precedence.)
+
+4. Open vSwitch headers, in alphabetical order.  Use ``""``, not ``<>``, to
+   specify Open vSwitch header names.
diff --git a/datapath-windows/automake.mk b/datapath-windows/automake.mk
index e741a484a..096575b14 100644
--- a/datapath-windows/automake.mk
+++ b/datapath-windows/automake.mk
@@ -1,5 +1,5 @@
 EXTRA_DIST += \
-	datapath-windows/CodingStyle \
+	datapath-windows/CodingStyle.rst \
 	datapath-windows/DESIGN \
 	datapath-windows/Package/package.VcxProj \
 	datapath-windows/Package/package.VcxProj.user \