lib/compiler.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013 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
  24 #if __GNUC__ && !__CHECKER__
  25 #define NO_RETURN __attribute__((__noreturn__))
  26 #define OVS_UNUSED __attribute__((__unused__))
  27 #define PRINTF_FORMAT(FMT, ARG1) __attribute__((__format__(printf, FMT, ARG1)))
  28 #define STRFTIME_FORMAT(FMT) __attribute__((__format__(__strftime__, FMT, 0)))
  29 #define MALLOC_LIKE __attribute__((__malloc__))
  30 #define ALWAYS_INLINE __attribute__((always_inline))
  31 #define WARN_UNUSED_RESULT __attribute__((__warn_unused_result__))
  32 #define SENTINEL(N) __attribute__((sentinel(N)))
  33 #define OVS_LIKELY(CONDITION) __builtin_expect(!!(CONDITION), 1)
  34 #define OVS_UNLIKELY(CONDITION) __builtin_expect(!!(CONDITION), 0)
  35 #else
  36 #define NO_RETURN
  37 #define OVS_UNUSED
  38 #define PRINTF_FORMAT(FMT, ARG1)
  39 #define STRFTIME_FORMAT(FMT)
  40 #define MALLOC_LIKE
  41 #define ALWAYS_INLINE
  42 #define WARN_UNUSED_RESULT
  43 #define SENTINEL(N)
  44 #define OVS_LIKELY(CONDITION) (!!(CONDITION))
  45 #define OVS_UNLIKELY(CONDITION) (!!(CONDITION))
  46 #endif
  47
  48 #if __has_feature(c_thread_safety_attributes)
  49 /* "clang" annotations for thread safety check.
  50  *
  51  * OVS_LOCKABLE indicates that the struct contains mutex element
  52  * which can be locked by functions like ovs_mutex_lock().
  53  *
  54  * Below, the word MUTEX stands for the name of an object with an OVS_LOCKABLE
  55  * struct type.  It can also be a comma-separated list of multiple structs,
  56  * e.g. to require a function to hold multiple locks while invoked.
  57  *
  58  *
  59  * On a variable:
  60  *
  61  *    - OVS_GUARDED indicates that the variable may only be accessed some mutex
  62  *      is held.
  63  *
  64  *    - OVS_GUARDED_BY(MUTEX) indicates that the variable may only be accessed
  65  *      while the specific MUTEX is held.
  66  *
  67  *
  68  * On a variable A of mutex type:
  69  *
  70  *    - OVS_ACQ_BEFORE(B), where B is a mutex or a comma-separated list of
  71  *      mutexes, declare that if both A and B are acquired at the same time,
  72  *      then A must be acquired before B.  That is, B nests inside A.
  73  *
  74  *    - OVS_ACQ_AFTER(B) is the opposite of OVS_ACQ_BEFORE(B), that is, it
  75  *      declares that A nests inside B.
  76  *
  77  *
  78  * On a function, the following attributes apply to mutexes:
  79  *
  80  *    - OVS_ACQUIRES(MUTEX) indicate that the function must be called without
  81  *      holding MUTEX and that it returns holding MUTEX.
  82  *
  83  *    - OVS_RELEASES(MUTEX) indicates that the function may only be called with
  84  *      MUTEX held and that it returns with MUTEX released.  It can be used for
  85  *      all types of MUTEX.
  86  *
  87  *    - OVS_TRY_LOCK(RETVAL, MUTEX) indicate that the function will try to
  88  *      acquire MUTEX.  RETVAL is an integer or boolean value specifying the
  89  *      return value of a successful lock acquisition.
  90  *
  91  *    - OVS_REQUIRES(MUTEX) indicate that the function may only be called with
  92  *      MUTEX held and that the function does not release MUTEX.
  93  *
  94  *    - OVS_LOCKS_EXCLUDED(MUTEX) indicates that the function may only be
  95  *      called when MUTEX is not held.
  96  *
  97  *
  98  * The following variants, with the same syntax, apply to reader-writer locks:
  99  *
 100  *    mutex                rwlock, for reading  rwlock, for writing
 101  *    -------------------  -------------------  -------------------
 102  *    OVS_ACQUIRES         OVS_ACQ_RDLOCK       OVS_ACQ_WRLOCK
 103  *    OVS_RELEASES         OVS_RELEASES         OVS_RELEASES
 104  *    OVS_TRY_LOCK         OVS_TRY_RDLOCK       OVS_TRY_WRLOCK
 105  *    OVS_REQUIRES         OVS_REQ_RDLOCK       OVS_REQ_WRLOCK
 106  *    OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED
 107  */
 108 #define OVS_LOCKABLE __attribute__((lockable))
 109 #define OVS_REQ_RDLOCK(...) __attribute__((shared_locks_required(__VA_ARGS__)))
 110 #define OVS_ACQ_RDLOCK(...) __attribute__((shared_lock_function(__VA_ARGS__)))
 111 #define OVS_REQ_WRLOCK(...) \
 112     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 113 #define OVS_ACQ_WRLOCK(...) \
 114     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 115 #define OVS_REQUIRES(...) \
 116     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 117 #define OVS_ACQUIRES(...) \
 118     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 119 #define OVS_TRY_WRLOCK(RETVAL, ...)                              \
 120     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 121 #define OVS_TRY_RDLOCK(RETVAL, ...)                          \
 122     __attribute__((shared_trylock_function(RETVAL, __VA_ARGS__)))
 123 #define OVS_TRY_LOCK(RETVAL, ...)                                \
 124     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 125 #define OVS_GUARDED __attribute__((guarded_var))
 126 #define OVS_GUARDED_BY(...) __attribute__((guarded_by(__VA_ARGS__)))
 127 #define OVS_RELEASES(...) __attribute__((unlock_function(__VA_ARGS__)))
 128 #define OVS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 129 #define OVS_ACQ_BEFORE(...) __attribute__((acquired_before(__VA_ARGS__)))
 130 #define OVS_ACQ_AFTER(...) __attribute__((acquired_after(__VA_ARGS__)))
 131 #elif __CHECKER__
 132 /* "sparse" annotations for mutexes and mutex-like constructs.
 133  *
 134  * Change the thread-safety check annotations to use "context" attribute.
 135  *
 136  * OVS_MACRO_LOCK and OVS_MACRO_RELEASE are suitable for use within macros,
 137  * where there is no function prototype to annotate. */
 138 #define OVS_LOCKABLE
 139 #define OVS_REQ_RDLOCK(...) __attribute__((context(MUTEX, 1, 1)))
 140 #define OVS_ACQ_RDLOCK(...) __attribute__((context(MUTEX, 0, 1)))
 141 #define OVS_REQ_WRLOCK(...) __attribute__((context(MUTEX, 1, 1)))
 142 #define OVS_ACQ_WRLOCK(...) __attribute__((context(MUTEX, 0, 1)))
 143 #define OVS_REQUIRES(...)   __attribute__((context(MUTEX, 1, 1)))
 144 #define OVS_ACQUIRES(...)   __attribute__((context(MUTEX, 0, 1)))
 145 #define OVS_TRY_WRLOCK(RETVAL, ...)
 146 #define OVS_TRY_RDLOCK(RETVAL, ...)
 147 #define OVS_TRY_LOCK(REVAL, ...)
 148 #define OVS_GUARDED
 149 #define OVS_GUARDED_BY(...)
 150 #define OVS_EXCLUDED(...)
 151 #define OVS_RELEASES(...)   __attribute__((context(MUTEX, 1, 0)))
 152 #define OVS_ACQ_BEFORE(...)
 153 #define OVS_ACQ_AFTER(...)
 154 #define OVS_MACRO_LOCK(...) __context__(MUTEX, 0, 1)
 155 #define OVS_MACRO_RELEASE(...) __context__(MUTEX, 1, 0)
 156 #else
 157 #define OVS_LOCKABLE
 158 #define OVS_REQ_RDLOCK(...)
 159 #define OVS_ACQ_RDLOCK(...)
 160 #define OVS_REQ_WRLOCK(...)
 161 #define OVS_ACQ_WRLOCK(...)
 162 #define OVS_REQUIRES(...)
 163 #define OVS_ACQUIRES(...)
 164 #define OVS_TRY_WRLOCK(...)
 165 #define OVS_TRY_RDLOCK(...)
 166 #define OVS_TRY_LOCK(...)
 167 #define OVS_GUARDED
 168 #define OVS_GUARDED_BY(...)
 169 #define OVS_EXCLUDED(...)
 170 #define OVS_RELEASES(...)
 171 #define OVS_ACQ_BEFORE(...)
 172 #define OVS_ACQ_AFTER(...)
 173 #define OVS_MACRO_LOCK(...)
 174 #define OVS_MACRO_RELEASE(...)
 175 #endif
 176
 177 /* ISO C says that a C implementation may choose any integer type for an enum
 178  * that is sufficient to hold all of its values.  Common ABIs (such as the
 179  * System V ABI used on i386 GNU/Linux) always use a full-sized "int", even
 180  * when a smaller type would suffice.
 181  *
 182  * In GNU C, "enum __attribute__((packed)) name { ... }" defines 'name' as an
 183  * enum compatible with a type that is no bigger than necessary.  This is the
 184  * intended use of OVS_PACKED_ENUM.
 185  *
 186  * OVS_PACKED_ENUM is intended for use only as a space optimization, since it
 187  * only works with GCC.  That means that it must not be used in wire protocols
 188  * or otherwise exposed outside of a single process. */
 189 #if __GNUC__ && !__CHECKER__
 190 #define OVS_PACKED_ENUM __attribute__((__packed__))
 191 #else
 192 #define OVS_PACKED_ENUM
 193 #endif
 194
 195 #ifndef _MSC_VER
 196 #define OVS_PACKED(DECL) DECL __attribute__((__packed__))
 197 #else
 198 #define OVS_PACKED(DECL) __pragma(pack(push, 1)) DECL __pragma(pack(pop))
 199 #endif
 200
 201 #endif /* compiler.h */