]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. _coding_style: |
2 | ||
3 | DPDK Coding Style | |
4 | ================= | |
5 | ||
6 | Description | |
7 | ----------- | |
8 | ||
9 | This document specifies the preferred style for source files in the DPDK source tree. | |
10 | It is based on the Linux Kernel coding guidelines and the FreeBSD 7.2 Kernel Developer's Manual (see man style(9)), but was heavily modified for the needs of the DPDK. | |
11 | ||
12 | General Guidelines | |
13 | ------------------ | |
14 | ||
15 | The rules and guidelines given in this document cannot cover every situation, so the following general guidelines should be used as a fallback: | |
16 | ||
17 | * The code style should be consistent within each individual file. | |
18 | * In the case of creating new files, the style should be consistent within each file in a given directory or module. | |
19 | * The primary reason for coding standards is to increase code readability and comprehensibility, therefore always use whatever option will make the code easiest to read. | |
20 | ||
21 | Line length is recommended to be not more than 80 characters, including comments. | |
22 | [Tab stop size should be assumed to be 8-characters wide]. | |
23 | ||
24 | .. note:: | |
25 | ||
26 | The above is recommendation, and not a hard limit. | |
27 | However, it is expected that the recommendations should be followed in all but the rarest situations. | |
28 | ||
29 | C Comment Style | |
30 | --------------- | |
31 | ||
32 | Usual Comments | |
33 | ~~~~~~~~~~~~~~ | |
34 | ||
35 | These comments should be used in normal cases. | |
36 | To document a public API, a doxygen-like format must be used: refer to :ref:`doxygen_guidelines`. | |
37 | ||
38 | .. code-block:: c | |
39 | ||
40 | /* | |
41 | * VERY important single-line comments look like this. | |
42 | */ | |
43 | ||
44 | /* Most single-line comments look like this. */ | |
45 | ||
46 | /* | |
47 | * Multi-line comments look like this. Make them real sentences. Fill | |
48 | * them so they look like real paragraphs. | |
49 | */ | |
50 | ||
51 | License Header | |
52 | ~~~~~~~~~~~~~~ | |
53 | ||
54 | Each file should begin with a special comment containing the appropriate copyright and license for the file. | |
55 | Generally this is the BSD License, except for code for Linux Kernel modules. | |
56 | After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file. | |
57 | ||
58 | C Preprocessor Directives | |
59 | ------------------------- | |
60 | ||
61 | Header Includes | |
62 | ~~~~~~~~~~~~~~~ | |
63 | ||
64 | In DPDK sources, the include files should be ordered as following: | |
65 | ||
66 | #. libc includes (system includes first) | |
67 | #. DPDK EAL includes | |
68 | #. DPDK misc libraries includes | |
69 | #. application-specific includes | |
70 | ||
71 | Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: "<>". | |
72 | ||
73 | Example: | |
74 | ||
75 | .. code-block:: c | |
76 | ||
77 | #include <stdio.h> | |
78 | #include <stdlib.h> | |
79 | ||
80 | #include <rte_eal.h> | |
81 | ||
82 | #include <rte_ring.h> | |
83 | #include <rte_mempool.h> | |
84 | ||
85 | #include "application.h" | |
86 | ||
87 | Header File Guards | |
88 | ~~~~~~~~~~~~~~~~~~ | |
89 | ||
90 | Headers should be protected against multiple inclusion with the usual: | |
91 | ||
92 | .. code-block:: c | |
93 | ||
94 | #ifndef _FILE_H_ | |
95 | #define _FILE_H_ | |
96 | ||
97 | /* Code */ | |
98 | ||
99 | #endif /* _FILE_H_ */ | |
100 | ||
101 | ||
102 | Macros | |
103 | ~~~~~~ | |
104 | ||
105 | Do not ``#define`` or declare names except with the standard DPDK prefix: ``RTE_``. | |
106 | This is to ensure there are no collisions with definitions in the application itself. | |
107 | ||
108 | The names of "unsafe" macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase. | |
109 | ||
110 | The expansions of expression-like macros are either a single token or have outer parentheses. | |
111 | If a macro is an inline expansion of a function, the function name is all in lowercase and the macro has the same name all in uppercase. | |
112 | If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements. | |
113 | Any final statement-terminating semicolon should be supplied by the macro invocation rather than the macro, to make parsing easier for pretty-printers and editors. | |
114 | ||
115 | For example: | |
116 | ||
117 | .. code-block:: c | |
118 | ||
119 | #define MACRO(x, y) do { \ | |
120 | variable = (x) + (y); \ | |
121 | (y) += 2; \ | |
122 | } while(0) | |
123 | ||
124 | .. note:: | |
125 | ||
126 | Wherever possible, enums and inline functions should be preferred to macros, since they provide additional degrees of type-safety and can allow compilers to emit extra warnings about unsafe code. | |
127 | ||
128 | Conditional Compilation | |
129 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
130 | ||
131 | * When code is conditionally compiled using ``#ifdef`` or ``#if``, a comment may be added following the matching | |
132 | ``#endif`` or ``#else`` to permit the reader to easily discern where conditionally compiled code regions end. | |
133 | * This comment should be used only for (subjectively) long regions, regions greater than 20 lines, or where a series of nested ``#ifdef``'s may be confusing to the reader. | |
134 | Exceptions may be made for cases where code is conditionally not compiled for the purposes of lint(1), or other tools, even though the uncompiled region may be small. | |
135 | * The comment should be separated from the ``#endif`` or ``#else`` by a single space. | |
136 | * For short conditionally compiled regions, a closing comment should not be used. | |
137 | * The comment for ``#endif`` should match the expression used in the corresponding ``#if`` or ``#ifdef``. | |
138 | * The comment for ``#else`` and ``#elif`` should match the inverse of the expression(s) used in the preceding ``#if`` and/or ``#elif`` statements. | |
139 | * In the comments, the subexpression ``defined(FOO)`` is abbreviated as "FOO". | |
140 | For the purposes of comments, ``#ifndef FOO`` is treated as ``#if !defined(FOO)``. | |
141 | ||
142 | .. code-block:: c | |
143 | ||
144 | #ifdef KTRACE | |
145 | #include <sys/ktrace.h> | |
146 | #endif | |
147 | ||
148 | #ifdef COMPAT_43 | |
149 | /* A large region here, or other conditional code. */ | |
150 | #else /* !COMPAT_43 */ | |
151 | /* Or here. */ | |
152 | #endif /* COMPAT_43 */ | |
153 | ||
154 | #ifndef COMPAT_43 | |
155 | /* Yet another large region here, or other conditional code. */ | |
156 | #else /* COMPAT_43 */ | |
157 | /* Or here. */ | |
158 | #endif /* !COMPAT_43 */ | |
159 | ||
160 | .. note:: | |
161 | ||
162 | Conditional compilation should be used only when absolutely necessary, as it increases the number of target binaries that need to be built and tested. | |
163 | ||
164 | C Types | |
165 | ------- | |
166 | ||
167 | Integers | |
168 | ~~~~~~~~ | |
169 | ||
170 | For fixed/minimum-size integer values, the project uses the form uintXX_t (from stdint.h) instead of older BSD-style integer identifiers of the form u_intXX_t. | |
171 | ||
172 | Enumerations | |
173 | ~~~~~~~~~~~~ | |
174 | ||
175 | * Enumeration values are all uppercase. | |
176 | ||
177 | .. code-block:: c | |
178 | ||
179 | enum enumtype { ONE, TWO } et; | |
180 | ||
181 | * Enum types should be used in preference to macros #defining a set of (sequential) values. | |
182 | * Enum types should be prefixed with ``rte_`` and the elements by a suitable prefix [generally starting ``RTE_<enum>_`` - where <enum> is a shortname for the enum type] to avoid namespace collisions. | |
183 | ||
184 | Bitfields | |
185 | ~~~~~~~~~ | |
186 | ||
187 | The developer should group bitfields that are included in the same integer, as follows: | |
188 | ||
189 | .. code-block:: c | |
190 | ||
191 | struct grehdr { | |
192 | uint16_t rec:3, | |
193 | srr:1, | |
194 | seq:1, | |
195 | key:1, | |
196 | routing:1, | |
197 | csum:1, | |
198 | version:3, | |
199 | reserved:4, | |
200 | ack:1; | |
201 | /* ... */ | |
202 | } | |
203 | ||
204 | Variable Declarations | |
205 | ~~~~~~~~~~~~~~~~~~~~~ | |
206 | ||
207 | In declarations, do not put any whitespace between asterisks and adjacent tokens, except for tokens that are identifiers related to types. | |
208 | (These identifiers are the names of basic types, type qualifiers, and typedef-names other than the one being declared.) | |
209 | Separate these identifiers from asterisks using a single space. | |
210 | ||
211 | For example: | |
212 | ||
213 | .. code-block:: c | |
214 | ||
215 | int *x; /* no space after asterisk */ | |
216 | int * const x; /* space after asterisk when using a type qualifier */ | |
217 | ||
218 | * All externally-visible variables should have an ``rte_`` prefix in the name to avoid namespace collisions. | |
219 | * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in variable names. | |
220 | Lower-case letters and underscores only. | |
221 | ||
222 | Structure Declarations | |
223 | ~~~~~~~~~~~~~~~~~~~~~~ | |
224 | ||
225 | * In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order. | |
226 | Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense. | |
227 | Ordering by size then ensures that as little padding is added to the structure as possible. | |
228 | * For existing structures, additions to structures should be added to the end so for backward compatibility reasons. | |
229 | * Each structure element gets its own line. | |
230 | * Try to make the structure readable by aligning the member names using spaces as shown below. | |
231 | * Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space. | |
232 | ||
233 | .. code-block:: c | |
234 | ||
235 | struct foo { | |
236 | struct foo *next; /* List of active foo. */ | |
237 | struct mumble amumble; /* Comment for mumble. */ | |
238 | int bar; /* Try to align the comments. */ | |
239 | struct verylongtypename *baz; /* Won't fit with other members */ | |
240 | }; | |
241 | ||
242 | ||
243 | * Major structures should be declared at the top of the file in which they are used, or in separate header files if they are used in multiple source files. | |
244 | * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file. | |
245 | * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions. | |
246 | ||
247 | Queues | |
248 | ~~~~~~ | |
249 | ||
250 | Use queue(3) macros rather than rolling your own lists, whenever possible. | |
251 | Thus, the previous example would be better written: | |
252 | ||
253 | .. code-block:: c | |
254 | ||
255 | #include <sys/queue.h> | |
256 | ||
257 | struct foo { | |
258 | LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ | |
259 | struct mumble amumble; /* Comment for mumble. */ | |
260 | int bar; /* Try to align the comments. */ | |
261 | struct verylongtypename *baz; /* Won't fit with other members */ | |
262 | }; | |
263 | LIST_HEAD(, foo) foohead; /* Head of global foo list. */ | |
264 | ||
265 | ||
266 | DPDK also provides an optimized way to store elements in lockless rings. | |
267 | This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access. | |
268 | ||
269 | Typedefs | |
270 | ~~~~~~~~ | |
271 | ||
272 | Avoid using typedefs for structure types. | |
273 | ||
274 | For example, use: | |
275 | ||
276 | .. code-block:: c | |
277 | ||
278 | struct my_struct_type { | |
279 | /* ... */ | |
280 | }; | |
281 | ||
282 | struct my_struct_type my_var; | |
283 | ||
284 | ||
285 | rather than: | |
286 | ||
287 | .. code-block:: c | |
288 | ||
289 | typedef struct my_struct_type { | |
290 | /* ... */ | |
291 | } my_struct_type; | |
292 | ||
293 | my_struct_type my_var | |
294 | ||
295 | ||
296 | Typedefs are problematic because they do not properly hide their underlying type; | |
297 | for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure. | |
298 | In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary. | |
299 | Typedefs are difficult to use in stand-alone header files. | |
300 | The header that defines the typedef must be included before the header that uses it, or by the header that uses it (which causes namespace pollution), | |
301 | or there must be a back-door mechanism for obtaining the typedef. | |
302 | ||
303 | Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement). | |
304 | For example, ``#define pint int *`` does not work as expected, while ``typedef int *pint`` does work. | |
305 | As stated when discussing macros, typedefs should be preferred to macros in cases like this. | |
306 | ||
307 | When convention requires a typedef; make its name match the struct tag. | |
308 | Avoid typedefs ending in ``_t``, except as specified in Standard C or by POSIX. | |
309 | ||
310 | .. note:: | |
311 | ||
312 | It is recommended to use typedefs to define function pointer types, for reasons of code readability. | |
313 | This is especially true when the function type is used as a parameter to another function. | |
314 | ||
315 | For example: | |
316 | ||
317 | .. code-block:: c | |
318 | ||
319 | /** | |
320 | * Definition of a remote launch function. | |
321 | */ | |
322 | typedef int (lcore_function_t)(void *); | |
323 | ||
324 | /* launch a function of lcore_function_t type */ | |
325 | int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id); | |
326 | ||
327 | ||
328 | C Indentation | |
329 | ------------- | |
330 | ||
331 | General | |
332 | ~~~~~~~ | |
333 | ||
334 | * Indentation is a hard tab, that is, a tab character, not a sequence of spaces, | |
335 | ||
336 | .. note:: | |
337 | ||
338 | Global whitespace rule in DPDK, use tabs for indentation, spaces for alignment. | |
339 | ||
340 | * Do not put any spaces before a tab for indentation. | |
341 | * If you have to wrap a long statement, put the operator at the end of the line, and indent again. | |
342 | * For control statements (if, while, etc.), continuation it is recommended that the next line be indented by two tabs, rather than one, | |
343 | to prevent confusion as to whether the second line of the control statement forms part of the statement body or not. | |
344 | Alternatively, the line continuation may use additional spaces to line up to an appropriately point on the preceding line, for example, to align to an opening brace. | |
345 | ||
346 | .. note:: | |
347 | ||
348 | As with all style guidelines, code should match style already in use in an existing file. | |
349 | ||
350 | .. code-block:: c | |
351 | ||
352 | while (really_long_variable_name_1 == really_long_variable_name_2 && | |
353 | var3 == var4){ /* confusing to read as */ | |
354 | x = y + z; /* control stmt body lines up with second line of */ | |
355 | a = b + c; /* control statement itself if single indent used */ | |
356 | } | |
357 | ||
358 | if (really_long_variable_name_1 == really_long_variable_name_2 && | |
359 | var3 == var4){ /* two tabs used */ | |
360 | x = y + z; /* statement body no longer lines up */ | |
361 | a = b + c; | |
362 | } | |
363 | ||
364 | z = a + really + long + statement + that + needs + | |
365 | two + lines + gets + indented + on + the + | |
366 | second + and + subsequent + lines; | |
367 | ||
368 | ||
369 | * Do not add whitespace at the end of a line. | |
370 | ||
371 | * Do not add whitespace or a blank line at the end of a file. | |
372 | ||
373 | ||
374 | Control Statements and Loops | |
375 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
376 | ||
377 | * Include a space after keywords (if, while, for, return, switch). | |
378 | * Do not use braces (``{`` and ``}``) for control statements with zero or just a single statement, unless that statement is more than a single line in which case the braces are permitted. | |
379 | ||
380 | .. code-block:: c | |
381 | ||
382 | for (p = buf; *p != '\0'; ++p) | |
383 | ; /* nothing */ | |
384 | for (;;) | |
385 | stmt; | |
386 | for (;;) { | |
387 | z = a + really + long + statement + that + needs + | |
388 | two + lines + gets + indented + on + the + | |
389 | second + and + subsequent + lines; | |
390 | } | |
391 | for (;;) { | |
392 | if (cond) | |
393 | stmt; | |
394 | } | |
395 | if (val != NULL) | |
396 | val = realloc(val, newsize); | |
397 | ||
398 | ||
399 | * Parts of a for loop may be left empty. | |
400 | ||
401 | .. code-block:: c | |
402 | ||
403 | for (; cnt < 15; cnt++) { | |
404 | stmt1; | |
405 | stmt2; | |
406 | } | |
407 | ||
408 | * Closing and opening braces go on the same line as the else keyword. | |
409 | * Braces that are not necessary should be left out. | |
410 | ||
411 | .. code-block:: c | |
412 | ||
413 | if (test) | |
414 | stmt; | |
415 | else if (bar) { | |
416 | stmt; | |
417 | stmt; | |
418 | } else | |
419 | stmt; | |
420 | ||
421 | ||
422 | Function Calls | |
423 | ~~~~~~~~~~~~~~ | |
424 | ||
425 | * Do not use spaces after function names. | |
426 | * Commas should have a space after them. | |
427 | * No spaces after ``(`` or ``[`` or preceding the ``]`` or ``)`` characters. | |
428 | ||
429 | .. code-block:: c | |
430 | ||
431 | error = function(a1, a2); | |
432 | if (error != 0) | |
433 | exit(error); | |
434 | ||
435 | ||
436 | Operators | |
437 | ~~~~~~~~~ | |
438 | ||
439 | * Unary operators do not require spaces, binary operators do. | |
440 | * Do not use parentheses unless they are required for precedence or unless the statement is confusing without them. | |
441 | However, remember that other people may be more easily confused than you. | |
442 | ||
443 | Exit | |
444 | ~~~~ | |
445 | ||
446 | Exits should be 0 on success, or 1 on failure. | |
447 | ||
448 | .. code-block:: c | |
449 | ||
450 | exit(0); /* | |
451 | * Avoid obvious comments such as | |
452 | * "Exit 0 on success." | |
453 | */ | |
454 | } | |
455 | ||
456 | Local Variables | |
457 | ~~~~~~~~~~~~~~~ | |
458 | ||
459 | * Variables should be declared at the start of a block of code rather than in the middle. | |
460 | The exception to this is when the variable is ``const`` in which case the declaration must be at the point of first use/assignment. | |
461 | * When declaring variables in functions, multiple variables per line are OK. | |
462 | However, if multiple declarations would cause the line to exceed a reasonable line length, begin a new set of declarations on the next line rather than using a line continuation. | |
463 | * Be careful to not obfuscate the code by initializing variables in the declarations, only the last variable on a line should be initialized. | |
464 | If multiple variables are to be initialized when defined, put one per line. | |
465 | * Do not use function calls in initializers, except for ``const`` variables. | |
466 | ||
467 | .. code-block:: c | |
468 | ||
469 | int i = 0, j = 0, k = 0; /* bad, too many initializer */ | |
470 | ||
471 | char a = 0; /* OK, one variable per line with initializer */ | |
472 | char b = 0; | |
473 | ||
474 | float x, y = 0.0; /* OK, only last variable has initializer */ | |
475 | ||
476 | ||
477 | Casts and sizeof | |
478 | ~~~~~~~~~~~~~~~~ | |
479 | ||
480 | * Casts and sizeof statements are not followed by a space. | |
481 | * Always write sizeof statements with parenthesis. | |
482 | The redundant parenthesis rules do not apply to sizeof(var) instances. | |
483 | ||
484 | C Function Definition, Declaration and Use | |
485 | ------------------------------------------- | |
486 | ||
487 | Prototypes | |
488 | ~~~~~~~~~~ | |
489 | ||
490 | * It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere. | |
491 | * Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary. | |
492 | * Functions used from other parts of code (external API) must be prototyped in the relevant include file. | |
493 | * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering. | |
494 | * Functions that are used locally in more than one module go into a separate header file, for example, "extern.h". | |
495 | * Do not use the ``__P`` macro. | |
496 | * Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See :ref:`doxygen_guidelines` for details. | |
497 | * Functions that are part of the external API must have an ``rte_`` prefix on the function name. | |
498 | * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in function names. Lower-case letters and underscores only. | |
499 | * When prototyping functions, associate names with parameter types, for example: | |
500 | ||
501 | .. code-block:: c | |
502 | ||
503 | void function1(int fd); /* good */ | |
504 | void function2(int); /* bad */ | |
505 | ||
506 | * Short function prototypes should be contained on a single line. | |
507 | Longer prototypes, e.g. those with many parameters, can be split across multiple lines. | |
508 | The second and subsequent lines should be further indented as for line statement continuations as described in the previous section. | |
509 | ||
510 | .. code-block:: c | |
511 | ||
512 | static char *function1(int _arg, const char *_arg2, | |
513 | struct foo *_arg3, | |
514 | struct bar *_arg4, | |
515 | struct baz *_arg5); | |
516 | static void usage(void); | |
517 | ||
518 | .. note:: | |
519 | ||
520 | Unlike function definitions, the function prototypes do not need to place the function return type on a separate line. | |
521 | ||
522 | Definitions | |
523 | ~~~~~~~~~~~ | |
524 | ||
525 | * The function type should be on a line by itself preceding the function. | |
526 | * The opening brace of the function body should be on a line by itself. | |
527 | ||
528 | .. code-block:: c | |
529 | ||
530 | static char * | |
531 | function(int a1, int a2, float fl, int a4) | |
532 | { | |
533 | ||
534 | ||
535 | * Do not declare functions inside other functions. | |
536 | ANSI C states that such declarations have file scope regardless of the nesting of the declaration. | |
537 | Hiding file declarations in what appears to be a local scope is undesirable and will elicit complaints from a good compiler. | |
538 | * Old-style (K&R) function declaration should not be used, use ANSI function declarations instead as shown below. | |
539 | * Long argument lists should be wrapped as described above in the function prototypes section. | |
540 | ||
541 | .. code-block:: c | |
542 | ||
543 | /* | |
544 | * All major routines should have a comment briefly describing what | |
545 | * they do. The comment before the "main" routine should describe | |
546 | * what the program does. | |
547 | */ | |
548 | int | |
549 | main(int argc, char *argv[]) | |
550 | { | |
551 | char *ep; | |
552 | long num; | |
553 | int ch; | |
554 | ||
555 | C Statement Style and Conventions | |
556 | --------------------------------- | |
557 | ||
558 | NULL Pointers | |
559 | ~~~~~~~~~~~~~ | |
560 | ||
561 | * NULL is the preferred null pointer constant. | |
562 | Use NULL instead of ``(type *)0`` or ``(type *)NULL``, except where the compiler does not know the destination type e.g. for variadic args to a function. | |
563 | * Test pointers against NULL, for example, use: | |
564 | ||
565 | .. code-block:: c | |
566 | ||
567 | if (p == NULL) /* Good, compare pointer to NULL */ | |
568 | ||
569 | if (!p) /* Bad, using ! on pointer */ | |
570 | ||
571 | ||
572 | * Do not use ! for tests unless it is a boolean, for example, use: | |
573 | ||
574 | .. code-block:: c | |
575 | ||
576 | if (*p == '\0') /* check character against (char)0 */ | |
577 | ||
578 | Return Value | |
579 | ~~~~~~~~~~~~ | |
580 | ||
581 | * Functions which create objects, or allocate memory, should return pointer types, and NULL on error. | |
582 | The error type should be indicated may setting the variable ``rte_errno`` appropriately. | |
583 | * Functions which work on bursts of packets, such as RX-like or TX-like functions, should return the number of packets handled. | |
584 | * Other functions returning int should generally behave like system calls: | |
585 | returning 0 on success and -1 on error, setting ``rte_errno`` to indicate the specific type of error. | |
586 | * Where already standard in a given library, the alternative error approach may be used where the negative value is not -1 but is instead ``-errno`` if relevant, for example, ``-EINVAL``. | |
587 | Note, however, to allow consistency across functions returning integer or pointer types, the previous approach is preferred for any new libraries. | |
588 | * For functions where no error is possible, the function type should be ``void`` not ``int``. | |
589 | * Routines returning ``void *`` should not have their return values cast to any pointer type. | |
590 | (Typecasting can prevent the compiler from warning about missing prototypes as any implicit definition of a function returns int, | |
591 | which, unlike ``void *``, needs a typecast to assign to a pointer variable.) | |
592 | ||
593 | .. note:: | |
594 | ||
595 | The above rule about not typecasting ``void *`` applies to malloc, as well as to DPDK functions. | |
596 | ||
597 | * Values in return statements should not be enclosed in parentheses. | |
598 | ||
599 | Logging and Errors | |
600 | ~~~~~~~~~~~~~~~~~~ | |
601 | ||
602 | In the DPDK environment, use the logging interface provided: | |
603 | ||
604 | .. code-block:: c | |
605 | ||
606 | #define RTE_LOGTYPE_TESTAPP1 RTE_LOGTYPE_USER1 | |
607 | #define RTE_LOGTYPE_TESTAPP2 RTE_LOGTYPE_USER2 | |
608 | ||
609 | /* enable these logs type */ | |
610 | rte_set_log_type(RTE_LOGTYPE_TESTAPP1, 1); | |
611 | rte_set_log_type(RTE_LOGTYPE_TESTAPP2, 1); | |
612 | ||
613 | /* log in debug level */ | |
614 | rte_set_log_level(RTE_LOG_DEBUG); | |
615 | RTE_LOG(DEBUG, TESTAPP1, "this is is a debug level message\n"); | |
616 | RTE_LOG(INFO, TESTAPP1, "this is is a info level message\n"); | |
617 | RTE_LOG(WARNING, TESTAPP1, "this is is a warning level message\n"); | |
618 | ||
619 | /* log in info level */ | |
620 | rte_set_log_level(RTE_LOG_INFO); | |
621 | RTE_LOG(DEBUG, TESTAPP2, "debug level message (not displayed)\n"); | |
622 | ||
623 | Branch Prediction | |
624 | ~~~~~~~~~~~~~~~~~ | |
625 | ||
626 | * When a test is done in a critical zone (called often or in a data path) the code can use the ``likely()`` and ``unlikely()`` macros to indicate the expected, or preferred fast path. | |
627 | They are expanded as a compiler builtin and allow the developer to indicate if the branch is likely to be taken or not. Example: | |
628 | ||
629 | .. code-block:: c | |
630 | ||
631 | #include <rte_branch_prediction.h> | |
632 | if (likely(x > 1)) | |
633 | do_stuff(); | |
634 | ||
635 | .. note:: | |
636 | ||
637 | The use of ``likely()`` and ``unlikely()`` should only be done in performance critical paths, | |
638 | and only when there is a clearly preferred path, or a measured performance increase gained from doing so. | |
639 | These macros should be avoided in non-performance-critical code. | |
640 | ||
641 | Static Variables and Functions | |
642 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
643 | ||
644 | * All functions and variables that are local to a file must be declared as ``static`` because it can often help the compiler to do some optimizations (such as, inlining the code). | |
645 | * Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file. | |
646 | ||
647 | .. note:: | |
648 | Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused. | |
649 | ||
650 | Const Attribute | |
651 | ~~~~~~~~~~~~~~~ | |
652 | ||
653 | The ``const`` attribute should be used as often as possible when a variable is read-only. | |
654 | ||
655 | Inline ASM in C code | |
656 | ~~~~~~~~~~~~~~~~~~~~ | |
657 | ||
658 | The ``asm`` and ``volatile`` keywords do not have underscores. The AT&T syntax should be used. | |
659 | Input and output operands should be named to avoid confusion, as shown in the following example: | |
660 | ||
661 | .. code-block:: c | |
662 | ||
663 | asm volatile("outb %[val], %[port]" | |
664 | : : | |
665 | [port] "dN" (port), | |
666 | [val] "a" (val)); | |
667 | ||
668 | Control Statements | |
669 | ~~~~~~~~~~~~~~~~~~ | |
670 | ||
671 | * Forever loops are done with for statements, not while statements. | |
672 | * Elements in a switch statement that cascade should have a FALLTHROUGH comment. For example: | |
673 | ||
674 | .. code-block:: c | |
675 | ||
676 | switch (ch) { /* Indent the switch. */ | |
677 | case 'a': /* Don't indent the case. */ | |
678 | aflag = 1; /* Indent case body one tab. */ | |
679 | /* FALLTHROUGH */ | |
680 | case 'b': | |
681 | bflag = 1; | |
682 | break; | |
683 | case '?': | |
684 | default: | |
685 | usage(); | |
686 | /* NOTREACHED */ | |
687 | } | |
688 | ||
689 | ||
690 | Python Code | |
691 | ----------- | |
692 | ||
693 | All python code should be compliant with `PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_. | |
694 | ||
695 | The ``pep8`` tool can be used for testing compliance with the guidelines. |