]>
Commit | Line | Data |
---|---|---|
bd7bc0cb SF |
1 | .. |
2 | Licensed under the Apache License, Version 2.0 (the "License"); you may | |
3 | not use this file except in compliance with the License. You may obtain | |
4 | a copy of the License at | |
5 | ||
6 | http://www.apache.org/licenses/LICENSE-2.0 | |
7 | ||
8 | Unless required by applicable law or agreed to in writing, software | |
9 | distributed under the License is distributed on an "AS IS" BASIS, WITHOUT | |
10 | WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the | |
11 | License for the specific language governing permissions and limitations | |
12 | under the License. | |
13 | ||
14 | Convention for heading levels in Open vSwitch documentation: | |
15 | ||
16 | ======= Heading 0 (reserved for the title in a document) | |
17 | ------- Heading 1 | |
18 | ~~~~~~~ Heading 2 | |
19 | +++++++ Heading 3 | |
20 | ''''''' Heading 4 | |
21 | ||
22 | Avoid deeper levels because they do not render well. | |
23 | ||
24 | ========================================== | |
25 | Open vSwitch Windows Datapath Coding Style | |
26 | ========================================== | |
27 | ||
dfec5030 | 28 | The :doc:`coding style <coding-style>` guide gives the flexibility for each |
d0e53b15 SF |
29 | platform to use its own coding style for the kernel datapath. This file |
30 | describes the specific coding style used in most of the C files in the Windows | |
31 | kernel datapath of the Open vSwitch distribution. | |
bd7bc0cb SF |
32 | |
33 | Most of the coding conventions applicable for the Open vSwitch distribution are | |
34 | applicable to the Windows kernel datapath as well. There are some exceptions | |
dfec5030 | 35 | and new guidelines owing to the commonly followed practices in Windows |
bd7bc0cb SF |
36 | kernel/driver code. They are noted as follows: |
37 | ||
38 | Basics | |
39 | ------ | |
40 | ||
41 | - Limit lines to 79 characters. | |
42 | ||
43 | Many times, this is not possible due to long names of functions and it is | |
44 | fine to go beyond the characters limit. One common example is when calling | |
45 | into NDIS functions. | |
46 | ||
47 | Types | |
48 | ----- | |
49 | ||
50 | Use data types defined by Windows for most of the code. This is a common | |
51 | practice in Windows driver code, and it makes integrating with the data | |
52 | structures and functions defined by Windows easier. Example: ``DWORD`` and | |
53 | ``BOOLEAN``. | |
54 | ||
55 | Use caution in portions of the code that interface with the OVS userspace. OVS | |
56 | userspace does not use Windows specific data types, and when copying data back | |
57 | and forth between kernel and userspace, care should be exercised. | |
58 | ||
59 | Naming | |
60 | ------ | |
61 | ||
62 | It is common practice to use camel casing for naming variables, functions and | |
63 | files in Windows. For types, especially structures, unions and enums, using | |
dfec5030 | 64 | all upper case letters with words separated by '_' is common. These practices |
bd7bc0cb SF |
65 | can be used for OVS Windows datapath. However, use the following guidelines: |
66 | ||
67 | - Use lower case to begin the name of a variable. | |
68 | ||
69 | - Do not use '_' to begin the name of the variable. '_' is to be used to begin | |
70 | the parameters of a pre-processor macro. | |
71 | ||
72 | - Use upper case to begin the name of a function, enum, file name etc. | |
73 | ||
74 | - Static functions whose scope is limited to the file they are defined in can | |
75 | be prefixed with '_'. This is not mandatory though. | |
76 | ||
77 | - For types, use all upper case for all letters with words separated by '_'. If | |
78 | camel casing is preferred, use upper case for the first letter. | |
79 | ||
80 | - It is a common practice to define a pointer type by prefixing the letter 'P' | |
81 | to a data type. The same practice can be followed here as well. | |
82 | ||
83 | For example:: | |
84 | ||
85 | static __inline BOOLEAN | |
86 | OvsDetectTunnelRxPkt(POVS_FORWARDING_CONTEXT ovsFwdCtx, | |
87 | POVS_FLOW_KEY flowKey) | |
88 | { | |
89 | POVS_VPORT_ENTRY tunnelVport = NULL; | |
90 | ||
91 | if (!flowKey->ipKey.nwFrag && | |
92 | flowKey->ipKey.nwProto == IPPROTO_UDP && | |
93 | flowKey->ipKey.l4.tpDst == VXLAN_UDP_PORT_NBO) { | |
94 | tunnelVport = OvsGetTunnelVport(OVSWIN_VPORT_TYPE_VXLAN); | |
95 | ovsActionStats.rxVxlan++; | |
96 | } else { | |
97 | return FALSE; | |
98 | } | |
99 | ||
100 | if (tunnelVport) { | |
101 | ASSERT(ovsFwdCtx->tunnelRxNic == NULL); | |
102 | ovsFwdCtx->tunnelRxNic = tunnelVport; | |
103 | return TRUE; | |
104 | } | |
105 | ||
106 | return FALSE; | |
107 | } | |
108 | ||
109 | For declaring variables of pointer type, use of the pointer data type prefixed | |
110 | with 'P' is preferred over using '*'. This is not mandatory though, and is only | |
111 | prescribed since it is a common practice in Windows. | |
112 | ||
113 | Example, #1 is preferred over #2 though #2 is also equally correct: | |
114 | ||
115 | 1. ``PNET_BUFFER_LIST curNbl;`` | |
116 | 2. ``NET_BUFFER_LIST *curNbl;`` | |
117 | ||
118 | Comments | |
119 | -------- | |
120 | ||
121 | Comments should be written as full sentences that start with a capital letter | |
dfec5030 | 122 | and end with a period. Putting two spaces between sentences is not necessary. |
bd7bc0cb SF |
123 | |
124 | ``//`` can be used for comments as long as the comment is a single line | |
125 | comment. For block comments, use ``/* */`` comments | |
126 | ||
127 | Functions | |
128 | --------- | |
129 | ||
130 | Put the return type, function name, and the braces that surround the function's | |
131 | code on separate lines, all starting in column 0. | |
132 | ||
133 | Before each function definition, write a comment that describes the function's | |
134 | purpose, including each parameter, the return value, and side effects. | |
135 | References to argument names should be given in single-quotes, e.g. 'arg'. The | |
136 | comment should not include the function name, nor need it follow any formal | |
137 | structure. The comment does not need to describe how a function does its work, | |
138 | unless this information is needed to use the function correctly (this is often | |
139 | better done with comments *inside* the function). | |
140 | ||
141 | Mention any side effects that the function has that are not obvious based on | |
142 | the name of the function or based on the workflow it is called from. | |
143 | ||
144 | In the interest of keeping comments describing functions similar in structure, | |
145 | use the following template. | |
146 | ||
147 | :: | |
148 | ||
149 | /* | |
150 | *---------------------------------------------------------------------------- | |
151 | * Any description of the function, arguments, return types, assumptions and | |
152 | * side effects. | |
153 | *---------------------------------------------------------------------------- | |
154 | */ | |
155 | ||
156 | Source Files | |
157 | ------------ | |
158 | ||
159 | Each source file should state its license in a comment at the very top, | |
160 | followed by a comment explaining the purpose of the code that is in that file. | |
161 | The comment should explain how the code in the file relates to code in other | |
162 | files. The goal is to allow a programmer to quickly figure out where a given | |
163 | module fits into the larger system. | |
164 | ||
165 | The first non-comment line in a .c source file should be:: | |
166 | ||
167 | #include <precomp.h> | |
168 | ||
169 | ``#include`` directives should appear in the following order: | |
170 | ||
171 | 1. ``#include <precomp.h>`` | |
172 | ||
173 | 2. The module's own headers, if any. Including this before any other header | |
174 | (besides ``<precomp.h>``) ensures that the module's header file is | |
175 | self-contained (see *Header Files*) below. | |
176 | ||
177 | 3. Standard C library headers and other system headers, preferably in | |
178 | alphabetical order. (Occasionally one encounters a set of system headers | |
179 | that must be included in a particular order, in which case that order must | |
180 | take precedence.) | |
181 | ||
182 | 4. Open vSwitch headers, in alphabetical order. Use ``""``, not ``<>``, to | |
183 | specify Open vSwitch header names. |