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
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
<HTML>
<HEAD>
<TITLE>AVS C Source file format</TITLE>
</HEAD>
<BODY>
<H1>1. C Source file format</H1>
<P>
The following defines the common C source file format for linux-wlan.
Most of the C-code formatting rules come from the linux kernel
document <CODE>CodingStyle</CODE>.
<H1>2. Characters and Code layout</H1>
<H2>2.1. Character Set</H2>
<P>
For all source files, we'll stick to the US character set and avoid all
trigraphs.
<H2>2.2. Indentation</H2>
<P>
All indentation will be done using tab characters which are mapped to a
spacing of eight characters.
<H2>2.3. Braces</H2>
<P>
Braces will be placed according to the format originally established
in Kernighan and Ritchie's book "The C Programming Language". Here
are some example statements:
<P>
<TABLE border=1><TR><TD><PRE>
for ( i= 0; i < N; i++) {
.
.
.
}
if ( a < b ) {
.
.
.
} else {
.
.
.
}
do {
.
.
.
} while ( i >> 0 );
</PRE></TABLE>
<H1>3. Naming and Definition Conventions</H1>
<H2>3.1. Preprocessor Elements</H2>
<P>
All elements defined via the C preprocessor (constants and macros) are
named using all capital letters. An exception is for macros that are
either wrapping function calls for portability or for macros that are
inline replacements for code that would normally be in a function.
<H2>3.2. Types</H2>
<P>
All programmer defined types must have single word type names
defined using the <PRE>typedef</PRE> statement. All type names
should be identified with an <PRE>_t</PRE> suffix. This is
particularly important for function pointers that are members of
structures or arguments to functions.
<P>
Anonymous types are not allowed. All struct, union, and enum
types shall be named and typedef'd.
<H2>3.3. Variables</H2>
The following conventions should be followed for variable
declaration and naming:
<UL>
<LI>Variables should be named using meaningful names.
<LI>Avoid variables with static lifetimes.
<LI>If static lifetime variables must be used, use file
scoped static variables and avoid static lifetime
variables with visibility beyond file scope.
<LI>All static lifetime variables should be declared in
the "Local Statics" section near the top of a given
source file.
</UL>
<H2>3.4. Functions</H2>
The following conventions should be followed for function
declaration and definition:
<UL>
<LI><B>All</B> functions must be declared above the point
where they are called.
<LI>Any functions that are only intended to be called
within a given source file should be declared static
within that file.
<LI>Functions defined within a common source file that are
visible across source file boundaries should be named
using a prefix that is unique to that source file.
</UL>
<H1>4. File Layout</H1>
<P>
Each file should be layed out using a common format. The
following shows a complete file with all its major sections.
<P>
Each major section within the file is begun with a comment of the
form:
<PRE>
/*================================================================*/
/* [Section Name] */
</PRE>
<P>
Subsections within a major section are denoted using:
<PRE>
/*----------------------------------------------------------------*/
/* [Subsection Name] */
</PRE>
<P>
<TABLE border=1><TR><TD>
<PRE>
/* [filename]: [one line description of the file]
* --------------------------------------------------------------------
*
* [Project Name]
*
* [License Statement]
*
* [Warranty Statement]
*
* [Initial Author Statement]
*
* --------------------------------------------------------------------
*
* [Initial Author Contact]
*
* --------------------------------------------------------------------
*
* [File Description]
*
* [Implementation and Usage Notes]
*
* --------------------------------------------------------------------
*/
/*================================================================*/
/* System Includes */
/*================================================================*/
/* Project Includes */
/*================================================================*/
/* Local Constants */
/*================================================================*/
/* Local Macros */
/*----------------------------------------------------------------*/
/* [A subsection] */
/*================================================================*/
/* Local Types */
/*================================================================*/
/* Local Static Definitions */
/*================================================================*/
/* Local Function Declarations */
/*================================================================*/
/* Function Definitions */
</PRE>
</TABLE>
<H2>4.1. System Includes Section</H2>
<P>
Preprocessor <CODE>#include</CODE> statements that are including
<I>system</I> includes shall be placed in this section. System
includes are those include files that are <B>not</B> part of the
managed source for this project.
<H2>4.2. Project Includes Section</H2>
<P>
Preprocessor <CODE>#include</CODE> statements that are including
<I>project</I> includes shall be placed in this section. Project
includes are those include files that are a part of the
managed source for this project.
<H2>4.3. Local Constants Section</H2>
<P>
Preprocessor "manifest" constants that are local to this file shall be
placed in this section. "Manifest" constants are preprocessor macros
that take no arguments.
<H2>4.4. Local Macros Section</H2>
<P>
Proprocessor macros that accept arguments shall be placed in this
section.
<H2>4.5. Local Types Section</H2>
<P>
Programmer defined types that are only used within the scope of this
file shall be defined in this section. Programmer defined types that
are used in more than one source file should be defined in a header
file.
<H2>4.6. Local Static Definitions Section</H2>
<P>
Variables with static extent that are defined within this file shall
be placed in this section. Whether a variable has scope beyond this
file will be apparent based on the presence or absence of the
<CODE>static</CODE> keyword in the declaration. If a variable is
declared without the <CODE>static</CODE> keyword, there should be an
<CODE>extern</CODE> declaration for that variable in a header file.
<H2>4.6. Local Function Declarations Section</H2>
<P>
Functions that are only used within this file should be declared
(prototyped) in this section. Additionally, these functions should be
declared using the <CODE>static</CODE> keyword. This avoids polluting
the global namespace with function names that need not be
<CODE>extern</CODE>.
<P>
Any functions defined in this file that <I>are</I> called from outside
this file should be declared (prototyped) in a header file.
<H2>4.6. Function Definitions Section</H2>
<P>
This section contains the definitions of the functions in this file.
Each function (or group of strongly related functions) will be
preceded by a function header comment (see below).
<H1>5. Comments</H1>
<H2>5.1. File Header</H2>
<P>
Each source file will have a header comment containing information
about the file as a whole. That comment shall be formatted:
<P>
<TABLE border=1><TR><TD><PRE>
/* [filename]: [one line description of the file]
* --------------------------------------------------------------------
*
* [Project Name]
*
* [License Statement]
*
* [Warranty Statement]
*
* [Initial Author Statement]
*
* --------------------------------------------------------------------
*
* [Initial Author Contact]
*
* --------------------------------------------------------------------
*
* [File Description]
*
* [Implementation and Usage Notes]
*
* --------------------------------------------------------------------
*/
</PRE>
</TABLE>
<H2>5.2. Function Header</H2>
<P>
Each function (or group of closely related functions) will be preceded
by a function comment header. The <CODE>Side effects</CODE> and
<CODE>Call context</CODE> sections are optional.
<P>
<TABLE border=1><TR><TD><PRE>
/*----------------------------------------------------------------
* [function name]
*
* [description]
*
* Arguments:
* [argument list]
*
* Returns:
* [return value list]
*
* Side effects:
* [description of function side effects]
*
* Call context:
* [description of calling context]
----------------------------------------------------------------*/
</PRE>
</TABLE>
</BODY>
</HTML>
|
