/usr/share/doc/openvswitch-doc/html/internals/contributing/coding-style-windows.html is in openvswitch-doc 2.9.0-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Open vSwitch Windows Datapath Coding Style — Open vSwitch 2.9.0 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '2.9.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Open vSwitch Documentation Style" href="documentation-style.html" />
<link rel="prev" title="Open vSwitch Coding Style" href="coding-style.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="open-vswitch-windows-datapath-coding-style">
<h1>Open vSwitch Windows Datapath Coding Style<a class="headerlink" href="#open-vswitch-windows-datapath-coding-style" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference internal" href="coding-style.html"><span class="doc">coding style</span></a> guide 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.</p>
<p>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:</p>
<div class="section" id="basics">
<h2>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">Limit lines to 79 characters.</p>
<p>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.</p>
</li>
</ul>
</div>
<div class="section" id="types">
<h2>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h2>
<p>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: <code class="docutils literal"><span class="pre">DWORD</span></code> and
<code class="docutils literal"><span class="pre">BOOLEAN</span></code>.</p>
<p>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.</p>
</div>
<div class="section" id="naming">
<h2>Naming<a class="headerlink" href="#naming" title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<ul class="simple">
<li>Use lower case to begin the name of a variable.</li>
<li>Do not use ‘_’ to begin the name of the variable. ‘_’ is to be used to begin
the parameters of a pre-processor macro.</li>
<li>Use upper case to begin the name of a function, enum, file name etc.</li>
<li>Static functions whose scope is limited to the file they are defined in can
be prefixed with ‘_’. This is not mandatory though.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>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;
}
</pre></div>
</div>
<p>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.</p>
<p>Example, #1 is preferred over #2 though #2 is also equally correct:</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">PNET_BUFFER_LIST</span> <span class="pre">curNbl;</span></code></li>
<li><code class="docutils literal"><span class="pre">NET_BUFFER_LIST</span> <span class="pre">*curNbl;</span></code></li>
</ol>
</div>
<div class="section" id="comments">
<h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p><code class="docutils literal"><span class="pre">//</span></code> can be used for comments as long as the comment is a single line
comment. For block comments, use <code class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></code> comments</p>
</div>
<div class="section" id="functions">
<h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>
<p>Put the return type, function name, and the braces that surround the function’s
code on separate lines, all starting in column 0.</p>
<p>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 <em>inside</em> the function).</p>
<p>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.</p>
<p>In the interest of keeping comments describing functions similar in structure,
use the following template.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">/*</span>
<span class="o">*----------------------------------------------------------------------------</span>
<span class="o">*</span> <span class="n">Any</span> <span class="n">description</span> <span class="n">of</span> <span class="n">the</span> <span class="n">function</span><span class="p">,</span> <span class="n">arguments</span><span class="p">,</span> <span class="k">return</span> <span class="n">types</span><span class="p">,</span> <span class="n">assumptions</span> <span class="ow">and</span>
<span class="o">*</span> <span class="n">side</span> <span class="n">effects</span><span class="o">.</span>
<span class="o">*----------------------------------------------------------------------------</span>
<span class="o">*/</span>
</pre></div>
</div>
</div>
<div class="section" id="source-files">
<h2>Source Files<a class="headerlink" href="#source-files" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>The first non-comment line in a .c source file should be:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#include <precomp.h></span>
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">#include</span></code> directives should appear in the following order:</p>
<ol class="arabic simple">
<li><code class="docutils literal"><span class="pre">#include</span> <span class="pre"><precomp.h></span></code></li>
<li>The module’s own headers, if any. Including this before any other header
(besides <code class="docutils literal"><span class="pre"><precomp.h></span></code>) ensures that the module’s header file is
self-contained (see <em>Header Files</em>) below.</li>
<li>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.)</li>
<li>Open vSwitch headers, in alphabetical order. Use <code class="docutils literal"><span class="pre">""</span></code>, not <code class="docutils literal"><span class="pre"><></span></code>, to
specify Open vSwitch header names.</li>
</ol>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../contents.html">
<img class="logo" src="../../_static/logo.png" alt="Logo"/>
</a></p>
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Open vSwitch Windows Datapath Coding Style</a><ul>
<li><a class="reference internal" href="#basics">Basics</a></li>
<li><a class="reference internal" href="#types">Types</a></li>
<li><a class="reference internal" href="#naming">Naming</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
<li><a class="reference internal" href="#functions">Functions</a></li>
<li><a class="reference internal" href="#source-files">Source Files</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../contents.html">Documentation overview</a><ul>
<li><a href="../index.html">Open vSwitch Internals</a><ul>
<li><a href="index.html">Contributing to Open vSwitch</a><ul>
<li>Previous: <a href="coding-style.html" title="previous chapter">Open vSwitch Coding Style</a></li>
<li>Next: <a href="documentation-style.html" title="next chapter">Open vSwitch Documentation Style</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/internals/contributing/coding-style-windows.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2018, The Open vSwitch Development Community.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="../../_sources/internals/contributing/coding-style-windows.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|