This file describes the coding style used in most C files in the Open
vSwitch distribution. However, Linux kernel code datapath directory
-follows the Linux kernel's established coding conventions.
+follows the Linux kernel's established coding conventions. For the
+Windows kernel datapath code, use the coding style described in
+datapath-windows/CodingStyle.
+
+The following GNU indent options approximate this style:
+
+ -npro -bad -bap -bbb -br -blf -brs -cdw -ce -fca -cli0 -npcs -i4 -l79 \
+ -lc79 -nbfda -nut -saf -sai -saw -sbi4 -sc -sob -st -ncdb -pi4 -cs -bs \
+ -di1 -lp -il0 -hnl
+
BASICS
should omit a null-pointer check. We find that this usually makes
code easier to read.
+Functions in .c files should not normally be marked "inline", because
+it does not usually help code generation and it does suppress
+compilers warnings about unused functions. (Functions defined in .h
+usually should be marked inline.)
+
FUNCTION PROTOTYPES
break;
default:
- NOT_REACHED();
+ OVS_NOT_REACHED();
}
"switch" statements with very short, uniform cases may use an
common case, so this can be a real form of optimization as well.)
+RETURN VALUES
+
+ For functions that return a success or failure indication, prefer
+one of the following return value conventions:
+
+ * An "int" where 0 indicates success and a positive errno value
+ indicates a reason for failure.
+
+ * A "bool" where true indicates success and false indicates
+ failure.
+
+
MACROS
Don't define an object-like macro if an enum can be used instead.
};
+THREAD SAFETY ANNOTATIONS
+
+ Use the macros in lib/compiler.h to annotate locking requirements.
+For example:
+
+ static struct ovs_mutex mutex = OVS_MUTEX_INITIALIZER;
+ static struct ovs_rwlock rwlock = OVS_RWLOCK_INITIALIZER;
+
+ void function_require_plain_mutex(void) OVS_REQUIRES(mutex);
+ void function_require_rwlock(void) OVS_REQ_RDLOCK(rwlock);
+
+ Pass lock objects, not their addresses, to the annotation macros.
+(Thus we have OVS_REQUIRES(mutex) above, not OVS_REQUIRES(&mutex).)
+
+
SOURCE FILES
Each source file should state its license in a comment at the very
integer types. Use the PRId<N>, PRIu<N>, and PRIx<N> macros from
<inttypes.h> for formatting them with printf() and related functions.
- Use %zu to format size_t with printf().
+ For compatibility with antique printf() implementations:
+
+ - Instead of "%zu", use "%"PRIuSIZE.
+
+ - Instead of "%td", use "%"PRIdPTR.
+
+ - Instead of "%ju", use "%"PRIuMAX.
+
+Other variants exist for different radixes. For example, use
+"%"PRIxSIZE instead of "%zx" or "%x" instead of "%hhx".
+
+ Also, instead of "%hhd", use "%d". Be cautious substituting "%u",
+"%x", and "%o" for the corresponding versions with "hh": cast the
+argument to unsigned char if necessary, because printf("%hhu", -1)
+prints 255 but printf("%u", -1) prints 4294967295.
Use bit-fields sparingly. Do not use bit-fields for layout of
network protocol fields or in other circumstances where the exact
format is important.
- Declare bit-fields to be type "unsigned int" or "signed int". Do
-*not* declare bit-fields of type "int": C89 allows these to be either
-signed or unsigned according to the compiler's whim. (A 1-bit
-bit-field of type "int" may have a range of -1...0!) Do not declare
-bit-fields of type _Bool or enum or any other type, because these are
-not portable.
+ Declare bit-fields to be signed or unsigned integer types or _Bool
+(aka bool). Do *not* declare bit-fields of type "int": C99 allows
+these to be either signed or unsigned according to the compiler's
+whim. (A 1-bit bit-field of type "int" may have a range of -1...0!)
Try to order structure members such that they pack well on a system
with 2-byte "short", 4-byte "int", and 4- or 8-byte "long" and pointer
C DIALECT
- Some C99 features are OK because they are widely implemented even in
-older compilers:
+ Most C99 features are OK because they are widely implemented:
* Flexible array members (e.g. struct { int foo[]; }).
* bool and <stdbool.h>, but don't assume that bool or _Bool can
only take on the values 0 or 1, because this behavior can't be
simulated on C89 compilers.
+ Also, don't assume that a conversion to bool or _Bool follows
+ C99 semantics. I.e. use "(bool)(some_value != 0)" rather than
+ "(bool)some_value". The latter might produce unexpected results
+ on non-C99 environments. For example, if bool is implemented as
+ a typedef of char and some_value = 0x10000000.
- Don't use other C99 features that are not widely implemented in
-older compilers:
-
- * Don't use designated initializers (e.g. don't write "struct foo
- foo = {.a = 1};" or "int a[] = {[2] = 5};").
+ * Designated initializers (e.g. "struct foo foo = {.a = 1};" and
+ "int a[] = {[2] = 5};").
- * Don't mix declarations and code within a block.
+ * Mixing of declarations and code within a block. Please use this
+ judiciously; keep declarations nicely grouped together in the
+ beginning of a block if possible.
- * Don't use declarations in iteration statements (e.g. don't write
+ * Use of declarations in iteration statements (e.g.
"for (int i = 0; i < 10; i++)").
- * Don't put a trailing comma in an enum declaration (e.g. don't
- write "enum { x = 1, };").
+ * Use of a trailing comma in an enum declaration (e.g.
+ "enum { x = 1, };").
As a matter of style, avoid // comments.
- Avoid using GCC extensions unless you also add a fallback for
-non-GCC compilers. You can, however, use GCC extensions and C99
-features in code that compiles only on GNU/Linux (such as
-lib/netdev-linux.c), because GCC is the system compiler there.
+ Avoid using GCC or Clang extensions unless you also add a fallback
+for other compilers. You can, however, use C99 features or GCC
+extensions also supported by Clang in code that compiles only on
+GNU/Linux (such as lib/netdev-linux.c), because GCC is the system
+compiler there.
projects / cascardo / ovs.git / blobdiff