This document specifies the preferred style for source files in the DPDK source tree. 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.
The rules and guidelines given in this document cannot cover every situation, so the following general guidelines should be used as a fallback:
Line length is recommended to be not more than 80 characters, including comments. [Tab stop size should be assumed to be 8-characters wide].
Note
The above is recommendation, and not a hard limit. However, it is expected that the recommendations should be followed in all but the rarest situations.
These comments should be used in normal cases. To document a public API, a doxygen-like format must be used: refer to Doxygen Guidelines.
/*
* VERY important single-line comments look like this.
*/
/* Most single-line comments look like this. */
/*
* Multi-line comments look like this. Make them real sentences. Fill
* them so they look like real paragraphs.
*/
Each file should begin with a special comment containing the appropriate copyright and license for the file. Generally this is the BSD License, except for code for Linux Kernel modules. After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file.
In DPDK sources, the include files should be ordered as following:
Include files from the local application directory are included using quotes, while includes from other paths are included using angle brackets: “<>”.
Example:
#include <stdio.h>
#include <stdlib.h>
#include <rte_eal.h>
#include <rte_ring.h>
#include <rte_mempool.h>
#include "application.h"
Headers should be protected against multiple inclusion with the usual:
#ifndef _FILE_H_
#define _FILE_H_
/* Code */
#endif /* _FILE_H_ */
Do not #define or declare names except with the standard DPDK prefix: RTE_. This is to ensure there are no collisions with definitions in the application itself.
The names of “unsafe” macros (ones that have side effects), and the names of macros for manifest constants, are all in uppercase.
The expansions of expression-like macros are either a single token or have outer parentheses. 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. If the macro encapsulates a compound statement, enclose it in a do-while loop, so that it can be used safely in if statements. 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.
For example:
#define MACRO(x, y) do { \
variable = (x) + (y); \
(y) += 2; \
} while(0)
Note
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.
#ifdef KTRACE
#include <sys/ktrace.h>
#endif
#ifdef COMPAT_43
/* A large region here, or other conditional code. */
#else /* !COMPAT_43 */
/* Or here. */
#endif /* COMPAT_43 */
#ifndef COMPAT_43
/* Yet another large region here, or other conditional code. */
#else /* COMPAT_43 */
/* Or here. */
#endif /* !COMPAT_43 */
Note
Conditional compilation should be used only when absolutely necessary, as it increases the number of target binaries that need to be built and tested.
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.
enum enumtype { ONE, TWO } et;
The developer should group bitfields that are included in the same integer, as follows:
struct grehdr {
uint16_t rec:3,
srr:1,
seq:1,
key:1,
routing:1,
csum:1,
version:3,
reserved:4,
ack:1;
/* ... */
}
In declarations, do not put any whitespace between asterisks and adjacent tokens, except for tokens that are identifiers related to types. (These identifiers are the names of basic types, type qualifiers, and typedef-names other than the one being declared.) Separate these identifiers from asterisks using a single space.
For example:
int *x; /* no space after asterisk */
int * const x; /* space after asterisk when using a type qualifier */
struct foo {
struct foo *next; /* List of active foo. */
struct mumble amumble; /* Comment for mumble. */
int bar; /* Try to align the comments. */
struct verylongtypename *baz; /* Won't fit with other members */
};
Note
Uses of bool in structures are not preferred as is wastes space and it’s also not clear as to what type size the bool is. A preferred use of bool is mainly as a return type from functions that return true/false, and maybe local variable functions.
Ref: LKML
Use queue(3) macros rather than rolling your own lists, whenever possible. Thus, the previous example would be better written:
#include <sys/queue.h>
struct foo {
LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
struct mumble amumble; /* Comment for mumble. */
int bar; /* Try to align the comments. */
struct verylongtypename *baz; /* Won't fit with other members */
};
LIST_HEAD(, foo) foohead; /* Head of global foo list. */
DPDK also provides an optimized way to store elements in lockless rings. This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access.
Avoid using typedefs for structure types.
For example, use:
struct my_struct_type {
/* ... */
};
struct my_struct_type my_var;
rather than:
typedef struct my_struct_type {
/* ... */
} my_struct_type;
my_struct_type my_var
Typedefs are problematic because they do not properly hide their underlying type; for example, you need to know if the typedef is the structure itself, as shown above, or a pointer to the structure. In addition, they must be declared exactly once, whereas an incomplete structure type can be mentioned as many times as necessary. Typedefs are difficult to use in stand-alone header files. 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), or there must be a back-door mechanism for obtaining the typedef.
Note that #defines used instead of typedefs also are problematic (since they do not propagate the pointer type correctly due to direct text replacement). For example, #define pint int * does not work as expected, while typedef int *pint does work. As stated when discussing macros, typedefs should be preferred to macros in cases like this.
When convention requires a typedef; make its name match the struct tag. Avoid typedefs ending in _t, except as specified in Standard C or by POSIX.
Note
It is recommended to use typedefs to define function pointer types, for reasons of code readability. This is especially true when the function type is used as a parameter to another function.
For example:
/**
* Definition of a remote launch function.
*/
typedef int (lcore_function_t)(void *);
/* launch a function of lcore_function_t type */
int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id);
Note
Global whitespace rule in DPDK, use tabs for indentation, spaces for alignment.
Note
As with all style guidelines, code should match style already in use in an existing file.
while (really_long_variable_name_1 == really_long_variable_name_2 &&
var3 == var4){ /* confusing to read as */
x = y + z; /* control stmt body lines up with second line of */
a = b + c; /* control statement itself if single indent used */
}
if (really_long_variable_name_1 == really_long_variable_name_2 &&
var3 == var4){ /* two tabs used */
x = y + z; /* statement body no longer lines up */
a = b + c;
}
z = a + really + long + statement + that + needs +
two + lines + gets + indented + on + the +
second + and + subsequent + lines;
for (p = buf; *p != '\0'; ++p)
; /* nothing */
for (;;)
stmt;
for (;;) {
z = a + really + long + statement + that + needs +
two + lines + gets + indented + on + the +
second + and + subsequent + lines;
}
for (;;) {
if (cond)
stmt;
}
if (val != NULL)
val = realloc(val, newsize);
for (; cnt < 15; cnt++) {
stmt1;
stmt2;
}
if (test)
stmt;
else if (bar) {
stmt;
stmt;
} else
stmt;
error = function(a1, a2);
if (error != 0)
exit(error);
Exits should be 0 on success, or 1 on failure.
exit(0); /*
* Avoid obvious comments such as
* "Exit 0 on success."
*/
}
int i = 0, j = 0, k = 0; /* bad, too many initializer */
char a = 0; /* OK, one variable per line with initializer */
char b = 0;
float x, y = 0.0; /* OK, only last variable has initializer */
void function1(int fd); /* good */
void function2(int); /* bad */
static char *function1(int _arg, const char *_arg2,
struct foo *_arg3,
struct bar *_arg4,
struct baz *_arg5);
static void usage(void);
Note
Unlike function definitions, the function prototypes do not need to place the function return type on a separate line.
static char *
function(int a1, int a2, float fl, int a4)
{
/*
* All major routines should have a comment briefly describing what
* they do. The comment before the "main" routine should describe
* what the program does.
*/
int
main(int argc, char *argv[])
{
char *ep;
long num;
int ch;
if (p == NULL) /* Good, compare pointer to NULL */
if (!p) /* Bad, using ! on pointer */
if (*p == '\0') /* check character against (char)0 */
Note
The above rule about not typecasting void * applies to malloc, as well as to DPDK functions.
In the DPDK environment, use the logging interface provided:
/* register log types for this application */
int my_logtype1 = rte_log_register("myapp.log1");
int my_logtype2 = rte_log_register("myapp.log2");
/* set global log level to INFO */
rte_log_set_global_level(RTE_LOG_INFO);
/* only display messages higher than NOTICE for log2 (default
* is DEBUG) */
rte_log_set_level(my_logtype2, RTE_LOG_NOTICE);
/* enable all PMD logs (whose identifier string starts with "pmd.") */
rte_log_set_level_pattern("pmd.*", RTE_LOG_DEBUG);
/* log in debug level */
rte_log_set_global_level(RTE_LOG_DEBUG);
RTE_LOG(DEBUG, my_logtype1, "this is is a debug level message\n");
RTE_LOG(INFO, my_logtype1, "this is is a info level message\n");
RTE_LOG(WARNING, my_logtype1, "this is is a warning level message\n");
RTE_LOG(WARNING, my_logtype2, "this is is a debug level message (not displayed)\n");
/* log in info level */
rte_log_set_global_level(RTE_LOG_INFO);
RTE_LOG(DEBUG, my_logtype1, "debug level message (not displayed)\n");
#include <rte_branch_prediction.h>
if (likely(x > 1))
do_stuff();
Note
The use of likely() and unlikely() should only be done in performance critical paths, and only when there is a clearly preferred path, or a measured performance increase gained from doing so. These macros should be avoided in non-performance-critical code.
Note
Static functions defined in a header file must be declared as static inline in order to prevent compiler warnings about the function being unused.
The const attribute should be used as often as possible when a variable is read-only.
The asm and volatile keywords do not have underscores. The AT&T syntax should be used. Input and output operands should be named to avoid confusion, as shown in the following example:
asm volatile("outb %[val], %[port]"
: :
[port] "dN" (port),
[val] "a" (val));
switch (ch) { /* Indent the switch. */
case 'a': /* Don't indent the case. */
aflag = 1; /* Indent case body one tab. */
/* FALLTHROUGH */
case 'b':
bflag = 1;
break;
case '?':
default:
usage();
/* NOTREACHED */
}
DPDK provides infrastructure to perform logging during runtime. This is very useful for enabling debug output without recompilation. To enable or disable logging of a particular topic, the --log-level parameter can be provided to EAL, which will change the log level. DPDK code can register topics, which allows the user to adjust the log verbosity for that specific topic.
In general, the naming scheme is as follows: type.section.name
- Type is the type of component, where lib, pmd, bus and user are the common options.
- Section refers to a specific area, for example a poll-mode-driver for an ethernet device would use pmd.net, while an eventdev PMD uses pmd.event.
- The name identifies the individual item that the log applies to. The name section must align with the directory that the PMD code resides. See examples below for clarity.
Examples:
- The virtio network PMD in drivers/net/virtio uses pmd.net.virtio
- The eventdev software poll mode driver in drivers/event/sw uses pmd.event.sw
- The octeontx mempool driver in drivers/mempool/octeontx uses pmd.mempool.octeontx
- The DPDK hash library in lib/librte_hash uses lib.hash
In addition to the above logging topic, any PMD or library can further split logging output by using “specializations”. A specialization could be the difference between initialization code, and logs of events that occur at runtime.
An example could be the initialization log messages getting one specialization, while another specialization handles mailbox command logging. Each PMD, library or component can create as many specializations as required.
A specialization looks like this:
- Initialization output: type.section.name.init
- PF/VF mailbox output: type.section.name.mbox
A real world example is the i40e poll mode driver which exposes two specializations, one for initialization pmd.net.i40e.init and the other for the remaining driver logs pmd.net.i40e.driver.
Note that specializations have no formatting rules, but please follow a precedent if one exists. In order to see all current log topics and specializations, run the app/test binary, and use the dump_log_types
All Python code should work with Python 2.7+ and 3.2+ and be compliant with PEP8 (Style Guide for Python Code).
The pep8 tool can be used for testing compliance with the guidelines.
DPDK supports being built in two different ways:
Any new library or driver to be integrated into DPDK should support being built with both systems. While building using make is a legacy approach, and most build-system enhancements are being done using meson and ninja there are no plans at this time to deprecate the legacy make build system.
Therefore all new component additions should include both a Makefile and a meson.build file, and should be added to the component lists in both the Makefile and meson.build files in the relevant top-level directory: either lib directory or a driver subdirectory.
The Makefile for the component should be of the following format, where <name> corresponds to the name of the library in question, e.g. hash, lpm, etc. For drivers, the same format of Makefile is used.
# pull in basic DPDK definitions, including whether library is to be
# built or not
include $(RTE_SDK)/mk/rte.vars.mk
# library name
LIB = librte_<name>.a
# any library cflags needed. Generally add "-O3 $(WERROR_FLAGS)"
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
# the symbol version information for the library, and .so version
EXPORT_MAP := rte_<name>_version.map
LIBABIVER := 1
# all source filenames are stored in SRCS-y
SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
# install includes
SYMLINK-$(CONFIG_RTE_LIBRTE_<NAME>)-include += rte_<name>.h
# pull in rules to build the library
include $(RTE_SDK)/mk/rte.lib.mk
The meson.build file for a new DPDK library should be of the following basic format.
sources = files('file1.c', ...)
headers = files('file1.c', ...)
The will build based on a number of conventions and assumptions within the DPDK itself, for example, that the library name is the same as the directory name in which the files are stored.
For a library meson.build file, there are number of variables which can be set, some mandatory, others optional. The mandatory fields are:
The optional fields are:
if host_machine.system() != 'linux'
build = false
endif
deps += ['ethdev']
my_dep = dependency('libX', required: 'false')
if my_dep.found()
ext_deps += my_dep
else
build = false
endif
Note
The name value also provides the name used to find the function version map file, as part of the build process, so if the directory name and library names differ, the version.map file should be named consistently with the library, not the directory
For drivers, the values are largely the same as for libraries. The variables supported are:
includes += include_directories('base')