lib/compiler.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef COMPILER_H
  18 #define COMPILER_H 1
  19
  20 #ifndef __has_feature
  21   #define __has_feature(x) 0
  22 #endif
  23 #ifndef __has_extension
  24   #define __has_extension(x) 0
  25 #endif
  26
  27 /* To make NO_RETURN portable across gcc/clang and MSVC, it should be
  28  * added at the beginning of the function declaration. */
  29 #if __GNUC__ && !__CHECKER__
  30 #define NO_RETURN __attribute__((__noreturn__))
  31 #elif _MSC_VER
  32 #define NO_RETURN __declspec(noreturn)
  33 #else
  34 #define NO_RETURN
  35 #endif
  36
  37 #if __GNUC__ && !__CHECKER__
  38 #define OVS_UNUSED __attribute__((__unused__))
  39 #define PRINTF_FORMAT(FMT, ARG1) __attribute__((__format__(printf, FMT, ARG1)))
  40 #define SCANF_FORMAT(FMT, ARG1) __attribute__((__format__(scanf, FMT, ARG1)))
  41 #define STRFTIME_FORMAT(FMT) __attribute__((__format__(__strftime__, FMT, 0)))
  42 #define MALLOC_LIKE __attribute__((__malloc__))
  43 #define ALWAYS_INLINE __attribute__((always_inline))
  44 #define WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
  45 #define SENTINEL(N) __attribute__((sentinel(N)))
  46 #define OVS_LIKELY(CONDITION) __builtin_expect(!!(CONDITION), 1)
  47 #define OVS_UNLIKELY(CONDITION) __builtin_expect(!!(CONDITION), 0)
  48 #else
  49 #define OVS_UNUSED
  50 #define PRINTF_FORMAT(FMT, ARG1)
  51 #define SCANF_FORMAT(FMT, ARG1)
  52 #define STRFTIME_FORMAT(FMT)
  53 #define MALLOC_LIKE
  54 #define ALWAYS_INLINE
  55 #define WARN_UNUSED_RESULT
  56 #define SENTINEL(N)
  57 #define OVS_LIKELY(CONDITION) (!!(CONDITION))
  58 #define OVS_UNLIKELY(CONDITION) (!!(CONDITION))
  59 #endif
  60
  61 #if __has_feature(c_thread_safety_attributes)
  62 /* "clang" annotations for thread safety check.
  63  *
  64  * OVS_LOCKABLE indicates that the struct contains mutex element
  65  * which can be locked by functions like ovs_mutex_lock().
  66  *
  67  * Below, the word MUTEX stands for the name of an object with an OVS_LOCKABLE
  68  * struct type.  It can also be a comma-separated list of multiple structs,
  69  * e.g. to require a function to hold multiple locks while invoked.
  70  *
  71  *
  72  * On a variable:
  73  *
  74  *    - OVS_GUARDED indicates that the variable may only be accessed some mutex
  75  *      is held.
  76  *
  77  *    - OVS_GUARDED_BY(MUTEX) indicates that the variable may only be accessed
  78  *      while the specific MUTEX is held.
  79  *
  80  *
  81  * On a variable A of mutex type:
  82  *
  83  *    - OVS_ACQ_BEFORE(B), where B is a mutex or a comma-separated list of
  84  *      mutexes, declare that if both A and B are acquired at the same time,
  85  *      then A must be acquired before B.  That is, B nests inside A.
  86  *
  87  *    - OVS_ACQ_AFTER(B) is the opposite of OVS_ACQ_BEFORE(B), that is, it
  88  *      declares that A nests inside B.
  89  *
  90  *
  91  * On a function, the following attributes apply to mutexes:
  92  *
  93  *    - OVS_ACQUIRES(MUTEX) indicate that the function must be called without
  94  *      holding MUTEX and that it returns holding MUTEX.
  95  *
  96  *    - OVS_RELEASES(MUTEX) indicates that the function may only be called with
  97  *      MUTEX held and that it returns with MUTEX released.  It can be used for
  98  *      all types of MUTEX.
  99  *
 100  *    - OVS_TRY_LOCK(RETVAL, MUTEX) indicate that the function will try to
 101  *      acquire MUTEX.  RETVAL is an integer or boolean value specifying the
 102  *      return value of a successful lock acquisition.
 103  *
 104  *    - OVS_REQUIRES(MUTEX) indicate that the function may only be called with
 105  *      MUTEX held and that the function does not release MUTEX.
 106  *
 107  *    - OVS_EXCLUDED(MUTEX) indicates that the function may only be called when
 108  *      MUTEX is not held.
 109  *
 110  *
 111  * The following variants, with the same syntax, apply to reader-writer locks:
 112  *
 113  *    mutex                rwlock, for reading  rwlock, for writing
 114  *    -------------------  -------------------  -------------------
 115  *    OVS_ACQUIRES         OVS_ACQ_RDLOCK       OVS_ACQ_WRLOCK
 116  *    OVS_RELEASES         OVS_RELEASES         OVS_RELEASES
 117  *    OVS_TRY_LOCK         OVS_TRY_RDLOCK       OVS_TRY_WRLOCK
 118  *    OVS_REQUIRES         OVS_REQ_RDLOCK       OVS_REQ_WRLOCK
 119  *    OVS_EXCLUDED         OVS_EXCLUDED         OVS_EXCLUDED
 120  */
 121 #define OVS_LOCKABLE __attribute__((lockable))
 122 #define OVS_REQ_RDLOCK(...) __attribute__((shared_locks_required(__VA_ARGS__)))
 123 #define OVS_ACQ_RDLOCK(...) __attribute__((shared_lock_function(__VA_ARGS__)))
 124 #define OVS_REQ_WRLOCK(...) \
 125     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 126 #define OVS_ACQ_WRLOCK(...) \
 127     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 128 #define OVS_REQUIRES(...) \
 129     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 130 #define OVS_ACQUIRES(...) \
 131     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 132 #define OVS_TRY_WRLOCK(RETVAL, ...)                              \
 133     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 134 #define OVS_TRY_RDLOCK(RETVAL, ...)                          \
 135     __attribute__((shared_trylock_function(RETVAL, __VA_ARGS__)))
 136 #define OVS_TRY_LOCK(RETVAL, ...)                                \
 137     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 138 #define OVS_GUARDED __attribute__((guarded_var))
 139 #define OVS_GUARDED_BY(...) __attribute__((guarded_by(__VA_ARGS__)))
 140 #define OVS_RELEASES(...) __attribute__((unlock_function(__VA_ARGS__)))
 141 #define OVS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 142 #define OVS_ACQ_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__)))
 143 #define OVS_ACQ_AFTER(...) __attribute__((acquired_after(__VA_ARGS__)))
 144 #define OVS_NO_THREAD_SAFETY_ANALYSIS \
 145     __attribute__((no_thread_safety_analysis))
 146 #else  /* not Clang */
 147 #define OVS_LOCKABLE
 148 #define OVS_REQ_RDLOCK(...)
 149 #define OVS_ACQ_RDLOCK(...)
 150 #define OVS_REQ_WRLOCK(...)
 151 #define OVS_ACQ_WRLOCK(...)
 152 #define OVS_REQUIRES(...)
 153 #define OVS_ACQUIRES(...)
 154 #define OVS_TRY_WRLOCK(...)
 155 #define OVS_TRY_RDLOCK(...)
 156 #define OVS_TRY_LOCK(...)
 157 #define OVS_GUARDED
 158 #define OVS_GUARDED_BY(...)
 159 #define OVS_EXCLUDED(...)
 160 #define OVS_RELEASES(...)
 161 #define OVS_ACQ_BEFORE(...)
 162 #define OVS_ACQ_AFTER(...)
 163 #define OVS_NO_THREAD_SAFETY_ANALYSIS
 164 #endif
 165
 166 /* ISO C says that a C implementation may choose any integer type for an enum
 167  * that is sufficient to hold all of its values.  Common ABIs (such as the
 168  * System V ABI used on i386 GNU/Linux) always use a full-sized "int", even
 169  * when a smaller type would suffice.
 170  *
 171  * In GNU C, "enum __attribute__((packed)) name { ... }" defines 'name' as an
 172  * enum compatible with a type that is no bigger than necessary.  This is the
 173  * intended use of OVS_PACKED_ENUM.
 174  *
 175  * OVS_PACKED_ENUM is intended for use only as a space optimization, since it
 176  * only works with GCC.  That means that it must not be used in wire protocols
 177  * or otherwise exposed outside of a single process. */
 178 #if __GNUC__ && !__CHECKER__
 179 #define OVS_PACKED_ENUM __attribute__((__packed__))
 180 #define HAVE_PACKED_ENUM
 181 #else
 182 #define OVS_PACKED_ENUM
 183 #endif
 184
 185 #ifndef _MSC_VER
 186 #define OVS_PACKED(DECL) DECL __attribute__((__packed__))
 187 #else
 188 #define OVS_PACKED(DECL) __pragma(pack(push, 1)) DECL __pragma(pack(pop))
 189 #endif
 190
 191 /* For defining a structure whose instances should aligned on an N-byte
 192  * boundary.
 193  *
 194  * e.g. The following:
 195  *     OVS_ALIGNED_STRUCT(64, mystruct) { ... };
 196  * is equivalent to the following except that it specifies 64-byte alignment:
 197  *     struct mystruct { ... };
 198  */
 199 #ifndef _MSC_VER
 200 #define OVS_ALIGNED_STRUCT(N, TAG) struct __attribute__((aligned(N))) TAG
 201 #else
 202 #define OVS_ALIGNED_STRUCT(N, TAG) __declspec(align(N)) struct TAG
 203 #endif
 204
 205 #ifdef _MSC_VER
 206 #define CCALL __cdecl
 207 #pragma section(".CRT$XCU",read)
 208 #define OVS_CONSTRUCTOR(f) \
 209     static void __cdecl f(void); \
 210     __declspec(allocate(".CRT$XCU")) void (__cdecl*f##_)(void) = f; \
 211     static void __cdecl f(void)
 212 #else
 213 #define OVS_CONSTRUCTOR(f) \
 214     static void f(void) __attribute__((constructor)); \
 215     static void f(void)
 216 #endif
 217
 218 /* OVS_PREFETCH() can be used to instruct the CPU to fetch the cache
 219  * line containing the given address to a CPU cache.
 220  * OVS_PREFETCH_WRITE() should be used when the memory is going to be
 221  * written to.  Depending on the target CPU, this can generate the same
 222  * instruction as OVS_PREFETCH(), or bring the data into the cache in an
 223  * exclusive state. */
 224 #if __GNUC__
 225 #define OVS_PREFETCH(addr) __builtin_prefetch((addr))
 226 #define OVS_PREFETCH_WRITE(addr) __builtin_prefetch((addr), 1)
 227 #else
 228 #define OVS_PREFETCH(addr)
 229 #define OVS_PREFETCH_WRITE(addr)
 230 #endif
 231
 232 /* Output a message (not an error) while compiling without failing the
 233  * compilation process */
 234 #if HAVE_PRAGMA_MESSAGE
 235 #define DO_PRAGMA(x) _Pragma(#x)
 236 #define BUILD_MESSAGE(x) \
 237     DO_PRAGMA(message(x))
 238 #else
 239 #define BUILD_MESSAGE(x)
 240 #endif
 241
 242 #endif /* compiler.h */