Setting tag sliver-openvswitch-2.2.90-1

[sliver-openvswitch.git] / CodingStyle

diff --git a/CodingStyle b/CodingStyle
index ee7a0e6..bae8cd6 100644 (file)
--- a/CodingStyle
+++ b/CodingStyle
@@ -224,7 +224,7 @@ statement, that is, write "return 0;" and not "return(0);"
         break;
 
     default:
-        NOT_REACHED();
+        OVS_NOT_REACHED();
     }
 
   "switch" statements with very short, uniform cases may use an
@@ -249,6 +249,18 @@ details.  (Some compilers also assume that the "if" branch is the more
 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.
@@ -286,6 +298,21 @@ the name of each enum.  For example:
     };
 
 
+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
@@ -367,7 +394,21 @@ from <stdint.h>.
 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
@@ -474,8 +515,7 @@ global variables.
 
 C DIALECT
 
-  Some C99 features are OK because they are widely implemented even in
-older compilers:
+  Some C99 features are OK because they are widely implemented:
 
     * Flexible array members (e.g. struct { int foo[]; }).
 
@@ -490,12 +530,12 @@ older compilers:
       only take on the values 0 or 1, because this behavior can't be
       simulated on C89 compilers.
 
+    * Designated initializers (e.g. "struct foo foo = {.a = 1};" and
+      "int a[] = {[2] = 5};").
+
   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};").
-
     * Don't mix declarations and code within a block.
 
     * Don't use declarations in iteration statements (e.g. don't write
@@ -506,7 +546,8 @@ older compilers:
 
   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.