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 function, the following attributes apply to mutexes:
  69  *
  70  *    - OVS_ACQUIRES(MUTEX) indicate that the function must be called without
  71  *      holding MUTEX and that it returns holding MUTEX.
  72  *
  73  *    - OVS_RELEASES(MUTEX) indicates that the function may only be called with
  74  *      MUTEX held and that it returns with MUTEX released.  It can be used for
  75  *      all types of MUTEX.
  76  *
  77  *    - OVS_TRY_LOCK(RETVAL, MUTEX) indicate that the function will try to
  78  *      acquire MUTEX.  RETVAL is an integer or boolean value specifying the
  79  *      return value of a successful lock acquisition.
  80  *
  81  *    - OVS_REQUIRES(MUTEX) indicate that the function may only be called with
  82  *      MUTEX held and that the function does not release MUTEX.
  83  *
  84  *    - OVS_LOCKS_EXCLUDED(MUTEX) indicates that the function may only be
  85  *      called when MUTEX is not held.
  86  *
  87  * The following variants, with the same syntax, apply to reader-writer locks:
  88  *
  89  *    mutex                rwlock, for reading  rwlock, for writing
  90  *    -------------------  -------------------  -------------------
  91  *    OVS_ACQUIRES         OVS_ACQ_RDLOCK       OVS_ACQ_WRLOCK
  92  *    OVS_RELEASES         OVS_RELEASES         OVS_RELEASES
  93  *    OVS_TRY_LOCK         OVS_TRY_RDLOCK       OVS_TRY_WRLOCK
  94  *    OVS_REQUIRES         OVS_REQ_RDLOCK       OVS_REQ_WRLOCK
  95  *    OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED   OVS_LOCKS_EXCLUDED
  96  */
  97 #define OVS_LOCKABLE __attribute__((lockable))
  98 #define OVS_REQ_RDLOCK(...) __attribute__((shared_locks_required(__VA_ARGS__)))
  99 #define OVS_ACQ_RDLOCK(...) __attribute__((shared_lock_function(__VA_ARGS__)))
 100 #define OVS_REQ_WRLOCK(...) \
 101     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 102 #define OVS_ACQ_WRLOCK(...) \
 103     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 104 #define OVS_REQUIRES(...) \
 105     __attribute__((exclusive_locks_required(__VA_ARGS__)))
 106 #define OVS_ACQUIRES(...) \
 107     __attribute__((exclusive_lock_function(__VA_ARGS__)))
 108 #define OVS_TRY_WRLOCK(RETVAL, ...)                              \
 109     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 110 #define OVS_TRY_RDLOCK(RETVAL, ...)                          \
 111     __attribute__((shared_trylock_function(RETVAL, __VA_ARGS__)))
 112 #define OVS_TRY_LOCK(RETVAL, ...)                                \
 113     __attribute__((exclusive_trylock_function(RETVAL, __VA_ARGS__)))
 114 #define OVS_GUARDED __attribute__((guarded_var))
 115 #define OVS_GUARDED_BY(...) __attribute__((guarded_by(__VA_ARGS__)))
 116 #define OVS_RELEASES(...) __attribute__((unlock_function(__VA_ARGS__)))
 117 #define OVS_LOCKS_EXCLUDED(...) __attribute__((locks_excluded(__VA_ARGS__)))
 118 #elif __CHECKER__
 119 /* "sparse" annotations for mutexes and mutex-like constructs.
 120  *
 121  * Change the thread-safety check annotations to use "context" attribute.
 122  *
 123  * OVS_MACRO_LOCK and OVS_MACRO_RELEASE are suitable for use within macros,
 124  * where there is no function prototype to annotate. */
 125 #define OVS_LOCKABLE
 126 #define OVS_REQ_RDLOCK(...) __attribute__((context(MUTEX, 1, 1)))
 127 #define OVS_ACQ_RDLOCK(...) __attribute__((context(MUTEX, 0, 1)))
 128 #define OVS_REQ_WRLOCK(...) __attribute__((context(MUTEX, 1, 1)))
 129 #define OVS_ACQ_WRLOCK(...) __attribute__((context(MUTEX, 0, 1)))
 130 #define OVS_REQUIRES(...)   __attribute__((context(MUTEX, 1, 1)))
 131 #define OVS_ACQUIRES(...)   __attribute__((context(MUTEX, 0, 1)))
 132 #define OVS_TRY_WRLOCK(RETVAL, ...)
 133 #define OVS_TRY_RDLOCK(RETVAL, ...)
 134 #define OVS_TRY_LOCK(REVAL, ...)
 135 #define OVS_GUARDED
 136 #define OVS_GUARDED_BY(...)
 137 #define OVS_RELEASES(...)   __attribute__((context(MUTEX, 1, 0)))
 138 #define OVS_MACRO_LOCK(...) __context__(MUTEX, 0, 1)
 139 #define OVS_MACRO_RELEASE(...) __context__(MUTEX, 1, 0)
 140 #else
 141 #define OVS_LOCKABLE
 142 #define OVS_REQ_RDLOCK(...)
 143 #define OVS_ACQ_RDLOCK(...)
 144 #define OVS_REQ_WRLOCK(...)
 145 #define OVS_ACQ_WRLOCK(...)
 146 #define OVS_REQUIRES(...)
 147 #define OVS_ACQUIRES(...)
 148 #define OVS_TRY_WRLOCK(...)
 149 #define OVS_TRY_RDLOCK(...)
 150 #define OVS_TRY_LOCK(...)
 151 #define OVS_GUARDED
 152 #define OVS_GUARDED_BY(...)
 153 #define OVS_RELEASES(...)
 154 #define OVS_MACRO_LOCK(...)
 155 #define OVS_MACRO_RELEASE(...)
 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 #else
 173 #define OVS_PACKED_ENUM
 174 #endif
 175
 176 #ifndef _MSC_VER
 177 #define OVS_PACKED(DECL) DECL __attribute__((__packed__))
 178 #else
 179 #define OVS_PACKED(DECL) __pragma(pack(push, 1)) DECL __pragma(pack(pop))
 180 #endif
 181
 182 #endif /* compiler.h */