Keep calm and Write something

출처 : DPDK mailing list

Coding Style

Description

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.

General Guidelines

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.

C Comment Style

Usual Comments

These comments should be used in normal cases. To document a public API, a doxygen-like format must be used: refer to Doxygen Documentation.

/*
 * 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.
 */

License Header

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.

C Preprocessor Directives

Header Includes

In DPDK sources, the include files should be ordered as following:

  1. libc includes (system includes first)
  2. DPDK EAL includes
  3. DPDK misc libraries includes
  4. application-specific includes

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"

Header File Guards

Headers should be protected against multiple inclusion with the usual:

#ifndef _FILE_H_
#define _FILE_H_

/* Code */

#endif /* _FILE_H_ */

Macros

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.

Conditional Compilation

When code is conditionally compiled using #ifdef or #if, a comment may be added following the matching #endif or #else to permit the reader to easily discern where conditionally compiled code regions end. 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. 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. The comment should be separated from the #endif or #else by a single space. For short conditionally compiled regions, a closing comment should not be used. The comment for #endif should match the expression used in the corresponding #if or #ifdef. The comment for #else and #elif should match the inverse of the expression(s) used in the preceding #if and/or #elif statements. In the comments, the subexpression defined(FOO) is abbreviated as “FOO”. For the purposes of comments, #ifndef FOO is treated as #if !defined(FOO).

#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.

C Types

Integers

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.

Enumerations

enum enumtype { ONE, TWO } et;

Bitfields

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;
/* ... */
}

Variable Declarations

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 */

Structure Declarations

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 */
};

Queues

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.

Typedefs

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);

C Indentation

General

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;

Control Statements and Loops

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;

Function Calls

error = function(a1, a2);
if (error != 0)
    exit(error);

Operators

Exit

Exits should be 0 on success, or 1 on failure.

exit(0);        /*
                 * Avoid obvious comments such as
                 * "Exit 0 on success."
                 */

}

Local Variables

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 */

Casts and sizeof

C Function Definition, Declaration and Use

Prototypes

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.

Definitions

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;

C Statement Style and Conventions

NULL Pointers

if (p == NULL) /* Good, compare pointer to NULL */

if (!p) /* Bad, using ! on pointer */

if (*p == '\0') /* check character against (char)0 */

Return Value

note

The above rule about not typecasting void * applies to malloc, as well as to DPDK functions.

Logging and Errors

In the DPDK environment, use the logging interface provided:

#define RTE_LOGTYPE_TESTAPP1 RTE_LOGTYPE_USER1
#define RTE_LOGTYPE_TESTAPP2 RTE_LOGTYPE_USER2

/* enable these logs type */
rte_set_log_type(RTE_LOGTYPE_TESTAPP1, 1);
rte_set_log_type(RTE_LOGTYPE_TESTAPP2, 1);

/* log in debug level */
rte_set_log_level(RTE_LOG_DEBUG);
RTE_LOG(DEBUG, TESTAPP1, "this is is a debug level message\n");
RTE_LOG(INFO, TESTAPP1, "this is is a info level message\n");
RTE_LOG(WARNING, TESTAPP1, "this is is a warning level message\n");

/* log in info level */
rte_set_log_level(RTE_LOG_INFO);
RTE_LOG(DEBUG, TESTAPP2, "debug level message (not displayed)\n");

Branch Prediction

#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.

Static Variables and Functions

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.

Const Attribute

The const attribute should be used as often as possible when a variable is read-only.

Inline ASM in C code

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));

Control Statements

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 */
}

Environment or Architecture-specific Sources

In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (bsdapp or linuxapp) and so on. As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.

By convention, a file is common if it is not located in a directory indicating that it is specific. For instance, a file located in a subdir of “x86_64” directory is specific to this architecture. A file located in a subdir of “linuxapp” is specific to this execution environment.

note

Code in DPDK libraries and applications should be generic. The correct location for architecture or executive environment specific code is in the EAL.

When absolutely necessary, there are several ways to handle specific code:

Per Architecture Sources

The following config options can be used:

Per Execution Environment Sources

The following config options can be used:

Doxygen Documentation

The API documentation is automatically generated in the DPDK framework. That is why all files that are part of the public API must be documented using Doxygen syntax.

The public API comprises functions of DPDK that can be used by an external application that will use the SDK. Only the Doxygen syntax described in the coding rules (this document) should be used in the code. All the Doxygen features are described in the Doxygen manual online.

Documenting a Function

All public functions must be documented. The documentation is placed in the header file, above the declaration of the function. The definition of the function may be documented, but using standard comments (not in doxygen format). The following is an example of function documentation:

/**
 * Summary here; one sentence on one line (should not exceed 80 chars).
 *
 * A more detailed description goes here.
 *
 * A blank line forms a paragraph. There should be no trailing white-space
 * anywhere.
 *
 * @param first
 *   "@param" is a Doxygen directive to describe a function parameter. Like
 *   some other directives, it takes a term/summary on the same line and a
 *   description (this text) indented by 2 spaces on the next line. All
 *   descriptive text should wrap at 80 chars, without going over.
 *   Newlines are NOT supported within directives; if a newline would be
 *   before this text, it would be appended to the general description above.
 * @param second
 *   There should be no newline between multiple directives (of the same
 *   type).
 *
 * @return
 *   "@return" is a different Doxygen directive to describe the return value
 *   of a function, if there is any.
 */
int rte_foo(int first, int second)

Documenting Files

Each public file may start with a comment describing what the file does. For example:

/**
 * @file
 * This file describes the coding rules of RTE.
 *
 * It contains the coding rules of C code, ASM code, reStructured
 * Text documentation, and of course how to use doxygen to document
 * public API.
 */

Documenting Constants and Variables

Examples:

/**
 * The definition of a funny TRUE.
 */
#define TRUE 0

#define TRUE 1 /**< another way to document a macro */

/**
 * Frequency of the HPET counter in Hz
 *
 * @see rte_eal_hpet_init()
 */
extern uint64_t eal_hpet_resolution_hz;

Documenting Structures

Public structures should also be documented. The /**< sequence can be used to documented the fields of the structure, as shown in the following example:

/**
 * Structure describing a memzone, which is a contiguous portions of
 * physical memory identified by a name.
 */
struct rte_memzone {

#define MEMZONE_NAMESIZE 32
  char name[MEMZONE_NAMESIZE]; /**< name of the memory zone */

  phys_addr_t phys_addr;       /**< start physical address */
  void *addr;                  /**< start virtual address */
  uint64_t len;                /**< len of the memzone */

  int socket_id;               /**< NUMA socket id */
};

See Also Sections

The @see keyword can be used to highlight a link to an existing function, file, or URL. This directive should be placed on one line, without anything else, at the bottom of the documentation header.

/**
 * (documentation of function, file, ...)
 *
 * @see rte_foo()
 * @see eal_memzone.c
 */

#DPDK #Coding Style #C