net/cnxk: make inline inbound device usage as default
[dpdk.git] / doc / guides / contributing / coding_style.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright 2018 The DPDK contributors
3
4 .. _coding_style:
5
6 DPDK Coding Style
7 =================
8
9 Description
10 -----------
11
12 This document specifies the preferred style for source files in the DPDK source tree.
13 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.
14
15 General Guidelines
16 ------------------
17
18 The rules and guidelines given in this document cannot cover every situation, so the following general guidelines should be used as a fallback:
19
20 * The code style should be consistent within each individual file.
21 * In the case of creating new files, the style should be consistent within each file in a given directory or module.
22 * 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.
23
24 Line length is recommended to be not more than 80 characters, including comments.
25 [Tab stop size should be assumed to be 8-characters wide].
26
27 .. note::
28
29         The above is recommendation, and not a hard limit.
30         Generally, line lengths up to 100 characters are acceptable in the code.
31
32 C Comment Style
33 ---------------
34
35 Usual Comments
36 ~~~~~~~~~~~~~~
37
38 These comments should be used in normal cases.
39 To document a public API, a doxygen-like format must be used: refer to :ref:`doxygen_guidelines`.
40
41 .. code-block:: c
42
43  /*
44   * VERY important single-line comments look like this.
45   */
46
47  /* Most single-line comments look like this. */
48
49  /*
50   * Multi-line comments look like this.  Make them real sentences. Fill
51   * them so they look like real paragraphs.
52   */
53
54 License Header
55 ~~~~~~~~~~~~~~
56
57 Each file must begin with a special comment containing the
58 `Software Package Data Exchange (SPDX) License Identifier <https://spdx.org/using-spdx-license-identifier>`_.
59
60 Generally this is the BSD License, except for code granted special exceptions.
61 The SPDX licences identifier is sufficient, a file should not contain
62 an additional text version of the license (boilerplate).
63
64 After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file.
65
66 C Preprocessor Directives
67 -------------------------
68
69 Header Includes
70 ~~~~~~~~~~~~~~~
71
72 In DPDK sources, the include files should be ordered as following:
73
74 #. libc includes (system includes first)
75 #. DPDK EAL includes
76 #. DPDK misc libraries includes
77 #. application-specific includes
78
79 Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: "<>".
80
81 Example:
82
83 .. code-block:: c
84
85  #include <stdio.h>
86  #include <stdlib.h>
87
88  #include <rte_eal.h>
89
90  #include <rte_ring.h>
91  #include <rte_mempool.h>
92
93  #include "application.h"
94
95 Header File Guards
96 ~~~~~~~~~~~~~~~~~~
97
98 Headers should be protected against multiple inclusion with the usual:
99
100 .. code-block:: c
101
102    #ifndef _FILE_H_
103    #define _FILE_H_
104
105    /* Code */
106
107    #endif /* _FILE_H_ */
108
109
110 Macros
111 ~~~~~~
112
113 Do not ``#define`` or declare names except with the standard DPDK prefix: ``RTE_``.
114 This is to ensure there are no collisions with definitions in the application itself.
115
116 The names of "unsafe" macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase.
117
118 The expansions of expression-like macros are either a single token or have outer parentheses.
119 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.
120 If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements.
121 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.
122
123 For example:
124
125 .. code-block:: c
126
127  #define MACRO(x, y) do {                                        \
128          variable = (x) + (y);                                   \
129          (y) += 2;                                               \
130  } while(0)
131
132 .. note::
133
134  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.
135
136 Conditional Compilation
137 ~~~~~~~~~~~~~~~~~~~~~~~
138
139 .. note::
140
141    Conditional compilation should be used only when absolutely necessary,
142    as it increases the number of target binaries that need to be built and tested.
143    See below for details of some utility macros/defines available
144    to allow ifdefs/macros to be replaced by C conditional in some cases.
145
146 Some high-level guidelines on the use of conditional compilation:
147
148 * If code can compile on all platforms/systems,
149   but cannot run on some due to lack of support,
150   then regular C conditionals, as described in the next section,
151   should be used instead of conditional compilation.
152 * If the code in question cannot compile on all systems,
153   but constitutes only a small fragment of a file,
154   then conditional compilation should be used, as described in this section.
155 * If the code for conditional compilation implements an interface in an OS
156   or platform-specific way, then create a file for each OS or platform
157   and select the appropriate file using the Meson build system.
158   In most cases, these environment-specific files should be created inside the EAL library,
159   rather than having each library implement its own abstraction layer.
160
161 Additional style guidance for the use of conditional compilation macros:
162
163 * When code is conditionally compiled using ``#ifdef`` or ``#if``, a comment may be added following the matching
164   ``#endif`` or ``#else`` to permit the reader to easily discern where conditionally compiled code regions end.
165 * 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.
166   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.
167 * The comment should be separated from the ``#endif`` or ``#else`` by a single space.
168 * For short conditionally compiled regions, a closing comment should not be used.
169 * The comment for ``#endif`` should match the expression used in the corresponding ``#if`` or ``#ifdef``.
170 * The comment for ``#else`` and ``#elif`` should match the inverse of the expression(s) used in the preceding ``#if`` and/or ``#elif`` statements.
171 * In the comments, the subexpression ``defined(FOO)`` is abbreviated as "FOO".
172   For the purposes of comments, ``#ifndef FOO`` is treated as ``#if !defined(FOO)``.
173
174 .. code-block:: c
175
176  #ifdef KTRACE
177  #include <sys/ktrace.h>
178  #endif
179
180  #ifdef COMPAT_43
181  /* A large region here, or other conditional code. */
182  #else /* !COMPAT_43 */
183  /* Or here. */
184  #endif /* COMPAT_43 */
185
186  #ifndef COMPAT_43
187  /* Yet another large region here, or other conditional code. */
188  #else /* COMPAT_43 */
189  /* Or here. */
190  #endif /* !COMPAT_43 */
191
192 Defines to Avoid Conditional Compilation
193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
195 In many cases in DPDK, one wants to run code based on
196 the target platform, or runtime environment.
197 While this can be done using the conditional compilation directives,
198 e.g. ``#ifdef RTE_EXEC_ENV_LINUX``, present in DPDK for many releases,
199 this can also be done in many cases using regular ``if`` statements
200 and the following defines:
201
202 * ``RTE_ENV_FREEBSD``, ``RTE_ENV_LINUX``, ``RTE_ENV_WINDOWS`` -
203   these define ids for each operating system environment.
204 * ``RTE_EXEC_ENV`` - this defines the id of the current environment,
205   i.e. one of the items in list above.
206 * ``RTE_EXEC_ENV_IS_FREEBSD``, ``RTE_EXEC_ENV_IS_LINUX``, ``RTE_EXEC_ENV_IS_WINDOWS`` -
207   0/1 values indicating if the current environment is that specified,
208   shortcuts for checking e.g. ``RTE_EXEC_ENV == RTE_ENV_WINDOWS``
209
210 Examples of use:
211
212 .. code-block:: c
213
214    /* report a unit tests as unsupported on Windows */
215    if (RTE_EXEC_ENV_IS_WINDOWS)
216        return TEST_SKIPPED;
217
218    /* set different default values depending on OS Environment */
219    switch (RTE_EXEC_ENV) {
220    case RTE_ENV_FREEBSD:
221        default = x;
222        break;
223    case RTE_ENV_LINUX:
224        default = y;
225        break;
226    case RTE_ENV_WINDOWS:
227        default = z;
228        break;
229    }
230
231
232 C Types
233 -------
234
235 Integers
236 ~~~~~~~~
237
238 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.
239
240 Enumerations
241 ~~~~~~~~~~~~
242
243 * Enumeration values are all uppercase.
244
245 .. code-block:: c
246
247  enum enumtype { ONE, TWO } et;
248
249 * Enum types should be used in preference to macros #defining a set of (sequential) values.
250 * 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.
251
252 Bitfields
253 ~~~~~~~~~
254
255 The developer should group bitfields that are included in the same integer, as follows:
256
257 .. code-block:: c
258
259  struct grehdr {
260    uint16_t rec:3,
261        srr:1,
262        seq:1,
263        key:1,
264        routing:1,
265        csum:1,
266        version:3,
267        reserved:4,
268        ack:1;
269  /* ... */
270  }
271
272 Variable Declarations
273 ~~~~~~~~~~~~~~~~~~~~~
274
275 In declarations, do not put any whitespace between asterisks and adjacent tokens, except for tokens that are identifiers related to types.
276 (These identifiers are the names of basic types, type qualifiers, and typedef-names other than the one being declared.)
277 Separate these identifiers from asterisks using a single space.
278
279 For example:
280
281 .. code-block:: c
282
283    int *x;         /* no space after asterisk */
284    int * const x;  /* space after asterisk when using a type qualifier */
285
286 * All externally-visible variables should have an ``rte_`` prefix in the name to avoid namespace collisions.
287 * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in variable names.
288   Lower-case letters and underscores only.
289
290 Structure Declarations
291 ~~~~~~~~~~~~~~~~~~~~~~
292
293 * In general, when declaring variables in new structures, declare them sorted by use, then by size (largest to smallest), and then in alphabetical order.
294   Sorting by use means that commonly used variables are used together and that the structure layout makes logical sense.
295   Ordering by size then ensures that as little padding is added to the structure as possible.
296 * For existing structures, additions to structures should be added to the end so for backward compatibility reasons.
297 * Each structure element gets its own line.
298 * Try to make the structure readable by aligning the member names using spaces as shown below.
299 * Names following extremely long types, which therefore cannot be easily aligned with the rest, should be separated by a single space.
300
301 .. code-block:: c
302
303  struct foo {
304          struct foo      *next;          /* List of active foo. */
305          struct mumble   amumble;        /* Comment for mumble. */
306          int             bar;            /* Try to align the comments. */
307          struct verylongtypename *baz;   /* Won't fit with other members */
308  };
309
310
311 * 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.
312 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
313 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
314
315 .. note::
316
317     Uses of ``bool`` in structures are not preferred as is wastes space and
318     it's also not clear as to what type size the bool is. A preferred use of
319     ``bool`` is mainly as a return type from functions that return true/false,
320     and maybe local variable functions.
321
322     Ref: `LKML <https://lkml.org/lkml/2017/11/21/384>`_
323
324 Queues
325 ~~~~~~
326
327 Use queue(3) macros rather than rolling your own lists, whenever possible.
328 Thus, the previous example would be better written:
329
330 .. code-block:: c
331
332  #include <sys/queue.h>
333
334  struct foo {
335          LIST_ENTRY(foo) link;      /* Use queue macros for foo lists. */
336          struct mumble   amumble;   /* Comment for mumble. */
337          int             bar;       /* Try to align the comments. */
338          struct verylongtypename *baz;   /* Won't fit with other members */
339  };
340  LIST_HEAD(, foo) foohead;          /* Head of global foo list. */
341
342
343 DPDK also provides an optimized way to store elements in lockless rings.
344 This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access.
345
346 Naming
347 ------
348
349 For symbol names and documentation, new usage of
350 'master / slave' (or 'slave' independent of 'master') and 'blacklist /
351 whitelist' is not allowed.
352
353 Recommended replacements for 'master / slave' are:
354     '{primary,main} / {secondary,replica,subordinate}'
355     '{initiator,requester} / {target,responder}'
356     '{controller,host} / {device,worker,proxy}'
357     'leader / follower'
358     'director / performer'
359
360 Recommended replacements for 'blacklist/whitelist' are:
361     'denylist / allowlist'
362     'blocklist / passlist'
363
364 Exceptions for introducing new usage is to maintain compatibility
365 with an existing (as of 2020) hardware or protocol
366 specification that mandates those terms.
367
368
369 Typedefs
370 ~~~~~~~~
371
372 Avoid using typedefs for structure types.
373
374 For example, use:
375
376 .. code-block:: c
377
378  struct my_struct_type {
379  /* ... */
380  };
381
382  struct my_struct_type my_var;
383
384
385 rather than:
386
387 .. code-block:: c
388
389  typedef struct my_struct_type {
390  /* ... */
391  } my_struct_type;
392
393  my_struct_type my_var
394
395
396 Typedefs are problematic because they do not properly hide their underlying type;
397 for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure.
398 In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary.
399 Typedefs are difficult to use in stand-alone header files.
400 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),
401 or there must be a back-door mechanism for obtaining the typedef.
402
403 Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement).
404 For example, ``#define pint int *`` does not work as expected, while ``typedef int *pint`` does work.
405 As stated when discussing macros, typedefs should be preferred to macros in cases like this.
406
407 When convention requires a typedef; make its name match the struct tag.
408 Avoid typedefs ending in ``_t``, except as specified in Standard C or by POSIX.
409
410 .. note::
411
412         It is recommended to use typedefs to define function pointer types, for reasons of code readability.
413         This is especially true when the function type is used as a parameter to another function.
414
415 For example:
416
417 .. code-block:: c
418
419         /**
420          * Definition of a remote launch function.
421          */
422         typedef int (lcore_function_t)(void *);
423
424         /* launch a function of lcore_function_t type */
425         int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned worker_id);
426
427
428 C Indentation
429 -------------
430
431 General
432 ~~~~~~~
433
434 * Indentation is a hard tab, that is, a tab character, not a sequence of spaces,
435
436 .. note::
437
438         Global whitespace rule in DPDK, use tabs for indentation, spaces for alignment.
439
440 * Do not put any spaces before a tab for indentation.
441 * If you have to wrap a long statement, put the operator at the end of the line, and indent again.
442 * For control statements (if, while, etc.), continuation it is recommended that the next line be indented by two tabs, rather than one,
443   to prevent confusion as to whether the second line of the control statement forms part of the statement body or not.
444   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.
445
446 .. note::
447
448         As with all style guidelines, code should match style already in use in an existing file.
449
450 .. code-block:: c
451
452  while (really_long_variable_name_1 == really_long_variable_name_2 &&
453      var3 == var4){  /* confusing to read as */
454      x = y + z;      /* control stmt body lines up with second line of */
455      a = b + c;      /* control statement itself if single indent used */
456  }
457
458  if (really_long_variable_name_1 == really_long_variable_name_2 &&
459          var3 == var4){  /* two tabs used */
460      x = y + z;          /* statement body no longer lines up */
461      a = b + c;
462  }
463
464  z = a + really + long + statement + that + needs +
465          two + lines + gets + indented + on + the +
466          second + and + subsequent + lines;
467
468
469 * Do not add whitespace at the end of a line.
470
471 * Do not add whitespace or a blank line at the end of a file.
472
473
474 Control Statements and Loops
475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
476
477 * Include a space after keywords (if, while, for, return, switch).
478 * 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.
479
480 .. code-block:: c
481
482  for (p = buf; *p != '\0'; ++p)
483          ;       /* nothing */
484  for (;;)
485          stmt;
486  for (;;) {
487          z = a + really + long + statement + that + needs +
488                  two + lines + gets + indented + on + the +
489                  second + and + subsequent + lines;
490  }
491  for (;;) {
492          if (cond)
493                  stmt;
494  }
495  if (val != NULL)
496          val = realloc(val, newsize);
497
498
499 * Parts of a for loop may be left empty.
500
501 .. code-block:: c
502
503  for (; cnt < 15; cnt++) {
504          stmt1;
505          stmt2;
506  }
507
508 * Closing and opening braces go on the same line as the else keyword.
509 * Braces that are not necessary should be left out.
510
511 .. code-block:: c
512
513  if (test)
514          stmt;
515  else if (bar) {
516          stmt;
517          stmt;
518  } else
519          stmt;
520
521
522 Function Calls
523 ~~~~~~~~~~~~~~
524
525 * Do not use spaces after function names.
526 * Commas should have a space after them.
527 * No spaces after ``(`` or ``[`` or preceding the ``]`` or ``)`` characters.
528
529 .. code-block:: c
530
531         error = function(a1, a2);
532         if (error != 0)
533                 exit(error);
534
535
536 Operators
537 ~~~~~~~~~
538
539 * Unary operators do not require spaces, binary operators do.
540 * Do not use parentheses unless they are required for precedence or unless the statement is confusing without them.
541   However, remember that other people may be more easily confused than you.
542
543 Exit
544 ~~~~
545
546 Exits should be 0 on success, or 1 on failure.
547
548 .. code-block:: c
549
550          exit(0);        /*
551                           * Avoid obvious comments such as
552                           * "Exit 0 on success."
553                           */
554  }
555
556 Local Variables
557 ~~~~~~~~~~~~~~~
558
559 * Variables should be declared at the start of a block of code rather than in the middle.
560   The exception to this is when the variable is ``const`` in which case the declaration must be at the point of first use/assignment.
561 * When declaring variables in functions, multiple variables per line are OK.
562   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.
563 * Be careful to not obfuscate the code by initializing variables in the declarations, only the last variable on a line should be initialized.
564   If multiple variables are to be initialized when defined, put one per line.
565 * Do not use function calls in initializers, except for ``const`` variables.
566
567 .. code-block:: c
568
569  int i = 0, j = 0, k = 0;  /* bad, too many initializer */
570
571  char a = 0;        /* OK, one variable per line with initializer */
572  char b = 0;
573
574  float x, y = 0.0;  /* OK, only last variable has initializer */
575
576
577 Casts and sizeof
578 ~~~~~~~~~~~~~~~~
579
580 * Casts and sizeof statements are not followed by a space.
581 * Always write sizeof statements with parenthesis.
582   The redundant parenthesis rules do not apply to sizeof(var) instances.
583
584 C Function Definition, Declaration and Use
585 -------------------------------------------
586
587 Prototypes
588 ~~~~~~~~~~
589
590 * It is recommended (and generally required by the compiler) that all non-static functions are prototyped somewhere.
591 * Functions local to one source module should be declared static, and should not be prototyped unless absolutely necessary.
592 * Functions used from other parts of code (external API) must be prototyped in the relevant include file.
593 * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering.
594 * Functions that are used locally in more than one module go into a separate header file, for example, "extern.h".
595 * Do not use the ``__P`` macro.
596 * Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See :ref:`doxygen_guidelines` for details.
597 * Functions that are part of the external API must have an ``rte_`` prefix on the function name.
598 * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in function names. Lower-case letters and underscores only.
599 * When prototyping functions, associate names with parameter types, for example:
600
601 .. code-block:: c
602
603  void function1(int fd); /* good */
604  void function2(int);    /* bad */
605
606 * Short function prototypes should be contained on a single line.
607   Longer prototypes, e.g. those with many parameters, can be split across multiple lines.
608   The second and subsequent lines should be further indented as for line statement continuations as described in the previous section.
609
610 .. code-block:: c
611
612  static char *function1(int _arg, const char *_arg2,
613         struct foo *_arg3,
614         struct bar *_arg4,
615         struct baz *_arg5);
616  static void usage(void);
617
618 .. note::
619
620         Unlike function definitions, the function prototypes do not need to place the function return type on a separate line.
621
622 Definitions
623 ~~~~~~~~~~~
624
625 * The function type should be on a line by itself preceding the function.
626 * The opening brace of the function body should be on a line by itself.
627
628 .. code-block:: c
629
630  static char *
631  function(int a1, int a2, float fl, int a4)
632  {
633
634
635 * Do not declare functions inside other functions.
636   ANSI C states that such declarations have file scope regardless of the nesting of the declaration.
637   Hiding file declarations in what appears to be a local scope is undesirable and will elicit complaints from a good compiler.
638 * Old-style (K&R) function declaration should not be used, use ANSI function declarations instead as shown below.
639 * Long argument lists should be wrapped as described above in the function prototypes section.
640
641 .. code-block:: c
642
643  /*
644   * All major routines should have a comment briefly describing what
645   * they do. The comment before the "main" routine should describe
646   * what the program does.
647   */
648  int
649  main(int argc, char *argv[])
650  {
651          char *ep;
652          long num;
653          int ch;
654
655 C Statement Style and Conventions
656 ---------------------------------
657
658 NULL Pointers
659 ~~~~~~~~~~~~~
660
661 * NULL is the preferred null pointer constant.
662   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.
663 * Test pointers against NULL, for example, use:
664
665 .. code-block:: c
666
667  if (p == NULL) /* Good, compare pointer to NULL */
668
669  if (!p) /* Bad, using ! on pointer */
670
671
672 * Do not use ! for tests unless it is a boolean, for example, use:
673
674 .. code-block:: c
675
676         if (*p == '\0') /* check character against (char)0 */
677
678 Return Value
679 ~~~~~~~~~~~~
680
681 * Functions which create objects, or allocate memory, should return pointer types, and NULL on error.
682   The error type should be indicated by setting the variable ``rte_errno`` appropriately.
683 * Functions which work on bursts of packets, such as RX-like or TX-like functions, should return the number of packets handled.
684 * Other functions returning int should generally behave like system calls:
685   returning 0 on success and -1 on error, setting ``rte_errno`` to indicate the specific type of error.
686 * 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``.
687   Note, however, to allow consistency across functions returning integer or pointer types, the previous approach is preferred for any new libraries.
688 * For functions where no error is possible, the function type should be ``void`` not ``int``.
689 * Routines returning ``void *`` should not have their return values cast to any pointer type.
690   (Typecasting can prevent the compiler from warning about missing prototypes as any implicit definition of a function returns int,
691   which, unlike ``void *``, needs a typecast to assign to a pointer variable.)
692
693 .. note::
694
695         The above rule about not typecasting ``void *`` applies to malloc, as well as to DPDK functions.
696
697 * Values in return statements should not be enclosed in parentheses.
698
699 Logging and Errors
700 ~~~~~~~~~~~~~~~~~~
701
702 In the DPDK environment, use the logging interface provided:
703
704 .. code-block:: c
705
706  /* register log types for this application */
707  int my_logtype1 = rte_log_register("myapp.log1");
708  int my_logtype2 = rte_log_register("myapp.log2");
709
710  /* set global log level to INFO */
711  rte_log_set_global_level(RTE_LOG_INFO);
712
713  /* only display messages higher than NOTICE for log2 (default
714   * is DEBUG) */
715  rte_log_set_level(my_logtype2, RTE_LOG_NOTICE);
716
717  /* enable all PMD logs (whose identifier string starts with "pmd.") */
718  rte_log_set_level_pattern("pmd.*", RTE_LOG_DEBUG);
719
720  /* log in debug level */
721  rte_log_set_global_level(RTE_LOG_DEBUG);
722  RTE_LOG(DEBUG, my_logtype1, "this is a debug level message\n");
723  RTE_LOG(INFO, my_logtype1, "this is a info level message\n");
724  RTE_LOG(WARNING, my_logtype1, "this is a warning level message\n");
725  RTE_LOG(WARNING, my_logtype2, "this is a debug level message (not displayed)\n");
726
727  /* log in info level */
728  rte_log_set_global_level(RTE_LOG_INFO);
729  RTE_LOG(DEBUG, my_logtype1, "debug level message (not displayed)\n");
730
731 Branch Prediction
732 ~~~~~~~~~~~~~~~~~
733
734 * 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.
735   They are expanded as a compiler builtin and allow the developer to indicate if the branch is likely to be taken or not. Example:
736
737 .. code-block:: c
738
739  #include <rte_branch_prediction.h>
740  if (likely(x > 1))
741    do_stuff();
742
743 .. note::
744
745         The use of ``likely()`` and ``unlikely()`` should only be done in performance critical paths,
746         and only when there is a clearly preferred path, or a measured performance increase gained from doing so.
747         These macros should be avoided in non-performance-critical code.
748
749 Static Variables and Functions
750 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751
752 * 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).
753 * Functions that should be inlined should to be declared as ``static inline`` and can be defined in a .c or a .h file.
754
755 .. note::
756         Static functions defined in a header file must be declared as ``static inline`` in order to prevent compiler warnings about the function being unused.
757
758 Const Attribute
759 ~~~~~~~~~~~~~~~
760
761 The ``const`` attribute should be used as often as possible when a variable is read-only.
762
763 Inline ASM in C code
764 ~~~~~~~~~~~~~~~~~~~~
765
766 The ``asm`` and ``volatile`` keywords do not have underscores. The AT&T syntax should be used.
767 Input and output operands should be named to avoid confusion, as shown in the following example:
768
769 .. code-block:: c
770
771         asm volatile("outb %[val], %[port]"
772                 : :
773                 [port] "dN" (port),
774                 [val] "a" (val));
775
776 Control Statements
777 ~~~~~~~~~~~~~~~~~~
778
779 * Forever loops are done with for statements, not while statements.
780 * Elements in a switch statement that cascade should have a FALLTHROUGH comment. For example:
781
782 .. code-block:: c
783
784          switch (ch) {         /* Indent the switch. */
785          case 'a':             /* Don't indent the case. */
786                  aflag = 1;    /* Indent case body one tab. */
787                  /* FALLTHROUGH */
788          case 'b':
789                  bflag = 1;
790                  break;
791          case '?':
792          default:
793                  usage();
794                  /* NOTREACHED */
795          }
796
797 Dynamic Logging
798 ---------------
799
800 DPDK provides infrastructure to perform logging during runtime. This is very
801 useful for enabling debug output without recompilation. To enable or disable
802 logging of a particular topic, the ``--log-level`` parameter can be provided
803 to EAL, which will change the log level. DPDK code can register topics,
804 which allows the user to adjust the log verbosity for that specific topic.
805
806 In general, the naming scheme is as follows: ``type.section.name``
807
808  * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user``
809    are the common options.
810  * Section refers to a specific area, for example a poll-mode-driver for an
811    ethernet device would use ``pmd.net``, while an eventdev PMD uses
812    ``pmd.event``.
813  * The name identifies the individual item that the log applies to.
814    The name section must align with
815    the directory that the PMD code resides. See examples below for clarity.
816
817 Examples:
818
819  * The virtio network PMD in ``drivers/net/virtio`` uses ``pmd.net.virtio``
820  * The eventdev software poll mode driver in ``drivers/event/sw`` uses ``pmd.event.sw``
821  * The octeontx mempool driver in ``drivers/mempool/octeontx`` uses ``pmd.mempool.octeontx``
822  * The DPDK hash library in ``lib/hash`` uses ``lib.hash``
823
824 Specializations
825 ~~~~~~~~~~~~~~~
826
827 In addition to the above logging topic, any PMD or library can further split
828 logging output by using "specializations". A specialization could be the
829 difference between initialization code, and logs of events that occur at runtime.
830
831 An example could be the initialization log messages getting one
832 specialization, while another specialization handles mailbox command logging.
833 Each PMD, library or component can create as many specializations as required.
834
835 A specialization looks like this:
836
837  * Initialization output: ``type.section.name.init``
838  * PF/VF mailbox output: ``type.section.name.mbox``
839
840 A real world example is the i40e poll mode driver which exposes two
841 specializations, one for initialization ``pmd.net.i40e.init`` and the other for
842 the remaining driver logs ``pmd.net.i40e.driver``.
843
844 Note that specializations have no formatting rules, but please follow
845 a precedent if one exists. In order to see all current log topics and
846 specializations, run the ``app/test`` binary, and use the ``dump_log_types``
847
848 Python Code
849 -----------
850
851 All Python code should be compliant with
852 `PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_.
853
854 The ``pep8`` tool can be used for testing compliance with the guidelines.
855
856 Integrating with the Build System
857 ---------------------------------
858
859 DPDK is built using the tools ``meson`` and ``ninja``.
860
861 .. note::
862
863    In order to catch possible issues as soon as possible,
864    it is recommended that developers build DPDK in "developer mode" to enable additional checks.
865    By default, this mode is enabled if the build is being done from a git checkout,
866    but the mode can be manually enabled/disabled using the
867    ``developer_mode`` meson configuration option.
868
869 Therefore all new component additions should include a ``meson.build`` file,
870 and should be added to the component lists in the ``meson.build`` files in the
871 relevant top-level directory:
872 either ``lib`` directory or a ``driver`` subdirectory.
873
874 Meson Build File Contents - Libraries
875 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
876
877 The ``meson.build`` file for a new DPDK library should be of the following basic
878 format.
879
880 .. code-block:: python
881
882         sources = files('file1.c', ...)
883         headers = files('file1.h', ...)
884
885
886 This will build based on a number of conventions and assumptions within the DPDK
887 itself, for example, that the library name is the same as the directory name in
888 which the files are stored.
889
890 For a library ``meson.build`` file, there are number of variables which can be
891 set, some mandatory, others optional. The mandatory fields are:
892
893 sources
894         **Default Value = []**.
895         This variable should list out the files to be compiled up to create the
896         library. Files must be specified using the meson ``files()`` function.
897
898
899 The optional fields are:
900
901 build
902         **Default Value = true**
903         Used to optionally compile a library, based on its dependencies or
904         environment. When set to "false" the ``reason`` value, explained below, should
905         also be set to explain to the user why the component is not being built.
906         A simple example of use would be:
907
908 .. code-block:: python
909
910         if not is_linux
911                 build = false
912                 reason = 'only supported on Linux'
913         endif
914
915
916 cflags
917         **Default Value = [<-march/-mcpu flags>]**.
918         Used to specify any additional cflags that need to be passed to compile
919         the sources in the library.
920
921 deps
922         **Default Value = ['eal']**.
923         Used to list the internal library dependencies of the library. It should
924         be assigned to using ``+=`` rather than overwriting using ``=``.  The
925         dependencies should be specified as strings, each one giving the name of
926         a DPDK library, without the ``librte_`` prefix. Dependencies are handled
927         recursively, so specifying e.g. ``mempool``, will automatically also
928         make the library depend upon the mempool library's dependencies too -
929         ``ring`` and ``eal``. For libraries that only depend upon EAL, this
930         variable may be omitted from the ``meson.build`` file.  For example:
931
932 .. code-block:: python
933
934         deps += ['ethdev']
935
936
937 ext_deps
938         **Default Value = []**.
939         Used to specify external dependencies of this library. They should be
940         returned as dependency objects, as returned from the meson
941         ``dependency()`` or ``find_library()`` functions. Before returning
942         these, they should be checked to ensure the dependencies have been
943         found, and, if not, the ``build`` variable should be set to ``false``.
944         For example:
945
946 .. code-block:: python
947
948         my_dep = dependency('libX', required: 'false')
949         if my_dep.found()
950                 ext_deps += my_dep
951         else
952                 build = false
953         endif
954
955
956 headers
957         **Default Value = []**.
958         Used to return the list of header files for the library that should be
959         installed to $PREFIX/include when ``ninja install`` is run. As with
960         source files, these should be specified using the meson ``files()``
961         function.
962         When ``check_includes`` build option is set to ``true``, each header file
963         has additional checks performed on it, for example to ensure that it is
964         not missing any include statements for dependent headers.
965         For header files which are public, but only included indirectly in
966         applications, these checks can be skipped by using the ``indirect_headers``
967         variable rather than ``headers``.
968
969 indirect_headers
970         **Default Value = []**.
971         As with ``headers`` option above, except that the files are not checked
972         for all needed include files as part of a DPDK build when
973         ``check_includes`` is set to ``true``.
974
975 includes:
976         **Default Value = []**.
977         Used to indicate any additional header file paths which should be
978         added to the header search path for other libs depending on this
979         library. EAL uses this so that other libraries building against it
980         can find the headers in subdirectories of the main EAL directory. The
981         base directory of each library is always given in the include path,
982         it does not need to be specified here.
983
984 name
985         **Default Value = library name derived from the directory name**.
986         If a library's .so or .a file differs from that given in the directory
987         name, the name should be specified using this variable. In practice,
988         since the convention is that for a library called ``librte_xyz.so``, the
989         sources are stored in a directory ``lib/xyz``, this value should
990         never be needed for new libraries.
991
992 .. note::
993
994         The name value also provides the name used to find the function version
995         map file, as part of the build process, so if the directory name and
996         library names differ, the ``version.map`` file should be named
997         consistently with the library, not the directory
998
999 objs
1000         **Default Value = []**.
1001         This variable can be used to pass to the library build some pre-built
1002         objects that were compiled up as part of another target given in the
1003         included library ``meson.build`` file.
1004
1005 reason
1006         **Default Value = '<unknown reason>'**.
1007         This variable should be used when a library is not to be built i.e. when
1008         ``build`` is set to "false", to specify the reason why a library will not be
1009         built. For missing dependencies this should be of the form
1010         ``'missing dependency, "libname"'``.
1011
1012 use_function_versioning
1013         **Default Value = false**.
1014         Specifies if the library in question has ABI versioned functions. If it
1015         has, this value should be set to ensure that the C files are compiled
1016         twice with suitable parameters for each of shared or static library
1017         builds.
1018
1019 Meson Build File Contents - Drivers
1020 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1021
1022 For drivers, the values are largely the same as for libraries. The variables
1023 supported are:
1024
1025 build
1026         As above.
1027
1028 cflags
1029         As above.
1030
1031 deps
1032         As above.
1033
1034 ext_deps
1035         As above.
1036
1037 includes
1038         **Default Value = <driver directory>** Some drivers include a base
1039         directory for additional source files and headers, so we have this
1040         variable to allow the headers from that base directory to be found when
1041         compiling driver sources. Should be appended to using ``+=`` rather than
1042         overwritten using ``=``.  The values appended should be meson include
1043         objects got using the ``include_directories()`` function. For example:
1044
1045 .. code-block:: python
1046
1047         includes += include_directories('base')
1048
1049 name
1050         As above, though note that each driver class can define it's own naming
1051         scheme for the resulting ``.so`` files.
1052
1053 objs
1054         As above, generally used for the contents of the ``base`` directory.
1055
1056 pkgconfig_extra_libs
1057         **Default Value = []**
1058         This variable is used to pass additional library link flags through to
1059         the DPDK pkgconfig file generated, for example, to track any additional
1060         libraries that may need to be linked into the build - especially when
1061         using static libraries. Anything added here will be appended to the end
1062         of the ``pkgconfig --libs`` output.
1063
1064 reason
1065         As above.
1066
1067 sources [mandatory]
1068         As above
1069
1070 headers
1071         As above
1072
1073 version
1074         As above
1075
1076
1077 Meson Coding Style
1078 ------------------
1079
1080 The following guidelines apply to the build system code in meson.build files in DPDK.
1081
1082 * Indentation should be using 4 spaces, no hard tabs.
1083
1084 * Line continuations should be doubly-indented to ensure visible difference from normal indentation.
1085   Any line continuations beyond the first may be singly indented to avoid large amounts of indentation.
1086
1087 * Where a line is split in the middle of a statement, e.g. a multiline `if` statement,
1088   brackets should be used in preference to escaping the line break.
1089
1090 Example::
1091
1092     if (condition1 and condition2            # line breaks inside () need no escaping
1093             and condition3 and condition4)
1094         x = y
1095     endif
1096
1097 * Lists of files or components must be alphabetical unless doing so would cause errors.
1098
1099 * Two formats are supported for lists of files or list of components:
1100
1101    * For a small number of list entries, generally 3 or fewer, all elements may be put on a single line.
1102      In this case, the opening and closing braces of the list must be on the same line as the list items.
1103      No trailing comma is put on the final list entry.
1104    * For lists with more than 3 items,
1105      it is recommended that the lists be put in the files with a *single* entry per line.
1106      In this case, the opening brace, or ``files`` function call must be on a line on its own,
1107      and the closing brace must similarly be on a line on its own at the end.
1108      To help with readability of nested sublists, the closing brace should be dedented to appear
1109      at the same level as the opening braced statement.
1110      The final list entry must have a trailing comma,
1111      so that adding a new entry to the list never modifies any other line in the list.
1112
1113 Examples::
1114
1115     sources = files('file1.c', 'file2.c')
1116
1117     subdirs = ['dir1', 'dir2']
1118
1119     headers = files(
1120             'header1.c',
1121             'header2.c',
1122             'header3.c',   # always include trailing comma
1123     )                      # closing brace at indent level of opening brace
1124
1125     components = [
1126             'comp1',
1127             'comp2',
1128             ...
1129             'compN',
1130     ]