include/linux/compiler_attributes.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef __LINUX_COMPILER_ATTRIBUTES_H
   3 #define __LINUX_COMPILER_ATTRIBUTES_H
   4
   5 /*
   6  * The attributes in this file are unconditionally defined and they directly
   7  * map to compiler attribute(s), unless one of the compilers does not support
   8  * the attribute. In that case, __has_attribute is used to check for support
   9  * and the reason is stated in its comment ("Optional: ...").
  10  *
  11  * Any other "attributes" (i.e. those that depend on a configuration option,
  12  * on a compiler, on an architecture, on plugins, on other attributes...)
  13  * should be defined elsewhere (e.g. compiler_types.h or compiler-*.h).
  14  * The intention is to keep this file as simple as possible, as well as
  15  * compiler- and version-agnostic (e.g. avoiding GCC_VERSION checks).
  16  *
  17  * This file is meant to be sorted (by actual attribute name,
  18  * not by #define identifier). Use the __attribute__((__name__)) syntax
  19  * (i.e. with underscores) to avoid future collisions with other macros.
  20  * Provide links to the documentation of each supported compiler, if it exists.
  21  */
  22
  23 /*
  24  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alias-function-attribute
  25  */
  26 #define __alias(symbol)                 __attribute__((__alias__(#symbol)))
  27
  28 /*
  29  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-aligned-function-attribute
  30  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-aligned-type-attribute
  31  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-aligned-variable-attribute
  32  */
  33 #define __aligned(x)                    __attribute__((__aligned__(x)))
  34 #define __aligned_largest               __attribute__((__aligned__))
  35
  36 /*
  37  * Note: users of __always_inline currently do not write "inline" themselves,
  38  * which seems to be required by gcc to apply the attribute according
  39  * to its docs (and also "warning: always_inline function might not be
  40  * inlinable [-Wattributes]" is emitted).
  41  *
  42  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-always_005finline-function-attribute
  43  * clang: mentioned
  44  */
  45 #define __always_inline                 inline __attribute__((__always_inline__))
  46
  47 /*
  48  * The second argument is optional (default 0), so we use a variadic macro
  49  * to make the shorthand.
  50  *
  51  * Beware: Do not apply this to functions which may return
  52  * ERR_PTRs. Also, it is probably unwise to apply it to functions
  53  * returning extra information in the low bits (but in that case the
  54  * compiler should see some alignment anyway, when the return value is
  55  * massaged by 'flags = ptr & 3; ptr &= ~3;').
  56  *
  57  * Optional: not supported by icc
  58  *
  59  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-assume_005faligned-function-attribute
  60  * clang: https://clang.llvm.org/docs/AttributeReference.html#assume-aligned
  61  */
  62 #if __has_attribute(__assume_aligned__)
  63 # define __assume_aligned(a, ...)       __attribute__((__assume_aligned__(a, ## __VA_ARGS__)))
  64 #else
  65 # define __assume_aligned(a, ...)
  66 #endif
  67
  68 /*
  69  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-cold-function-attribute
  70  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Label-Attributes.html#index-cold-label-attribute
  71  */
  72 #define __cold                          __attribute__((__cold__))
  73
  74 /*
  75  * Note the long name.
  76  *
  77  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute
  78  */
  79 #define __attribute_const__             __attribute__((__const__))
  80
  81 /*
  82  * Optional: only supported since gcc >= 9
  83  * Optional: not supported by clang
  84  * Optional: not supported by icc
  85  *
  86  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-copy-function-attribute
  87  */
  88 #if __has_attribute(__copy__)
  89 # define __copy(symbol)                 __attribute__((__copy__(symbol)))
  90 #else
  91 # define __copy(symbol)
  92 #endif
  93
  94 /*
  95  * Don't. Just don't. See commit 771c035372a0 ("deprecate the '__deprecated'
  96  * attribute warnings entirely and for good") for more information.
  97  *
  98  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute
  99  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-deprecated-type-attribute
 100  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-deprecated-variable-attribute
 101  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Enumerator-Attributes.html#index-deprecated-enumerator-attribute
 102  * clang: https://clang.llvm.org/docs/AttributeReference.html#deprecated
 103  */
 104 #define __deprecated
 105
 106 /*
 107  * Optional: only supported since gcc >= 5.1
 108  * Optional: not supported by clang
 109  * Optional: not supported by icc
 110  *
 111  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-designated_005finit-type-attribute
 112  */
 113 #if __has_attribute(__designated_init__)
 114 # define __designated_init              __attribute__((__designated_init__))
 115 #else
 116 # define __designated_init
 117 #endif
 118
 119 /*
 120  * Optional: only supported since clang >= 14.0
 121  *
 122  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-error-function-attribute
 123  */
 124 #if __has_attribute(__error__)
 125 # define __compiletime_error(msg)       __attribute__((__error__(msg)))
 126 #else
 127 # define __compiletime_error(msg)
 128 #endif
 129
 130 /*
 131  * Optional: not supported by clang
 132  *
 133  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-externally_005fvisible-function-attribute
 134  */
 135 #if __has_attribute(__externally_visible__)
 136 # define __visible                      __attribute__((__externally_visible__))
 137 #else
 138 # define __visible
 139 #endif
 140
 141 /*
 142  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-format-function-attribute
 143  * clang: https://clang.llvm.org/docs/AttributeReference.html#format
 144  */
 145 #define __printf(a, b)                  __attribute__((__format__(printf, a, b)))
 146 #define __scanf(a, b)                   __attribute__((__format__(scanf, a, b)))
 147
 148 /*
 149  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-gnu_005finline-function-attribute
 150  * clang: https://clang.llvm.org/docs/AttributeReference.html#gnu-inline
 151  */
 152 #define __gnu_inline                    __attribute__((__gnu_inline__))
 153
 154 /*
 155  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute
 156  */
 157 #define __malloc                        __attribute__((__malloc__))
 158
 159 /*
 160  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-mode-type-attribute
 161  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-mode-variable-attribute
 162  */
 163 #define __mode(x)                       __attribute__((__mode__(x)))
 164
 165 /*
 166  * Optional: only supported since gcc >= 7
 167  *
 168  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/x86-Function-Attributes.html#index-no_005fcaller_005fsaved_005fregisters-function-attribute_002c-x86
 169  * clang: https://clang.llvm.org/docs/AttributeReference.html#no-caller-saved-registers
 170  */
 171 #if __has_attribute(__no_caller_saved_registers__)
 172 # define __no_caller_saved_registers    __attribute__((__no_caller_saved_registers__))
 173 #else
 174 # define __no_caller_saved_registers
 175 #endif
 176
 177 /*
 178  * Optional: not supported by clang
 179  *
 180  *  gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noclone-function-attribute
 181  */
 182 #if __has_attribute(__noclone__)
 183 # define __noclone                      __attribute__((__noclone__))
 184 #else
 185 # define __noclone
 186 #endif
 187
 188 /*
 189  * Add the pseudo keyword 'fallthrough' so case statement blocks
 190  * must end with any of these keywords:
 191  *   break;
 192  *   fallthrough;
 193  *   continue;
 194  *   goto <label>;
 195  *   return [expression];
 196  *
 197  *  gcc: https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#Statement-Attributes
 198  */
 199 #if __has_attribute(__fallthrough__)
 200 # define fallthrough                    __attribute__((__fallthrough__))
 201 #else
 202 # define fallthrough                    do {} while (0)  /* fallthrough */
 203 #endif
 204
 205 /*
 206  * gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes
 207  * clang: https://clang.llvm.org/docs/AttributeReference.html#flatten
 208  */
 209 # define __flatten                      __attribute__((flatten))
 210
 211 /*
 212  * Note the missing underscores.
 213  *
 214  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute
 215  * clang: mentioned
 216  */
 217 #define   noinline                      __attribute__((__noinline__))
 218
 219 /*
 220  * Optional: only supported since gcc >= 8
 221  * Optional: not supported by clang
 222  * Optional: not supported by icc
 223  *
 224  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-nonstring-variable-attribute
 225  */
 226 #if __has_attribute(__nonstring__)
 227 # define __nonstring                    __attribute__((__nonstring__))
 228 #else
 229 # define __nonstring
 230 #endif
 231
 232 /*
 233  * Optional: only supported since GCC >= 7.1, clang >= 13.0.
 234  *
 235  *      gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005fprofile_005finstrument_005ffunction-function-attribute
 236  *    clang: https://clang.llvm.org/docs/AttributeReference.html#no-profile-instrument-function
 237  */
 238 #if __has_attribute(__no_profile_instrument_function__)
 239 # define __no_profile                  __attribute__((__no_profile_instrument_function__))
 240 #else
 241 # define __no_profile
 242 #endif
 243
 244 /*
 245  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute
 246  * clang: https://clang.llvm.org/docs/AttributeReference.html#noreturn
 247  * clang: https://clang.llvm.org/docs/AttributeReference.html#id1
 248  */
 249 #define __noreturn                      __attribute__((__noreturn__))
 250
 251 /*
 252  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-packed-type-attribute
 253  * clang: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-packed-variable-attribute
 254  */
 255 #define __packed                        __attribute__((__packed__))
 256
 257 /*
 258  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute
 259  */
 260 #define __pure                          __attribute__((__pure__))
 261
 262 /*
 263  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-section-function-attribute
 264  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-section-variable-attribute
 265  * clang: https://clang.llvm.org/docs/AttributeReference.html#section-declspec-allocate
 266  */
 267 #define __section(section)              __attribute__((__section__(section)))
 268
 269 /*
 270  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute
 271  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-unused-type-attribute
 272  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-unused-variable-attribute
 273  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Label-Attributes.html#index-unused-label-attribute
 274  * clang: https://clang.llvm.org/docs/AttributeReference.html#maybe-unused-unused
 275  */
 276 #define __always_unused                 __attribute__((__unused__))
 277 #define __maybe_unused                  __attribute__((__unused__))
 278
 279 /*
 280  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-used-function-attribute
 281  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-used-variable-attribute
 282  */
 283 #define __used                          __attribute__((__used__))
 284
 285 /*
 286  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute
 287  * clang: https://clang.llvm.org/docs/AttributeReference.html#nodiscard-warn-unused-result
 288  */
 289 #define __must_check                    __attribute__((__warn_unused_result__))
 290
 291 /*
 292  * Optional: only supported since clang >= 14.0
 293  *
 294  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warning-function-attribute
 295  */
 296 #if __has_attribute(__warning__)
 297 # define __compiletime_warning(msg)     __attribute__((__warning__(msg)))
 298 #else
 299 # define __compiletime_warning(msg)
 300 #endif
 301
 302 /*
 303  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-weak-function-attribute
 304  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-weak-variable-attribute
 305  */
 306 #define __weak                          __attribute__((__weak__))
 307
 308 #endif /* __LINUX_COMPILER_ATTRIBUTES_H */