From patchwork Sun Oct 30 13:30:05 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 688943 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3t6JQB0DY2z9t1T for ; Mon, 31 Oct 2016 00:34:57 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=cfvj24s+; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 03BDA105E2; Sun, 30 Oct 2016 06:34:41 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx3v3.cudamail.com (mx3.cudamail.com [64.34.241.5]) by archives.nicira.com (Postfix) with ESMTPS id AEA54105E2 for ; Sun, 30 Oct 2016 06:34:39 -0700 (PDT) Received: from bar6.cudamail.com (localhost [127.0.0.1]) by mx3v3.cudamail.com (Postfix) with ESMTPS id 47074163D2F for ; Sun, 30 Oct 2016 07:34:39 -0600 (MDT) X-ASG-Debug-ID: 1477834477-0b32372044228db0001-byXFYA Received: from mx3-pf3.cudamail.com ([192.168.14.3]) by bar6.cudamail.com with ESMTP id u6cZkxRQ8VVphdd8 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sun, 30 Oct 2016 07:34:37 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.3 Received: from unknown (HELO cadetblue.maple.relay.mailchannels.net) (23.83.214.28) by mx3-pf3.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 30 Oct 2016 13:34:37 -0000 Received-SPF: none (mx3-pf3.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.214.28 X-Barracuda-RBL-IP: 23.83.214.28 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 463491264A6 for ; Sun, 30 Oct 2016 13:34:35 +0000 (UTC) Received: from one.mxroute.com (ip-10-220-3-24.us-west-2.compute.internal [10.220.3.24]) by relay.mailchannels.net (Postfix) with ESMTPA id AC078125CEA for ; Sun, 30 Oct 2016 13:34:33 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([TEMPUNAVAIL]. [10.16.27.41]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sun, 30 Oct 2016 13:34:35 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1477834475037:1411274585 X-MC-Ingress-Time: 1477834475037 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=xxwZHt8QxHQNhdi1q11aMN3TNFm5M79m6VK3roQSLag=; b=cfvj24s+70X+qNZO9TFzTDwbUu qEbOpbwbqyBc1RGQiaUlLLrlZc1B6xj9lroB5HIVFlMNhesBMEqmc3nw7toTFYgVsHUjkRqNoDJeC khNoTWthZ7DPsV2unZYuVdW3ypDcuDUxgxY9jToZIyGIrmL+EbbQVQrTYXW/ykv00apz1/ajG7jb4 HH2r8Va73f9ooXRPS5h03p2bEk/dm4k8rOFoMVbOnALC7+zZm/0hLWxTn1WGO4gmATxDUUruX1OhV fRq8J0EKGRweX9Ap58yhAzh9QvXflfURUMr8k6Z/6rjaR+TNNRzDgBzTmaLZTJn8ESy3gWcTni8kA v10Eu+7Q==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-V3-1029004414 X-CudaMail-DTE: 103016 X-CudaMail-Originating-IP: 23.83.214.28 Date: Sun, 30 Oct 2016 13:30:05 +0000 X-ASG-Orig-Subj: [##CM-V3-1029004414##][PATCH 19/23] doc: Convert datapath-windows/CodingStyle to rST Message-Id: <1477834209-11414-20-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1477834209-11414-1-git-send-email-stephen@that.guru> References: <1477834209-11414-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 23.83.214.28, Ugly c=0.237282 p=-0.2 Source Normal X-MessageSniffer-Rules: 0-0-0-30976-c X-Barracuda-Connect: UNKNOWN[192.168.14.3] X-Barracuda-Start-Time: 1477834477 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Barracuda-BRTS-Status: 1 X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-Spam-Score: 1.10 X-Barracuda-Spam-Status: No, SCORE=1.10 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.34168 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 19/23] doc: Convert datapath-windows/CodingStyle to rST X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Signed-off-by: Stephen Finucane --- datapath-windows/CodingStyle | 154 -------------------------------- datapath-windows/CodingStyle.rst | 183 +++++++++++++++++++++++++++++++++++++++ datapath-windows/automake.mk | 2 +- 3 files changed, 184 insertions(+), 155 deletions(-) delete mode 100644 datapath-windows/CodingStyle create mode 100644 datapath-windows/CodingStyle.rst diff --git a/datapath-windows/CodingStyle b/datapath-windows/CodingStyle deleted file mode 100644 index 40873e8..0000000 --- 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 - -#include directives should appear in the following order: - - 1. #include - - 2. The module's own headers, if any. Including this before any - other header (besides ) 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 0000000..1de7488 --- /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 + +``#include`` directives should appear in the following order: + +1. ``#include `` + +2. The module's own headers, if any. Including this before any other header + (besides ````) 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 e741a48..096575b 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 \