coding_style.rst revision 97f17497
1.. _coding_style:
2
3DPDK Coding Style
4=================
5
6Description
7-----------
8
9This document specifies the preferred style for source files in the DPDK source tree.
10It 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
12General Guidelines
13------------------
14
15The 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
21Line 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
29C Comment Style
30---------------
31
32Usual Comments
33~~~~~~~~~~~~~~
34
35These comments should be used in normal cases.
36To 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
51License Header
52~~~~~~~~~~~~~~
53
54Each file should begin with a special comment containing the appropriate copyright and license for the file.
55Generally this is the BSD License, except for code for Linux Kernel modules.
56After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file.
57
58C Preprocessor Directives
59-------------------------
60
61Header Includes
62~~~~~~~~~~~~~~~
63
64In 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
71Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: "<>".
72
73Example:
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
87Header File Guards
88~~~~~~~~~~~~~~~~~~
89
90Headers 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
102Macros
103~~~~~~
104
105Do not ``#define`` or declare names except with the standard DPDK prefix: ``RTE_``.
106This is to ensure there are no collisions with definitions in the application itself.
107
108The names of "unsafe" macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase.
109
110The expansions of expression-like macros are either a single token or have outer parentheses.
111If 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.
112If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements.
113Any 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
115For 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
128Conditional 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
164C Types
165-------
166
167Integers
168~~~~~~~~
169
170For 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
172Enumerations
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
184Bitfields
185~~~~~~~~~
186
187The 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
204Variable Declarations
205~~~~~~~~~~~~~~~~~~~~~
206
207In 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.)
209Separate these identifiers from asterisks using a single space.
210
211For 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
222Structure 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
247Queues
248~~~~~~
249
250Use queue(3) macros rather than rolling your own lists, whenever possible.
251Thus, 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
266DPDK also provides an optimized way to store elements in lockless rings.
267This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access.
268
269Typedefs
270~~~~~~~~
271
272Avoid using typedefs for structure types.
273
274For 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
285rather 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
296Typedefs are problematic because they do not properly hide their underlying type;
297for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure.
298In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary.
299Typedefs are difficult to use in stand-alone header files.
300The 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),
301or there must be a back-door mechanism for obtaining the typedef.
302
303Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement).
304For example, ``#define pint int *`` does not work as expected, while ``typedef int *pint`` does work.
305As stated when discussing macros, typedefs should be preferred to macros in cases like this.
306
307When convention requires a typedef; make its name match the struct tag.
308Avoid 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
315For 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
328C Indentation
329-------------
330
331General
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
374Control 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
422Function 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
436Operators
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
443Exit
444~~~~
445
446Exits 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
456Local 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
477Casts 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
484C Function Definition, Declaration and Use
485-------------------------------------------
486
487Prototypes
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
522Definitions
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
555C Statement Style and Conventions
556---------------------------------
557
558NULL 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
578Return 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
599Logging and Errors
600~~~~~~~~~~~~~~~~~~
601
602In 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
623Branch 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
641Static 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
650Const Attribute
651~~~~~~~~~~~~~~~
652
653The ``const`` attribute should be used as often as possible when a variable is read-only.
654
655Inline ASM in C code
656~~~~~~~~~~~~~~~~~~~~
657
658The ``asm`` and ``volatile`` keywords do not have underscores. The AT&T syntax should be used.
659Input 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
668Control 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