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