include/openvswitch/compiler.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2016 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 OPENVSWITCH_COMPILER_H
  18 #define OPENVSWITCH_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 OVS_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 OVS_NO_RETURN __attribute__((__noreturn__))
  31 #elif _MSC_VER
  32 #define OVS_NO_RETURN __declspec(noreturn)
  33 #else
  34 #define OVS_NO_RETURN
  35 #endif
  36
  37 #if __GNUC__ && !__CHECKER__
  38 #define OVS_UNUSED __attribute__((__unused__))
  39 #define OVS_PRINTF_FORMAT(FMT, ARG1) __attribute__((__format__(printf, FMT, ARG1)))
  40 #define OVS_SCANF_FORMAT(FMT, ARG1) __attribute__((__format__(scanf, FMT, ARG1)))
  41 #define OVS_WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
  42 #define OVS_LIKELY(CONDITION) __builtin_expect(!!(CONDITION), 1)
  43 #define OVS_UNLIKELY(CONDITION) __builtin_expect(!!(CONDITION), 0)
  44 #else
  45 #define OVS_UNUSED
  46 #define OVS_PRINTF_FORMAT(FMT, ARG1)
  47 #define OVS_SCANF_FORMAT(FMT, ARG1)
  48 #define OVS_WARN_UNUSED_RESULT
  49 #define OVS_LIKELY(CONDITION) (!!(CONDITION))
  50 #define OVS_UNLIKELY(CONDITION) (!!(CONDITION))
  51 #endif
  52
  53 #if __has_feature(c_thread_safety_attributes)
  54 /* "clang" annotations for thread safety check.
  55  *
  56  * OVS_LOCKABLE indicates that the struct contains mutex element
  57  * which can be locked by functions like ovs_mutex_lock().
  58  *
  59  * Below, the word MUTEX stands for the name of an object with an OVS_LOCKABLE
  60  * struct type.  It can also be a comma-separated list of multiple structs,
  61  * e.g. to require a function to hold multiple locks while invoked.
  62  *
  63  *
  64  * On a variable:
  65  *
  66  *    - OVS_GUARDED indicates that the variable may only be accessed some mutex
  67  *      is held.
  68  *
  69  *    - OVS_GUARDED_BY(MUTEX) indicates that the variable may only be accessed
  70  *      while the specific MUTEX is held.
  71  *
  72  *
  73  * On a variable A of mutex type:
  74  *
  75  *    - OVS_ACQ_BEFORE(B), where B is a mutex or a comma-separated list of
  76  *      mutexes, declare that if both A and B are acquired at the same time,
  77  *      then A must be acquired before B.  That is, B nests inside A.
  78  *
  79  *    - OVS_ACQ_AFTER(B) is the opposite of OVS_ACQ_BEFORE(B), that is, it
  80  *      declares that A nests inside B.
  81  *
  82  *
  83  * On a function, the following attributes apply to mutexes:
  84  *
  85  *    - OVS_ACQUIRES(MUTEX) indicate that the function must be called without
  86  *      holding MUTEX and that it returns holding MUTEX.
  87  *
  88  *    - OVS_RELEASES(MUTEX) indicates that the function may only be called with
  89  *      MUTEX held and that it returns with MUTEX released.  It can be used for
  90  *      all types of MUTEX.
  91  *
  92  *    - OVS_TRY_LOCK(RETVAL, MUTEX) indicate that the function will try to
  93  *      acquire MUTEX.  RETVAL is an integer or boolean value specifying the
  94  *      return value of a successful lock acquisition.
  95  *
  96  *    - OVS_REQUIRES(MUTEX) indicate that the function may only be called with
  97  *      MUTEX held and that the function does not release MUTEX.
  98  *
  99  *    - OVS_EXCLUDED(MUTEX) indicates that the function may only be called when
 100  *      MUTEX is not held.
 101  *
 102  *
 103  * The following variants, with the same syntax, apply to reader-writer locks:
 104  *
 105  *    mutex                rwlock, for reading  rwlock, for writing
 106  *    -------------------  -------------------  -------------------
 107  *    OVS_ACQUIRES         OVS_ACQ_RDLOCK       OVS_ACQ_WRLOCK
 108  *    OVS_RELEASES         OVS_RELEASES         OVS_RELEASES
 109  *    OVS_TRY_LOCK         OVS_TRY_RDLOCK       OVS_TRY_WRLOCK
 110  *    OVS_REQUIRES         OVS_REQ_RDLOCK       OVS_REQ_WRLOCK
 111  *    OVS_EXCLUDED         OVS_EXCLUDED         OVS_EXCLUDED
 112  */
 113 #define OVS_LOCKABLE __attribute__((lockable))
 114 #define OVS_REQ_RDLOCK(...) __attribute__((shared_locks_required(__VA_ARGS__)))
 115 #define OVS_ACQ_RDLOCK(...) __attribute__((shared_lock_function(__VA_ARGS__)))
 116 #define OVS_REQ_WRLOCK(...) \
 117     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 118 #define OVS_ACQ_WRLOCK(...) \
 119     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 120 #define OVS_REQUIRES(...) \
 121     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 122 #define OVS_ACQUIRES(...) \
 123     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 124 #define OVS_TRY_WRLOCK(RETVAL, ...)                              \
 125     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 126 #define OVS_TRY_RDLOCK(RETVAL, ...)                          \
 127     __attribute__((shared_trylock_function(RETVAL, __VA_ARGS__)))
 128 #define OVS_TRY_LOCK(RETVAL, ...)                                \
 129     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 130 #define OVS_GUARDED __attribute__((guarded_var))
 131 #define OVS_GUARDED_BY(...) __attribute__((guarded_by(__VA_ARGS__)))
 132 #define OVS_RELEASES(...) __attribute__((unlock_function(__VA_ARGS__)))
 133 #define OVS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 134 #define OVS_ACQ_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__)))
 135 #define OVS_ACQ_AFTER(...) __attribute__((acquired_after(__VA_ARGS__)))
 136 #define OVS_NO_THREAD_SAFETY_ANALYSIS \
 137     __attribute__((no_thread_safety_analysis))
 138 #else  /* not Clang */
 139 #define OVS_LOCKABLE
 140 #define OVS_REQ_RDLOCK(...)
 141 #define OVS_ACQ_RDLOCK(...)
 142 #define OVS_REQ_WRLOCK(...)
 143 #define OVS_ACQ_WRLOCK(...)
 144 #define OVS_REQUIRES(...)
 145 #define OVS_ACQUIRES(...)
 146 #define OVS_TRY_WRLOCK(...)
 147 #define OVS_TRY_RDLOCK(...)
 148 #define OVS_TRY_LOCK(...)
 149 #define OVS_GUARDED
 150 #define OVS_GUARDED_BY(...)
 151 #define OVS_EXCLUDED(...)
 152 #define OVS_RELEASES(...)
 153 #define OVS_ACQ_BEFORE(...)
 154 #define OVS_ACQ_AFTER(...)
 155 #define OVS_NO_THREAD_SAFETY_ANALYSIS
 156 #endif
 157
 158 /* ISO C says that a C implementation may choose any integer type for an enum
 159  * that is sufficient to hold all of its values.  Common ABIs (such as the
 160  * System V ABI used on i386 GNU/Linux) always use a full-sized "int", even
 161  * when a smaller type would suffice.
 162  *
 163  * In GNU C, "enum __attribute__((packed)) name { ... }" defines 'name' as an
 164  * enum compatible with a type that is no bigger than necessary.  This is the
 165  * intended use of OVS_PACKED_ENUM.
 166  *
 167  * OVS_PACKED_ENUM is intended for use only as a space optimization, since it
 168  * only works with GCC.  That means that it must not be used in wire protocols
 169  * or otherwise exposed outside of a single process. */
 170 #if __GNUC__ && !__CHECKER__
 171 #define OVS_PACKED_ENUM __attribute__((__packed__))
 172 #define HAVE_PACKED_ENUM
 173 #else
 174 #define OVS_PACKED_ENUM
 175 #endif
 176
 177 #ifndef _MSC_VER
 178 #define OVS_PACKED(DECL) DECL __attribute__((__packed__))
 179 #else
 180 #define OVS_PACKED(DECL) __pragma(pack(push, 1)) DECL __pragma(pack(pop))
 181 #endif
 182
 183 /* For defining a structure whose instances should aligned on an N-byte
 184  * boundary.
 185  *
 186  * e.g. The following:
 187  *     OVS_ALIGNED_STRUCT(64, mystruct) { ... };
 188  * is equivalent to the following except that it specifies 64-byte alignment:
 189  *     struct mystruct { ... };
 190  */
 191 #ifndef _MSC_VER
 192 #define OVS_ALIGNED_STRUCT(N, TAG) struct __attribute__((aligned(N))) TAG
 193 #else
 194 #define OVS_ALIGNED_STRUCT(N, TAG) __declspec(align(N)) struct TAG
 195 #endif
 196
 197 /* Supplies code to be run at startup time before invoking main().
 198  * Use as:
 199  *
 200  *     OVS_CONSTRUCTOR(my_constructor) {
 201  *         ...some code...
 202  *     }
 203  */
 204 #ifdef _MSC_VER
 205 #define CCALL __cdecl
 206 #pragma section(".CRT$XCU",read)
 207 #define OVS_CONSTRUCTOR(f) \
 208     static void __cdecl f(void); \
 209     __declspec(allocate(".CRT$XCU")) static void (__cdecl*f##_)(void) = f; \
 210     static void __cdecl f(void)
 211 #else
 212 #define OVS_CONSTRUCTOR(f) \
 213     static void f(void) __attribute__((constructor)); \
 214     static void f(void)
 215 #endif
 216
 217 /* OVS_PREFETCH() can be used to instruct the CPU to fetch the cache
 218  * line containing the given address to a CPU cache.
 219  * OVS_PREFETCH_WRITE() should be used when the memory is going to be
 220  * written to.  Depending on the target CPU, this can generate the same
 221  * instruction as OVS_PREFETCH(), or bring the data into the cache in an
 222  * exclusive state. */
 223 #if __GNUC__
 224 #define OVS_PREFETCH(addr) __builtin_prefetch((addr))
 225 #define OVS_PREFETCH_WRITE(addr) __builtin_prefetch((addr), 1)
 226 #else
 227 #define OVS_PREFETCH(addr)
 228 #define OVS_PREFETCH_WRITE(addr)
 229 #endif
 230
 231 #endif /* compiler.h */