Compiler Attributes: improve explanation of header
[sfrench/cifs-2.6.git] / 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  * __has_attribute is supported on gcc >= 5, clang >= 2.9 and icc >= 17.
25  * In the meantime, to support 4.6 <= gcc < 5, we implement __has_attribute
26  * by hand.
27  *
28  * sparse does not support __has_attribute (yet) and defines __GNUC_MINOR__
29  * depending on the compiler used to build it; however, these attributes have
30  * no semantic effects for sparse, so it does not matter. Also note that,
31  * in order to avoid sparse's warnings, even the unsupported ones must be
32  * defined to 0.
33  */
34 #ifndef __has_attribute
35 # define __has_attribute(x) __GCC4_has_attribute_##x
36 # define __GCC4_has_attribute___assume_aligned__      (__GNUC_MINOR__ >= 9)
37 # define __GCC4_has_attribute___designated_init__     0
38 # define __GCC4_has_attribute___externally_visible__  1
39 # define __GCC4_has_attribute___noclone__             1
40 # define __GCC4_has_attribute___optimize__            1
41 # define __GCC4_has_attribute___nonstring__           0
42 # define __GCC4_has_attribute___no_sanitize_address__ (__GNUC_MINOR__ >= 8)
43 #endif
44
45 /*
46  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alias-function-attribute
47  */
48 #define __alias(symbol)                 __attribute__((__alias__(#symbol)))
49
50 /*
51  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-aligned-function-attribute
52  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-aligned-type-attribute
53  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-aligned-variable-attribute
54  */
55 #define __aligned(x)                    __attribute__((__aligned__(x)))
56 #define __aligned_largest               __attribute__((__aligned__))
57
58 /*
59  * Note: users of __always_inline currently do not write "inline" themselves,
60  * which seems to be required by gcc to apply the attribute according
61  * to its docs (and also "warning: always_inline function might not be
62  * inlinable [-Wattributes]" is emitted).
63  *
64  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-always_005finline-function-attribute
65  * clang: mentioned
66  */
67 #define __always_inline                 inline __attribute__((__always_inline__))
68
69 /*
70  * The second argument is optional (default 0), so we use a variadic macro
71  * to make the shorthand.
72  *
73  * Beware: Do not apply this to functions which may return
74  * ERR_PTRs. Also, it is probably unwise to apply it to functions
75  * returning extra information in the low bits (but in that case the
76  * compiler should see some alignment anyway, when the return value is
77  * massaged by 'flags = ptr & 3; ptr &= ~3;').
78  *
79  * Optional: only supported since gcc >= 4.9
80  * Optional: not supported by icc
81  *
82  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-assume_005faligned-function-attribute
83  * clang: https://clang.llvm.org/docs/AttributeReference.html#assume-aligned
84  */
85 #if __has_attribute(__assume_aligned__)
86 # define __assume_aligned(a, ...)       __attribute__((__assume_aligned__(a, ## __VA_ARGS__)))
87 #else
88 # define __assume_aligned(a, ...)
89 #endif
90
91 /*
92  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-cold-function-attribute
93  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Label-Attributes.html#index-cold-label-attribute
94  */
95 #define __cold                          __attribute__((__cold__))
96
97 /*
98  * Note the long name.
99  *
100  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute
101  */
102 #define __attribute_const__             __attribute__((__const__))
103
104 /*
105  * Don't. Just don't. See commit 771c035372a0 ("deprecate the '__deprecated'
106  * attribute warnings entirely and for good") for more information.
107  *
108  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute
109  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-deprecated-type-attribute
110  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-deprecated-variable-attribute
111  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Enumerator-Attributes.html#index-deprecated-enumerator-attribute
112  * clang: https://clang.llvm.org/docs/AttributeReference.html#deprecated
113  */
114 #define __deprecated
115
116 /*
117  * Optional: only supported since gcc >= 5.1
118  * Optional: not supported by clang
119  * Optional: not supported by icc
120  *
121  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-designated_005finit-type-attribute
122  */
123 #if __has_attribute(__designated_init__)
124 # define __designated_init              __attribute__((__designated_init__))
125 #else
126 # define __designated_init
127 #endif
128
129 /*
130  * Optional: not supported by clang
131  *
132  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-externally_005fvisible-function-attribute
133  */
134 #if __has_attribute(__externally_visible__)
135 # define __visible                      __attribute__((__externally_visible__))
136 #else
137 # define __visible
138 #endif
139
140 /*
141  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-format-function-attribute
142  * clang: https://clang.llvm.org/docs/AttributeReference.html#format
143  */
144 #define __printf(a, b)                  __attribute__((__format__(printf, a, b)))
145 #define __scanf(a, b)                   __attribute__((__format__(scanf, a, b)))
146
147 /*
148  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-gnu_005finline-function-attribute
149  * clang: https://clang.llvm.org/docs/AttributeReference.html#gnu-inline
150  */
151 #define __gnu_inline                    __attribute__((__gnu_inline__))
152
153 /*
154  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute
155  */
156 #define __malloc                        __attribute__((__malloc__))
157
158 /*
159  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-mode-type-attribute
160  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-mode-variable-attribute
161  */
162 #define __mode(x)                       __attribute__((__mode__(x)))
163
164 /*
165  * Optional: not supported by clang
166  * Note: icc does not recognize gcc's no-tracer
167  *
168  *  gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noclone-function-attribute
169  *  gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-optimize-function-attribute
170  */
171 #if __has_attribute(__noclone__)
172 # if __has_attribute(__optimize__)
173 #  define __noclone                     __attribute__((__noclone__, __optimize__("no-tracer")))
174 # else
175 #  define __noclone                     __attribute__((__noclone__))
176 # endif
177 #else
178 # define __noclone
179 #endif
180
181 /*
182  * Note the missing underscores.
183  *
184  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute
185  * clang: mentioned
186  */
187 #define   noinline                      __attribute__((__noinline__))
188
189 /*
190  * Optional: only supported since gcc >= 8
191  * Optional: not supported by clang
192  * Optional: not supported by icc
193  *
194  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-nonstring-variable-attribute
195  */
196 #if __has_attribute(__nonstring__)
197 # define __nonstring                    __attribute__((__nonstring__))
198 #else
199 # define __nonstring
200 #endif
201
202 /*
203  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute
204  * clang: https://clang.llvm.org/docs/AttributeReference.html#noreturn
205  * clang: https://clang.llvm.org/docs/AttributeReference.html#id1
206  */
207 #define __noreturn                      __attribute__((__noreturn__))
208
209 /*
210  * Optional: only supported since gcc >= 4.8
211  * Optional: not supported by icc
212  *
213  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005fsanitize_005faddress-function-attribute
214  * clang: https://clang.llvm.org/docs/AttributeReference.html#no-sanitize-address-no-address-safety-analysis
215  */
216 #if __has_attribute(__no_sanitize_address__)
217 # define __no_sanitize_address          __attribute__((__no_sanitize_address__))
218 #else
219 # define __no_sanitize_address
220 #endif
221
222 /*
223  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-packed-type-attribute
224  * clang: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-packed-variable-attribute
225  */
226 #define __packed                        __attribute__((__packed__))
227
228 /*
229  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute
230  */
231 #define __pure                          __attribute__((__pure__))
232
233 /*
234  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-section-function-attribute
235  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-section-variable-attribute
236  * clang: https://clang.llvm.org/docs/AttributeReference.html#section-declspec-allocate
237  */
238 #define __section(S)                    __attribute__((__section__(#S)))
239
240 /*
241  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute
242  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-unused-type-attribute
243  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-unused-variable-attribute
244  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Label-Attributes.html#index-unused-label-attribute
245  * clang: https://clang.llvm.org/docs/AttributeReference.html#maybe-unused-unused
246  */
247 #define __always_unused                 __attribute__((__unused__))
248 #define __maybe_unused                  __attribute__((__unused__))
249
250 /*
251  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-used-function-attribute
252  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-used-variable-attribute
253  */
254 #define __used                          __attribute__((__used__))
255
256 /*
257  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-weak-function-attribute
258  *   gcc: https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html#index-weak-variable-attribute
259  */
260 #define __weak                          __attribute__((__weak__))
261
262 #endif /* __LINUX_COMPILER_ATTRIBUTES_H */